@adia-ai/web-组件
AdiaUI的香草网络组件. ~130 光度- DOM 自定义元素
(单位:千美元)ls components | wc -l 是人口普查)+ 56个可变特性,反应核(信号+标记-模板渲染器),形式相联的形式控制,并被集成到A2UI生成管.
这个包裹只运送UI原子. 复合贝壳(admin / chall / 编辑器 / 简单 / 主题) 活在
@adia-ai/web-modulesA2UI 协议运行时间@adia-ai/a2ui; 生成管道+图案体@adia-ai/gen-ui; MCP 服务器在@adia-ai/mcp(数量)gen-ui(原始内容存档于2018-10-21). space.消费者指南:
USAGE.md——财产反应,事件合同,形式参与,生命周期,注册,TypeScript. 如果你把AdiaUI 整合到一个应用程序里 就从这里开始.现场演示 用于每个组件
https://ui-kit.exe.xyz/site/components/<name>—— 说<name>标记没有-ui后缀(例如:.button, (中文(简体) ),select, (中文(简体) ),slider) (中文(简体) ).
安装
npm install @adia-ai/web-components
对于复合弹壳(admin / calm / 编辑器 / 简单 / 主题集群),配对 @adia-ai/web-modules数字 :
npm install @adia-ai/web-components @adia-ai/web-modules
使用人工智能代理( Claude Code / Cursor / Windsurf / Claude 桌面)
使用 AI 编码代理编译 UI 时, 加载 adia-ui-kit 技能 在特工的绳子。 它编码:
- 完整组件目录( 其中
*-ui标签做什么 + 当使用它时) - 组成模式(admin shell、仪表板、表格、聊天、编辑器表面)
- 飞行前舱门(在撰写前捕获到"没有申报道由的进口")
- Plan-Execut-Verify 纪律(将结果提交真正的演示以核实)
这个技能生活在 .agents/skills/adia-ui-kit/ 在repo;活化短语包括"用AdiaUI来构建一页","组成这个UI","线上这些组件","使用AdiaUI组件来作曲"等,以及"一个管理员应用/仪表板/形式/聊天表面的规律是什么"等. 没有技能,一个代理就与这个README作对;凭借技能,它拥有推理阶梯+目录+每个组件的配方.
CDN — 无捆绑器( CodePen, 营销页, 静态 HTML)
自兹 (单位:千美元),这个包船 预膨胀 + 精密捆绑在下面 dist/ 使用零积分工具。 把这些放入 HTML 页面 :
<!-- CSS: all components, tokens, resets (443 KB raw / ~50 KB gzipped) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/[email protected]/dist/web-components.min.css">
<!-- JS: registers every component (~250 KB gzipped via Brotli) -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/[email protected]/dist/web-components.min.js"></script>
这个 @0.8 范围跟踪最新 0.8.x 自动补丁( 不会跳到断开处) 0.9) (中文(简体) ). 对于可复制的建筑,用精确的版本来取而代之——例如. @adia-ai/[email protected]/dist/web-components.min.css。 。 。 .
对于复合弹壳,添加来自 @adia-ai/web-modules 看到了吗 其读物 或 CDN 使用指南。厨房下沉路径是 @adia-ai/web-modules/dist/everything.min.js (所有组件+全部4个弹壳;~424 KB gziped)——CodePen演示的一个标记.
选择一条捆绑的道路. 相会(如. everything.min.js + 一个单独的 web-components.min.js原因 customElements.define 将“名称”丢入 dup-load 上。 选择树 :
- HTML- first / CodePen / 市场营销 →
@adia-ai/web-modules/everything(一个标签覆盖一切) - 仅包括部件,无壳 →
@adia-ai/web-components/js/bundled - 维特/网包/建设-现有根导出(
import '@adia-ai/web-components'; 计 数*/bundled出口是添加剂——捆绑者消费者没有看到变化.
快开始
仅限无害环境管理——捆绑者(Vite、esbuilt、webpack 5+、Rollup) import 两者 .js 财务报告和审定财务报表 .css; 在简单的 HTML 使用中 <script type="module"> + 键 <link rel="stylesheet">。 。 。 .
import '@adia-ai/web-components'; // registers every *-ui tag
import '@adia-ai/web-components/css'; // every component's CSS (one stylesheet)
或每个组件 树震动意识捆绑:
import '@adia-ai/web-components/components/button'; // <button-ui> only
import '@adia-ai/web-components/components/button.css'; // its CSS
然后在标记中使用标记 :
<card-ui>
<header>
<span slot="icon"><avatar-ui icon="user"></avatar-ui></span>
<span slot="heading"><text-ui strong>Hello</text-ui></span>
</header>
<section>Composition works out of the box — no framework.</section>
</card-ui>
包裹 sideEffects 条目保持上方的导入不为
树形; 导入 index.js 副作用 - 登记每个组件.
版式
web-components/
├── core/ — Reactivity + base classes
│ ├── signals.js signal() / computed() / effect() / batch() / untracked()
│ ├── template.js tagged templates: html, css, repeat, stamp
│ ├── element.js UIElement — light-DOM reactive base
│ ├── form.js UIFormElement — form-associated + ElementInternals + validation
│ ├── provider.js global provider registration + router-ui
│ ├── anchor.js popover + anchor-positioning
│ ├── markdown.js lightweight markdown renderer
│ ├── transport.js SSE / streaming helpers for LLM adapters
│ └── data-stream.js `data-stream-*` attribute trait (HTTP/SSE/WS,
│ signal-backed, refcounted shared transports)
│
├── components/ — ~130 *-ui custom elements (components)
│ └── <tag>/
│ ├── <tag>.js class definition (extends UIElement / UIFormElement)
│ ├── <tag>.css @scope(tag-ui) two-block: tokens + styles
│ ├── <tag>.yaml authoring contract (props, slots, events, examples)
│ └── <tag>.a2ui.json generated — do NOT edit
│
│ Composite shells (admin-shell, chat-shell, editor-shell, simple-shell,
│ theme-panel, gen-root, a2ui-root) ship in the sibling
│ `@adia-ai/web-modules` package — see ADR-0012 for the three-tier
│ rationale.
│
├── traits/ — 56 composable behaviors via defineTrait() + the
│ <traits-host> wrapper for raw-HTML declarative
│ composition. Generated catalog at _catalog.json
│ drives the MCP get_traits tool + per-trait demo
│ pages. Full contract in .claude/docs/specs/traits.md.
│
└── styles/ — Global tokens and CSS layering
├── tokens.css all --a-* design tokens
├── colors/ primitives / semantics / scrims
├── typography.css, space.css, radius.css, shadow.css
└── themes/*.css 8 themes (ocean, forest, sunset, …)
建设 + dev 公用事业(包括 build-a2ui-data.mjs, (中文(简体) ), qa-training.mjs, (中文(简体) ),
a2ui-to-html.cjs, (中文(简体) ), mcp-call.cjs, (中文(简体) ), mcp-pipeline.cjs, (中文(简体) ), screenshot.cjs(中文(简体) )
住在转场 scripts/ 目录而不是此目录
软件包——它们横跨单列波(MCP服务器,a2ui-corpus数据,
组件目录),并且不只局限于网络组件.
使用组件(消费者指南)
完整的消费者表面——财产反应、事件合同、形式参与、生命周期、登记、TypeScript——生活在 USAGE.md。如果您正在将 AdiaUI 整合到一个应用程序中, 而不是编写一个新的组件, 请从那里开始 .
快速引用 :
// Property reactivity — every prop is signal-backed
slider.value = 75; // triggers re-render
// Event contract — CustomEvent with typed detail (since v0.4.5)
slider.addEventListener('change', (e) => console.log(e.detail.value));
// Form participation — 15 components extend UIFormElement
new FormData(document.getElementById('settings')); // includes every <input-ui>, <select-ui>, etc.
// Lifecycle — UIElement provides connected/render/updated/disconnected hooks
class MyWidget extends UIElement {
connected() { /* set up */ }
render() { /* update DOM */ }
disconnected() { /* tear down */ }
}
// Registration — conflict-safe via defineIfFree
import { defineIfFree } from '@adia-ai/web-components/core';
defineIfFree('my-widget', MyWidget);
TypeScript用户:自v.4.6.起在包件中为船型. import type { UISlider, SliderChangeEvent } from '@adia-ai/web-components' 手型处理器; HTMLElementTagNameMap 被扩充到 document.querySelector('slider-ui') 返回时 UISlider。 。 。 .
写入组件
如果你贡献了一个新的部件(而不是消耗的部件),这是给你的。 每个组件都是单文件类扩展 UIElement (或 UIFormElement 为窗体字段)。 所有造型都住在兄弟会里 .css 文件使用 双块 @scope数字 :
@scope (button-ui) {
:where(:scope) {
/* Tokens only — zero specificity, parent overrides win */
--button-bg: var(--a-accent-bg);
--button-fg: var(--a-accent-fg);
--button-radius: var(--a-radius);
}
:scope {
/* Styles — consume component tokens only, never global directly */
background: var(--button-bg);
color: var(--button-fg);
border-radius: var(--button-radius);
}
:scope[variant="danger"] {
--button-bg: var(--a-danger-bg); /* variants override tokens, not styles */
}
}
撰写规则(由 ui-audit-coherence:
- 无生色 在组件CSS中——每种颜色都通过一个符号.
- 变体会改变符号,模式会改变布局. 设置选择器
display, (中文(简体) ),padding, (中文(简体) ),flex, (中文(简体) ),grid等为 a 模式 需要一个 合同文件中的受制裁模式属性条目. - 布尔道具默认为
false。 。 。 . 如果预期的默认值是"在", 翻转名称( r)closable→permanent) (中文(简体) ). - 活动听众在
connected()有匹配removeEventListener内disconnected()。 。 。 . 手艺稳定#field箭头,永远不要 内线. - 只有轻度DOM. 没有
::part(), (中文(简体) ),::slotted(),阴之根也. 使用 儿童属性选择器 ::scope > [slot="icon"]。 。 。 .
static template 是结束 —— 导入它提到的内容
这个 static template 属性是常规的 JavaScript 关闭(典型的标记模板字元 - () => html 随后是模板正文)。 任何信号,变量或函数 引用必须是 范围方面的理论 在定义类的文件。 这是 JavaScript 范围界定, 而不是任何 AdiaUI 的特异性 —— 但让作者惊讶的是, 它来自框架, 其中模板神奇地接收道具.
// ❌ WRONG — ReferenceError at runtime: minL is not defined
// (no import; the template function can't see minL just because
// it's exported elsewhere in the monorepo)
class MyPanel extends UIElement {
static template = () => html`<div>L: ${minL.value}</div>`;
}
// ✅ RIGHT — import the signal locally
import { minL } from './state.js';
class MyPanel extends UIElement {
static template = () => html`<div>L: ${minL.value}</div>`;
}
浏览器控制台中的错误显示为 ReferenceError: minL is not defined 初出炉时——不是舱载时,不是 tsc --noEmit。 。 。 . 模板函数机构的跟踪点,而不是在缺失的导入,这是不引向的部分.
如果你的组件需要 外部反应状态 不同每英寸, 把它暴露为财产 而不是达到模块范围信号:
// ✅ Best — per-instance reactive prop
class MyPanel extends UIElement {
static properties = {
minL: { type: Number, default: 0 },
};
static template = el => html`<div>L: ${el.minL}</div>`;
}
// Consumer:
<my-panel .minL=${minL}></my-panel> // signal binds reactively per ADR-template-binding
这个 el 参数是元素实例——每个信号后置属性都是被动读取.
正式写作合同: .claude/docs/specs/component-token-contract.md。 。 。 .
这个 adia-ui-authoring 技能编码了20个不可谈判的规则.
卡-n/抽屉-Ui 构成均等
两个都接受赤裸 <header> 编号 : <section> 编号 : <footer> 标记或明确
[slot="header|body|footer"]。当
任何直接 [slot="icon|heading|description|action"] 存在孩子
(单位:千美元):has(> …) ——只有直生子女). 绘图器支持多节正体
有粘相头/脚. 已工作的抽屉组件页面
实例.
A2UI 运行时间
A2UI 运行时间生活在兄弟零依赖度 @adia-ai/a2ui 软件包; 此软件包是组件目录, 其渲染器解析标记对应 :
import { A2UIRenderer } from '@adia-ai/a2ui';
import '@adia-ai/web-components'; // register the custom elements
const renderer = new A2UIRenderer(document.getElementById('canvas'));
renderer.process({
type: 'updateComponents',
components: [
{ id: 'root', component: 'Card', children: ['hdr', 'body'] },
{ id: 'hdr', component: 'Header', slots: { heading: 'Generated UI' } },
{ id: 'body', component: 'Section', children: ['btn'] },
{ id: 'btn', component: 'Button', attrs: { variant: 'primary' }, content: 'Click' },
],
});
核心消息类型 : createSurface, (中文(简体) ), updateComponents, (中文(简体) ),
updateDataModel, (中文(简体) ), wireComponents, (中文(简体) ), deleteSurface (单位:千美元)
updateStyles编号 :removeStyles) (中文(简体) ). 登记册使LLM的发送正常化
异名( 例如 ). Carousel → swiper-ui)所以生成的输出很强
以命名为漂流.
数据流通过 data-stream-* 属性
有固定表的任何元素 .data 财产——图表-i、表格-i、,
热映射-ui、stat-ui、list-ui等——可从支持中获取
仅通过属性来源。 无每个组件选入 :
<!-- HTTP one-shot fetch, JSON -->
<chart-ui type="area" x="month" y="revenue"
data-stream-src="/api/revenue?range=3m"
data-stream-path="data"></chart-ui>
<!-- HTTP polling every 5s -->
<table-ui sortable striped
data-stream-src="/api/orders"
data-stream-interval="5000"></table-ui>
<!-- Server-Sent Events, append on each message -->
<heatmap-ui type="matrix" rows="7" cols="52"
data-stream-src="/sse/activity"
data-stream-mode="sse"
data-stream-merge="append"></heatmap-ui>
<!-- Spread a multi-property response onto the element -->
<stat-ui data-stream-src="/api/kpi"
data-stream-target="*"></stat-ui>
模式:HTTP(一发或投票), sse (单位:千美元)EventSource, (中文(简体) ), ws
(单位:千美元)WebSocket。格式: json (违约), csv, (中文(简体) ), tsv, (中文(简体) ), jsonl, (中文(简体) ),
text ——自动从URL扩展或内容类型中检测出. 两个
属性- 相同流的元素共享一个传输
(重新计算,信号支持);明确 data-stream-id 让我们
不相关的配置有意共享 。 通过程序访问
页:1 streams 从 core/data-stream.js。 。 。 .
执行: core/data-stream.js (~360行). 满
属性表 +活演示:
/site/components/chart#data-stream。 。 。 .
构建
npm run build:components # regenerate all .a2ui.json from YAML
大楼也写着 packages/gen-ui/a2ui/catalog/catalog-a2ui_1_0.json 财务报告和审定财务报表
catalog-a2ui_1_0_rules.txt 平面文件目录 MCP 服务器和
生成引擎消耗(ADR- 0050:目录是 @adia-ai/a2ui是因为
(合同).
主题、密度、尺度
<div theme="ocean" density="compact" size="sm">
…all descendants re-theme / re-densify / re-scale automatically…
</div>
[theme]- 8个主题:default, (中文(简体) ),ocean, (中文(简体) ),forest, (中文(简体) ),sunset, (中文(简体) ),lavender, (中文(简体) ),rose, (中文(简体) ),slate, (中文(简体) ),midnight[density]—— 说compact· (0.85×)spacious(1.15×) (中文(简体) )[size]—— 说sm|md|lg移动整个类型尺度+组件 维度[radius]—— 说sharp(0) ·rounded(1) 妇女round(二)
每个都是CSS可变的覆被;没有类切换,没有再入.
依赖方向
gen-ui (compose/) ──reads──> gen-ui (corpus/) ←─reads── web-components
mcp ──reads──> gen-ui
网络组件从未从 @adia-ai/gen-ui 或者说 @adia-ai/mcp。A2UI 渲染器
使用一个协议,而不是一个生成器——任何释放有效的 A2UI 的
信息驱动它.
许可证
麻省理工学院