@jboltai/tokui-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jboltai.com
+
+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,56 @@
+# @jboltai/tokui-react
+
+> TokUI 的 React 适配器：`<TokUIView>` 组件 + `useTokUIStream()` 流式 hook。
+
+## 安装
+
+```bash
+npm install @jboltai/tokui-react react
+```
+
+## 声明式渲染
+
+```jsx
+import { TokUIView } from '@jboltai/tokui-react';
+
+export function App() {
+  return (
+    <TokUIView
+      dsl="[card tt:你好 TokUI][p 流式 UI，零依赖][/card]"
+      theme="default"
+    />
+  );
+}
+```
+
+`dsl` 变化时自动重新渲染；组件卸载时自动断开清理。
+
+## 流式 / SSE
+
+```jsx
+import { useTokUIStream } from '@jboltai/tokui-react';
+
+export function Chat() {
+  const { ref, start, feed, end, connect } = useTokUIStream();
+  return (
+    <>
+      <div ref={ref} />
+      <button onClick={() => {
+        start();
+        feed('[card tt:');
+        feed('流式卡片]');
+        end();
+      }}>渲染</button>
+      <button onClick={() => connect('/api/chat', { prompt: '画登录卡片' })}>
+        SSE 连接
+      </button>
+    </>
+  );
+}
+```
+
+## CSS
+
+样式随 `@jboltai/tokui` 自动注入，无需手动引 CSS。
+
+License: MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@jboltai/tokui-react",
+  "version": "0.1.0",
+  "description": "TokUI React adapter — <TokUIView> component and useTokUIStream() hook for streaming DSL UI.",
+  "license": "MIT",
+  "author": "sdxiaomu (https://jboltai.com)",
+  "homepage": "https://github.com/jboltai/tokui",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jboltai/tokui.git",
+    "directory": "packages/react"
+  },
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@jboltai/tokui": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    }
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "tokui",
+    "react",
+    "streaming-ui",
+    "dsl",
+    "hook"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,30 @@
+import type * as React from 'react';
+import type { TokUI as TokUIClass, TokUIEventCallback } from '@jboltai/tokui';
+
+export interface TokUIViewProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** DSL 文本，变化时重新渲染 */
+  dsl?: string;
+  /** 主题名（如 'dark'） */
+  theme?: string;
+  /** 事件回调，签名 (eventName, data) */
+  onEvent?: TokUIEventCallback;
+}
+
+export declare const TokUIView: React.FC<TokUIViewProps>;
+
+export interface UseTokUIStreamReturn {
+  ref: React.RefObject<HTMLDivElement>;
+  ui: React.MutableRefObject<TokUIClass | null>;
+  start: (container?: HTMLDivElement) => void;
+  feed: (chunk: string) => void;
+  end: () => void;
+  connect: (url: string, body?: Record<string, any>) => Promise<void>;
+  disconnect: () => void;
+}
+
+export declare function useTokUIStream(options?: {
+  theme?: string;
+  onEvent?: TokUIEventCallback;
+}): UseTokUIStreamReturn;
+
+export default TokUIView;

package/src/index.js

@@ -0,0 +1,88 @@
+'use strict';
+
+// TokUI React 适配器：<TokUIView> 组件 + useTokUIStream() 流式 hook。
+// 用 createElement 避免 JSX 运行时依赖，兼容任意 React 16.8+ 项目。
+import { useEffect, useRef, useCallback, createElement } from 'react';
+import { TokUI, setTheme } from '@jboltai/tokui';
+
+/**
+ * 声明式渲染一段 TokUI DSL。
+ * @param {object} props
+ * @param {string} [props.dsl] DSL 文本（变化时重新渲染）
+ * @param {string} [props.theme] 主题名
+ * @param {function} [props.onEvent] 事件回调 (name, data)
+ */
+export function TokUIView(props) {
+  const { dsl, theme, onEvent, ...rest } = props;
+  const ref = useRef(null);
+  const uiRef = useRef(null);
+
+  // 挂载时创建 TokUI 实例；卸载时断开清理
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const ui = new TokUI({ container: el, theme, onEvent });
+    uiRef.current = ui;
+    if (theme) { try { setTheme(theme); } catch (e) { /* ignore */ } }
+    if (dsl) ui.render(dsl);
+    return () => {
+      try { if (ui.disconnect) ui.disconnect(); } catch (e) { /* ignore */ }
+      uiRef.current = null;
+    };
+    // 仅挂载时初始化（theme/onEvent 变化不重建实例）
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // dsl 变化 → 重新渲染
+  useEffect(() => {
+    const ui = uiRef.current;
+    if (ui && dsl != null) ui.render(dsl);
+  }, [dsl]);
+
+  return createElement('div', { ref, ...rest });
+}
+
+/**
+ * 流式渲染 hook（手动 feed / SSE connect）。
+ * @param {object} [options] TokUI 构造选项（theme/onEvent 等）
+ * @returns {{ref, ui, start, feed, end, connect, disconnect}}
+ */
+export function useTokUIStream(options) {
+  const ref = useRef(null);
+  const uiRef = useRef(null);
+
+  const get = useCallback(() => {
+    if (!uiRef.current && ref.current) {
+      uiRef.current = new TokUI({ container: ref.current, ...(options || {}) });
+    }
+    return uiRef.current;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const start = useCallback((container) => {
+    const ui = get();
+    if (ui) ui.startStream(container || ref.current);
+  }, [get]);
+
+  const feed = useCallback((chunk) => {
+    const ui = get();
+    if (ui) ui.feed(chunk);
+  }, [get]);
+
+  const end = useCallback(() => {
+    if (uiRef.current) uiRef.current.endStream();
+  }, []);
+
+  const connect = useCallback((url, body) => {
+    const ui = get();
+    return ui ? ui.connect(url, body) : Promise.resolve();
+  }, [get]);
+
+  const disconnect = useCallback(() => {
+    if (uiRef.current && uiRef.current.disconnect) uiRef.current.disconnect();
+  }, []);
+
+  return { ref, ui: uiRef, start, feed, end, connect, disconnect };
+}
+
+export default TokUIView;