xiaohao-components 0.0.0-stage → 0.1.0

package/dist/lib/cn.d.ts

@@ -0,0 +1,3 @@
+import { ClassValue } from 'clsx';
+/** 包内唯一类名合并工具（只搬 cn，业务工具留在宿主） */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/portal-context.d.ts

@@ -0,0 +1,7 @@
+import { ReactNode } from 'react';
+export declare function A2uiPortalProvider({ container, children, }: {
+    container: HTMLElement | null;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** 包内 Portal 挂载点；`null` 表示还没就绪（Portal 会挂到 body，通常只在首帧） */
+export declare function useA2uiPortalContainer(): HTMLElement | null;

package/dist/messages/a2ui-messages.d.ts

@@ -0,0 +1,65 @@
+import { ProcessableMessagePayload } from '@a2ui/web_core/v0_9';
+/** v0.9 消息必须带 `version`，缺了引擎按 v0.8 解析（形状完全不同，症状是"一条都渲不出来"） */
+export declare const A2UI_VERSION = "v0.9";
+/**
+ * 工具结果里的**指令键**（不是数据路径）：协同端用它下发「选项列表要换成这些」之类的
+ * 增量 `updateComponents`。§2.6 明确它**不参与**「路径必须出现在 outputSchema」的校验，
+ * 本端同理——它不能被当成 `/xxx` 塞进数据模型，否则会多出一个永远匹配不到组件的幽灵路径。
+ */
+export declare const A2UI_AUX_KEY = "_a2uiMessages";
+/** 一条 `updateDataModel` 消息的形状（只取本端构造时用到的字段） */
+export interface A2uiDataModelMessage {
+    version: typeof A2UI_VERSION;
+    updateDataModel: {
+        surfaceId: string;
+        path: string;
+        value: unknown;
+    };
+}
+/** 解析结果：surface 标识 + 原文消息（顺序已归位） */
+export interface A2uiCardMessages {
+    surfaceId: string;
+    /** createSurface → updateComponents → 其余（原文逐字保留，客户端不改字段） */
+    messages: ProcessableMessagePayload[];
+}
+/**
+ * 解析卡片 JSON 原文。
+ *
+ * **失败一律返回 `null`，不抛、不重试**（重试不会让坏 JSON 变好）。调用方据此退纯文本
+ * 并记 `card.a2ui.parse_failed`。
+ *
+ * 只做两件"结构上必须做"的事：
+ * 1. 取出 `messages` 数组——**逐字保留**消息体，不补 `version`、不改 `catalogId`
+ *    （发布端是唯一真相源，客户端擅自补字段会让"编辑端所见"与"运行时所得"分叉）；
+ * 2. 按投递顺序归位（§4.4）——数据后投是硬要求，组件先于数据是观感要求。
+ */
+export declare function parseA2uiCard(json: string | null | undefined): A2uiCardMessages | null;
+/**
+ * 把工具结果的 `structuredContent` 拍平成 `updateDataModel` 的路径条目。
+ *
+ * 服务端下发的键**已经是绝对路径**（`"/services"`、`"/formValid"`），如
+ * `cloud-platform/docs/demo/a2ui/fixtures/structured-content.samples.json`。
+ * 这里容忍不带前导 `/` 的写法（补上），因为手写工具时漏斜杠太常见了，
+ * 而漏了斜杠的症状是"数据在、卡是空的"，极难查。
+ *
+ * `_a2uiMessages` 走 `auxMessagesOf`，**不进数据模型**。
+ */
+export declare function toDataEntries(structuredContent: unknown): {
+    path: string;
+    value: unknown;
+}[];
+/** 取 `_a2uiMessages`（协同端下发的增量消息）；不是数组或为空时返回空数组 */
+export declare function auxMessagesOf(structuredContent: unknown): unknown[];
+/** 数据条目 → 一条条 `updateDataModel`（**一条一路径**，引擎不认批量） */
+export declare function buildDataModelMessages(surfaceId: string, entries: {
+    path: string;
+    value: unknown;
+}[]): A2uiDataModelMessage[];
+/**
+ * 提交结果写回时的冻结判据（§1.3「冻结条件」）：
+ * 工具回包里的 `/submitted === true` 或 `/formValid === false` ⇒ 整卡冻结。
+ *
+ * 用**回包数据**判而不是卡类型判：两条规则正好对应"表单已提交"与"表单已失效"，
+ * 而展示卡的按钮回包不会带这两个键（带了也说明它真的是表单卡）。
+ */
+export declare function shouldFreeze(structuredContent: unknown): boolean;

package/dist/messages/missing-paths.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 列出 json 里引用、但 data 没提供的路径（数据齐全返回 `[]`；json 坏返回 `[]`，
+ * 解析失败另有专门的兜底路径，这里不重复报）。
+ */
+export declare function collectMissingPaths(json: string, data: Record<string, unknown>): string[];

package/dist/messages/remote-options.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 远程选项：`options` 写成对象时的解析（对官方 v0.9 的扩展）。
+ *
+ * 官方 `ChoicePicker.options` 只能是静态数组 `[{label, value}]`，且输入组件没有
+ * `onChange`/`action` —— 「选中即调工具」表达不出来；工具想回灌选项只能发
+ * `_a2uiMessages` 用同一组件 id 整份替换，而**自动生成的卡拿不到组件 id**
+ * （协同端 `A2UI卡片平台化生成-流程方案.md` §5.6 的三条理由）。
+ *
+ * 故约定这张卡自己声明选项从哪来：
+ *
+ * ```json
+ * "options": { "source": "/services", "label": "name", "value": "id" }
+ * ```
+ *
+ * 工具仍然是纯数据（`"/services": [{"id":"svc_1","name":"订单服务"}]`），
+ * 由渲染层（本文件）在投递前解析成官方要求的静态数组。
+ *
+ * **这是对官方 schema 的协议偏离**：官方 `ChoicePickerApi.schema` 会判它不合法。
+ * 手机端已按同一口径实现（`xiaohao_mobile/lib/core/a2ui/catalog/remote_options.dart`，
+ * 回退链与本文件逐条对齐），改这里必须同时改那边。
+ */
+/** 卡里声明的远程选项（`options` 为对象而非数组） */
+export interface RemoteOptionsDescriptor {
+    /** 工具返回的数组在数据模型里的路径（协同端生成器只产绝对路径；相对路径按组件作用域解析） */
+    source: string;
+    /** 用元素里的哪个属性当显示名；缺省 `name` */
+    label?: string;
+    /** 用元素里的哪个属性当选中值；缺省 `id` */
+    value?: string;
+}
+/** 官方 `options` 的元素形状（渲染层只关心这两项） */
+export interface ChoiceOption {
+    label: string;
+    value: string;
+}
+/** 缺省取显示名的属性——与协同端生成器的注释、示例卡保持一致 */
+export declare const DEFAULT_LABEL_KEY = "name";
+/** 缺省取值的属性 */
+export declare const DEFAULT_VALUE_KEY = "id";
+/**
+ * 判断一个 `options` 是不是远程写法。
+ *
+ * 只认「非数组的对象且 `source` 是非空字符串」：静态数组、`undefined`、残缺对象
+ * 都走官方路径 —— 静态卡的行为一个字节都不能变。
+ */
+export declare function isRemoteOptions(value: unknown): value is RemoteOptionsDescriptor;
+/**
+ * 把 `source` 指向的数组解析成官方选项数组。
+ *
+ * 取值的回退链是**故意宽松**的（声明没写 → `name`/`id` → `label`/`value`）：
+ * 写卡的人少写一个 `label` 就整列空白，排查成本远高于多两条回退。但元素**没有值就跳过**——
+ * 选不了的选项不如不出现。
+ *
+ * 数据还没到（`undefined`）或不是数组 → 空数组，渲染成「暂无选项」。
+ */
+export declare function resolveRemoteOptions(data: unknown, descriptor: RemoteOptionsDescriptor): ChoiceOption[];

package/dist/text.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 工具结果的文本提取（纯函数副本，源自桌面 `store/card.ts`）。
+ *
+ * 包内只用于「JSON 解析失败退纯文本」的兜底文案；宿主可另行 import
+ * 同名函数避免两份实现。
+ */
+/** 包内认的最小形状（不引宿主的 zod 契约） */
+export interface A2uiToolResultLike {
+    content?: unknown;
+}
+/** 从工具结果提取纯文本兜底文案（content[] 里的 text 块拼接；空则 null） */
+export declare function extractToolResultText(toolResult: A2uiToolResultLike | null | undefined): string | null;

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import { ReactNode } from 'react';
+/**
+ * 渲染入参：只保留渲染所需，不引任何宿主的聊天域类型。
+ * （桌面 `CardData` → 本类型是 P2 的三行映射，见提案 §4.2。）
+ */
+export interface A2uiCardInput {
+    /** 动作幂等/日志用 */
+    cardInstanceId: string;
+    /** 服务端注册名（mcp__{pluginId}__{serverName}__{toolName}），用于按钮短名补前缀 */
+    tool: string;
+    /** A2UI v0.9 原文（发布端是唯一真相源，包不改写） */
+    json: string;
+    /** 工具结果里的数据（键是绝对路径，如 "/services"） */
+    structuredContent?: Record<string, unknown>;
+    /** 历史回看派生的「已提交」→ 直接冻结 */
+    submitted?: boolean;
+}
+/** 一次按钮动作（工具名已补全成注册名） */
+export interface A2uiActionRequest {
+    tool: string;
+    args: Record<string, unknown>;
+}
+/** 与 card-tool-calls 200 回包同形（五态 + result + submitted） */
+export interface A2uiActionOutcome {
+    outcome: "ok" | "rejected" | "denied" | "unavailable" | "retryable";
+    reason?: string;
+    result?: {
+        structuredContent?: Record<string, unknown>;
+        isError?: boolean;
+    };
+    submitted?: boolean;
+}
+export interface A2uiRendererProps {
+    card: A2uiCardInput;
+    /**
+     * 动作上行。**不传 = 预览模式**：按钮可点、只回调 `onPreviewAction`，
+     * 不进状态机、不写回、不冻结、不发请求——「预览不产生任何业务请求」
+     * 是结构保证，不靠调用方自觉。
+     */
+    onAction?: (req: A2uiActionRequest) => Promise<A2uiActionOutcome>;
+    /** 预览模式下的按钮点击回显 */
+    onPreviewAction?: (req: A2uiActionRequest) => void;
+    /** 宿主通知（原 toast）；缺省 no-op */
+    onNotify?: (n: {
+        level: "error" | "info";
+        message: string;
+    }) => void;
+    /** 宿主日志；缺省 no-op。只记事件名与上下文，不记正文 */
+    logger?: (event: string, ctx?: Record<string, string | number | boolean>) => void;
+    /** 渲染失败时的兜底内容；缺省纯文本节点 */
+    renderFallback?: (text: string) => ReactNode;
+    /** 深浅主题；`auto` 跟随 prefers-color-scheme（不依赖 next-themes） */
+    theme?: "light" | "dark" | "auto";
+    /** 追加到根节点（.xa2ui-root）的类名 */
+    className?: string;
+}

package/dist/ui/button.d.ts

@@ -0,0 +1,8 @@
+import { Button as ButtonPrimitive } from '@base-ui/react/button';
+import { VariantProps } from 'class-variance-authority';
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "outline" | "secondary" | "ghost" | "destructive" | "link" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function Button({ className, variant, size, ...props }: ButtonPrimitive.Props & VariantProps<typeof buttonVariants>): import("react").JSX.Element;
+export { Button, buttonVariants };

package/dist/ui/card.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+declare function Card({ className, size, ...props }: React.ComponentProps<"div"> & {
+    size?: "default" | "sm";
+}): React.JSX.Element;
+declare function CardHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardTitle({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardDescription({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardAction({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardContent({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function CardFooter({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent, };

package/dist/ui/checkbox.d.ts

@@ -0,0 +1,3 @@
+import { Checkbox as CheckboxPrimitive } from '@base-ui/react/checkbox';
+declare function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props): import("react").JSX.Element;
+export { Checkbox };

package/dist/ui/dialog.d.ts

@@ -0,0 +1,17 @@
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
+import * as React from "react";
+declare function Dialog({ ...props }: DialogPrimitive.Root.Props): React.JSX.Element;
+declare function DialogTrigger({ ...props }: DialogPrimitive.Trigger.Props): React.JSX.Element;
+declare function DialogPortal({ ...props }: DialogPrimitive.Portal.Props): React.JSX.Element;
+declare function DialogClose({ ...props }: DialogPrimitive.Close.Props): React.JSX.Element;
+declare function DialogOverlay({ className, ...props }: DialogPrimitive.Backdrop.Props): React.JSX.Element;
+declare function DialogContent({ className, children, showCloseButton, ...props }: DialogPrimitive.Popup.Props & {
+    showCloseButton?: boolean;
+}): React.JSX.Element;
+declare function DialogHeader({ className, ...props }: React.ComponentProps<"div">): React.JSX.Element;
+declare function DialogFooter({ className, showCloseButton, children, ...props }: React.ComponentProps<"div"> & {
+    showCloseButton?: boolean;
+}): React.JSX.Element;
+declare function DialogTitle({ className, ...props }: DialogPrimitive.Title.Props): React.JSX.Element;
+declare function DialogDescription({ className, ...props }: DialogPrimitive.Description.Props): React.JSX.Element;
+export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, };

package/dist/ui/input.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+declare function Input({ className, type, ...props }: React.ComponentProps<"input">): React.JSX.Element;
+export { Input };

package/dist/ui/label.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+declare function Label({ className, ...props }: React.ComponentProps<"label">): React.JSX.Element;
+export { Label };

package/dist/ui/select.d.ts

@@ -0,0 +1,15 @@
+import { Select as SelectPrimitive } from '@base-ui/react/select';
+import * as React from "react";
+declare const Select: typeof SelectPrimitive.Root;
+declare function SelectGroup({ className, ...props }: SelectPrimitive.Group.Props): React.JSX.Element;
+declare function SelectValue({ className, ...props }: SelectPrimitive.Value.Props): React.JSX.Element;
+declare function SelectTrigger({ className, size, children, ...props }: SelectPrimitive.Trigger.Props & {
+    size?: "sm" | "default";
+}): React.JSX.Element;
+declare function SelectContent({ className, children, side, sideOffset, align, alignOffset, alignItemWithTrigger, ...props }: SelectPrimitive.Popup.Props & Pick<SelectPrimitive.Positioner.Props, "align" | "alignOffset" | "side" | "sideOffset" | "alignItemWithTrigger">): React.JSX.Element;
+declare function SelectLabel({ className, ...props }: SelectPrimitive.GroupLabel.Props): React.JSX.Element;
+declare function SelectItem({ className, children, ...props }: SelectPrimitive.Item.Props): React.JSX.Element;
+declare function SelectSeparator({ className, ...props }: SelectPrimitive.Separator.Props): React.JSX.Element;
+declare function SelectScrollUpButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollUpArrow>): React.JSX.Element;
+declare function SelectScrollDownButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollDownArrow>): React.JSX.Element;
+export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, };

package/dist/ui/separator.d.ts

@@ -0,0 +1,3 @@
+import { Separator as SeparatorPrimitive } from '@base-ui/react/separator';
+declare function Separator({ className, orientation, ...props }: SeparatorPrimitive.Props): import("react").JSX.Element;
+export { Separator };

package/dist/ui/slider.d.ts

@@ -0,0 +1,3 @@
+import { Slider as SliderPrimitive } from '@base-ui/react/slider';
+declare function Slider({ className, defaultValue, value, min, max, ...props }: SliderPrimitive.Root.Props): import("react").JSX.Element;
+export { Slider };

package/dist/ui/tabs.d.ts

@@ -0,0 +1,10 @@
+import { Tabs as TabsPrimitive } from '@base-ui/react/tabs';
+import { VariantProps } from 'class-variance-authority';
+declare function Tabs({ className, orientation, ...props }: TabsPrimitive.Root.Props): import("react").JSX.Element;
+declare const tabsListVariants: (props?: ({
+    variant?: "default" | "line" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare function TabsList({ className, variant, ...props }: TabsPrimitive.List.Props & VariantProps<typeof tabsListVariants>): import("react").JSX.Element;
+declare function TabsTrigger({ className, ...props }: TabsPrimitive.Tab.Props): import("react").JSX.Element;
+declare function TabsContent({ className, ...props }: TabsPrimitive.Panel.Props): import("react").JSX.Element;
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants };

package/dist/ui/textarea.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+declare function Textarea({ className, ...props }: React.ComponentProps<"textarea">): React.JSX.Element;
+export { Textarea };

package/fixtures/index.d.ts

@@ -0,0 +1,16 @@
+/** 样例 JSON（A2UI v0.9 原文，字符串） */
+export declare const DISPLAY_SAMPLE_JSON: string;
+export declare const EDITABLE_SAMPLE_JSON: string;
+export declare const EDITABLE_SURFACE_ID: string;
+export declare const FORM_SAMPLE_JSON: string;
+export declare const MULTI_ACTION_SAMPLE_JSON: string;
+export declare const MULTI_ACTION_SURFACE_ID: string;
+export declare const TRACK_SAMPLE_JSON: string;
+export declare const TRACK_SURFACE_ID: string;
+/** 样例数据（键是绝对路径） */
+export declare const DISPLAY_SAMPLE_DATA: Record<string, unknown>;
+export declare const EDITABLE_SAMPLE_DATA: Record<string, unknown>;
+export declare const EDITABLE_UNIT_OPTIONS: Array<{ code: string; name: string }>;
+export declare const FORM_SAMPLE_DATA: Record<string, unknown>;
+export declare const MULTI_ACTION_SAMPLE_DATA: Record<string, unknown>;
+export declare const TRACK_SAMPLE_DATA: Record<string, unknown>;

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "xiaohao-components",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A2UI 卡片的 Web 渲染层：官方引擎装配 + 19 个组件映射 + 动作状态机（React 18/19）",
+  "keywords": [
+    "a2ui",
+    "renderer",
+    "react",
+    "shadcn",
+    "json-ui",
+    "generative-ui"
+  ],
+  "license": "MIT",
+  "author": "Hubei Yunzhimeng Technology Co., Ltd.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./fixtures": {
+      "types": "./fixtures/index.d.ts",
+      "import": "./dist/fixtures.js"
+    },
+    "./styles.css": "./dist/a2ui.css"
+  },
+  "files": [
+    "dist",
+    "fixtures/index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepack": "npm run build",
+    "build": "npm run build:js && npm run build:css && npm run check:bundle",
+    "build:js": "vite build",
+    "build:css": "vite build --config vite.styles.config.ts && node scripts/scope-css.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check:bundle": "node scripts/check-bundle.mjs",
+    "pack": "npm run build && npm pack",
+    "playground": "vite serve playground --config playground/vite.config.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@a2ui/react": "^0.14.0",
+    "@a2ui/web_core": "^0.14.0",
+    "@base-ui/react": "^1.6.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.25.0",
+    "tailwind-merge": "^3.6.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/node": "^26.6.6",
+    "@types/react": "^19.1.8",
+    "@types/react-dom": "^19.1.6",
+    "@vitejs/plugin-react": "^4.6.0",
+    "antd": "^5.26.0",
+    "jsdom": "^29.1.1",
+    "postcss": "^8.5.6",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "tailwindcss": "^4.3.3",
+    "vite": "^7.0.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.1.10"
+  }
+}