@chenzy-design/svelte 0.1.0

package/dist/menu/MenuPopupNode.svelte.d.ts

@@ -0,0 +1,52 @@
+import type { Snippet } from 'svelte';
+import type { Placement } from '@chenzy-design/core';
+import type { MenuItemDef, MenuItemNode, MenuKey } from './types.js';
+interface TooltipProps {
+    content?: string;
+    position?: string;
+    theme?: 'dark' | 'light';
+    mouseEnterDelay?: number;
+    mouseLeaveDelay?: number;
+}
+interface Props {
+    item: MenuItemDef;
+    /** 顶层节点用 bottomStart 弹出向下，嵌套层用 rightStart 向右 */
+    placement: Placement;
+    isSelected: (key: MenuKey) => boolean;
+    onSelectLeaf: (item: MenuItemNode) => void;
+    /** 选中叶子后自顶向下逐级关闭浮层 */
+    onCloseAll: () => void;
+    openDelay?: number;
+    closeDelay?: number;
+    /** 折叠图标轨：仅本节点（顶层）隐藏文字 label、只显图标，浮层内子项不受影响 */
+    collapsed?: boolean;
+    /** 多选模式：选中叶子显勾选标记并用 aria-checked/menuitemcheckbox 语义 */
+    multiple?: boolean;
+    /** navigation 用途：含 href 叶子渲染原生 <a href>，结构去除 menu/menuitem role（原生链接语义） */
+    navigation?: boolean;
+    /** 浮层子菜单触发方式：'hover'（默认）随悬停开合 / 'click' 点击 title 切换 */
+    trigger?: 'hover' | 'click';
+    /** 浮层子菜单挂载容器（透传 floating action getContainer） */
+    getPopupContainer?: (() => HTMLElement | null | undefined) | undefined;
+    /** 整体禁用（来自父 Menu disabled）：叠加单项 disabled */
+    parentDisabled?: boolean;
+    /** 浮层隐藏时是否卸载内容 DOM（默认 false：保留 DOM 仅隐藏，重显不重建） */
+    destroyOnHide?: boolean;
+    /**
+     * 折叠模式下顶层项的 Tooltip 配置。content 默认为项 label；
+     * position→placement、theme、mouseEnterDelay、mouseLeaveDelay 透传给 Tooltip。
+     */
+    tooltipProps?: TooltipProps;
+    /**
+     * 自定义每个叶子项内容的包裹 Snippet，接收 { item, children }。
+     * children 为默认的 <a> 或 <button> 内容 snippet。
+     */
+    renderWrapper?: Snippet<[{
+        item: MenuItemNode;
+        children: Snippet;
+    }]>;
+}
+declare const MenuPopupNode: import("svelte").Component<Props, {}, "">;
+type MenuPopupNode = ReturnType<typeof MenuPopupNode>;
+export default MenuPopupNode;
+//# sourceMappingURL=MenuPopupNode.svelte.d.ts.map

package/dist/menu/MenuPopupNode.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MenuPopupNode.svelte.d.ts","sourceRoot":"","sources":["../../src/menu/MenuPopupNode.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAKnE,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,UAAU,KAAK;IACb,IAAI,EAAE,WAAW,CAAC;IAClB,gDAAgD;IAChD,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC,YAAY,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;IAC3C,sBAAsB;IACtB,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAC5B,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IACvE,4CAA4C;IAC5C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;CACtE;AA0OH,QAAA,MAAM,aAAa,2CAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}

package/dist/menu/index.d.ts

@@ -0,0 +1,5 @@
+export { default as Menu } from './Menu.svelte';
+export { meta as menuMeta } from './meta.js';
+export type { MenuItemDef, MenuPurpose } from './types.js';
+export { deriveMenuSemantics } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/menu/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/menu/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/menu/index.js

@@ -0,0 +1,3 @@
+export { default as Menu } from './Menu.svelte';
+export { meta as menuMeta } from './meta.js';
+export { deriveMenuSemantics } from './types.js';

package/dist/menu/meta.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export declare const meta: {
+    readonly name: "Menu";
+    readonly category: "navigation";
+    readonly description: "导航菜单，数据驱动。支持 vertical/inline/horizontal 模式、SubMenu 展开/收起、单选/多选高亮，受控/非受控。items 支持 type=divider 分隔符与 type=group 分组标题。purpose 区分命令式菜单（menu/menuitem 语义）与站点导航（nav landmark + 原生 <a> 链接语义）。";
+    readonly props: readonly [{
+        readonly name: "items";
+        readonly type: "MenuItemDef[]";
+        readonly default: "[]";
+        readonly desc: "菜单数据。普通项可省略 type（含 children 即可展开的 SubMenu，item.icon 为项前图标 Snippet）；{ type:\"divider\" } 渲染水平分隔线；{ type:\"group\", label, children } 渲染始终展开的分组标题 + 组内项。navigation 用途下叶子可带 href/target/rel，渲染为原生 <a>";
+    }, {
+        readonly name: "mode";
+        readonly type: "'vertical'|'inline'|'horizontal'";
+        readonly default: "vertical";
+        readonly desc: "vertical=SubMenu hover 浮层；inline=内联展开；horizontal=顶部菜单栏 + ←→ roving";
+    }, {
+        readonly name: "selectedKeys";
+        readonly type: "(string|number)[]";
+        readonly default: "undefined";
+        readonly desc: "受控选中项（单选取首项）";
+    }, {
+        readonly name: "defaultSelectedKeys";
+        readonly type: "(string|number)[]";
+        readonly default: "[]";
+    }, {
+        readonly name: "openKeys";
+        readonly type: "(string|number)[]";
+        readonly default: "undefined";
+        readonly desc: "受控展开的 SubMenu";
+    }, {
+        readonly name: "defaultOpenKeys";
+        readonly type: "(string|number)[]";
+        readonly default: "[]";
+    }, {
+        readonly name: "size";
+        readonly type: "'small'|'default'|'large'";
+        readonly default: "default";
+    }, {
+        readonly name: "inlineIndent";
+        readonly type: "number";
+        readonly default: "24";
+        readonly desc: "子级缩进像素";
+    }, {
+        readonly name: "inlineCollapsed";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "inline 模式折叠为图标轨：仅显图标、容器变窄，有子菜单的项 hover 向右弹浮层（无图标项取 label 首字符；保留 aria-label/title 可访问名）";
+    }, {
+        readonly name: "multiple";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "多选模式：点击叶子项 toggle 选中态，selectedKeys 可含多项同时高亮并显勾选标记。受控下父组件依据 onSelect(key) 自行 toggle selectedKeys；非受控由组件内部维护多选 Set";
+    }, {
+        readonly name: "triggerSubMenuAction";
+        readonly type: "'hover'|'click'";
+        readonly default: "hover";
+        readonly desc: "浮层子菜单触发方式（vertical/horizontal/collapsed 浮层模式生效）：hover 悬停带 open/close 延迟开合；click 点击 title 切换。缺省按 mode 推导（默认 hover）";
+    }, {
+        readonly name: "subMenuOpenDelay";
+        readonly type: "number";
+        readonly default: "100";
+        readonly desc: "hover 触发子菜单浮层展开延迟(ms)";
+    }, {
+        readonly name: "subMenuCloseDelay";
+        readonly type: "number";
+        readonly default: "100";
+        readonly desc: "hover 触发子菜单浮层收起延迟(ms)";
+    }, {
+        readonly name: "status";
+        readonly type: "'default'|'warning'|'error'";
+        readonly default: "default";
+        readonly desc: "校验态（表单内菜单选择，少见）：非 default 时加 cd-menu--{status} 类，以 token 着色选中指示条/文字，error 时根节点 aria-invalid=true";
+    }, {
+        readonly name: "destroyOnHide";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "浮层子菜单隐藏时是否卸载内容 DOM；默认 false 首开后保留 DOM 仅隐藏，true 时随 open 卸载/重建。仅作用于 vertical/horizontal/collapsed 浮层子菜单";
+    }, {
+        readonly name: "getPopupContainer";
+        readonly type: "() => HTMLElement";
+        readonly default: "() => document.body";
+        readonly desc: "浮层子菜单挂载容器（透传 floating action getContainer）；非 body 时改 absolute 相对该容器定位";
+    }, {
+        readonly name: "disabled";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "整体禁用：所有项不可交互（叠加单项 disabled）";
+    }, {
+        readonly name: "purpose";
+        readonly type: "'menu'|'navigation'";
+        readonly default: "menu";
+        readonly desc: "语义用途。'menu'（默认，向后兼容）=命令式菜单：role=menu/menuitem + roving tabindex，叶子 button+onClick。'navigation'=站点导航：<nav> landmark 包裹原生 list，含 href 的叶子渲染原生 <a href>（aria-current=page），沿用浏览器链接 + Tab 键序，不用 menuitem role。role 由 deriveMenuSemantics 纯函数据 purpose+mode+multiple 派生";
+    }, {
+        readonly name: "onSelect";
+        readonly type: "(key: string|number) => void";
+        readonly default: "undefined";
+        readonly desc: "点击叶子项回调，回传被点击的 key（多选语义不变，由父组件据此 toggle）";
+    }, {
+        readonly name: "onOpenChange";
+        readonly type: "(keys: (string|number)[]) => void";
+        readonly default: "undefined";
+    }, {
+        readonly name: "ariaLabel";
+        readonly type: "string";
+        readonly default: "undefined";
+    }, {
+        readonly name: "tooltipProps";
+        readonly type: "{ content?: string; position?: string; theme?: \"dark\"|\"light\"; mouseEnterDelay?: number; mouseLeaveDelay?: number }";
+        readonly default: "undefined";
+        readonly desc: "折叠模式（inlineCollapsed=true）下顶层项的 Tooltip 配置。content 默认为项 label；position→placement 透传给 Tooltip。未提供时用原生 title 属性降级。";
+    }, {
+        readonly name: "renderWrapper";
+        readonly type: "Snippet<[{ item: MenuItemNode; children: Snippet }]>";
+        readonly default: "undefined";
+        readonly desc: "自定义叶子项内容包裹 Snippet，接收 { item, children }。children 为默认的 <a> 或 <button>，可在外层加徽标/标签等装饰。inline/vertical/horizontal/collapsed 模式下均生效。";
+    }];
+    readonly a11y: {
+        readonly role: "menu";
+        readonly keyboard: readonly ["Tab", "Enter", "Space"];
+        readonly notes: readonly ["ul[role=menu] > li[role=none] > button[role=menuitem] 结构", "SubMenu 标题 aria-haspopup=true + aria-expanded 反映展开态", "选中叶子项 aria-current=true（单选）；multiple 下叶子项 role=menuitemcheckbox + aria-checked", "禁用项 aria-disabled=true 且原生 disabled", "divider 渲染 li[role=separator]，不可聚焦不可选；键盘导航天然跳过（非 menuitem）", "group 渲染组标题（不可点击）+ ul[role=group][aria-label=分组名]，组内项正常 menuitem 可选；组标题不可聚焦故键盘跳过", "purpose='navigation'：<nav aria-label> landmark 包裹原生 ul>li>a（去除 menu/menuitem/separator/group 等 role），含 href 叶子为 <a href>，当前项 aria-current=page；用浏览器原生链接 + Tab 键序导航，不接管 ←→ roving", "purpose='menu'（默认）：role=menu/menubar + menuitem，叶子 button + onClick，行为完全向后兼容；role 集合由 deriveMenuSemantics(purpose, mode, multiple) 纯函数派生（红线 #2）"];
+    };
+    readonly tokens: readonly ["--cd-menu-bg", "--cd-menu-item-height", "--cd-menu-item-padding", "--cd-menu-item-color", "--cd-menu-item-color-selected", "--cd-menu-item-color-disabled", "--cd-menu-item-bg-hover", "--cd-menu-item-bg-selected", "--cd-menu-item-indicator", "--cd-menu-submenu-arrow-color", "--cd-focus-ring", "--cd-motion-*"];
+};
+//# sourceMappingURL=meta.d.ts.map

package/dist/menu/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/menu/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoIP,CAAC"}

package/dist/menu/meta.js

@@ -0,0 +1,136 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+    name: 'Menu',
+    category: 'navigation',
+    description: '导航菜单，数据驱动。支持 vertical/inline/horizontal 模式、SubMenu 展开/收起、单选/多选高亮，受控/非受控。items 支持 type=divider 分隔符与 type=group 分组标题。purpose 区分命令式菜单（menu/menuitem 语义）与站点导航（nav landmark + 原生 <a> 链接语义）。',
+    props: [
+        {
+            name: 'items',
+            type: 'MenuItemDef[]',
+            default: '[]',
+            desc: '菜单数据。普通项可省略 type（含 children 即可展开的 SubMenu，item.icon 为项前图标 Snippet）；{ type:"divider" } 渲染水平分隔线；{ type:"group", label, children } 渲染始终展开的分组标题 + 组内项。navigation 用途下叶子可带 href/target/rel，渲染为原生 <a>',
+        },
+        {
+            name: 'mode',
+            type: "'vertical'|'inline'|'horizontal'",
+            default: 'vertical',
+            desc: 'vertical=SubMenu hover 浮层；inline=内联展开；horizontal=顶部菜单栏 + ←→ roving',
+        },
+        {
+            name: 'selectedKeys',
+            type: '(string|number)[]',
+            default: 'undefined',
+            desc: '受控选中项（单选取首项）',
+        },
+        { name: 'defaultSelectedKeys', type: '(string|number)[]', default: '[]' },
+        {
+            name: 'openKeys',
+            type: '(string|number)[]',
+            default: 'undefined',
+            desc: '受控展开的 SubMenu',
+        },
+        { name: 'defaultOpenKeys', type: '(string|number)[]', default: '[]' },
+        { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
+        { name: 'inlineIndent', type: 'number', default: '24', desc: '子级缩进像素' },
+        {
+            name: 'inlineCollapsed',
+            type: 'boolean',
+            default: 'false',
+            desc: 'inline 模式折叠为图标轨：仅显图标、容器变窄，有子菜单的项 hover 向右弹浮层（无图标项取 label 首字符；保留 aria-label/title 可访问名）',
+        },
+        {
+            name: 'multiple',
+            type: 'boolean',
+            default: 'false',
+            desc: '多选模式：点击叶子项 toggle 选中态，selectedKeys 可含多项同时高亮并显勾选标记。受控下父组件依据 onSelect(key) 自行 toggle selectedKeys；非受控由组件内部维护多选 Set',
+        },
+        {
+            name: 'triggerSubMenuAction',
+            type: "'hover'|'click'",
+            default: 'hover',
+            desc: '浮层子菜单触发方式（vertical/horizontal/collapsed 浮层模式生效）：hover 悬停带 open/close 延迟开合；click 点击 title 切换。缺省按 mode 推导（默认 hover）',
+        },
+        { name: 'subMenuOpenDelay', type: 'number', default: '100', desc: 'hover 触发子菜单浮层展开延迟(ms)' },
+        { name: 'subMenuCloseDelay', type: 'number', default: '100', desc: 'hover 触发子菜单浮层收起延迟(ms)' },
+        {
+            name: 'status',
+            type: "'default'|'warning'|'error'",
+            default: 'default',
+            desc: '校验态（表单内菜单选择，少见）：非 default 时加 cd-menu--{status} 类，以 token 着色选中指示条/文字，error 时根节点 aria-invalid=true',
+        },
+        {
+            name: 'destroyOnHide',
+            type: 'boolean',
+            default: 'false',
+            desc: '浮层子菜单隐藏时是否卸载内容 DOM；默认 false 首开后保留 DOM 仅隐藏，true 时随 open 卸载/重建。仅作用于 vertical/horizontal/collapsed 浮层子菜单',
+        },
+        {
+            name: 'getPopupContainer',
+            type: '() => HTMLElement',
+            default: '() => document.body',
+            desc: '浮层子菜单挂载容器（透传 floating action getContainer）；非 body 时改 absolute 相对该容器定位',
+        },
+        { name: 'disabled', type: 'boolean', default: 'false', desc: '整体禁用：所有项不可交互（叠加单项 disabled）' },
+        {
+            name: 'purpose',
+            type: "'menu'|'navigation'",
+            default: 'menu',
+            desc: "语义用途。'menu'（默认，向后兼容）=命令式菜单：role=menu/menuitem + roving tabindex，叶子 button+onClick。'navigation'=站点导航：<nav> landmark 包裹原生 list，含 href 的叶子渲染原生 <a href>（aria-current=page），沿用浏览器链接 + Tab 键序，不用 menuitem role。role 由 deriveMenuSemantics 纯函数据 purpose+mode+multiple 派生",
+        },
+        {
+            name: 'onSelect',
+            type: '(key: string|number) => void',
+            default: 'undefined',
+            desc: '点击叶子项回调，回传被点击的 key（多选语义不变，由父组件据此 toggle）',
+        },
+        {
+            name: 'onOpenChange',
+            type: '(keys: (string|number)[]) => void',
+            default: 'undefined',
+        },
+        { name: 'ariaLabel', type: 'string', default: 'undefined' },
+        {
+            name: 'tooltipProps',
+            type: '{ content?: string; position?: string; theme?: "dark"|"light"; mouseEnterDelay?: number; mouseLeaveDelay?: number }',
+            default: 'undefined',
+            desc: '折叠模式（inlineCollapsed=true）下顶层项的 Tooltip 配置。content 默认为项 label；position→placement 透传给 Tooltip。未提供时用原生 title 属性降级。',
+        },
+        {
+            name: 'renderWrapper',
+            type: 'Snippet<[{ item: MenuItemNode; children: Snippet }]>',
+            default: 'undefined',
+            desc: '自定义叶子项内容包裹 Snippet，接收 { item, children }。children 为默认的 <a> 或 <button>，可在外层加徽标/标签等装饰。inline/vertical/horizontal/collapsed 模式下均生效。',
+        },
+    ],
+    a11y: {
+        role: 'menu',
+        keyboard: ['Tab', 'Enter', 'Space'],
+        notes: [
+            'ul[role=menu] > li[role=none] > button[role=menuitem] 结构',
+            'SubMenu 标题 aria-haspopup=true + aria-expanded 反映展开态',
+            '选中叶子项 aria-current=true（单选）；multiple 下叶子项 role=menuitemcheckbox + aria-checked',
+            '禁用项 aria-disabled=true 且原生 disabled',
+            'divider 渲染 li[role=separator]，不可聚焦不可选；键盘导航天然跳过（非 menuitem）',
+            'group 渲染组标题（不可点击）+ ul[role=group][aria-label=分组名]，组内项正常 menuitem 可选；组标题不可聚焦故键盘跳过',
+            "purpose='navigation'：<nav aria-label> landmark 包裹原生 ul>li>a（去除 menu/menuitem/separator/group 等 role），含 href 叶子为 <a href>，当前项 aria-current=page；用浏览器原生链接 + Tab 键序导航，不接管 ←→ roving",
+            "purpose='menu'（默认）：role=menu/menubar + menuitem，叶子 button + onClick，行为完全向后兼容；role 集合由 deriveMenuSemantics(purpose, mode, multiple) 纯函数派生（红线 #2）",
+        ],
+    },
+    tokens: [
+        '--cd-menu-bg',
+        '--cd-menu-item-height',
+        '--cd-menu-item-padding',
+        '--cd-menu-item-color',
+        '--cd-menu-item-color-selected',
+        '--cd-menu-item-color-disabled',
+        '--cd-menu-item-bg-hover',
+        '--cd-menu-item-bg-selected',
+        '--cd-menu-item-indicator',
+        '--cd-menu-submenu-arrow-color',
+        '--cd-focus-ring',
+        '--cd-motion-*',
+    ],
+};

package/dist/menu/types.d.ts

@@ -0,0 +1,82 @@
+import type { Snippet } from 'svelte';
+/** Menu 项键类型。 */
+export type MenuKey = string | number;
+/** 普通菜单项；含 children 即为可展开的 SubMenu。 */
+export interface MenuItemNode {
+    /** 非分隔符/分组时无需 type，默认即普通项；显式可写 'item' */
+    type?: 'item';
+    key: MenuKey;
+    label: string;
+    disabled?: boolean;
+    /** 项前自定义图标 */
+    icon?: Snippet;
+    children?: MenuItemDef[];
+    /**
+     * 链接地址。仅 navigation 用途生效：叶子项渲染为原生 `<a href>` 走站点导航语义；
+     * menu 用途（默认命令式菜单）忽略此字段，叶子仍为 button + onClick。
+     */
+    href?: string;
+    /** 链接 target（如 '_blank'）；仅 navigation + href 渲染 `<a>` 时透传。 */
+    target?: string;
+    /** 链接 rel（如 'noopener noreferrer'）；仅 navigation + href 渲染 `<a>` 时透传。 */
+    rel?: string;
+}
+/**
+ * 分隔符项：渲染为一条水平分隔线，不可选不可聚焦（role=separator）。
+ * 无需 key/label；为避免 #each 缺 key 警告，渲染时按索引生成兜底 key。
+ */
+export interface MenuDividerNode {
+    type: 'divider';
+    key?: MenuKey;
+}
+/**
+ * 分组项：渲染为不可点击的组标题 + 其下始终展开的菜单项。
+ * 区别于 SubMenu（可展开/收起）——group 是始终展开的分区标题。
+ */
+export interface MenuGroupNode {
+    type: 'group';
+    key?: MenuKey;
+    /** 分组标题文案 */
+    label: string;
+    children: MenuItemDef[];
+}
+/**
+ * Menu 数据项。向后兼容：普通项可省略 type；
+ * 通过 type='divider' / type='group' 扩展分隔符与分组标题。
+ */
+export type MenuItemDef = MenuItemNode | MenuDividerNode | MenuGroupNode;
+/** 类型守卫：分隔符项。 */
+export declare function isDivider(item: MenuItemDef): item is MenuDividerNode;
+/** 类型守卫：分组项。 */
+export declare function isGroup(item: MenuItemDef): item is MenuGroupNode;
+/**
+ * Menu 用途（语义区分）：
+ * - 'menu'（默认）：命令式菜单，执行操作。容器 role=menu/menubar，
+ *   叶子 role=menuitem（多选 menuitemcheckbox），button + onClick，roving 键盘。
+ * - 'navigation'：站点导航。容器为 nav landmark（无 menu role），
+ *   含 href 的叶子渲染原生 `<a href>`，沿用浏览器原生链接 + Tab 键序，不用 menuitem role。
+ */
+export type MenuPurpose = 'menu' | 'navigation';
+/** 容器 ARIA 角色集合，由 purpose + mode 纯函数派生（红线 #2）。 */
+export interface MenuSemantics {
+    /** 是否为 navigation 用途（原生链接语义）。 */
+    navigation: boolean;
+    /** 最外层 ul 的 role；navigation 下为 undefined（用原生 list 语义 + nav landmark 包裹）。 */
+    listRole: 'menu' | 'menubar' | undefined;
+    /** 叶子项控件 role；navigation 下为 undefined（原生 a/button 语义）。 */
+    leafRole: 'menuitem' | 'menuitemcheckbox' | undefined;
+    /** SubMenu 标题控件 role；navigation 下为 undefined。 */
+    submenuTitleRole: 'menuitem' | undefined;
+    /** 内嵌/浮层子列表 role；navigation 下为 undefined。 */
+    subListRole: 'menu' | undefined;
+    /** 分组/分隔等结构 li 的 role（none）；navigation 下为 undefined（原生 li）。 */
+    structuralRole: 'none' | undefined;
+    /** group 子列表 role；navigation 下为 undefined。 */
+    groupListRole: 'group' | undefined;
+}
+/**
+ * 纯函数：据 purpose + mode + multiple 派生容器/项的 ARIA 角色。
+ * 无副作用、不读 DOM/registry（红线 #2）。
+ */
+export declare function deriveMenuSemantics(purpose: MenuPurpose, mode: 'vertical' | 'inline' | 'horizontal', multiple: boolean): MenuSemantics;
+//# sourceMappingURL=types.d.ts.map

package/dist/menu/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/menu/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,iBAAiB;AACjB,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtC,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,eAAe,GAAG,aAAa,CAAC;AAEzE,iBAAiB;AACjB,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,eAAe,CAEpE;AAED,gBAAgB;AAChB,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,aAAa,CAEhE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,YAAY,CAAC;AAEhD,kDAAkD;AAClD,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,UAAU,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC,0DAA0D;IAC1D,QAAQ,EAAE,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACtD,iDAAiD;IACjD,gBAAgB,EAAE,UAAU,GAAG,SAAS,CAAC;IACzC,6CAA6C;IAC7C,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,+DAA+D;IAC/D,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,8CAA8C;IAC9C,aAAa,EAAE,OAAO,GAAG,SAAS,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,UAAU,GAAG,QAAQ,GAAG,YAAY,EAC1C,QAAQ,EAAE,OAAO,GAChB,aAAa,CAqBf"}

package/dist/menu/types.js

@@ -0,0 +1,34 @@
+/** 类型守卫：分隔符项。 */
+export function isDivider(item) {
+    return item.type === 'divider';
+}
+/** 类型守卫：分组项。 */
+export function isGroup(item) {
+    return item.type === 'group';
+}
+/**
+ * 纯函数：据 purpose + mode + multiple 派生容器/项的 ARIA 角色。
+ * 无副作用、不读 DOM/registry（红线 #2）。
+ */
+export function deriveMenuSemantics(purpose, mode, multiple) {
+    if (purpose === 'navigation') {
+        return {
+            navigation: true,
+            listRole: undefined,
+            leafRole: undefined,
+            submenuTitleRole: undefined,
+            subListRole: undefined,
+            structuralRole: undefined,
+            groupListRole: undefined,
+        };
+    }
+    return {
+        navigation: false,
+        listRole: mode === 'horizontal' ? 'menubar' : 'menu',
+        leafRole: multiple ? 'menuitemcheckbox' : 'menuitem',
+        submenuTitleRole: 'menuitem',
+        subListRole: 'menu',
+        structuralRole: 'none',
+        groupListRole: 'group',
+    };
+}

package/dist/meta.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=meta.test.d.ts.map

package/dist/meta.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.test.d.ts","sourceRoot":"","sources":["../src/meta.test.ts"],"names":[],"mappings":""}

package/dist/meta.test.js

@@ -0,0 +1,164 @@
+import { describe, expect, it } from 'vitest';
+import { meta as buttonMeta } from './button/meta.js';
+import { meta as iconMeta } from './icon/meta.js';
+import { meta as dividerMeta } from './divider/meta.js';
+import { meta as spaceMeta } from './space/meta.js';
+import { meta as typographyMeta } from './typography/meta.js';
+import { meta as gridMeta } from './grid/meta.js';
+import { meta as layoutMeta } from './layout/meta.js';
+import { meta as inputMeta } from './input/meta.js';
+import { meta as textareaMeta } from './textarea/meta.js';
+import { meta as switchMeta } from './switch/meta.js';
+import { meta as checkboxMeta } from './checkbox/meta.js';
+import { meta as radioMeta } from './radio/meta.js';
+import { meta as inputNumberMeta } from './input-number/meta.js';
+import { meta as ratingMeta } from './rating/meta.js';
+import { meta as sliderMeta } from './slider/meta.js';
+import { meta as formMeta } from './form/meta.js';
+import { meta as selectMeta } from './select/meta.js';
+import { meta as autocompleteMeta } from './autocomplete/meta.js';
+import { meta as tagInputMeta } from './tag-input/meta.js';
+import { meta as colorPickerMeta } from './color-picker/meta.js';
+import { meta as datePickerMeta } from './date-picker/meta.js';
+import { meta as timePickerMeta } from './time-picker/meta.js';
+import { meta as cascaderMeta } from './cascader/meta.js';
+import { meta as treeSelectMeta } from './tree-select/meta.js';
+import { meta as transferMeta } from './transfer/meta.js';
+import { meta as uploadMeta } from './upload/meta.js';
+import { meta as breadcrumbMeta } from './breadcrumb/meta.js';
+import { meta as paginationMeta } from './pagination/meta.js';
+import { meta as stepsMeta } from './steps/meta.js';
+import { meta as tabsMeta } from './tabs/meta.js';
+import { meta as dropdownMeta } from './dropdown/meta.js';
+import { meta as menuMeta } from './menu/meta.js';
+import { meta as anchorMeta } from './anchor/meta.js';
+import { meta as tagMeta } from './tag/meta.js';
+import { meta as avatarMeta } from './avatar/meta.js';
+import { meta as badgeMeta } from './badge/meta.js';
+import { meta as cardMeta } from './card/meta.js';
+import { meta as tooltipMeta } from './tooltip/meta.js';
+import { meta as popoverMeta } from './popover/meta.js';
+import { meta as emptyMeta } from './empty/meta.js';
+import { meta as descriptionsMeta } from './descriptions/meta.js';
+import { meta as collapseMeta } from './collapse/meta.js';
+import { meta as timelineMeta } from './timeline/meta.js';
+import { meta as listMeta } from './list/meta.js';
+import { meta as imageMeta } from './image/meta.js';
+import { meta as highlightMeta } from './highlight/meta.js';
+import { meta as virtualListMeta } from './virtual-list/meta.js';
+import { meta as carouselMeta } from './carousel/meta.js';
+import { meta as treeMeta } from './tree/meta.js';
+import { meta as tableMeta } from './table/meta.js';
+import { meta as calendarMeta } from './calendar/meta.js';
+import { meta as scrollListMeta } from './scroll-list/meta.js';
+import { meta as overflowListMeta } from './overflow-list/meta.js';
+import { meta as spinMeta } from './spin/meta.js';
+import { meta as progressMeta } from './progress/meta.js';
+import { meta as skeletonMeta } from './skeleton/meta.js';
+import { meta as bannerMeta } from './banner/meta.js';
+import { meta as modalMeta } from './modal/meta.js';
+import { meta as popconfirmMeta } from './popconfirm/meta.js';
+import { meta as drawerMeta } from './drawer/meta.js';
+import { meta as sideSheetMeta } from './side-sheet/meta.js';
+import { meta as toastMeta } from './toast/meta.js';
+import { meta as notificationMeta } from './notification/meta.js';
+import { meta as backTopMeta } from './back-top/meta.js';
+import { meta as localeProviderMeta } from './locale-provider/meta.js';
+import { meta as configProviderMeta } from './config-provider/meta.js';
+import { meta as resizeObserverMeta } from './resize-observer/meta.js';
+import { meta as lottieIconMeta } from './lottie-icon/meta.js';
+const metas = {
+    buttonMeta,
+    iconMeta,
+    dividerMeta,
+    spaceMeta,
+    typographyMeta,
+    gridMeta,
+    layoutMeta,
+    inputMeta,
+    textareaMeta,
+    switchMeta,
+    checkboxMeta,
+    radioMeta,
+    inputNumberMeta,
+    ratingMeta,
+    sliderMeta,
+    formMeta,
+    selectMeta,
+    autocompleteMeta,
+    tagInputMeta,
+    colorPickerMeta,
+    datePickerMeta,
+    timePickerMeta,
+    cascaderMeta,
+    treeSelectMeta,
+    transferMeta,
+    uploadMeta,
+    breadcrumbMeta,
+    paginationMeta,
+    stepsMeta,
+    tabsMeta,
+    dropdownMeta,
+    menuMeta,
+    anchorMeta,
+    tagMeta,
+    avatarMeta,
+    badgeMeta,
+    cardMeta,
+    tooltipMeta,
+    popoverMeta,
+    emptyMeta,
+    descriptionsMeta,
+    collapseMeta,
+    timelineMeta,
+    listMeta,
+    imageMeta,
+    highlightMeta,
+    virtualListMeta,
+    carouselMeta,
+    treeMeta,
+    tableMeta,
+    calendarMeta,
+    scrollListMeta,
+    overflowListMeta,
+    spinMeta,
+    progressMeta,
+    skeletonMeta,
+    bannerMeta,
+    modalMeta,
+    popconfirmMeta,
+    drawerMeta,
+    sideSheetMeta,
+    toastMeta,
+    notificationMeta,
+    backTopMeta,
+    localeProviderMeta,
+    configProviderMeta,
+    resizeObserverMeta,
+    lottieIconMeta,
+};
+/** collect prop entries from either a flat `props` or aggregated `subComponents[].props` */
+function allProps(m) {
+    if (Array.isArray(m.props))
+        return m.props;
+    if (Array.isArray(m.subComponents)) {
+        return m.subComponents.flatMap((sc) => sc.props ?? []);
+    }
+    return [];
+}
+describe('component metadata', () => {
+    it.each(Object.entries(metas))('%s is well-formed', (_name, m) => {
+        expect(m.name).toBeTruthy();
+        expect(['basic', 'input', 'navigation', 'show', 'feedback', 'other']).toContain(m.category);
+        expect(m.description).toBeTruthy();
+        expect(allProps(m).length).toBeGreaterThan(0);
+    });
+    it('every prop entry has name and type', () => {
+        for (const m of Object.values(metas)) {
+            for (const p of allProps(m)) {
+                expect(p.name, `${m.name} prop`).toBeTruthy();
+                expect(p.type, `${m.name}.${p.name} type`).toBeTruthy();
+            }
+        }
+    });
+});