@joplo-app/plugin-ui 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,97 @@
+Required Notice: Copyright 2026 Joplo-app (https://joplo.app, support@joplo.app)
+
+Licensor Line of Business: Joplo, a tool for authoring, previewing, reviewing, and publishing interactive product prototypes, demos, and presentations (https://joplo.app)
+Licensor Line of Business: Joplo Cloud, a service for hosting, sharing, commenting on, reviewing, and measuring Joplo prototypes and presentations (https://joplo.app)
+
+What counts as competing, and how to ask about other uses: see COMMERCIAL.md
+https://github.com/Joplo-app/Joplo/blob/main/COMMERCIAL.md
+
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/dist/catalog.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 第一方 UI 组件目录（D35 / D87）：名称与属性对齐 Mantine（数据表对齐 mantine-datatable），另加少量 AI 交互组件、
+ * HTML 兜底标签和 Joplo 专用组件。复合组件用点语法：`<AppShell.Header>` 编译出的节点 type 是 'ui:AppShell.Header'。
+ *
+ * 目录是唯一来源：@joplo-app/plugin-ui 的导出、同包 runtime 的实现、COMPONENT_DOCS 都必须与 COMPONENT_TYPES 一致
+ * （packages/core/test/catalog.test.ts 与渲染器的类型检查保证）。目录之外的名称在编译时报错，不会被静默渲染。
+ * 只换词汇，不换渲染：运行时不引入 Mantine，仍由 Joplo 渲染成低保真风格。
+ */
+export declare const HTML_TAGS: readonly string[];
+export declare const COMPONENT_TYPES: readonly ["AppShell", "AppShell.Header", "AppShell.Navbar", "AppShell.Main", "AppShell.Aside", "AppShell.Footer", "Container", "Stack", "Group", "Flex", "Grid", "Grid.Col", "SimpleGrid", "Center", "Box", "Space", "Paper", "Card", "Card.Section", "Divider", "ScrollArea", "Title", "Text", "Code", "Kbd", "Blockquote", "List", "List.Item", "Badge", "Avatar", "Image", "ThemeIcon", "Indicator", "Timeline", "Timeline.Item", "Table", "Table.Thead", "Table.Tbody", "Table.Tr", "Table.Th", "Table.Td", "DataTable", "Accordion", "Accordion.Item", "Accordion.Panel", "Radio", "Tabs.List", "Tabs.Panel", "Breadcrumbs", "Stepper", "Stepper.Step", "Alert", "Loader", "Progress", "RingProgress", "Skeleton", "Notification", "Modal", "Drawer", "ChatMessage", "ToolCall", "Thinking", "Artifact", "Email", "DataCard", "StateFlow", "Terminal", "Terminal.Command", "Terminal.Output", "Phone", "Avatar.Group", "Radio.Card", "EmptyState", "ListRow", "Stat", "KeyValue", "BarChart", "LineChart", "Menu", "Menu.Target", "Menu.Dropdown", "Menu.Label", "Menu.Divider", "div", "span", "p", "h1", "h2", "h3", "h4", "main", "section", "header", "footer", "nav", "aside", "ul", "ol", "li", "strong", "em", "small", "code", "Placeholder", "Button", "ActionIcon", "CloseButton", "Anchor", "a", "NavLink", "Burger", "TextInput", "PasswordInput", "NumberInput", "Textarea", "Select", "MultiSelect", "Checkbox", "Radio.Group", "Switch", "SegmentedControl", "FileInput", "Tabs", "Tabs.Tab", "Accordion.Control", "Pagination", "PromptInput", "Terminal.Input", "Artifact.Ref", "Menu.Item", "TabBar"];
+export type ComponentType = (typeof COMPONENT_TYPES)[number];
+export declare const INTERACTIVE_TYPES: ReadonlySet<string>;
+/** 可接收输入值；type/select/toggle 动作写入 state.inputs[nodeId]。 */
+export declare const VALUE_TYPES: ReadonlySet<string>;
+/**
+ * 只有 opened（兼容旧写法 open）为真时自身和子节点才可见的浮层。
+ * Menu.Dropdown（D68）：作者把 opened 写在 Menu 上（与 Mantine 一致），编译器把它抄到菜单里的 Menu.Dropdown 上。
+ */
+export declare const GATED_CONTAINERS: ReadonlySet<string>;
+/**
+ * 每个组件一行常用属性提示（`joplo skill components` 由此生成）。所有组件另外都接受：
+ * 样式属性 m/mt/mb/ml/mr/mx/my、p/pt/pb/pl/pr/px/py、w/h/miw/maw/mih/mah、c/bg/fz/fw/ta/ff/lh/opacity，
+ * 响应式写成 { base, xs, sm, md, lg, xl }；visibleFrom / hiddenFrom；以及 Joplo 属性 id/when/disabled/disabledReason/unmodeled/note。
+ */
+export declare const COMPONENT_DOCS: Record<ComponentType, string>;
+/**
+ * 示例（D68，`npx joplo components <名字>` 输出）：每个都能直接放进页面或层级里用；交互状态写成 $.ui / $.data 绑定，由步骤 set()。
+ * 只给最容易写错、或需要和步骤配合的组件；其余组件看 COMPONENT_DOCS 的一行提示就够。
+ */
+export declare const COMPONENT_EXAMPLES: Partial<Record<ComponentType, string>>;

package/dist/catalog.js

@@ -0,0 +1,255 @@
+/**
+ * 第一方 UI 组件目录（D35 / D87）：名称与属性对齐 Mantine（数据表对齐 mantine-datatable），另加少量 AI 交互组件、
+ * HTML 兜底标签和 Joplo 专用组件。复合组件用点语法：`<AppShell.Header>` 编译出的节点 type 是 'ui:AppShell.Header'。
+ *
+ * 目录是唯一来源：@joplo-app/plugin-ui 的导出、同包 runtime 的实现、COMPONENT_DOCS 都必须与 COMPONENT_TYPES 一致
+ * （packages/core/test/catalog.test.ts 与渲染器的类型检查保证）。目录之外的名称在编译时报错，不会被静默渲染。
+ * 只换词汇，不换渲染：运行时不引入 Mantine，仍由 Joplo 渲染成低保真风格。
+ */
+/** HTML 兜底标签（不可操作）；`a` 在 INTERACTIVE 里。目录之外的标签（br、img、button、input…）报 UNKNOWN_COMPONENT。 */
+const HTML = ['div', 'span', 'p', 'h1', 'h2', 'h3', 'h4', 'main', 'section', 'header', 'footer', 'nav', 'aside', 'ul', 'ol', 'li', 'strong', 'em', 'small', 'code'];
+export const HTML_TAGS = [...HTML, 'a'];
+/** 布局、展示与容器：不可操作。 */
+const STRUCTURE = [
+    // 布局
+    'AppShell', 'AppShell.Header', 'AppShell.Navbar', 'AppShell.Main', 'AppShell.Aside', 'AppShell.Footer',
+    'Container', 'Stack', 'Group', 'Flex', 'Grid', 'Grid.Col', 'SimpleGrid', 'Center', 'Box', 'Space',
+    'Paper', 'Card', 'Card.Section', 'Divider', 'ScrollArea',
+    // 文字与展示
+    'Title', 'Text', 'Code', 'Kbd', 'Blockquote', 'List', 'List.Item', 'Badge', 'Avatar', 'Image', 'ThemeIcon', 'Indicator',
+    'Timeline', 'Timeline.Item',
+    'Table', 'Table.Thead', 'Table.Tbody', 'Table.Tr', 'Table.Th', 'Table.Td', 'DataTable',
+    'Accordion', 'Accordion.Item', 'Accordion.Panel',
+    'Radio',
+    // 导航
+    'Tabs.List', 'Tabs.Panel', 'Breadcrumbs', 'Stepper', 'Stepper.Step',
+    // 反馈与浮层
+    'Alert', 'Loader', 'Progress', 'RingProgress', 'Skeleton', 'Notification', 'Modal', 'Drawer',
+    // AI 交互（Joplo 自有）
+    'ChatMessage', 'ToolCall', 'Thinking', 'Artifact', 'Email', 'DataCard', 'StateFlow',
+    // 设备外框（Joplo 自有）：终端与手机
+    'Terminal', 'Terminal.Command', 'Terminal.Output', 'Phone',
+    // 产品界面（D68）：官网示例里反复手拼的常见界面，名字能对齐 Mantine 的就对齐（Menu、Avatar.Group、Radio.Card、BarChart、LineChart）
+    'Avatar.Group', 'Radio.Card', 'EmptyState', 'ListRow', 'Stat', 'KeyValue', 'BarChart', 'LineChart',
+    'Menu', 'Menu.Target', 'Menu.Dropdown', 'Menu.Label', 'Menu.Divider',
+    // HTML 兜底
+    ...HTML,
+    // Joplo
+    'Placeholder', // props: label, h —— 图片/图表等占位
+];
+/** 看起来可操作：必须有演示行为、明确禁用并说明原因，或标记 unmodeled。 */
+const INTERACTIVE = [
+    'Button', 'ActionIcon', 'CloseButton', 'Anchor', 'a', 'NavLink', 'Burger',
+    'TextInput', 'PasswordInput', 'NumberInput', 'Textarea', 'Select', 'MultiSelect', 'Checkbox', 'Radio.Group', 'Switch',
+    'SegmentedControl', 'FileInput', 'Tabs', 'Tabs.Tab', 'Accordion.Control', 'Pagination', 'PromptInput', 'Terminal.Input',
+    'Artifact.Ref',
+    // 产品界面（D68）
+    'Menu.Item', 'TabBar',
+];
+export const COMPONENT_TYPES = [...STRUCTURE, ...INTERACTIVE];
+export const INTERACTIVE_TYPES = new Set(INTERACTIVE);
+/** 可接收输入值；type/select/toggle 动作写入 state.inputs[nodeId]。 */
+export const VALUE_TYPES = new Set([
+    'TextInput', 'PasswordInput', 'NumberInput', 'Textarea', 'Select', 'MultiSelect', 'Checkbox', 'Radio.Group', 'Switch',
+    'SegmentedControl', 'FileInput', 'Tabs', 'Accordion', 'Pagination', 'PromptInput', 'Terminal.Input', 'TabBar',
+]);
+/**
+ * 只有 opened（兼容旧写法 open）为真时自身和子节点才可见的浮层。
+ * Menu.Dropdown（D68）：作者把 opened 写在 Menu 上（与 Mantine 一致），编译器把它抄到菜单里的 Menu.Dropdown 上。
+ */
+export const GATED_CONTAINERS = new Set(['Modal', 'Drawer', 'Menu.Dropdown']);
+/**
+ * 每个组件一行常用属性提示（`joplo skill components` 由此生成）。所有组件另外都接受：
+ * 样式属性 m/mt/mb/ml/mr/mx/my、p/pt/pb/pl/pr/px/py、w/h/miw/maw/mih/mah、c/bg/fz/fw/ta/ff/lh/opacity，
+ * 响应式写成 { base, xs, sm, md, lg, xl }；visibleFrom / hiddenFrom；以及 Joplo 属性 id/when/disabled/disabledReason/unmodeled/note。
+ */
+export const COMPONENT_DOCS = {
+    AppShell: 'header={{ height }}, navbar={{ width, breakpoint, collapsed: { mobile, desktop } }}, aside={{ width, breakpoint, collapsed }}, footer={{ height }}, padding; navigation collapses below breakpoint and shows Burger',
+    'AppShell.Header': 'Header; p, px',
+    'AppShell.Navbar': 'Navigation sidebar; p; contains NavLink',
+    'AppShell.Main': 'Main content; contains <Outlet />',
+    'AppShell.Aside': 'Right sidebar; p',
+    'AppShell.Footer': 'Footer; p',
+    Container: 'size: xs|sm|md|lg|xl|number (default md), fluid',
+    Stack: 'gap (default md), align, justify; vertical layout',
+    Group: 'gap (default md), justify, align (default center), wrap, grow; horizontal layout',
+    Flex: 'direction, gap, rowGap, columnGap, align, justify, wrap; all responsive',
+    Grid: 'columns (default 12), gutter, justify, align, grow; Grid.Col children',
+    'Grid.Col': 'span: number|"auto"|"content"|{ base, md }, offset',
+    SimpleGrid: 'cols={{ base: 1, md: 3 }}, spacing, verticalSpacing',
+    Center: 'inline; centers content',
+    Box: 'Generic container; style props only',
+    Space: 'h, w; blank space',
+    Paper: 'p, withBorder, shadow, radius',
+    Card: 'padding (default md), withBorder, shadow, radius; Card.Section for edge-to-edge sections',
+    'Card.Section': 'withBorder, inheritPadding',
+    Divider: 'label, labelPosition: left|center|right, orientation, my',
+    ScrollArea: 'h, mah',
+    Title: 'order: 1-6; text in children',
+    Text: 'size: xs|sm|md|lg|xl, c: dimmed|red|green|…, fw, ta, truncate, lineClamp, span; preserves newlines',
+    Code: 'block (multiline code block), color',
+    Kbd: 'Keyboard key',
+    Blockquote: 'cite, color',
+    List: 'type: ordered|unordered, spacing; List.Item children',
+    'List.Item': 'List item',
+    Badge: 'color, variant: filled|light|outline|dot|default, size',
+    Avatar: 'name (shows first character), src, color, radius, size',
+    Image: 'src={asset("./photo.jpg")} (embeds a project image), alt, h, w, radius, fit: cover|contain (default cover), position (e.g. "center 20%"); other src values draw a placeholder with alt',
+    ThemeIcon: 'color, variant, size, radius; one character as child',
+    Indicator: 'label, color, disabled (hides the badge; can be a condition), processing; wraps one element with a corner badge',
+    Timeline: 'active (completed item index), bulletSize; Timeline.Item children',
+    'Timeline.Item': 'title, bullet; description in children',
+    Table: 'data={{ head: [...], body: [[...]] }} or Table.Thead/Tbody/Tr/Th/Td; striped, withTableBorder',
+    'Table.Thead': 'Table head',
+    'Table.Tbody': 'Table body',
+    'Table.Tr': 'Row',
+    'Table.Th': 'Header cell',
+    'Table.Td': 'Cell',
+    DataTable: 'records (can bind $.data.x), columns: [{ accessor, title, textAlign, width, sortable, badge: true | { value: color }, avatar: true }], sortStatus: { columnAccessor, direction: asc|desc } (arrow only; set sorted records yourself), selectedRecords (ids, checkbox column), idAccessor (default id), fetching (loading overlay), noRecordsText; matches mantine-datatable',
+    Accordion: 'value / defaultValue (expanded item); select sets the expanded item; Accordion.Item children',
+    'Accordion.Item': 'value; contains Accordion.Control and Accordion.Panel',
+    'Accordion.Panel': 'Content shown when expanded',
+    Radio: 'value, label; place inside Radio.Group',
+    'Tabs.List': 'Tab bar; contains Tabs.Tab',
+    'Tabs.Panel': 'value; current tab content',
+    Breadcrumbs: 'separator; Anchor or text children',
+    Stepper: 'active (zero-based); Stepper.Step children',
+    'Stepper.Step': 'label, description; step content in children (only current step shown)',
+    Alert: 'title, color (default blue), variant, icon (character), withCloseButton; description in children',
+    Loader: 'size, color, type; optional child text',
+    Progress: 'value 0-100, color, size, striped',
+    RingProgress: 'sections: [{ value, color }], label, size, thickness',
+    Skeleton: 'h, w, circle, radius, visible (false shows children), animate (pulse, default true)',
+    Notification: 'title, color, icon (character), loading, withCloseButton, position: top|top-left|top-right|bottom|bottom-left|bottom-right (floats over the page; show it with when); inline without position; Buttons in children (e.g. Undo)',
+    Modal: 'opened (gated, usually opened={$.ui.open}), title, size, centered, fullScreen',
+    Drawer: 'opened (gated), title, position: left|right|top|bottom (default left), size',
+    ChatMessage: "from: 'user'|'assistant', name; message content in children (preserves newlines)",
+    ToolCall: "title, state: 'running'|'done'|'error'; call details in children",
+    Email: 'from, to, subject, time; simple email card, body in children; can contain Button',
+    DataCard: 'title, value (object or state binding), fields?: [{ key, label }]; lists all keys by default; rows changed this step show old value → new value',
+    StateFlow: 'value (current state binding), states: string[], labels?: { state: name }; earlier states are completed, current state highlighted',
+    Thinking: 'title (current thought; can bind $.ui.x), active (thinking: title pulses), duration (shows "Thought for …" when finished), opened (expands the process); thinking process in children',
+    Artifact: "title, kind: 'doc'|'code'|'sheet'|'web'|'image', status: 'generating'|'ready'|'error', version; Agent artifact side panel, content in children",
+    Terminal: 'title; terminal window (CLI prototype), Terminal.Command / Terminal.Output / Terminal.Input children; scrolls internally when content exceeds h or mah',
+    'Terminal.Command': 'prompt (default "$"); command text in children',
+    'Terminal.Output': "tone: 'plain'|'ok'|'warn'|'error' (default plain); output text in children (preserves newlines)",
+    Phone: 'scale (visual scale, default 1), h (screen height, default 844), landscape (turned sideways: content 772 × 358, notch on the left; use it for video-style or landscape mobile screens); phone frame, children laid out at mobile width 390 with breakpoints based on that width; viewport: "mobile" on a page adds it automatically; do not add Phone explicitly',
+    div: 'HTML fallback; prefer Box/Stack/Group',
+    span: 'HTML fallback; prefer Text span',
+    p: 'HTML fallback; prefer Text',
+    h1: 'HTML fallback; prefer Title order={1}',
+    h2: 'HTML fallback; prefer Title order={2}',
+    h3: 'HTML fallback; prefer Title order={3}',
+    h4: 'HTML fallback; prefer Title order={4}',
+    main: 'HTML fallback; prefer AppShell.Main',
+    section: 'HTML fallback; prefer Box',
+    header: 'HTML fallback; prefer AppShell.Header',
+    footer: 'HTML fallback; prefer AppShell.Footer',
+    nav: 'HTML fallback; prefer AppShell.Navbar',
+    aside: 'HTML fallback; prefer AppShell.Aside',
+    ul: 'HTML fallback; prefer List',
+    ol: 'HTML fallback; prefer List type="ordered"',
+    li: 'HTML fallback; prefer List.Item',
+    strong: 'HTML fallback; prefer Text fw={700} span',
+    em: 'HTML fallback; prefer Text fs="italic" span',
+    small: 'HTML fallback; prefer Text size="xs"',
+    code: 'HTML fallback; prefer Code',
+    'Avatar.Group': 'spacing (overlap, default sm); Avatar children shown as an overlapping stack',
+    'Radio.Card': 'value, label, description, leftSection (character); selectable card inside Radio.Group (select writes the group value)',
+    EmptyState: 'icon (character), title, description, withBorder, color; empty lists, 404 / expired / no-access pages, result pages; action Buttons in children',
+    ListRow: 'avatar (name) or icon (character), title, description, active, withBorder, color; list row with right-side content (Badge, Button, Text) in children; not clickable itself: use NavLink for a tappable row',
+    Stat: 'label, value, diff (e.g. "+12%", red when it starts with -), description, icon, color, progress (0-100); KPI card',
+    KeyValue: 'items: [{ label, value }] (values can bind $.data.x), total (bold last row), withDivider; order summary / details list',
+    BarChart: 'data: [{ month: "Jan", signups: 40 }] (can bind $.data.x), dataKey (x axis), series: [{ name, label?, color? }], h (default 220), unit, withLegend; low-fi bars, values animate when data changes',
+    LineChart: 'same props as BarChart; low-fi lines with points',
+    Menu: 'opened (usually opened={$.ui.menu}; dropdown shows only when true), position: bottom-start|bottom-end|top-start|top-end; Menu.Target + Menu.Dropdown children',
+    'Menu.Target': 'Wraps the trigger (ActionIcon or Button with its own id)',
+    'Menu.Dropdown': 'Menu items; visible only while the Menu is opened; floats above tables and cards',
+    'Menu.Label': 'Section label inside Menu.Dropdown',
+    'Menu.Divider': 'Divider inside Menu.Dropdown',
+    Placeholder: 'label, h; placeholder for images, charts, etc.',
+    Button: 'variant: filled|light|outline|subtle|default|white, color, size, fullWidth, loading, leftSection / rightSection (character)',
+    ActionIcon: "Icon button: aria-label (required as name), variant, color, size; one character child such as '+'",
+    CloseButton: 'aria-label, size',
+    Anchor: 'href is display-only; clicking never navigates; use go() in the step; c, underline',
+    a: 'HTML fallback; prefer Anchor',
+    NavLink: 'label, description, href (highlighted when equal to current route), active, leftSection / rightSection (character or short text); nested NavLink allowed',
+    Burger: 'opened, aria-label; narrow-screen navigation toggle, usually with hiddenFrom="sm"',
+    TextInput: 'label, placeholder, description, error, withAsterisk, type; type action writes the value',
+    PasswordInput: 'label, placeholder, description, error; type action writes the value, shown as dots',
+    NumberInput: 'label, placeholder, min, max, suffix, prefix; type action writes the value',
+    Textarea: 'label, placeholder, description, error, minRows, autosize; type action writes the value',
+    Select: 'label, data: string[] | { value, label }[], placeholder, description; select accepts value or label',
+    MultiSelect: 'label, data, placeholder; each select toggles one option',
+    Checkbox: 'label, description, checked; toggle action writes the value',
+    'Radio.Group': 'label, value; Radio value/label children; select accepts value or label',
+    Switch: 'label, description, checked; toggle action writes the value',
+    SegmentedControl: 'data: string[] | { value, label }[], fullWidth; select accepts value or label',
+    FileInput: 'label, placeholder, accept; type action writes the filename',
+    Tabs: 'value / defaultValue; Tabs.Tab inside Tabs.List, content in Tabs.Panel; select switches tabs',
+    'Tabs.Tab': 'value, leftSection (character), rightSection (count or short text, e.g. 3)',
+    'Accordion.Control': 'Clickable heading (requires id)',
+    Pagination: 'total, value / defaultValue; select action writes the page number',
+    PromptInput: 'placeholder, value; native multiline AI input, type action writes the value; audience edits are disposable exploration; use ActionIcon or Button to send',
+    'Artifact.Ref': "title, kind, status; card linking to an artifact in the conversation (requires id; clickable)",
+    'Terminal.Input': 'prompt (default "$"), placeholder; terminal input line (requires id), type action writes the value',
+    'Menu.Item': 'leftSection (character), rightSection (text), color (red for destructive); clickable menu row (requires id)',
+    TabBar: 'data: string[] | [{ value, label, icon?, badge? }], value / defaultValue, aria-label; mobile bottom tab bar, select switches tabs; place it last in a full-height Stack',
+};
+/**
+ * 示例（D68，`npx joplo components <名字>` 输出）：每个都能直接放进页面或层级里用；交互状态写成 $.ui / $.data 绑定，由步骤 set()。
+ * 只给最容易写错、或需要和步骤配合的组件；其余组件看 COMPONENT_DOCS 的一行提示就够。
+ */
+export const COMPONENT_EXAMPLES = {
+    EmptyState: `<EmptyState icon="✉" title="No members yet" description="Invite teammates to start working together">
+  <Button id="invite_first">Invite members</Button>
+</EmptyState>`,
+    ListRow: `<Stack gap={0}>
+  <ListRow avatar="Ana Lee" title="Ana Lee" description="ana@example.com"><Badge color="green" variant="light">Admin</Badge></ListRow>
+  <ListRow avatar="Bo Chen" title="Bo Chen" description={$.ui.boStatus} active={$.ui.boNew}><Button id="resend" variant="subtle">Resend</Button></ListRow>
+</Stack>`,
+    Menu: `<Menu opened={$.ui.rowMenu} position="bottom-end">
+  <Menu.Target><ActionIcon id="row_more" aria-label="More actions">⋯</ActionIcon></Menu.Target>
+  <Menu.Dropdown>
+    <Menu.Item id="copy_link" leftSection="🔗">Copy invite link</Menu.Item>
+    <Menu.Divider />
+    <Menu.Item id="revoke" color="red" leftSection="✕">Revoke invite</Menu.Item>
+  </Menu.Dropdown>
+</Menu>
+// steps: .click('row_more', set($.ui.rowMenu, true)).click('revoke', set($.ui.rowMenu, false), set($.ui.confirm, true))`,
+    TabBar: `<Stack h="100%" gap={0}>
+  <ScrollArea style={{ flex: 1, minHeight: 0 }}>…page…</ScrollArea>
+  <TabBar id="tabs" aria-label="Bottom navigation" data={[{ value: 'home', label: 'Home', icon: '⌂' }, { value: 'trips', label: 'Trips', icon: '⛺', badge: 2 }, { value: 'me', label: 'Me', icon: '☺' }]} />
+</Stack>
+// steps: .select('tabs', 'trips', go('/trips'))`,
+    Stat: `<SimpleGrid cols={3}>
+  <Stat label="Signups this week" value={$.data.signups} diff="+12%" icon="↗" />
+  <Stat label="Seats used" value="8 / 10" progress={80} description="2 seats left" />
+  <Stat label="Failed payments" value="3" diff="-2" color="red" />
+</SimpleGrid>`,
+    KeyValue: `<KeyValue withDivider total items={[{ label: 'Seats', value: '5 × $9' }, { label: 'Tax', value: '$4.50' }, { label: 'Total', value: $.data.total }]} />`,
+    Image: `<Image src={asset('../../assets/capitol.jpg')} alt="U.S. Capitol" h={240} fit="cover" position="center 40%" radius="md" />
+// import { asset } from '@joplo-app/kit'; the path is relative to this file. jpg/png/gif/webp/avif/svg, up to 2 MB each; compress first.
+// The image is embedded, so the board, build and share show it offline. For a tinted or full-bleed background, use style={{ backgroundImage: \`url(\${asset('./bg.jpg')})\` }}.`,
+    BarChart: `<BarChart h={220} dataKey="week" unit="" data={$.data.weeks} series={[{ name: 'signups', label: 'Signups' }, { name: 'churn', label: 'Churn', color: 'red' }]} />
+// state: data: { weeks: [{ week: 'W1', signups: 40, churn: 4 }, { week: 'W2', signups: 52, churn: 6 }] }; set() a new array to animate`,
+    LineChart: `<LineChart h={200} dataKey="day" data={[{ day: 'Mon', p95: 320 }, { day: 'Tue', p95: 280 }]} series={[{ name: 'p95', label: 'p95 latency' }]} unit="ms" />`,
+    DataTable: `<DataTable idAccessor="id" records={$.data.members} selectedRecords={$.ui.selected} fetching={$.ui.loading}
+  sortStatus={{ columnAccessor: 'joined', direction: 'desc' }}
+  columns={[{ accessor: 'name', title: 'Name', avatar: true }, { accessor: 'status', title: 'Status', badge: { Active: 'green', Pending: 'yellow', Expired: 'gray' } }, { accessor: 'joined', title: 'Joined', sortable: true }]} />`,
+    Notification: `<Notification when={$.ui.deleted} position="bottom" title="Invite revoked" icon="↺" withCloseButton={false}>
+  <Group justify="space-between">Ana can no longer join<Button id="undo" variant="subtle" size="xs">Undo</Button></Group>
+</Notification>`,
+    'Radio.Card': `<Radio.Group id="plan" label="Plan">
+  <Stack gap="xs">
+    <Radio.Card value="team" label="Team" description="Up to 10 seats" leftSection="👥" />
+    <Radio.Card value="pro" label="Pro" description="Unlimited seats" leftSection="★" />
+  </Stack>
+</Radio.Group>
+// steps: .select('plan', 'pro')`,
+    'Avatar.Group': `<Avatar.Group><Avatar name="Ana Lee" /><Avatar name="Bo Chen" /><Avatar name="+3" /></Avatar.Group>`,
+    Modal: `<Modal id="confirm" opened={$.ui.confirm} title="Revoke this invite?" size="sm">
+  <Text>Ana's link stops working right away. You can invite her again later.</Text>
+  <Group justify="flex-end"><Button id="cancel_revoke" variant="default">Cancel</Button><Button id="do_revoke" color="red">Revoke</Button></Group>
+</Modal>`,
+};

package/dist/components.d.ts

@@ -0,0 +1,150 @@
+import type { JoploProps } from '@joplo-app/kit/plugin';
+export declare const AppShell: ((props: JoploProps) => any) & {
+    Header: (props: JoploProps) => any;
+    Navbar: (props: JoploProps) => any;
+    Main: (props: JoploProps) => any;
+    Aside: (props: JoploProps) => any;
+    Footer: (props: JoploProps) => any;
+};
+export declare const Container: (props: JoploProps) => any;
+export declare const Stack: (props: JoploProps) => any;
+export declare const Group: (props: JoploProps) => any;
+export declare const Flex: (props: JoploProps) => any;
+export declare const Grid: ((props: JoploProps) => any) & {
+    Col: (props: JoploProps) => any;
+};
+export declare const SimpleGrid: (props: JoploProps) => any;
+export declare const Center: (props: JoploProps) => any;
+export declare const Box: (props: JoploProps) => any;
+export declare const Space: (props: JoploProps) => any;
+export declare const Paper: (props: JoploProps) => any;
+export declare const Card: ((props: JoploProps) => any) & {
+    Section: (props: JoploProps) => any;
+};
+export declare const Divider: (props: JoploProps) => any;
+export declare const ScrollArea: (props: JoploProps) => any;
+export declare const Title: (props: JoploProps) => any;
+export declare const Text: (props: JoploProps) => any;
+export declare const Code: (props: JoploProps) => any;
+export declare const Kbd: (props: JoploProps) => any;
+export declare const Blockquote: (props: JoploProps) => any;
+export declare const List: ((props: JoploProps) => any) & {
+    Item: (props: JoploProps) => any;
+};
+export declare const Badge: (props: JoploProps) => any;
+export declare const Avatar: ((props: JoploProps) => any) & {
+    Group: (props: JoploProps) => any;
+};
+export declare const Image: (props: JoploProps) => any;
+export declare const ThemeIcon: (props: JoploProps) => any;
+export declare const Indicator: (props: JoploProps) => any;
+export declare const Timeline: ((props: JoploProps) => any) & {
+    Item: (props: JoploProps) => any;
+};
+export declare const Table: ((props: JoploProps) => any) & {
+    Thead: (props: JoploProps) => any;
+    Tbody: (props: JoploProps) => any;
+    Tr: (props: JoploProps) => any;
+    Th: (props: JoploProps) => any;
+    Td: (props: JoploProps) => any;
+};
+export declare const DataTable: (props: JoploProps) => any;
+export declare const Accordion: ((props: JoploProps) => any) & {
+    Item: (props: JoploProps) => any;
+    Control: (props: JoploProps) => any;
+    Panel: (props: JoploProps) => any;
+};
+export declare const Button: (props: JoploProps) => any;
+export declare const ActionIcon: (props: JoploProps) => any;
+export declare const CloseButton: (props: JoploProps) => any;
+export declare const TextInput: (props: JoploProps) => any;
+export declare const PasswordInput: (props: JoploProps) => any;
+export declare const NumberInput: (props: JoploProps) => any;
+export declare const Textarea: (props: JoploProps) => any;
+export declare const Select: (props: JoploProps) => any;
+export declare const MultiSelect: (props: JoploProps) => any;
+export declare const Checkbox: (props: JoploProps) => any;
+export declare const Radio: ((props: JoploProps) => any) & {
+    Group: (props: JoploProps) => any;
+    Card: (props: JoploProps) => any;
+};
+export declare const Switch: (props: JoploProps) => any;
+export declare const SegmentedControl: (props: JoploProps) => any;
+export declare const FileInput: (props: JoploProps) => any;
+export declare const Anchor: (props: JoploProps) => any;
+export declare const NavLink: (props: JoploProps) => any;
+export declare const Tabs: ((props: JoploProps) => any) & {
+    List: (props: JoploProps) => any;
+    Tab: (props: JoploProps) => any;
+    Panel: (props: JoploProps) => any;
+};
+export declare const Breadcrumbs: (props: JoploProps) => any;
+export declare const Pagination: (props: JoploProps) => any;
+export declare const Stepper: ((props: JoploProps) => any) & {
+    Step: (props: JoploProps) => any;
+};
+export declare const Burger: (props: JoploProps) => any;
+export declare const Alert: (props: JoploProps) => any;
+export declare const Loader: (props: JoploProps) => any;
+export declare const Progress: (props: JoploProps) => any;
+export declare const RingProgress: (props: JoploProps) => any;
+export declare const Skeleton: (props: JoploProps) => any;
+export declare const Notification: (props: JoploProps) => any;
+/** 简单邮件卡片，正文可放 Button。 */
+export declare const Email: (props: JoploProps) => any;
+/** 键值记录；fields 缺省时展示 value 的全部键，绑定的变化行显示前后对比。 */
+export declare const DataCard: (props: JoploProps) => any;
+/** 按 states 顺序展示完成/当前/待完成状态，labels 可替换显示文字。 */
+export declare const StateFlow: (props: JoploProps) => any;
+export declare const Modal: (props: JoploProps) => any;
+export declare const Drawer: (props: JoploProps) => any;
+export declare const ChatMessage: (props: JoploProps) => any;
+export declare const ToolCall: (props: JoploProps) => any;
+export declare const PromptInput: (props: JoploProps) => any;
+/**
+ * 思考过程（D56）：`<Thinking title={$.ui.thought} active={$.ui.thinking} duration="8 秒" opened>…</Thinking>`。
+ * title 是此刻在想什么（随步骤 set 变化）；active 时标题闪动；结束后显示“思考了 {duration}”；opened 时展开子节点里的过程。
+ */
+export declare const Thinking: (props: JoploProps) => any;
+/**
+ * Agent 的侧边产物（D56）：`<Artifact title="露营行程.md" kind="doc" status={$.ui.planStatus} version="v2">…</Artifact>`，
+ * 子节点是产物内容（Text / List / Table / Code 等，文字可以用 stream 逐字生成）。
+ * 对话里引用它用 `<Artifact.Ref id="open_plan" title="露营行程" kind="doc" />`（可点击）。
+ */
+export declare const Artifact: ((props: JoploProps) => any) & {
+    Ref: (props: JoploProps) => any;
+};
+/** 终端窗口：`<Terminal title="~/work"><Terminal.Command>npx joplo skill</Terminal.Command><Terminal.Output tone="ok">…</Terminal.Output></Terminal>`。 */
+export declare const Terminal: ((props: JoploProps) => any) & {
+    Command: (props: JoploProps) => any;
+    Output: (props: JoploProps) => any;
+    Input: (props: JoploProps) => any;
+};
+/** 手机外框：子节点按手机宽度排版。页面写 viewport: 'mobile' 时舞台会自动套上，不用写它。 */
+export declare const Phone: (props: JoploProps) => any;
+/** 空状态 / 结果页：`<EmptyState icon="✉" title="还没有成员" description="邀请同事一起协作"><Button id="invite">邀请成员</Button></EmptyState>`。 */
+export declare const EmptyState: (props: JoploProps) => any;
+/** 列表行：`<ListRow avatar="阿杰" title="阿杰" description="已确认"><Badge>成员</Badge></ListRow>`；右侧内容放在子节点里。 */
+export declare const ListRow: (props: JoploProps) => any;
+/** 指标卡：`<Stat label="本月注册" value={$.data.signups} diff="+12%" />`。 */
+export declare const Stat: (props: JoploProps) => any;
+/** 键值清单：`<KeyValue items={[{ label: '席位', value: '5 个' }, { label: '合计', value: '¥ 450' }]} total />`。 */
+export declare const KeyValue: (props: JoploProps) => any;
+/** 低保真图表（对齐 @mantine/charts）：`<BarChart data={$.data.weeks} dataKey="week" series={[{ name: 'signups', label: '注册' }]} />`。 */
+export declare const BarChart: (props: JoploProps) => any;
+export declare const LineChart: (props: JoploProps) => any;
+/**
+ * 菜单（对齐 Mantine）：opened 写在 Menu 上，下拉只在为真时出现。
+ * `<Menu opened={$.ui.rowMenu}><Menu.Target><ActionIcon id="row_more" aria-label="更多">⋯</ActionIcon></Menu.Target>
+ *  <Menu.Dropdown><Menu.Item id="revoke" color="red">撤销邀请</Menu.Item></Menu.Dropdown></Menu>`
+ */
+export declare const Menu: ((props: JoploProps) => any) & {
+    Target: (props: JoploProps) => any;
+    Dropdown: (props: JoploProps) => any;
+    Item: (props: JoploProps) => any;
+    Label: (props: JoploProps) => any;
+    Divider: (props: JoploProps) => any;
+};
+/** 手机底部标签栏：`<TabBar id="tabs" aria-label="底部导航" value={$.ui.tab} data={[{ value: 'home', label: '首页', icon: '⌂' }]} />`，select 切换。 */
+export declare const TabBar: (props: JoploProps) => any;
+export declare const Placeholder: (props: JoploProps) => any;