@chenzy-design/svelte 0.1.0

package/dist/dropdown/DropdownSubMenu.svelte

@@ -0,0 +1,212 @@
+<!--
+  Dropdown.SubMenu — 声明式可展开子菜单包装。
+  用于 <Dropdown> children 插槽模式，与 DropdownItemNode（items 数据驱动）行为对齐：
+  hover/聚焦展开，floating 到父项右侧（溢出翻转左侧），键盘 →/←/↑↓/Esc 导航。
+-->
+<script lang="ts">
+  import { tick, getContext } from 'svelte';
+  import { floating } from '../_floating/use-floating.js';
+  import { DROPDOWN_CTX, type DropdownContext } from './context.js';
+
+  interface Props {
+    /** 子菜单标题文案 */
+    title?: string;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** hover 开启延迟（ms），默认 100 */
+    openDelay?: number;
+    /** hover 关闭延迟（ms），默认 200 */
+    closeDelay?: number;
+    children?: import('svelte').Snippet;
+  }
+
+  let {
+    title = '',
+    disabled = false,
+    openDelay = 100,
+    closeDelay = 200,
+    children,
+  }: Props = $props();
+
+  const ddCtx = getContext<DropdownContext | undefined>(DROPDOWN_CTX);
+
+  let titleEl = $state<HTMLButtonElement | null>(null);
+  let subEl = $state<HTMLUListElement | null>(null);
+  let open = $state(false);
+
+  let openTimer: ReturnType<typeof setTimeout> | undefined;
+  let closeTimer: ReturnType<typeof setTimeout> | undefined;
+
+  function clearTimers() {
+    if (openTimer !== undefined) { clearTimeout(openTimer); openTimer = undefined; }
+    if (closeTimer !== undefined) { clearTimeout(closeTimer); closeTimer = undefined; }
+  }
+
+  function scheduleOpen() {
+    if (disabled) return;
+    if (closeTimer !== undefined) { clearTimeout(closeTimer); closeTimer = undefined; }
+    if (open) return;
+    openTimer = setTimeout(() => { open = true; openTimer = undefined; }, openDelay);
+  }
+
+  function scheduleClose() {
+    if (openTimer !== undefined) { clearTimeout(openTimer); openTimer = undefined; }
+    if (!open) return;
+    closeTimer = setTimeout(() => { open = false; closeTimer = undefined; }, closeDelay);
+  }
+
+  function keepOpen() {
+    if (closeTimer !== undefined) { clearTimeout(closeTimer); closeTimer = undefined; }
+  }
+
+  function closeNow() {
+    clearTimers();
+    open = false;
+  }
+
+  async function openAndFocusFirst() {
+    if (disabled) return;
+    open = true;
+    await tick();
+    const first = subEl?.querySelector<HTMLElement>('[role="menuitem"]:not([aria-disabled="true"])');
+    first?.focus();
+  }
+
+  function onTitleKeydown(e: KeyboardEvent) {
+    switch (e.key) {
+      case 'ArrowRight':
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        void openAndFocusFirst();
+        break;
+      case 'ArrowLeft':
+      case 'Escape':
+        if (open) {
+          e.preventDefault();
+          e.stopPropagation();
+          closeNow();
+          titleEl?.focus();
+        }
+        break;
+    }
+  }
+
+  function onSubKeydown(e: KeyboardEvent) {
+    if (e.key === 'ArrowLeft' || e.key === 'Escape') {
+      e.preventDefault();
+      e.stopPropagation();
+      closeNow();
+      titleEl?.focus();
+    }
+  }
+
+  $effect(() => clearTimers);
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<li
+  class="cd-dropdown__item-wrap cd-dropdown__item-wrap--submenu"
+  role="none"
+  onpointerenter={scheduleOpen}
+  onpointerleave={scheduleClose}
+>
+  <button
+    type="button"
+    class="cd-dropdown__item cd-dropdown__item--submenu"
+    role="menuitem"
+    tabindex="-1"
+    aria-haspopup="menu"
+    aria-expanded={open}
+    aria-disabled={disabled || undefined}
+    disabled={disabled || undefined}
+    bind:this={titleEl}
+    onclick={() => void openAndFocusFirst()}
+    onkeydown={onTitleKeydown}
+  >
+    <span class="cd-dropdown__label">{title}</span>
+    <span class="cd-dropdown__arrow" aria-hidden="true">
+      <svg viewBox="0 0 16 16" width="10" height="10" focusable="false">
+        <path fill="currentColor" d="M6 4l4 4-4 4V4Z" />
+      </svg>
+    </span>
+  </button>
+
+  {#if open && titleEl}
+    <ul
+      class="cd-dropdown__sub"
+      role="menu"
+      tabindex="-1"
+      bind:this={subEl}
+      use:floating={{ trigger: titleEl, placement: 'rightStart', offset: 2, autoAdjust: true, getContainer: ddCtx?.getContainer }}
+      onpointerenter={keepOpen}
+      onpointerleave={scheduleClose}
+      onkeydown={onSubKeydown}
+    >
+      {@render children?.()}
+    </ul>
+  {/if}
+</li>
+
+<style>
+  .cd-dropdown__item-wrap {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .cd-dropdown__item-wrap--submenu {
+    position: relative;
+  }
+  .cd-dropdown__item {
+    display: flex;
+    align-items: center;
+    gap: var(--cd-spacing-2);
+    inline-size: 100%;
+    margin: 0;
+    padding: var(--cd-dropdown-item-padding);
+    border: none;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    text-align: start;
+    cursor: pointer;
+  }
+  .cd-dropdown__item:hover,
+  .cd-dropdown__item:focus-visible {
+    background: var(--cd-dropdown-item-bg-hover);
+  }
+  .cd-dropdown__item:focus-visible {
+    outline: none;
+  }
+  .cd-dropdown__item--submenu[aria-expanded='true'] {
+    background: var(--cd-dropdown-item-bg-hover);
+  }
+  .cd-dropdown__item[aria-disabled='true'] {
+    color: var(--cd-dropdown-item-color-disabled);
+    cursor: not-allowed;
+  }
+  .cd-dropdown__label {
+    flex: 1 1 auto;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+  .cd-dropdown__arrow {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 auto;
+    color: var(--cd-color-text-2);
+  }
+  .cd-dropdown__sub {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    z-index: var(--cd-dropdown-z);
+    min-inline-size: var(--cd-dropdown-min-width);
+    padding-block: var(--cd-spacing-1);
+    background: var(--cd-dropdown-bg);
+    border-radius: var(--cd-dropdown-radius);
+    box-shadow: var(--cd-dropdown-shadow);
+  }
+</style>

package/dist/dropdown/DropdownSubMenu.svelte.d.ts

@@ -0,0 +1,15 @@
+interface Props {
+    /** 子菜单标题文案 */
+    title?: string;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** hover 开启延迟（ms），默认 100 */
+    openDelay?: number;
+    /** hover 关闭延迟（ms），默认 200 */
+    closeDelay?: number;
+    children?: import('svelte').Snippet;
+}
+declare const DropdownSubMenu: import("svelte").Component<Props, {}, "">;
+type DropdownSubMenu = ReturnType<typeof DropdownSubMenu>;
+export default DropdownSubMenu;
+//# sourceMappingURL=DropdownSubMenu.svelte.d.ts.map

package/dist/dropdown/DropdownSubMenu.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DropdownSubMenu.svelte.d.ts","sourceRoot":"","sources":["../../src/dropdown/DropdownSubMenu.svelte.ts"],"names":[],"mappings":"AAQE,UAAU,KAAK;IACb,cAAc;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;CACrC;AAkHH,QAAA,MAAM,eAAe,2CAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/dropdown/DropdownTitle.svelte

@@ -0,0 +1,34 @@
+<!--
+  Dropdown.Title — 不可点击的分组标题（对应 items 数据驱动模式中 type='group' 的 label）。
+  渲染为 role=none 的 li 中的纯展示 div，不接收键盘焦点。
+-->
+<script lang="ts">
+  interface Props {
+    children?: import('svelte').Snippet;
+  }
+
+  let { children }: Props = $props();
+</script>
+
+<li class="cd-dropdown__group" role="none">
+  <div class="cd-dropdown__group-title">
+    {@render children?.()}
+  </div>
+</li>
+
+<style>
+  .cd-dropdown__group {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .cd-dropdown__group-title {
+    display: flex;
+    align-items: center;
+    padding: var(--cd-dropdown-item-padding);
+    color: var(--cd-dropdown-item-color-disabled);
+    font-size: var(--cd-font-size-1);
+    cursor: default;
+    user-select: none;
+  }
+</style>

package/dist/dropdown/DropdownTitle.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    children?: import('svelte').Snippet;
+}
+declare const DropdownTitle: import("svelte").Component<Props, {}, "">;
+type DropdownTitle = ReturnType<typeof DropdownTitle>;
+export default DropdownTitle;
+//# sourceMappingURL=DropdownTitle.svelte.d.ts.map

package/dist/dropdown/DropdownTitle.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DropdownTitle.svelte.d.ts","sourceRoot":"","sources":["../../src/dropdown/DropdownTitle.svelte.ts"],"names":[],"mappings":"AAGE,UAAU,KAAK;IACb,QAAQ,CAAC,EAAE,OAAO,QAAQ,EAAE,OAAO,CAAC;CACrC;AAkBH,QAAA,MAAM,aAAa,2CAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}

package/dist/dropdown/context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Dropdown 子树共享上下文。
+ * 透传 getPopupContainer，使递归的 DropdownItemNode 子菜单浮层挂到与顶层
+ * 浮层相同的自定义容器；同时透传 showTick，在叶子项右侧渲染勾选标记。
+ */
+export interface DropdownContext {
+    /** 浮层挂载容器解析器；缺省时（undefined）floating 默认挂 body。 */
+    getContainer?: (() => HTMLElement | null | undefined) | undefined;
+    /** 已选中的 Item 是否显示 ✓ 勾选标记（默认 false）。 */
+    showTick?: boolean;
+}
+export declare const DROPDOWN_CTX: unique symbol;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/dropdown/context.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,YAAY,CAAC,EAAE,CAAC,MAAM,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IAClE,uCAAuC;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,YAAY,eAA4B,CAAC"}

package/dist/dropdown/context.js

@@ -0,0 +1 @@
+export const DROPDOWN_CTX = Symbol('cd-dropdown-ctx');

package/dist/dropdown/index.d.ts

@@ -0,0 +1,18 @@
+import Dropdown_ from './Dropdown.svelte';
+import DropdownItem from './DropdownItem.svelte';
+import DropdownMenu from './DropdownMenu.svelte';
+import DropdownSubMenu from './DropdownSubMenu.svelte';
+import DropdownTitle from './DropdownTitle.svelte';
+import DropdownDivider from './DropdownDivider.svelte';
+export declare const Dropdown: typeof Dropdown_ & {
+    Item: typeof DropdownItem;
+    Menu: typeof DropdownMenu;
+    SubMenu: typeof DropdownSubMenu;
+    Title: typeof DropdownTitle;
+    Divider: typeof DropdownDivider;
+};
+export { DropdownItem, DropdownMenu, DropdownSubMenu, DropdownTitle, DropdownDivider };
+export { meta as dropdownMeta } from './meta.js';
+export { isDropdownDivider, isDropdownGroup, hasDropdownChildren, } from './types.js';
+export type { DropdownItem as DropdownItemType, DropdownItemNode, DropdownDividerNode, DropdownGroupNode, DropdownKey, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dropdown/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAC1C,OAAO,YAAY,MAAM,uBAAuB,CAAC;AACjD,OAAO,YAAY,MAAM,uBAAuB,CAAC;AACjD,OAAO,eAAe,MAAM,0BAA0B,CAAC;AACvD,OAAO,aAAa,MAAM,wBAAwB,CAAC;AACnD,OAAO,eAAe,MAAM,0BAA0B,CAAC;AAGvD,eAAO,MAAM,QAAQ,EAAE,OAAO,SAAS,GAAG;IACxC,IAAI,EAAE,OAAO,YAAY,CAAC;IAC1B,IAAI,EAAE,OAAO,YAAY,CAAC;IAC1B,OAAO,EAAE,OAAO,eAAe,CAAC;IAChC,KAAK,EAAE,OAAO,aAAa,CAAC;IAC5B,OAAO,EAAE,OAAO,eAAe,CAAC;CAOhC,CAAC;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;AACvF,OAAO,EAAE,IAAI,IAAI,YAAY,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,YAAY,IAAI,gBAAgB,EAChC,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/dropdown/index.js

@@ -0,0 +1,17 @@
+import Dropdown_ from './Dropdown.svelte';
+import DropdownItem from './DropdownItem.svelte';
+import DropdownMenu from './DropdownMenu.svelte';
+import DropdownSubMenu from './DropdownSubMenu.svelte';
+import DropdownTitle from './DropdownTitle.svelte';
+import DropdownDivider from './DropdownDivider.svelte';
+// Dropdown 挂载声明式子组件：Item / Menu / SubMenu / Title / Divider。
+export const Dropdown = Object.assign(Dropdown_, {
+    Item: DropdownItem,
+    Menu: DropdownMenu,
+    SubMenu: DropdownSubMenu,
+    Title: DropdownTitle,
+    Divider: DropdownDivider,
+});
+export { DropdownItem, DropdownMenu, DropdownSubMenu, DropdownTitle, DropdownDivider };
+export { meta as dropdownMeta } from './meta.js';
+export { isDropdownDivider, isDropdownGroup, hasDropdownChildren, } from './types.js';

package/dist/dropdown/meta.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export declare const meta: {
+    readonly name: "Dropdown";
+    readonly category: "navigation";
+    readonly description: "下拉菜单，通过触发元素唤起一组可操作命令项。支持 hover/click/contextMenu 触发、嵌套子菜单、divider 分隔符、group 分组、useDismiss 关闭、键盘导航与危险项。";
+    readonly props: readonly [{
+        readonly name: "items";
+        readonly type: "DropdownItem[]";
+        readonly default: "[]";
+        readonly desc: "菜单项数据；判别联合：普通项含 children 即可展开子菜单，type=divider 分隔符，type=group 分组标题";
+    }, {
+        readonly name: "trigger";
+        readonly type: "'hover'|'click'|'contextMenu'";
+        readonly default: "hover";
+        readonly desc: "触发方式；contextMenu 为右键唤起并定位到光标";
+    }, {
+        readonly name: "open";
+        readonly type: "boolean";
+        readonly default: "undefined";
+        readonly desc: "受控显隐";
+    }, {
+        readonly name: "defaultOpen";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "非受控初始显隐";
+    }, {
+        readonly name: "position";
+        readonly type: "'bottomStart'|'bottomEnd'|'topStart'";
+        readonly default: "bottomStart";
+        readonly desc: "浮层位置";
+    }, {
+        readonly name: "size";
+        readonly type: "'small'|'default'|'large'";
+        readonly default: "default";
+    }, {
+        readonly name: "disabled";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "禁用整个触发";
+    }, {
+        readonly name: "closeOnSelect";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "点击项后自动关闭";
+    }, {
+        readonly name: "closeOnEsc";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "Esc 是否关闭";
+    }, {
+        readonly name: "mouseEnterDelay";
+        readonly type: "number";
+        readonly default: "150";
+        readonly desc: "hover 进入延迟(ms)";
+    }, {
+        readonly name: "mouseLeaveDelay";
+        readonly type: "number";
+        readonly default: "150";
+        readonly desc: "hover 离开延迟(ms)";
+    }, {
+        readonly name: "spacing";
+        readonly type: "number | { x: number; y: number }";
+        readonly default: "4";
+        readonly desc: "浮层与触发元素间距(px)，映射到 floating 主轴 offset；{ x, y } 按 position 主轴方向取值（上下取 y、左右取 x）";
+    }, {
+        readonly name: "clickToHide";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "hover 模式下点击菜单项是否关闭浮层；false 时点击项不关闭（仅移出/Esc/外部点击收起），仅影响 hover 触发";
+    }, {
+        readonly name: "zIndex";
+        readonly type: "number";
+        readonly default: "1050";
+        readonly desc: "浮层层级（写入浮层内联 z-index）";
+    }, {
+        readonly name: "autoAdjustOverflow";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "空间不足时自动翻转/移位到可视区（透传 floating autoAdjust）；false 时严格按 position 定位不翻转";
+    }, {
+        readonly name: "destroyOnClose";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "关闭即卸载浮层内容（{#if}）重开重建；默认 false 首开后保留 DOM 仅隐藏";
+    }, {
+        readonly name: "lazyRender";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "首次打开前不渲染浮层内容（惰性）；false 时即使从未打开也预渲染浮层 DOM（仅隐藏）";
+    }, {
+        readonly name: "keepDOM";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "关闭后保留浮层 DOM（与 destroyOnClose 互斥；true 时强制保留，忽略 destroyOnClose）";
+    }, {
+        readonly name: "getPopupContainer";
+        readonly type: "() => HTMLElement";
+        readonly default: "() => document.body";
+        readonly desc: "浮层挂载容器；非 body 容器时改 absolute 相对该容器定位，嵌套子菜单与右键浮层同容器";
+    }, {
+        readonly name: "onSelect";
+        readonly type: "(key: string|number) => void";
+        readonly default: "undefined";
+    }, {
+        readonly name: "onOpenChange";
+        readonly type: "(open: boolean) => void";
+        readonly default: "undefined";
+    }, {
+        readonly name: "triggerContent";
+        readonly type: "Snippet";
+        readonly default: "undefined";
+        readonly desc: "触发元素内容";
+    }, {
+        readonly name: "children";
+        readonly type: "Snippet";
+        readonly default: "undefined";
+        readonly desc: "自定义浮层内容（提供则忽略 items）";
+    }];
+    readonly a11y: {
+        readonly role: "menu";
+        readonly keyboard: readonly ["Enter", "Space", "ArrowDown", "ArrowUp", "ArrowRight", "ArrowLeft", "Escape"];
+        readonly notes: readonly ["触发器 aria-haspopup=menu + aria-expanded + aria-controls", "浮层 role=menu，项 role=menuitem，焦点式 roving（tabindex=-1 + 方向键移动焦点）", "子菜单父项 aria-haspopup=menu + aria-expanded；→ 进入子菜单首项，← / Esc 逐层返回", "divider role=separator；group 组标题不可聚焦，组内项始终展开（role=group）", "useDismiss 处理外部点击与 Escape 关闭"];
+    };
+    readonly tokens: readonly ["--cd-dropdown-*", "--cd-focus-ring", "--cd-radius-1", "--cd-spacing-*", "--cd-color-danger"];
+};
+//# sourceMappingURL=meta.d.ts.map

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

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

package/dist/dropdown/meta.js

@@ -0,0 +1,96 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+    name: 'Dropdown',
+    category: 'navigation',
+    description: '下拉菜单，通过触发元素唤起一组可操作命令项。支持 hover/click/contextMenu 触发、嵌套子菜单、divider 分隔符、group 分组、useDismiss 关闭、键盘导航与危险项。',
+    props: [
+        {
+            name: 'items',
+            type: 'DropdownItem[]',
+            default: '[]',
+            desc: '菜单项数据；判别联合：普通项含 children 即可展开子菜单，type=divider 分隔符，type=group 分组标题',
+        },
+        {
+            name: 'trigger',
+            type: "'hover'|'click'|'contextMenu'",
+            default: 'hover',
+            desc: "触发方式；contextMenu 为右键唤起并定位到光标",
+        },
+        { name: 'open', type: 'boolean', default: 'undefined', desc: '受控显隐' },
+        { name: 'defaultOpen', type: 'boolean', default: 'false', desc: '非受控初始显隐' },
+        {
+            name: 'position',
+            type: "'bottomStart'|'bottomEnd'|'topStart'",
+            default: 'bottomStart',
+            desc: '浮层位置',
+        },
+        { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
+        { name: 'disabled', type: 'boolean', default: 'false', desc: '禁用整个触发' },
+        { name: 'closeOnSelect', type: 'boolean', default: 'true', desc: '点击项后自动关闭' },
+        { name: 'closeOnEsc', type: 'boolean', default: 'true', desc: 'Esc 是否关闭' },
+        { name: 'mouseEnterDelay', type: 'number', default: '150', desc: 'hover 进入延迟(ms)' },
+        { name: 'mouseLeaveDelay', type: 'number', default: '150', desc: 'hover 离开延迟(ms)' },
+        {
+            name: 'spacing',
+            type: 'number | { x: number; y: number }',
+            default: '4',
+            desc: '浮层与触发元素间距(px)，映射到 floating 主轴 offset；{ x, y } 按 position 主轴方向取值（上下取 y、左右取 x）',
+        },
+        {
+            name: 'clickToHide',
+            type: 'boolean',
+            default: 'true',
+            desc: 'hover 模式下点击菜单项是否关闭浮层；false 时点击项不关闭（仅移出/Esc/外部点击收起），仅影响 hover 触发',
+        },
+        { name: 'zIndex', type: 'number', default: '1050', desc: '浮层层级（写入浮层内联 z-index）' },
+        {
+            name: 'autoAdjustOverflow',
+            type: 'boolean',
+            default: 'true',
+            desc: '空间不足时自动翻转/移位到可视区（透传 floating autoAdjust）；false 时严格按 position 定位不翻转',
+        },
+        {
+            name: 'destroyOnClose',
+            type: 'boolean',
+            default: 'false',
+            desc: '关闭即卸载浮层内容（{#if}）重开重建；默认 false 首开后保留 DOM 仅隐藏',
+        },
+        {
+            name: 'lazyRender',
+            type: 'boolean',
+            default: 'true',
+            desc: '首次打开前不渲染浮层内容（惰性）；false 时即使从未打开也预渲染浮层 DOM（仅隐藏）',
+        },
+        {
+            name: 'keepDOM',
+            type: 'boolean',
+            default: 'false',
+            desc: '关闭后保留浮层 DOM（与 destroyOnClose 互斥；true 时强制保留，忽略 destroyOnClose）',
+        },
+        {
+            name: 'getPopupContainer',
+            type: '() => HTMLElement',
+            default: '() => document.body',
+            desc: '浮层挂载容器；非 body 容器时改 absolute 相对该容器定位，嵌套子菜单与右键浮层同容器',
+        },
+        { name: 'onSelect', type: '(key: string|number) => void', default: 'undefined' },
+        { name: 'onOpenChange', type: '(open: boolean) => void', default: 'undefined' },
+        { name: 'triggerContent', type: 'Snippet', default: 'undefined', desc: '触发元素内容' },
+        { name: 'children', type: 'Snippet', default: 'undefined', desc: '自定义浮层内容（提供则忽略 items）' },
+    ],
+    a11y: {
+        role: 'menu',
+        keyboard: ['Enter', 'Space', 'ArrowDown', 'ArrowUp', 'ArrowRight', 'ArrowLeft', 'Escape'],
+        notes: [
+            '触发器 aria-haspopup=menu + aria-expanded + aria-controls',
+            '浮层 role=menu，项 role=menuitem，焦点式 roving（tabindex=-1 + 方向键移动焦点）',
+            '子菜单父项 aria-haspopup=menu + aria-expanded；→ 进入子菜单首项，← / Esc 逐层返回',
+            'divider role=separator；group 组标题不可聚焦，组内项始终展开（role=group）',
+            'useDismiss 处理外部点击与 Escape 关闭',
+        ],
+    },
+    tokens: ['--cd-dropdown-*', '--cd-focus-ring', '--cd-radius-1', '--cd-spacing-*', '--cd-color-danger'],
+};

package/dist/dropdown/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Dropdown 数据项类型。与 Menu 对齐的判别联合思路（见 menu/types.ts）：
+ * 普通项含 children 即为可展开 SubMenu；type='divider' 分隔符；type='group' 分组标题。
+ * 向后兼容：普通项可省略 type，旧的 flat items 无需改动。
+ */
+/** Dropdown 项键类型。 */
+export type DropdownKey = string | number;
+/** 普通菜单项；含 children 即为可展开的 SubMenu。 */
+export interface DropdownItemNode {
+    /** 非分隔符/分组时无需 type，默认即普通项；显式可写 'item' */
+    type?: 'item';
+    key: DropdownKey;
+    label: string;
+    disabled?: boolean;
+    danger?: boolean;
+    /** 是否选中（showTick=true 时在右侧渲染 ✓ 勾选标记） */
+    selected?: boolean;
+    /** 含子项即为可展开的子菜单（SubMenu），可多层嵌套 */
+    children?: DropdownItem[];
+}
+/**
+ * 分隔符项：渲染为一条水平分隔线，不可选不可聚焦（role=separator）。
+ * 无需 key/label；为避免 #each 缺 key 警告，渲染时按索引生成兜底 key。
+ */
+export interface DropdownDividerNode {
+    type: 'divider';
+    key?: DropdownKey;
+}
+/**
+ * 分组项：渲染为不可点击的组标题 + 其下始终展开的菜单项。
+ * 区别于 SubMenu（可展开/收起）——group 是始终展开的分区标题。
+ */
+export interface DropdownGroupNode {
+    type: 'group';
+    key?: DropdownKey;
+    /** 分组标题文案 */
+    label: string;
+    children: DropdownItem[];
+}
+/**
+ * Dropdown 数据项。向后兼容：普通项可省略 type；
+ * 通过 type='divider' / type='group' 扩展分隔符与分组标题，
+ * 普通项的 children 表示可展开子菜单。
+ */
+export type DropdownItem = DropdownItemNode | DropdownDividerNode | DropdownGroupNode;
+/** 类型守卫：分隔符项。 */
+export declare function isDropdownDivider(item: DropdownItem): item is DropdownDividerNode;
+/** 类型守卫：分组项。 */
+export declare function isDropdownGroup(item: DropdownItem): item is DropdownGroupNode;
+/** 普通项是否含可展开子菜单。 */
+export declare function hasDropdownChildren(item: DropdownItemNode): boolean;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/dropdown/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAqB;AACrB,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,WAAW,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,CAAC,EAAE,WAAW,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,aAAa;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB,gBAAgB,GAChB,mBAAmB,GACnB,iBAAiB,CAAC;AAEtB,iBAAiB;AACjB,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,IAAI,mBAAmB,CAEjF;AAED,gBAAgB;AAChB,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,IAAI,iBAAiB,CAE7E;AAED,oBAAoB;AACpB,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAEnE"}

package/dist/dropdown/types.js

@@ -0,0 +1,12 @@
+/** 类型守卫：分隔符项。 */
+export function isDropdownDivider(item) {
+    return item.type === 'divider';
+}
+/** 类型守卫：分组项。 */
+export function isDropdownGroup(item) {
+    return item.type === 'group';
+}
+/** 普通项是否含可展开子菜单。 */
+export function hasDropdownChildren(item) {
+    return !!item.children && item.children.length > 0;
+}

package/dist/dropdown/types.test.d.ts

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

package/dist/dropdown/types.test.d.ts.map

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