@chenzy-design/svelte 0.1.0

package/src/list/ListA11yFixture.svelte

@@ -0,0 +1,38 @@
+<!--
+  仅供 List.a11y.test.ts 使用的测试夹具：数据驱动 dataSource + renderItem Snippet。
+  selectable 时容器升级 role=listbox，行 role=option + aria-selected。
+-->
+<script lang="ts">
+  import { List } from './index.js';
+
+  interface Props {
+    selectable?: false | 'single' | 'multiple';
+    bordered?: boolean;
+    header?: string;
+    defaultSelectedKeys?: (string | number)[];
+  }
+  let {
+    selectable = false,
+    bordered = false,
+    header = undefined,
+    defaultSelectedKeys = [],
+  }: Props = $props();
+
+  const dataSource = [
+    { key: 'u1', title: 'Ada Lovelace' },
+    { key: 'u2', title: 'Alan Turing' },
+    { key: 'u3', title: 'Grace Hopper' },
+  ];
+</script>
+
+<List
+  {dataSource}
+  {selectable}
+  {bordered}
+  {defaultSelectedKeys}
+  {...header !== undefined ? { header } : {}}
+>
+  {#snippet renderItem(item)}
+    <span>{(item as { title: string }).title}</span>
+  {/snippet}
+</List>

package/src/list/ListBenchFixture.svelte

@@ -0,0 +1,22 @@
+<!--
+  仅供 List.bench.ts 使用的基准夹具：按 count 生成 dataSource，
+  用 renderItem snippet 渲染真实行。隔离 snippet（snippet 只能在 .svelte 内定义）。
+-->
+<script lang="ts">
+  import { List } from './index.js';
+
+  interface Props {
+    count?: number;
+  }
+  let { count = 100 }: Props = $props();
+
+  const dataSource = $derived(
+    Array.from({ length: count }, (_, i) => ({ key: `r${i}`, title: `Item ${i}` })),
+  );
+</script>
+
+<List {dataSource} bordered>
+  {#snippet renderItem(item)}
+    <span>{(item as { title: string }).title}</span>
+  {/snippet}
+</List>

package/src/list/ListItem.svelte

@@ -0,0 +1,175 @@
+<!--
+  List.Item — 声明式列表项容器。
+  - 默认（非 selectable）：渲染 <li role="listitem">，与 dataSource 模式同结构，复用父 List
+    的 split/size 样式。
+  - selectable：读父 List context（getListContext），渲染 role="option" + aria-selected，
+    左侧内置 checkbox/radio 视觉，点击/键盘触发 ctx.toggle（仅回调 onSelectionChange，
+    红线 #1：不回写 selectedKeys）。
+  default 主内容 + extra（右侧附加区） + actions（底部操作区）三段插槽，对齐 spec。
+  无 effect 自循环：选中态来自父 context 派生（受控 selectedKeys），本组件不写 $state。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { ListKey } from '@chenzy-design/core';
+  import { Checkbox } from '../checkbox/index.js';
+  import { getListContext } from './context.js';
+
+  interface Props {
+    /** selectable 模式下本项的唯一 key（用于选中态判定与回调）。 */
+    itemKey?: ListKey;
+    /** item 头部（字符串或 Snippet）。 */
+    header?: string | Snippet;
+    /** item 主要内容区（语义化 slot，与 children 不互斥）。 */
+    main?: Snippet;
+    /** 右侧附加内容区（如缩略图、统计数字）。 */
+    extra?: Snippet;
+    /** 底部操作区（按钮组）。 */
+    actions?: Snippet;
+    class?: string;
+    /** 主内容（通用插槽）。 */
+    children?: Snippet;
+  }
+
+  let { itemKey, header, main, extra, actions, class: className = '', children }: Props = $props();
+
+  function isSnippet(v: unknown): v is Snippet {
+    return typeof v === 'function';
+  }
+
+  const ctx = getListContext();
+
+  const selectable = $derived(ctx?.getSelectable() ?? false);
+  const selected = $derived(
+    selectable && itemKey !== undefined ? !!ctx?.isSelected(itemKey) : false,
+  );
+  const multiple = $derived(selectable === 'multiple');
+
+  function activate(shiftKey: boolean) {
+    if (!selectable || itemKey === undefined) return;
+    ctx?.toggle(itemKey, shiftKey);
+  }
+
+  function onClick(e: MouseEvent) {
+    activate(e.shiftKey);
+  }
+
+  // roving tabindex 由父派生（红线 #2：本组件只读不写父级 $state）。
+  const tabindex = $derived(
+    selectable && itemKey !== undefined ? (ctx?.rowTabindex(itemKey) ?? 0) : undefined,
+  );
+
+  function onKeydown(e: KeyboardEvent) {
+    if (e.key === ' ' || e.key === 'Enter') {
+      e.preventDefault();
+      activate(e.shiftKey);
+      return;
+    }
+    // ↑↓ / Home/End / PageUp/Down roving 交父按 DOM 顺序处理。
+    if (itemKey !== undefined) ctx?.onRowKeydown(e, itemKey);
+  }
+
+  const cls = $derived(
+    [
+      'cd-list__item',
+      selectable && 'cd-list__item--selectable',
+      selected && 'cd-list__item--selected',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+</script>
+
+{#snippet itemInner()}
+  {#if header !== undefined}
+    <div class="cd-list__item-header">
+      {#if isSnippet(header)}{@render header()}{:else}{header}{/if}
+    </div>
+  {/if}
+  <div class="cd-list__item-row">
+    <div class="cd-list__item-content">
+      {#if main}{@render main()}{/if}
+      {@render children?.()}
+    </div>
+    {#if extra}<div class="cd-list__item-extra">{@render extra()}</div>{/if}
+  </div>
+  {#if actions}<div class="cd-list__item-actions">{@render actions()}</div>{/if}
+{/snippet}
+
+{#if selectable}
+  <li
+    class={cls}
+    role="option"
+    aria-selected={selected}
+    data-list-key={itemKey}
+    {tabindex}
+    onclick={onClick}
+    onkeydown={onKeydown}
+    onfocus={() => itemKey !== undefined && ctx?.onRowFocus(itemKey)}
+  >
+    <span class="cd-list__item-selector" aria-hidden="true">
+      <Checkbox checked={selected} />
+    </span>
+    <div class="cd-list__item-main">
+      {@render itemInner()}
+    </div>
+  </li>
+{:else}
+  <li class={cls}>
+    <div class="cd-list__item-main">
+      {@render itemInner()}
+    </div>
+  </li>
+{/if}
+
+<style>
+  .cd-list__item-main {
+    flex: 1;
+    min-inline-size: 0;
+  }
+  .cd-list__item-header {
+    font-weight: var(--cd-font-weight-medium, 500);
+    margin-block-end: var(--cd-spacing-1, 4px);
+    color: var(--cd-color-text-0);
+  }
+  .cd-list__item-row {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--cd-spacing-3, 12px);
+  }
+  .cd-list__item-content {
+    flex: 1;
+    min-inline-size: 0;
+  }
+  .cd-list__item-extra {
+    flex: none;
+  }
+  .cd-list__item-actions {
+    display: flex;
+    gap: var(--cd-spacing-3, 12px);
+    margin-block-start: var(--cd-spacing-2, 8px);
+  }
+
+  .cd-list__item--selectable {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--cd-spacing-2, 8px);
+    cursor: pointer;
+    outline: none;
+  }
+  .cd-list__item--selectable:hover {
+    background: var(--cd-color-fill-0, rgba(0, 0, 0, 0.03));
+  }
+  .cd-list__item--selectable:focus-visible {
+    box-shadow: inset 0 0 0 2px var(--cd-color-primary, #0066ff);
+  }
+  .cd-list__item--selected {
+    background: var(--cd-color-primary-light-default, rgba(0, 102, 255, 0.1));
+  }
+  .cd-list__item-selector {
+    flex: none;
+    display: flex;
+    align-items: center;
+    pointer-events: none;
+  }
+</style>

package/src/list/ListKbdFixture.svelte

@@ -0,0 +1,31 @@
+<!--
+  仅供 List.kbd.test.ts（browser project）使用的键盘 e2e 夹具。
+  selectable="single" → role=listbox / 行 role=option，roving 单停靠点（真实焦点）。
+  前后各放按钮验证 Tab 进入只停靠单行、Tab 出去落到 after。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import List from './List.svelte';
+
+  type Row = { key: string; label: string };
+  const dataSource: Row[] = [
+    { key: 'a', label: 'Alpha' },
+    { key: 'b', label: 'Bravo' },
+    { key: 'c', label: 'Charlie' },
+  ];
+</script>
+
+<LocaleProvider locale="en_US">
+  <button type="button" data-testid="before">before</button>
+  <List
+    {dataSource}
+    rowKey="key"
+    selectable="single"
+    ariaLabel="People"
+  >
+    {#snippet renderItem(item: Row)}
+      <span>{item.label}</span>
+    {/snippet}
+  </List>
+  <button type="button" data-testid="after">after</button>
+</LocaleProvider>

package/src/list/ListMeta.svelte

@@ -0,0 +1,73 @@
+<!--
+  List.Meta — 项内结构化布局：avatar（头像/图标） + title（标题） + description（描述）。
+  三段均可用 props（string）或同名 Snippet 提供，Snippet 优先。纯展示，无状态、无 effect。
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    /** 左侧头像/图标区，string 直接渲染或用 avatar Snippet。 */
+    avatar?: string | Snippet;
+    /** 标题，string 或 title Snippet。 */
+    title?: string | Snippet;
+    /** 描述，string 或 description Snippet。 */
+    description?: string | Snippet;
+    class?: string;
+  }
+
+  let { avatar, title, description, class: className = '' }: Props = $props();
+
+  function isSnippet(v: unknown): v is Snippet {
+    return typeof v === 'function';
+  }
+</script>
+
+<div class={['cd-list__meta', className].filter(Boolean).join(' ')}>
+  {#if avatar !== undefined}
+    <div class="cd-list__meta-avatar">
+      {#if isSnippet(avatar)}{@render avatar()}{:else}{avatar}{/if}
+    </div>
+  {/if}
+  <div class="cd-list__meta-content">
+    {#if title !== undefined}
+      <div class="cd-list__meta-title">
+        {#if isSnippet(title)}{@render title()}{:else}{title}{/if}
+      </div>
+    {/if}
+    {#if description !== undefined}
+      <div class="cd-list__meta-description">
+        {#if isSnippet(description)}{@render description()}{:else}{description}{/if}
+      </div>
+    {/if}
+  </div>
+</div>
+
+<style>
+  .cd-list__meta {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--cd-spacing-3, 12px);
+    flex: 1;
+    min-inline-size: 0;
+  }
+  .cd-list__meta-avatar {
+    flex: none;
+    display: flex;
+    align-items: center;
+  }
+  .cd-list__meta-content {
+    flex: 1;
+    min-inline-size: 0;
+  }
+  .cd-list__meta-title {
+    color: var(--cd-list-item-color);
+    font-weight: var(--cd-font-weight-medium, 500);
+    line-height: 1.4;
+  }
+  .cd-list__meta-description {
+    color: var(--cd-list-header-color);
+    font-size: var(--cd-font-size-small, 12px);
+    line-height: 1.5;
+    margin-block-start: 2px;
+  }
+</style>

package/src/list/context.ts

@@ -0,0 +1,39 @@
+import { getContext, setContext } from 'svelte';
+import type { ListKey } from '@chenzy-design/core';
+
+/**
+ * List context — exposes selectable state to declarative <List.Item> children.
+ * Getters keep reactivity to the parent List's props (reading a snapshot would
+ * freeze the initial value). No mutable state stored here; selection toggling
+ * goes through the parent's command (which calls the controlled onSelectionChange
+ * — red line #1: never writes back to selectedKeys).
+ */
+export interface ListContext {
+  /** Whether selectable is enabled (single|multiple). */
+  getSelectable: () => false | 'single' | 'multiple';
+  /** Whether row `key` is currently selected. */
+  isSelected: (key: ListKey) => boolean;
+  /** Request a selection toggle for row `key` (fires onSelectionChange only). */
+  toggle: (key: ListKey, shiftKey: boolean) => void;
+  /** Row vertical padding size class suffix. */
+  getSize: () => 'small' | 'default' | 'large';
+  /**
+   * roving tabindex (pure derived): focused row / first DOM row is 0, others -1.
+   * Red line #2: read-only during render, never writes parent $state.
+   */
+  rowTabindex: (key: ListKey) => 0 | -1;
+  /** Row keydown: ↑↓ roving + Home/End + PageUp/Down (imperative focus()). */
+  onRowKeydown: (event: KeyboardEvent, key: ListKey) => void;
+  /** Sync focusedRowKey when a row gains focus. */
+  onRowFocus: (key: ListKey) => void;
+}
+
+const KEY = Symbol('cd-list');
+
+export function setListContext(ctx: ListContext): void {
+  setContext(KEY, ctx);
+}
+
+export function getListContext(): ListContext | undefined {
+  return getContext<ListContext | undefined>(KEY);
+}

package/src/list/index.ts

@@ -0,0 +1,21 @@
+import List_ from './List.svelte';
+import ListItem_ from './ListItem.svelte';
+import ListMeta from './ListMeta.svelte';
+
+// List.Item 挂 Meta 子组件（List.Item.Meta），List 挂 Item（及 Item.Meta 镜像）。
+const ListItem: typeof ListItem_ & { Meta: typeof ListMeta } = Object.assign(ListItem_, {
+  Meta: ListMeta,
+});
+
+export const List: typeof List_ & {
+  Item: typeof ListItem;
+  Meta: typeof ListMeta;
+} = Object.assign(List_, { Item: ListItem, Meta: ListMeta });
+
+export { ListItem, ListMeta };
+export { meta as listMeta } from './meta.js';
+export {
+  getListContext,
+  setListContext,
+  type ListContext,
+} from './context.js';

package/src/list/meta.ts

@@ -0,0 +1,99 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * List — see specs/components/show/List.spec.md
+ */
+export const meta = {
+  name: 'List',
+  category: 'show',
+  description:
+    '列表：数据驱动渲染（dataSource + renderItem），支持 header/footer（string 或 Snippet）、bordered 外框、split 行间分隔线、loading 骨架/spinner 与空态（默认 Empty）。泛型组件。',
+  exports: ['List', 'ListItem', 'ListMeta'],
+  subComponents: ['List.Item', 'List.Item.Meta', 'List.Meta'],
+  props: [
+    { name: 'dataSource', type: 'T[]', default: '[]', desc: '列表数据数组' },
+    {
+      name: 'renderItem',
+      type: 'Snippet<[item: T, index: number]>',
+      default: 'undefined',
+      desc: '行渲染 Snippet',
+    },
+    {
+      name: 'rowKey',
+      type: 'string|((item: T) => string|number)',
+      default: "'key'",
+      desc: '行唯一标识，用于 each key',
+    },
+    { name: 'size', type: "'small'|'default'|'large'", default: "'default'", desc: '行内边距尺寸' },
+    { name: 'bordered', type: 'boolean', default: 'false', desc: '外层边框 + 圆角' },
+    { name: 'split', type: 'boolean', default: 'true', desc: '行间分隔线' },
+    { name: 'header', type: 'string|Snippet', default: 'undefined', desc: '头部内容' },
+    { name: 'footer', type: 'string|Snippet', default: 'undefined', desc: '底部内容' },
+    { name: 'loading', type: 'boolean', default: 'false', desc: '加载态，覆盖 body' },
+    { name: 'loadingSkeleton', type: 'boolean', default: 'false', desc: 'loading 时用骨架行替代 spinner' },
+    { name: 'skeletonCount', type: 'number', default: '3', desc: '骨架占位行数' },
+    {
+      name: 'emptyContent',
+      type: 'string|Snippet',
+      default: 'undefined',
+      desc: '空数据展示内容，默认内置 Empty',
+    },
+    { name: 'grid', type: 'number | { column?: number; gutter?: number }', default: 'undefined', desc: '网格布局列数/间距' },
+    { name: 'loadMore', type: 'Snippet', default: 'undefined', desc: '自定义底部加载区' },
+    { name: 'onLoadMore', type: '() => void', default: 'undefined', desc: '内置加载更多按钮回调' },
+    { name: 'loadingMore', type: 'boolean', default: 'false', desc: '内置按钮 loading 态' },
+    { name: 'hasMore', type: 'boolean', default: 'false', desc: '是否还有更多数据' },
+    { name: 'pagination', type: 'false | { pageSize?, current?, defaultCurrent?, onChange? }', default: 'undefined', desc: '分页（切片当页，与 loadMore 互斥优先）' },
+    { name: 'virtualized', type: 'false | { itemSize?: number|"auto"; estimatedItemSize?: number; height: number|string; overscan?: number }', default: 'false', desc: '虚拟化：仅渲染视口内行，定高/动态测高，复用 core 区间数学（与 grid/pagination 互斥，优先生效）' },
+    { name: 'selectable', type: "false | 'single' | 'multiple'", default: 'false', desc: '行可选模式：单选/多选（listbox/option 语义）' },
+    { name: 'selectedKeys', type: '(string|number)[]', default: 'undefined', desc: '受控选中 key 集合（不回写，仅 onSelectionChange 回调）' },
+    { name: 'defaultSelectedKeys', type: '(string|number)[]', default: '[]', desc: '非受控初始选中 key 集合' },
+    { name: 'onSelectionChange', type: '(keys, { item, key, selected }) => void', default: 'undefined', desc: '选中态变更回调（受控/非受控均触发）' },
+    { name: 'children', type: 'Snippet', default: 'undefined', desc: '声明式用法：内嵌 <List.Item>（不传 dataSource 时生效）' },
+    { name: 'class', type: 'string', default: "''", desc: '根类名透传' },
+  ],
+  capabilities: ['data-render', 'pagination', 'load-more', 'virtualized', 'grid', 'selectable', 'declarative-items', 'empty/loading-state'],
+  methods: [
+    { name: 'scrollToIndex', type: "(index: number, opts?: { align?: 'start'|'center'|'end' }) => void", desc: '虚拟化模式命令式滚动到指定索引项' },
+  ],
+  events: [
+    { name: 'onSelectionChange', payload: '(keys, { item, key, selected })', desc: 'selectable 选中态变更' },
+  ],
+  slots: [
+    { name: 'renderItem', desc: '行渲染（item, index）' },
+    { name: 'header', desc: '头部 Snippet（与 header string 二选一）' },
+    { name: 'footer', desc: '底部 Snippet' },
+    { name: 'emptyContent', desc: '空态 Snippet' },
+    { name: 'children', desc: '声明式 <List.Item> 子项（不传 dataSource 时）' },
+  ],
+  a11y: {
+    role: 'list',
+    focusable: false,
+    notes: [
+      'ul/li 原生列表语义；selectable 时容器 role=listbox（multiple 加 aria-multiselectable），行 role=option + aria-selected',
+      'selectable 行 tabindex=0，Space/Enter 切换选中；multiple 支持 shift 连选',
+      'loading 时根容器 aria-busy=true',
+      '骨架行 aria-hidden=true，spinner aria-hidden=true',
+      '虚拟化行带 aria-setsize/aria-posinset',
+    ],
+  },
+  tokens: [
+    '--cd-list-bg',
+    '--cd-list-border',
+    '--cd-list-radius',
+    '--cd-list-item-padding',
+    '--cd-list-item-padding-small',
+    '--cd-list-split-color',
+    '--cd-list-header-color',
+    '--cd-list-item-color',
+    '--cd-radius-full',
+    '--cd-radius-small',
+    '--cd-color-primary',
+  ],
+  examples: [
+    {
+      title: '基础',
+      code:
+        '{#snippet item(d)}<span>{d.title}</span>{/snippet}\n<List dataSource={data} renderItem={item} bordered />',
+    },
+  ],
+} as const;

package/src/locale-provider/LocaleProvider.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+  import { setContext } from 'svelte';
+  import type { Snippet } from 'svelte';
+  import {
+    createLocale,
+    resolveLocale,
+    mergeLocale,
+    en_US,
+    type LocaleApi,
+    type Direction,
+    type CreateLocaleOptions,
+  } from '@chenzy-design/locale';
+  import type { Locale } from '@chenzy-design/locale';
+  import { LOCALE_CONTEXT_KEY, type LocaleContextValue } from './context.js';
+  import { getLocaleContext } from './index.js';
+
+  interface Props {
+    /**
+     * 语言包对象，或内置/已注册的字符串码（如 'zh_CN' / 'en-US'）。
+     * 字符串码经 registerLocale 注册表 + 内置包查表解析；未知码回退 en_US。
+     */
+    locale: Locale | string;
+    /** 缺失 key 回退包，默认 createLocale 内部用 en_US。 */
+    fallback?: Locale;
+    /** 文本方向，默认 'auto'（按 locale.rtl 推断）。 */
+    direction?: Direction | 'auto';
+    /**
+     * 嵌套时是否深合并父级 LocaleProvider 的语言包（子覆盖父，未覆盖继承父）。
+     * 默认 true；设 false 则整体替换，仅用本级语言包。
+     */
+    inherit?: boolean;
+    /** 默认 IANA 时区（如 'Asia/Shanghai'）注入 formatDate；未设时继承父级。 */
+    timeZone?: string;
+    /** 默认 ISO 4217 货币（如 'CNY'）用于 currency 风格 formatNumber；未设时继承父级。 */
+    currency?: string;
+    /** locale/direction 变化时的通知回调（受控，不回写）。 */
+    onLocaleChange?: (info: { locale: string; direction: Direction }) => void;
+    children?: Snippet<
+      [
+        {
+          locale: string;
+          t: LocaleApi['t'];
+          formatDate: LocaleApi['formatDate'];
+          formatNumber: LocaleApi['formatNumber'];
+          direction: Direction;
+        },
+      ]
+    >;
+  }
+
+  let {
+    locale,
+    fallback,
+    direction = 'auto',
+    inherit = true,
+    timeZone,
+    currency,
+    onLocaleChange,
+    children,
+  }: Props = $props();
+
+  // 最近的父级 LocaleProvider 上下文（初始化期读一次）；用于 inherit 深合并与配置继承。
+  const parent = getLocaleContext();
+
+  // 解析本级语言包：字符串码经注册表/内置查表，未知码回退 en_US；对象原样使用。
+  // 红线 #2：resolveLocale / mergeLocale 为 @chenzy-design/locale 的纯函数。
+  const resolved = $derived.by<Locale>(() => {
+    const own = resolveLocale(locale) ?? en_US;
+    // inherit：深合并父级生效包作基底，子覆盖父、未覆盖继承父。
+    return inherit && parent ? (mergeLocale(parent.resolved, own) as Locale) : own;
+  });
+
+  // 时区/货币：本级未设时继承父级生效值（仅 inherit 时；否则只用本级）。
+  const effTimeZone = $derived(timeZone ?? (inherit ? parent?.timeZone : undefined));
+  const effCurrency = $derived(currency ?? (inherit ? parent?.currency : undefined));
+
+  // 派生 LocaleApi：依赖变化时重建（Intl 缓存随之重置，可接受）。
+  // exactOptionalPropertyTypes 下条件构造 options，避免给可选属性传 undefined。
+  const api = $derived.by<LocaleApi>(() => {
+    const options: CreateLocaleOptions = { locale: resolved, direction };
+    if (fallback) options.fallback = fallback;
+    if (effTimeZone) options.timeZone = effTimeZone;
+    if (effCurrency) options.currency = effCurrency;
+    return createLocale(options);
+  });
+
+  // setContext 注入带 getter 的稳定引用对象，使后代 getContext 读到最新值。
+  // 红线 #1：locale 受控，仅注入不回写。resolved/timeZone/currency 供子级 inherit 用。
+  setContext<LocaleContextValue>(LOCALE_CONTEXT_KEY, {
+    get current(): LocaleApi {
+      return api;
+    },
+    get resolved(): Locale {
+      return resolved;
+    },
+    get timeZone(): string | undefined {
+      return effTimeZone;
+    },
+    get currency(): string | undefined {
+      return effCurrency;
+    },
+  });
+
+  // 红线 #3：$effect 只调通知回调，无 DOM/几何操作。首次 mount 也会触发一次（payload 为初始 locale，可接受）。
+  $effect(() => {
+    onLocaleChange?.({ locale: api.code, direction: api.direction });
+  });
+</script>
+
+{#if children}{@render children({ locale: api.code, t: api.t, formatDate: api.formatDate, formatNumber: api.formatNumber, direction: api.direction })}{/if}

package/src/locale-provider/context.ts

@@ -0,0 +1,22 @@
+import type { Locale, LocaleApi } from '@chenzy-design/locale';
+
+/** Svelte context key shared by LocaleProvider 与（未来的）ConfigProvider。 */
+export const LOCALE_CONTEXT_KEY = Symbol('cd-locale');
+
+/**
+ * 注入到 context 的对象。`current` 是消费端读的 LocaleApi（getter，随语言切换更新）；
+ * `resolved`/`timeZone`/`currency` 供嵌套 LocaleProvider 做 inherit 深合并与配置继承，
+ * 消费组件无需关心。
+ */
+export interface LocaleContextValue {
+  /** 最近注入的 LocaleApi（getter，渲染期重新读取拿到最新值）。 */
+  readonly current: LocaleApi;
+  /** 当前生效的完整语言包对象，供子级 inherit 深合并的父基底。 */
+  readonly resolved: Locale;
+  /** 当前生效的默认时区，供子级未显式设置时继承。 */
+  readonly timeZone: string | undefined;
+  /** 当前生效的默认货币，供子级未显式设置时继承。 */
+  readonly currency: string | undefined;
+}
+
+export type { Locale, LocaleApi };

package/src/locale-provider/index.ts

@@ -0,0 +1,21 @@
+import { getContext } from 'svelte';
+import { LOCALE_CONTEXT_KEY, type LocaleContextValue } from './context.js';
+
+export { default as LocaleProvider } from './LocaleProvider.svelte';
+export {
+  LOCALE_CONTEXT_KEY,
+  type LocaleApi,
+  type LocaleContextValue,
+} from './context.js';
+export { meta as localeProviderMeta } from './meta.js';
+
+/**
+ * 读取最近 LocaleProvider 注入的上下文值。
+ * 约束：getContext 只能在组件初始化期调用，故此 helper 必须在消费组件的
+ * `<script>` 顶层（初始化期）调用，返回对象的 `current` 持有最新 LocaleApi。
+ */
+export function getLocaleContext(): LocaleContextValue | undefined {
+  return getContext(LOCALE_CONTEXT_KEY);
+}
+
+export { useLocale } from './use-locale.js';