sheetjs/docs.sheetjs.com
1
Fork 6
Code Issues 1 Pull Requests 5 Projects Releases Wiki Activity

chore/update-kaioken-docs #49

Open
LankyMoose wants to merge 3 commits from LankyMoose/docs.sheetjs.com:chore/update-kaioken-docs into master
pull from: LankyMoose/docs.sheetjs.com:chore/update-kaioken-docs
merge into: sheetjs:master
Conversation 0 Commits 3 Files Changed 1 +73 -73
1 changed files with 73 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
docz/docs/03-demos/02-frontend/01-kaioken.md → docz/docs/03-demos/02-frontend/01-kiru.md
View File

@ -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:
</td></tr></tbody></table>
The Kaioken `useState`[^1] hook can configure the state:
The Kiru `useState`[^1] hook can configure the state:
<Tabs groupId="lang">
<TabItem name="JS" value="JavaScript">
```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([]);
<TabItem name="TS" value="TypeScript" default>
```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<any[]>([]);
```
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<President[]>([]);
```
@ -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
<TabItem name="JS" value="JavaScript">
```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() => {
<TabItem name="TS" value="TypeScript" default>
```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<President[]>(async() => {
const { data: pres, loading, error } = useAsync<President[]>(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:
<Tabs groupId="hook">
<TabItem name="async" value="useAsync">
```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<President[]>(async() => {
const { data: pres, loading, error } = useAsync<President[]>(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 (<table><thead><tr><th>Name</th><th>Index</th></tr></thead><tbody>
@ -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 ? (
<b>Data is loaded</b>
) : loading ? (
<b>Loading ...</b>
@ -392,8 +392,8 @@ For clarity, the loading and error messages are separated.
</TabItem>
<TabItem name="effect" value="useEffect + useState">
```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<President[]>([]);
/* 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 (<table><thead><tr><th>Name</th><th>Index</th></tr></thead><tbody>
@ -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<Element>(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.
</details>
[^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.