@jboltai/tokui-webc 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,51 @@
+# @jboltai/tokui-webc
+
+> TokUI 的 Web Component 适配器 —— 一个框架无关的 `<tokui-view>` 自定义元素。
+
+装一次，**任何框架**都能用：React / Vue / Svelte / Angular / 原生 HTML / 无框架。
+
+## 安装
+
+```bash
+npm install @jboltai/tokui-webc
+```
+
+## 用法
+
+```js
+import defineTokuiElement from '@jboltai/tokui-webc';
+defineTokuiElement(); // 注册 <tokui-view>
+```
+
+然后任意 HTML / JSX / template：
+
+```html
+<tokui-view dsl="[card tt:你好][p 流式 UI，零依赖][/card]"></tokui-view>
+```
+
+属性：
+- `dsl` —— 一次性渲染整段 DSL
+- `theme` —— 切换主题（如 `dark`）
+
+命令式 API（流式 / SSE）：
+
+```js
+const view = document.querySelector('tokui-view');
+view.startStream();
+view.feed('[card tt:');
+view.feed('流式卡片]');
+view.endStream();
+
+// SSE
+view.connect('/api/chat', { prompt: '画一个登录卡片' });
+```
+
+## CSS
+
+`@jboltai/tokui` 的样式随包自动注入（通过 `import` 副作用），无需手动引入。如需显式引入：
+
+```js
+import '@jboltai/tokui/css';
+```
+
+License: MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@jboltai/tokui-webc",
+  "version": "0.1.0",
+  "description": "TokUI Web Component — framework-agnostic <tokui-view> custom element wrapping @jboltai/tokui. Works in React, Vue, Svelte, Angular, vanilla, or any HTML.",
+  "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/webc"
+  },
+  "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"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "tokui",
+    "web-component",
+    "custom-element",
+    "tokui-view",
+    "framework-agnostic"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,20 @@
+import type { TokUI as TokUIClass } from '@jboltai/tokui';
+
+/**
+ * <tokui-view> 自定义元素。注册后可直接在 HTML / JSX / template 中使用。
+ */
+export class TokUIViewElement extends HTMLElement {
+  render(dsl: string): void;
+  startStream(): TokUIClass | null;
+  feed(chunk: string): void;
+  endStream(): void;
+  connect(url: string, body?: Record<string, any>): Promise<void>;
+}
+
+/**
+ * 注册自定义元素（默认 'tokui-view'）。
+ * SSR 下不注册（customElements 不存在），仅返回类。
+ */
+export default function defineTokuiElement(name?: string): typeof TokUIViewElement;
+
+export { defineTokuiElement };

package/src/index.js

@@ -0,0 +1,74 @@
+'use strict';
+
+// TokUI Web Component —— 框架无关的 <tokui-view> 自定义元素。
+// 在 React / Vue / Svelte / Angular / 原生 HTML 中均可使用同一套 DSL。
+import { TokUI, setTheme } from '@jboltai/tokui';
+
+// SSR 安全：Node 无 HTMLElement，用空基类兜底，避免 `extends HTMLElement` 在 import 求值期崩。
+// 方法体内访问的 DOM API 仅在浏览器调用时执行，SSR 不会触发。
+const BaseElement = (typeof HTMLElement !== 'undefined') ? HTMLElement : class {};
+
+/**
+ * <tokui-view> 自定义元素：把 TokUI 实例封装为标准 Custom Element。
+ * 属性：dsl（一次性渲染）、theme（主题切换）。
+ * 方法：render / startStream / feed / endStream / connect（透传到内部 TokUI 实例）。
+ */
+class TokUIViewElement extends BaseElement {
+  constructor() {
+    super();
+    this._ui = null;
+  }
+
+  static get observedAttributes() {
+    return ['dsl', 'theme'];
+  }
+
+  connectedCallback() {
+    if (this._ui) return;
+    this._ui = new TokUI({ container: this });
+    const theme = this.getAttribute('theme');
+    if (theme) { try { setTheme(theme); } catch (e) { /* 主题可能未注册 */ } }
+    const dsl = this.getAttribute('dsl');
+    if (dsl) this.render(dsl);
+  }
+
+  disconnectedCallback() {
+    if (this._ui && this._ui.disconnect) this._ui.disconnect();
+    this._ui = null;
+  }
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    if (oldVal === newVal) return;
+    if (name === 'theme' && newVal) { try { setTheme(newVal); } catch (e) { /* ignore */ } }
+    if (name === 'dsl' && this._ui && newVal) this.render(newVal);
+  }
+
+  // —— 透传 TokUI 实例方法 ——
+  render(dsl) { if (this._ui) this._ui.render(dsl); }
+  startStream() { if (this._ui) this._ui.startStream(); return this._ui; }
+  feed(chunk) { if (this._ui) this._ui.feed(chunk); }
+  endStream() { if (this._ui) this._ui.endStream(); }
+  connect(url, body) {
+    return this._ui ? this._ui.connect(url, body)
+      : Promise.reject(new Error('@jboltai/tokui-webc: element not connected yet'));
+  }
+}
+
+/**
+ * 注册 <tokui-view>（或自定义元素名）。
+ * SSR 环境下 customElements 不存在，会给出告警并返回类本身（不注册）。
+ * @param {string} [name='tokui-view'] 自定义元素名（须含连字符）
+ * @returns {typeof TokUIViewElement}
+ */
+export function defineTokuiElement(name) {
+  name = name || 'tokui-view';
+  if (typeof customElements === 'undefined') {
+    console.warn('@jboltai/tokui-webc: customElements 不可用（SSR？）。请在浏览器环境调用 defineTokuiElement()。');
+    return TokUIViewElement;
+  }
+  if (!customElements.get(name)) customElements.define(name, TokUIViewElement);
+  return TokUIViewElement;
+}
+
+export { TokUIViewElement };
+export default defineTokuiElement;