diff --git a/docz/docs/03-demos/02-frontend/01-kaioken.md b/docz/docs/03-demos/02-frontend/01-kiru.md similarity index 79% rename from docz/docs/03-demos/02-frontend/01-kaioken.md rename to docz/docs/03-demos/02-frontend/01-kiru.md index 15ad90a..a88cf16 100644 --- a/docz/docs/03-demos/02-frontend/01-kaioken.md +++ b/docz/docs/03-demos/02-frontend/01-kiru.md @@ -1,7 +1,7 @@ --- -title: Super Saiyan Sheets with Kaioken -sidebar_label: Kaioken -description: Build interactive websites with Kaioken. Seamlessly integrate spreadsheets into your app using SheetJS. Bring Excel-powered workflows and data to the modern web. +title: Sheets in Kiru Sites +sidebar_label: Kiru +description: Build interactive websites with Kiru. Seamlessly integrate spreadsheets into your app using SheetJS. Bring Excel-powered workflows and data to the modern web. pagination_prev: demos/index pagination_next: demos/grid/index sidebar_position: 1 @@ -12,28 +12,28 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; -[Kaioken](https://kaioken.dev/) is a JavaScript library for building user +[Kiru](https://kirujs.dev/) is a JavaScript library for building user interfaces. [SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing data from spreadsheets. -This demo uses Kaioken and SheetJS to process and generate spreadsheets. We'll -explore how to load SheetJS in "Kaioponents" (Kaioken components) and compare +This demo uses Kiru and SheetJS to process and generate spreadsheets. We'll +explore how to load SheetJS in Kiru components and compare common state models and data flow strategies. :::note pass -This demo focuses on Kaioken concepts. Other demos cover general deployments: +This demo focuses on Kiru concepts. Other demos cover general deployments: - [Desktop application powered by Tauri](/docs/demos/desktop/tauri) ::: -:::caution Kaioken support is considered experimental. +:::caution Kiru support is considered experimental. Great open source software grows with user tests and reports. Any issues should -be reported to the Kaioken project for further diagnosis. +be reported to the Kiru project for further diagnosis. ::: @@ -85,15 +85,15 @@ object for each row, using the values in the first rows as keys: -The Kaioken `useState`[^1] hook can configure the state: +The Kiru `useState`[^1] hook can configure the state: ```ts -import { useState } from 'kaioken'; +import { useState } from 'kiru'; -/* the kaioponent state is an array of objects */ +/* the state is an array of objects */ const [pres, setPres] = useState([]); ``` @@ -101,23 +101,23 @@ const [pres, setPres] = useState([]); ```ts -import { useState } from 'kaioken'; +import { useState } from 'kiru'; -/* the kaioponent state is an array of objects */ +/* the state is an array of objects */ const [pres, setPres] = useState([]); ``` When the spreadsheet header row is known ahead of time, row typing is possible: ```ts -import { useState } from 'kaioken'; +import { useState } from 'kiru'; interface President { Name: string; Index: number; } -/* the kaioponent state is an array of presidents */ +/* the state is an array of presidents */ const [pres, setPres] = useState([]); ``` @@ -148,7 +148,7 @@ flowchart LR wb(SheetJS\nWorkbook) ws(SheetJS\nWorksheet) aoo(array of\nobjects) - state((Kaioponent\nstate)) + state((Kiru\nstate)) url --> |fetch\n\n| ab ab --> |read\n\n| wb wb --> |wb.Sheets\nselect sheet| ws @@ -160,7 +160,7 @@ flowchart LR ```js -import { useEffect } from 'kaioken'; +import { useEffect } from 'kiru'; import { read, utils } from 'xlsx'; /* Fetch and update the state once */ @@ -187,7 +187,7 @@ useEffect(() => { (async() => { ```ts -import { useEffect } from 'kaioken'; +import { useEffect } from 'kiru'; import { read, utils } from 'xlsx'; /* Fetch and update the state once */ @@ -219,12 +219,12 @@ For this particular use case (fetching a file once when the page loads), it is strongly recommended to use the `useAsync` hook: ```ts -import { useAsync } from 'kaioken'; +import { useAsync } from 'kiru'; import { read, utils } from 'xlsx'; /* Fetch and parse the file */ // highlight-next-line -const [ pres, loading, error ] = useAsync(async() => { +const { data: pres, loading, error } = useAsync(async() => { /* Download from https://docs.sheetjs.com/pres.numbers */ const f = await fetch("https://docs.sheetjs.com/pres.numbers"); const ab = await f.arrayBuffer(); @@ -250,7 +250,7 @@ SheetJS users reported that it is easier to reason about data fetching using the #### Rendering Data -Kaioponents typically render HTML tables from arrays of objects. The `TR` table +Kiru components typically render HTML tables from arrays of objects. The `TR` table row elements are typically generated by mapping over the state array, as shown in the example JSX code: @@ -284,7 +284,7 @@ A callback can generate a local file when a user clicks a button: ```mermaid flowchart LR - state((Kaioponent\nstate)) + state((Kiru\nstate)) ws(SheetJS\nWorksheet) wb(SheetJS\nWorkbook) file[(XLSX\nexport)] @@ -294,7 +294,7 @@ flowchart LR ``` ```ts -import { useCallback } from 'kaioken'; +import { useCallback } from 'kiru'; import { utils, writeFile } from 'xlsx'; /* get state data and export to XLSX */ @@ -306,13 +306,13 @@ const exportFile = useCallback(() => { const wb = utils.book_new(); utils.book_append_sheet(wb, ws, "Data"); /* export to XLSX */ - writeFile(wb, "SheetJSKaiokenAoO.xlsx"); + writeFile(wb, "SheetJSKiruAoO.xlsx"); }, [pres]); ``` -#### Complete Kaioponent +#### Complete Kiru Component -This complete Kaioponent example fetches a test file and displays the data in a +This complete Kiru component example fetches a test file and displays the data in a HTML table. When the export button is clicked, a callback will export a file. Examples using `useAsync` and `useEffect` with `useState` are shown below: @@ -320,8 +320,8 @@ Examples using `useAsync` and `useEffect` with `useState` are shown below: -```tsx title="src/SheetJSKaiokenAoO.tsx" -import { useAsync, useCallback } from "kaioken"; +```tsx title="src/SheetJSKiruAoO.tsx" +import { useAsync, useCallback } from "kiru"; import { read, utils, writeFileXLSX } from 'xlsx'; interface President { @@ -329,9 +329,9 @@ interface President { Index: number; } -export default function SheetJSKaiokenAoO() { +export default function SheetJSKiruAoO() { /* Fetch and parse the file */ - const [ pres, loading, error ] = useAsync(async() => { + const { data: pres, loading, error } = useAsync(async() => { const f = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).arrayBuffer(); const wb = read(f); // parse the array buffer const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet @@ -344,7 +344,7 @@ export default function SheetJSKaiokenAoO() { const ws = utils.json_to_sheet(pres!); const wb = utils.book_new(); utils.book_append_sheet(wb, ws, "Data"); - writeFileXLSX(wb, "SheetJSKaiokenAoO.xlsx"); + writeFileXLSX(wb, "SheetJSKiruAoO.xlsx"); }, [pres]); return ( @@ -371,10 +371,10 @@ export default function SheetJSKaiokenAoO() { Typically the JSX structure uses ternary expressions for testing status: ```jsx -const [ pres, loading, error ] = useAsync(async() => { /* ... */ }); +const { data, loading, error } = useAsync(async() => { /* ... */ }); return ( <> - { pres ? ( + { data ? ( Data is loaded ) : loading ? ( Loading ... @@ -392,8 +392,8 @@ For clarity, the loading and error messages are separated. -```tsx title="src/SheetJSKaiokenAoO.tsx" -import { useCallback, useEffect, useState } from "kaioken"; +```tsx title="src/SheetJSKiruAoO.tsx" +import { useCallback, useEffect, useState } from "kiru"; import { read, utils, writeFileXLSX } from 'xlsx'; interface President { @@ -401,8 +401,8 @@ interface President { Index: number; } -export default function SheetJSKaiokenAoO() { - /* the kaioponent state is an array of presidents */ +export default function SheetJSKiruAoO() { + /* the state is an array of presidents */ const [pres, setPres] = useState([]); /* Fetch and update the state once */ @@ -419,7 +419,7 @@ export default function SheetJSKaiokenAoO() { const ws = utils.json_to_sheet(pres); const wb = utils.book_new(); utils.book_append_sheet(wb, ws, "Data"); - writeFileXLSX(wb, "SheetJSKaiokenAoO.xlsx"); + writeFileXLSX(wb, "SheetJSKiruAoO.xlsx"); }, [pres]); return (
NameIndex
@@ -448,29 +448,29 @@ export default function SheetJSKaiokenAoO() { This demo was tested in the following environments: -| Kaioken | ViteJS | Date | +| Kiru | ViteJS | Date | |:---------|:---------|:-----------| -| `0.17.0` | `5.2.11` | 2024-05-21 | +| `0.44.2` | `5.2.11` | 2024-05-21 | ::: 1) Create a new site. ```bash -npm create vite@latest sheetjs-kaioken -- --template vanilla-ts -cd sheetjs-kaioken -npm add --save kaioken -npm add --save vite-plugin-kaioken -D +npm create vite@latest sheetjs-kiru -- --template vanilla-ts +cd sheetjs-kiru +npm add --save kiru +npm add --save vite-plugin-kiru -D ``` 2) Create a new file `vite.config.ts` with the following content: ```ts title="vite.config.ts (create new file)" import { defineConfig } from "vite" -import kaioken from "vite-plugin-kaioken" +import kiru from "vite-plugin-kiru" export default defineConfig({ - plugins: [kaioken()], + plugins: [kiru()], }) ``` @@ -486,14 +486,14 @@ export default defineConfig({ 4) Replace `src/main.ts` with the following codeblock: ```ts title="src/main.ts (replace contents)" -import { mount } from "kaioken"; -import App from "./SheetJSKaiokenAoO"; +import { mount } from "kiru"; +import App from "./SheetJSKiruAoO"; const root = document.getElementById("app"); mount(App, root!); ``` -5) Create a new file `src/SheetJSKaiokenAoO.tsx` using the original code example. +5) Create a new file `src/SheetJSKiruAoO.tsx` using the original code example. 6) Install the SheetJS dependency and start the dev server: @@ -505,7 +505,7 @@ npm run dev`} 7) Open a web browser and access the displayed URL (`http://localhost:5173`) The page will refresh and show a table with an Export button. Click the button -and the page will attempt to download `SheetJSKaiokenAoO.xlsx`. +and the page will attempt to download `SheetJSKiruAoO.xlsx`. 8) Build the site: @@ -544,15 +544,15 @@ generates HTML that is aware of merges and other worksheet features. To add the table to the page, the current recommendation involves setting the `innerHTML` attribute of a `ref`. -In this example, the kaioponent attaches a `ref` to the `DIV` container. During +In this example, we attach a `ref` to the `DIV` container. During export, the first `TABLE` child element can be parsed with [`table_to_book`](/docs/api/utilities/html#html-table-input) to generate a workbook object. -```tsx title="src/SheetJSKaiokenHTML.tsx" -import { useCallback, useEffect, useRef } from "kaioken"; +```tsx title="src/SheetJSKiruHTML.tsx" +import { useCallback, useEffect, useRef } from "kiru"; import { read, utils, writeFileXLSX } from 'xlsx'; -export default function SheetJSKaiokenHTML() { +export default function SheetJSKiruHTML() { /* the ref is used in export */ const tbl = useRef(null); @@ -574,7 +574,7 @@ export default function SheetJSKaiokenHTML() { const elt = tbl.current!.getElementsByTagName("TABLE")[0]; const wb = utils.table_to_book(elt); // highlight-end - writeFileXLSX(wb, "SheetJSKaiokenHTML.xlsx"); + writeFileXLSX(wb, "SheetJSKiruHTML.xlsx"); }, [tbl]); return ( <> @@ -595,29 +595,29 @@ export default function SheetJSKaiokenHTML() { This demo was tested in the following environments: -| Kaioken | ViteJS | Date | +| Kiru | ViteJS | Date | |:---------|:---------|:-----------| -| `0.17.0` | `5.2.11` | 2024-05-21 | +| `0.44.2` | `5.2.11` | 2024-05-21 | ::: 1) Create a new site. ```bash -npm create vite@latest sheetjs-kaioken -- --template vanilla-ts -cd sheetjs-kaioken -npm add --save kaioken -npm add --save vite-plugin-kaioken -D +npm create vite@latest sheetjs-kiru -- --template vanilla-ts +cd sheetjs-kiru +npm add --save kiru +npm add --save vite-plugin-kiru -D ``` 2) Create a new file `vite.config.ts` with the following content: ```ts title="vite.config.ts (create new file)" import { defineConfig } from "vite" -import kaioken from "vite-plugin-kaioken" +import kiru from "vite-plugin-kiru" export default defineConfig({ - plugins: [kaioken()], + plugins: [kiru()], }) ``` @@ -633,14 +633,14 @@ export default defineConfig({ 4) Replace `src/main.ts` with the following codeblock: ```ts title="src/main.ts (replace contents)" -import { mount } from "kaioken"; -import App from "./SheetJSKaiokenHTML"; +import { mount } from "kiru"; +import App from "./SheetJSKiruHTML"; const root = document.getElementById("app"); mount(App, root!); ``` -5) Create a new file `src/SheetJSKaiokenHTML.tsx` using the original code example. +5) Create a new file `src/SheetJSKiruHTML.tsx` using the original code example. 6) Install the SheetJS dependency and start the dev server: @@ -652,7 +652,7 @@ npm run dev`} 7) Open a web browser and access the displayed URL (`http://localhost:5173`) The page will refresh and show a table with an Export button. Click the button -and the page will attempt to download `SheetJSKaiokenHTML.xlsx`. +and the page will attempt to download `SheetJSKiruHTML.xlsx`. 8) Build the site: @@ -680,9 +680,9 @@ will generate a workbook that can be opened in a spreadsheet editor. -[^1]: See [`useState`](https://kaioken.dev/docs/hooks/useState) in the Kaioken documentation. -[^2]: See [`useAsync`](https://kaioken.dev/docs/hooks/useAsync) in the Kaioken documentation. -[^3]: See [`useEffect`](https://kaioken.dev/docs/hooks/useEffect) in the Kaioken documentation. -[^4]: See [`useCallback`](https://kaioken.dev/docs/hooks/useCallback) in the Kaioken documentation. -[^5]: See [`useCallback`](https://kaioken.dev/docs/hooks/useCallback) in the Kaioken documentation. +[^1]: See [`useState`](https://kirujs.dev/docs/hooks/useState) in the Kiru documentation. +[^2]: See [`useAsync`](https://kirujs.dev/docs/hooks/useAsync) in the Kiru documentation. +[^3]: See [`useEffect`](https://kirujs.dev/docs/hooks/useEffect) in the Kiru documentation. +[^4]: See [`useCallback`](https://kirujs.dev/docs/hooks/useCallback) in the Kiru documentation. +[^5]: See [`useCallback`](https://kirujs.dev/docs/hooks/useCallback) in the Kiru documentation. [^6]: See ["Merged Cells" in "SheetJS Data Model"](/docs/csf/features/merges) for more details.
NameIndex