@chenzy-design/svelte 0.1.0

package/src/scroll-list/ScrollList.svelte

@@ -0,0 +1,257 @@
+<!--
+  ScrollList — see specs/components/show/ScrollList.spec.md
+  滚轮选择器：JS 主导定位吸附居中，中央选区遮罩 + 上下渐隐。
+  单列（data）向后兼容；多列（columns）联动，值为各列组合数组。
+  进阶：cyclic 循环、惯性物理（pointer 拖拽 + 减速）、虚拟化、loadMore、status。
+  复用 @chenzy-design/core 纯函数（offset/index/cyclic/momentum/virtual）。
+  受控 value 不回写仅 onChange（红线 #1）；监听/动画命令式 + cleanup（红线 #3）；
+  列联动/循环/虚拟窗口派生纯函数（红线 #2）。单列逐列封装在 ScrollColumn 子组件。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { untrack } from 'svelte';
+  import {
+    useId,
+    indexOfValue,
+    firstEnabledIndex,
+    type ScrollListValue,
+    type ScrollListItem,
+  } from '@chenzy-design/core';
+  import { useLocale } from '../locale-provider/index.js';
+  import ScrollColumn from './ScrollColumn.svelte';
+  import type { ScrollListColumn, ScrollListStatus } from './types.js';
+
+  type Size = 'small' | 'default' | 'large';
+  type Status = ScrollListStatus;
+
+  type ChangeInfo = {
+    /** 单列：选中值；多列：各列值数组。 */
+    value: ScrollListValue | ScrollListValue[];
+    /** 单列时提供 item/index；多列省略。 */
+    item?: ScrollListItem;
+    index?: number;
+    /** 多列：发生变化的列序号。 */
+    column?: number;
+  };
+
+  interface Props {
+    value?: ScrollListValue | ScrollListValue[];
+    defaultValue?: ScrollListValue | ScrollListValue[];
+    /** 单列数据（向后兼容）。与 columns 互斥；columns 优先。 */
+    data?: ScrollListItem[];
+    /** 多列配置。提供时进入多列模式。 */
+    columns?: ScrollListColumn[];
+    size?: Size;
+    rows?: number;
+    itemHeight?: number;
+    disabled?: boolean;
+    /** 全局循环（单列或所有列）；列级 cyclic 覆盖之。 */
+    cyclic?: boolean;
+    /** 虚拟化（列项很多时）。 */
+    virtualized?: boolean;
+    overscan?: number;
+    /** 单列加载/空状态。 */
+    status?: Status;
+    emptyText?: string;
+    loadingText?: string;
+    ariaLabel?: string;
+    /** 单列滚到末尾加载更多。 */
+    onLoadMore?: () => void;
+    renderItem?: Snippet<[{ item: ScrollListItem; selected: boolean; index: number }]>;
+    onChange?: (info: ChangeInfo) => void;
+  }
+
+  let {
+    value,
+    defaultValue,
+    data = [],
+    columns,
+    size = 'default',
+    rows = 5,
+    itemHeight,
+    disabled = false,
+    cyclic = false,
+    virtualized = false,
+    overscan = 3,
+    status = 'idle',
+    emptyText,
+    loadingText,
+    ariaLabel,
+    onLoadMore,
+    renderItem,
+    onChange,
+  }: Props = $props();
+
+  const loc = useLocale();
+  // 稳定 id 前缀（每列追加列号），SSR/水合一致。
+  const baseId = useId('cd-scroll-list');
+
+  const ih = $derived(itemHeight ?? { small: 28, default: 36, large: 44 }[size]);
+  const isMulti = $derived(Array.isArray(columns) && columns.length > 0);
+
+  // 归一化为「列数组」：单列模式包成一项。
+  const colDefs = $derived.by<ScrollListColumn[]>(() => {
+    if (isMulti) return columns!;
+    const single: ScrollListColumn = { data, cyclic, status };
+    if (ariaLabel !== undefined) single.ariaLabel = ariaLabel;
+    if (onLoadMore !== undefined) single.onLoadMore = onLoadMore;
+    return [single];
+  });
+  const isControlled = $derived(value !== undefined);
+
+  // 把外部 value/defaultValue 归一化为「逐列 value」数组。
+  function valueForColumn(col: number, seed: ScrollListValue | ScrollListValue[] | undefined):
+    | ScrollListValue
+    | undefined {
+    if (seed === undefined) return undefined;
+    if (Array.isArray(seed)) return seed[col];
+    return col === 0 ? seed : undefined;
+  }
+
+  // 每列当前逻辑 index（受控时派生自 value，非受控用 defaultValue 解析初值后由列内部维护）。
+  function resolveColIndex(col: number, seed: ScrollListValue | ScrollListValue[] | undefined): number {
+    const items = colDefs[col]?.data ?? [];
+    const v = valueForColumn(col, seed);
+    const i = indexOfValue(items, v);
+    if (i >= 0 && !items[i]?.disabled) return i;
+    const f = firstEnabledIndex(items);
+    return f === -1 ? 0 : f;
+  }
+
+  // 受控时每列 index 派生自 value；非受控传初值（defaultValue 或 value）。
+  const controlledIndices = $derived.by(() =>
+    colDefs.map((_, col) => resolveColIndex(col, value)),
+  );
+  const initialIndices = untrack(() =>
+    colDefs.map((_, col) => resolveColIndex(col, value !== undefined ? value : defaultValue)),
+  );
+
+  // 非受控：记录各列当前逻辑 index（用于组装多列 onChange 的 values）。
+  let innerIndices = $state<number[]>(untrack(() => [...initialIndices]));
+
+  // 列变更 → 组装 onChange（红线 #1：受控不回写，仅回调）。
+  function handleColSelect(col: number, logicalIndex: number): void {
+    if (!isControlled) {
+      const next = [...innerIndices];
+      next[col] = logicalIndex;
+      innerIndices = next;
+    }
+    const item = colDefs[col]?.data[logicalIndex];
+    if (!item) return;
+
+    if (isMulti) {
+      // 组装各列当前值数组（变更列用最新，其它列用受控值或内部值）。
+      const values = colDefs.map((c, ci) => {
+        const idx =
+          ci === col
+            ? logicalIndex
+            : (isControlled ? controlledIndices[ci] : innerIndices[ci]) ?? 0;
+        return c.data[idx]?.value as ScrollListValue;
+      });
+      onChange?.({ value: values, column: col });
+    } else {
+      onChange?.({ value: item.value, item, index: logicalIndex });
+    }
+  }
+
+  const viewportHeight = $derived(ih * rows);
+  const resolvedEmpty = $derived(emptyText ?? loc().t('ScrollList.empty'));
+  const resolvedLoading = $derived(loadingText ?? loc().t('ScrollList.loading'));
+
+  const cls = $derived(
+    [
+      'cd-scroll-list',
+      `cd-scroll-list--${size}`,
+      isMulti && 'cd-scroll-list--multi',
+      disabled && 'cd-scroll-list--disabled',
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+</script>
+
+<div
+  class={cls}
+  style="--cd-sl-item-height: {ih}px; --cd-sl-viewport-height: {viewportHeight}px;"
+>
+  <div class="cd-scroll-list__cols">
+    {#each colDefs as col, ci (ci)}
+      <ScrollColumn
+        data={col.data}
+        index={(isControlled ? controlledIndices[ci] : innerIndices[ci]) ?? 0}
+        controlled={isControlled}
+        itemHeight={ih}
+        {rows}
+        {disabled}
+        cyclic={col.cyclic ?? cyclic}
+        {virtualized}
+        {overscan}
+        status={col.status ?? status}
+        emptyText={resolvedEmpty}
+        loadingText={resolvedLoading}
+        ariaLabel={col.ariaLabel ?? ariaLabel ?? loc().t('ScrollList.ariaLabel')}
+        itemIdPrefix={`${baseId}-c${ci}`}
+        {renderItem}
+        onSelect={(i) => handleColSelect(ci, i)}
+        onLoadMore={col.onLoadMore}
+      />
+    {/each}
+  </div>
+
+  <div class="cd-scroll-list__mask" aria-hidden="true"></div>
+  <div class="cd-scroll-list__gradient cd-scroll-list__gradient--top" aria-hidden="true"></div>
+  <div class="cd-scroll-list__gradient cd-scroll-list__gradient--bottom" aria-hidden="true"></div>
+</div>
+
+<style>
+  .cd-scroll-list {
+    position: relative;
+    inline-size: 100%;
+    block-size: var(--cd-sl-viewport-height);
+    overflow: hidden;
+    border: 1px solid var(--cd-scrolllist-border-color);
+    border-radius: var(--cd-scrolllist-radius);
+    color: var(--cd-scrolllist-color-text-adjacent);
+    font-size: var(--cd-font-size-body);
+  }
+
+  .cd-scroll-list__cols {
+    display: flex;
+    block-size: 100%;
+  }
+
+  .cd-scroll-list--disabled .cd-scroll-list__cols {
+    pointer-events: none;
+  }
+
+  /* 中央选区遮罩：居中一行，上下 1px 边框 */
+  .cd-scroll-list__mask {
+    position: absolute;
+    inset-inline: 0;
+    inset-block-start: calc(50% - var(--cd-sl-item-height) / 2);
+    block-size: var(--cd-sl-item-height);
+    background: var(--cd-scrolllist-mask-bg);
+    border-block: 1px solid var(--cd-scrolllist-mask-border);
+    pointer-events: none;
+  }
+
+  /* 上/下渐隐 */
+  .cd-scroll-list__gradient {
+    position: absolute;
+    inset-inline: 0;
+    block-size: calc((var(--cd-sl-viewport-height) - var(--cd-sl-item-height)) / 2);
+    pointer-events: none;
+  }
+  .cd-scroll-list__gradient--top {
+    inset-block-start: 0;
+    background: linear-gradient(
+      to bottom,
+      var(--cd-scrolllist-gradient-color),
+      transparent
+    );
+  }
+  .cd-scroll-list__gradient--bottom {
+    inset-block-end: 0;
+    background: linear-gradient(to top, var(--cd-scrolllist-gradient-color), transparent);
+  }
+</style>

package/src/scroll-list/index.ts

@@ -0,0 +1,4 @@
+export { default as ScrollList } from './ScrollList.svelte';
+export { meta as scrollListMeta } from './meta.js';
+export type { ScrollListColumn, ScrollListStatus } from './types.js';
+export type { ScrollListItem, ScrollListValue } from '@chenzy-design/core';

package/src/scroll-list/meta.ts

@@ -0,0 +1,93 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * ScrollList — see specs/components/show/ScrollList.spec.md
+ */
+export const meta = {
+  name: 'ScrollList',
+  category: 'show',
+  description:
+    '滚轮选择器：JS 主导定位吸附居中，中央选区遮罩 + 上下渐隐，支持点击/键盘/拖拽选中、disabled 项跳过，受控 value 不回写仅通过 onChange 通知。单列（data）向后兼容；多列（columns）联动，值为各列组合数组。进阶能力：cyclic 循环滚动、惯性物理（pointer 拖拽 + 指数减速 + 预测吸附）、虚拟化（列项很多时只渲染视口）、loadMore（滚到末尾加载更多）、status（loading/empty 状态）。复用 @chenzy-design/core 纯函数（offsetToIndex/indexToOffset/keyboardTarget/wrapIndex/cyclicCenterIndex/cyclicRecenter/momentumStep/projectSettleIndex/fixedRange）。',
+  exports: ['ScrollList'],
+  props: [
+    { name: 'value', type: 'string | number | (string|number)[]', default: 'undefined', desc: '受控选中值；多列为数组；受控时不回写' },
+    { name: 'defaultValue', type: 'string | number | (string|number)[]', default: 'undefined', desc: '非受控初始值；多列为数组' },
+    { name: 'data', type: 'ScrollListItem[]', default: '[]', desc: '单列选项数据（与 columns 互斥）' },
+    { name: 'columns', type: 'ScrollListColumn[]', default: 'undefined', desc: '多列配置；提供时进入多列联动模式' },
+    { name: 'cyclic', type: 'boolean', default: 'false', desc: '循环滚动（滚到底接回开头）；列级可覆盖' },
+    { name: 'virtualized', type: 'boolean', default: 'false', desc: '虚拟化：列项很多时只渲染视口范围' },
+    { name: 'overscan', type: 'number', default: '3', desc: '虚拟化视口上下缓冲行数' },
+    { name: 'status', type: "'idle'|'loading'|'empty'", default: "'idle'", desc: '列状态；loading 显示加载中、empty 显示空文案' },
+    { name: 'emptyText', type: 'string', default: 'i18n', desc: '空状态文案' },
+    { name: 'loadingText', type: 'string', default: 'i18n', desc: '加载中文案' },
+    { name: 'onLoadMore', type: '() => void', default: 'undefined', desc: '单列滚到末尾触发加载更多（非 cyclic）' },
+    {
+      name: 'size',
+      type: "'small'|'default'|'large'",
+      default: "'default'",
+      desc: '决定 itemHeight 28/36/44',
+    },
+    { name: 'rows', type: 'number', default: '5', desc: '可见行数（奇数）' },
+    { name: 'itemHeight', type: 'number', default: 'undefined', desc: '显式覆盖 size 推导的行高' },
+    { name: 'disabled', type: 'boolean', default: 'false', desc: '禁止滚动与选中交互' },
+    { name: 'ariaLabel', type: 'string', default: "'滚动选择'", desc: 'listbox 无障碍标签' },
+    {
+      name: 'renderItem',
+      type: 'Snippet<[{ item; selected; index }]>',
+      default: 'undefined',
+      desc: '自定义单项渲染',
+    },
+    {
+      name: 'onChange',
+      type: '(info: { value; item; index }) => void',
+      default: 'undefined',
+      desc: '选中变化回调',
+    },
+  ],
+  events: [
+    { name: 'onChange', desc: '居中选中项变化（滚动落定 / 点击 / 键盘 / 拖拽惯性）；单列回调 {value,item,index}，多列回调 {value:数组,column}' },
+    { name: 'onLoadMore', desc: '滚到末尾触发加载更多' },
+  ],
+  slots: [{ name: 'renderItem', desc: '自定义单项渲染，提供 item/selected/index' }],
+  a11y: {
+    hasRole: true,
+    focusable: true,
+    note: 'role=listbox + aria-orientation=vertical + aria-activedescendant 指向居中项；每项 role=option + aria-selected；单一 tab stop；键盘 ArrowUp/Down、PageUp/Down、Home/End 移动选中，disabled 项自动跳过。',
+  },
+  tokens: [
+    '--cd-scrolllist-item-height',
+    '--cd-scrolllist-item-height-small',
+    '--cd-scrolllist-item-height-large',
+    '--cd-scrolllist-color-text',
+    '--cd-scrolllist-color-text-adjacent',
+    '--cd-scrolllist-color-text-disabled',
+    '--cd-scrolllist-mask-bg',
+    '--cd-scrolllist-mask-border',
+    '--cd-scrolllist-gradient-color',
+    '--cd-scrolllist-border-color',
+    '--cd-scrolllist-radius',
+    '--cd-scrolllist-transition',
+  ],
+  responsive: false,
+  examples: [
+    {
+      title: '基础数字选择',
+      code: '<ScrollList data={hours} defaultValue={9} onChange={(i) => (v = i.value)} />',
+    },
+    {
+      title: '自定义渲染',
+      code: '<ScrollList data={list}>{#snippet renderItem({ item, selected })}<span class:on={selected}>{item.label}</span>{/snippet}</ScrollList>',
+    },
+    {
+      title: '多列联动（年/月/日）',
+      code: '<ScrollList columns={[{ data: years }, { data: months }, { data: days, cyclic: true }]} value={[2024, 2, 15]} onChange={(i) => (date = i.value)} />',
+    },
+    {
+      title: 'cyclic 循环 + 惯性拖拽',
+      code: '<ScrollList data={hours} cyclic defaultValue={12} />',
+    },
+    {
+      title: '虚拟化 + loadMore + status',
+      code: '<ScrollList data={big} virtualized status={loading ? "loading" : "idle"} onLoadMore={fetchMore} />',
+    },
+  ],
+} as const;

package/src/scroll-list/types.ts

@@ -0,0 +1,18 @@
+import type { ScrollListItem } from '@chenzy-design/core';
+
+/** 列状态：空闲 / 加载中 / 空。 */
+export type ScrollListStatus = 'idle' | 'loading' | 'empty';
+
+/** 多列模式下单列配置项（columns 数组元素）。 */
+export interface ScrollListColumn {
+  /** 本列选项数据。 */
+  data: ScrollListItem[];
+  /** 本列是否循环滚动（覆盖全局 cyclic）。 */
+  cyclic?: boolean;
+  /** 本列加载/空状态（覆盖全局 status）。 */
+  status?: ScrollListStatus;
+  /** 本列无障碍标签。 */
+  ariaLabel?: string;
+  /** 本列滚到末尾触发加载更多（非 cyclic 有效）。 */
+  onLoadMore?: () => void;
+}

package/src/select/Select.a11y.test.ts

@@ -0,0 +1,59 @@
+// Select a11y：combobox 触发器 + listbox/option 浮层（use:floating portal 到 body）。
+// 只断言静态 ARIA + axe，不测真实键盘/焦点（jsdom 限制）。
+//
+// 修复记录：根 `<div role="combobox">` 现经 ariaLabel/ariaLabelledby prop 或
+//   placeholder / locale Select.ariaLabel 回退获可访问名，axe aria-input-field-name 消除。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import Select from './Select.svelte';
+
+const options = [
+  { label: 'Apple', value: 'apple' },
+  { label: 'Banana', value: 'banana' },
+  { label: 'Cherry', value: 'cherry' },
+];
+
+describe('Select a11y', () => {
+  it('关闭态：触发器 role=combobox / aria-expanded=false / aria-haspopup=listbox（结构断言）', () => {
+    const { container } = renderWithLocale(Select, {
+      props: { options, placeholder: 'Pick a fruit' },
+    });
+    const combobox = container.querySelector('[role="combobox"]');
+    expect(combobox).not.toBeNull();
+    expect(combobox?.getAttribute('aria-expanded')).toBe('false');
+    expect(combobox?.getAttribute('aria-haspopup')).toBe('listbox');
+  });
+
+  it('打开态：listbox + option 渲染（结构断言）', () => {
+    renderWithLocale(Select, {
+      props: { options, defaultOpen: true, placeholder: 'Pick a fruit' },
+    });
+    const listbox = document.querySelector('[role="listbox"]');
+    expect(listbox).not.toBeNull();
+    expect(document.querySelectorAll('[role="option"]').length).toBe(options.length);
+  });
+
+  it('已选值：选中 option aria-selected=true（结构断言）', () => {
+    renderWithLocale(Select, {
+      props: { options, defaultOpen: true, defaultValue: 'banana' },
+    });
+    const selected = document.querySelector('[role="option"][aria-selected="true"]');
+    expect(selected?.textContent).toContain('Banana');
+  });
+
+  it('多选：aria-multiselectable=true（结构断言）', () => {
+    renderWithLocale(Select, {
+      props: { options, defaultOpen: true, multiple: true },
+    });
+    expect(document.querySelector('[role="listbox"]')?.getAttribute('aria-multiselectable')).toBe('true');
+  });
+
+  // combobox 可访问名回退到 placeholder（缺省走 locale Select.ariaLabel）。
+  it('打开态：axe 0 violations（combobox 经 placeholder/locale 获可访问名）', async () => {
+    renderWithLocale(Select, {
+      props: { options, defaultOpen: true, placeholder: 'Pick a fruit' },
+    });
+    expect(document.querySelector('[role="combobox"]')?.getAttribute('aria-label')).toBe('Pick a fruit');
+    await expectNoAxeViolations(document.body);
+  });
+});

package/src/select/Select.kbd.test.ts

@@ -0,0 +1,59 @@
+// Select 键盘 e2e（browser project / 真实 chromium），浮层方向键导航。
+// Select 高亮走 aria-activedescendant 模式：焦点始终留在 role=combobox 触发器上
+// （options tabindex=-1，从不真实聚焦），"高亮项"由触发器的 aria-activedescendant
+// 指向的 option id 表达。故断言 activedescendant 指向的 option id 变化，而非 toHaveFocus。
+// 浮层经 use:floating portal 到 document.body —— 在 document 范围查 listbox。
+//   1. 打开后 ↓ 高亮首项（opt-0），再 ↓ 移到 opt-1；↑ 回到 opt-0。
+//   2. Home/End 跳列表首/末。
+//   3. Enter 选中当前高亮项（onChange 写入夹具 output）。
+import { describe, it, expect } from 'vitest';
+import { renderKbdFixture, userEvent } from '../test-utils/kbd.js';
+import SelectKbdFixture from './SelectKbdFixture.svelte';
+
+describe('Select 键盘 e2e（aria-activedescendant 浮层导航）', () => {
+  it('打开后 ↑↓ 移高亮 + Home/End 首末 + Enter 选中', async () => {
+    renderKbdFixture(SelectKbdFixture);
+
+    const combobox = document.querySelector('[role="combobox"]') as HTMLElement;
+    expect(combobox).not.toBeNull();
+
+    // 点击触发器打开浮层（焦点留在 combobox）。
+    await userEvent.click(combobox);
+    const listbox = document.querySelector('[role="listbox"]') as HTMLElement;
+    expect(listbox).not.toBeNull();
+    const listId = listbox.id;
+    expect(listId).toBeTruthy();
+
+    const options = Array.from(
+      listbox.querySelectorAll<HTMLElement>('[role="option"]'),
+    );
+    expect(options.length).toBe(3);
+
+    // 焦点在 combobox 上，options 不可真实聚焦（tabindex=-1）。
+    expect(options.every((o) => o.tabIndex === -1)).toBe(true);
+
+    // 1. ↓ 高亮首项（activeIndex -1 → 0），aria-activedescendant 指向 opt-0。
+    await userEvent.keyboard('{ArrowDown}');
+    expect(combobox.getAttribute('aria-activedescendant')).toBe(`${listId}-opt-0`);
+    expect(options[0]!.classList.contains('cd-select__option--active')).toBe(true);
+
+    // 再 ↓ 移到 opt-1。
+    await userEvent.keyboard('{ArrowDown}');
+    expect(combobox.getAttribute('aria-activedescendant')).toBe(`${listId}-opt-1`);
+
+    // ↑ 回到 opt-0。
+    await userEvent.keyboard('{ArrowUp}');
+    expect(combobox.getAttribute('aria-activedescendant')).toBe(`${listId}-opt-0`);
+
+    // 2. End 跳末项（opt-2）；Home 回首项（opt-0）。
+    await userEvent.keyboard('{End}');
+    expect(combobox.getAttribute('aria-activedescendant')).toBe(`${listId}-opt-2`);
+    await userEvent.keyboard('{Home}');
+    expect(combobox.getAttribute('aria-activedescendant')).toBe(`${listId}-opt-0`);
+
+    // 3. Enter 选中当前高亮项（opt-0 = Apple），onChange 写入夹具 output。
+    await userEvent.keyboard('{Enter}');
+    const out = document.querySelector('[data-testid="value"]') as HTMLElement;
+    expect(out.textContent).toBe(JSON.stringify('apple'));
+  });
+});