@qw-ui/core 0.1.0 → 0.2.0-next.0

package/dist/tabs/tabs.d.ts

@@ -0,0 +1,61 @@
+import type { Props as ZagTabsProps } from "@zag-js/tabs";
+/**
+ * Tabs 契约 — 原型 B（有状态），core 包裹 zag.js tabs machine。
+ * 行为 props 进 createTabsProps → zag context；视觉 props（level/variant/size）
+ * 不进 machine，由适配层挂 data-* 属性驱动 CSS。
+ *
+ * 枚举以运行时常量数组为唯一事实源（类型从常量推导），__test__ 直接锁死词表。
+ */
+/** 导航层级全集：primary 一级导航（默认）/ secondary 二级导航。 */
+export declare const TABS_LEVELS: readonly ["primary", "secondary"];
+export type TabsLevel = (typeof TABS_LEVELS)[number];
+/** 视觉形态全集：text 纯文本（默认）/ button 按钮。button 仅 secondary 支持。 */
+export declare const TABS_VARIANTS: readonly ["text", "button"];
+export type TabsVariant = (typeof TABS_VARIANTS)[number];
+/** 字号全集：仅 primary 生效，"14" / "16"（默认）。 */
+export declare const TABS_SIZES: readonly ["14", "16"];
+export type TabsSize = (typeof TABS_SIZES)[number];
+/**
+ * QwTabsProps — 双栈共享的行为 + 视觉契约。
+ * 行为 props（进 createTabsProps → zag machine）：
+ * - loop（默认 true）→ zag loopFocus；
+ * - value / defaultValue / activationMode 透传；
+ * - onValueChange 适配 zag details。
+ * 视觉 props（不进 machine，适配层挂 data-*）：
+ * - level / variant / size。
+ */
+export interface QwTabsProps {
+    /** 唯一 id 前缀；不传由适配层生成 (SSR/CSR 一致)。 */
+    id?: string;
+    /** 受控当前项。 */
+    value?: string | null;
+    /** 非受控初值。 */
+    defaultValue?: string | null;
+    /** 激活模式，默认 automatic（聚焦即激活）。 */
+    activationMode?: "manual" | "automatic";
+    /** 方向键首尾循环，默认 true (zag 原名 loopFocus)。 */
+    loop?: boolean;
+    /** 选中项变化回调；zag 原生 onValueChange。 */
+    onValueChange?: (e: {
+        value: string;
+    }) => void;
+    /** 导航层级，默认 primary。 */
+    level?: TabsLevel;
+    /** 视觉形态，默认 text。level=primary 时强制 text。 */
+    variant?: TabsVariant;
+    /** 字号，默认 "16"。仅 level=primary 生效。 */
+    size?: TabsSize;
+}
+/**
+ * 直接 re-export zag tabs 的 machine 与 connect —— 不包一层。
+ * 用 re-export 保留原始可移植类型 (避免 TS2742)。
+ */
+export { machine as tabsMachine, connect } from "@zag-js/tabs";
+/** rebrand zag 的 TabsApi 类型对外。 */
+export type { Api as QwTabsApi } from "@zag-js/tabs";
+/**
+ * 把 QwTabsProps 的行为 props 转成 zag tabs machine 的 props (默认值收口 + 命名 rebrand)。
+ * 视觉 props（level/variant/size）不出现在返回值中——它们是适配层 data-* 属性。
+ * 用法：`useMachine(tabsMachine, createTabsProps(props))`。
+ */
+export declare function createTabsProps(props?: QwTabsProps): Partial<ZagTabsProps>;

package/dist/toast/index.d.ts

@@ -0,0 +1 @@
+export * from "./toast.js";

package/dist/toast/index.js

@@ -0,0 +1,44 @@
+//#region src/toast/toast.ts
+/**
+* @qw-ui/core · Toast 契约（原型 D · 自研命令式单例）
+* ─────────────────────────────────────────────────────────────
+* 纯 TS / SSR-safe，零框架依赖。只收口「框架无关的选项契约 + 纯函数」：
+* 交互（命令式挂载 / 计时 / 渲染）落在各框架适配层，节点类型（icon/content）
+* 由适配层用 `ReactNode` / `VNode` 具体化 `QwToastOptions<Node>`。
+*/
+/** 垂直显示位置。 */
+const TOAST_POSITIONS = [
+	"top",
+	"bottom",
+	"center"
+];
+/** 内建状态图标类型。 */
+const TOAST_ICON_TYPES = [
+	"success",
+	"fail",
+	"loading"
+];
+/** 逻辑部件（承载 data-part 样式与 parity 指纹）。 */
+const TOAST_PARTS = [
+	"mask",
+	"wrap",
+	"body",
+	"icon",
+	"content"
+];
+/** 默认展示时长（ms）。 */
+const DEFAULT_TOAST_DURATION = 3e3;
+/** 默认垂直位置（对齐设计稿：默认顶部）。 */
+const DEFAULT_TOAST_POSITION = "top";
+/** 判断 icon 是否为内建状态图标类型。 */
+function isToastIconType(icon) {
+	return typeof icon === "string" && TOAST_ICON_TYPES.includes(icon);
+}
+/** 解析持续时间：未传用默认 3000；显式 0 透传（不自动关闭）。 */
+function resolveToastDuration(duration) {
+	return duration == null ? DEFAULT_TOAST_DURATION : duration;
+}
+//#endregion
+export { DEFAULT_TOAST_DURATION, DEFAULT_TOAST_POSITION, TOAST_ICON_TYPES, TOAST_PARTS, TOAST_POSITIONS, isToastIconType, resolveToastDuration };
+
+//# sourceMappingURL=index.js.map

package/dist/toast/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/toast/toast.ts"],"sourcesContent":["/**\n * @qw-ui/core · Toast 契约（原型 D · 自研命令式单例）\n * ─────────────────────────────────────────────────────────────\n * 纯 TS / SSR-safe，零框架依赖。只收口「框架无关的选项契约 + 纯函数」：\n * 交互（命令式挂载 / 计时 / 渲染）落在各框架适配层，节点类型（icon/content）\n * 由适配层用 `ReactNode` / `VNode` 具体化 `QwToastOptions<Node>`。\n */\n\n/** 垂直显示位置。 */\nexport const TOAST_POSITIONS = [\"top\", \"bottom\", \"center\"] as const;\nexport type QwToastPosition = (typeof TOAST_POSITIONS)[number];\n\n/** 内建状态图标类型。 */\nexport const TOAST_ICON_TYPES = [\"success\", \"fail\", \"loading\"] as const;\nexport type QwToastIconType = (typeof TOAST_ICON_TYPES)[number];\n\n/** 逻辑部件（承载 data-part 样式与 parity 指纹）。 */\nexport const TOAST_PARTS = [\"mask\", \"wrap\", \"body\", \"icon\", \"content\"] as const;\nexport type QwToastPart = (typeof TOAST_PARTS)[number];\n\n/** 默认展示时长（ms）。 */\nexport const DEFAULT_TOAST_DURATION = 3000;\n\n/** 默认垂直位置（对齐设计稿：默认顶部）。 */\nexport const DEFAULT_TOAST_POSITION: QwToastPosition = \"top\";\n\n/**\n * Toast 选项契约。`Node` / `Style` 由适配层具体化\n * （React `ReactNode` / `CSSProperties`；Vue `VNode` / `StyleValue`）。\n * 与 antd-mobile 风格对齐：命令式 `Toast.show(options)`。\n */\nexport interface QwToastOptions<Node = unknown, Style = unknown> {\n  /** 提示主文案。可空（纯图标提示）。 */\n  content?: Node;\n  /** 前置图标：内建类型 `success | fail | loading`，或任意自定义节点；不传则不展示图标。 */\n  icon?: QwToastIconType | Node;\n  /** 持续时间（ms），默认 3000；为 0 时不自动关闭。 */\n  duration?: number;\n  /** 垂直显示位置，默认 top。 */\n  position?: QwToastPosition;\n  /** 自定义遮罩层内联样式。 */\n  maskStyle?: Style;\n  /** 自定义遮罩层 class。 */\n  maskClassName?: string;\n  /** 关闭后回调（自动消失或手动 clear 均触发）。 */\n  afterClose?: () => void;\n}\n\n/** 命令式 Toast 单例接口（各框架适配层实现同名同义）。 */\nexport interface QwToast<Node = unknown, Style = unknown> {\n  /** 展示一条提示（替换上一条）。 */\n  show: (options?: QwToastOptions<Node, Style>) => void;\n  /** 立即收起当前提示。 */\n  clear: () => void;\n}\n\n/** 判断 icon 是否为内建状态图标类型。 */\nexport function isToastIconType(icon: unknown): icon is QwToastIconType {\n  return typeof icon === \"string\" && (TOAST_ICON_TYPES as readonly string[]).includes(icon);\n}\n\n/** 解析持续时间：未传用默认 3000；显式 0 透传（不自动关闭）。 */\nexport function resolveToastDuration(duration?: number): number {\n  return duration == null ? DEFAULT_TOAST_DURATION : duration;\n}\n"],"mappings":";;;;;;;;;AASA,MAAa,kBAAkB;CAAC;CAAO;CAAU;AAAQ;;AAIzD,MAAa,mBAAmB;CAAC;CAAW;CAAQ;AAAS;;AAI7D,MAAa,cAAc;CAAC;CAAQ;CAAQ;CAAQ;CAAQ;AAAS;;AAIrE,MAAa,yBAAyB;;AAGtC,MAAa,yBAA0C;;AAiCvD,SAAgB,gBAAgB,MAAwC;CACtE,OAAO,OAAO,SAAS,YAAa,iBAAuC,SAAS,IAAI;AAC1F;;AAGA,SAAgB,qBAAqB,UAA2B;CAC9D,OAAO,YAAY,OAAO,yBAAyB;AACrD"}

package/dist/toast/toast.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @qw-ui/core · Toast 契约（原型 D · 自研命令式单例）
+ * ─────────────────────────────────────────────────────────────
+ * 纯 TS / SSR-safe，零框架依赖。只收口「框架无关的选项契约 + 纯函数」：
+ * 交互（命令式挂载 / 计时 / 渲染）落在各框架适配层，节点类型（icon/content）
+ * 由适配层用 `ReactNode` / `VNode` 具体化 `QwToastOptions<Node>`。
+ */
+/** 垂直显示位置。 */
+export declare const TOAST_POSITIONS: readonly ["top", "bottom", "center"];
+export type QwToastPosition = (typeof TOAST_POSITIONS)[number];
+/** 内建状态图标类型。 */
+export declare const TOAST_ICON_TYPES: readonly ["success", "fail", "loading"];
+export type QwToastIconType = (typeof TOAST_ICON_TYPES)[number];
+/** 逻辑部件（承载 data-part 样式与 parity 指纹）。 */
+export declare const TOAST_PARTS: readonly ["mask", "wrap", "body", "icon", "content"];
+export type QwToastPart = (typeof TOAST_PARTS)[number];
+/** 默认展示时长（ms）。 */
+export declare const DEFAULT_TOAST_DURATION = 3000;
+/** 默认垂直位置（对齐设计稿：默认顶部）。 */
+export declare const DEFAULT_TOAST_POSITION: QwToastPosition;
+/**
+ * Toast 选项契约。`Node` / `Style` 由适配层具体化
+ * （React `ReactNode` / `CSSProperties`；Vue `VNode` / `StyleValue`）。
+ * 与 antd-mobile 风格对齐：命令式 `Toast.show(options)`。
+ */
+export interface QwToastOptions<Node = unknown, Style = unknown> {
+    /** 提示主文案。可空（纯图标提示）。 */
+    content?: Node;
+    /** 前置图标：内建类型 `success | fail | loading`，或任意自定义节点；不传则不展示图标。 */
+    icon?: QwToastIconType | Node;
+    /** 持续时间（ms），默认 3000；为 0 时不自动关闭。 */
+    duration?: number;
+    /** 垂直显示位置，默认 top。 */
+    position?: QwToastPosition;
+    /** 自定义遮罩层内联样式。 */
+    maskStyle?: Style;
+    /** 自定义遮罩层 class。 */
+    maskClassName?: string;
+    /** 关闭后回调（自动消失或手动 clear 均触发）。 */
+    afterClose?: () => void;
+}
+/** 命令式 Toast 单例接口（各框架适配层实现同名同义）。 */
+export interface QwToast<Node = unknown, Style = unknown> {
+    /** 展示一条提示（替换上一条）。 */
+    show: (options?: QwToastOptions<Node, Style>) => void;
+    /** 立即收起当前提示。 */
+    clear: () => void;
+}
+/** 判断 icon 是否为内建状态图标类型。 */
+export declare function isToastIconType(icon: unknown): icon is QwToastIconType;
+/** 解析持续时间：未传用默认 3000；显式 0 透传（不自动关闭）。 */
+export declare function resolveToastDuration(duration?: number): number;

package/dist/top-bar/index.d.ts

@@ -0,0 +1 @@
+export * from "./top-bar.js";

package/dist/top-bar/index.js

@@ -0,0 +1,43 @@
+//#region src/top-bar/top-bar.ts
+/**
+* Top Bar 契约 — 原型 A（无状态），core 无 machine，只承载双栈共享的类型契约。
+* React/Vue 适配层从这里 import 类型与 createTopBarProps，不允许各自再定义一份。
+*
+* Top Bar 是内容面板的头部组件，通过 `variant` prop 选择三种互斥结构形式：
+* basic（标题 + 收起 icon）、tab（tablist + 收起 icon）、extended（返回箭头 + 自定义中间 + 关闭 icon）。
+* Tab 切换复用 @qw-ui/core/tabs。
+*
+* 枚举以运行时常量数组为唯一事实源（类型从常量推导），__test__ 直接锁死词表。
+*/
+/** variant 全集：basic 基础 / tab 标签页 / extended 拓展。 */
+const TOPBAR_VARIANTS = [
+	"basic",
+	"tab",
+	"extended"
+];
+/**
+* 把 QwTopBarProps 收口默认值，返回适配层配置对象。
+* 不进 machine（原型 A）。纯函数，SSR-safe。
+*/
+function createTopBarProps(props) {
+	const items = props.items;
+	return {
+		variant: props.variant,
+		title: props.title,
+		items,
+		defaultValue: props.defaultValue ?? null,
+		value: props.value ?? null,
+		onValueChange: props.onValueChange,
+		onCollapse: props.onCollapse,
+		collapseLabel: props.collapseLabel ?? "收起",
+		onBack: props.onBack,
+		backLabel: props.backLabel ?? "返回",
+		onClose: props.onClose,
+		closeLabel: props.closeLabel ?? "关闭",
+		hasTabs: items !== void 0 && items.length > 0
+	};
+}
+//#endregion
+export { TOPBAR_VARIANTS, createTopBarProps };
+
+//# sourceMappingURL=index.js.map

package/dist/top-bar/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/top-bar/top-bar.ts"],"sourcesContent":["/**\n * Top Bar 契约 — 原型 A（无状态），core 无 machine，只承载双栈共享的类型契约。\n * React/Vue 适配层从这里 import 类型与 createTopBarProps，不允许各自再定义一份。\n *\n * Top Bar 是内容面板的头部组件，通过 `variant` prop 选择三种互斥结构形式：\n * basic（标题 + 收起 icon）、tab（tablist + 收起 icon）、extended（返回箭头 + 自定义中间 + 关闭 icon）。\n * Tab 切换复用 @qw-ui/core/tabs。\n *\n * 枚举以运行时常量数组为唯一事实源（类型从常量推导），__test__ 直接锁死词表。\n */\n\n/** variant 全集：basic 基础 / tab 标签页 / extended 拓展。 */\nexport const TOPBAR_VARIANTS = [\"basic\", \"tab\", \"extended\"] as const;\n\n/** 结构形式。 */\nexport type TopBarVariant = (typeof TOPBAR_VARIANTS)[number];\n\n/**\n * TopBarItem — Tab 项契约，与 @qw-ui/react/tabs 和 @qw-ui/vue/tabs 的 TabItem 同构。\n * core 定义最小形状（label/content 为 string），适配层各自扩展为 ReactNode / slot。\n */\nexport interface TopBarItem {\n  /** 选项唯一值。 */\n  value: string;\n  /** 选项标签文本。 */\n  label: string;\n  /** 选项内容（简单文本）。 */\n  content?: string;\n  /** 禁用该选项：跳过键盘漫游、不可点击。 */\n  disabled?: boolean;\n}\n\n/**\n * QwTopBarProps — 双栈共享的行为 + 视觉契约。\n * Tab 相关 props（items/value/defaultValue/onValueChange）透传给 @qw-ui/core/tabs。\n * variant 为必填，其余 props 按 variant 条件可选（flat interface，非 discriminated union）。\n */\nexport interface QwTopBarProps {\n  /** 结构形式（必填）。 */\n  variant: TopBarVariant;\n\n  // ── basic 专用 ──\n  /** 标题名称（basic 专用）。 */\n  title?: string;\n\n  // ── tab 专用 ──\n  /** Tab 切换模式的数据项。 */\n  items?: TopBarItem[];\n  /** Tab 非受控初值。 */\n  defaultValue?: string | null;\n  /** Tab 受控当前项。 */\n  value?: string | null;\n  /** Tab 选中项变化回调。 */\n  onValueChange?: (e: { value: string }) => void;\n\n  // ── basic + tab 共用 ──\n  /** 收起 icon 点击回调（关闭内容面板）。 */\n  onCollapse?: () => void;\n  /** 收起 icon 的 aria-label，默认「收起」。 */\n  collapseLabel?: string;\n\n  // ── extended 专用 ──\n  /** 返回箭头点击回调（面板内导航回退）。 */\n  onBack?: () => void;\n  /** 返回箭头的 aria-label，默认「返回」。 */\n  backLabel?: string;\n  /** 关闭 icon 点击回调（关闭面板）。 */\n  onClose?: () => void;\n  /** 关闭 icon 的 aria-label，默认「关闭」。 */\n  closeLabel?: string;\n}\n\n/**\n * ResolvedTopBarProps — createTopBarProps 返回值，适配层消费此对象渲染。\n */\nexport interface ResolvedTopBarProps {\n  variant: TopBarVariant;\n  title: string | undefined;\n  items: TopBarItem[] | undefined;\n  defaultValue: string | null;\n  value: string | null;\n  onValueChange: ((e: { value: string }) => void) | undefined;\n  onCollapse: (() => void) | undefined;\n  collapseLabel: string;\n  onBack: (() => void) | undefined;\n  backLabel: string;\n  onClose: (() => void) | undefined;\n  closeLabel: string;\n  hasTabs: boolean;\n}\n\n/**\n * 把 QwTopBarProps 收口默认值，返回适配层配置对象。\n * 不进 machine（原型 A）。纯函数，SSR-safe。\n */\nexport function createTopBarProps(props: QwTopBarProps): ResolvedTopBarProps {\n  const items = props.items;\n\n  return {\n    variant: props.variant,\n    title: props.title,\n    items,\n    defaultValue: props.defaultValue ?? null,\n    value: props.value ?? null,\n    onValueChange: props.onValueChange,\n    onCollapse: props.onCollapse,\n    collapseLabel: props.collapseLabel ?? \"收起\",\n    onBack: props.onBack,\n    backLabel: props.backLabel ?? \"返回\",\n    onClose: props.onClose,\n    closeLabel: props.closeLabel ?? \"关闭\",\n    hasTabs: items !== undefined && items.length > 0,\n  };\n}\n"],"mappings":";;;;;;;;;;;;AAYA,MAAa,kBAAkB;CAAC;CAAS;CAAO;AAAU;;;;;AAmF1D,SAAgB,kBAAkB,OAA2C;CAC3E,MAAM,QAAQ,MAAM;CAEpB,OAAO;EACL,SAAS,MAAM;EACf,OAAO,MAAM;EACb;EACA,cAAc,MAAM,gBAAgB;EACpC,OAAO,MAAM,SAAS;EACtB,eAAe,MAAM;EACrB,YAAY,MAAM;EAClB,eAAe,MAAM,iBAAiB;EACtC,QAAQ,MAAM;EACd,WAAW,MAAM,aAAa;EAC9B,SAAS,MAAM;EACf,YAAY,MAAM,cAAc;EAChC,SAAS,UAAU,KAAA,KAAa,MAAM,SAAS;CACjD;AACF"}

package/dist/top-bar/top-bar.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Top Bar 契约 — 原型 A（无状态），core 无 machine，只承载双栈共享的类型契约。
+ * React/Vue 适配层从这里 import 类型与 createTopBarProps，不允许各自再定义一份。
+ *
+ * Top Bar 是内容面板的头部组件，通过 `variant` prop 选择三种互斥结构形式：
+ * basic（标题 + 收起 icon）、tab（tablist + 收起 icon）、extended（返回箭头 + 自定义中间 + 关闭 icon）。
+ * Tab 切换复用 @qw-ui/core/tabs。
+ *
+ * 枚举以运行时常量数组为唯一事实源（类型从常量推导），__test__ 直接锁死词表。
+ */
+/** variant 全集：basic 基础 / tab 标签页 / extended 拓展。 */
+export declare const TOPBAR_VARIANTS: readonly ["basic", "tab", "extended"];
+/** 结构形式。 */
+export type TopBarVariant = (typeof TOPBAR_VARIANTS)[number];
+/**
+ * TopBarItem — Tab 项契约，与 @qw-ui/react/tabs 和 @qw-ui/vue/tabs 的 TabItem 同构。
+ * core 定义最小形状（label/content 为 string），适配层各自扩展为 ReactNode / slot。
+ */
+export interface TopBarItem {
+    /** 选项唯一值。 */
+    value: string;
+    /** 选项标签文本。 */
+    label: string;
+    /** 选项内容（简单文本）。 */
+    content?: string;
+    /** 禁用该选项：跳过键盘漫游、不可点击。 */
+    disabled?: boolean;
+}
+/**
+ * QwTopBarProps — 双栈共享的行为 + 视觉契约。
+ * Tab 相关 props（items/value/defaultValue/onValueChange）透传给 @qw-ui/core/tabs。
+ * variant 为必填，其余 props 按 variant 条件可选（flat interface，非 discriminated union）。
+ */
+export interface QwTopBarProps {
+    /** 结构形式（必填）。 */
+    variant: TopBarVariant;
+    /** 标题名称（basic 专用）。 */
+    title?: string;
+    /** Tab 切换模式的数据项。 */
+    items?: TopBarItem[];
+    /** Tab 非受控初值。 */
+    defaultValue?: string | null;
+    /** Tab 受控当前项。 */
+    value?: string | null;
+    /** Tab 选中项变化回调。 */
+    onValueChange?: (e: {
+        value: string;
+    }) => void;
+    /** 收起 icon 点击回调（关闭内容面板）。 */
+    onCollapse?: () => void;
+    /** 收起 icon 的 aria-label，默认「收起」。 */
+    collapseLabel?: string;
+    /** 返回箭头点击回调（面板内导航回退）。 */
+    onBack?: () => void;
+    /** 返回箭头的 aria-label，默认「返回」。 */
+    backLabel?: string;
+    /** 关闭 icon 点击回调（关闭面板）。 */
+    onClose?: () => void;
+    /** 关闭 icon 的 aria-label，默认「关闭」。 */
+    closeLabel?: string;
+}
+/**
+ * ResolvedTopBarProps — createTopBarProps 返回值，适配层消费此对象渲染。
+ */
+export interface ResolvedTopBarProps {
+    variant: TopBarVariant;
+    title: string | undefined;
+    items: TopBarItem[] | undefined;
+    defaultValue: string | null;
+    value: string | null;
+    onValueChange: ((e: {
+        value: string;
+    }) => void) | undefined;
+    onCollapse: (() => void) | undefined;
+    collapseLabel: string;
+    onBack: (() => void) | undefined;
+    backLabel: string;
+    onClose: (() => void) | undefined;
+    closeLabel: string;
+    hasTabs: boolean;
+}
+/**
+ * 把 QwTopBarProps 收口默认值，返回适配层配置对象。
+ * 不进 machine（原型 A）。纯函数，SSR-safe。
+ */
+export declare function createTopBarProps(props: QwTopBarProps): ResolvedTopBarProps;

package/dist/visual-manifest.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 组件视觉契约清单类型 — workspace 内部使用（不进 npm 产物、不进 core 公开 API）。
+ *
+ * 每个组件在 `src/<slug>/docs/visual.ts` 维护一份 `QwComponentVisualMeta`，
+ * 它是确定性视觉契约的唯一事实源：React/Vue 共用同一份场景声明，
+ * `tools/visual-check` 按清单展开矩阵并在真实浏览器内做运行时自比较
+ *（状态差异 / token 绑定 / 主题切换 / 双栈样式 parity / 几何关系）。
+ *
+ * Demo 层通过 `data-visual-target="<target>"` 标记契约锚点（不进组件公共 API）。
+ *
+ * 非目标：禁止落盘任何截图或 computed-style 指纹制品作为跨运行基线。
+ */
+/** 受支持的视觉状态词表（封闭集合；新增状态须改此类型并更新共享 driver）。 */
+export type QwVisualState = "default" | "hover" | "active" | "focus-visible" | "disabled" | "loading" | "open" | "closed" | "selected" | "checked" | "expanded";
+/** 主题轴。 */
+export type QwVisualTheme = "light" | "dark";
+/** 框架轴。 */
+export type QwVisualFramework = "react" | "vue";
+/** 视口配置（预留扩展；默认 mobile = 390×844 @2x，与 G3 一致）。 */
+export type QwVisualViewport = "mobile";
+/**
+ * 语义视觉通道——状态变化的抽象分组，不是 CSS 属性字面量。
+ * 状态差异断言要求 delta 至少命中该状态通道词表中的一项。
+ */
+export type QwVisualChannel = "fill" | "content" | "edge" | "opacity" | "transform" | "cursor" | "presence";
+/** 声明式前置动作（进入 open/selected 等状态）。 */
+export type QwVisualAction = {
+    action: "click";
+    target: string;
+} | {
+    action: "press";
+    target: string;
+    keys: string;
+} | {
+    action: "tab-to";
+    target: string;
+} | {
+    action: "click-role";
+    role: string;
+    name?: string;
+    index?: number;
+};
+/**
+ * 几何关系谓词——只表达相对关系，不写死绝对像素。
+ * 封闭小词表；按需求增长，不预设。
+ */
+export type QwGeometryRelation = {
+    rel: "contains";
+    outer: string;
+    inner: string;
+} | {
+    rel: "centered";
+    item: string;
+    within: string;
+    axis?: "block" | "inline";
+} | {
+    rel: "monotonic";
+    axis: "block-size" | "inline-size";
+    targets: string[];
+} | {
+    rel: "equal";
+    axis: "block-size" | "inline-size";
+    targets: string[];
+    tolerancePx?: number;
+} | {
+    rel: "token-size";
+    target: string;
+    axis: "block-size" | "inline-size";
+    /** T3 token 短名，如 "size-control-height-m"；运行时从 tokens.json 解析 */
+    token: string;
+};
+/** 场景级可选强契约；省略时仍享有零声明基础保障。 */
+export interface QwVisualExpect {
+    /** 覆盖库级默认通道（极少用，如某状态刻意不改 fill）。 */
+    channels?: Partial<Record<QwVisualState, QwVisualChannel[]>>;
+    /**
+     * 强契约：状态下某属性必须解析为指定 T3 token 的值。
+     * key = "state.property"（state 可省略，默认 default），value = token 短名（如 "border-focus"）。
+     */
+    tokens?: Record<string, string>;
+    /** 几何关系谓词。 */
+    geometry?: QwGeometryRelation[];
+    /** 该场景颜色随主题不变，显式豁免主题 delta 检查。 */
+    themeInvariant?: boolean;
+    /** 动画契约。 */
+    motion?: {
+        /** data-visual-target 或 data-part 选择器别名；解析为动画宿主 */
+        animatedPart: string;
+        respectsReducedMotion?: boolean;
+    };
+    /** Icon 等：双栈 SVG 结构归一化哈希一致。 */
+    svgParity?: boolean;
+    /** target 允许溢出 demo 画布（Dialog backdrop / Toast overlay 等）。 */
+    allowOverflow?: boolean;
+}
+/** 单个视觉场景。 */
+export interface QwVisualScenario {
+    /** kebab-case 场景名，进入 case id。 */
+    name: string;
+    /** 引用 demos.ts 中的 demo id。 */
+    demo: string;
+    /** 对应 demo 中 `data-visual-target` 的值。 */
+    target: string;
+    /** 本场景要验证的视觉状态列表。 */
+    states: QwVisualState[];
+    /** 主题列表，默认 light + dark（主题 delta 使用；parity 仍跑双主题）。 */
+    themes?: QwVisualTheme[];
+    /** 框架列表，默认 react + vue。 */
+    frameworks?: QwVisualFramework[];
+    /** 进入特定状态前的动作序列。 */
+    setup?: QwVisualAction[];
+    /** 视口配置，默认 mobile。 */
+    viewport?: QwVisualViewport;
+    /** 可选强契约；零声明场景仍有基础保障。 */
+    expect?: QwVisualExpect;
+}
+/** 组件视觉契约元数据。 */
+export interface QwComponentVisualMeta {
+    slug: string;
+    scenarios: QwVisualScenario[];
+    /** 软预算提示阈值（契约 case 数）；超出时 verify 警告但不阻塞。 */
+    budget?: number;
+}
+/** 默认主题轴。 */
+export declare const QW_VISUAL_DEFAULT_THEMES: readonly QwVisualTheme[];
+/** 默认框架轴。 */
+export declare const QW_VISUAL_DEFAULT_FRAMEWORKS: readonly QwVisualFramework[];
+/** 软预算默认值（契约 case 数）。 */
+export declare const QW_VISUAL_DEFAULT_BUDGET = 120;
+/**
+ * 库级默认：状态 → 期望变化的视觉通道。
+ * 通道命中即可（OR），不要求全部命中。
+ */
+export declare const QW_STATE_CHANNELS: Readonly<Record<Exclude<QwVisualState, "default" | "closed">, readonly QwVisualChannel[]>>;
+/** Case id：`{slug}-{scenario}--{state}--{theme}-{framework}` */
+export declare function qwVisualCaseId(slug: string, scenario: string, state: QwVisualState, theme: QwVisualTheme, framework: QwVisualFramework): string;
+/** @deprecated 使用 qwVisualCaseId；保留别名以兼容过渡期引用。 */
+export declare const qwVisualSnapshotName: typeof qwVisualCaseId;
+/** 展开场景为契约 case id 列表。 */
+export declare function expandVisualCases(meta: QwComponentVisualMeta): string[];
+/** @deprecated 使用 expandVisualCases。 */
+export declare const expandVisualSnapshots: typeof expandVisualCases;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qw-ui/core",
-  "version": "0.1.0",
+  "version": "0.2.0-next.0",
   "description": "L2 · Headless Core — zag.js machine 薄包装，纯 TS / SSR-safe，零样式。",
   "license": "MIT",
   "author": "qw-ui contributors",
@@ -35,12 +35,59 @@
     "./tabs": {
       "types": "./dist/tabs/index.d.ts",
       "import": "./dist/tabs/index.js"
+    },
+    "./toast": {
+      "types": "./dist/toast/index.d.ts",
+      "import": "./dist/toast/index.js"
+    },
+    "./button": {
+      "types": "./dist/button/index.d.ts",
+      "import": "./dist/button/index.js"
+    },
+    "./empty": {
+      "types": "./dist/empty/index.d.ts",
+      "import": "./dist/empty/index.js"
+    },
+    "./divider": {
+      "types": "./dist/divider/index.d.ts",
+      "import": "./dist/divider/index.js"
+    },
+    "./loading": {
+      "types": "./dist/loading/index.d.ts",
+      "import": "./dist/loading/index.js"
+    },
+    "./skeleton": {
+      "types": "./dist/skeleton/index.d.ts",
+      "import": "./dist/skeleton/index.js"
+    },
+    "./top-bar": {
+      "types": "./dist/top-bar/index.d.ts",
+      "import": "./dist/top-bar/index.js"
+    },
+    "./icon": {
+      "types": "./dist/icon/index.d.ts",
+      "import": "./dist/icon/index.js"
+    },
+    "./search-bar": {
+      "types": "./dist/search-bar/index.d.ts",
+      "import": "./dist/search-bar/index.js"
+    },
+    "./avatar": {
+      "types": "./dist/avatar/index.d.ts",
+      "import": "./dist/avatar/index.js"
+    },
+    "./image": {
+      "types": "./dist/image/index.d.ts",
+      "import": "./dist/image/index.js"
     }
   },
   "sideEffects": false,
   "dependencies": {
+    "@zag-js/core": "1.42.0",
     "@zag-js/dialog": "^1.42.0",
-    "@zag-js/tabs": "^1.42.0"
+    "@zag-js/tabs": "^1.42.0",
+    "@zag-js/utils": "1.42.0",
+    "@qw-ui/icons": "^0.2.0-next.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.58.9",
@@ -50,8 +97,9 @@
     "@zag-js/vanilla": "^1.42.0",
     "jsdom": "^29.1.1",
     "size-limit": "^12.1.0",
-    "tsup": "^8.5.1",
+    "tsdown": "^0.22.4",
     "typescript": "^6.0.3",
+    "unrun": "^0.3.1",
     "vitest": "^4.1.9",
     "@qw-ui/eslint-config": "0.0.0",
     "@qw-ui/tsconfig": "0.0.0"
@@ -70,6 +118,14 @@
       "ignore": [
         "@zag-js/tabs"
       ]
+    },
+    {
+      "path": "dist/top-bar/index.js",
+      "limit": "4 kB"
+    },
+    {
+      "path": "dist/toast/index.js",
+      "limit": "2 kB"
     }
   ],
   "publishConfig": {
@@ -77,9 +133,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown && tsgo -p tsconfig.build.json",
     "test": "vitest run",
     "lint": "eslint .",
+    "typecheck": "tsgo --noEmit -p tsconfig.build.json",
     "size": "size-limit",
     "api": "api-extractor run --local",
     "clean": "rm -rf dist .turbo etc/*.api.json temp"

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/dialog/index.ts","../src/tabs/index.ts"],"names":[],"mappings":";;;;AAwDO,SAAS,iBAAA,CAAkB,KAAA,GAAuB,EAAC,EAA4B;AACpF,EAAA,MAAM,GAAA,GAA+B;AAAA,IACnC,IAAI,KAAA,CAAM,EAAA;AAAA,IACV,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,aAAa,KAAA,CAAM,WAAA;AAAA,IACnB,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,aAAA,EAAe,MAAM,UAAA,KAAe,KAAA;AAAA,IACpC,sBAAA,EAAwB,MAAM,cAAA,KAAmB,KAAA;AAAA,IACjD,aAAA,EAAe,MAAM,UAAA,KAAe;AAAA,GACtC;AAEA,EAAA,IAAI,KAAA,CAAM,KAAA,KAAU,MAAA,EAAW,GAAA,CAAI,QAAQ,KAAA,CAAM,KAAA;AAEjD,EAAA,IAAI,MAAM,YAAA,EAAc;AACtB,IAAA,MAAM,KAAK,KAAA,CAAM,YAAA;AACjB,IAAA,GAAA,CAAI,YAAA,GAAe,CAAC,CAAA,KAAyB,EAAA,CAAG,EAAE,IAAA,EAAM,CAAA,CAAE,MAAM,CAAA;AAAA,EAClE;AAGA,EAAA,IAAI,OAAO,KAAA,CAAM,YAAA,KAAiB,QAAA,EAAU;AAC1C,IAAA,MAAM,GAAA,GAAM,MAAM,YAAA,CAAa,QAAA;AAC/B,IAAA,GAAA,CAAI,cAAA,GAAiB,MAAM,QAAA,CAAS,aAAA,CAA2B,GAAG,CAAA;AAAA,EACpE;AAGA,EAAA,IAAI,OAAO,KAAA,CAAM,WAAA,KAAgB,QAAA,EAAU;AACzC,IAAA,MAAM,GAAA,GAAM,MAAM,WAAA,CAAY,QAAA;AAC9B,IAAA,GAAA,CAAI,YAAA,GAAe,MAAM,QAAA,CAAS,aAAA,CAA2B,GAAG,CAAA;AAAA,EAClE,CAAA,MAAA,IAAW,KAAA,CAAM,WAAA,KAAgB,MAAA,EAAQ;AACvC,IAAA,GAAA,CAAI,YAAA,GAAe,KAAA;AAAA,EACrB;AAEA,EAAA,OAAO,GAAA;AACT;AClDO,SAAS,eAAA,CAAgB,KAAA,GAAqB,EAAC,EAA0B;AAC9E,EAAA,MAAM,GAAA,GAA6B;AAAA,IACjC,IAAI,KAAA,CAAM,EAAA;AAAA,IACV,OAAO,KAAA,CAAM,KAAA;AAAA,IACb,cAAc,KAAA,CAAM,YAAA;AAAA,IACpB,aAAa,KAAA,CAAM,WAAA;AAAA,IACnB,gBAAgB,KAAA,CAAM,cAAA;AAAA,IACtB,SAAA,EAAW,MAAM,IAAA,KAAS;AAAA,GAC5B;AAEA,EAAA,IAAI,MAAM,aAAA,EAAe;AACvB,IAAA,MAAM,KAAK,KAAA,CAAM,aAAA;AACjB,IAAA,GAAA,CAAI,aAAA,GAAgB,CAAC,CAAA,KAA0B,EAAA,CAAG,EAAE,KAAA,EAAO,CAAA,CAAE,OAAO,CAAA;AAAA,EACtE;AAEA,EAAA,OAAO,GAAA;AACT","file":"index.js","sourcesContent":["import type { Props as ZagDialogProps, OpenChangeDetails } from \"@zag-js/dialog\";\n\n/**\n * QwDialogProps — Dialog 的用户输入。\n *\n * 对 zag.js 输入做两件事 (§06)：\n * 1. 默认值收口：closeOnEsc / closeOnOutside / scrollLock 默认全 true；\n * 2. 命名 rebrand：把 zag 的 closeOnInteractOutside / preventScroll 改成业务易懂命名；\n * 3. 业务 props 透出：onOpenChange / initialFocus / returnFocus 在 React/Vue 同名。\n *\n * 业务方只需 import 本类型，不需要直接 import `@zag-js/*`。\n */\nexport interface QwDialogProps {\n  /** 唯一 id 前缀；不传时由 zag 安全生成 (SSR/CSR 一致)。 */\n  id?: string;\n  /** 受控开关。 */\n  open?: boolean;\n  /** 非受控初值。 */\n  defaultOpen?: boolean;\n  /** ESC 关闭，默认 true (zag 原名 closeOnEscape)。 */\n  closeOnEsc?: boolean;\n  /** 点击 backdrop 关闭，默认 true (zag 原名 closeOnInteractOutside)。 */\n  closeOnOutside?: boolean;\n  /** 滚动锁，默认 true (zag 原名 preventScroll)。 */\n  scrollLock?: boolean;\n  /** 模态遮蔽，默认 true。 */\n  modal?: boolean;\n  /** 角色，默认 dialog。 */\n  role?: \"dialog\" | \"alertdialog\";\n  /** 初始焦点策略；对象形式提供 selector，由 core 翻译成 zag 的 initialFocusEl。 */\n  initialFocus?: \"autofocus\" | \"first\" | \"none\" | { selector: string };\n  /** 关闭回焦策略；对应 zag 的 restoreFocus + finalFocusEl。 */\n  returnFocus?: \"previous\" | \"none\" | { selector: string };\n  /** 状态变化回调；zag 原生 onOpenChange。 */\n  onOpenChange?: (e: { open: boolean }) => void;\n  /**\n   * 禁用 trigger：禁用后点击/键盘都不打开。\n   * adapter 层声明式属性（落到原生 button[disabled]）——zag dialog 无此 context，不进 machine。\n   */\n  disabled?: boolean;\n}\n\n/**\n * 直接 re-export zag 的 dialog machine 与 connect —— 不再包一层。\n * machine 由各框架 useMachine 消费；connect 把 service 接成 prop-getter。\n * 用 re-export 而非 `const x = dialog.x` 以保留原始可移植类型 (避免 TS2742)。\n */\nexport { machine as dialogMachine, connect } from \"@zag-js/dialog\";\n\n/** rebrand zag 的 DialogApi 类型对外。 */\nexport type { Api as QwDialogApi } from \"@zag-js/dialog\";\n\n/**\n * 把 QwDialogProps 转成 zag dialog machine 的 context (默认值收口 + 命名 rebrand)。\n * 用法：`useMachine(dialogMachine, createDialogProps(props))`。\n */\nexport function createDialogProps(props: QwDialogProps = {}): Partial<ZagDialogProps> {\n  const ctx: Partial<ZagDialogProps> = {\n    id: props.id,\n    open: props.open,\n    defaultOpen: props.defaultOpen,\n    role: props.role,\n    closeOnEscape: props.closeOnEsc !== false,\n    closeOnInteractOutside: props.closeOnOutside !== false,\n    preventScroll: props.scrollLock !== false,\n  };\n\n  if (props.modal !== undefined) ctx.modal = props.modal;\n\n  if (props.onOpenChange) {\n    const cb = props.onOpenChange;\n    ctx.onOpenChange = (d: OpenChangeDetails) => cb({ open: d.open });\n  }\n\n  // initialFocus: { selector } → initialFocusEl 回调；'none' 关闭自动聚焦\n  if (typeof props.initialFocus === \"object\") {\n    const sel = props.initialFocus.selector;\n    ctx.initialFocusEl = () => document.querySelector<HTMLElement>(sel);\n  }\n\n  // returnFocus: { selector } → finalFocusEl；'none' → restoreFocus=false\n  if (typeof props.returnFocus === \"object\") {\n    const sel = props.returnFocus.selector;\n    ctx.finalFocusEl = () => document.querySelector<HTMLElement>(sel);\n  } else if (props.returnFocus === \"none\") {\n    ctx.restoreFocus = false;\n  }\n\n  return ctx;\n}\n","import type { Props as ZagTabsProps, ValueChangeDetails } from \"@zag-js/tabs\";\n\n/**\n * QwTabsProps — Tabs 的用户输入。对 zag.js 输入做默认值收口 + 命名 rebrand：\n * - loop（默认 true）→ zag loopFocus；\n * - value / defaultValue / orientation / activationMode 透传；\n * - onValueChange 适配 zag details。\n * 业务方只 import 本类型，不直接 import `@zag-js/*`。\n */\nexport interface QwTabsProps {\n  /** 唯一 id 前缀；不传由适配层生成 (SSR/CSR 一致)。 */\n  id?: string;\n  /** 受控当前项。 */\n  value?: string | null;\n  /** 非受控初值。 */\n  defaultValue?: string | null;\n  /** 方向，默认 horizontal。 */\n  orientation?: \"horizontal\" | \"vertical\";\n  /** 激活模式，默认 automatic（聚焦即激活）。 */\n  activationMode?: \"manual\" | \"automatic\";\n  /** 方向键首尾循环，默认 true (zag 原名 loopFocus)。 */\n  loop?: boolean;\n  /** 选中项变化回调；zag 原生 onValueChange。 */\n  onValueChange?: (e: { value: string }) => void;\n}\n\n/**\n * 直接 re-export zag tabs 的 machine 与 connect —— 不包一层。\n * 用 re-export 保留原始可移植类型 (避免 TS2742)。\n */\nexport { machine as tabsMachine, connect } from \"@zag-js/tabs\";\n\n/** rebrand zag 的 TabsApi 类型对外。 */\nexport type { Api as QwTabsApi } from \"@zag-js/tabs\";\n\n/**\n * 把 QwTabsProps 转成 zag tabs machine 的 props (默认值收口 + 命名 rebrand)。\n * 用法：`useMachine(tabsMachine, createTabsProps(props))`。\n */\nexport function createTabsProps(props: QwTabsProps = {}): Partial<ZagTabsProps> {\n  const ctx: Partial<ZagTabsProps> = {\n    id: props.id,\n    value: props.value,\n    defaultValue: props.defaultValue,\n    orientation: props.orientation,\n    activationMode: props.activationMode,\n    loopFocus: props.loop !== false,\n  };\n\n  if (props.onValueChange) {\n    const cb = props.onValueChange;\n    ctx.onValueChange = (d: ValueChangeDetails) => cb({ value: d.value });\n  }\n\n  return ctx;\n}\n"]}