@jboltai/tokui 0.1.0

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@jboltai/tokui",
+  "version": "0.1.0",
+  "description": "TokUI — Zero-dependency streaming UI description & rendering framework for AI chat. Describe UI with a tiny DSL, stream over SSE, render to real DOM incrementally.",
+  "keywords": [
+    "tokui",
+    "streaming-ui",
+    "dsl",
+    "ui-framework",
+    "ai",
+    "sse",
+    "server-sent-events",
+    "component",
+    "render",
+    "framework-agnostic",
+    "react",
+    "vue",
+    "svelte",
+    "web-components"
+  ],
+  "license": "MIT",
+  "author": "sdxiaomu (https://jboltai.com)",
+  "contributors": [
+    "sdxiaomu <mumengmeng@vecspc.com>"
+  ],
+  "homepage": "https://github.com/jboltai/tokui",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jboltai/tokui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jboltai/tokui/issues"
+  },
+  "main": "dist/tokui.cjs",
+  "module": "dist/tokui.mjs",
+  "types": "src/index.d.ts",
+  "browser": "dist/tokui.umd.js",
+  "unpkg": "dist/tokui.umd.js",
+  "jsdelivr": "dist/tokui.umd.js",
+  "style": "dist/tokui.css",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./dist/tokui.mjs",
+      "require": "./dist/tokui.cjs",
+      "browser": "./dist/tokui.umd.js",
+      "default": "./dist/tokui.mjs"
+    },
+    "./css": "./dist/tokui.css",
+    "./builder": {
+      "types": "./src/server/tokui-builder.d.ts",
+      "node": "./src/server/tokui-builder.js",
+      "require": "./src/server/tokui-builder.js",
+      "default": "./src/server/tokui-builder.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/index.d.ts",
+    "src/server/tokui-builder.js",
+    "src/server/tokui-builder.d.ts",
+    "README.md",
+    "README_EN.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "c8": "^10.1.3",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitepress": "^1.6.4"
+  },
+  "scripts": {
+    "test": "npm run test:all",
+    "test:all": "for f in tests/test-*.js; do node \"$f\" || exit 1; done",
+    "test:core": "node tests/test-event-bus.js && node tests/test-theme.js && node tests/test-renderer.js",
+    "test:parser": "node tests/test-parser.js",
+    "test:builder": "node tests/test-builder.js",
+    "test:layout": "node tests/test-layout.js",
+    "test:table": "node tests/test-table.js",
+    "typecheck": "tsc",
+    "coverage": "c8 --include='src/**/*.js' --exclude='src/server/**' npm run test:all",
+    "server": "node src/server/sse-server.js",
+    "dev": "vite",
+    "build": "vite build --mode lib",
+    "build:lib": "vite build --mode lib",
+    "dev:lib": "vite build --mode lib --watch",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "npm run build && vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,116 @@
+// Type definitions for TokUI
+// 零依赖流式 UI 描述与渲染框架 / Zero-dependency streaming UI description & rendering framework
+// Public API mirrors src/lib.js
+
+/**
+ * 事件处理器函数签名
+ * @param data  - DSL 中 clk/sub 属性携带的数据（任意结构）
+ * @param event - 原生 DOM 事件对象
+ * @param element - 触发事件的 DOM 元素
+ */
+export type TokUIHandlerFn = (data: any, event: Event, element: HTMLElement) => void;
+
+/**
+ * onEvent 回调签名
+ * @param eventName - 事件名，如 'streamEnd'
+ * @param data      - 事件数据
+ */
+export type TokUIEventCallback = (eventName: string, data: any) => void;
+
+/**
+ * TokUI 构造选项
+ */
+export interface TokUIOptions {
+  /** 渲染目标容器（CSS 选择器或 DOM 元素） */
+  container?: string | HTMLElement | null;
+  /** 主题名称，如 'default' / 'dark'，默认 'default' */
+  theme?: string;
+  /** 是否启用流式渲染模式，默认 true */
+  streaming?: boolean;
+  /** 事件回调，如接收到 ('streamEnd', {}) */
+  onEvent?: TokUIEventCallback | null;
+}
+
+/**
+ * TokUI 核心类
+ *
+ * 三种用法：
+ *   render(dsl)               — 一次性渲染
+ *   startStream() + feed(chk) — 手动流式喂入
+ *   connect(url, body)        — SSE 自动连接并流式渲染
+ *
+ * @example
+ * const ui = new TokUI({ container: '#app', theme: 'dark' });
+ * ui.connect('/api/chat/stream', { prompt: 'hi' });
+ */
+export class TokUI {
+  /** 合并后的运行时选项 */
+  options: Required<Pick<TokUIOptions, 'theme' | 'streaming'>> & TokUIOptions;
+
+  /** 主容器 DOM */
+  container: HTMLElement | null;
+
+  /** 流式目标容器 */
+  streamingContainer: HTMLElement | null;
+
+  constructor(options?: TokUIOptions);
+
+  /** 一次性渲染完整 DSL 文本到容器 */
+  render(tokuiString: string, targetContainer?: HTMLElement): void;
+
+  /** 开始流式渲染（初始化流式解析器） */
+  startStream(targetContainer?: HTMLElement): void;
+
+  /** 向流式解析器喂入一段 DSL 文本片段 */
+  feed(chunk: string): void;
+
+  /** 结束流式渲染（刷新缓冲区并重置插槽栈） */
+  endStream(): void;
+
+  /** 断开 SSE 连接并清理流式容器 */
+  disconnect(): void;
+
+  /** 通过 SSE 连接服务端并流式渲染，返回 fetch Promise */
+  connect(url: string, body?: Record<string, any>): Promise<void>;
+}
+
+/**
+ * 注册事件处理函数（与 DSL 中 clk:/sub: 绑定对应）
+ * @param name - 处理函数名称
+ * @param fn   - 处理函数
+ */
+export declare function registerHandler(name: string, fn: TokUIHandlerFn): void;
+
+/** 移除已注册的事件处理函数 */
+export declare function removeHandler(name: string): void;
+
+/** 设置当前主题（更新容器 data-tokui-theme 属性） */
+export declare function setTheme(themeName: string): void;
+
+/** 获取当前主题名称 */
+export declare function getTheme(): string;
+
+/**
+ * DOM 创建快捷方法
+ * @param tag         - 标签名
+ * @param attrs       - 属性键值表（on* / formaction 会被过滤防 XSS）
+ * @param textContent - 文本内容
+ */
+export declare function el(
+  tag: string,
+  attrs?: Record<string, unknown>,
+  textContent?: string
+): HTMLElement;
+
+/** 公共命名空间对象（ESM default 导出） */
+export interface TokUINamespace {
+  TokUI: typeof TokUI;
+  registerHandler: typeof registerHandler;
+  removeHandler: typeof removeHandler;
+  setTheme: typeof setTheme;
+  getTheme: typeof getTheme;
+  el: typeof el;
+}
+
+declare const TokUINamespace: TokUINamespace;
+export default TokUINamespace;

package/src/server/tokui-builder.d.ts

@@ -0,0 +1,89 @@
+// Type definitions for TokUIBuilder
+// 链式 DSL 生成器 / Chainable DSL builder (server-side)
+// Public API mirrors src/server/tokui-builder.js
+//
+// 注：builder 有 ~170 个对应 DSL 组件的链式方法，本声明覆盖核心原语
+// （_open / _selfClosing）与常用组件。**未列出**的组件方法可用这两个
+// 原语等价表达，或临时 `as any`：
+//   b._selfClosing('gantt', null, { data: [...] })   // 自闭合组件
+//   b._open('drawer', { tt: '抽屉' }) ... b.end()    // 容器组件
+
+/** 组件属性键值表（DSL 属性，值任意） */
+export type BuilderAttrs = Record<string, any>;
+
+/**
+ * TokUI 构建器 —— 链式生成 TokUI DSL 字符串
+ *
+ * @example
+ * const b = new TokUIBuilder();
+ * b.card({ tt: '标题' }).h2('内容').p('描述').end();
+ * const dsl = b.toString(); // '[card tt:标题][h2 内容][p 描述][/card]'
+ */
+export declare class TokUIBuilder {
+  constructor();
+
+  // —— 终端方法（输出）——
+  /** 输出完整 DSL 字符串（自动补全未关闭容器） */
+  toString(): string;
+  /** 输出 DSL 片段数组（自动补全未关闭容器） */
+  toChunks(): string[];
+
+  // —— 容器栈控制 ——
+  /** 关闭最近一个未关闭容器 */
+  end(): this;
+  /** 关闭全部未关闭容器 */
+  endAll(): this;
+  /** 清空构建器状态 */
+  reset(): this;
+
+  // —— 底层原语（任意组件的强类型逃逸口）——
+  /** 容器组件开标签 */
+  _open(type: string, attrs?: BuilderAttrs): this;
+  /** 自闭合组件 */
+  _selfClosing(type: string, content?: string | null, attrs?: BuilderAttrs): this;
+  /** 补全未关闭容器并返回片段数组 */
+  _finalizeChunks(): string[];
+
+  // —— 标题 / 文本（content-first）——
+  h1(content?: string, attrs?: BuilderAttrs): this;
+  h2(content?: string, attrs?: BuilderAttrs): this;
+  h3(content?: string, attrs?: BuilderAttrs): this;
+  h4(content?: string, attrs?: BuilderAttrs): this;
+  h5(content?: string, attrs?: BuilderAttrs): this;
+  h6(content?: string, attrs?: BuilderAttrs): this;
+  p(content?: string, attrs?: BuilderAttrs): this;
+  tag(content?: string, attrs?: BuilderAttrs): this;
+
+  // —— 自闭合叶子（attrs-only）——
+  dv(attrs?: BuilderAttrs): this;
+  a(attrs?: BuilderAttrs): this;
+  img(attrs?: BuilderAttrs): this;
+  input(attrs?: BuilderAttrs): this;
+  pwd(attrs?: BuilderAttrs): this;
+  btn(attrs?: BuilderAttrs): this;
+  checkbox(attrs?: BuilderAttrs): this;
+  toggle(attrs?: BuilderAttrs): this;
+  col(attrs?: BuilderAttrs): this;
+  tcol(attrs?: BuilderAttrs): this;
+  opt(attrs?: BuilderAttrs): this;
+
+  // —— 容器（attrs-only，需 end() 闭合）——
+  card(attrs?: BuilderAttrs): this;
+  ft(attrs?: BuilderAttrs): this;
+  form(attrs?: BuilderAttrs): this;
+  table(attrs?: BuilderAttrs): this;
+  tbody(attrs?: BuilderAttrs): this;
+  select(attrs?: BuilderAttrs): this;
+  radio(attrs?: BuilderAttrs): this;
+  btngroup(attrs?: BuilderAttrs): this;
+  picker(attrs?: BuilderAttrs): this;
+  toggleGroup(attrs?: BuilderAttrs): this;
+
+  // —— 表格辅助 ——
+  thead(attrs?: BuilderAttrs): this;
+  theadCols(cols: any[]): this;
+  tr(cells: any[], attrs?: BuilderAttrs): this;
+
+  // —— 代码块（容器）——
+  code(attrs?: BuilderAttrs): this;
+}