@chenzy-design/svelte 0.1.0

package/src/modal/meta.ts

@@ -0,0 +1,165 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * Modal — see specs/components/feedback/Modal.spec.md
+ */
+export const meta = {
+  name: 'Modal',
+  category: 'feedback',
+  description:
+    '模态对话框：fixed 遮罩 + 面板，portal 到 body（或 getContainer）脱离父层叠上下文，role=dialog aria-modal；useFocusTrap 焦点捕获与归还、Esc/遮罩点击关闭（受 keyboard/maskClosable 控制）、useScrollLock 锁背景滚动；头/体/尾结构，ok/cancel 默认按钮可换自定义尾部，danger okType；reduced-motion 关闭过渡。受控 open 不回写，仅 onOpenChange/onCancel 通知。destroyOnClose 关闭即卸载内容、重开重建（默认 false 保留 DOM）。draggable 按住标题栏拖动面板（偏移派生 transform 叠加定位，重开重置，pointer 事件绑 window）。堆叠 z-index 由模块级计数器分配（声明式与命令式共享，后开者在上、关闭回收）。命令式工厂 Modal.confirm/info/success/warning/error（亦可解构 modal）：mount 到 body 临时 host、async onOk 自动 loading、返回 { destroy, update }。',
+  exports: ['Modal', 'modal'],
+  props: [
+    { name: 'open', type: 'boolean', default: 'undefined', desc: '受控显隐；受控时不回写' },
+    { name: 'title', type: 'string', default: 'undefined', desc: '标题文案' },
+    {
+      name: 'titleSnippet',
+      type: 'Snippet',
+      default: 'undefined',
+      desc: '自定义标题，覆盖 title',
+    },
+    { name: 'width', type: 'number|string', default: '448', desc: '面板宽度' },
+    { name: 'centered', type: 'boolean', default: 'false', desc: '垂直居中（否则距顶）' },
+    { name: 'closable', type: 'boolean', default: 'true', desc: '右上角关闭按钮' },
+    { name: 'maskClosable', type: 'boolean', default: 'true', desc: '点遮罩关闭' },
+    { name: 'keyboard', type: 'boolean', default: 'true', desc: 'Esc 关闭' },
+    {
+      name: 'draggable',
+      type: 'boolean',
+      default: 'false',
+      desc: '按住标题栏拖动面板（偏移叠加在定位上，重开重置）；鼠标增强不影响键盘/焦点',
+    },
+    {
+      name: 'confirmLoading',
+      type: 'boolean',
+      default: 'false',
+      desc: '确认按钮 loading 态',
+    },
+    { name: 'okText', type: 'string', default: "'确定'" },
+    { name: 'cancelText', type: 'string', default: "'取消'" },
+    { name: 'okType', type: "'primary'|'danger'", default: "'primary'", desc: '确认按钮类型' },
+    {
+      name: 'destroyOnClose',
+      type: 'boolean',
+      default: 'false',
+      desc: '关闭即卸载内部内容（{#if} 卸载），重开重建；默认保留 DOM 仅隐藏',
+    },
+    {
+      name: 'getContainer',
+      type: '() => HTMLElement | null',
+      default: 'undefined',
+      desc: 'Portal 容器，缺省 document.body',
+    },
+    {
+      name: 'footer',
+      type: 'Snippet<[{ ok; cancel }]>|null',
+      default: 'undefined',
+      desc: 'null 隐藏默认按钮；snippet 自定义尾部',
+    },
+    { name: 'children', type: 'Snippet', default: 'undefined', desc: '内容主体' },
+    { name: 'ariaLabel', type: 'string', default: 'undefined', desc: '无 title 时的 aria-label' },
+    { name: 'onOk', type: '() => void', default: 'undefined' },
+    { name: 'onCancel', type: '() => void', default: 'undefined' },
+    { name: 'onOpenChange', type: '(open: boolean) => void', default: 'undefined' },
+    { name: 'onAfterClose', type: '() => void', default: 'undefined', desc: '关闭过渡结束触发' },
+    {
+      name: 'okButtonProps',
+      type: 'Record<string, unknown>',
+      default: 'undefined',
+      desc: '透传给确定按钮的额外 props（如 disabled、size 等）',
+    },
+    {
+      name: 'cancelButtonProps',
+      type: 'Record<string, unknown>',
+      default: 'undefined',
+      desc: '透传给取消按钮的额外 props',
+    },
+    { name: 'hasCancel', type: 'boolean', default: 'true', desc: '是否显示取消按钮' },
+    {
+      name: 'size',
+      type: "'small'|'medium'|'large'|'full-width'",
+      default: 'undefined',
+      desc: '预设宽度枚举（small=480px, medium=600px, large=800px, full-width=100vw），优先级低于 width',
+    },
+    { name: 'fullScreen', type: 'boolean', default: 'false', desc: '全屏模式' },
+    {
+      name: 'keepDOM',
+      type: 'boolean',
+      default: 'false',
+      desc: '关闭时保留 DOM（display:none 隐藏），与 destroyOnClose 反义',
+    },
+    {
+      name: 'lazyRender',
+      type: 'boolean',
+      default: 'true',
+      desc: '配合 keepDOM 的懒挂载：true 时首次打开前不渲染内容',
+    },
+    { name: 'bodyStyle', type: 'string', default: 'undefined', desc: '内容区内联 style 字符串' },
+    { name: 'maskStyle', type: 'string', default: 'undefined', desc: '遮罩层内联 style 字符串' },
+    { name: 'height', type: 'number|string', default: 'undefined', desc: 'Modal 高度' },
+    { name: 'footerFill', type: 'boolean', default: 'false', desc: '底部按钮撑满宽度' },
+    {
+      name: 'modalContentClass',
+      type: 'string',
+      default: 'undefined',
+      desc: '内容区域额外 class',
+    },
+    { name: 'closeIcon', type: 'Snippet', default: 'undefined', desc: '自定义关闭图标' },
+    { name: 'mask', type: 'boolean', default: 'true', desc: '是否显示遮罩' },
+  ],
+  events: [
+    { name: 'onOk', desc: '确认按钮点击（非受控自动关闭）' },
+    { name: 'onCancel', desc: '取消/关闭按钮/遮罩/Esc 关闭' },
+    { name: 'onOpenChange', desc: '显隐变化通知' },
+    { name: 'onAfterClose', desc: '关闭过渡结束' },
+  ],
+  slots: [
+    { name: 'children', desc: '内容主体' },
+    { name: 'titleSnippet', desc: '自定义标题' },
+    { name: 'footer', desc: '自定义尾部（接收 { ok, cancel }）' },
+    { name: 'closeIcon', desc: '自定义关闭图标' },
+  ],
+  a11y: {
+    hasRole: true,
+    focusable: true,
+    note: 'role=dialog + aria-modal=true；有 title 用 aria-labelledby，无则 aria-label；useFocusTrap 捕获 Tab 焦点并在关闭时归还触发元素；Esc 关闭受 keyboard 控制；useScrollLock 锁背景滚动；关闭按钮 aria-label「关闭」。',
+  },
+  tokens: [
+    '--cd-modal-radius',
+    '--cd-modal-bg',
+    '--cd-modal-shadow',
+    '--cd-modal-mask-bg',
+    '--cd-modal-padding',
+    '--cd-modal-header-gap',
+    '--cd-modal-footer-gap',
+    '--cd-modal-title-color',
+    '--cd-modal-title-size',
+    '--cd-modal-body-color',
+    '--cd-modal-close-color',
+    '--cd-modal-close-hover-bg',
+    '--cd-modal-z',
+    '--cd-modal-motion-duration',
+  ],
+  responsive: false,
+  examples: [
+    {
+      title: '基础确认框',
+      code: '<Modal open={visible} title="提示" onOk={() => (visible = false)} onCancel={() => (visible = false)}>确认操作？</Modal>',
+    },
+    {
+      title: '自定义尾部',
+      code: '<Modal open={visible} title="标题">\n  内容\n  {#snippet footer({ cancel })}<Button onclick={cancel}>知道了</Button>{/snippet}\n</Modal>',
+    },
+    {
+      title: 'danger 确认',
+      code: '<Modal open={visible} title="删除" okType="danger" okText="删除" onOk={remove}>不可恢复，确定删除？</Modal>',
+    },
+    {
+      title: '命令式确认（异步 onOk 自动 loading）',
+      code: "Modal.confirm({ title: '确认操作', content: '确定执行？', onOk: () => fetch('/api/do') });",
+    },
+    {
+      title: 'destroyOnClose 重开重建',
+      code: '<Modal open={visible} title="表单" destroyOnClose>...每次重开重置内部状态...</Modal>',
+    },
+  ],
+} as const;

package/src/modal/z-stack.ts

@@ -0,0 +1,26 @@
+/**
+ * 模块级 z-index 堆叠管理：多个 Modal（声明式 <Modal> + 命令式 modal.confirm）
+ * 共享同一计数器，后开者在上；关闭时回收，避免无限增长。
+ * 用递增整数（不用 Math.random/Date.now，红线 #3）。
+ */
+
+// 与 --cd-modal-z token 基线一致；每开一个 +10，给遮罩/面板留间隙。
+const Z_BASE = 1000;
+const STEP = 10;
+
+let counter = 0;
+
+/** 申请一个堆叠层级，返回 z-index 与回收函数。回收幂等。 */
+export function acquireZIndex(): { zIndex: number; release: () => void } {
+  counter += 1;
+  const zIndex = Z_BASE + counter * STEP;
+  let released = false;
+  return {
+    zIndex,
+    release() {
+      if (released) return;
+      released = true;
+      counter = Math.max(0, counter - 1);
+    },
+  };
+}

package/src/notification/NotificationContainer.svelte

@@ -0,0 +1,192 @@
+<!--
+  NotificationContainer — 单例容器，订阅 store 渲染全部通知。
+  由 store.ts 惰性 mount 到 body（或 getPopupContainer）下的宿主节点；仅此一个实例。
+  按 6 placement（topLeft/top/topRight/bottomLeft/bottom/bottomRight）分组渲染独立堆叠列。
+  RTL：item.direction==='rtl' 时左右方位互换（topRight→topLeft 视觉镜像），堆叠列写 dir=rtl
+  令卡片整体镜像（关闭按钮、图标、文案方向、内边距均经逻辑属性自动翻转）；进出场水平偏移随之取反。
+  Esc 关闭（红线 #3）：$effect 命令式挂 window keydown，按 Esc 关闭最近一条通知；cleanup 移除监听。
+  进出场用 svelte/transition fly（运行时驱动，退场后 DOM 正常卸载，不卡 from 帧）；
+  重排用 animate:flip。reduced-motion 时 fly duration 降为 0。
+  红线：render 不读 effect 写的状态——items 初始同步读一次（拿到惰性挂载前已入队的首条），
+  $effect 仅做订阅 + cleanup 退订 / keydown 监听 + cleanup。
+-->
+<script lang="ts">
+  import { fly } from 'svelte/transition';
+  import { flip } from 'svelte/animate';
+  import { prefersReducedMotion } from 'svelte/motion';
+  import type {
+    NotificationStore,
+    NotificationItem,
+    NotificationPlacement,
+  } from '@chenzy-design/core';
+  import NotificationItemView from './NotificationItem.svelte';
+  import { onCloseClickMap } from './store.js';
+
+  interface Props {
+    store: NotificationStore;
+  }
+
+  let { store }: Props = $props();
+
+  // 初始同步读一次：捕获惰性挂载前已入队的首条通知。
+  // 用函数包裹读取，避免 state 初始化器直接引用 prop 触发 state_referenced_locally。
+  // core 的 subscribe 不会立即回放当前值，因此必须在此先读一次。
+  function readInitial(): NotificationItem[] {
+    return store.getItems();
+  }
+  let items = $state<NotificationItem[]>(readInitial());
+
+  // 桥接外部（非 Svelte runes）store：订阅写入本地 state，cleanup 退订。
+  // 这是 store->state 的单向桥，无法用 $derived 表达（外部 store 非响应式源）。
+  $effect(() => {
+    const unsub = store.subscribe((v) => {
+      items = v;
+    });
+    return unsub;
+  });
+
+  // Esc 关闭（红线 #3）：命令式挂 window keydown，关闭最近一条（最后入队）通知；cleanup 移除。
+  // 直接读 store.getItems()（快照），不读 effect 写的 items state，避免 effect 自依赖重订阅。
+  $effect(() => {
+    function onKeydown(e: KeyboardEvent): void {
+      if (e.key !== 'Escape') return;
+      const current = store.getItems();
+      const last = current[current.length - 1];
+      if (last) store.close(last.id, 'manual');
+    }
+    window.addEventListener('keydown', onKeydown);
+    return () => window.removeEventListener('keydown', onKeydown);
+  });
+
+  const placements: NotificationPlacement[] = [
+    'topLeft',
+    'top',
+    'topRight',
+    'bottomLeft',
+    'bottom',
+    'bottomRight',
+  ];
+
+  // RTL 方位镜像：rtl 通知的左右方位视觉互换（topRight→topLeft 等），居中不变。
+  const RTL_SWAP: Record<NotificationPlacement, NotificationPlacement> = {
+    topLeft: 'topRight',
+    topRight: 'topLeft',
+    bottomLeft: 'bottomRight',
+    bottomRight: 'bottomLeft',
+    top: 'top',
+    bottom: 'bottom',
+  };
+  function effectivePlacement(item: NotificationItem): NotificationPlacement {
+    return item.direction === 'rtl' ? RTL_SWAP[item.placement] : item.placement;
+  }
+
+  const flyDuration = $derived(prefersReducedMotion.current ? 0 : 220);
+  const flipDuration = $derived(prefersReducedMotion.current ? 0 : 200);
+
+  const grouped = $derived(
+    placements.map((p) => ({
+      placement: p,
+      items: items.filter((i) => effectivePlacement(i) === p),
+    })),
+  );
+
+  // 每个方位的进出场水平/垂直偏移：左侧从左滑入、右侧从右滑入、居中走垂直。
+  function flyParams(placement: NotificationPlacement): { x: number; y: number } {
+    if (placement === 'topLeft' || placement === 'bottomLeft') return { x: -24, y: 0 };
+    if (placement === 'topRight' || placement === 'bottomRight') return { x: 24, y: 0 };
+    return { x: 0, y: placement === 'top' ? -16 : 16 };
+  }
+
+  function handleClose(id: string) {
+    store.close(id, 'manual');
+  }
+
+  function handleCloseClick(id: string) {
+    onCloseClickMap.get(id)?.(id);
+    store.close(id, 'manual');
+  }
+  function handlePause(id: string) {
+    store.pause(id);
+  }
+  function handleResume(id: string) {
+    store.resume(id);
+  }
+</script>
+
+{#each grouped as group (group.placement)}
+  {#if group.items.length > 0}
+    <div class="cd-notification-stack cd-notification-stack--{group.placement}">
+      {#each group.items as item (item.id)}
+        <div
+          class="cd-notification-stack__item"
+          dir={item.direction}
+          in:fly={{ ...flyParams(group.placement), duration: flyDuration }}
+          out:fly={{ ...flyParams(group.placement), duration: flyDuration }}
+          animate:flip={{ duration: flipDuration }}
+        >
+          <NotificationItemView
+            {item}
+            onClose={handleClose}
+            onCloseClick={handleCloseClick}
+            onPause={handlePause}
+            onResume={handleResume}
+          />
+        </div>
+      {/each}
+    </div>
+  {/if}
+{/each}
+
+<style>
+  .cd-notification-stack {
+    position: fixed;
+    z-index: var(--cd-notification-z);
+    display: flex;
+    flex-direction: column;
+    gap: var(--cd-notification-gap);
+    inline-size: max-content;
+    max-inline-size: calc(100vw - 2 * var(--cd-notification-offset));
+    pointer-events: none;
+  }
+
+  .cd-notification-stack--topLeft {
+    top: var(--cd-notification-offset);
+    left: var(--cd-notification-offset);
+  }
+
+  .cd-notification-stack--top {
+    top: var(--cd-notification-offset);
+    left: 50%;
+    transform: translateX(-50%);
+  }
+
+  .cd-notification-stack--topRight {
+    top: var(--cd-notification-offset);
+    right: var(--cd-notification-offset);
+  }
+
+  .cd-notification-stack--bottomLeft {
+    bottom: var(--cd-notification-offset);
+    left: var(--cd-notification-offset);
+    flex-direction: column-reverse;
+  }
+
+  .cd-notification-stack--bottom {
+    bottom: var(--cd-notification-offset);
+    left: 50%;
+    transform: translateX(-50%);
+    flex-direction: column-reverse;
+  }
+
+  .cd-notification-stack--bottomRight {
+    bottom: var(--cd-notification-offset);
+    right: var(--cd-notification-offset);
+    flex-direction: column-reverse;
+  }
+
+  .cd-notification-stack__item {
+    inline-size: auto;
+    max-inline-size: 100%;
+    pointer-events: none;
+  }
+</style>

package/src/notification/NotificationItem.a11y.test.ts

@@ -0,0 +1,73 @@
+// Notification a11y：命令式单例 API（notification.open）经惰性挂载容器渲染。
+// 这里直接渲染纯展示的 NotificationItem（接收一个完整 item），断言静态 ARIA：
+//  - error/warning → role=alert + aria-live=assertive；其余 → role=status + aria-live=polite。
+//  - title/content 经 useId 关联 aria-labelledby / aria-describedby。
+//  - 视觉隐藏类型前缀（如「Error:」）令屏幕阅读器先播报极性语义。
+// jsdom 只断言静态 ARIA + axe（定时器 / hover 暂停留给真实浏览器）。
+import { describe, it, expect } from 'vitest';
+import type { Component } from 'svelte';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import NotificationItemRaw from './NotificationItem.svelte';
+import type { NotificationItem as NotificationItemData } from '@chenzy-design/core';
+
+// NotificationItem 有必填 props（item/onClose/...）；测试帮手用宽松 Record 构造器签名，
+// 故在此把组件转为宽松类型（props 实际值在调用处提供，运行时安全）。
+const NotificationItem = NotificationItemRaw as unknown as Component<Record<string, unknown>>;
+
+const noop = () => {};
+
+function makeItem(overrides: Partial<NotificationItemData> = {}): NotificationItemData {
+  return {
+    id: 'n1',
+    title: 'Saved',
+    content: 'Your changes were saved.',
+    type: 'success',
+    duration: 4.5,
+    placement: 'topRight',
+    closable: true,
+    pauseOnHover: true,
+    showProgress: false,
+    theme: 'light',
+    direction: 'ltr',
+    footer: undefined,
+    onClose: undefined,
+    ...overrides,
+  };
+}
+
+describe('Notification a11y', () => {
+  it('success：role=status + aria-live=polite + aria-labelledby/describedby，无 axe violations', async () => {
+    const { container } = renderWithLocale(NotificationItem, {
+      props: { item: makeItem(), onClose: noop, onPause: noop, onResume: noop },
+    });
+    const card = container.querySelector('.cd-notification-item');
+    expect(card?.getAttribute('role')).toBe('status');
+    expect(card?.getAttribute('aria-live')).toBe('polite');
+    const labelledby = card?.getAttribute('aria-labelledby');
+    const describedby = card?.getAttribute('aria-describedby');
+    expect(labelledby ? container.querySelector(`#${labelledby}`)?.textContent : '').toContain('Saved');
+    expect(
+      describedby ? container.querySelector(`#${describedby}`)?.textContent : '',
+    ).toContain('changes');
+    // 关闭按钮可访问名来自 locale。
+    expect(container.querySelector('.cd-notification-item__close')?.getAttribute('aria-label')).toBeTruthy();
+    await expectNoAxeViolations(container);
+  });
+
+  it('error：role=alert + aria-live=assertive + 视觉隐藏类型前缀，无 axe violations', async () => {
+    const { container } = renderWithLocale(NotificationItem, {
+      props: {
+        item: makeItem({ type: 'error', title: 'Upload failed', content: 'Try again.' }),
+        onClose: noop,
+        onPause: noop,
+        onResume: noop,
+      },
+    });
+    const card = container.querySelector('.cd-notification-item');
+    expect(card?.getAttribute('role')).toBe('alert');
+    expect(card?.getAttribute('aria-live')).toBe('assertive');
+    // 类型前缀（如「Error:」）以视觉隐藏文本注入，非空。
+    expect(container.querySelector('.cd-sr-only')?.textContent?.trim()).toBeTruthy();
+    await expectNoAxeViolations(container);
+  });
+});