@chenzy-design/svelte 0.1.0

package/src/timeline/TimelineItem.svelte

@@ -0,0 +1,164 @@
+<!--
+  Timeline.Item — 声明式单项，与 dataSource 模式渲染同一套 .cd-timeline__item 结构，
+  从而复用父 Timeline 的 :nth-child 交替布局 CSS（alternate/center）与方向样式，无需索引计算。
+
+  interactive：父 Timeline 开启时，项渲染为可聚焦 role=button，roving tabindex 由父持有的
+  焦点 id 决定（getter 经 context 保持响应性，项不写 $state——红线 #2）。方向键 roving 上交父级
+  处理，Enter/Space 触发本项 onClick。挂载时经 context 领号、卸载时退号（命令式 cleanup）。
+-->
+<script lang="ts">
+  import { untrack, type Snippet } from 'svelte';
+  import { getTimelineContext, type TimelineLineStyle } from './context.js';
+
+  interface Props {
+    /** 圆点颜色（等价 dataSource 项的 dotColor/color）。 */
+    dotColor?: string;
+    /** 圆点颜色别名（与 dotColor 等价，优先级低于 dotColor）。 */
+    color?: string;
+    /** 语义类型，给圆点附加 cd-timeline__dot--{type} class。 */
+    type?: 'default' | 'ongoing' | 'success' | 'warning' | 'error';
+    /** 自定义圆点 snippet，提供时替代默认圆点。 */
+    dot?: Snippet;
+    /** 单项连接线样式，覆盖父 Timeline 的 lineStyle。 */
+    lineStyle?: TimelineLineStyle;
+    /** 时间文本，渲染在内容下方（horizontal 模式同 dataSource）。 */
+    time?: string;
+    /** 覆盖父 Timeline mode 的单项定位（'left' | 'right'）。 */
+    position?: 'left' | 'right';
+    /** 辅助内容（时间旁附加信息），字符串或 Snippet。 */
+    extra?: string | Snippet;
+    /** interactive 模式下按 Enter/Space 或点击该节点触发。 */
+    onClick?: () => void;
+    children?: Snippet;
+  }
+
+  let { dotColor, color, type, dot, lineStyle, time, position, extra, onClick, children }: Props = $props();
+
+  const ctx = getTimelineContext();
+
+  // 未显式指定时回退到父 Timeline 的 lineStyle。
+  const effectiveLine = $derived<TimelineLineStyle>(lineStyle ?? ctx?.getLineStyle() ?? 'solid');
+
+  // dotColor 优先，其次 color 别名。
+  const effectiveDotColor = $derived(dotColor ?? color);
+
+  const dotInline = $derived(effectiveDotColor ? `--cd-timeline-dot-current: ${effectiveDotColor};` : undefined);
+
+  const dotClass = $derived(
+    ['cd-timeline__dot', type && type !== 'default' && `cd-timeline__dot--${type}`]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  // interactive：在 $effect 内 mount 领号 / unmount 退号（仿 Tabs；untrack 读初值仅跑一次，
+  // 避免重注册打乱保序）。项自身不参与 roving 簿记 $state。
+  const interactive = $derived(ctx?.getInteractive() ?? false);
+  let myId = $state(-1);
+  $effect(() => {
+    const reg = ctx?.registerItem;
+    if (!reg) return;
+    const r = untrack(() => reg());
+    myId = r.id;
+    return r.unregister;
+  });
+
+  // roving tabindex：焦点项 0，其余 -1（焦点状态经 context getter 读取，保持响应性）。
+  const tindex = $derived(interactive && myId >= 0 && ctx?.isFocused(myId) ? 0 : -1);
+
+  function onKeydown(e: KeyboardEvent): void {
+    if (!interactive) return;
+    // Enter/Space 触发本项 onClick；方向键 roving 交父级。
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      onClick?.();
+      return;
+    }
+    ctx?.onItemKeydown(myId, e);
+  }
+
+  function onActivate(): void {
+    if (!interactive) {
+      onClick?.();
+      return;
+    }
+    ctx?.onItemFocus(myId);
+    onClick?.();
+  }
+</script>
+
+{#if interactive}
+  <!-- svelte-ignore a11y_no_noninteractive_element_to_interactive_role -->
+  <li
+    class={[
+      'cd-timeline__item',
+      'cd-timeline__item--interactive',
+      effectiveLine === 'dashed' && 'cd-timeline__item--dashed',
+      position && `cd-timeline__item--${position}`,
+    ]}
+    role="button"
+    tabindex={tindex}
+    data-tid={myId}
+    onclick={onActivate}
+    onkeydown={onKeydown}
+    onfocus={() => ctx?.onItemFocus(myId)}
+  >
+    <span class="cd-timeline__tail" aria-hidden="true"></span>
+    <span class={dotClass} style={dotInline} aria-hidden="true">
+      {#if dot}{@render dot()}{/if}
+    </span>
+    <div class="cd-timeline__body">
+      <div class="cd-timeline__content">{@render children?.()}</div>
+      {#if time || extra}
+        <div class="cd-timeline__time">
+          {#if time}{time}{/if}
+          {#if extra}
+            {#if typeof extra === 'string'}
+              <span class="cd-timeline__extra">{extra}</span>
+            {:else}
+              <span class="cd-timeline__extra">{@render extra()}</span>
+            {/if}
+          {/if}
+        </div>
+      {/if}
+    </div>
+  </li>
+{:else}
+  <li
+    class={[
+      'cd-timeline__item',
+      effectiveLine === 'dashed' && 'cd-timeline__item--dashed',
+      position && `cd-timeline__item--${position}`,
+    ]}
+  >
+    <span class="cd-timeline__tail" aria-hidden="true"></span>
+    <span class={dotClass} style={dotInline} aria-hidden="true">
+      {#if dot}{@render dot()}{/if}
+    </span>
+    <div class="cd-timeline__body">
+      <div class="cd-timeline__content">{@render children?.()}</div>
+      {#if time || extra}
+        <div class="cd-timeline__time">
+          {#if time}{time}{/if}
+          {#if extra}
+            {#if typeof extra === 'string'}
+              <span class="cd-timeline__extra">{extra}</span>
+            {:else}
+              <span class="cd-timeline__extra">{@render extra()}</span>
+            {/if}
+          {/if}
+        </div>
+      {/if}
+    </div>
+  </li>
+{/if}
+
+<style>
+  /* 单项 dashed 覆盖：作用于自身 tail，优先于父级 solid。 */
+  .cd-timeline__item--dashed .cd-timeline__tail {
+    border-inline-start-style: dashed;
+  }
+  :global(.cd-timeline--horizontal) .cd-timeline__item--dashed .cd-timeline__tail {
+    border-inline-start: none;
+    border-block-start-style: dashed;
+  }
+</style>

package/src/timeline/context.ts

@@ -0,0 +1,28 @@
+import { getContext, setContext } from 'svelte';
+
+export type TimelineLineStyle = 'solid' | 'dashed';
+
+export interface TimelineContext {
+  // getter 保持对父 Timeline prop 变化的响应性（直接读快照会冻结初始值）。
+  getLineStyle: () => TimelineLineStyle;
+  /** interactive 是否开启（getter 保持响应性）。 */
+  getInteractive: () => boolean;
+  /** 声明式项挂载时领号，返回 id 与卸载清理；id 构成 roving 序列。 */
+  registerItem: () => { id: number; unregister: () => void };
+  /** 该 id 是否为当前 roving 焦点项（决定 tabindex 0/-1）。 */
+  isFocused: (id: number) => boolean;
+  /** 声明式项键盘事件冒泡到父：方向键 roving 由父处理（Enter/Space 由项自身处理）。 */
+  onItemKeydown: (id: number, e: KeyboardEvent) => void;
+  /** 项获得焦点时同步父级焦点索引（点击/Tab 进入）。 */
+  onItemFocus: (id: number) => void;
+}
+
+const KEY = Symbol('cd-timeline');
+
+export function setTimelineContext(ctx: TimelineContext): void {
+  setContext(KEY, ctx);
+}
+
+export function getTimelineContext(): TimelineContext | undefined {
+  return getContext<TimelineContext | undefined>(KEY);
+}

package/src/timeline/index.ts

@@ -0,0 +1,16 @@
+import Timeline_ from './Timeline.svelte';
+import TimelineItem from './TimelineItem.svelte';
+
+export const Timeline: typeof Timeline_ & {
+  Item: typeof TimelineItem;
+} = Object.assign(Timeline_, { Item: TimelineItem });
+
+export { TimelineItem };
+export { meta as timelineMeta } from './meta.js';
+export type { TimelineItemData } from './types.js';
+export {
+  getTimelineContext,
+  setTimelineContext,
+  type TimelineContext,
+  type TimelineLineStyle,
+} from './context.js';

package/src/timeline/meta.ts

@@ -0,0 +1,129 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'Timeline',
+  category: 'show',
+  description:
+    '时间轴，按时间顺序垂直/水平展示一组事件。两种用法择一：传 dataSource 数据驱动，或不传 dataSource 而在 children 内写 <Timeline.Item> 声明式（可放任意富内容）。支持 left/right/alternate/center 模式、vertical/horizontal 方向、pending 幽灵节点、reverse 倒序与实/虚线样式；交替布局由纯 CSS :nth-child 决定，两种用法共用同一套结构与样式。',
+  props: [
+    {
+      name: 'dataSource',
+      type: 'TimelineItemData[]',
+      default: '[]',
+      desc: '节点数据（数据驱动用法；优先于声明式 children）',
+    },
+    {
+      name: 'children',
+      type: 'Snippet',
+      default: 'undefined',
+      desc: '声明式用法：内嵌 <Timeline.Item> 列表，仅在未传 dataSource 时生效',
+    },
+    {
+      name: 'mode',
+      type: "'left'|'right'|'alternate'|'center'",
+      default: 'left',
+      desc: 'right 轴线在右、内容靠右对齐（left 镜像）；center 轴线居中、两侧内容朝轴对称对齐',
+    },
+    {
+      name: 'direction',
+      type: "'vertical'|'horizontal'",
+      default: 'vertical',
+      desc: '时间轴方向',
+    },
+    { name: 'reverse', type: 'boolean', default: 'false', desc: '倒序展示' },
+    {
+      name: 'pending',
+      type: 'boolean|string',
+      default: 'false',
+      desc: '末尾追加幽灵节点，string 作为其内容',
+    },
+    { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
+    { name: 'lineStyle', type: "'solid'|'dashed'", default: 'solid' },
+    {
+      name: 'virtualized',
+      type: 'boolean',
+      default: 'false',
+      desc: '虚拟化：长时间轴只渲染视口内项（复用 core fixedRange；仅 dataSource 模式生效，强制 vertical 列布局，轴线靠固定项高连续）',
+    },
+    {
+      name: 'itemHeight',
+      type: 'number',
+      default: '56',
+      desc: '虚拟化固定项高（px）',
+    },
+    {
+      name: 'maxHeight',
+      type: 'number|string',
+      default: '400',
+      desc: '虚拟化视口最大高（px 数字或 CSS 字符串）',
+    },
+    {
+      name: 'overscan',
+      type: 'number',
+      default: '3',
+      desc: '虚拟化上下缓冲项数',
+    },
+    {
+      name: 'interactive',
+      type: 'boolean',
+      default: 'false',
+      desc: 'roving tabindex 键盘漫游：项可聚焦，↑↓/←→ 移动焦点、Home/End 跳首尾、Enter/Space 触发项 onClick',
+    },
+    { name: 'class', type: 'string', default: "''" },
+  ],
+  subComponents: [
+    {
+      name: 'Timeline.Item',
+      desc: '声明式单项，渲染 dot/line/内容（children），与 dataSource 项视觉一致',
+      props: [
+        { name: 'dotColor', type: 'string', default: 'undefined', desc: '圆点颜色' },
+        { name: 'color', type: 'string', default: 'undefined', desc: '圆点颜色别名（与 dotColor 等价，dotColor 优先）' },
+        {
+          name: 'type',
+          type: "'default'|'ongoing'|'success'|'warning'|'error'",
+          default: 'undefined',
+          desc: '语义类型，给圆点附加 cd-timeline__dot--{type} class',
+        },
+        { name: 'dot', type: 'Snippet', default: 'undefined', desc: '自定义圆点 snippet，提供时替代默认圆点' },
+        {
+          name: 'lineStyle',
+          type: "'solid'|'dashed'",
+          default: '继承父 Timeline',
+          desc: '单项连接线样式',
+        },
+        { name: 'time', type: 'string', default: 'undefined', desc: '时间文本' },
+        {
+          name: 'position',
+          type: "'left'|'right'",
+          default: 'undefined',
+          desc: '覆盖父 Timeline mode 的单项定位',
+        },
+        {
+          name: 'extra',
+          type: 'string | Snippet',
+          default: 'undefined',
+          desc: '时间旁辅助内容',
+        },
+        {
+          name: 'onClick',
+          type: '() => void',
+          default: 'undefined',
+          desc: 'interactive 模式下点击或 Enter/Space 触发',
+        },
+        { name: 'children', type: 'Snippet', default: 'undefined', desc: '项内容' },
+      ],
+    },
+  ],
+  a11y: {
+    role: 'list',
+    notes: [
+      'ul/li 结构',
+      '圆点与连接线 aria-hidden=true',
+      '内容与时间为可读文本',
+      'interactive：项 role=button + roving tabindex（焦点项 tabindex=0 其余 -1），↑↓/←→ 移动焦点、Home/End 跳首尾、Enter/Space 激活，aria-label 取节点内容',
+    ],
+  },
+  tokens: ['--cd-timeline-*', '--cd-radius-full', '--cd-spacing-1', '--cd-font-size-1'],
+} as const;

package/src/timeline/types.ts

@@ -0,0 +1,9 @@
+export interface TimelineItemData {
+  key?: string;
+  content: string;
+  time?: string;
+  color?: string;
+  dotColor?: string;
+  /** interactive 模式下按 Enter/Space 或点击该节点触发（非 interactive 时忽略）。 */
+  onClick?: () => void;
+}

package/src/toast/Toast.a11y.test.ts

@@ -0,0 +1,67 @@
+// Toast a11y：命令式单例 API（Toast.info 等）经惰性挂载容器渲染。
+// Toast 的播报模型与多数库不同：卡片本身 role=presentation + aria-live=off（不充当 live
+// region），所有文案播报统一走单例 live region（live-region.ts），避免每卡各自 region 的
+// 重复/竞争。故拆两部分测：
+//  1) ToastItem 纯展示卡片：role=presentation + aria-live=off，关闭按钮 locale 可访问名，axe 0。
+//  2) live region：announce() 命令式写入 body 内 role=status（polite）/ role=alert（assertive）节点。
+// jsdom 只断言静态 ARIA + axe。
+import { describe, it, expect, afterEach } from 'vitest';
+import type { Component } from 'svelte';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import ToastItemRaw from './ToastItem.svelte';
+import { announce, __resetLiveRegion } from './live-region.js';
+import type { ToastItem as ToastItemData } from '@chenzy-design/core';
+
+// ToastItem 有必填 props（toast/onClose/...）；测试帮手用宽松 Record 构造器签名，
+// 故在此把组件转为宽松类型（props 实际值在调用处提供，运行时安全）。
+const ToastItem = ToastItemRaw as unknown as Component<Record<string, unknown>>;
+
+const noop = () => {};
+
+function makeToast(overrides: Partial<ToastItemData> = {}): ToastItemData {
+  return {
+    id: 't1',
+    content: 'Copied to clipboard',
+    type: 'success',
+    duration: 3,
+    position: 'top',
+    closable: true,
+    pauseOnHover: true,
+    theme: 'light',
+    onClose: undefined,
+    ...overrides,
+  };
+}
+
+describe('Toast a11y', () => {
+  afterEach(() => {
+    __resetLiveRegion();
+  });
+
+  it('ToastItem 卡片：role=presentation + aria-live=off + 关闭按钮 locale 可访问名，无 axe violations', async () => {
+    const { container } = renderWithLocale(ToastItem, {
+      props: { toast: makeToast(), onClose: noop, onPause: noop, onResume: noop },
+    });
+    const card = container.querySelector('.cd-toast-item');
+    expect(card?.getAttribute('role')).toBe('presentation');
+    expect(card?.getAttribute('aria-live')).toBe('off');
+    expect(container.querySelector('.cd-toast-item__close')?.getAttribute('aria-label')).toBeTruthy();
+    await expectNoAxeViolations(container);
+  });
+
+  it('live region：polite 文案写入 role=status / aria-live=polite 节点', async () => {
+    announce('Saved', 'success');
+    const polite = document.querySelector('.cd-toast-live-region[aria-live="polite"]');
+    expect(polite?.getAttribute('role')).toBe('status');
+    expect(polite?.textContent).toBe('Saved');
+    await expectNoAxeViolations(document.body);
+  });
+
+  it('live region：error 文案写入 role=alert / aria-live=assertive 节点', async () => {
+    announce('Failed', 'error');
+    const assertive = document.querySelector('.cd-toast-live-region[aria-live="assertive"]');
+    expect(assertive?.getAttribute('role')).toBe('alert');
+    expect(assertive?.textContent).toBe('Failed');
+    await expectNoAxeViolations(document.body);
+  });
+});

package/src/toast/ToastContainer.svelte

@@ -0,0 +1,184 @@
+<!--
+  ToastContainer — 单例容器，订阅 store 渲染全部 toast。
+  由 store.ts 惰性 mount 到 body 下的宿主节点；仅此一个实例。
+  按 6 方位（topLeft/top/topRight/bottomLeft/bottom/bottomRight）分组渲染独立堆叠列，
+  对齐 Notification 的方位实现。向后兼容：旧的纯 top/bottom 用法仍居中堆叠不变。
+  进出场用 svelte/transition fly（运行时驱动，退场后 DOM 正常卸载，不卡 from 帧）；
+  重排用 animate:flip。reduced-motion 时 fly duration 降为 0。
+  红线 #2：方位分组（grouped）/进出场偏移（flyParams）为派生纯函数。
+  红线：render 不读 effect 写的状态——toasts 初始同步读一次（拿到惰性挂载前已入队的首条），
+  $effect 仅做订阅 + cleanup 退订。
+-->
+<script lang="ts">
+  import { fly } from 'svelte/transition';
+  import { flip } from 'svelte/animate';
+  import { prefersReducedMotion } from 'svelte/motion';
+  import type { ToastStore, ToastItem, ToastPosition } from '@chenzy-design/core';
+  import ToastItemView from './ToastItem.svelte';
+  import { getToastConfig } from './store.js';
+
+  interface Props {
+    store: ToastStore;
+  }
+
+  let { store }: Props = $props();
+
+  // 初始同步读一次：捕获惰性挂载前已入队的首条 toast。
+  // 用函数包裹读取，避免 state 初始化器直接引用 prop 触发 state_referenced_locally。
+  // core 的 subscribe 不会立即回放当前值，因此必须在此先读一次。
+  function readInitial(): ToastItem[] {
+    return store.getToasts();
+  }
+  let toasts = $state<ToastItem[]>(readInitial());
+
+  // 桥接外部（非 Svelte runes）store：订阅写入本地 state，cleanup 退订。
+  // 这是 store->state 的单向桥，无法用 $derived 表达（外部 store 非响应式源）。
+  $effect(() => {
+    const unsub = store.subscribe((v) => {
+      toasts = v;
+    });
+    return unsub;
+  });
+
+  const positions: ToastPosition[] = [
+    'topLeft',
+    'top',
+    'topRight',
+    'bottomLeft',
+    'bottom',
+    'bottomRight',
+  ];
+
+  const flyDuration = $derived(prefersReducedMotion.current ? 0 : 220);
+  const flipDuration = $derived(prefersReducedMotion.current ? 0 : 200);
+
+  // 红线 #2：方位分组纯派生——按 6 方位过滤当前 toasts。
+  const grouped = $derived(
+    positions.map((p) => ({
+      position: p,
+      items: toasts.filter((t) => t.position === p),
+    })),
+  );
+
+  // 每方位进出场偏移：左侧从左滑入、右侧从右滑入、居中走垂直（对齐 Notification）。
+  function flyParams(position: ToastPosition): { x: number; y: number } {
+    if (position === 'topLeft' || position === 'bottomLeft') return { x: -24, y: 0 };
+    if (position === 'topRight' || position === 'bottomRight') return { x: 24, y: 0 };
+    return { x: 0, y: position === 'top' ? -16 : 16 };
+  }
+
+  function handleClose(id: string) {
+    store.remove(id, 'manual');
+  }
+  function handlePause(id: string) {
+    store.pause(id);
+  }
+  function handleResume(id: string) {
+    store.resume(id);
+  }
+
+  // 全局配置衍生样式变量（应用到容器的 CSS 自定义属性）。
+  function toPx(v: number | string | undefined): string | undefined {
+    if (v === undefined) return undefined;
+    return typeof v === 'number' ? `${v}px` : v;
+  }
+
+  const cfg = $derived(getToastConfig());
+  const configStyle = $derived(() => {
+    const parts: string[] = [];
+    if (cfg.zIndex !== undefined) parts.push(`--cd-toast-z: ${cfg.zIndex}`);
+    if (cfg.top !== undefined) parts.push(`--cd-toast-config-top: ${toPx(cfg.top)}`);
+    if (cfg.bottom !== undefined) parts.push(`--cd-toast-config-bottom: ${toPx(cfg.bottom)}`);
+    if (cfg.left !== undefined) parts.push(`--cd-toast-config-left: ${toPx(cfg.left)}`);
+    if (cfg.right !== undefined) parts.push(`--cd-toast-config-right: ${toPx(cfg.right)}`);
+    return parts.length > 0 ? parts.join('; ') : undefined;
+  });
+
+  // 任一 toast 带 stack 标志时，整组容器附加 stacked class。
+  const hasStack = $derived(toasts.some((t) => t.stack));
+</script>
+
+{#each grouped as group (group.position)}
+  {#if group.items.length > 0}
+    <div
+      class={['cd-toast-stack', `cd-toast-stack--${group.position}`, hasStack && 'cd-toast-wrapper--stacked']}
+      style={configStyle()}
+    >
+      {#each group.items as t (t.id)}
+        <div
+          class="cd-toast-stack__item"
+          in:fly={{ ...flyParams(group.position), duration: flyDuration }}
+          out:fly={{ ...flyParams(group.position), duration: flyDuration }}
+          animate:flip={{ duration: flipDuration }}
+        >
+          <ToastItemView
+            toast={t}
+            onClose={handleClose}
+            onPause={handlePause}
+            onResume={handleResume}
+          />
+        </div>
+      {/each}
+    </div>
+  {/if}
+{/each}
+
+<style>
+  .cd-toast-stack {
+    position: fixed;
+    z-index: var(--cd-toast-z);
+    display: flex;
+    flex-direction: column;
+    gap: var(--cd-toast-stack-gap);
+    inline-size: max-content;
+    max-inline-size: calc(100vw - 32px);
+    pointer-events: none;
+  }
+
+  .cd-toast-stack--topLeft {
+    top: 24px;
+    left: 24px;
+    align-items: flex-start;
+  }
+
+  .cd-toast-stack--top {
+    top: 24px;
+    left: 50%;
+    transform: translateX(-50%);
+    align-items: center;
+  }
+
+  .cd-toast-stack--topRight {
+    top: 24px;
+    right: 24px;
+    align-items: flex-end;
+  }
+
+  .cd-toast-stack--bottomLeft {
+    bottom: 24px;
+    left: 24px;
+    align-items: flex-start;
+    flex-direction: column-reverse;
+  }
+
+  .cd-toast-stack--bottom {
+    bottom: 24px;
+    left: 50%;
+    transform: translateX(-50%);
+    align-items: center;
+    flex-direction: column-reverse;
+  }
+
+  .cd-toast-stack--bottomRight {
+    bottom: 24px;
+    right: 24px;
+    align-items: flex-end;
+    flex-direction: column-reverse;
+  }
+
+  .cd-toast-stack__item {
+    inline-size: auto;
+    max-inline-size: 100%;
+    pointer-events: none;
+  }
+</style>