@chenzy-design/svelte 0.1.0 → 0.2.0

package/src/scroll-list/ScrollList.svelte

@@ -1,257 +0,0 @@
-<!--
-  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

@@ -1,4 +0,0 @@
-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

@@ -1,93 +0,0 @@
-/**
- * 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

@@ -1,18 +0,0 @@
-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

@@ -1,59 +0,0 @@
-// 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

@@ -1,59 +0,0 @@
-// 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'));
-  });
-});