@chenzy-design/svelte 0.2.1 → 0.3.1

package/dist/nav/NavSub.svelte

@@ -0,0 +1,57 @@
+<!--
+  Nav.Sub — 声明式可展开子导航（对齐 Semi Nav.Sub）。
+  注册自身描述符（含空 items 数组）到父收集器，并向 children 提供新的收集器，
+  使内嵌的 Nav.Item / Nav.Sub 按 DOM 顺序 push 进自己的 items（普通数组，嵌套树）。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { onMount, setContext } from 'svelte';
+  import { getNavCollector, NAV_COLLECTOR_KEY, type NavCollector } from './context.js';
+  import type { NavItemDef, NavKey } from './types.js';
+
+  interface Props {
+    /** 子导航唯一标识。 */
+    itemKey: NavKey;
+    /** 子导航标题文案。 */
+    text: string;
+    /** 标题前置图标。 */
+    icon?: Snippet;
+    /** 是否禁用。 */
+    disabled?: boolean;
+    /** 内嵌的 Nav.Item / Nav.Sub。 */
+    children?: Snippet;
+  }
+
+  let { itemKey, text, icon, disabled, children }: Props = $props();
+
+  const parent = getNavCollector();
+
+  // 自身描述符：items 为普通数组，承接子项注册。
+  // 声明式项「声明时读取一次」语义（对齐 Semi），静态读取，警告预期且无害。
+  const childItems: NavItemDef[] = [];
+  // svelte-ignore state_referenced_locally
+  const selfDescriptor: NavItemDef = {
+    itemKey,
+    text,
+    items: childItems,
+    ...(icon !== undefined ? { icon } : {}),
+    ...(disabled !== undefined ? { disabled } : {}),
+  };
+
+  // init 同步注册到父级（普通数组）。
+  if (parent) parent.add(selfDescriptor);
+
+  // 向 children 提供收集器：add 写入自身 childItems；bump 继续上抛父级（合并为一次）。
+  const childCollector: NavCollector = {
+    add: (item: NavItemDef) => {
+      childItems.push(item);
+      return item;
+    },
+    bump: () => parent?.bump(),
+  };
+  setContext(NAV_COLLECTOR_KEY, childCollector);
+
+  onMount(() => parent?.bump());
+</script>
+
+{#if children}{@render children()}{/if}

package/dist/nav/NavSub.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { Snippet } from 'svelte';
+import type { NavKey } from './types.js';
+interface Props {
+    /** 子导航唯一标识。 */
+    itemKey: NavKey;
+    /** 子导航标题文案。 */
+    text: string;
+    /** 标题前置图标。 */
+    icon?: Snippet;
+    /** 是否禁用。 */
+    disabled?: boolean;
+    /** 内嵌的 Nav.Item / Nav.Sub。 */
+    children?: Snippet;
+}
+declare const NavSub: import("svelte").Component<Props, {}, "">;
+type NavSub = ReturnType<typeof NavSub>;
+export default NavSub;
+//# sourceMappingURL=NavSub.svelte.d.ts.map

package/dist/nav/NavSub.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NavSub.svelte.d.ts","sourceRoot":"","sources":["../../src/nav/NavSub.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EAAc,MAAM,EAAE,MAAM,YAAY,CAAC;AAGnD,UAAU,KAAK;IACb,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe;IACf,IAAI,EAAE,MAAM,CAAC;IACb,cAAc;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA6CH,QAAA,MAAM,MAAM,2CAAwC,CAAC;AACrD,KAAK,MAAM,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC;AACxC,eAAe,MAAM,CAAC"}

package/dist/nav/context.d.ts

@@ -0,0 +1,31 @@
+import type { NavItemDef } from './types.js';
+export interface NavContext {
+    /** 当前是否折叠（仅 vertical 有意义）。 */
+    readonly collapsed: boolean;
+    /** 当前模式。 */
+    readonly mode: 'vertical' | 'horizontal';
+    /** 切换折叠态。 */
+    toggleCollapsed: () => void;
+}
+export declare const NAV_CONTEXT_KEY: unique symbol;
+/** Nav.Footer 内部读取 Nav 上下文（无则 undefined）。 */
+export declare function getNavContext(): NavContext | undefined;
+/**
+ * 声明式子项收集上下文（Nav.Item / Nav.Sub）。
+ *
+ * 安全约束（见记忆 svelte5-child-register-state-array-loop）：
+ * - 子项注册写入的 children 是【普通数组】（非 $state），子项 init 同步 push，不在 effect 里写 $state。
+ * - 触发 Nav 重建 items 的反应量是单独一个 $state revision，子项在挂载后【异步】bump 一次，
+ *   脱离挂载 effect 同步栈，避免读写自循环。
+ * - Nav.Sub 向下提供一个新的 collector，其 children 指向自己 descriptor 的 children 数组，
+ *   从而把嵌套结构按 DOM 顺序、按层级收进普通数组树。
+ */
+export interface NavCollector {
+    /** 把一个子项描述符按声明顺序 push 进当前层级的普通数组，返回该描述符（供 Sub 取其 children）。 */
+    add: (item: NavItemDef) => NavItemDef;
+    /** 挂载后异步触发一次 Nav 重建（合并多次为一次）。 */
+    bump: () => void;
+}
+export declare const NAV_COLLECTOR_KEY: unique symbol;
+export declare function getNavCollector(): NavCollector | undefined;
+//# sourceMappingURL=context.d.ts.map

package/dist/nav/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/nav/context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,YAAY;IACZ,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY,CAAC;IACzC,aAAa;IACb,eAAe,EAAE,MAAM,IAAI,CAAC;CAC7B;AAED,eAAO,MAAM,eAAe,eAAmB,CAAC;AAEhD,6CAA6C;AAC7C,wBAAgB,aAAa,IAAI,UAAU,GAAG,SAAS,CAEtD;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,GAAG,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU,CAAC;IACtC,iCAAiC;IACjC,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,eAAO,MAAM,iBAAiB,eAA6B,CAAC;AAE5D,wBAAgB,eAAe,IAAI,YAAY,GAAG,SAAS,CAI1D"}

package/dist/nav/context.js

@@ -0,0 +1,15 @@
+/**
+ * Nav 上下文：折叠联动（Footer）+ 声明式子项收集（Nav.Item/Nav.Sub）。
+ */
+import { getContext, hasContext } from 'svelte';
+export const NAV_CONTEXT_KEY = Symbol('cd-nav');
+/** Nav.Footer 内部读取 Nav 上下文（无则 undefined）。 */
+export function getNavContext() {
+    return hasContext(NAV_CONTEXT_KEY) ? getContext(NAV_CONTEXT_KEY) : undefined;
+}
+export const NAV_COLLECTOR_KEY = Symbol('cd-nav-collector');
+export function getNavCollector() {
+    return hasContext(NAV_COLLECTOR_KEY)
+        ? getContext(NAV_COLLECTOR_KEY)
+        : undefined;
+}

package/dist/nav/index.d.ts

@@ -0,0 +1,20 @@
+import NavRoot from './Nav.svelte';
+import NavHeader from './NavHeader.svelte';
+import NavFooter from './NavFooter.svelte';
+import NavItem from './NavItem.svelte';
+import NavSub from './NavSub.svelte';
+/** Named exports (also usable directly). */
+export { NavHeader, NavFooter, NavItem, NavSub };
+/**
+ * Aggregated namespace export: enables <Nav.Header /> / <Nav.Footer /> / <Nav.Item /> / <Nav.Sub />.
+ * Explicit type annotation avoids leaking component Props type errors.
+ */
+export declare const Nav: typeof NavRoot & {
+    Header: typeof NavHeader;
+    Footer: typeof NavFooter;
+    Item: typeof NavItem;
+    Sub: typeof NavSub;
+};
+export { meta as navMeta } from './meta.js';
+export type { NavItemDef, NavKey, NavMode, NavHeaderConfig, NavFooterConfig } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/nav/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,SAAS,MAAM,oBAAoB,CAAC;AAC3C,OAAO,SAAS,MAAM,oBAAoB,CAAC;AAC3C,OAAO,OAAO,MAAM,kBAAkB,CAAC;AACvC,OAAO,MAAM,MAAM,iBAAiB,CAAC;AAErC,4CAA4C;AAC5C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,GAAG,EAAE,OAAO,OAAO,GAAG;IACjC,MAAM,EAAE,OAAO,SAAS,CAAC;IACzB,MAAM,EAAE,OAAO,SAAS,CAAC;IACzB,IAAI,EAAE,OAAO,OAAO,CAAC;IACrB,GAAG,EAAE,OAAO,MAAM,CAAC;CAMnB,CAAC;AAEH,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/nav/index.js

@@ -0,0 +1,18 @@
+import NavRoot from './Nav.svelte';
+import NavHeader from './NavHeader.svelte';
+import NavFooter from './NavFooter.svelte';
+import NavItem from './NavItem.svelte';
+import NavSub from './NavSub.svelte';
+/** Named exports (also usable directly). */
+export { NavHeader, NavFooter, NavItem, NavSub };
+/**
+ * Aggregated namespace export: enables <Nav.Header /> / <Nav.Footer /> / <Nav.Item /> / <Nav.Sub />.
+ * Explicit type annotation avoids leaking component Props type errors.
+ */
+export const Nav = Object.assign(NavRoot, {
+    Header: NavHeader,
+    Footer: NavFooter,
+    Item: NavItem,
+    Sub: NavSub,
+});
+export { meta as navMeta } from './meta.js';

package/dist/nav/meta.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export declare const meta: {
+    readonly name: "Nav";
+    readonly category: "navigation";
+    readonly description: "站点导航菜单（对齐 Semi Navigation）。支持垂直/水平模式、子导航、logo 头部、折叠按钮。字段对齐 Semi（itemKey/text/icon/items），内部委托 Menu 渲染导航体。";
+    readonly props: readonly [{
+        readonly name: "items";
+        readonly type: "NavItemDef[]";
+        readonly default: "[]";
+        readonly desc: "导航项列表，字段对齐 Semi：itemKey/text/icon/items（含 items 即子导航）";
+    }, {
+        readonly name: "mode";
+        readonly type: "'vertical'|'horizontal'";
+        readonly default: "'vertical'";
+        readonly desc: "导航方向：侧边/顶部";
+    }, {
+        readonly name: "selectedKeys";
+        readonly type: "NavKey[]";
+        readonly default: "undefined";
+        readonly desc: "受控选中项 key 数组";
+    }, {
+        readonly name: "defaultSelectedKeys";
+        readonly type: "NavKey[]";
+        readonly default: "undefined";
+        readonly desc: "默认选中项 key 数组";
+    }, {
+        readonly name: "openKeys";
+        readonly type: "NavKey[]";
+        readonly default: "undefined";
+        readonly desc: "受控展开子导航 key（vertical 且未折叠有效）";
+    }, {
+        readonly name: "defaultOpenKeys";
+        readonly type: "NavKey[]";
+        readonly default: "undefined";
+        readonly desc: "默认展开子导航 key";
+    }, {
+        readonly name: "isCollapsed";
+        readonly type: "boolean";
+        readonly default: "undefined";
+        readonly desc: "受控折叠态（仅 vertical 有效）";
+    }, {
+        readonly name: "defaultIsCollapsed";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "默认折叠态（仅 vertical 有效）";
+    }, {
+        readonly name: "header";
+        readonly type: "{ logo?: Snippet; text?: string }";
+        readonly default: "undefined";
+        readonly desc: "头部配置（logo + 文案）";
+    }, {
+        readonly name: "footer";
+        readonly type: "{ collapseButton?: boolean }";
+        readonly default: "undefined";
+        readonly desc: "底部配置（收起按钮，仅 vertical）";
+    }, {
+        readonly name: "disabled";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "整体禁用";
+    }, {
+        readonly name: "inlineIndent";
+        readonly type: "number";
+        readonly default: "24";
+        readonly desc: "子级缩进像素（透传 Menu）";
+    }, {
+        readonly name: "limitIndent";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "仅一级缩进；false 时逐级缩进";
+    }, {
+        readonly name: "toggleIconPosition";
+        readonly type: "'left'|'right'";
+        readonly default: "'right'";
+        readonly desc: "子导航展开箭头位置";
+    }, {
+        readonly name: "expandIcon";
+        readonly type: "Snippet";
+        readonly default: "undefined";
+        readonly desc: "自定义展开箭头图标";
+    }, {
+        readonly name: "subNavMotion";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "子导航展开动画开关";
+    }, {
+        readonly name: "subNavOpenDelay";
+        readonly type: "number";
+        readonly default: "undefined";
+        readonly desc: "浮层子导航展开延迟 ms";
+    }, {
+        readonly name: "subNavCloseDelay";
+        readonly type: "number";
+        readonly default: "undefined";
+        readonly desc: "浮层子导航关闭延迟 ms";
+    }, {
+        readonly name: "getPopupContainer";
+        readonly type: "() => HTMLElement";
+        readonly default: "undefined";
+        readonly desc: "浮层挂载容器";
+    }, {
+        readonly name: "renderWrapper";
+        readonly type: "Snippet";
+        readonly default: "undefined";
+        readonly desc: "自定义导航项外层包裹";
+    }, {
+        readonly name: "class";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "根元素自定义类名";
+    }, {
+        readonly name: "style";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "根元素自定义内联样式";
+    }, {
+        readonly name: "bodyStyle";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "导航项列表容器样式（对齐 Semi bodyStyle）";
+    }, {
+        readonly name: "ariaLabel";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "可访问性标签";
+    }];
+    readonly events: readonly [{
+        readonly name: "onSelect";
+        readonly payload: "NavKey";
+        readonly desc: "选中导航项时触发";
+    }, {
+        readonly name: "onClick";
+        readonly payload: "NavKey";
+        readonly desc: "点击任意导航项时触发";
+    }, {
+        readonly name: "onOpenChange";
+        readonly payload: "NavKey[]";
+        readonly desc: "展开/收起子导航时触发";
+    }, {
+        readonly name: "onCollapseChange";
+        readonly payload: "boolean";
+        readonly desc: "折叠态变化时触发";
+    }];
+    readonly slots: readonly [{
+        readonly name: "headerSlot";
+        readonly desc: "自定义头部（覆盖 header 配置对象）";
+    }, {
+        readonly name: "footerSlot";
+        readonly desc: "自定义底部（覆盖 footer 配置对象）";
+    }, {
+        readonly name: "children";
+        readonly desc: "声明式子项（<Nav.Item>/<Nav.Sub>），与 items 二选一";
+    }];
+    readonly subComponents: readonly [{
+        readonly name: "Nav.Header";
+        readonly element: "div";
+        readonly props: readonly [{
+            readonly name: "logo";
+            readonly type: "Snippet";
+            readonly default: "undefined";
+            readonly desc: "Logo 节点";
+        }, {
+            readonly name: "text";
+            readonly type: "string";
+            readonly default: "undefined";
+            readonly desc: "Logo 文案";
+        }, {
+            readonly name: "class";
+            readonly type: "string";
+            readonly default: "undefined";
+            readonly desc: "自定义类名";
+        }, {
+            readonly name: "style";
+            readonly type: "string";
+            readonly default: "undefined";
+            readonly desc: "自定义内联样式";
+        }];
+    }, {
+        readonly name: "Nav.Footer";
+        readonly element: "div";
+        readonly props: readonly [{
+            readonly name: "collapseButton";
+            readonly type: "boolean";
+            readonly default: "false";
+            readonly desc: "收起按钮（仅 vertical 生效）";
+        }, {
+            readonly name: "class";
+            readonly type: "string";
+            readonly default: "undefined";
+            readonly desc: "自定义类名";
+        }, {
+            readonly name: "style";
+            readonly type: "string";
+            readonly default: "undefined";
+            readonly desc: "自定义内联样式";
+        }];
+    }, {
+        readonly name: "Nav.Item";
+        readonly element: "—";
+        readonly props: readonly [{
+            readonly name: "itemKey";
+            readonly type: "NavKey";
+            readonly default: "—";
+            readonly desc: "导航项唯一标识（必填）";
+        }, {
+            readonly name: "text";
+            readonly type: "string";
+            readonly default: "—";
+            readonly desc: "导航项文案";
+        }, {
+            readonly name: "icon";
+            readonly type: "Snippet";
+            readonly default: "undefined";
+            readonly desc: "项前置图标";
+        }, {
+            readonly name: "disabled";
+            readonly type: "boolean";
+            readonly default: "undefined";
+            readonly desc: "是否禁用";
+        }, {
+            readonly name: "link";
+            readonly type: "string";
+            readonly default: "undefined";
+            readonly desc: "链接地址（渲染原生 <a>）";
+        }, {
+            readonly name: "target";
+            readonly type: "string";
+            readonly default: "undefined";
+            readonly desc: "链接 target";
+        }, {
+            readonly name: "rel";
+            readonly type: "string";
+            readonly default: "undefined";
+            readonly desc: "链接 rel";
+        }, {
+            readonly name: "onClick";
+            readonly type: "(e: MouseEvent) => void";
+            readonly default: "undefined";
+            readonly desc: "项级点击回调";
+        }, {
+            readonly name: "onMouseEnter";
+            readonly type: "(e: MouseEvent) => void";
+            readonly default: "undefined";
+            readonly desc: "鼠标移入";
+        }, {
+            readonly name: "onMouseLeave";
+            readonly type: "(e: MouseEvent) => void";
+            readonly default: "undefined";
+            readonly desc: "鼠标移出";
+        }];
+    }, {
+        readonly name: "Nav.Sub";
+        readonly element: "—";
+        readonly props: readonly [{
+            readonly name: "itemKey";
+            readonly type: "NavKey";
+            readonly default: "—";
+            readonly desc: "子导航唯一标识（必填）";
+        }, {
+            readonly name: "text";
+            readonly type: "string";
+            readonly default: "—";
+            readonly desc: "子导航标题文案";
+        }, {
+            readonly name: "icon";
+            readonly type: "Snippet";
+            readonly default: "undefined";
+            readonly desc: "标题前置图标";
+        }, {
+            readonly name: "disabled";
+            readonly type: "boolean";
+            readonly default: "undefined";
+            readonly desc: "是否禁用";
+        }, {
+            readonly name: "children";
+            readonly type: "Snippet";
+            readonly default: "undefined";
+            readonly desc: "内嵌 Nav.Item / Nav.Sub";
+        }];
+    }];
+    readonly a11y: {
+        readonly role: "navigation";
+        readonly keyboard: readonly ["Tab", "Shift+Tab", "Enter"];
+        readonly notes: readonly ["委托 Menu purpose=navigation：渲染 <nav> landmark + 含 link 的叶子为原生 <a>", "选中项 aria-current=page；折叠按钮原生 button + aria-expanded + aria-label"];
+    };
+    readonly tokens: readonly ["--cd-nav-*"];
+    readonly aiHints: readonly ["侧边导航用 mode=vertical + footer={{collapseButton:true}}；顶部导航用 mode=horizontal。", "items 字段对齐 Semi：itemKey/text/icon/items（非 Menu 的 key/label）。", "配合 Layout：<Layout.Sider><Nav mode=vertical/></Layout.Sider> 或 <Layout.Header><Nav mode=horizontal/></Layout.Header>。"];
+    readonly examples: readonly [{
+        readonly title: "侧边导航";
+        readonly code: "<Nav mode=\"vertical\" items={items} header={{logo, text:\"后台\"}} footer={{collapseButton:true}} />";
+    }];
+};
+//# sourceMappingURL=meta.d.ts.map

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

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

package/dist/nav/meta.js

@@ -0,0 +1,119 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+    name: 'Nav',
+    category: 'navigation',
+    description: '站点导航菜单（对齐 Semi Navigation）。支持垂直/水平模式、子导航、logo 头部、折叠按钮。字段对齐 Semi（itemKey/text/icon/items），内部委托 Menu 渲染导航体。',
+    props: [
+        {
+            name: 'items',
+            type: 'NavItemDef[]',
+            default: '[]',
+            desc: '导航项列表，字段对齐 Semi：itemKey/text/icon/items（含 items 即子导航）',
+        },
+        { name: 'mode', type: "'vertical'|'horizontal'", default: "'vertical'", desc: '导航方向：侧边/顶部' },
+        { name: 'selectedKeys', type: 'NavKey[]', default: 'undefined', desc: '受控选中项 key 数组' },
+        { name: 'defaultSelectedKeys', type: 'NavKey[]', default: 'undefined', desc: '默认选中项 key 数组' },
+        { name: 'openKeys', type: 'NavKey[]', default: 'undefined', desc: '受控展开子导航 key（vertical 且未折叠有效）' },
+        { name: 'defaultOpenKeys', type: 'NavKey[]', default: 'undefined', desc: '默认展开子导航 key' },
+        { name: 'isCollapsed', type: 'boolean', default: 'undefined', desc: '受控折叠态（仅 vertical 有效）' },
+        { name: 'defaultIsCollapsed', type: 'boolean', default: 'false', desc: '默认折叠态（仅 vertical 有效）' },
+        { name: 'header', type: '{ logo?: Snippet; text?: string }', default: 'undefined', desc: '头部配置（logo + 文案）' },
+        { name: 'footer', type: '{ collapseButton?: boolean }', default: 'undefined', desc: '底部配置（收起按钮，仅 vertical）' },
+        { name: 'disabled', type: 'boolean', default: 'false', desc: '整体禁用' },
+        { name: 'inlineIndent', type: 'number', default: '24', desc: '子级缩进像素（透传 Menu）' },
+        { name: 'limitIndent', type: 'boolean', default: 'true', desc: '仅一级缩进；false 时逐级缩进' },
+        { name: 'toggleIconPosition', type: "'left'|'right'", default: "'right'", desc: '子导航展开箭头位置' },
+        { name: 'expandIcon', type: 'Snippet', default: 'undefined', desc: '自定义展开箭头图标' },
+        { name: 'subNavMotion', type: 'boolean', default: 'true', desc: '子导航展开动画开关' },
+        { name: 'subNavOpenDelay', type: 'number', default: 'undefined', desc: '浮层子导航展开延迟 ms' },
+        { name: 'subNavCloseDelay', type: 'number', default: 'undefined', desc: '浮层子导航关闭延迟 ms' },
+        { name: 'getPopupContainer', type: '() => HTMLElement', default: 'undefined', desc: '浮层挂载容器' },
+        { name: 'renderWrapper', type: 'Snippet', default: 'undefined', desc: '自定义导航项外层包裹' },
+        { name: 'class', type: 'string', default: 'undefined', desc: '根元素自定义类名' },
+        { name: 'style', type: 'string', default: 'undefined', desc: '根元素自定义内联样式' },
+        { name: 'bodyStyle', type: 'string', default: 'undefined', desc: '导航项列表容器样式（对齐 Semi bodyStyle）' },
+        { name: 'ariaLabel', type: 'string', default: 'undefined', desc: '可访问性标签' },
+    ],
+    events: [
+        { name: 'onSelect', payload: 'NavKey', desc: '选中导航项时触发' },
+        { name: 'onClick', payload: 'NavKey', desc: '点击任意导航项时触发' },
+        { name: 'onOpenChange', payload: 'NavKey[]', desc: '展开/收起子导航时触发' },
+        { name: 'onCollapseChange', payload: 'boolean', desc: '折叠态变化时触发' },
+    ],
+    slots: [
+        { name: 'headerSlot', desc: '自定义头部（覆盖 header 配置对象）' },
+        { name: 'footerSlot', desc: '自定义底部（覆盖 footer 配置对象）' },
+        { name: 'children', desc: '声明式子项（<Nav.Item>/<Nav.Sub>），与 items 二选一' },
+    ],
+    subComponents: [
+        {
+            name: 'Nav.Header',
+            element: 'div',
+            props: [
+                { name: 'logo', type: 'Snippet', default: 'undefined', desc: 'Logo 节点' },
+                { name: 'text', type: 'string', default: 'undefined', desc: 'Logo 文案' },
+                { name: 'class', type: 'string', default: 'undefined', desc: '自定义类名' },
+                { name: 'style', type: 'string', default: 'undefined', desc: '自定义内联样式' },
+            ],
+        },
+        {
+            name: 'Nav.Footer',
+            element: 'div',
+            props: [
+                { name: 'collapseButton', type: 'boolean', default: 'false', desc: '收起按钮（仅 vertical 生效）' },
+                { name: 'class', type: 'string', default: 'undefined', desc: '自定义类名' },
+                { name: 'style', type: 'string', default: 'undefined', desc: '自定义内联样式' },
+            ],
+        },
+        {
+            name: 'Nav.Item',
+            element: '—',
+            props: [
+                { name: 'itemKey', type: 'NavKey', default: '—', desc: '导航项唯一标识（必填）' },
+                { name: 'text', type: 'string', default: '—', desc: '导航项文案' },
+                { name: 'icon', type: 'Snippet', default: 'undefined', desc: '项前置图标' },
+                { name: 'disabled', type: 'boolean', default: 'undefined', desc: '是否禁用' },
+                { name: 'link', type: 'string', default: 'undefined', desc: '链接地址（渲染原生 <a>）' },
+                { name: 'target', type: 'string', default: 'undefined', desc: '链接 target' },
+                { name: 'rel', type: 'string', default: 'undefined', desc: '链接 rel' },
+                { name: 'onClick', type: '(e: MouseEvent) => void', default: 'undefined', desc: '项级点击回调' },
+                { name: 'onMouseEnter', type: '(e: MouseEvent) => void', default: 'undefined', desc: '鼠标移入' },
+                { name: 'onMouseLeave', type: '(e: MouseEvent) => void', default: 'undefined', desc: '鼠标移出' },
+            ],
+        },
+        {
+            name: 'Nav.Sub',
+            element: '—',
+            props: [
+                { name: 'itemKey', type: 'NavKey', default: '—', desc: '子导航唯一标识（必填）' },
+                { name: 'text', type: 'string', default: '—', desc: '子导航标题文案' },
+                { name: 'icon', type: 'Snippet', default: 'undefined', desc: '标题前置图标' },
+                { name: 'disabled', type: 'boolean', default: 'undefined', desc: '是否禁用' },
+                { name: 'children', type: 'Snippet', default: 'undefined', desc: '内嵌 Nav.Item / Nav.Sub' },
+            ],
+        },
+    ],
+    a11y: {
+        role: 'navigation',
+        keyboard: ['Tab', 'Shift+Tab', 'Enter'],
+        notes: [
+            '委托 Menu purpose=navigation：渲染 <nav> landmark + 含 link 的叶子为原生 <a>',
+            '选中项 aria-current=page；折叠按钮原生 button + aria-expanded + aria-label',
+        ],
+    },
+    tokens: ['--cd-nav-*'],
+    aiHints: [
+        '侧边导航用 mode=vertical + footer={{collapseButton:true}}；顶部导航用 mode=horizontal。',
+        'items 字段对齐 Semi：itemKey/text/icon/items（非 Menu 的 key/label）。',
+        '配合 Layout：<Layout.Sider><Nav mode=vertical/></Layout.Sider> 或 <Layout.Header><Nav mode=horizontal/></Layout.Header>。',
+    ],
+    examples: [
+        {
+            title: '侧边导航',
+            code: '<Nav mode="vertical" items={items} header={{logo, text:"后台"}} footer={{collapseButton:true}} />',
+        },
+    ],
+};

package/dist/nav/types.d.ts

@@ -0,0 +1,52 @@
+import type { Snippet } from 'svelte';
+import type { MenuItemDef } from '../menu/types.js';
+/** Nav 项键类型（对齐 Semi itemKey）。 */
+export type NavKey = string | number;
+/** Nav 模式：垂直（侧边）或水平（顶部）。对齐 Semi mode。 */
+export type NavMode = 'vertical' | 'horizontal';
+/**
+ * Nav 导航项（字段对齐 Semi：itemKey / text / icon / items）。
+ * 含 items 即为可展开子导航。Nav 内部映射为 Menu 的 MenuItemDef 渲染。
+ */
+export interface NavItemDef {
+    /** 导航项唯一标识（对齐 Semi itemKey）。 */
+    itemKey: NavKey;
+    /** 导航项文案（对齐 Semi text）。 */
+    text: string;
+    /** 项前置图标。 */
+    icon?: Snippet;
+    /** 是否禁用。 */
+    disabled?: boolean;
+    /** 链接地址；传入时叶子项渲染为原生 `<a href>`（站点导航语义）。 */
+    link?: string;
+    /** 链接 target（如 '_blank'）。 */
+    target?: string;
+    /** 链接 rel（如 'noopener noreferrer'）。 */
+    rel?: string;
+    /** 项级点击回调（叶子项）。 */
+    onClick?: (e: MouseEvent) => void;
+    /** 项级鼠标移入回调。 */
+    onMouseEnter?: (e: MouseEvent) => void;
+    /** 项级鼠标移出回调。 */
+    onMouseLeave?: (e: MouseEvent) => void;
+    /** 子导航项；含 items 即为可展开子导航。 */
+    items?: NavItemDef[];
+}
+/** Nav.Header 配置对象（对齐 Semi header={{logo,text}}）。 */
+export interface NavHeaderConfig {
+    /** Logo 节点（Snippet）。 */
+    logo?: Snippet;
+    /** Logo 文案。 */
+    text?: string;
+}
+/** Nav.Footer 配置对象（对齐 Semi footer={{collapseButton}}）。 */
+export interface NavFooterConfig {
+    /** 是否展示底部「收起侧边栏」按钮，仅 mode='vertical' 生效。 */
+    collapseButton?: boolean;
+}
+/**
+ * 把 Nav 项（Semi 字段）递归映射为 Menu 的 MenuItemDef。
+ * itemKey→key、text→label、items→children、link→href，icon/target/rel/disabled 直传。
+ */
+export declare function navItemsToMenuItems(items?: NavItemDef[]): MenuItemDef[];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/nav/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,iCAAiC;AACjC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAErC,yCAAyC;AACzC,MAAM,MAAM,OAAO,GAAG,UAAU,GAAG,YAAY,CAAC;AAEhD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IAClC,gBAAgB;IAChB,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACvC,gBAAgB;IAChB,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAC;IACvC,6BAA6B;IAC7B,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB;AAED,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,eAAe;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,GAAE,UAAU,EAAO,GAAG,WAAW,EAAE,CAiB3E"}