@chenzy-design/svelte 0.3.0 → 0.4.1

package/dist/pincode/PinCode.svelte

@@ -0,0 +1,348 @@
+<!--
+  PinCode — see specs/components/input/PinCode.spec.md
+  分格验证码 / OTP：N 个受控单字符输入格的编排器。跨格键盘（←→/Backspace/Delete）、
+  自动跳格、整串粘贴分发（遇非法字符停止）、受控/非受控、组合态过滤，全部委托
+  @chenzy-design/core 的纯函数。单格复用 Input 家族的填充式外观 token（--cd-color-input-*）。
+  a11y 增强（超越 Semi）：root role=group + aria-label；每格 aria-label 位次「第 N 位，共 M 位」、
+  autoComplete="one-time-code"、inputMode 随 format、maxlength=1。
+-->
+<script lang="ts">
+  import { useId } from '@chenzy-design/core';
+  import {
+    validateChar,
+    inputModeForFormat,
+    toValueList,
+    fromValueList,
+    isComplete,
+    completeSingleInput,
+    pinCodeHandleKeyDown,
+    distributePaste,
+    type PinCodeFormat,
+  } from '@chenzy-design/core';
+  import { useLocale } from '../locale-provider/index.js';
+
+  type Size = 'small' | 'default' | 'large';
+  type Status = 'default' | 'warning' | 'error';
+
+  interface Props {
+    /** 受控值。整串验证码字符串（如 "123456"），内部拆到各格；配合 onChange。 */
+    value?: string;
+    /** 非受控初始值，仅初始化时拆分。 */
+    defaultValue?: string;
+    /** 验证码位数（格数）。 */
+    count?: number;
+    /** 单字符可输入范围：number=纯数字 / mixed=数字+字母 / RegExp 逐字符 test / 函数逐字符判定。 */
+    format?: PinCodeFormat;
+    /** 每格尺寸。 */
+    size?: Size;
+    /** 禁用全部格。 */
+    disabled?: boolean;
+    /**
+     * 挂载时聚焦第一格。默认 true（对齐 Semi）：验证码场景用户几乎总是立即输入，
+     * 自动聚焦第一格符合预期；如需关闭传 autoFocus={false}。
+     */
+    autoFocus?: boolean;
+    /** 表单字段名，透传隐藏聚合 input 提交整串值。 */
+    name?: string;
+    /** 根容器 id，关联 aria-labelledby；不传自动生成。 */
+    id?: string;
+    /** 无可视标签时分组的辅助名（i18n 默认）。 */
+    ariaLabel?: string;
+    /** 外部可视 label 的 id，关联为分组名（优先于 ariaLabel）。 */
+    ariaLabelledby?: string;
+    /** 校验态，透传各格边框语义。 */
+    status?: Status;
+    /** 根容器类名。 */
+    className?: string;
+    /** 根容器内联样式。 */
+    style?: string;
+    /** 任一格值变化即触发，回传各格拼接整串（含清空）。 */
+    onChange?: (value: string) => void;
+    /** 最后一格填入完成时触发一次，回传完整验证码；同时 blur 末格。 */
+    onComplete?: (value: string) => void;
+  }
+
+  let {
+    value = $bindable(),
+    defaultValue = '',
+    count = 6,
+    format = 'number',
+    size = 'default',
+    disabled = false,
+    autoFocus = true,
+    name,
+    id,
+    ariaLabel,
+    ariaLabelledby,
+    status = 'default',
+    className,
+    style,
+    onChange,
+    onComplete,
+  }: Props = $props();
+
+  const loc = useLocale();
+  const autoId = useId('cd-pincode');
+  const rootId = $derived(id ?? autoId);
+
+  const isControlled = $derived(value !== undefined);
+  // 非受控内部值以整串字符串承载（受控时不写此 state，依赖外部回写）。
+  // 仅捕获挂载时的 defaultValue 初值（对齐 Input/Rating 的非受控范式）。
+  let inner = $state(getInitialValue());
+
+  function getInitialValue(): string {
+    return defaultValue;
+  }
+  const currentStr = $derived(isControlled ? (value ?? '') : inner);
+  const cells = $derived(toValueList(currentStr, count));
+
+  const inputMode = $derived(inputModeForFormat(format));
+  const rtl = $derived(loc().direction === 'rtl');
+  const resolvedAriaLabel = $derived(ariaLabel ?? loc().t('PinCode.ariaLabel'));
+
+  const cls = $derived(
+    ['cd-pincode', `cd-pincode--${size}`, `cd-pincode--${status}`, disabled && 'cd-pincode--disabled', className]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  // 各格 DOM 引用（供 focus / blur / 跳格）。普通数组簿记（非 $state，避免 effect 自循环）。
+  const inputEls: (HTMLInputElement | undefined)[] = [];
+
+  function setCells(next: string[]) {
+    const str = fromValueList(next);
+    if (!isControlled) inner = str;
+    onChange?.(str);
+  }
+
+  function focusCell(index: number, selectEnd = true) {
+    const el = inputEls[Math.max(0, Math.min(count - 1, index))];
+    if (!el) return;
+    el.focus();
+    if (selectEnd) {
+      // 将光标置于字符后（若有）。
+      const len = el.value.length;
+      try {
+        el.setSelectionRange(len, len);
+      } catch {
+        // number/email 类型不支持 setSelectionRange；text 恒支持，忽略即可。
+      }
+    }
+  }
+
+  function blurCell(index: number) {
+    inputEls[Math.max(0, Math.min(count - 1, index))]?.blur();
+  }
+
+  // —— 实例方法（供 bind:this 暴露）——
+  export function focus(index = 0): void {
+    focusCell(index);
+  }
+  export function blur(index = 0): void {
+    blurCell(index);
+  }
+
+  // 组合态：中文候选期间不写入。逐格独立追踪。
+  let composingIndex = $state<number | null>(null);
+
+  function handleInput(index: number, e: Event & { currentTarget: HTMLInputElement }) {
+    const el = e.currentTarget;
+    if (composingIndex === index) return; // 组合中，等 compositionend
+    // 取本次输入的最后一个合法字符（处理粘贴/快速输入落到 input 事件的情况由 onpaste 兜底）。
+    const raw = el.value;
+    const chars = [...raw];
+    const char = chars[chars.length - 1] ?? '';
+    if (!char || !validateChar(char, format)) {
+      // 非法字符：回滚显示为当前格既有值。
+      el.value = cells[index] ?? '';
+      return;
+    }
+    const r = completeSingleInput(cells, count, index, char);
+    setCells(r.list);
+    if (r.completed) {
+      // 填满：blur 末格并触发 onComplete。
+      blurCell(count - 1);
+      onComplete?.(fromValueList(r.list));
+    } else {
+      focusCell(r.nextIndex);
+    }
+  }
+
+  function handleKeydown(index: number, e: KeyboardEvent) {
+    if (composingIndex === index) return;
+    const action = pinCodeHandleKeyDown(e.key, index, count, rtl);
+    if (action.type === 'none') return;
+    e.preventDefault();
+    if (action.type === 'focus') {
+      focusCell(action.index);
+    } else {
+      // clear：清空当前格并移动焦点。
+      const next = toValueList(currentStr, count);
+      next[action.index] = '';
+      setCells(next);
+      focusCell(action.nextIndex);
+    }
+  }
+
+  function handlePaste(index: number, e: ClipboardEvent) {
+    const text = e.clipboardData?.getData('text') ?? '';
+    if (!text) return;
+    e.preventDefault(); // 防双写
+    const r = distributePaste(cells, count, index, text, format);
+    if (r.written === 0) return;
+    setCells(r.list);
+    if (r.completed) {
+      blurCell(count - 1);
+      onComplete?.(fromValueList(r.list));
+    } else {
+      focusCell(r.nextIndex);
+    }
+  }
+
+  function handleCompositionStart(index: number) {
+    composingIndex = index;
+  }
+
+  function handleCompositionEnd(index: number, e: Event & { currentTarget: HTMLInputElement }) {
+    composingIndex = null;
+    // 组合结束后按 input 逻辑重新处理最后落定的字符。
+    handleInput(index, e as Event & { currentTarget: HTMLInputElement });
+  }
+
+  function handleFocus(e: FocusEvent & { currentTarget: HTMLInputElement }) {
+    // 聚焦时全选，便于覆盖输入。
+    e.currentTarget.select();
+  }
+
+  // autoFocus：命令式聚焦第一格一次（红线 #3，SSR 安全，延后到下一帧）。
+  $effect(() => {
+    if (!autoFocus || disabled) return;
+    const el = inputEls[0];
+    if (!el) return;
+    const raf = requestAnimationFrame(() => el.focus());
+    return () => cancelAnimationFrame(raf);
+  });
+
+  function cellLabel(index: number): string {
+    return loc().t('PinCode.cellAriaLabel', {
+      index: loc().formatNumber(index + 1),
+      count: loc().formatNumber(count),
+    });
+  }
+
+  const aggregateValue = $derived(fromValueList(cells));
+</script>
+
+<div
+  id={rootId}
+  class={cls}
+  role="group"
+  aria-label={ariaLabelledby ? undefined : resolvedAriaLabel}
+  aria-labelledby={ariaLabelledby}
+  aria-disabled={disabled || undefined}
+  {style}
+>
+  {#if name}<input type="hidden" {name} value={aggregateValue} />{/if}
+
+  {#each cells as cell, i (i)}
+    <input
+      bind:this={inputEls[i]}
+      class="cd-pincode__cell"
+      class:cd-pincode__cell--warning={status === 'warning'}
+      class:cd-pincode__cell--error={status === 'error'}
+      type="text"
+      inputmode={inputMode}
+      autocomplete="one-time-code"
+      maxlength="1"
+      value={cell}
+      {disabled}
+      aria-label={cellLabel(i)}
+      aria-invalid={status === 'error' || undefined}
+      oninput={(e) => handleInput(i, e)}
+      onkeydown={(e) => handleKeydown(i, e)}
+      onpaste={(e) => handlePaste(i, e)}
+      onfocus={handleFocus}
+      oncompositionstart={() => handleCompositionStart(i)}
+      oncompositionend={(e) => handleCompositionEnd(i, e)}
+    />
+  {/each}
+</div>
+
+<style>
+  .cd-pincode {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cd-pincode-gap-default);
+  }
+  .cd-pincode--small {
+    gap: var(--cd-pincode-gap-small);
+  }
+  .cd-pincode--large {
+    gap: var(--cd-pincode-gap-large);
+  }
+  /* 单格：复用 Input 家族填充式外观 token（边框 / 背景 / 聚焦 / 校验态），正方形居中。 */
+  .cd-pincode__cell {
+    box-sizing: border-box;
+    inline-size: var(--cd-pincode-cell-width-default);
+    block-size: var(--cd-height-input-wrapper-default);
+    margin: 0;
+    padding: 0;
+    text-align: var(--cd-pincode-cell-text-align);
+    font-size: var(--cd-pincode-cell-font-size);
+    color: var(--cd-color-input-default-text-default);
+    background: var(--cd-color-input-default-bg-default);
+    border: var(--cd-width-input-wrapper-border) solid var(--cd-color-input-default-border-default);
+    border-radius: var(--cd-radius-input-wrapper);
+    outline: none;
+    transition:
+      background-color var(--cd-transition-duration-input-bg)
+        var(--cd-transition-function-input-bg) var(--cd-transition-delay-input-bg),
+      border var(--cd-transition-duration-input-border)
+        var(--cd-transition-function-input-border) var(--cd-transition-delay-input-border);
+  }
+  .cd-pincode--small .cd-pincode__cell {
+    inline-size: var(--cd-pincode-cell-width-small);
+    block-size: var(--cd-height-input-wrapper-small);
+  }
+  .cd-pincode--large .cd-pincode__cell {
+    inline-size: var(--cd-pincode-cell-width-large);
+    block-size: var(--cd-height-input-wrapper-large);
+  }
+  .cd-pincode__cell:hover:not(:disabled):not(:focus) {
+    background: var(--cd-color-input-default-bg-hover);
+    border-color: var(--cd-color-input-default-border-hover);
+  }
+  .cd-pincode__cell:focus {
+    background: var(--cd-color-input-default-bg-focus);
+    border-color: var(--cd-color-input-default-border-focus);
+  }
+  /* warning / error —— 对齐 Input：浅色状态底 + 同色描边 */
+  .cd-pincode__cell--warning {
+    background: var(--cd-color-input-warning-bg-default);
+    border-color: var(--cd-color-input-warning-border-default);
+  }
+  .cd-pincode__cell--warning:focus {
+    background: var(--cd-color-input-warning-bg-focus);
+    border-color: var(--cd-color-input-warning-border-focus);
+  }
+  .cd-pincode__cell--error {
+    background: var(--cd-color-input-danger-bg-default);
+    border-color: var(--cd-color-input-danger-border-default);
+  }
+  .cd-pincode__cell--error:focus {
+    background: var(--cd-color-input-danger-bg-focus);
+    border-color: var(--cd-color-input-danger-border-focus);
+  }
+  .cd-pincode--disabled .cd-pincode__cell,
+  .cd-pincode__cell:disabled {
+    background: var(--cd-color-input-disabled-bg-default);
+    color: var(--cd-color-input-disabled-text-default);
+    -webkit-text-fill-color: var(--cd-color-input-disabled-text-default);
+    cursor: not-allowed;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .cd-pincode__cell {
+      transition: none;
+    }
+  }
+</style>

package/dist/pincode/PinCode.svelte.d.ts

@@ -0,0 +1,47 @@
+import { type PinCodeFormat } from '@chenzy-design/core';
+type Size = 'small' | 'default' | 'large';
+type Status = 'default' | 'warning' | 'error';
+interface Props {
+    /** 受控值。整串验证码字符串（如 "123456"），内部拆到各格；配合 onChange。 */
+    value?: string;
+    /** 非受控初始值，仅初始化时拆分。 */
+    defaultValue?: string;
+    /** 验证码位数（格数）。 */
+    count?: number;
+    /** 单字符可输入范围：number=纯数字 / mixed=数字+字母 / RegExp 逐字符 test / 函数逐字符判定。 */
+    format?: PinCodeFormat;
+    /** 每格尺寸。 */
+    size?: Size;
+    /** 禁用全部格。 */
+    disabled?: boolean;
+    /**
+     * 挂载时聚焦第一格。默认 true（对齐 Semi）：验证码场景用户几乎总是立即输入，
+     * 自动聚焦第一格符合预期；如需关闭传 autoFocus={false}。
+     */
+    autoFocus?: boolean;
+    /** 表单字段名，透传隐藏聚合 input 提交整串值。 */
+    name?: string;
+    /** 根容器 id，关联 aria-labelledby；不传自动生成。 */
+    id?: string;
+    /** 无可视标签时分组的辅助名（i18n 默认）。 */
+    ariaLabel?: string;
+    /** 外部可视 label 的 id，关联为分组名（优先于 ariaLabel）。 */
+    ariaLabelledby?: string;
+    /** 校验态，透传各格边框语义。 */
+    status?: Status;
+    /** 根容器类名。 */
+    className?: string;
+    /** 根容器内联样式。 */
+    style?: string;
+    /** 任一格值变化即触发，回传各格拼接整串（含清空）。 */
+    onChange?: (value: string) => void;
+    /** 最后一格填入完成时触发一次，回传完整验证码；同时 blur 末格。 */
+    onComplete?: (value: string) => void;
+}
+declare const PinCode: import("svelte").Component<Props, {
+    focus: (index?: number) => void;
+    blur: (index?: number) => void;
+}, "value">;
+type PinCode = ReturnType<typeof PinCode>;
+export default PinCode;
+//# sourceMappingURL=PinCode.svelte.d.ts.map

package/dist/pincode/PinCode.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PinCode.svelte.d.ts","sourceRoot":"","sources":["../../src/pincode/PinCode.svelte.ts"],"names":[],"mappings":"AAIA,OAAO,EASH,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAI7B,KAAK,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAC1C,KAAK,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE9C,UAAU,KAAK;IACb,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,YAAY;IACZ,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,aAAa;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,wCAAwC;IACxC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAiMH,QAAA,MAAM,OAAO;+BA/GiB,IAAI;8BAGL,IAAI;WA4GoB,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/pincode/index.d.ts

@@ -0,0 +1,3 @@
+export { default as PinCode } from './PinCode.svelte';
+export { meta as pinCodeMeta } from './meta.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/pincode/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pincode/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,IAAI,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/pincode/index.js

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

package/dist/pincode/meta.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md 与 specs/components/input/PinCode.spec.md §10。
+ */
+export declare const meta: {
+    readonly name: "PinCode";
+    readonly category: "input";
+    readonly stage: "M2";
+    readonly semiEquivalent: "PinCode";
+    readonly description: "分格验证码 / OTP 输入组件：N 个受控单字符输入格，逐格填入、自动跳格、整串粘贴自动分发，支持数字/混合/RegExp/函数四种字符校验。";
+    readonly props: readonly [{
+        readonly name: "value";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "受控值；整串验证码，配合 onChange";
+    }, {
+        readonly name: "defaultValue";
+        readonly type: "string";
+        readonly default: "''";
+        readonly desc: "非受控初始值，仅初始化拆分";
+    }, {
+        readonly name: "count";
+        readonly type: "number";
+        readonly default: "6";
+        readonly desc: "验证码位数（格数）";
+    }, {
+        readonly name: "format";
+        readonly type: "'number' | 'mixed' | RegExp | ((char: string) => boolean)";
+        readonly default: "'number'";
+        readonly desc: "单字符可输入范围；number→inputMode=numeric";
+    }, {
+        readonly name: "size";
+        readonly type: "'small' | 'default' | 'large'";
+        readonly default: "default";
+        readonly desc: "每格尺寸";
+    }, {
+        readonly name: "disabled";
+        readonly type: "boolean";
+        readonly default: "false";
+        readonly desc: "禁用全部格";
+    }, {
+        readonly name: "autoFocus";
+        readonly type: "boolean";
+        readonly default: "true";
+        readonly desc: "挂载聚焦第一格（对齐 Semi）；验证码场景通常立即输入，如需关闭传 autoFocus={false}";
+    }, {
+        readonly name: "name";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "表单字段名，透传隐藏聚合 input（超越 Semi：Semi 无表单聚合能力）";
+    }, {
+        readonly name: "id";
+        readonly type: "string";
+        readonly default: "自动生成";
+        readonly desc: "根容器 id（超越 Semi：本库 a11y 分组约定）";
+    }, {
+        readonly name: "ariaLabel";
+        readonly type: "string";
+        readonly default: "i18n 默认";
+        readonly desc: "无可视标签时分组辅助名（超越 Semi：Semi root 无 aria）";
+    }, {
+        readonly name: "ariaLabelledby";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "外部 label id，优先于 ariaLabel（超越 Semi：Semi root 无 aria）";
+    }, {
+        readonly name: "status";
+        readonly type: "'default' | 'warning' | 'error'";
+        readonly default: "default";
+        readonly desc: "校验态（超越 Semi：Semi 单格外观固定，无校验态）";
+    }, {
+        readonly name: "className";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "根容器类名";
+    }, {
+        readonly name: "style";
+        readonly type: "string";
+        readonly default: "undefined";
+        readonly desc: "根容器内联样式";
+    }, {
+        readonly name: "onChange";
+        readonly type: "(value: string) => void";
+        readonly default: "undefined";
+        readonly desc: "任一格变化触发，回传整串";
+    }, {
+        readonly name: "onComplete";
+        readonly type: "(value: string) => void";
+        readonly default: "undefined";
+        readonly desc: "填满末格触发一次，同时 blur 末格";
+    }];
+    readonly events: readonly [{
+        readonly name: "onChange";
+        readonly payload: "(value: string)";
+        readonly desc: "任一格值变化即触发（含清空）";
+    }, {
+        readonly name: "onComplete";
+        readonly payload: "(value: string)";
+        readonly desc: "最后一格填入完成时触发一次";
+    }];
+    readonly methods: readonly [{
+        readonly name: "focus";
+        readonly signature: "(index?: number) => void";
+        readonly desc: "聚焦第 index 格（默认 0）";
+    }, {
+        readonly name: "blur";
+        readonly signature: "(index?: number) => void";
+        readonly desc: "移出第 index 格焦点";
+    }];
+    readonly i18nKeys: readonly ["PinCode.ariaLabel", "PinCode.cellAriaLabel"];
+    readonly a11yPattern: "group-of-inputs";
+    readonly a11y: {
+        readonly role: "group";
+        readonly keyboard: readonly ["ArrowLeft/ArrowRight", "Backspace", "Delete", "Home", "End", "自动跳格"];
+        readonly notes: readonly ["root role=group + aria-label（i18n）或 aria-labelledby", "每格 aria-label 位次「第 N 位，共 M 位」", "每格 autoComplete=one-time-code（OTP 系统级填充，超越 Semi）", "inputMode 随 format（number→numeric）；maxlength=1", "status=error → 各格 aria-invalid；disabled → aria-disabled + 原生 disabled", "RTL：←→ 语义镜像；组合态（isComposing）不写入"];
+        readonly keyboardMap: {
+            readonly ArrowLeft: "上一格（首格不越界；RTL 镜像）";
+            readonly ArrowRight: "下一格（末格不越界；RTL 镜像）";
+            readonly Backspace: "清空当前格并回退";
+            readonly Delete: "清空当前格并前进";
+            readonly char: "合法单字符写入后自动前进；填满末格 blur + onComplete";
+            readonly paste: "从当前格起逐字符分发，遇非法字符停止";
+        };
+    };
+    readonly tokens: readonly ["--cd-pincode-gap-small", "--cd-pincode-gap-default", "--cd-pincode-gap-large", "--cd-pincode-cell-width-small", "--cd-pincode-cell-width-default", "--cd-pincode-cell-width-large", "--cd-pincode-cell-font-size", "--cd-pincode-cell-text-align"];
+    readonly examples: readonly [{
+        readonly title: "基础 6 位数字码";
+        readonly code: "<PinCode />";
+    }, {
+        readonly title: "4 位";
+        readonly code: "<PinCode count={4} />";
+    }, {
+        readonly title: "mixed 字母数字";
+        readonly code: "<PinCode format=\"mixed\" />";
+    }, {
+        readonly title: "受控";
+        readonly code: "<PinCode {value} onChange={(v) => (value = v)} />";
+    }, {
+        readonly title: "error 态";
+        readonly code: "<PinCode status=\"error\" />";
+    }, {
+        readonly title: "onComplete 提交";
+        readonly code: "<PinCode onComplete={(v) => submit(v)} />";
+    }];
+    readonly doNot: readonly ["不要写死格宽 / 颜色（用 token）", "不要漏单格 aria 位次"];
+};
+//# sourceMappingURL=meta.d.ts.map

package/dist/pincode/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/pincode/meta.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuFP,CAAC"}

package/dist/pincode/meta.js

@@ -0,0 +1,91 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * See specs/00-foundation/ai-friendly.spec.md 与 specs/components/input/PinCode.spec.md §10。
+ */
+export const meta = {
+    name: 'PinCode',
+    category: 'input',
+    stage: 'M2',
+    semiEquivalent: 'PinCode',
+    description: '分格验证码 / OTP 输入组件：N 个受控单字符输入格，逐格填入、自动跳格、整串粘贴自动分发，支持数字/混合/RegExp/函数四种字符校验。',
+    props: [
+        { name: 'value', type: 'string', default: 'undefined', desc: '受控值；整串验证码，配合 onChange' },
+        { name: 'defaultValue', type: 'string', default: "''", desc: '非受控初始值，仅初始化拆分' },
+        { name: 'count', type: 'number', default: '6', desc: '验证码位数（格数）' },
+        {
+            name: 'format',
+            type: "'number' | 'mixed' | RegExp | ((char: string) => boolean)",
+            default: "'number'",
+            desc: '单字符可输入范围；number→inputMode=numeric',
+        },
+        { name: 'size', type: "'small' | 'default' | 'large'", default: 'default', desc: '每格尺寸' },
+        { name: 'disabled', type: 'boolean', default: 'false', desc: '禁用全部格' },
+        {
+            name: 'autoFocus',
+            type: 'boolean',
+            default: 'true',
+            desc: '挂载聚焦第一格（对齐 Semi）；验证码场景通常立即输入，如需关闭传 autoFocus={false}',
+        },
+        { name: 'name', type: 'string', default: 'undefined', desc: '表单字段名，透传隐藏聚合 input（超越 Semi：Semi 无表单聚合能力）' },
+        { name: 'id', type: 'string', default: '自动生成', desc: '根容器 id（超越 Semi：本库 a11y 分组约定）' },
+        { name: 'ariaLabel', type: 'string', default: 'i18n 默认', desc: '无可视标签时分组辅助名（超越 Semi：Semi root 无 aria）' },
+        { name: 'ariaLabelledby', type: 'string', default: 'undefined', desc: '外部 label id，优先于 ariaLabel（超越 Semi：Semi root 无 aria）' },
+        { name: 'status', type: "'default' | 'warning' | 'error'", default: 'default', desc: '校验态（超越 Semi：Semi 单格外观固定，无校验态）' },
+        { name: 'className', type: 'string', default: 'undefined', desc: '根容器类名' },
+        { name: 'style', type: 'string', default: 'undefined', desc: '根容器内联样式' },
+        { name: 'onChange', type: '(value: string) => void', default: 'undefined', desc: '任一格变化触发，回传整串' },
+        { name: 'onComplete', type: '(value: string) => void', default: 'undefined', desc: '填满末格触发一次，同时 blur 末格' },
+    ],
+    events: [
+        { name: 'onChange', payload: '(value: string)', desc: '任一格值变化即触发（含清空）' },
+        { name: 'onComplete', payload: '(value: string)', desc: '最后一格填入完成时触发一次' },
+    ],
+    methods: [
+        { name: 'focus', signature: '(index?: number) => void', desc: '聚焦第 index 格（默认 0）' },
+        { name: 'blur', signature: '(index?: number) => void', desc: '移出第 index 格焦点' },
+    ],
+    i18nKeys: ['PinCode.ariaLabel', 'PinCode.cellAriaLabel'],
+    a11yPattern: 'group-of-inputs',
+    a11y: {
+        role: 'group',
+        keyboard: ['ArrowLeft/ArrowRight', 'Backspace', 'Delete', 'Home', 'End', '自动跳格'],
+        notes: [
+            'root role=group + aria-label（i18n）或 aria-labelledby',
+            '每格 aria-label 位次「第 N 位，共 M 位」',
+            "每格 autoComplete=one-time-code（OTP 系统级填充，超越 Semi）",
+            'inputMode 随 format（number→numeric）；maxlength=1',
+            'status=error → 各格 aria-invalid；disabled → aria-disabled + 原生 disabled',
+            'RTL：←→ 语义镜像；组合态（isComposing）不写入',
+        ],
+        keyboardMap: {
+            ArrowLeft: '上一格（首格不越界；RTL 镜像）',
+            ArrowRight: '下一格（末格不越界；RTL 镜像）',
+            Backspace: '清空当前格并回退',
+            Delete: '清空当前格并前进',
+            char: '合法单字符写入后自动前进；填满末格 blur + onComplete',
+            paste: '从当前格起逐字符分发，遇非法字符停止',
+        },
+    },
+    tokens: [
+        '--cd-pincode-gap-small',
+        '--cd-pincode-gap-default',
+        '--cd-pincode-gap-large',
+        '--cd-pincode-cell-width-small',
+        '--cd-pincode-cell-width-default',
+        '--cd-pincode-cell-width-large',
+        '--cd-pincode-cell-font-size',
+        '--cd-pincode-cell-text-align',
+    ],
+    examples: [
+        { title: '基础 6 位数字码', code: '<PinCode />' },
+        { title: '4 位', code: '<PinCode count={4} />' },
+        { title: 'mixed 字母数字', code: '<PinCode format="mixed" />' },
+        { title: '受控', code: '<PinCode {value} onChange={(v) => (value = v)} />' },
+        { title: 'error 态', code: '<PinCode status="error" />' },
+        { title: 'onComplete 提交', code: '<PinCode onComplete={(v) => submit(v)} />' },
+    ],
+    doNot: [
+        '不要写死格宽 / 颜色（用 token）',
+        '不要漏单格 aria 位次',
+    ],
+};