@unlaxer/tramli-react 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @unlaxer/tramli-react
+
+tramli の React フック。`useFlow` が FlowEngine + FlowStore + FlowInstance のライフサイクルをコンポーネントに統合します。
+
+## インストール
+
+```bash
+npm install @unlaxer/tramli-react @unlaxer/tramli react
+```
+
+## 使い方
+
+```tsx
+import { useFlow } from '@unlaxer/tramli-react';
+
+function AuthPage() {
+  const { state, context, resume, error, isLoading, flowId } = useFlow(authFlowDefinition, {
+    initialData: new Map([['RequestOrigin', { returnTo: '/' }]]),
+  });
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorBanner error={error} />;
+  if (state === 'MFA_PENDING') return <MfaForm onSubmit={code => resume(new Map([['MfaCode', code]]))} />;
+  if (state === 'COMPLETE') return <Dashboard />;
+  return <LoginRedirect />;
+}
+```
+
+## API
+
+### `useFlow<S>(definition, options?)`
+
+| 引数 | 型 | 説明 |
+|---|---|---|
+| `definition` | `FlowDefinition<S>` | tramli フロー定義 |
+| `options.initialData` | `Map<string, unknown>` | 初期データ |
+| `options.sessionId` | `string` | セッション ID (省略時は自動生成) |
+
+### 戻り値 (`UseFlowResult<S>`)
+
+| フィールド | 型 | 説明 |
+|---|---|---|
+| `state` | `S \| null` | 現在のフロー状態 |
+| `context` | `FlowContext \| null` | フローコンテキスト |
+| `flowId` | `string \| null` | フローインスタンス ID |
+| `error` | `Error \| null` | 直近のエラー |
+| `isLoading` | `boolean` | startFlow/resume 実行中 |
+| `resume` | `(data?) => Promise<void>` | 外部データでフローを再開 |
+
+## 動作
+
+- `FlowEngine` + `InMemoryFlowStore` はマウント時に一度だけ生成 (`useRef`)
+- `startFlow` は `useEffect` で非同期実行
+- `resume` は `useCallback` で安定参照
+- 各操作後に `FlowInstance` から React state を同期
+- エラーは `error` フィールドに格納 (throw しない)
+- 操作中は `isLoading = true`
+
+## License
+
+MIT

package/dist/cjs/index.d.ts

@@ -0,0 +1,2 @@
+export { useFlow } from './use-flow.js';
+export type { UseFlowOptions, UseFlowResult } from './use-flow.js';

package/dist/cjs/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFlow = void 0;
+var use_flow_js_1 = require("./use-flow.js");
+Object.defineProperty(exports, "useFlow", { enumerable: true, get: function () { return use_flow_js_1.useFlow; } });

package/dist/cjs/use-flow.d.ts

@@ -0,0 +1,28 @@
+import { type FlowDefinition, type FlowContext } from '@unlaxer/tramli';
+export interface UseFlowOptions {
+    /** Initial data to seed the flow context. */
+    initialData?: Map<string, unknown>;
+    /** Session ID for the flow instance. Defaults to crypto.randomUUID(). */
+    sessionId?: string;
+}
+export interface UseFlowResult<S extends string> {
+    /** Current flow state, or null before the flow starts. */
+    state: S | null;
+    /** Flow context, or null before the flow starts. */
+    context: FlowContext | null;
+    /** Flow instance ID, or null before the flow starts. */
+    flowId: string | null;
+    /** Error from the last operation, or null. */
+    error: Error | null;
+    /** True while startFlow or resume is in progress. */
+    isLoading: boolean;
+    /** Resume the flow with optional external data. */
+    resume: (externalData?: Map<string, unknown>) => Promise<void>;
+}
+/**
+ * React hook that manages a tramli flow lifecycle.
+ *
+ * Creates a FlowEngine + InMemoryFlowStore once per mount,
+ * starts the flow in useEffect, and exposes state/context/resume.
+ */
+export declare function useFlow<S extends string>(definition: FlowDefinition<S>, options?: UseFlowOptions): UseFlowResult<S>;

package/dist/cjs/use-flow.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFlow = useFlow;
+const react_1 = require("react");
+const tramli_1 = require("@unlaxer/tramli");
+/**
+ * React hook that manages a tramli flow lifecycle.
+ *
+ * Creates a FlowEngine + InMemoryFlowStore once per mount,
+ * starts the flow in useEffect, and exposes state/context/resume.
+ */
+function useFlow(definition, options) {
+    const [state, setState] = (0, react_1.useState)(null);
+    const [context, setContext] = (0, react_1.useState)(null);
+    const [flowId, setFlowId] = (0, react_1.useState)(null);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [isLoading, setIsLoading] = (0, react_1.useState)(true);
+    // Singleton store + engine per mount
+    const storeRef = (0, react_1.useRef)(null);
+    const engineRef = (0, react_1.useRef)(null);
+    const flowIdRef = (0, react_1.useRef)(null);
+    if (storeRef.current === null) {
+        storeRef.current = new tramli_1.InMemoryFlowStore();
+        engineRef.current = tramli_1.Tramli.engine(storeRef.current);
+    }
+    // Sync React state from a flow instance
+    const syncFromInstance = (0, react_1.useCallback)((instance) => {
+        setState(instance.currentState);
+        setContext(instance.context);
+        setFlowId(instance.id);
+        flowIdRef.current = instance.id;
+    }, []);
+    // Start flow on mount
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        async function start() {
+            try {
+                setIsLoading(true);
+                setError(null);
+                const sessionId = options?.sessionId ?? crypto.randomUUID();
+                const initialData = options?.initialData ?? new Map();
+                const instance = await engineRef.current.startFlow(definition, sessionId, initialData);
+                if (!cancelled) {
+                    syncFromInstance(instance);
+                }
+            }
+            catch (e) {
+                if (!cancelled) {
+                    setError(e instanceof Error ? e : new Error(String(e)));
+                }
+            }
+            finally {
+                if (!cancelled) {
+                    setIsLoading(false);
+                }
+            }
+        }
+        start();
+        return () => {
+            cancelled = true;
+        };
+        // definition identity is stable per mount — callers should useMemo if needed
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [definition]);
+    // Stable resume callback
+    const resume = (0, react_1.useCallback)(async (externalData) => {
+        const currentFlowId = flowIdRef.current;
+        if (!currentFlowId || !engineRef.current) {
+            throw new Error('Flow not started yet — cannot resume');
+        }
+        try {
+            setIsLoading(true);
+            setError(null);
+            const instance = await engineRef.current.resumeAndExecute(currentFlowId, definition, externalData);
+            syncFromInstance(instance);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e : new Error(String(e)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [definition, syncFromInstance]);
+    return { state, context, flowId, error, isLoading, resume };
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export { useFlow } from './use-flow.js';
+export type { UseFlowOptions, UseFlowResult } from './use-flow.js';

package/dist/esm/index.js

@@ -0,0 +1 @@
+export { useFlow } from './use-flow.js';

package/dist/esm/use-flow.d.ts

@@ -0,0 +1,28 @@
+import { type FlowDefinition, type FlowContext } from '@unlaxer/tramli';
+export interface UseFlowOptions {
+    /** Initial data to seed the flow context. */
+    initialData?: Map<string, unknown>;
+    /** Session ID for the flow instance. Defaults to crypto.randomUUID(). */
+    sessionId?: string;
+}
+export interface UseFlowResult<S extends string> {
+    /** Current flow state, or null before the flow starts. */
+    state: S | null;
+    /** Flow context, or null before the flow starts. */
+    context: FlowContext | null;
+    /** Flow instance ID, or null before the flow starts. */
+    flowId: string | null;
+    /** Error from the last operation, or null. */
+    error: Error | null;
+    /** True while startFlow or resume is in progress. */
+    isLoading: boolean;
+    /** Resume the flow with optional external data. */
+    resume: (externalData?: Map<string, unknown>) => Promise<void>;
+}
+/**
+ * React hook that manages a tramli flow lifecycle.
+ *
+ * Creates a FlowEngine + InMemoryFlowStore once per mount,
+ * starts the flow in useEffect, and exposes state/context/resume.
+ */
+export declare function useFlow<S extends string>(definition: FlowDefinition<S>, options?: UseFlowOptions): UseFlowResult<S>;

package/dist/esm/use-flow.js

@@ -0,0 +1,82 @@
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { Tramli, InMemoryFlowStore, } from '@unlaxer/tramli';
+/**
+ * React hook that manages a tramli flow lifecycle.
+ *
+ * Creates a FlowEngine + InMemoryFlowStore once per mount,
+ * starts the flow in useEffect, and exposes state/context/resume.
+ */
+export function useFlow(definition, options) {
+    const [state, setState] = useState(null);
+    const [context, setContext] = useState(null);
+    const [flowId, setFlowId] = useState(null);
+    const [error, setError] = useState(null);
+    const [isLoading, setIsLoading] = useState(true);
+    // Singleton store + engine per mount
+    const storeRef = useRef(null);
+    const engineRef = useRef(null);
+    const flowIdRef = useRef(null);
+    if (storeRef.current === null) {
+        storeRef.current = new InMemoryFlowStore();
+        engineRef.current = Tramli.engine(storeRef.current);
+    }
+    // Sync React state from a flow instance
+    const syncFromInstance = useCallback((instance) => {
+        setState(instance.currentState);
+        setContext(instance.context);
+        setFlowId(instance.id);
+        flowIdRef.current = instance.id;
+    }, []);
+    // Start flow on mount
+    useEffect(() => {
+        let cancelled = false;
+        async function start() {
+            try {
+                setIsLoading(true);
+                setError(null);
+                const sessionId = options?.sessionId ?? crypto.randomUUID();
+                const initialData = options?.initialData ?? new Map();
+                const instance = await engineRef.current.startFlow(definition, sessionId, initialData);
+                if (!cancelled) {
+                    syncFromInstance(instance);
+                }
+            }
+            catch (e) {
+                if (!cancelled) {
+                    setError(e instanceof Error ? e : new Error(String(e)));
+                }
+            }
+            finally {
+                if (!cancelled) {
+                    setIsLoading(false);
+                }
+            }
+        }
+        start();
+        return () => {
+            cancelled = true;
+        };
+        // definition identity is stable per mount — callers should useMemo if needed
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [definition]);
+    // Stable resume callback
+    const resume = useCallback(async (externalData) => {
+        const currentFlowId = flowIdRef.current;
+        if (!currentFlowId || !engineRef.current) {
+            throw new Error('Flow not started yet — cannot resume');
+        }
+        try {
+            setIsLoading(true);
+            setError(null);
+            const instance = await engineRef.current.resumeAndExecute(currentFlowId, definition, externalData);
+            syncFromInstance(instance);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e : new Error(String(e)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [definition, syncFromInstance]);
+    return { state, context, flowId, error, isLoading, resume };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@unlaxer/tramli-react",
+  "version": "0.1.0",
+  "description": "React hooks for tramli — useFlow wraps FlowEngine + FlowStore + FlowInstance lifecycle",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/esm/index.d.ts"
+    }
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opaopa6969/tramli-ts"
+  },
+  "author": "Hisayuki Ookubo <opaopa6969@gmail.com>",
+  "peerDependencies": {
+    "react": ">=18",
+    "@unlaxer/tramli": ">=3.3.0"
+  },
+  "devDependencies": {
+    "@unlaxer/tramli": "^3.3.0",
+    "@types/react": "^18.0.0",
+    "react": "^18.0.0",
+    "typescript": "^5.5.0"
+  }
+}