@chenzy-design/svelte 0.1.0

package/src/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/src/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/src/dropdown/context.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 const DROPDOWN_CTX = Symbol('cd-dropdown-ctx');

package/src/dropdown/index.ts

@@ -0,0 +1,36 @@
+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: typeof Dropdown_ & {
+  Item: typeof DropdownItem;
+  Menu: typeof DropdownMenu;
+  SubMenu: typeof DropdownSubMenu;
+  Title: typeof DropdownTitle;
+  Divider: typeof DropdownDivider;
+} = 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';
+export type {
+  DropdownItem as DropdownItemType,
+  DropdownItemNode,
+  DropdownDividerNode,
+  DropdownGroupNode,
+  DropdownKey,
+} from './types.js';

package/src/dropdown/meta.ts

@@ -0,0 +1,97 @@
+/**
+ * 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'],
+} as const;

package/src/dropdown/types.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import {
+  isDropdownDivider,
+  isDropdownGroup,
+  hasDropdownChildren,
+  type DropdownItem,
+} from './types.js';
+
+describe('dropdown type guards', () => {
+  const leaf: DropdownItem = { key: 'a', label: 'A' };
+  const submenu: DropdownItem = {
+    key: 'b',
+    label: 'B',
+    children: [{ key: 'b1', label: 'B1' }],
+  };
+  const divider: DropdownItem = { type: 'divider' };
+  const group: DropdownItem = {
+    type: 'group',
+    label: 'G',
+    children: [{ key: 'g1', label: 'G1' }],
+  };
+
+  it('isDropdownDivider only matches divider nodes', () => {
+    expect(isDropdownDivider(divider)).toBe(true);
+    expect(isDropdownDivider(leaf)).toBe(false);
+    expect(isDropdownDivider(group)).toBe(false);
+    expect(isDropdownDivider(submenu)).toBe(false);
+  });
+
+  it('isDropdownGroup only matches group nodes', () => {
+    expect(isDropdownGroup(group)).toBe(true);
+    expect(isDropdownGroup(leaf)).toBe(false);
+    expect(isDropdownGroup(divider)).toBe(false);
+    expect(isDropdownGroup(submenu)).toBe(false);
+  });
+
+  it('hasDropdownChildren detects expandable submenu items', () => {
+    expect(hasDropdownChildren(submenu)).toBe(true);
+    expect(hasDropdownChildren(leaf)).toBe(false);
+    expect(hasDropdownChildren({ key: 'c', label: 'C', children: [] })).toBe(false);
+  });
+
+  it('backward compat: a flat item without type is a valid DropdownItem', () => {
+    const items: DropdownItem[] = [
+      { key: 'edit', label: '编辑' },
+      { key: 'del', label: '删除', danger: true, disabled: true },
+    ];
+    expect(items.every((i) => !isDropdownDivider(i) && !isDropdownGroup(i))).toBe(true);
+  });
+});

package/src/dropdown/types.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 function isDropdownDivider(item: DropdownItem): item is DropdownDividerNode {
+  return (item as DropdownDividerNode).type === 'divider';
+}
+
+/** 类型守卫：分组项。 */
+export function isDropdownGroup(item: DropdownItem): item is DropdownGroupNode {
+  return (item as DropdownGroupNode).type === 'group';
+}
+
+/** 普通项是否含可展开子菜单。 */
+export function hasDropdownChildren(item: DropdownItemNode): boolean {
+  return !!item.children && item.children.length > 0;
+}

package/src/empty/Empty.a11y.test.ts

@@ -0,0 +1,24 @@
+// Empty a11y：预设插画 aria-hidden；外部图片 <img> 带 alt。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import Empty from './Empty.svelte';
+
+describe('Empty a11y', () => {
+  it('预设插画：image 容器 aria-hidden，无 axe violations', async () => {
+    const { container } = renderWithLocale(Empty, {
+      props: { image: 'noData', description: 'No data available' },
+    });
+    const imageBox = container.querySelector('.cd-empty__image');
+    expect(imageBox?.getAttribute('aria-hidden')).toBe('true');
+    await expectNoAxeViolations(container);
+  });
+
+  it('外部图片 URL：<img> 带 alt（取标题/空串），无 axe violations', async () => {
+    const { container } = renderWithLocale(Empty, {
+      props: { image: 'https://example.com/empty.png', title: 'Nothing here' },
+    });
+    const img = container.querySelector('.cd-empty__img');
+    expect(img?.getAttribute('alt')).toBe('Nothing here');
+    await expectNoAxeViolations(container);
+  });
+});