@chenzy-design/svelte 0.1.0

package/src/grid/meta.ts

@@ -0,0 +1,72 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * Aggregated metadata for the Grid family (Row + Col).
+ * 24-column flex grid with responsive breakpoint props (xs/sm/md/lg/xl/xxl).
+ */
+export const meta = {
+  name: 'Grid',
+  category: 'basic',
+  description: '24 栅格布局：Row 容器 + Col 列，flex 实现，gutter 经 context 下发到 Col；支持 xs/sm/md/lg/xl/xxl 响应式断点（mobile-first 降级解析）。',
+  exports: ['Row', 'Col'],
+  // flat props (Row + Col merged); each item tagged with its owner.
+  props: [
+    {
+      owner: 'Row',
+      name: 'gutter',
+      type: 'number|[number,number]|Partial<Record<Breakpoint,number|[number,number]>>',
+      default: '0',
+      desc: 'number→水平间距；[x,y]→水平+垂直；按断点对象 { xs,sm,md,... } 时按当前视口 mobile-first 降级解析',
+    },
+    {
+      owner: 'Row',
+      name: 'align',
+      type: "'top'|'middle'|'bottom'|'baseline'|'stretch'",
+      default: "'top'",
+      desc: '映射 align-items',
+    },
+    {
+      owner: 'Row',
+      name: 'justify',
+      type: "'start'|'end'|'center'|'space-between'|'space-around'|'space-evenly'",
+      default: "'start'",
+      desc: '映射 justify-content',
+    },
+    { owner: 'Row', name: 'wrap', type: 'boolean', default: 'true', desc: 'false→flex-wrap:nowrap' },
+    { owner: 'Row', name: 'class', type: 'string', default: "''" },
+    { owner: 'Col', name: 'span', type: 'number', default: 'undefined', desc: '0-24，0 隐藏，未设为自动列' },
+    { owner: 'Col', name: 'offset', type: 'number', default: '0', desc: 'margin-inline-start 偏移列数' },
+    { owner: 'Col', name: 'order', type: 'number', default: '0', desc: 'flex order' },
+    { owner: 'Col', name: 'push', type: 'number', default: '0', desc: 'inset-inline-start 相对偏移' },
+    { owner: 'Col', name: 'pull', type: 'number', default: '0', desc: 'inset-inline-end 相对偏移' },
+    {
+      owner: 'Col',
+      name: 'flex',
+      type: 'string|number',
+      default: 'undefined',
+      desc: '设置后优先于 span，直接控制 flex',
+    },
+    {
+      owner: 'Col',
+      name: 'xs|sm|md|lg|xl|xxl',
+      type: 'number | { span?, offset?, order?, push?, pull?, flex? }',
+      default: 'undefined',
+      desc: '响应式断点覆盖：值为 number(span) 或子集对象，按当前视口 mobile-first 降级解析后覆盖基础 props',
+    },
+    { owner: 'Col', name: 'class', type: 'string', default: "''" },
+  ],
+  events: [],
+  slots: [{ name: 'children', desc: 'Row 内放 Col；Col 内放任意内容' }],
+  a11y: { hasRole: false, focusable: false, note: '纯布局容器，不引入语义角色' },
+  tokens: ['--cd-grid-columns', '--cd-grid-gutter-x', '--cd-grid-gutter-y'],
+  responsive: true,
+  examples: [
+    {
+      title: '基础两栏',
+      code: '<Row gutter={16}><Col span={12}>左</Col><Col span={12}>右</Col></Row>',
+    },
+    {
+      title: '响应式断点',
+      code: '<Row gutter={{ xs: 8, md: 24 }}><Col xs={24} md={12}>左</Col><Col xs={24} md={12}>右</Col></Row>',
+    },
+  ],
+} as const;

package/src/grid/use-breakpoint.svelte.ts

@@ -0,0 +1,48 @@
+/**
+ * useBreakpoint — reactive current breakpoint from the viewport width.
+ * Listens to resize (rAF-throttled) imperatively in $effect with cleanup
+ * (red line #3); pure breakpoint math lives in @chenzy-design/core.
+ * SSR-safe: defaults to 'xs' until mounted, then syncs to the real width.
+ */
+import { resolveActiveBreakpoint, type Breakpoint } from '@chenzy-design/core';
+
+export interface BreakpointHandle {
+  /** the current active breakpoint (reactive) */
+  readonly current: Breakpoint;
+}
+
+const SUPPORTS_DOM = typeof window !== 'undefined';
+
+export function useBreakpoint(): BreakpointHandle {
+  // initial value: real width if available (client), else 'xs' (SSR-safe).
+  let bp = $state<Breakpoint>(
+    SUPPORTS_DOM ? resolveActiveBreakpoint(window.innerWidth) : 'xs',
+  );
+
+  $effect(() => {
+    if (!SUPPORTS_DOM) return;
+    let frame = 0;
+    const measure = () => {
+      frame = 0;
+      const next = resolveActiveBreakpoint(window.innerWidth);
+      if (next !== bp) bp = next;
+    };
+    const onResize = () => {
+      if (frame) return;
+      frame = window.requestAnimationFrame(measure);
+    };
+    // sync once on mount (covers the SSR→client width correction) then listen.
+    measure();
+    window.addEventListener('resize', onResize);
+    return () => {
+      if (frame) window.cancelAnimationFrame(frame);
+      window.removeEventListener('resize', onResize);
+    };
+  });
+
+  return {
+    get current() {
+      return bp;
+    },
+  };
+}

package/src/highlight/Highlight.a11y.test.ts

@@ -0,0 +1,25 @@
+// Highlight a11y：命中片段默认渲染 <mark>，纯文本输出。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import Highlight from './Highlight.svelte';
+
+describe('Highlight a11y', () => {
+  it('单关键词：命中渲染 <mark>，无 axe violations', async () => {
+    const { container } = renderWithLocale(Highlight, {
+      props: { sourceString: 'The quick brown fox', searchWords: 'quick' },
+    });
+    const marks = container.querySelectorAll('mark.cd-highlight__mark');
+    expect(marks.length).toBe(1);
+    expect(marks[0]?.textContent).toBe('quick');
+    await expectNoAxeViolations(container);
+  });
+
+  it('多关键词：多处命中，无 axe violations', async () => {
+    const { container } = renderWithLocale(Highlight, {
+      props: { sourceString: 'red green red blue', searchWords: ['red', 'blue'] },
+    });
+    const marks = container.querySelectorAll('mark.cd-highlight__mark');
+    expect(marks.length).toBe(3);
+    await expectNoAxeViolations(container);
+  });
+});

package/src/highlight/Highlight.svelte

@@ -0,0 +1,99 @@
+<!--
+  Highlight — see specs/components/show/Highlight.spec.md
+  纯展示文本高亮：sourceString 中标记 searchWords。纯文本输出（不解析 HTML）。
+  片段分割 / 重叠区间合并为纯函数（@chenzy-design/core highlightChunks，红线 #2），
+  渲染派生：默认 <mark>，可由 highlight/chunk snippet 自定义。
+  支持单/多关键词、大小写敏感、highlightAll、autoEscape、自定义 component/类名/样式、
+  unstyled、命中片段 id + aria 关联。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { highlightChunks, useId } from '@chenzy-design/core';
+
+  interface Props {
+    sourceString?: string;
+    searchWords?: string | string[];
+    caseSensitive?: boolean;
+    highlightAll?: boolean;
+    autoEscape?: boolean;
+    component?: string;
+    highlightClassName?: string;
+    highlightStyle?: string;
+    className?: string;
+    style?: string;
+    unstyled?: boolean;
+    /** 自定义命中片段渲染（覆盖默认 <mark>）。 */
+    highlight?: Snippet<[{ chunk: string; index: number }]>;
+    /** 自定义非命中片段渲染（默认裸文本）。 */
+    chunk?: Snippet<[{ chunk: string; index: number }]>;
+    /** 命中片段 id 前缀，用于 aria 关联；省略则自动生成。 */
+    idPrefix?: string;
+    /** 追加到每个命中片段的 aria-describedby（指向外部说明元素）。 */
+    describedById?: string;
+    /** 命中片段的 aria-label（默认不加，避免逐字播报噪音）。 */
+    highlightAriaLabel?: string;
+  }
+
+  let {
+    sourceString = '',
+    searchWords = [],
+    caseSensitive = false,
+    highlightAll = true,
+    autoEscape = true,
+    component = 'mark',
+    highlightClassName = '',
+    highlightStyle = '',
+    className = '',
+    style = '',
+    unstyled = false,
+    highlight,
+    chunk,
+    idPrefix,
+    describedById,
+    highlightAriaLabel,
+  }: Props = $props();
+
+  // 稳定前缀：仅在未显式传入时生成一次，render 期只读（红线 #2）。
+  const autoPrefix = useId('cd-highlight');
+  const prefix = $derived(idPrefix || autoPrefix);
+
+  // 片段分割 + 重叠区间合并：纯函数（core），渲染只读派生（红线 #2）。
+  const chunks = $derived(
+    highlightChunks(sourceString, searchWords, { caseSensitive, highlightAll, autoEscape }),
+  );
+
+  const rootClass = $derived(['cd-highlight', className].filter(Boolean).join(' '));
+  const markClass = $derived(
+    ['cd-highlight__mark', unstyled && 'cd-highlight__mark--unstyled', highlightClassName]
+      .filter(Boolean)
+      .join(' '),
+  );
+</script>
+
+<span class={rootClass} style={style || undefined}
+  >{#each chunks as item, i (i)}{#if item.matched}{#if highlight}{@render highlight({ chunk: item.text, index: i })}{:else}<svelte:element
+          this={component}
+          id={`${prefix}-${i}`}
+          class={markClass}
+          style={highlightStyle || undefined}
+          aria-label={highlightAriaLabel || undefined}
+          aria-describedby={describedById || undefined}>{item.text}</svelte:element>{/if}{:else if chunk}{@render chunk({ chunk: item.text, index: i })}{:else}{item.text}{/if}{/each}</span
+>
+
+<style>
+  .cd-highlight {
+    color: inherit;
+  }
+  .cd-highlight__mark {
+    padding-inline: 2px;
+    border-radius: var(--cd-radius-small);
+    background: var(--cd-highlight-bg);
+    color: var(--cd-highlight-color);
+    font-weight: inherit;
+  }
+  .cd-highlight__mark--unstyled {
+    padding-inline: 0;
+    background: transparent;
+    color: inherit;
+  }
+</style>

package/src/highlight/index.ts

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

package/src/highlight/meta.ts

@@ -0,0 +1,80 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * Highlight — see specs/components/show/Highlight.spec.md
+ */
+export const meta = {
+  name: 'Highlight',
+  category: 'show',
+  description:
+    '纯展示文本高亮：在 sourceString 中标记 searchWords，默认用 <mark> 包裹。纯文本输出（HTML 会被转义而非解析），支持大小写敏感、仅首个/全部匹配、正则转义开关与自定义包裹元素/样式。',
+  exports: ['Highlight'],
+  props: [
+    { name: 'sourceString', type: 'string', default: "''", desc: '待处理原始文本（纯文本，HTML 被转义）' },
+    { name: 'searchWords', type: 'string|string[]', default: '[]', desc: '需高亮关键词，空串忽略' },
+    { name: 'caseSensitive', type: 'boolean', default: 'false', desc: '是否大小写敏感' },
+    { name: 'highlightAll', type: 'boolean', default: 'true', desc: 'true 高亮全部匹配，false 仅首个' },
+    {
+      name: 'autoEscape',
+      type: 'boolean',
+      default: 'true',
+      desc: '是否对关键词正则转义；关闭后 searchWords 视为正则源',
+    },
+    { name: 'component', type: 'string', default: "'mark'", desc: '高亮片段包裹标签名' },
+    { name: 'highlightClassName', type: 'string', default: "''", desc: '追加到高亮片段的类名' },
+    { name: 'highlightStyle', type: 'string', default: "''", desc: '追加到高亮片段的内联样式' },
+    { name: 'className', type: 'string', default: "''", desc: '根 span 类名' },
+    { name: 'style', type: 'string', default: "''", desc: '根 span 内联样式' },
+    { name: 'unstyled', type: 'boolean', default: 'false', desc: '移除默认高亮视觉，仅保留语义与类名' },
+    {
+      name: 'idPrefix',
+      type: 'string',
+      default: 'auto',
+      desc: '命中片段 id 前缀（生成 `${prefix}-${index}`），用于 aria 关联；省略则自动生成',
+    },
+    {
+      name: 'describedById',
+      type: 'string',
+      default: "''",
+      desc: '追加到每个命中片段的 aria-describedby，指向外部说明元素',
+    },
+    {
+      name: 'highlightAriaLabel',
+      type: 'string',
+      default: 'undefined',
+      desc: '命中片段的 aria-label；默认不加以避免逐字播报噪音',
+    },
+  ],
+  events: [],
+  slots: [
+    {
+      name: 'highlight',
+      type: 'Snippet<[{ chunk: string; index: number }]>',
+      desc: '自定义命中片段渲染，覆盖默认 <mark>；不传则保持默认高亮行为',
+    },
+    {
+      name: 'chunk',
+      type: 'Snippet<[{ chunk: string; index: number }]>',
+      desc: '自定义非命中片段渲染；不传则输出裸文本',
+    },
+  ],
+  a11y: {
+    role: 'none',
+    focusable: false,
+    notes: [
+      '高亮片段用原生 <mark> 元素承载浏览器/AT 内建“标记”语义',
+      '不可聚焦、无 tabindex，避免搜索结果列表产生大量 Tab 停留点',
+      '默认不对每个高亮加 aria-label，避免逐字播报噪音；命中计数由调用方外层 live region 负责',
+      '每个命中片段带稳定 id（idPrefix-index），可被外部 aria-describedby/控件引用以定位',
+      '可选 describedById/highlightAriaLabel 供需要显式关联的无障碍场景按需开启',
+      '语义+背景双通道区分，不仅靠颜色（WCAG 1.4.1）',
+    ],
+  },
+  tokens: ['--cd-highlight-bg', '--cd-highlight-color', '--cd-radius-small'],
+  examples: [
+    { title: '基础', code: '<Highlight sourceString="hello world" searchWords="world" />' },
+    {
+      title: '多词',
+      code: '<Highlight sourceString="foo bar baz" searchWords={["foo", "baz"]} />',
+    },
+  ],
+} as const;

package/src/icon/Icon.svelte

@@ -0,0 +1,156 @@
+<!--
+  Icon — see specs/components/basic/Icon.spec.md
+  Pure presentational primitive. Token-driven size/color, a11y-correct.
+-->
+<script lang="ts">
+  import type { Component, Snippet } from 'svelte';
+
+  type IconSize = 'extra-small' | 'small' | 'default' | 'large' | 'extra-large' | number;
+  type IconStatus = 'default' | 'warning' | 'error' | 'success' | 'info';
+
+  interface Props {
+    size?: IconSize;
+    spin?: boolean;
+    rotate?: number;
+    status?: IconStatus;
+    color?: string;
+    /** 直接传入 SVG 字符串，内部用 {@html} 渲染。来源须可信（构建期 SVGO 净化）。 */
+    svg?: string;
+    /** 传入一个 Svelte 图标组件作为渲染源。 */
+    component?: Component;
+    label?: string;
+    class?: string;
+    /** 透传到根元素的内联样式。 */
+    style?: string;
+    children?: Snippet;
+  }
+
+  let {
+    size = 'default',
+    spin = false,
+    rotate = 0,
+    status = 'default',
+    color,
+    svg,
+    component,
+    label,
+    class: className = '',
+    style = '',
+    children,
+  }: Props = $props();
+
+  // 渲染源派生：优先级 svg > component > children。
+  const SvgComponent = $derived(component);
+
+  const isNumericSize = $derived(typeof size === 'number');
+
+  const cls = $derived(
+    [
+      'cd-icon',
+      !isNumericSize && `cd-icon--${size}`,
+      status !== 'default' && `cd-icon--status-${status}`,
+      spin && 'cd-icon--spin',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  const inlineStyle = $derived(
+    [
+      isNumericSize && `width:${size}px`,
+      isNumericSize && `height:${size}px`,
+      color && `color:${color}`,
+      rotate && `transform:rotate(${rotate}deg)`,
+      style,
+    ]
+      .filter(Boolean)
+      .join(';'),
+  );
+</script>
+
+<span
+  class={cls}
+  style={inlineStyle || undefined}
+  role={label ? 'img' : undefined}
+  aria-label={label}
+  aria-hidden={label ? undefined : 'true'}
+>
+  {#if svg}
+    <!-- 渲染源 svg：信任来源（构建期 SVGO 净化），运行时不做净化；用户传入的运行时 svg 须自行确保可信。 -->
+    {@html svg}
+  {:else if SvgComponent}
+    <SvgComponent />
+  {:else}
+    {@render children?.()}
+  {/if}
+</span>
+
+<style>
+  .cd-icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    vertical-align: -0.125em;
+    width: var(--cd-icon-size-default);
+    height: var(--cd-icon-size-default);
+    color: currentColor;
+    fill: currentColor;
+    line-height: 1;
+  }
+  .cd-icon :global(svg) {
+    width: 100%;
+    height: 100%;
+    /* Do NOT force fill here: stroke-based SVGs set their own fill="none".
+       Color propagates via currentColor; fill-based icons should use
+       fill="currentColor" in their own markup. */
+  }
+  .cd-icon--extra-small {
+    width: var(--cd-icon-size-extra-small);
+    height: var(--cd-icon-size-extra-small);
+  }
+  .cd-icon--small {
+    width: var(--cd-icon-size-small);
+    height: var(--cd-icon-size-small);
+  }
+  .cd-icon--default {
+    width: var(--cd-icon-size-default);
+    height: var(--cd-icon-size-default);
+  }
+  .cd-icon--large {
+    width: var(--cd-icon-size-large);
+    height: var(--cd-icon-size-large);
+  }
+  .cd-icon--extra-large {
+    width: var(--cd-icon-size-extra-large);
+    height: var(--cd-icon-size-extra-large);
+  }
+  .cd-icon--status-warning {
+    color: var(--cd-icon-color-warning);
+  }
+  .cd-icon--status-error {
+    color: var(--cd-icon-color-error);
+  }
+  .cd-icon--status-success {
+    color: var(--cd-icon-color-success);
+  }
+  .cd-icon--status-info {
+    color: var(--cd-icon-color-info);
+  }
+  .cd-icon--spin {
+    animation: cd-icon-spin var(--cd-icon-spin-duration) var(--cd-icon-spin-timing) infinite;
+  }
+  @keyframes cd-icon-spin {
+    from {
+      transform: rotate(0deg);
+    }
+    to {
+      transform: rotate(360deg);
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .cd-icon--spin {
+      animation: none;
+    }
+  }
+</style>

package/src/icon/index.ts

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

package/src/icon/meta.ts

@@ -0,0 +1,41 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/components/basic/Icon.spec.md.
+ */
+export const meta = {
+  name: 'Icon',
+  category: 'basic',
+  description: '统一尺寸、颜色、对齐的矢量图标容器，纯展示原语。',
+  props: [
+    {
+      name: 'size',
+      type: "'extra-small'|'small'|'default'|'large'|'extra-large'|number",
+      default: "'default'",
+      desc: '尺寸枚举映射到 token，数字直接作为 px',
+    },
+    { name: 'spin', type: 'boolean', default: 'false', desc: '持续旋转，受 reduced-motion 抑制' },
+    { name: 'rotate', type: 'number', default: '0', desc: '静态旋转角度（deg）' },
+    { name: 'status', type: "'default'|'warning'|'error'|'success'|'info'", default: "'default'" },
+    { name: 'color', type: 'string', default: 'undefined', desc: '显式覆盖颜色，优先级高于 status' },
+    {
+      name: 'svg',
+      type: 'string',
+      default: 'undefined',
+      desc: 'SVG 字符串，内部 {@html} 渲染（来源须可信）；优先级最高',
+    },
+    {
+      name: 'component',
+      type: 'Component',
+      default: 'undefined',
+      desc: 'Svelte 图标组件作渲染源；优先级高于 children',
+    },
+    { name: 'label', type: 'string', default: 'undefined', desc: '语义图标可访问名称；提供后 role=img' },
+    { name: 'class', type: 'string', default: "''" },
+    { name: 'style', type: 'string', default: "''", desc: '透传到根元素的内联样式' },
+  ],
+  events: [],
+  slots: [{ name: 'children', desc: '自定义图标内容（SVG）' }],
+  a11y: { role: 'img-when-labeled', decorativeDefault: true, reducedMotion: true },
+  tokens: ['--cd-icon-size-*', '--cd-icon-color', '--cd-icon-color-*', '--cd-icon-spin-*'],
+  examples: [{ title: '加载中', code: '<Icon spin status="info">{@render svg()}</Icon>' }],
+} as const;

package/src/image/Image.a11y.test.ts

@@ -0,0 +1,30 @@
+// Image a11y：有意义图带 alt；装饰图（alt=''）取 role=presentation。
+// jsdom 不真正解码图片，状态停在 loading/placeholder，<img> 与 alt/role 仍可断言。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import Image from './Image.svelte';
+
+// Image 的 src 为必填 prop，与 renderWithLocale 的宽松 AnyComponent 形态不严格兼容
+// （exactOptionalPropertyTypes），故转为 helper 接受的构造器类型。
+const ImageC = Image as unknown as Parameters<typeof renderWithLocale>[0];
+
+describe('Image a11y', () => {
+  it('有意义图：<img> 带 alt，无 axe violations', async () => {
+    const { container } = renderWithLocale(ImageC, {
+      props: { src: 'https://example.com/p.png', alt: 'A scenic mountain', lazy: false },
+    });
+    const img = container.querySelector('img.cd-image__img');
+    expect(img?.getAttribute('alt')).toBe('A scenic mountain');
+    expect(img?.getAttribute('role')).toBeNull();
+    await expectNoAxeViolations(container);
+  });
+
+  it('装饰图（alt=""）：role=presentation，无 axe violations', async () => {
+    const { container } = renderWithLocale(ImageC, {
+      props: { src: 'https://example.com/deco.png', alt: '', lazy: false },
+    });
+    const img = container.querySelector('img.cd-image__img');
+    expect(img?.getAttribute('role')).toBe('presentation');
+    await expectNoAxeViolations(container);
+  });
+});