@chenzy-design/svelte 0.1.0

package/src/slider/SliderKbdFixture.svelte

@@ -0,0 +1,21 @@
+<!--
+  仅供 Slider.kbd.test.ts（browser project）使用的键盘 e2e 夹具。
+  渲染单值 Slider 与 range Slider 两块：
+   - 单值：一个 role=slider 手柄，方向键 / Home / End 真实调值（aria-valuenow）。
+   - range：两个 role=slider 手柄，各自可聚焦、各自调值。
+  before 按钮用于验证 Tab 真实聚焦到手柄。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import Slider from './Slider.svelte';
+</script>
+
+<LocaleProvider locale="en_US">
+  <button type="button" data-testid="before">before</button>
+  <div data-testid="single">
+    <Slider defaultValue={50} min={0} max={100} step={1} ariaLabel="Volume" />
+  </div>
+  <div data-testid="range">
+    <Slider range defaultValue={[20, 60]} min={0} max={100} step={1} ariaLabel="Range" />
+  </div>
+</LocaleProvider>

package/src/slider/index.ts

@@ -0,0 +1,2 @@
+export { default as Slider } from './Slider.svelte';
+export { meta as sliderMeta } from './meta.js';

package/src/slider/meta.ts

@@ -0,0 +1,55 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md.
+ */
+export const meta = {
+  name: 'Slider',
+  category: 'input',
+  description: '在连续/离散区间内选值的滑块，支持单值与 range、刻度、垂直方向与全键盘操作。',
+  props: [
+    { name: 'value', type: 'number | [number, number]', default: 'undefined', desc: '受控值；range 时为二元组' },
+    { name: 'defaultValue', type: 'number | [number, number]', default: 'min / [min,min]', desc: '非受控初始值' },
+    { name: 'min', type: 'number', default: '0' },
+    { name: 'max', type: 'number', default: '100' },
+    { name: 'step', type: 'number | null', default: '1', desc: 'null 时仅停靠 marks 键' },
+    { name: 'range', type: 'boolean', default: 'false', desc: '双滑块区间模式' },
+    { name: 'marks', type: 'Record<number, string>', default: 'undefined', desc: '刻度标记' },
+    { name: 'dots', type: 'boolean', default: 'false', desc: '在每个 step 处显示圆点（段内激活色）' },
+    { name: 'included', type: 'boolean', default: 'true', desc: '是否填充已选轨道段' },
+    { name: 'vertical', type: 'boolean', default: 'false' },
+    { name: 'verticalReverse', type: 'boolean', default: 'false', desc: '垂直时反向（顶部为 min）' },
+    { name: 'height', type: 'number', default: '200', desc: '垂直模式高度（px）' },
+    { name: 'disabled', type: 'boolean', default: 'false' },
+    { name: 'clickable', type: 'boolean', default: 'true', desc: '是否允许点击轨道跳转到最近合法值' },
+    { name: 'size', type: "'small'|'default'|'large'", default: 'default' },
+    { name: 'status', type: "'default'|'warning'|'error'", default: 'default', desc: '校验态，影响已选轨道与手柄边框色' },
+    { name: 'tooltipVisible', type: 'boolean | undefined', default: 'undefined', desc: '强制控制数值气泡显隐（受控）' },
+    { name: 'alwaysShowTip', type: 'boolean', default: 'false', desc: '始终显示数值气泡' },
+    { name: 'tipFormatter', type: '(value: number) => string | null', default: 'String', desc: '自定义气泡文案；返回 null 隐藏' },
+    { name: 'getAriaValueText', type: '(value: number, index: number) => string', default: 'undefined', desc: '自定义 aria-valuetext（如带单位）' },
+    { name: 'railStyle', type: 'string', default: 'undefined', desc: '透传轨道内联样式' },
+    { name: 'handleStyle', type: 'string', default: 'undefined', desc: '透传手柄内联样式' },
+    { name: 'id', type: 'string', default: 'undefined', desc: '根节点 id，关联表单 label' },
+    { name: 'ariaLabel', type: 'string', default: 'undefined' },
+    { name: 'ariaLabelledby', type: 'string', default: 'undefined', desc: 'group 与各手柄 aria-labelledby（指向外部 label id）' },
+    { name: 'onChange', type: '(v: number | [number, number]) => void', default: 'undefined', desc: '值变化（拖拽落定/键盘/点击）' },
+    { name: 'onChangeComplete', type: '(v: number | [number, number]) => void', default: 'undefined', desc: '拖拽结束或键盘落定时触发，适合请求节流' },
+    { name: 'onInput', type: '(v: number | [number, number]) => void', default: 'undefined', desc: '与 change 同步的低级输入信号（拖动中实时触发）' },
+    { name: 'onFocus', type: '(detail: { index: number }) => void', default: 'undefined', desc: '手柄获得焦点，附带手柄索引' },
+    { name: 'onBlur', type: '(detail: { index: number }) => void', default: 'undefined', desc: '手柄失焦，附带手柄索引' },
+  ],
+  a11y: {
+    role: 'slider',
+    keyboard: ['ArrowUp/Right', 'ArrowDown/Left', 'PageUp', 'PageDown', 'Home', 'End'],
+    notes: [
+      '根容器 role=group，每个手柄 role=slider + tabindex=0',
+      '手柄 aria-valuemin/valuemax/valuenow/aria-orientation',
+      'range 模式两手柄不交叉（越过自动交换）',
+      '拖拽命令式：pointerdown 读一次 rail rect，document 监听 pointermove/up',
+      'disabled→aria-disabled，手柄 tabindex=-1',
+      'aria-valuetext 优先 getAriaValueText，其次 tipFormatter 输出（带单位可读文案）',
+      '数值气泡：hover/focus/拖拽显示，alwaysShowTip 常驻，tooltipVisible 强制受控',
+    ],
+  },
+  tokens: ['--cd-slider-*', '--cd-color-text-3', '--cd-spacing-*', '--cd-radius-full', '--cd-shadow-1', '--cd-focus-ring', '--cd-motion-*'],
+} as const;

package/src/space/Space.a11y.test.ts

@@ -0,0 +1,22 @@
+// Space a11y：间距 flex 容器。纯布局容器，不引入语义角色。
+// 仅断言 axe 0 violations（透明保留子元素语义）。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import SpaceFixture from './SpaceA11yFixture.svelte';
+
+describe('Space a11y', () => {
+  it('horizontal：纯布局无语义角色，子元素语义透明保留，无 axe violations', async () => {
+    const { container } = renderWithLocale(SpaceFixture, {});
+    expect(container.querySelector('.cd-space')).not.toBeNull();
+    expect(container.querySelectorAll('button').length).toBe(2);
+    await expectNoAxeViolations(container);
+  });
+
+  it('vertical：方向切换不引入语义变化，无 axe violations', async () => {
+    const { container } = renderWithLocale(SpaceFixture, {
+      props: { direction: 'vertical' },
+    });
+    expect(container.querySelector('.cd-space--vertical')).not.toBeNull();
+    await expectNoAxeViolations(container);
+  });
+});

package/src/space/Space.svelte

@@ -0,0 +1,109 @@
+<!--
+  Space — see specs/components/basic/Space.spec.md
+  Flex spacing container. Token-driven gap.
+  NOTE: `split` slot (separator between items) is intentionally omitted in this
+  iteration; to be added later alongside per-item iteration support.
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  type SpaceDirection = 'horizontal' | 'vertical';
+  type SpaceSpacing = 'tight' | 'medium' | 'loose' | number | [number, number];
+  type SpaceAlign = 'start' | 'end' | 'center' | 'baseline';
+
+  interface Props {
+    direction?: SpaceDirection;
+    spacing?: SpaceSpacing;
+    align?: SpaceAlign;
+    wrap?: boolean;
+    block?: boolean;
+    class?: string;
+    children?: Snippet;
+  }
+
+  let {
+    direction = 'horizontal',
+    spacing = 'medium',
+    align,
+    wrap = false,
+    block = false,
+    class: className = '',
+    children,
+  }: Props = $props();
+
+  const presetGap: Record<string, string> = {
+    tight: 'var(--cd-space-tight)',
+    medium: 'var(--cd-space-medium)',
+    loose: 'var(--cd-space-loose)',
+  };
+
+  const gapCss = $derived.by(() => {
+    if (Array.isArray(spacing)) {
+      const [row, col] = spacing;
+      return `${row}px ${col}px`;
+    }
+    if (typeof spacing === 'number') {
+      return `${spacing}px`;
+    }
+    return presetGap[spacing];
+  });
+
+  const alignItems = $derived.by(() => {
+    if (!align) return undefined;
+    if (align === 'start') return 'flex-start';
+    if (align === 'end') return 'flex-end';
+    return align;
+  });
+
+  const isPreset = $derived(typeof spacing === 'string');
+
+  const cls = $derived(
+    [
+      'cd-space',
+      `cd-space--${direction}`,
+      isPreset && `cd-space--gap-${spacing}`,
+      wrap && 'cd-space--wrap',
+      block && 'cd-space--block',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  const inlineStyle = $derived(
+    [!isPreset && `gap:${gapCss}`, alignItems && `align-items:${alignItems}`]
+      .filter(Boolean)
+      .join(';'),
+  );
+</script>
+
+<div class={cls} style={inlineStyle || undefined}>
+  {@render children?.()}
+</div>
+
+<style>
+  .cd-space {
+    display: inline-flex;
+  }
+  .cd-space--block {
+    display: flex;
+  }
+  .cd-space--horizontal {
+    flex-direction: row;
+  }
+  .cd-space--vertical {
+    flex-direction: column;
+  }
+  .cd-space--wrap {
+    flex-wrap: wrap;
+  }
+  .cd-space--gap-tight {
+    gap: var(--cd-space-tight);
+  }
+  .cd-space--gap-medium {
+    gap: var(--cd-space-medium);
+  }
+  .cd-space--gap-loose {
+    gap: var(--cd-space-loose);
+  }
+</style>

package/src/space/SpaceA11yFixture.svelte

@@ -0,0 +1,17 @@
+<!--
+  仅供 Space.a11y.test.ts 使用的测试夹具：Space 间距容器包裹若干子元素。
+  纯布局容器，不引入语义；本套件只断言 axe 0 violations。
+-->
+<script lang="ts">
+  import Space from './Space.svelte';
+
+  interface Props {
+    direction?: 'horizontal' | 'vertical';
+  }
+  let { direction = 'horizontal' }: Props = $props();
+</script>
+
+<Space {direction}>
+  <button type="button">First</button>
+  <button type="button">Second</button>
+</Space>

package/src/space/index.ts

@@ -0,0 +1,2 @@
+export { default as Space } from './Space.svelte';
+export { meta as spaceMeta } from './meta.js';

package/src/space/meta.ts

@@ -0,0 +1,27 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/components/basic/Space.spec.md.
+ */
+export const meta = {
+  name: 'Space',
+  category: 'basic',
+  description: '为子元素提供统一间距的 flex 容器。',
+  props: [
+    { name: 'direction', type: "'horizontal'|'vertical'", default: "'horizontal'" },
+    {
+      name: 'spacing',
+      type: "'tight'|'medium'|'loose'|number|[number,number]",
+      default: "'medium'",
+      desc: '档位映射 token，number→px，数组→[行,列] gap',
+    },
+    { name: 'align', type: "'start'|'end'|'center'|'baseline'", default: 'undefined' },
+    { name: 'wrap', type: 'boolean', default: 'false' },
+    { name: 'block', type: 'boolean', default: 'false', desc: 'true→display:flex 占满宽度' },
+    { name: 'class', type: 'string', default: "''" },
+  ],
+  events: [],
+  slots: [{ name: 'children', desc: '需要间距的子元素' }],
+  a11y: { role: 'none', note: '纯布局容器，不引入语义' },
+  tokens: ['--cd-space-tight', '--cd-space-medium', '--cd-space-loose'],
+  examples: [{ title: '横向', code: '<Space><Button>A</Button><Button>B</Button></Space>' }],
+} as const;

package/src/spin/Spin.a11y.test.ts

@@ -0,0 +1,29 @@
+// Spin a11y：role=status + aria-live=polite 公布加载。
+// 经 SpinA11yFixture（不注入 children，使 inline 形态生效；harness 会恒注入空 children → wrapper）。
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/svelte';
+import { expectNoAxeViolations } from '../test-utils/a11y.js';
+import SpinA11yFixture from './SpinA11yFixture.svelte';
+
+describe('Spin a11y', () => {
+  it('inline：role=status + aria-live + aria-label（来自 locale），无 axe violations', async () => {
+    const { container } = render(SpinA11yFixture, {
+      props: { props: { spinning: true } },
+    });
+    const root = container.querySelector('.cd-spin');
+    expect(root?.getAttribute('role')).toBe('status');
+    expect(root?.getAttribute('aria-live')).toBe('polite');
+    // 无 tip 时取 locale 的 Spin.loading 作为可访问名。
+    expect(root?.getAttribute('aria-label')).toBeTruthy();
+    await expectNoAxeViolations(container);
+  });
+
+  it('inline + tip：tip 文本作为可访问名，无 axe violations', async () => {
+    const { container } = render(SpinA11yFixture, {
+      props: { props: { spinning: true, tip: 'Loading data' } },
+    });
+    const tip = container.querySelector('.cd-spin__tip');
+    expect(tip?.textContent).toContain('Loading data');
+    await expectNoAxeViolations(container);
+  });
+});

package/src/spin/Spin.svelte

@@ -0,0 +1,293 @@
+<!--
+  Spin — see specs/components/feedback/Spin.spec.md
+  加载指示器：inline / wrapper / fullscreen 三形态。
+  delay 去抖 + minShowTime 最短显示 由 @chenzy-design/core createSpinController 提供（必须复用，不重复实现）。
+  红线 #1：spinning 是受控输入，effective 是内部派生显示态，绝不回写 spinning，仅触发 onShow/onHide。
+  红线 #3：定时器/订阅全部在 $effect 命令式管理 + cleanup，无 DOM 几何测量。
+  role=status (aria-live=polite) 公布加载；wrapper 内容 aria-busy；reduced-motion 退化为呼吸。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { createSpinController, type SpinController } from '@chenzy-design/core';
+  import { useLocale } from '../locale-provider/index.js';
+
+  type Size = 'small' | 'default' | 'large';
+
+  interface Props {
+    spinning?: boolean;
+    size?: Size;
+    tip?: string;
+    delay?: number;
+    minShowTime?: number;
+    fullscreen?: boolean;
+    wrapperClassName?: string;
+    ariaLabel?: string;
+    indicator?: Snippet<[{ size: Size }]>;
+    children?: Snippet;
+    onShow?: () => void;
+    onHide?: () => void;
+  }
+
+  let {
+    spinning = true,
+    size = 'default',
+    tip = '',
+    delay = 0,
+    minShowTime = 0,
+    fullscreen = false,
+    wrapperClassName = '',
+    ariaLabel,
+    indicator,
+    children,
+    onShow,
+    onHide,
+  }: Props = $props();
+
+  const loc = useLocale();
+
+  // effective：内部派生显示态，render 读它决定显隐（红线 #1）。
+  let effective = $state(false);
+  // controller 在 client $effect 命令式创建（SSR 安全），不在 render 路径触碰定时器。
+  let ctrl: SpinController | null = $state(null);
+
+  // effect A：mount 时创建 controller 并订阅；依赖 delay/minShowTime（变化才重建）。
+  // 不依赖 spinning：避免 spinning 变化重建 controller 丢失去抖/最短显示状态。
+  $effect(() => {
+    const controller = createSpinController({ delay, minShowTime, spinning });
+    ctrl = controller;
+    effective = controller.getEffective();
+    const unsub = controller.subscribe((v) => {
+      effective = v;
+      if (v) onShow?.();
+      else onHide?.();
+    });
+    return () => {
+      unsub();
+      controller.destroy();
+      ctrl = null;
+    };
+  });
+
+  // effect B：仅依赖 spinning + ctrl，把受控请求推给 controller（红线 #1：只推入，不回写）。
+  $effect(() => {
+    ctrl?.setSpinning(spinning);
+  });
+
+  const isWrapper = $derived(children !== undefined && !fullscreen);
+  const isFullscreen = $derived(fullscreen);
+  const isInline = $derived(!isWrapper && !isFullscreen);
+
+  const hasTip = $derived(tip.length > 0);
+  // 有 tip 时 tip 文本作为可访问名；无 tip 时用 ariaLabel。
+  const statusLabel = $derived(hasTip ? undefined : (ariaLabel ?? loc().t('Spin.loading')));
+
+  const indicatorClass = $derived(`cd-spin__indicator cd-spin__indicator--${size}`);
+</script>
+
+{#snippet defaultIndicator()}
+  <svg
+    class={indicatorClass}
+    viewBox="0 0 24 24"
+    aria-hidden="true"
+    focusable="false"
+  >
+    <circle
+      class="cd-spin__track"
+      cx="12"
+      cy="12"
+      r="10"
+      fill="none"
+      stroke="var(--cd-spin-track-color)"
+      stroke-width="2.5"
+    />
+    <circle
+      class="cd-spin__arc"
+      cx="12"
+      cy="12"
+      r="10"
+      fill="none"
+      stroke="var(--cd-spin-color)"
+      stroke-width="2.5"
+      stroke-linecap="round"
+      stroke-dasharray="47 63"
+    />
+  </svg>
+{/snippet}
+
+{#snippet spinner()}
+  {#if indicator}
+    {@render indicator({ size })}
+  {:else}
+    {@render defaultIndicator()}
+  {/if}
+{/snippet}
+
+{#if isInline}
+  <div
+    class="cd-spin cd-spin--{size}"
+    role="status"
+    aria-live="polite"
+    aria-label={statusLabel}
+  >
+    {@render spinner()}
+    {#if hasTip}
+      <div class="cd-spin__tip">{tip}</div>
+    {/if}
+  </div>
+{:else if isFullscreen}
+  {#if effective}
+    <div
+      class="cd-spin cd-spin--{size} cd-spin--fullscreen"
+      role="status"
+      aria-live="polite"
+      aria-label={statusLabel}
+    >
+      <div class="cd-spin__box">
+        {@render spinner()}
+        {#if hasTip}
+          <div class="cd-spin__tip">{tip}</div>
+        {/if}
+      </div>
+    </div>
+  {/if}
+{:else}
+  <div class="cd-spin-wrapper {wrapperClassName}">
+    <div
+      class="cd-spin__content"
+      class:cd-spin__content--blur={effective}
+      aria-busy={effective ? true : undefined}
+      inert={effective ? true : undefined}
+    >
+      {@render children?.()}
+    </div>
+    {#if effective}
+      <div
+        class="cd-spin__overlay cd-spin--{size}"
+        role="status"
+        aria-live="polite"
+        aria-label={statusLabel}
+      >
+        <div class="cd-spin__box">
+          {@render spinner()}
+          {#if hasTip}
+            <div class="cd-spin__tip">{tip}</div>
+          {/if}
+        </div>
+      </div>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  .cd-spin {
+    display: inline-flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: var(--cd-spin-tip-gap);
+    color: var(--cd-spin-color);
+  }
+
+  .cd-spin__indicator {
+    display: block;
+    inline-size: var(--cd-spin-size-default);
+    block-size: var(--cd-spin-size-default);
+    animation: cd-spin-rotate var(--cd-spin-duration) linear infinite;
+  }
+  .cd-spin__indicator--small {
+    inline-size: var(--cd-spin-size-small);
+    block-size: var(--cd-spin-size-small);
+  }
+  .cd-spin__indicator--default {
+    inline-size: var(--cd-spin-size-default);
+    block-size: var(--cd-spin-size-default);
+  }
+  .cd-spin__indicator--large {
+    inline-size: var(--cd-spin-size-large);
+    block-size: var(--cd-spin-size-large);
+  }
+
+  .cd-spin__tip {
+    color: var(--cd-spin-tip-color);
+    font-size: var(--cd-font-size-body);
+    text-align: center;
+  }
+
+  /* wrapper 形态 */
+  .cd-spin-wrapper {
+    position: relative;
+  }
+  .cd-spin__content {
+    transition: opacity var(--cd-spin-fade-duration) var(--cd-motion-ease-standard);
+  }
+  .cd-spin__content--blur {
+    opacity: 0.5;
+    pointer-events: none;
+    user-select: none;
+  }
+  .cd-spin__overlay {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: var(--cd-spin-z);
+    background: var(--cd-spin-mask-bg);
+    animation: cd-spin-fade var(--cd-spin-fade-duration) var(--cd-motion-ease-standard);
+  }
+
+  /* fullscreen 形态 */
+  .cd-spin--fullscreen {
+    position: fixed;
+    inset: 0;
+    z-index: var(--cd-spin-z-fullscreen);
+    background: var(--cd-spin-mask-bg);
+    animation: cd-spin-fade var(--cd-spin-fade-duration) var(--cd-motion-ease-standard);
+  }
+
+  .cd-spin__box {
+    display: inline-flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: var(--cd-spin-tip-gap);
+    color: var(--cd-spin-color);
+  }
+
+  @keyframes cd-spin-rotate {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+  @keyframes cd-spin-fade {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .cd-spin__indicator {
+      animation: cd-spin-pulse var(--cd-spin-duration-reduced) ease-in-out infinite;
+    }
+    .cd-spin__overlay,
+    .cd-spin--fullscreen {
+      animation: none;
+    }
+    .cd-spin__content {
+      transition: none;
+    }
+  }
+
+  @keyframes cd-spin-pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.4;
+    }
+  }
+</style>

package/src/spin/SpinA11yFixture.svelte

@@ -0,0 +1,18 @@
+<!--
+  Spin a11y 测试夹具：不注入 children，使 inline 形态生效。
+  （renderWithLocale 的 harness 恒注入空 children snippet，会让 Spin 走 wrapper 形态。）
+  自带 LocaleProvider，故测试直接 render 本夹具。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import Spin from './Spin.svelte';
+
+  interface Props {
+    props?: Record<string, unknown>;
+  }
+  let { props = {} }: Props = $props();
+</script>
+
+<LocaleProvider locale="en_US">
+  <Spin {...props} />
+</LocaleProvider>

package/src/spin/index.ts

@@ -0,0 +1,2 @@
+export { default as Spin } from './Spin.svelte';
+export { meta as spinMeta } from './meta.js';