@gasboost/react 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gasboost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @gasboost/react
+
+Google Apps Script Web アプリケーション向けの React integration です。
+
+`@gasboost/client` が提供する navigation と Job Store を React から利用するためのコンポーネントと Hook を提供します。
+
+現在、以下の API を公開しています。
+
+- `AppsScriptRouter`
+- `useAppsScriptJob`
+
+## インストール
+
+```bash
+pnpm add @gasboost/react @gasboost/client react
+```
+
+npm:
+
+```bash
+npm install @gasboost/react @gasboost/client react
+```
+
+現在 React 19 を対象としています。
+
+## AppsScriptRouter
+
+`AppsScriptRouter` は、Google Apps Script Web アプリケーションの Container History と iframe 側の History を同期します。
+
+```tsx
+import { AppsScriptRouter } from "@gasboost/react";
+
+export function App() {
+  return (
+    <AppsScriptRouter>
+      <main>Application</main>
+    </AppsScriptRouter>
+  );
+}
+```
+
+内部では `@gasboost/client` の `AppsScriptHistoryPipeline` を利用します。
+
+```text
+google.script.history / google.script.url
+                ↕
+     AppsScriptHistoryPipeline
+                ↕
+          iframe History
+                ↕
+              React
+```
+
+## 初期化
+
+`AppsScriptRouter` は History Pipeline の生成と同期が完了するまで children を描画しません。
+
+```tsx
+<AppsScriptRouter>
+  <App />
+</AppsScriptRouter>
+```
+
+概念的には次の順序で初期化されます。
+
+```text
+AppsScriptRouter mount
+        ↓
+AppsScriptHistoryPipeline.create()
+        ↓
+pipeline.sync()
+        ↓
+History synchronization ready
+        ↓
+children render
+```
+
+これにより、GAS Container と iframe の navigation state を同期してからアプリケーションを描画します。
+
+## Cleanup
+
+`AppsScriptRouter` が unmount されると、History Pipeline が返した監視解除関数を実行します。
+
+そのため、Router の破棄後に navigation の監視が残り続けることはありません。
+
+## useAppsScriptJob
+
+`useAppsScriptJob` は `AppsScriptJobStore` を React から購読する Hook です。
+
+内部では React の `useSyncExternalStore` を利用します。
+
+```tsx
+import { useAppsScriptJob } from "@gasboost/react";
+```
+
+例えば `@gasboost/client` の Job Store を渡すと、Job 一覧の変更に合わせて React component を再描画できます。
+
+```tsx
+const snapshot = useAppsScriptJob(jobStore);
+```
+
+`useAppsScriptJob` は次の interface を持つ Store を受け取ります。
+
+```ts
+interface AppsScriptJobStore {
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): AppsScriptJob[];
+}
+```
+
+Store が変更通知を行うと、最新の snapshot が React に反映されます。
+
+## Store の切り替え
+
+`useAppsScriptJob` に渡す Store が変更された場合、以前の Store の購読を解除し、新しい Store を購読します。
+
+component が unmount された場合も購読解除関数が呼び出されます。
+
+## Job UI
+
+`@gasboost/react` は Job の表示 UI 自体は提供しません。
+
+`useAppsScriptJob` が返す snapshot を利用して、アプリケーション側で自由に UI を構築できます。
+
+例えば:
+
+```tsx
+const jobs = useAppsScriptJob(jobStore);
+
+return (
+  <ul>
+    {jobs.map((job) => (
+      <li key={job.id}>
+        {job.label}: {job.status}
+      </li>
+    ))}
+  </ul>
+);
+```
+
+Job の状態管理、cancel、retry などの実体は `@gasboost/client` が担当します。
+
+## 責務
+
+`@gasboost/react` が担当するもの:
+
+- `AppsScriptHistoryPipeline` の React lifecycle への統合
+- History 同期完了後の描画制御
+- unmount 時の History 監視解除
+- `AppsScriptJobStore` と React の同期
+- Store の購読と解除
+
+以下は担当しません。
+
+- RPC transport
+- Job Queue / Runner
+- RPC 型推論
+- Google Apps Script backend
+- GAS build
+
+これらはそれぞれ `@gasboost/client`、`@gasboost/app`、`@gasboost/vite` が担当します。
+
+## 関連パッケージ
+
+- `@gasboost/client` — RPC、Job、History
+- `@gasboost/app` — backend runtime と RPC 契約
+- `@gasboost/vite` — GAS build と Local RPC
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasboost/react",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "React integration for Google Apps Script web applications.",
   "repository": {
     "type": "git",
@@ -17,6 +17,10 @@
     "web-app",
     "gasboost"
   ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -26,7 +30,7 @@
     }
   },
   "dependencies": {
-    "@gasboost/client": "0.1.0"
+    "@gasboost/client": "0.1.1"
   },
   "peerDependencies": {
     "react": "^19"

package/src/AppsScriptRouter.tsx

@@ -1,26 +0,0 @@
-import { AppsScriptHistoryPipeline } from "@gasboost/client";
-import type { PropsWithChildren } from "react";
-import { useEffect, useState } from "react";
-
-export function AppsScriptRouter({ children }: PropsWithChildren) {
-  const [ready, setReady] = useState(false);
-
-  useEffect(() => {
-    let dispose: (() => void) | undefined;
-
-    AppsScriptHistoryPipeline.create((pipeline) => {
-      dispose = pipeline.sync();
-      setReady(true);
-    });
-
-    return () => {
-      dispose?.();
-    };
-  }, []);
-
-  if (!ready) {
-    return null;
-  }
-
-  return children;
-}

package/src/index.ts

@@ -1,2 +0,0 @@
-export { AppsScriptRouter } from "./AppsScriptRouter";
-export { useAppsScriptJob } from "./useAppsScriptJob";

package/src/useAppsScriptJob.tsx

@@ -1,9 +0,0 @@
-import { AppsScriptJobStore } from "@gasboost/client";
-import { useSyncExternalStore } from "react";
-
-export function useAppsScriptJob(jobStore: AppsScriptJobStore) {
-  return useSyncExternalStore(
-    jobStore.subscribe.bind(jobStore),
-    jobStore.getSnapshot.bind(jobStore),
-  );
-}

package/tests/AppsScriptRouter.spec.js

@@ -1,60 +0,0 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { cleanup, render, screen, waitFor } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { AppsScriptHistoryPipeline } from "@gasboost/client";
-import { AppsScriptRouter } from "../src/AppsScriptRouter";
-vi.mock("@gasboost/client", () => ({
-    AppsScriptHistoryPipeline: {
-        create: vi.fn(),
-    },
-}));
-describe("AppsScriptRouter", () => {
-    beforeEach(() => {
-        vi.resetAllMocks();
-        cleanup();
-    });
-    it("pipeline の生成が完了するまでは children を描画しない", () => {
-        vi.mocked(AppsScriptHistoryPipeline.create).mockImplementation(() => { });
-        render(_jsx(AppsScriptRouter, { children: _jsx("div", { children: "app" }) }));
-        expect(screen.queryByText("app")).toBeNull();
-    });
-    it("pipeline 生成後に同期を開始する", async () => {
-        const sync = vi.fn(() => vi.fn());
-        const pipeline = {
-            sync,
-        };
-        vi.mocked(AppsScriptHistoryPipeline.create).mockImplementation((callback) => {
-            callback(pipeline);
-        });
-        render(_jsx(AppsScriptRouter, { children: _jsx("div", { children: "app" }) }));
-        await waitFor(() => {
-            expect(sync).toHaveBeenCalledOnce();
-        });
-        expect(AppsScriptHistoryPipeline.create).toHaveBeenCalledOnce();
-    });
-    it("同期開始後に children を描画する", async () => {
-        const pipeline = {
-            sync: vi.fn(() => vi.fn()),
-        };
-        vi.mocked(AppsScriptHistoryPipeline.create).mockImplementation((callback) => {
-            callback(pipeline);
-        });
-        render(_jsx(AppsScriptRouter, { children: _jsx("div", { children: "app" }) }));
-        expect(await screen.findByText("app")).toBeTruthy();
-    });
-    it("アンマウント時に pipeline の監視を解除する", async () => {
-        const dispose = vi.fn();
-        const pipeline = {
-            sync: vi.fn(() => dispose),
-        };
-        vi.mocked(AppsScriptHistoryPipeline.create).mockImplementation((callback) => {
-            callback(pipeline);
-        });
-        const { unmount } = render(_jsx(AppsScriptRouter, { children: _jsx("div", { children: "app" }) }));
-        await waitFor(() => {
-            expect(pipeline.sync).toHaveBeenCalledOnce();
-        });
-        unmount();
-        expect(dispose).toHaveBeenCalledOnce();
-    });
-});

package/tests/AppsScriptRouter.spec.tsx

@@ -1,104 +0,0 @@
-import { cleanup, render, screen, waitFor } from "@testing-library/react";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-import { AppsScriptHistoryPipeline } from "@gasboost/client";
-import { AppsScriptRouter } from "../src/AppsScriptRouter";
-
-vi.mock("@gasboost/client", () => ({
-  AppsScriptHistoryPipeline: {
-    create: vi.fn(),
-  },
-}));
-
-describe("AppsScriptRouter", () => {
-  beforeEach(() => {
-    vi.resetAllMocks();
-    cleanup();
-  });
-
-  it("pipeline の生成が完了するまでは children を描画しない", () => {
-    vi.mocked(AppsScriptHistoryPipeline.create).mockImplementation(() => {});
-
-    render(
-      <AppsScriptRouter>
-        <div>app</div>
-      </AppsScriptRouter>,
-    );
-
-    expect(screen.queryByText("app")).toBeNull();
-  });
-
-  it("pipeline 生成後に同期を開始する", async () => {
-    const sync = vi.fn(() => vi.fn());
-
-    const pipeline = {
-      sync,
-    } as unknown as AppsScriptHistoryPipeline;
-
-    vi.mocked(AppsScriptHistoryPipeline.create).mockImplementation(
-      (callback) => {
-        callback(pipeline);
-      },
-    );
-
-    render(
-      <AppsScriptRouter>
-        <div>app</div>
-      </AppsScriptRouter>,
-    );
-
-    await waitFor(() => {
-      expect(sync).toHaveBeenCalledOnce();
-    });
-
-    expect(AppsScriptHistoryPipeline.create).toHaveBeenCalledOnce();
-  });
-
-  it("同期開始後に children を描画する", async () => {
-    const pipeline = {
-      sync: vi.fn(() => vi.fn()),
-    } as unknown as AppsScriptHistoryPipeline;
-
-    vi.mocked(AppsScriptHistoryPipeline.create).mockImplementation(
-      (callback) => {
-        callback(pipeline);
-      },
-    );
-
-    render(
-      <AppsScriptRouter>
-        <div>app</div>
-      </AppsScriptRouter>,
-    );
-
-    expect(await screen.findByText("app")).toBeTruthy();
-  });
-
-  it("アンマウント時に pipeline の監視を解除する", async () => {
-    const dispose = vi.fn();
-
-    const pipeline = {
-      sync: vi.fn(() => dispose),
-    } as unknown as AppsScriptHistoryPipeline;
-
-    vi.mocked(AppsScriptHistoryPipeline.create).mockImplementation(
-      (callback) => {
-        callback(pipeline);
-      },
-    );
-
-    const { unmount } = render(
-      <AppsScriptRouter>
-        <div>app</div>
-      </AppsScriptRouter>,
-    );
-
-    await waitFor(() => {
-      expect(pipeline.sync).toHaveBeenCalledOnce();
-    });
-
-    unmount();
-
-    expect(dispose).toHaveBeenCalledOnce();
-  });
-});

package/tests/useAppsScriptJob.spec.js

@@ -1,104 +0,0 @@
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
-import { useAppsScriptJob } from "../src/useAppsScriptJob";
-describe("useAppsScriptJob", () => {
-    it("jobStore の現在の snapshot を返す", () => {
-        const snapshot = {
-            status: "pending",
-        };
-        const jobStore = {
-            subscribe: vi.fn(() => vi.fn()),
-            getSnapshot: vi.fn(() => snapshot),
-        };
-        const { result } = renderHook(() => useAppsScriptJob(jobStore));
-        expect(result.current).toBe(snapshot);
-    });
-    it("jobStore の変更を subscribe する", async () => {
-        const snapshot = {
-            status: "pending",
-        };
-        const subscribe = vi.fn(() => vi.fn());
-        const jobStore = {
-            subscribe,
-            getSnapshot: vi.fn(() => snapshot),
-        };
-        renderHook(() => useAppsScriptJob(jobStore));
-        await waitFor(() => {
-            expect(subscribe).toHaveBeenCalledOnce();
-        });
-    });
-    it("jobStore の変更通知を受けると最新の snapshot を返す", async () => {
-        let listener;
-        let snapshot = {
-            status: "pending",
-        };
-        const jobStore = {
-            subscribe: vi.fn((handler) => {
-                listener = handler;
-                return vi.fn();
-            }),
-            getSnapshot: vi.fn(() => snapshot),
-        };
-        const { result } = renderHook(() => useAppsScriptJob(jobStore));
-        await waitFor(() => {
-            expect(listener).toBeDefined();
-        });
-        snapshot = {
-            status: "completed",
-        };
-        act(() => {
-            listener?.();
-        });
-        expect(result.current).toEqual({
-            status: "completed",
-        });
-    });
-    it("アンマウント時に subscribe の解除関数を呼ぶ", async () => {
-        const snapshot = {
-            status: "pending",
-        };
-        const unsubscribe = vi.fn();
-        const jobStore = {
-            subscribe: vi.fn(() => unsubscribe),
-            getSnapshot: vi.fn(() => snapshot),
-        };
-        const { unmount } = renderHook(() => useAppsScriptJob(jobStore));
-        await waitFor(() => {
-            expect(jobStore.subscribe).toHaveBeenCalledOnce();
-        });
-        unmount();
-        expect(unsubscribe).toHaveBeenCalledOnce();
-    });
-    it("jobStore が変更された場合は新しい store を subscribe する", async () => {
-        const firstSnapshot = {
-            status: "first",
-        };
-        const secondSnapshot = {
-            status: "second",
-        };
-        const firstUnsubscribe = vi.fn();
-        const firstStore = {
-            subscribe: vi.fn(() => firstUnsubscribe),
-            getSnapshot: vi.fn(() => firstSnapshot),
-        };
-        const secondStore = {
-            subscribe: vi.fn(() => vi.fn()),
-            getSnapshot: vi.fn(() => secondSnapshot),
-        };
-        const { rerender } = renderHook(({ store }) => useAppsScriptJob(store), {
-            initialProps: {
-                store: firstStore,
-            },
-        });
-        await waitFor(() => {
-            expect(firstStore.subscribe).toHaveBeenCalledOnce();
-        });
-        rerender({
-            store: secondStore,
-        });
-        await waitFor(() => {
-            expect(secondStore.subscribe).toHaveBeenCalledOnce();
-        });
-        expect(firstUnsubscribe).toHaveBeenCalledOnce();
-    });
-});

package/tests/useAppsScriptJob.spec.tsx

@@ -1,139 +0,0 @@
-import type { AppsScriptJobStore } from "@gasboost/client";
-import { act, renderHook, waitFor } from "@testing-library/react";
-import { describe, expect, it, vi } from "vitest";
-import { useAppsScriptJob } from "../src/useAppsScriptJob";
-
-describe("useAppsScriptJob", () => {
-  it("jobStore の現在の snapshot を返す", () => {
-    const snapshot = {
-      status: "pending",
-    };
-
-    const jobStore = {
-      subscribe: vi.fn(() => vi.fn()),
-      getSnapshot: vi.fn(() => snapshot),
-    } as unknown as AppsScriptJobStore;
-
-    const { result } = renderHook(() => useAppsScriptJob(jobStore));
-
-    expect(result.current).toBe(snapshot);
-  });
-
-  it("jobStore の変更を subscribe する", async () => {
-    const snapshot = {
-      status: "pending",
-    };
-
-    const subscribe = vi.fn(() => vi.fn());
-
-    const jobStore = {
-      subscribe,
-      getSnapshot: vi.fn(() => snapshot),
-    } as unknown as AppsScriptJobStore;
-
-    renderHook(() => useAppsScriptJob(jobStore));
-
-    await waitFor(() => {
-      expect(subscribe).toHaveBeenCalledOnce();
-    });
-  });
-
-  it("jobStore の変更通知を受けると最新の snapshot を返す", async () => {
-    let listener: (() => void) | undefined;
-
-    let snapshot = {
-      status: "pending",
-    };
-
-    const jobStore = {
-      subscribe: vi.fn((handler: () => void) => {
-        listener = handler;
-        return vi.fn();
-      }),
-      getSnapshot: vi.fn(() => snapshot),
-    } as unknown as AppsScriptJobStore;
-
-    const { result } = renderHook(() => useAppsScriptJob(jobStore));
-
-    await waitFor(() => {
-      expect(listener).toBeDefined();
-    });
-
-    snapshot = {
-      status: "completed",
-    };
-
-    act(() => {
-      listener?.();
-    });
-
-    expect(result.current).toEqual({
-      status: "completed",
-    });
-  });
-
-  it("アンマウント時に subscribe の解除関数を呼ぶ", async () => {
-    const snapshot = {
-      status: "pending",
-    };
-
-    const unsubscribe = vi.fn();
-
-    const jobStore = {
-      subscribe: vi.fn(() => unsubscribe),
-      getSnapshot: vi.fn(() => snapshot),
-    } as unknown as AppsScriptJobStore;
-
-    const { unmount } = renderHook(() => useAppsScriptJob(jobStore));
-
-    await waitFor(() => {
-      expect(jobStore.subscribe).toHaveBeenCalledOnce();
-    });
-
-    unmount();
-
-    expect(unsubscribe).toHaveBeenCalledOnce();
-  });
-
-  it("jobStore が変更された場合は新しい store を subscribe する", async () => {
-    const firstSnapshot = {
-      status: "first",
-    };
-
-    const secondSnapshot = {
-      status: "second",
-    };
-
-    const firstUnsubscribe = vi.fn();
-
-    const firstStore = {
-      subscribe: vi.fn(() => firstUnsubscribe),
-      getSnapshot: vi.fn(() => firstSnapshot),
-    } as unknown as AppsScriptJobStore;
-
-    const secondStore = {
-      subscribe: vi.fn(() => vi.fn()),
-      getSnapshot: vi.fn(() => secondSnapshot),
-    } as unknown as AppsScriptJobStore;
-
-    const { rerender } = renderHook(({ store }) => useAppsScriptJob(store), {
-      initialProps: {
-        store: firstStore,
-      },
-    });
-
-    await waitFor(() => {
-      expect(firstStore.subscribe).toHaveBeenCalledOnce();
-    });
-
-    rerender({
-      store: secondStore,
-    });
-
-    await waitFor(() => {
-      expect(secondStore.subscribe).toHaveBeenCalledOnce();
-    });
-
-    expect(firstUnsubscribe).toHaveBeenCalledOnce();
-  });
-});

package/tsconfig.build.json

@@ -1,13 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist",
-    "declaration": true,
-    "declarationMap": false,
-    "sourceMap": false,
-    "noEmit": false
-  },
-  "include": ["src"],
-  "exclude": ["tests", "dist"]
-}

package/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "jsx": "react-jsx"
-  },
-  "include": ["src", "tests"]
-}

package/vitest.config.mts

@@ -1,7 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    environment: "jsdom",
-  },
-});