@chenzy-design/svelte 0.1.0

package/dist/form/Field.svelte

@@ -0,0 +1,492 @@
+<!--
+  Field — see specs/components/input/Form.spec.md
+  Single-field wrapper: label + required mark + error/extra text + a11y wiring.
+  Pulls field slices from the shared form context (read-only during render).
+-->
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { useId, type Rule, type ValidateTrigger } from '@chenzy-design/core';
+  import { getFormContext } from './context.js';
+  import { useLocale } from '../locale-provider/index.js';
+
+  type FieldStatus = 'default' | 'error' | 'warning';
+
+  interface ChildArgs {
+    /** Generic field value — always present, regardless of `valuePropName`. */
+    value: unknown;
+    onChange: (v: unknown) => void;
+    onBlur: () => void;
+    status: FieldStatus;
+    id: string;
+    /** id(s) of the field's error/warning/extra text, for the control's aria-describedby */
+    describedBy: string | undefined;
+    disabled: boolean;
+    /**
+     * whether this field is required (spec §138). Controls should expose it as
+     * `aria-required="true"` so the required semantic reaches screen readers —
+     * the visible star is `aria-hidden` and thus inaudible on its own.
+     */
+    required: boolean;
+    /**
+     * Convenience alias keyed by `valuePropName` (default 'value'), carrying the
+     * same value as `value`. Lets non-`value` controls (e.g. Checkbox/Switch use
+     * `checked`) destructure `{ checked, onChange }` directly from the snippet.
+     */
+    [key: string]: unknown;
+  }
+
+  interface Props {
+    field: string;
+    label?: string;
+    rules?: Rule[];
+    /** field-level initial value; overrides the container's initValues (spec §4.2 L79). */
+    initValue?: unknown;
+    required?: boolean;
+    /**
+     * externally forced validate status (spec §4.2 L81). A controlled DISPLAY
+     * state only — it never feeds the internal validation engine and is never
+     * written back (red line #1). When set it takes precedence over the
+     * internally computed status for visuals/aria.
+     */
+    validateStatus?: 'default' | 'warning' | 'error';
+    extraText?: string;
+    /**
+     * register & collect only, render no layout DOM (spec §4.2 L85 / §190). The
+     * control snippet is still rendered (so it can bind), but the label / status
+     * text / field wrapper chrome are skipped.
+     */
+    noStyle?: boolean;
+    /** number of columns this field spans inside a grid parent / Form.Section (spec §4.2 L86). */
+    span?: number;
+    /** pure value transform applied at collect/submit time (spec §4.2 L88). */
+    transform?: (value: unknown, values: Record<string, unknown>) => unknown;
+    /**
+     * Name of the control's value prop. Default 'value'. For boolean controls
+     * such as Checkbox/Switch pass 'checked'; the snippet then exposes a
+     * `checked` alias mirroring the field value.
+     */
+    valuePropName?: string;
+    /** names of fields this field's validation depends on (e.g. confirm → ['password']) */
+    dependencies?: string[];
+    /** field-level override of the form's validateTrigger (spec §4 L84). */
+    trigger?: ValidateTrigger | ValidateTrigger[];
+    /**
+     * 是否允许空字符串作为有效值（默认 false：空串当 undefined 处理，不触发 required 通过）。
+     * 设为 true 后空串参与 required 校验和值收集。
+     */
+    allowEmptyString?: boolean;
+    /**
+     * 字段值在存入 formState 前的转换函数（在 Field 层执行，不同于 transform 的提交时转换）。
+     * convert 的结果回写 formState，transform 的结果仅用于提交/收集，不回写。
+     */
+    convert?: (value: unknown) => unknown;
+    /**
+     * 组件卸载时保留字段状态（默认 false：卸载时清空字段值/错误/touched）。
+     * 设为 true 后卸载不清 formState，下次挂载时继承上次状态。
+     */
+    keepState?: boolean;
+    children?: Snippet<[ChildArgs]>;
+  }
+
+  let {
+    field,
+    label,
+    rules = [],
+    initValue,
+    required = false,
+    validateStatus,
+    extraText,
+    noStyle = false,
+    span,
+    transform,
+    valuePropName = 'value',
+    dependencies,
+    trigger,
+    allowEmptyString = false,
+    convert,
+    keepState = false,
+    children,
+  }: Props = $props();
+
+  const ctx = getFormContext();
+  if (!ctx) throw new Error('<Form.Field> must be used inside <Form>');
+  const { form, getFormState } = ctx;
+
+  const loc = useLocale();
+
+  const id = useId('cd-field');
+  const errorId = `${id}-error`;
+  const warningId = `${id}-warning`;
+  const extraId = `${id}-extra`;
+
+  // Register the field in the core registry (a plain Map, not Svelte-reactive),
+  // so this never feeds back into a render-read. Cleanup unregisters.
+  $effect(() => {
+    const effectiveRules = required ? [{ required: true } as Rule, ...rules] : rules;
+    const config: {
+      rules: Rule[];
+      label?: string;
+      initialValue?: unknown;
+      dependencies?: string[];
+      trigger?: ValidateTrigger | ValidateTrigger[];
+      transform?: (value: unknown, values: Record<string, unknown>) => unknown;
+    } = {
+      rules: effectiveRules,
+    };
+    if (label !== undefined) config.label = label;
+    if (initValue !== undefined) config.initialValue = initValue;
+    if (dependencies !== undefined) config.dependencies = dependencies;
+    if (trigger !== undefined) config.trigger = trigger;
+    if (transform !== undefined) config.transform = transform;
+    const unregister = form.registerField(field, config);
+    // spec §2 L26: a `mount` trigger validates once right after registration.
+    // Imperative one-shot (not a render read) so it cannot loop.
+    if (form.getFieldTrigger(field).includes('mount')) void form.validateField(field);
+    // keepState: when false (default), unregister clears field state on destroy.
+    // When true, we skip the cleanup so state persists for future mounts.
+    return keepState ? () => { /* preserve state — do not unregister */ } : unregister;
+  });
+
+  // Read-only slices derived from the bridged form state (render-safe getters).
+  const value = $derived(getFormState().values[field]);
+  const error = $derived(getFormState().errors[field]);
+  const warning = $derived(getFormState().warnings[field]);
+  const validating = $derived(getFormState().validating[field] === true);
+  const touched = $derived(getFormState().touched[field]);
+
+  // `validateStatus` is a controlled display override (spec §4.2 L81): it forces
+  // the visual status without touching the internal validation engine (red line
+  // #1 — never written back). When set, it wins over the computed status.
+  const forcedError = $derived(validateStatus === 'error');
+  const forcedWarning = $derived(validateStatus === 'warning');
+  const showError = $derived(forcedError || (error !== undefined && error !== ''));
+  // a warning only surfaces when there is no blocking error to show
+  const showWarning = $derived(
+    !showError && (forcedWarning || (warning !== undefined && warning !== '')),
+  );
+  const status = $derived<FieldStatus>(showError ? 'error' : showWarning ? 'warning' : 'default');
+
+  const showRequiredMark = $derived(ctx.getRequiredMark() && required);
+  const showExtra = $derived(
+    !showError && !showWarning && extraText !== undefined && extraText !== '',
+  );
+  const validatingText = $derived(loc().t('Form.validating'));
+
+  // resolved validation triggers for this field (own override → form default).
+  // Plain getters off the core registry (a non-reactive Map), read inside event
+  // handlers only — never during render, so no effect loop.
+  function triggers(): ValidateTrigger[] {
+    return form.getFieldTrigger(field);
+  }
+
+  function handleChange(v: unknown) {
+    // allowEmptyString: treat empty string as undefined unless explicitly allowed.
+    // This normalizes '' to undefined for required validation / collection.
+    const coerced = !allowEmptyString && v === '' ? undefined : v;
+    // convert: field-level value transform (applied before storing into formState).
+    const stored = convert !== undefined ? convert(coerced) : coerced;
+    const tr = triggers();
+    // Validate on change when 'change' is an active trigger AND the field is
+    // already "active": after a blur (touched) OR while an error is showing (so
+    // typing clears a submit error). Controls like Input have no blur hook to
+    // set `touched`, so the "showing error" path keeps submit errors clearable.
+    const active = touched === true || (error !== undefined && error !== '');
+    const validate = tr.includes('change') && active;
+    form.setFieldValue(field, stored, { validate });
+  }
+
+  function handleBlur() {
+    form.setFieldTouched(field);
+    // only validate on blur when 'blur' is an active trigger for this field.
+    if (triggers().includes('blur')) void form.validateField(field);
+  }
+
+  const describedBy = $derived(
+    // noStyle renders no status/extra elements, so there is nothing to point at
+    noStyle
+      ? undefined
+      : showError
+        ? errorId
+        : showWarning
+          ? warningId
+          : showExtra
+            ? extraId
+            : undefined,
+  );
+
+  const labelWidth = $derived(ctx.getLabelWidth());
+  const labelPosition = $derived(ctx.getLabelPosition());
+  const labelAlign = $derived(ctx.getLabelAlign());
+  const showValidateIcon = $derived(ctx.getShowValidateIcon());
+  const extraTextPosition = $derived(ctx.getExtraTextPosition?.() ?? 'bottom');
+  // label style: fixed width in `left` mode + text-align from labelAlign (§4 L60)
+  const labelStyle = $derived(
+    [
+      labelPosition === 'left' && labelWidth !== undefined
+        ? `inline-size:${typeof labelWidth === 'number' ? `${labelWidth}px` : labelWidth}`
+        : undefined,
+      `text-align:${labelAlign}`,
+    ]
+      .filter(Boolean)
+      .join(';'),
+  );
+
+  // inset：label 浮入控件，聚焦或有值时上浮变小（floating label）
+  const isInset = $derived(labelPosition === 'inset');
+  let focused = $state(false);
+  const hasValue = $derived(value !== undefined && value !== null && value !== '');
+  const labelFloated = $derived(focused || hasValue);
+
+  const cls = $derived(
+    [
+      'cd-form-field',
+      `cd-form-field--label-${labelPosition}`,
+      `cd-form-field--${status}`,
+      isInset && labelFloated && 'cd-form-field--floated',
+    ]
+      .filter(Boolean)
+      .join(' '),
+  );
+
+  // `span` (spec §4.2 L86): occupy N columns of a grid parent (e.g. Form.Section).
+  // Pure inline `grid-column` — inert when the parent isn't a grid.
+  const wrapStyle = $derived(span !== undefined ? `grid-column:span ${span}` : undefined);
+</script>
+
+{#if noStyle}
+  <!--
+    noStyle (spec §4.2 L85 / §190): register & collect only, render no layout
+    chrome. The control snippet is still rendered so it can bind to the field;
+    label / status text / wrapper DOM are skipped. `validateStatus`/error still
+    flow into `status` so a custom control can style itself.
+  -->
+  {@render children?.({
+    value,
+    [valuePropName]: value,
+    onChange: handleChange,
+    onBlur: handleBlur,
+    status,
+    id,
+    describedBy,
+    disabled: ctx.getDisabled(),
+    required,
+  })}
+{:else}
+<div class={cls} data-field={field} style={wrapStyle}>
+  {#if label !== undefined && !isInset}
+    <label
+      class="cd-form-field__label cd-form-field__label--align-{labelAlign}"
+      for={id}
+      style={labelStyle}
+    >
+      {#if showRequiredMark}<span aria-hidden="true" class="cd-form-field__required">*</span>{/if}
+      <span class="cd-form-field__label-text">{label}{ctx.getColon() ? '：' : ''}</span>
+    </label>
+  {/if}
+
+  <!-- inset 时 label 浮入控件容器内；focusin/focusout 驱动上浮 (红线 #3 命令式 DOM 事件) -->
+  <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+  <div
+    class="cd-form-field__control"
+    aria-describedby={describedBy}
+    onfocusin={isInset ? () => (focused = true) : undefined}
+    onfocusout={isInset ? () => (focused = false) : undefined}
+  >
+    {#if label !== undefined && isInset}
+      <label class="cd-form-field__inset-label" for={id}>
+        {#if showRequiredMark}<span aria-hidden="true" class="cd-form-field__required">*</span>{/if}
+        <span class="cd-form-field__label-text">{label}</span>
+      </label>
+    {/if}
+
+    {@render children?.({
+      value,
+      // alias keyed by valuePropName (e.g. `checked`); for the default 'value'
+      // this is the same key and a no-op spread. Pure object construction —
+      // no write-back, satisfies red line #1/#2.
+      [valuePropName]: value,
+      onChange: handleChange,
+      onBlur: handleBlur,
+      status,
+      id,
+      describedBy,
+      disabled: ctx.getDisabled(),
+      required,
+    })}
+
+    {#if validating}
+      <div class="cd-form-field__validating" aria-live="polite">
+        <span class="cd-form-field__spinner" aria-hidden="true"></span>
+        <span>{validatingText}</span>
+      </div>
+    {/if}
+
+    {#if showError}
+      <div id={errorId} role="alert" class="cd-form-field__error">
+        {#if showValidateIcon}
+          <svg
+            class="cd-form-field__status-icon"
+            viewBox="0 0 16 16"
+            width="14"
+            height="14"
+            aria-hidden="true"
+            focusable="false"
+          >
+            <path
+              fill="currentColor"
+              d="M8 1a7 7 0 1 0 0 14A7 7 0 0 0 8 1Zm-.75 3.5h1.5v5h-1.5v-5ZM8 12.25a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"
+            />
+          </svg>
+        {/if}
+        <span>{error}</span>
+      </div>
+    {:else if showWarning}
+      <div id={warningId} class="cd-form-field__warning">
+        {#if showValidateIcon}
+          <svg
+            class="cd-form-field__status-icon"
+            viewBox="0 0 16 16"
+            width="14"
+            height="14"
+            aria-hidden="true"
+            focusable="false"
+          >
+            <path
+              fill="currentColor"
+              d="M7.13 1.7a1 1 0 0 1 1.74 0l6.1 10.8A1 1 0 0 1 14.1 14H1.9a1 1 0 0 1-.87-1.5l6.1-10.8ZM7.25 6h1.5v4h-1.5V6ZM8 12.4a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"
+            />
+          </svg>
+        {/if}
+        <span>{warning}</span>
+      </div>
+    {:else if showExtra}
+      <div id={extraId} class="cd-form-field__extra" class:cd-form-field__extra--middle={extraTextPosition === 'middle'} class:cd-form-field__extra--bottom={extraTextPosition === 'bottom'}>{extraText}</div>
+    {/if}
+  </div>
+</div>
+{/if}
+
+<style>
+  .cd-form-field {
+    display: flex;
+    gap: var(--cd-form-label-gap, var(--cd-spacing-2));
+  }
+  .cd-form-field--label-top {
+    flex-direction: column;
+  }
+  .cd-form-field--label-left {
+    flex-direction: row;
+    align-items: flex-start;
+  }
+  .cd-form-field__label {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cd-spacing-1);
+    color: var(--cd-form-label-color, var(--cd-color-text-1));
+  }
+  /* labelAlign (§4 L60): justify the label's inline content within its box */
+  .cd-form-field__label--align-left {
+    justify-content: flex-start;
+  }
+  .cd-form-field__label--align-right {
+    justify-content: flex-end;
+  }
+  .cd-form-field--label-left .cd-form-field__label {
+    padding-block-start: var(--cd-spacing-1);
+  }
+  .cd-form-field__required {
+    color: var(--cd-form-required-color, var(--cd-color-danger, #e54848));
+  }
+  .cd-form-field__control {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    gap: var(--cd-spacing-1);
+    min-inline-size: 0;
+  }
+  /* inset floating label */
+  .cd-form-field--label-inset {
+    flex-direction: column;
+  }
+  .cd-form-field--label-inset .cd-form-field__control {
+    position: relative;
+    padding-block-start: var(--cd-spacing-3);
+  }
+  .cd-form-field__inset-label {
+    position: absolute;
+    inset-block-start: 50%;
+    inset-inline-start: var(--cd-input-padding-x, var(--cd-spacing-3));
+    transform: translateY(-50%);
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cd-spacing-1);
+    color: var(--cd-input-color-placeholder, var(--cd-color-text-3));
+    pointer-events: none;
+    transition:
+      transform var(--cd-motion-duration-fast) var(--cd-motion-ease-standard),
+      font-size var(--cd-motion-duration-fast) var(--cd-motion-ease-standard),
+      color var(--cd-motion-duration-fast) var(--cd-motion-ease-standard);
+  }
+  .cd-form-field--floated .cd-form-field__inset-label {
+    transform: translateY(calc(-50% - 0.85rem)) scale(0.85);
+    color: var(--cd-form-label-color, var(--cd-color-text-1));
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .cd-form-field__inset-label {
+      transition: none;
+    }
+  }
+  .cd-form-field__error {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cd-spacing-1);
+    color: var(--cd-form-error-color, var(--cd-color-danger, #e54848));
+    font-size: var(--cd-form-error-font-size, var(--cd-font-size-1, 0.75rem));
+  }
+  .cd-form-field__warning {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cd-spacing-1);
+    color: var(--cd-form-warning-color, var(--cd-color-warning, #fa8c16));
+    font-size: var(--cd-form-error-font-size, var(--cd-font-size-1, 0.75rem));
+  }
+  .cd-form-field__status-icon {
+    flex: 0 0 auto;
+  }
+  .cd-form-field__extra {
+    color: var(--cd-form-extra-color, var(--cd-color-text-3));
+    font-size: var(--cd-form-error-font-size, var(--cd-font-size-1, 0.75rem));
+  }
+  .cd-form-field__extra--middle {
+    order: -1;
+  }
+  .cd-form-field__extra--bottom {
+    order: 0;
+  }
+  /* async-validation indicator (red line #3: pure-CSS spin, no JS geometry) */
+  .cd-form-field__validating {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--cd-spacing-1);
+    color: var(--cd-form-extra-color, var(--cd-color-text-3));
+    font-size: var(--cd-form-error-font-size, var(--cd-font-size-1, 0.75rem));
+  }
+  .cd-form-field__spinner {
+    inline-size: 0.85em;
+    block-size: 0.85em;
+    border: 2px solid var(--cd-color-fill-2, rgba(0, 0, 0, 0.1));
+    border-block-start-color: var(--cd-color-primary, #3370ff);
+    border-radius: 50%;
+    animation: cd-form-field-spin 0.7s linear infinite;
+  }
+  @keyframes cd-form-field-spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .cd-form-field__spinner {
+      animation-duration: 1.8s;
+    }
+  }
+</style>

package/dist/form/Field.svelte.d.ts

@@ -0,0 +1,82 @@
+import type { Snippet } from 'svelte';
+import { type Rule, type ValidateTrigger } from '@chenzy-design/core';
+type FieldStatus = 'default' | 'error' | 'warning';
+interface ChildArgs {
+    /** Generic field value — always present, regardless of `valuePropName`. */
+    value: unknown;
+    onChange: (v: unknown) => void;
+    onBlur: () => void;
+    status: FieldStatus;
+    id: string;
+    /** id(s) of the field's error/warning/extra text, for the control's aria-describedby */
+    describedBy: string | undefined;
+    disabled: boolean;
+    /**
+     * whether this field is required (spec §138). Controls should expose it as
+     * `aria-required="true"` so the required semantic reaches screen readers —
+     * the visible star is `aria-hidden` and thus inaudible on its own.
+     */
+    required: boolean;
+    /**
+     * Convenience alias keyed by `valuePropName` (default 'value'), carrying the
+     * same value as `value`. Lets non-`value` controls (e.g. Checkbox/Switch use
+     * `checked`) destructure `{ checked, onChange }` directly from the snippet.
+     */
+    [key: string]: unknown;
+}
+interface Props {
+    field: string;
+    label?: string;
+    rules?: Rule[];
+    /** field-level initial value; overrides the container's initValues (spec §4.2 L79). */
+    initValue?: unknown;
+    required?: boolean;
+    /**
+     * externally forced validate status (spec §4.2 L81). A controlled DISPLAY
+     * state only — it never feeds the internal validation engine and is never
+     * written back (red line #1). When set it takes precedence over the
+     * internally computed status for visuals/aria.
+     */
+    validateStatus?: 'default' | 'warning' | 'error';
+    extraText?: string;
+    /**
+     * register & collect only, render no layout DOM (spec §4.2 L85 / §190). The
+     * control snippet is still rendered (so it can bind), but the label / status
+     * text / field wrapper chrome are skipped.
+     */
+    noStyle?: boolean;
+    /** number of columns this field spans inside a grid parent / Form.Section (spec §4.2 L86). */
+    span?: number;
+    /** pure value transform applied at collect/submit time (spec §4.2 L88). */
+    transform?: (value: unknown, values: Record<string, unknown>) => unknown;
+    /**
+     * Name of the control's value prop. Default 'value'. For boolean controls
+     * such as Checkbox/Switch pass 'checked'; the snippet then exposes a
+     * `checked` alias mirroring the field value.
+     */
+    valuePropName?: string;
+    /** names of fields this field's validation depends on (e.g. confirm → ['password']) */
+    dependencies?: string[];
+    /** field-level override of the form's validateTrigger (spec §4 L84). */
+    trigger?: ValidateTrigger | ValidateTrigger[];
+    /**
+     * 是否允许空字符串作为有效值（默认 false：空串当 undefined 处理，不触发 required 通过）。
+     * 设为 true 后空串参与 required 校验和值收集。
+     */
+    allowEmptyString?: boolean;
+    /**
+     * 字段值在存入 formState 前的转换函数（在 Field 层执行，不同于 transform 的提交时转换）。
+     * convert 的结果回写 formState，transform 的结果仅用于提交/收集，不回写。
+     */
+    convert?: (value: unknown) => unknown;
+    /**
+     * 组件卸载时保留字段状态（默认 false：卸载时清空字段值/错误/touched）。
+     * 设为 true 后卸载不清 formState，下次挂载时继承上次状态。
+     */
+    keepState?: boolean;
+    children?: Snippet<[ChildArgs]>;
+}
+declare const Field: import("svelte").Component<Props, {}, "">;
+type Field = ReturnType<typeof Field>;
+export default Field;
+//# sourceMappingURL=Field.svelte.d.ts.map

package/dist/form/Field.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Field.svelte.d.ts","sourceRoot":"","sources":["../../src/form/Field.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAS,KAAK,IAAI,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAK3E,KAAK,WAAW,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEnD,UAAU,SAAS;IACjB,2EAA2E;IAC3E,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,EAAE,WAAW,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,wFAAwF;IACxF,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,UAAU,KAAK;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,uFAAuF;IACvF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IACzE;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uFAAuF;IACvF,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,wEAAwE;IACxE,OAAO,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IAC9C;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;CACjC;AAmQH,QAAA,MAAM,KAAK,2CAAwC,CAAC;AACpD,KAAK,KAAK,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC;AACtC,eAAe,KAAK,CAAC"}

package/dist/form/FieldArray.svelte

@@ -0,0 +1,75 @@
+<!--
+  FieldArray (Form.List) — 动态字段数组：增/删/重排子表单项。
+  本地维护行标识 items（{ key }[]），children snippet 渲染每行；
+  子字段用拼接键 `${name}.${item.key}.${sub}` 走普通 Field（core 扁平键天然支持校验）。
+  remove 时清理该行所有子字段值（setFieldValue undefined），避免提交残留。
+  不依赖 core 的嵌套路径支持，自包含（红线 #1：不写回 props，状态本地 $state）。
+-->
+<script lang="ts">
+  import { untrack, type Snippet } from 'svelte';
+  import { useId } from '@chenzy-design/core';
+  import { getFormContext } from './context.js';
+
+  interface ArrayItem {
+    /** 稳定行标识，用于拼接子字段名与 each key */
+    key: string;
+  }
+  interface ChildArgs {
+    items: ArrayItem[];
+    /** 拼接某行某子字段的完整 field 名 */
+    name: (item: ArrayItem, sub: string) => string;
+    add: () => void;
+    remove: (item: ArrayItem) => void;
+    move: (from: number, to: number) => void;
+  }
+
+  interface Props {
+    /** 数组字段名（子字段前缀） */
+    name: string;
+    /** 初始行数 */
+    initialCount?: number;
+    children?: Snippet<[ChildArgs]>;
+  }
+
+  let { name, initialCount = 0, children }: Props = $props();
+
+  const ctx = getFormContext();
+  if (!ctx) throw new Error('<Form.List> must be used inside <Form>');
+  const { form } = ctx;
+
+  function newKey(): string {
+    return useId(`${name}-row`);
+  }
+  function getInitial(): ArrayItem[] {
+    return Array.from({ length: Math.max(0, initialCount) }, () => ({ key: newKey() }));
+  }
+  let items = $state<ArrayItem[]>(untrack(getInitial));
+
+  function add() {
+    items = [...items, { key: newKey() }];
+  }
+  function remove(item: ArrayItem) {
+    // 清理该行所有子字段值（前缀匹配），避免提交残留
+    const prefix = `${name}.${item.key}.`;
+    const values = form.getState().values;
+    for (const k of Object.keys(values)) {
+      if (k.startsWith(prefix)) form.setFieldValue(k, undefined);
+    }
+    items = items.filter((it) => it.key !== item.key);
+  }
+  function move(from: number, to: number) {
+    if (from === to || from < 0 || to < 0 || from >= items.length || to >= items.length) return;
+    const next = [...items];
+    const [moved] = next.splice(from, 1);
+    next.splice(to, 0, moved as ArrayItem);
+    items = next;
+  }
+
+  function fieldName(item: ArrayItem, sub: string): string {
+    return `${name}.${item.key}.${sub}`;
+  }
+</script>
+
+<div class="cd-field-array">
+  {@render children?.({ items, name: fieldName, add, remove, move })}
+</div>

package/dist/form/FieldArray.svelte.d.ts

@@ -0,0 +1,24 @@
+import { type Snippet } from 'svelte';
+interface ArrayItem {
+    /** 稳定行标识，用于拼接子字段名与 each key */
+    key: string;
+}
+interface ChildArgs {
+    items: ArrayItem[];
+    /** 拼接某行某子字段的完整 field 名 */
+    name: (item: ArrayItem, sub: string) => string;
+    add: () => void;
+    remove: (item: ArrayItem) => void;
+    move: (from: number, to: number) => void;
+}
+interface Props {
+    /** 数组字段名（子字段前缀） */
+    name: string;
+    /** 初始行数 */
+    initialCount?: number;
+    children?: Snippet<[ChildArgs]>;
+}
+declare const FieldArray: import("svelte").Component<Props, {}, "">;
+type FieldArray = ReturnType<typeof FieldArray>;
+export default FieldArray;
+//# sourceMappingURL=FieldArray.svelte.d.ts.map

package/dist/form/FieldArray.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldArray.svelte.d.ts","sourceRoot":"","sources":["../../src/form/FieldArray.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAK7C,UAAU,SAAS;IACjB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;CACb;AACD,UAAU,SAAS;IACjB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/C,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C;AAED,UAAU,KAAK;IACb,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW;IACX,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;CACjC;AAuDH,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/form/Form.a11y.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Form.a11y.test.d.ts.map

package/dist/form/Form.a11y.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Form.a11y.test.d.ts","sourceRoot":"","sources":["../../src/form/Form.a11y.test.ts"],"names":[],"mappings":""}