@chenzy-design/svelte 0.1.0

package/dist/form/Form.a11y.test.js

@@ -0,0 +1,36 @@
+// Form a11y：经 FormA11yFixture 组合 Form.Input + Form.Field 自定义控件。
+// 验证 label 关联（<label for> ↔ 控件 id）、required → aria-required、
+// validateStatus=error → 控件 aria-invalid、extraText/error → aria-describedby。
+// 仅静态 ARIA + axe（不测校验交互）。
+import { describe, it, expect } from 'vitest';
+import { renderWithLocale, expectNoAxeViolations } from '../test-utils/a11y.js';
+import FormA11yFixture from './FormA11yFixture.svelte';
+describe('Form a11y', () => {
+    it('Form.Input：label 经 for/id 关联到 input，required → aria-required', async () => {
+        const { container } = renderWithLocale(FormA11yFixture, {});
+        const nameField = container.querySelector('[data-field="name"]');
+        expect(nameField).not.toBeNull();
+        const label = nameField?.querySelector('label');
+        const input = nameField?.querySelector('input');
+        expect(label).not.toBeNull();
+        expect(input).not.toBeNull();
+        // label[for] 精确指向控件 id（WAI-ARIA 首选关联）。
+        expect(label?.getAttribute('for')).toBe(input?.getAttribute('id'));
+        expect(input?.getAttribute('aria-required')).toBe('true');
+    });
+    it('Form.Field 自定义控件：validateStatus=error → aria-invalid，describedBy 关联存在的元素', async () => {
+        const { container } = renderWithLocale(FormA11yFixture, {});
+        const bioField = container.querySelector('[data-field="bio"]');
+        expect(bioField).not.toBeNull();
+        const textarea = bioField?.querySelector('textarea');
+        expect(textarea?.getAttribute('aria-invalid')).toBe('true');
+        // aria-describedby 指向实际存在的状态文本元素。
+        const describedBy = textarea?.getAttribute('aria-describedby');
+        expect(describedBy).toBeTruthy();
+        expect(container.querySelector(`#${describedBy}`)).not.toBeNull();
+    });
+    it('整个表单：无 axe violations', async () => {
+        const { container } = renderWithLocale(FormA11yFixture, {});
+        await expectNoAxeViolations(container);
+    });
+});

package/dist/form/Form.svelte

@@ -0,0 +1,243 @@
+<!--
+  Form — see specs/components/input/Form.spec.md
+  Container that bridges the headless `createForm` (callback-subscribe) into Svelte
+  runes and shares it via context. Token-driven, a11y-correct.
+-->
+<script lang="ts">
+  import { untrack, type Snippet } from 'svelte';
+  import {
+    createForm,
+    type FormValues,
+    type FieldErrors,
+    type MessageDescriptor,
+    type ValidateTrigger,
+  } from '@chenzy-design/core';
+  import { interpolate } from '@chenzy-design/locale';
+  import {
+    setFormContext,
+    type FormLayout,
+    type FormLabelPosition,
+    type FormSize,
+    type FormLabelAlign,
+    type GridCol,
+  } from './context.js';
+  import { useLocale } from '../locale-provider/index.js';
+  import { getGlobalValidateMessages } from '../config-provider/index.js';
+
+  interface Props {
+    /** controlled whole-form values (reported back via onChange, never written to the prop) */
+    value?: FormValues;
+    initValues?: FormValues;
+    layout?: FormLayout;
+    /** 'top' | 'left' | 'inset'（inset：label 浮入控件，聚焦/有值时上浮变小） */
+    labelPosition?: FormLabelPosition;
+    labelWidth?: number | string;
+    /** Label 文本对齐（spec §4 L60，默认 'left'）。 */
+    labelAlign?: FormLabelAlign;
+    size?: FormSize;
+    disabled?: boolean;
+    requiredMark?: boolean;
+    colon?: boolean;
+    /** on failed submit, scroll to and focus the first errored field */
+    scrollToError?: boolean;
+    /** 全局默认校验时机（spec §4 L65，默认 ['blur','change']），字段可覆盖。 */
+    validateTrigger?: ValidateTrigger | ValidateTrigger[];
+    /** 错误/警告文案是否带状态图标（spec §4 L66，默认 true）。 */
+    showValidateIcon?: boolean;
+    /** 字段命中首条错误即停止该字段后续 rule（spec §4 L68，默认 false）。 */
+    stopValidateWithError?: boolean;
+    /** 是否拦截原生 submit 默认行为（spec §4 L69，默认 true）。 */
+    preventDefault?: boolean;
+    /** 收集值时是否保留空值字段键（spec §4 L70，默认 false）。 */
+    allowEmpty?: boolean;
+    /** scrollToError 别名（优先级低于 scrollToError）。 */
+    autoScrollToError?: boolean;
+    /** 额外说明文本位置（默认 'bottom'，经 context 传给 FormField）。 */
+    extraTextPosition?: 'middle' | 'bottom';
+    onSubmit?: (r: { valid: boolean; values: FormValues; errors: FieldErrors }) => void;
+    /** 任意字段值变化时触发（不同于 onChange 的纯值快照，此回调额外携带变更字段信息）。 */
+    onValueChange?: (values: FormValues, changedValues: Record<string, unknown>) => void;
+    /** 表单校验失败时独立回调（onSubmit 只在 valid 时调用时可用此做失败分支）。 */
+    onSubmitFail?: (errors: FieldErrors, values: FormValues) => void;
+    onChange?: (values: FormValues) => void;
+    /** 控件布局列配置（Grid 布局时）。 */
+    wrapperCol?: GridCol;
+    /** 标签布局列配置（Grid 布局时）。 */
+    labelCol?: GridCol;
+    children?: Snippet;
+    footer?: Snippet<[{ submitting: boolean }]>;
+  }
+
+  let {
+    value,
+    initValues = {},
+    layout = 'vertical',
+    labelPosition = 'top',
+    labelWidth,
+    labelAlign = 'left',
+    size = 'default',
+    disabled = false,
+    requiredMark = true,
+    colon = false,
+    scrollToError = false,
+    autoScrollToError = false,
+    extraTextPosition = 'bottom',
+    validateTrigger = ['blur', 'change'],
+    showValidateIcon = true,
+    stopValidateWithError = false,
+    preventDefault = true,
+    allowEmpty = false,
+    onSubmit,
+    onValueChange,
+    onSubmitFail,
+    onChange,
+    wrapperCol,
+    labelCol,
+    children,
+    footer,
+  }: Props = $props();
+
+  const loc = useLocale();
+  // 全局校验文案覆盖（来自 ConfigProvider getValidateMessages）；须在 init 期读 context。
+  const globalValidateMessages = getGlobalValidateMessages();
+
+  // 校验消息优先级：
+  // 1) rule.message（descriptor.text）显式覆盖；
+  // 2) ConfigProvider getValidateMessages() 提供的对应 `Form.*` 键模板（带插值）；
+  // 3) locale 内置 Form.* 模板。
+  // 未配置全局覆盖时行为完全不变（向后兼容）。
+  function resolveMessage(d: MessageDescriptor): string {
+    if (d.text !== undefined) return d.text;
+    const override = globalValidateMessages?.()[d.key];
+    if (override !== undefined) return d.params ? interpolate(override, d.params) : override;
+    return loc().t(d.key, d.params);
+  }
+
+  // initial values are a one-time snapshot by design; untrack makes the
+  // non-reactive seed read explicit (later prop changes flow via the controlled
+  // `value` effect / onChange, not by re-seeding the form).
+  const seedValues: FormValues = untrack(() => value ?? initValues);
+  // validateTrigger / stopValidateWithError / allowEmpty are construction-time
+  // config of the headless form (read once, like initialValues). untrack keeps
+  // the read non-reactive — the form instance is created exactly once.
+  const form = createForm({
+    initialValues: seedValues,
+    resolveMessage,
+    validateTrigger: untrack(() => validateTrigger),
+    stopValidateWithError: untrack(() => stopValidateWithError),
+    allowEmpty: untrack(() => allowEmpty),
+  });
+
+  // Bridge: callback-subscribe → runes. core returns a STABLE state object whose
+  // sub-objects are replaced immutably; we take a fresh shallow snapshot on every
+  // emit so the new reference triggers Svelte reactivity. The $effect ONLY writes
+  // formState — it never reads state that children write on mount, so no loop.
+  let formState = $state({ ...form.getState() });
+  let lastValues = form.getState().values;
+  // Subscribe synchronously at component init (NOT inside an $effect): child
+  // Field registration effects run after the parent's setup but emit on the core
+  // bus; subscribing here guarantees we capture those early emits (e.g. a
+  // field-level `initValue` seeding the value). The subscriber only WRITES
+  // `formState` from the stable core state — it never reads child-written render
+  // state, so there is no effect loop. Cleanup unsubscribes on destroy.
+  const unsub = form.subscribe((s) => {
+    formState = { ...s };
+    if (s.values !== lastValues) {
+      const prev = lastValues;
+      lastValues = s.values;
+      onChange?.(s.values);
+      if (onValueChange) {
+        // Compute changedValues: fields whose reference differs from previous snapshot.
+        const changed: Record<string, unknown> = {};
+        for (const k of Object.keys(s.values)) {
+          if (s.values[k] !== prev[k]) changed[k] = s.values[k];
+        }
+        onValueChange(s.values, changed);
+      }
+    }
+  });
+  $effect(() => unsub);
+
+  // Controlled `value`: push into the form only when the prop reference changes.
+  // We never write back to the prop (onChange is the only outward channel), so
+  // this cannot form a value -> onChange -> value loop.
+  $effect(() => {
+    if (value !== undefined) form.setFieldsValue(value);
+  });
+
+  setFormContext({
+    form,
+    getFormState: () => formState,
+    getLabelPosition: () => labelPosition,
+    getLabelWidth: () => labelWidth,
+    getLabelAlign: () => labelAlign,
+    getSize: () => size,
+    getDisabled: () => disabled,
+    getRequiredMark: () => requiredMark,
+    getColon: () => colon,
+    getShowValidateIcon: () => showValidateIcon,
+    getExtraTextPosition: () => extraTextPosition,
+    getWrapperCol: () => wrapperCol,
+    getLabelCol: () => labelCol,
+  });
+
+  // autoScrollToError 是 scrollToError 别名（scrollToError 优先）
+  const effScrollToError = $derived(scrollToError || autoScrollToError || false);
+
+  // ref to the <form> element — used imperatively (red line #3: DOM ops live in
+  // the event handler, never in render) to locate the first errored field.
+  let formEl: HTMLFormElement | undefined;
+
+  function focusFirstError(errors: FieldErrors): void {
+    if (!formEl) return;
+    // walk fields in DOM order so we land on the *first* errored one on screen.
+    const nodes = formEl.querySelectorAll<HTMLElement>('[data-field]');
+    for (const node of nodes) {
+      const name = node.dataset.field;
+      if (name === undefined) continue;
+      const err = errors[name];
+      if (err === undefined || err === '') continue;
+      node.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      const control = node.querySelector<HTMLElement>(
+        'input, textarea, select, [tabindex]:not([tabindex="-1"])',
+      );
+      control?.focus({ preventScroll: true });
+      return;
+    }
+  }
+
+  async function handleSubmit(e: SubmitEvent) {
+    // spec §4 L69 / §6 L140: preventDefault is now prop-controlled (default true
+    // = previous hardcoded behavior, backward compatible).
+    if (preventDefault) e.preventDefault();
+    const r = await form.submit();
+    if (!r.valid && effScrollToError) focusFirstError(r.errors);
+    if (!r.valid) onSubmitFail?.(r.errors, r.values);
+    onSubmit?.(r);
+  }
+
+  const cls = $derived(
+    `cd-form cd-form--${layout} cd-form--label-${labelPosition} cd-form--${size}`,
+  );
+</script>
+
+<form bind:this={formEl} class={cls} onsubmit={handleSubmit}>
+  {@render children?.()}
+  {#if footer}
+    <div class="cd-form__footer">
+      {@render footer({ submitting: formState.submitting })}
+    </div>
+  {/if}
+</form>
+
+<style>
+  .cd-form {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cd-form-item-gap, var(--cd-spacing-4));
+  }
+  .cd-form__footer {
+    display: flex;
+    gap: var(--cd-spacing-3);
+  }
+</style>

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

@@ -0,0 +1,56 @@
+import { type Snippet } from 'svelte';
+import { type FormValues, type FieldErrors, type ValidateTrigger } from '@chenzy-design/core';
+import { type FormLayout, type FormLabelPosition, type FormSize, type FormLabelAlign, type GridCol } from './context.js';
+interface Props {
+    /** controlled whole-form values (reported back via onChange, never written to the prop) */
+    value?: FormValues;
+    initValues?: FormValues;
+    layout?: FormLayout;
+    /** 'top' | 'left' | 'inset'（inset：label 浮入控件，聚焦/有值时上浮变小） */
+    labelPosition?: FormLabelPosition;
+    labelWidth?: number | string;
+    /** Label 文本对齐（spec §4 L60，默认 'left'）。 */
+    labelAlign?: FormLabelAlign;
+    size?: FormSize;
+    disabled?: boolean;
+    requiredMark?: boolean;
+    colon?: boolean;
+    /** on failed submit, scroll to and focus the first errored field */
+    scrollToError?: boolean;
+    /** 全局默认校验时机（spec §4 L65，默认 ['blur','change']），字段可覆盖。 */
+    validateTrigger?: ValidateTrigger | ValidateTrigger[];
+    /** 错误/警告文案是否带状态图标（spec §4 L66，默认 true）。 */
+    showValidateIcon?: boolean;
+    /** 字段命中首条错误即停止该字段后续 rule（spec §4 L68，默认 false）。 */
+    stopValidateWithError?: boolean;
+    /** 是否拦截原生 submit 默认行为（spec §4 L69，默认 true）。 */
+    preventDefault?: boolean;
+    /** 收集值时是否保留空值字段键（spec §4 L70，默认 false）。 */
+    allowEmpty?: boolean;
+    /** scrollToError 别名（优先级低于 scrollToError）。 */
+    autoScrollToError?: boolean;
+    /** 额外说明文本位置（默认 'bottom'，经 context 传给 FormField）。 */
+    extraTextPosition?: 'middle' | 'bottom';
+    onSubmit?: (r: {
+        valid: boolean;
+        values: FormValues;
+        errors: FieldErrors;
+    }) => void;
+    /** 任意字段值变化时触发（不同于 onChange 的纯值快照，此回调额外携带变更字段信息）。 */
+    onValueChange?: (values: FormValues, changedValues: Record<string, unknown>) => void;
+    /** 表单校验失败时独立回调（onSubmit 只在 valid 时调用时可用此做失败分支）。 */
+    onSubmitFail?: (errors: FieldErrors, values: FormValues) => void;
+    onChange?: (values: FormValues) => void;
+    /** 控件布局列配置（Grid 布局时）。 */
+    wrapperCol?: GridCol;
+    /** 标签布局列配置（Grid 布局时）。 */
+    labelCol?: GridCol;
+    children?: Snippet;
+    footer?: Snippet<[{
+        submitting: boolean;
+    }]>;
+}
+declare const Form: import("svelte").Component<Props, {}, "">;
+type Form = ReturnType<typeof Form>;
+export default Form;
+//# sourceMappingURL=Form.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Form.svelte.d.ts","sourceRoot":"","sources":["../../src/form/Form.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAEH,KAAK,UAAU,EACf,KAAK,WAAW,EAEhB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAE/B,OAAO,EAEH,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,OAAO,EACb,MAAM,cAAc,CAAC;AAKtB,UAAU,KAAK;IACb,2FAA2F;IAC3F,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,iBAAiB,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,yCAAyC;IACzC,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oEAAoE;IACpE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wDAAwD;IACxD,eAAe,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IACtD,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mDAAmD;IACnD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,+CAA+C;IAC/C,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACxC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,KAAK,IAAI,CAAC;IACpF,oDAAoD;IACpD,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACrF,mDAAmD;IACnD,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACjE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACxC,yBAAyB;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yBAAyB;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;CAC7C;AAiLH,QAAA,MAAM,IAAI,2CAAwC,CAAC;AACnD,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AACpC,eAAe,IAAI,CAAC"}

package/dist/form/FormA11yFixture.svelte

@@ -0,0 +1,31 @@
+<!--
+  Form a11y 测试夹具：在 Form 内组合 Form.Input（Field+Input）与一个 Form.Field
+  自定义控件，覆盖 label 关联（for/id）、aria-required、aria-describedby、
+  validateStatus 强制 error → aria-invalid。仅供 Form.a11y.test.ts 使用，不导出。
+  通过 renderWithLocale 渲染（harness 会注入空 children 插槽，Form 接受 children 故无碍）。
+-->
+<script lang="ts">
+  import { Form } from './index.js';
+  import TextArea from '../textarea/TextArea.svelte';
+</script>
+
+<Form initValues={{ name: 'Ada', bio: '' }}>
+  <!-- Form.Input：Field + Input，label 经 for/id 关联，required → aria-required -->
+  <Form.Input field="name" label="Name" required placeholder="Your name" />
+
+  <!-- Form.Field 自定义控件：validateStatus 强制 error → 控件 aria-invalid，
+       extraText → aria-describedby 关联 -->
+  <Form.Field field="bio" label="Bio" validateStatus="error" extraText="Some hint">
+    {#snippet children({ value, onChange, onBlur, status, id, describedBy, required })}
+      <TextArea
+        value={value === undefined ? '' : String(value)}
+        {id}
+        status={status === 'error' ? 'error' : 'default'}
+        ariaLabel="Bio"
+        {...(describedBy !== undefined ? { ariaDescribedby: describedBy } : {})}
+        onChange={(v) => onChange(v)}
+        onBlur={() => onBlur()}
+      />
+    {/snippet}
+  </Form.Field>
+</Form>

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

@@ -0,0 +1,19 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const FormA11yFixture: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type FormA11yFixture = InstanceType<typeof FormA11yFixture>;
+export default FormA11yFixture;
+//# sourceMappingURL=FormA11yFixture.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FormA11yFixture.svelte.d.ts","sourceRoot":"","sources":["../../src/form/FormA11yFixture.svelte.ts"],"names":[],"mappings":"AA0BA,UAAU,kCAAkC,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,OAAO,GAAG,EAAE,EAAE,QAAQ,GAAG,MAAM;IACpM,KAAK,OAAO,EAAE,OAAO,QAAQ,EAAE,2BAA2B,CAAC,KAAK,CAAC,GAAG,OAAO,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,GAAG;QAAE,UAAU,CAAC,EAAE,QAAQ,CAAA;KAAE,GAAG,OAAO,CAAC;IACjK,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,CAAA;KAAC,GAAG,OAAO,GAAG;QAAE,IAAI,CAAC,EAAE,GAAG,CAAC;QAAC,GAAG,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC;IACtG,YAAY,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAKD,QAAA,MAAM,eAAe;;kBAA+E,CAAC;AACnF,KAAK,eAAe,GAAG,YAAY,CAAC,OAAO,eAAe,CAAC,CAAC;AAC9D,eAAe,eAAe,CAAC"}

package/dist/form/FormCascader.svelte

@@ -0,0 +1,82 @@
+<!--
+  Form.Cascader — convenience wrapper: <Form.Field> + <Cascader> bound to a field.
+-->
+<script lang="ts">
+  import type { Rule, ValidateTrigger } from '@chenzy-design/core';
+  import type { ComponentProps } from 'svelte';
+  import Field from './Field.svelte';
+  import Cascader from '../cascader/Cascader.svelte';
+
+  type CascaderProps = ComponentProps<typeof Cascader>;
+
+  interface Props {
+    field: string;
+    label?: string;
+    rules?: Rule[];
+    initValue?: unknown;
+    required?: boolean;
+    validateStatus?: 'default' | 'warning' | 'error';
+    extraText?: string;
+    span?: number;
+    transform?: (value: unknown, values: Record<string, unknown>) => unknown;
+    dependencies?: string[];
+    trigger?: ValidateTrigger | ValidateTrigger[];
+    // Cascader-specific props
+    treeData?: CascaderProps['treeData'];
+    multiple?: CascaderProps['multiple'];
+    placeholder?: CascaderProps['placeholder'];
+    disabled?: boolean;
+    size?: CascaderProps['size'];
+    displayProp?: CascaderProps['displayProp'];
+  }
+
+  let {
+    field,
+    label,
+    rules = [],
+    initValue,
+    required = false,
+    validateStatus,
+    extraText,
+    span,
+    transform,
+    dependencies,
+    trigger,
+    treeData,
+    multiple,
+    placeholder,
+    disabled,
+    size,
+    displayProp,
+  }: Props = $props();
+
+  const fieldProps = $derived<ComponentProps<typeof Field>>({
+    field,
+    rules,
+    required,
+    ...(label !== undefined ? { label } : {}),
+    ...(initValue !== undefined ? { initValue } : {}),
+    ...(validateStatus !== undefined ? { validateStatus } : {}),
+    ...(extraText !== undefined ? { extraText } : {}),
+    ...(span !== undefined ? { span } : {}),
+    ...(transform !== undefined ? { transform } : {}),
+    ...(dependencies !== undefined ? { dependencies } : {}),
+    ...(trigger !== undefined ? { trigger } : {}),
+  });
+</script>
+
+<Field {...fieldProps}>
+  {#snippet children({ value, onChange, status, disabled: fieldDisabled })}
+    <Cascader
+      value={value as CascaderProps['value']}
+      {treeData}
+      {multiple}
+      {placeholder}
+      disabled={disabled ?? fieldDisabled}
+      {size}
+      {displayProp}
+      status={status === 'error' ? 'error' : 'default'}
+      onChange={(v) => onChange(v)}
+    />
+  {/snippet}
+</Field>

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

@@ -0,0 +1,27 @@
+import type { Rule, ValidateTrigger } from '@chenzy-design/core';
+import type { ComponentProps } from 'svelte';
+import Cascader from '../cascader/Cascader.svelte';
+type CascaderProps = ComponentProps<typeof Cascader>;
+interface Props {
+    field: string;
+    label?: string;
+    rules?: Rule[];
+    initValue?: unknown;
+    required?: boolean;
+    validateStatus?: 'default' | 'warning' | 'error';
+    extraText?: string;
+    span?: number;
+    transform?: (value: unknown, values: Record<string, unknown>) => unknown;
+    dependencies?: string[];
+    trigger?: ValidateTrigger | ValidateTrigger[];
+    treeData?: CascaderProps['treeData'];
+    multiple?: CascaderProps['multiple'];
+    placeholder?: CascaderProps['placeholder'];
+    disabled?: boolean;
+    size?: CascaderProps['size'];
+    displayProp?: CascaderProps['displayProp'];
+}
+declare const FormCascader: import("svelte").Component<Props, {}, "">;
+type FormCascader = ReturnType<typeof FormCascader>;
+export default FormCascader;
+//# sourceMappingURL=FormCascader.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FormCascader.svelte.d.ts","sourceRoot":"","sources":["../../src/form/FormCascader.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,QAAQ,MAAM,6BAA6B,CAAC;AAGjD,KAAK,aAAa,GAAG,cAAc,CAAC,OAAO,QAAQ,CAAC,CAAC;AAErD,UAAU,KAAK;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IACzE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IAE9C,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;CAC5C;AAqDH,QAAA,MAAM,YAAY,2CAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/form/FormCheckbox.svelte

@@ -0,0 +1,83 @@
+<!--
+  Form.Checkbox — convenience wrapper: <Form.Field> + <Checkbox> bound to a field.
+  Uses valuePropName='checked' since Checkbox is a boolean control.
+-->
+<script lang="ts">
+  import type { Rule, ValidateTrigger } from '@chenzy-design/core';
+  import type { ComponentProps, Snippet } from 'svelte';
+  import Field from './Field.svelte';
+  import Checkbox from '../checkbox/Checkbox.svelte';
+
+  type CheckboxProps = ComponentProps<typeof Checkbox>;
+
+  interface Props {
+    field: string;
+    label?: string;
+    rules?: Rule[];
+    initValue?: unknown;
+    required?: boolean;
+    validateStatus?: 'default' | 'warning' | 'error';
+    extraText?: string;
+    span?: number;
+    transform?: (value: unknown, values: Record<string, unknown>) => unknown;
+    dependencies?: string[];
+    trigger?: ValidateTrigger | ValidateTrigger[];
+    // Checkbox-specific props
+    disabled?: boolean;
+    size?: CheckboxProps['size'];
+    indeterminate?: CheckboxProps['indeterminate'];
+    type?: CheckboxProps['type'];
+    children?: Snippet;
+  }
+
+  let {
+    field,
+    label,
+    rules = [],
+    initValue,
+    required = false,
+    validateStatus,
+    extraText,
+    span,
+    transform,
+    dependencies,
+    trigger,
+    disabled,
+    size,
+    indeterminate,
+    type,
+    children,
+  }: Props = $props();
+
+  const fieldProps = $derived<ComponentProps<typeof Field>>({
+    field,
+    rules,
+    required,
+    valuePropName: 'checked',
+    ...(label !== undefined ? { label } : {}),
+    ...(initValue !== undefined ? { initValue } : {}),
+    ...(validateStatus !== undefined ? { validateStatus } : {}),
+    ...(extraText !== undefined ? { extraText } : {}),
+    ...(span !== undefined ? { span } : {}),
+    ...(transform !== undefined ? { transform } : {}),
+    ...(dependencies !== undefined ? { dependencies } : {}),
+    ...(trigger !== undefined ? { trigger } : {}),
+  });
+</script>
+
+<Field {...fieldProps}>
+  {#snippet children({ value, onChange, status, disabled: fieldDisabled, id, required: fieldRequired })}
+    <Checkbox
+      checked={typeof value === 'boolean' ? value : undefined}
+      disabled={disabled ?? fieldDisabled}
+      {size}
+      {indeterminate}
+      {type}
+      {id}
+      status={status === 'error' ? 'error' : 'default'}
+      onChange={(checked) => onChange(checked)}
+    >
+      {@render children?.()}
+    </Checkbox>
+  {/snippet}
+</Field>

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

@@ -0,0 +1,26 @@
+import type { Rule, ValidateTrigger } from '@chenzy-design/core';
+import type { ComponentProps, Snippet } from 'svelte';
+import Checkbox from '../checkbox/Checkbox.svelte';
+type CheckboxProps = ComponentProps<typeof Checkbox>;
+interface Props {
+    field: string;
+    label?: string;
+    rules?: Rule[];
+    initValue?: unknown;
+    required?: boolean;
+    validateStatus?: 'default' | 'warning' | 'error';
+    extraText?: string;
+    span?: number;
+    transform?: (value: unknown, values: Record<string, unknown>) => unknown;
+    dependencies?: string[];
+    trigger?: ValidateTrigger | ValidateTrigger[];
+    disabled?: boolean;
+    size?: CheckboxProps['size'];
+    indeterminate?: CheckboxProps['indeterminate'];
+    type?: CheckboxProps['type'];
+    children?: Snippet;
+}
+declare const FormCheckbox: import("svelte").Component<Props, {}, "">;
+type FormCheckbox = ReturnType<typeof FormCheckbox>;
+export default FormCheckbox;
+//# sourceMappingURL=FormCheckbox.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FormCheckbox.svelte.d.ts","sourceRoot":"","sources":["../../src/form/FormCheckbox.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtD,OAAO,QAAQ,MAAM,6BAA6B,CAAC;AAGjD,KAAK,aAAa,GAAG,cAAc,CAAC,OAAO,QAAQ,CAAC,CAAC;AAErD,UAAU,KAAK;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IACzE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,eAAe,GAAG,eAAe,EAAE,CAAC;IAE9C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC/C,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAuDH,QAAA,MAAM,YAAY,2CAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}