@chenzy-design/svelte 0.1.0

package/src/collapse/CollapsePanel.svelte

@@ -0,0 +1,102 @@
+<!--
+  Collapse.Panel — 声明式单面板，与数据驱动 panels 渲染同一套 .cd-collapse__item 结构，
+  从而复用父 Collapse 的 grid 展开动画、箭头位置、边框等全部 CSS，无需在父级建挂载 registry。
+  父子状态经 context.ts 传递（参考 Timeline.Item / Form.Field）：
+    展开态判断（isActive/shouldRender）为父级纯派生函数，本组件只读不写（红线 #2）；
+    点击 header 调父 toggle，受控时仅 onChange 不回写（红线 #1，在父级落实）。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { getCollapseContext } from './context.js';
+
+  interface Props {
+    /** 面板唯一标识，等价数据驱动 panel.key。 */
+    itemKey: string;
+    /** 头部文本。 */
+    header?: string;
+    /** 面板级 disabled：该面板不可展开/收起。 */
+    disabled?: boolean;
+    /** 头部富内容插槽，优先于 header 文本。 */
+    head?: Snippet;
+    /** 头部右侧额外内容（不触发展开/收起），可为字符串或 Snippet。 */
+    extra?: Snippet | string;
+    /** 是否显示箭头区域，默认 true。 */
+    showArrow?: boolean;
+    children?: Snippet;
+  }
+
+  let { itemKey, header, disabled = false, head, extra, showArrow = true, children }: Props = $props();
+
+  const ctx = getCollapseContext();
+
+  // 展开态由父派生（纯函数），跨 context 读 getter 保持响应性。
+  const active = $derived(ctx?.isActive(itemKey) ?? false);
+  // 面板不可用 = 父整体 disabled 或本面板 disabled。
+  const itemDisabled = $derived((ctx?.getDisabled() ?? false) || disabled);
+  const render = $derived(ctx?.shouldRender(itemKey) ?? true);
+
+  const idBase = $derived(ctx?.getIdBase() ?? 'cd-collapse');
+  const headerId = $derived(`${idBase}-h-${itemKey}`);
+  const regionId = $derived(`${idBase}-r-${itemKey}`);
+  const headingLevel = $derived(ctx?.getHeadingLevel() ?? 3);
+  // roving tabindex 由父派生（红线 #2：本组件只读不写父级 $state）。
+  const tabindex = $derived(ctx?.headerTabindex(itemKey, disabled) ?? 0);
+  const expandIcon = $derived(ctx?.getExpandIcon());
+</script>
+
+<div class="cd-collapse__item" class:cd-collapse__item--active={active}>
+  <!-- APG Accordion：Header 触发器外层 role=heading + aria-level。 -->
+  <span role="heading" aria-level={headingLevel} class="cd-collapse__heading">
+  <button
+    type="button"
+    id={headerId}
+    class="cd-collapse__header"
+    data-collapse-key={itemKey}
+    aria-expanded={active}
+    aria-controls={regionId}
+    aria-disabled={itemDisabled || undefined}
+    disabled={itemDisabled || undefined}
+    {tabindex}
+    onclick={(e) => ctx?.headerClick(e, itemKey, disabled)}
+    onkeydown={(e) => ctx?.onHeaderKeydown(e, itemKey)}
+    onfocus={() => ctx?.onHeaderFocus(itemKey)}
+  >
+    {#if showArrow}
+      {#if expandIcon}
+        <span class="cd-collapse__arrow" class:cd-collapse__arrow--open={active} aria-hidden="true">
+          {@render expandIcon({ isExpanded: active })}
+        </span>
+      {:else}
+        <span class="cd-collapse__arrow" class:cd-collapse__arrow--open={active} aria-hidden="true">
+          <svg viewBox="0 0 16 16" width="12" height="12" focusable="false">
+            <path fill="currentColor" d="M6 4l4 4-4 4V4Z" />
+          </svg>
+        </span>
+      {/if}
+    {/if}
+    <span class="cd-collapse__title">
+      {#if head}{@render head()}{:else}{header}{/if}
+    </span>
+    {#if extra !== undefined}
+      <span class="cd-collapse__extra" onclick={(e) => e.stopPropagation()} role="none">
+        {#if typeof extra === 'string'}{extra}{:else}{@render extra()}{/if}
+      </span>
+    {/if}
+  </button>
+  </span>
+  <div
+    id={regionId}
+    class="cd-collapse__region"
+    role="region"
+    aria-labelledby={headerId}
+    hidden={!active}
+  >
+    <div class="cd-collapse__region-inner">
+      <div class="cd-collapse__content">
+        {#if render}
+          {@render children?.()}
+        {/if}
+      </div>
+    </div>
+  </div>
+</div>

package/src/collapse/context.ts

@@ -0,0 +1,54 @@
+import { getContext, setContext } from 'svelte';
+import type { Snippet } from 'svelte';
+
+export type CollapseSize = 'small' | 'default' | 'large';
+export type CollapseIconPosition = 'left' | 'right';
+
+/**
+ * 父 Collapse 向声明式 <Collapse.Panel> 暴露的上下文。
+ * 全部用 getter 跨 context 边界保持对父 prop / 展开态变化的响应性
+ * （直接读快照会冻结初始值）。
+ * 红线 #2: isActive / shouldRender 为纯派生函数，render 期只读不写。
+ */
+export interface CollapseContext {
+  /** 该 key 当前是否展开（受控读 prop、非受控读本地 set，均由父派生）。 */
+  isActive: (key: string) => boolean;
+  /** 该 key 内容是否应渲染（lazyRender / keepDOM 策略）。 */
+  shouldRender: (key: string) => boolean;
+  /** 点击 header 切换展开态；panelDisabled 为该面板自身 disabled。 */
+  toggle: (key: string, panelDisabled?: boolean) => void;
+  /**
+   * Header 点击入口：先发 on:headerClick（埋点，disabled 拦截前），再 toggle。
+   * 声明式 <Collapse.Panel> 的 header onclick 应调此，保证 headerClick 事件统一从父发出。
+   */
+  headerClick: (event: MouseEvent, key: string, panelDisabled?: boolean) => void;
+  /** 父级整体 disabled。 */
+  getDisabled: () => boolean;
+  getSize: () => CollapseSize;
+  getIconPosition: () => CollapseIconPosition;
+  /** header/region id 前缀，用于 aria 关联。 */
+  getIdBase: () => string;
+  /** Header role=heading 的 aria-level。 */
+  getHeadingLevel: () => number;
+  /**
+   * roving tabindex（纯派生）：焦点 Header / 首个未禁用 Header 为 0，其余 -1。
+   * 红线 #2：render 期只读，不写父级 $state。
+   */
+  headerTabindex: (key: string, panelDisabled?: boolean) => 0 | -1;
+  /** Header keydown：↑↓ roving + Home/End（命令式 focus()，非 render 期）。 */
+  onHeaderKeydown: (event: KeyboardEvent, key: string) => void;
+  /** Header 获得焦点时同步 focusedKey。 */
+  onHeaderFocus: (key: string) => void;
+  /** 自定义展开图标 Snippet，参数为 {isExpanded}；undefined 时渲染默认箭头 SVG。 */
+  getExpandIcon: () => Snippet<[{ isExpanded: boolean }]> | undefined;
+}
+
+const KEY = Symbol('cd-collapse');
+
+export function setCollapseContext(ctx: CollapseContext): void {
+  setContext(KEY, ctx);
+}
+
+export function getCollapseContext(): CollapseContext | undefined {
+  return getContext<CollapseContext | undefined>(KEY);
+}

package/src/collapse/index.ts

@@ -0,0 +1,17 @@
+import Collapse_ from './Collapse.svelte';
+import CollapsePanelComponent from './CollapsePanel.svelte';
+
+export const Collapse: typeof Collapse_ & {
+  Panel: typeof CollapsePanelComponent;
+} = Object.assign(Collapse_, { Panel: CollapsePanelComponent });
+
+export { CollapsePanelComponent };
+export { meta as collapseMeta } from './meta.js';
+export type { CollapsePanel } from './types.js';
+export {
+  getCollapseContext,
+  setCollapseContext,
+  type CollapseContext,
+  type CollapseSize,
+  type CollapseIconPosition,
+} from './context.js';

package/src/collapse/meta.ts

@@ -0,0 +1,79 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'Collapse',
+  category: 'show',
+  description:
+    '折叠面板，分组承载内容、按需展开。支持数据驱动 panels 与声明式 <Collapse.Panel> 两种用法（择一）、受控 activeKey、accordion 手风琴、展开动画、箭头位置、边框与面板级 disabled。',
+  props: [
+    {
+      name: 'panels',
+      type: 'CollapsePanel[]',
+      default: '[]',
+      desc: '面板头部数据（数据驱动模式；为空且传 children 时切换为声明式 <Collapse.Panel>）',
+    },
+    {
+      name: 'activeKey',
+      type: 'string|string[]',
+      default: 'undefined',
+      desc: '受控展开键，仅 onChange 不回写',
+    },
+    { name: 'defaultActiveKey', type: 'string|string[]', default: 'undefined' },
+    { name: 'accordion', type: 'boolean', default: 'false', desc: '手风琴模式，仅展开一个' },
+    { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
+    { name: 'expandIconPosition', type: "'left'|'right'", default: 'right' },
+    { name: 'bordered', type: 'boolean', default: 'true' },
+    { name: 'disabled', type: 'boolean', default: 'false' },
+    { name: 'motion', type: 'boolean', default: 'true', desc: '展开动画开关' },
+    { name: 'lazyRender', type: 'boolean', default: 'false', desc: '首次展开后才渲染内容' },
+    { name: 'keepDOM', type: 'boolean', default: 'true', desc: '展开过的内容保留 DOM' },
+    { name: 'onChange', type: '(keys: string[]) => void', default: 'undefined' },
+    { name: 'onExpand', type: '(detail: { key: string }) => void', default: 'undefined', desc: '某面板被展开后触发' },
+    { name: 'onCollapse', type: '(detail: { key: string }) => void', default: 'undefined', desc: '某面板被收起后触发' },
+    {
+      name: 'onHeaderClick',
+      type: '(detail: { key: string; event: MouseEvent }) => void',
+      default: 'undefined',
+      desc: 'Header 被点击触发（disabled 拦截前发出，可用于埋点）',
+    },
+    {
+      name: 'children',
+      type: 'Snippet<[{ key: string }]> | Snippet',
+      default: 'undefined',
+      desc: '数据驱动：按 key 渲染面板内容；声明式（不传 panels）：内嵌 <Collapse.Panel> 列表',
+    },
+  ],
+  subcomponents: [
+    {
+      name: 'Collapse.Panel',
+      desc: '声明式单面板，经 Object.assign(Collapse, { Panel }) 导出，父子状态用 context 传递（同 Timeline.Item / Form.Field 复合模式）。等价于 panels 数据驱动的一项，可放富内容头部/内容。',
+      props: [
+        { name: 'itemKey', type: 'string', default: '(required)', desc: '面板唯一标识，等价 panel.key' },
+        { name: 'header', type: 'string', default: 'undefined', desc: '头部文本' },
+        { name: 'disabled', type: 'boolean', default: 'false', desc: '面板级 disabled，该面板不可展开/收起' },
+        { name: 'head', type: 'Snippet', default: 'undefined', desc: '头部富内容插槽，优先于 header' },
+        { name: 'children', type: 'Snippet', default: 'undefined', desc: '面板内容' },
+      ],
+    },
+  ],
+  a11y: {
+    role: 'region',
+    keyboard: ['Tab', 'Enter', 'Space'],
+    notes: [
+      '面板头为原生 button，aria-expanded 标记展开态',
+      'button aria-controls 指向内容 region，region aria-labelledby 指回头部',
+      '折叠时内容区 hidden 移出可达性树',
+      '箭头 aria-hidden=true',
+    ],
+  },
+  tokens: [
+    '--cd-collapse-*',
+    '--cd-focus-ring',
+    '--cd-radius-1',
+    '--cd-spacing-2',
+    '--cd-motion-ease-standard',
+    '--cd-color-text-3',
+  ],
+} as const;

package/src/collapse/types.ts

@@ -0,0 +1,5 @@
+export interface CollapsePanel {
+  key: string;
+  header: string;
+  disabled?: boolean;
+}

package/src/color-picker/ColorPicker.a11y.test.ts

@@ -0,0 +1,60 @@
+// ColorPicker a11y：inline 面板 role=group；saturation/hue/alpha 滑块 role=slider；
+// presets role=listbox/option；trigger 模式按钮 aria-haspopup/aria-expanded，需 ariaLabel 提供可访问名。
+// 浮层不 portal，渲染在 root 容器内，故扫 container（参照 Modal 但无需扫 body）。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import ColorPicker from './ColorPicker.svelte';
+
+describe('ColorPicker a11y', () => {
+  it('inline：role=group 面板 + 滑块 role=slider + presets listbox/option，无 axe violations', async () => {
+    const { container } = renderWithLocale(ColorPicker, {
+      props: { inline: true, defaultValue: '#3370ff', alpha: true, presets: ['#ff0000', '#00ff00'] },
+    });
+    const panel = container.querySelector('[role="group"]');
+    expect(panel).not.toBeNull();
+    expect(panel?.getAttribute('aria-label')).toBeTruthy();
+
+    // saturation / hue / alpha 三个 slider，均有 aria-label + aria-valuenow。
+    const sliders = container.querySelectorAll('[role="slider"]');
+    expect(sliders.length).toBeGreaterThanOrEqual(3);
+    sliders.forEach((s) => {
+      expect(s.getAttribute('aria-label')).toBeTruthy();
+      expect(s.getAttribute('aria-valuenow')).not.toBeNull();
+    });
+
+    // presets：listbox + option，可访问名/选中态。
+    const listbox = container.querySelector('[role="listbox"]');
+    expect(listbox).not.toBeNull();
+    expect(listbox?.getAttribute('aria-label')).toBeTruthy();
+    const options = container.querySelectorAll('[role="option"]');
+    expect(options.length).toBe(2);
+    expect(options[0]?.getAttribute('aria-label')).toBeTruthy();
+
+    await expectNoAxeViolations(container);
+  });
+
+  it('trigger 模式（关闭态）：trigger 按钮 aria-haspopup=dialog / aria-expanded=false / ariaLabel 可访问名', async () => {
+    const { container } = renderWithLocale(ColorPicker, {
+      props: { ariaLabel: 'Pick brand color', defaultValue: '#3370ff' },
+    });
+    const trigger = container.querySelector('.cd-color-picker__trigger');
+    expect(trigger?.getAttribute('aria-haspopup')).toBe('dialog');
+    expect(trigger?.getAttribute('aria-expanded')).toBe('false');
+    expect(trigger?.getAttribute('aria-label')).toBe('Pick brand color');
+    await expectNoAxeViolations(container);
+  });
+
+  it('trigger 模式（打开态）：role=dialog 面板渲染于容器内，aria-expanded=true，无 axe violations', async () => {
+    const { container } = renderWithLocale(ColorPicker, {
+      props: { ariaLabel: 'Background color', open: true, defaultValue: '#112233' },
+    });
+    const trigger = container.querySelector('.cd-color-picker__trigger');
+    expect(trigger?.getAttribute('aria-expanded')).toBe('true');
+    // 浮层非 portal：直接在 root 容器内查询。
+    const dialog = container.querySelector('[role="dialog"]');
+    expect(dialog).not.toBeNull();
+    expect(dialog?.getAttribute('aria-label')).toBe('Background color');
+    expect(container.querySelectorAll('[role="slider"]').length).toBeGreaterThanOrEqual(2);
+    await expectNoAxeViolations(container);
+  });
+});

package/src/color-picker/ColorPicker.kbd.test.ts

@@ -0,0 +1,73 @@
+// ColorPicker 键盘 e2e（browser project / 真实 chromium）。
+// 测浮层 focus-trap 的真实焦点行为——jsdom 测不了（焦点模型不完整）：
+//   1. 点 trigger 打开后焦点进入面板内首个可聚焦控件（饱和度 slider）。
+//   2. Tab 循环被困在面板内：Tab 到最后一个再 Tab 回第一个；Shift+Tab 反向。
+//   3. Esc 关闭后焦点归还触发元素（trigger）。
+//
+// ColorPicker 浮层「非 portal」：面板渲染在 .cd-color-picker 根容器内，
+// 故在 fixture container 范围内查 [role=dialog]（不在 document 查）。
+import { describe, it, expect, vi } from 'vitest';
+import { page } from 'vitest/browser';
+import { renderKbdFixture, userEvent } from '../test-utils/kbd.js';
+import ColorPickerKbdFixture from './ColorPickerKbdFixture.svelte';
+
+function loc(el: Element) {
+  return page.elementLocator(el);
+}
+
+function focusablesIn(panel: HTMLElement) {
+  return Array.from(
+    panel.querySelectorAll<HTMLElement>(
+      'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]),select:not([disabled]),[tabindex]:not([tabindex="-1"])',
+    ),
+  ).filter((el) => el.offsetParent !== null);
+}
+
+describe('ColorPicker 键盘 e2e（focus trap）', () => {
+  it('打开后焦点进入面板首控件；Tab 循环困在面板内；Esc 关闭后焦点归还 trigger', async () => {
+    const { container } = renderKbdFixture(ColorPickerKbdFixture);
+
+    // trigger 是 ColorPicker 自带按钮（非 portal，在 container 内）。
+    // 该按钮尺寸来自 CSS token（测试环境未加载组件 token 样式表，故渲染为 0×0，
+    // userEvent.click 的可见性门槛过不去）。改用原生 focus()+click()：先聚焦使其成为
+    // 焦点归还锚点（focus-trap activate 时记录的 previouslyFocused），再触发打开。
+    const trigger = container.querySelector('.cd-color-picker__trigger') as HTMLButtonElement;
+    expect(trigger).not.toBeNull();
+    trigger.focus();
+    await expect.element(loc(trigger)).toHaveFocus();
+    trigger.click();
+
+    // 浮层非 portal —— 在 container 范围查面板（role=dialog）。
+    // click 触发的 open 状态更新→重渲染是异步的，轮询等面板出现。
+    await vi.waitFor(() => {
+      const p = container.querySelector('[role="dialog"]');
+      expect(p).not.toBeNull();
+    });
+    const panel = container.querySelector('[role="dialog"]') as HTMLElement;
+    await expect.element(loc(panel)).toBeInTheDocument();
+
+    // 1. 焦点进入面板内（focus-trap activate 聚焦首个可聚焦控件）。
+    expect(panel.contains(document.activeElement)).toBe(true);
+
+    const focusables = focusablesIn(panel);
+    expect(focusables.length).toBeGreaterThan(1);
+    const first = focusables[0]!;
+    const last = focusables[focusables.length - 1]!;
+
+    // 2a. 焦点移到最后一个，再 Tab → 循环回第一个（被困住，不逃出面板）。
+    last.focus();
+    await expect.element(loc(last)).toHaveFocus();
+    await userEvent.tab();
+    await expect.element(loc(first)).toHaveFocus();
+    expect(panel.contains(document.activeElement)).toBe(true);
+
+    // 2b. Shift+Tab 从第一个 → 循环回最后一个。
+    await userEvent.tab({ shift: true });
+    await expect.element(loc(last)).toHaveFocus();
+    expect(panel.contains(document.activeElement)).toBe(true);
+
+    // 3. Esc 关闭 —— focus-trap deactivate 把焦点归还 trigger。
+    await userEvent.keyboard('{Escape}');
+    await expect.element(loc(trigger)).toHaveFocus();
+  });
+});