@aircall/blocks 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import * as React$1 from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 import { VariantProps } from "class-variance-authority";
 import * as _tanstack_react_form0 from "@tanstack/react-form";
-import { DeepKeys, DeepKeysOfType, FieldAsyncValidateOrFn, FieldValidateOrFn } from "@tanstack/react-form";
+import { DeepKeys, DeepKeysOfType, DeepValue, FieldAsyncValidateOrFn, FieldListeners, FieldValidateOrFn, FieldValidators } from "@tanstack/react-form";
 import { useRender } from "@base-ui/react/use-render";
 import * as class_variance_authority_types0 from "class-variance-authority/types";
 
@@ -1284,17 +1284,33 @@ declare const useForm: <TFormData, TOnMount extends _tanstack_react_form0.FormVa
   readonly CardSaveBar: typeof CardSaveBar;
 }>;
 declare const withForm: <TFormData, TOnMount extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnChange extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnChangeAsync extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TOnBlur extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnBlurAsync extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TOnSubmit extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnSubmitAsync extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TOnDynamic extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnDynamicAsync extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TOnServer extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TSubmitMeta, TRenderProps extends object = {}>({
-  render,
-  props
-}: _tanstack_react_form0.WithFormProps<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta, {}, {
-  readonly SubmitButton: typeof SubmitButton;
-  readonly CardSaveBar: typeof CardSaveBar;
-}, TRenderProps>) => React$1.FunctionComponent<React$1.PropsWithChildren<NoInfer<[unknown] extends [TRenderProps] ? any : TRenderProps> & {
-  form: _tanstack_react_form0.AppFieldExtendedReactFormApi<[unknown] extends [TFormData] ? any : TFormData, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnMount] ? [TOnMount] extends [TOnMount & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnMount : TOnMount, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnChange] ? [TOnChange] extends [TOnChange & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnChange : TOnChange, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnChangeAsync] ? [TOnChangeAsync] extends [TOnChangeAsync & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnChangeAsync : TOnChangeAsync, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnBlur] ? [TOnBlur] extends [TOnBlur & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnBlur : TOnBlur, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnBlurAsync] ? [TOnBlurAsync] extends [TOnBlurAsync & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnBlurAsync : TOnBlurAsync, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnSubmit] ? [TOnSubmit] extends [TOnSubmit & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnSubmit : TOnSubmit, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnSubmitAsync] ? [TOnSubmitAsync] extends [TOnSubmitAsync & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnSubmitAsync : TOnSubmitAsync, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnDynamic] ? [TOnDynamic] extends [TOnDynamic & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnDynamic : TOnDynamic, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnDynamicAsync] ? [TOnDynamicAsync] extends [TOnDynamicAsync & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnDynamicAsync : TOnDynamicAsync, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnServer] ? [TOnServer] extends [TOnServer & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnServer : TOnServer, [unknown] extends [TSubmitMeta] ? any : TSubmitMeta, {}, {
+    render,
+    props
+  }: _tanstack_react_form0.WithFormProps<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, TSubmitMeta, {}, {
     readonly SubmitButton: typeof SubmitButton;
     readonly CardSaveBar: typeof CardSaveBar;
-  }>;
-}>>;
+  }, TRenderProps>) => React$1.FunctionComponent<React$1.PropsWithChildren<NoInfer<[unknown] extends [TRenderProps] ? any : TRenderProps> & {
+    form: _tanstack_react_form0.AppFieldExtendedReactFormApi<[unknown] extends [TFormData] ? any : TFormData, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnMount] ? [TOnMount] extends [TOnMount & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnMount : TOnMount, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnChange] ? [TOnChange] extends [TOnChange & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnChange : TOnChange, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnChangeAsync] ? [TOnChangeAsync] extends [TOnChangeAsync & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnChangeAsync : TOnChangeAsync, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnBlur] ? [TOnBlur] extends [TOnBlur & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnBlur : TOnBlur, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnBlurAsync] ? [TOnBlurAsync] extends [TOnBlurAsync & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnBlurAsync : TOnBlurAsync, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnSubmit] ? [TOnSubmit] extends [TOnSubmit & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnSubmit : TOnSubmit, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnSubmitAsync] ? [TOnSubmitAsync] extends [TOnSubmitAsync & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnSubmitAsync : TOnSubmitAsync, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnDynamic] ? [TOnDynamic] extends [TOnDynamic & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnDynamic : TOnDynamic, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnDynamicAsync] ? [TOnDynamicAsync] extends [TOnDynamicAsync & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnDynamicAsync : TOnDynamicAsync, [_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined] extends [TOnServer] ? [TOnServer] extends [TOnServer & (_tanstack_react_form0.FormValidateOrFn<TFormData> | undefined)] ? any : TOnServer : TOnServer, [unknown] extends [TSubmitMeta] ? any : TSubmitMeta, {}, {
+      readonly SubmitButton: typeof SubmitButton;
+      readonly CardSaveBar: typeof CardSaveBar;
+    }>;
+  }>>, withFieldGroup: <TFieldGroupData, TSubmitMeta, TRenderProps extends object = {}>({
+    render,
+    props,
+    defaultValues
+  }: _tanstack_react_form0.WithFieldGroupProps<TFieldGroupData, {}, {
+    readonly SubmitButton: typeof SubmitButton;
+    readonly CardSaveBar: typeof CardSaveBar;
+  }, TSubmitMeta, TRenderProps>) => <TFormData, TFields extends _tanstack_react_form0.DeepKeysOfType<TFormData, TFieldGroupData | null | undefined> | _tanstack_react_form0.FieldsMap<TFormData, TFieldGroupData>, TOnMount extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnChange extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnChangeAsync extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TOnBlur extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnBlurAsync extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TOnSubmit extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnSubmitAsync extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TOnDynamic extends _tanstack_react_form0.FormValidateOrFn<TFormData> | undefined, TOnDynamicAsync extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TOnServer extends _tanstack_react_form0.FormAsyncValidateOrFn<TFormData> | undefined, TFormSubmitMeta>(params: React$1.PropsWithChildren<NoInfer<TRenderProps> & {
+    form: _tanstack_react_form0.AppFieldExtendedReactFormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnDynamic, TOnDynamicAsync, TOnServer, unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta, {}, {
+      readonly SubmitButton: typeof SubmitButton;
+      readonly CardSaveBar: typeof CardSaveBar;
+    }> | _tanstack_react_form0.AppFieldExtendedReactFieldGroupApi<unknown, TFormData, string | _tanstack_react_form0.FieldsMap<unknown, TFormData>, any, any, any, any, any, any, any, any, any, any, unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta, {}, {
+      readonly SubmitButton: typeof SubmitButton;
+      readonly CardSaveBar: typeof CardSaveBar;
+    }>;
+    fields: TFields;
+  }>) => ReturnType<React$1.FunctionComponent>;
 //#endregion
 //#region src/form/form-context.d.ts
 /**
@@ -1344,26 +1360,62 @@ type BoundForm = {
   };
   AppField: (...args: never[]) => unknown;
 };
-type FieldValidator<TFormData, TName> = TName extends DeepKeys<TFormData> ? FieldValidateOrFn<TFormData, TName> : never;
-type FieldAsyncValidator<TFormData, TName> = TName extends DeepKeys<TFormData> ? FieldAsyncValidateOrFn<TFormData, TName> : never;
-/** Field validators typed against the field's value — the `validators` prop of every wrapper. */
-type FormFieldValidators<TFormData, TName> = {
-  onMount?: FieldValidator<TFormData, TName>;
-  onChange?: FieldValidator<TFormData, TName>;
-  onChangeAsync?: FieldAsyncValidator<TFormData, TName>;
-  onChangeAsyncDebounceMs?: number;
-  onBlur?: FieldValidator<TFormData, TName>;
-  onBlurAsync?: FieldAsyncValidator<TFormData, TName>;
-  onBlurAsyncDebounceMs?: number;
-  onSubmit?: FieldValidator<TFormData, TName>;
-  onSubmitAsync?: FieldAsyncValidator<TFormData, TName>;
+/**
+ * Field validators typed against the field's value — the `validators` prop of every wrapper.
+ *
+ * Reuses TanStack's own `FieldValidators` (the exact interface `AppField` accepts) instead of a
+ * hand-rolled mirror, so every slot AppField supports is exposed with identical typing:
+ * `onMount`, `onChange`/`onChangeAsync`/`onChangeListenTo`, `onBlur`/`onBlurAsync`/`onBlurListenTo`,
+ * `onSubmit`/`onSubmitAsync`, `onDynamic`/`onDynamicAsync`, plus the `*DebounceMs` knobs.
+ *
+ * The per-slot validator generics can't be inferred here (the wrapper is generic over `TForm`/
+ * `TName`, not a generic *function* like `AppField`), so each is instantiated to its widest
+ * `FieldValidateOrFn`/`FieldAsyncValidateOrFn`. `value` still infers as the field's real type
+ * because `TData` (`DeepValue<TFormData, TName>`) is concrete. The outer conditional keeps `TName`
+ * unconstrained at the boundary so `DeepKeysOfType` subsets (e.g. the string-only Select keys)
+ * resolve without a constraint clash, exactly like the previous guard.
+ */
+type FormFieldValidators<TFormData, TName> = TName extends DeepKeys<TFormData> ? FieldValidators<TFormData, TName, DeepValue<TFormData, TName>, FieldValidateOrFn<TFormData, TName>, FieldValidateOrFn<TFormData, TName>, FieldAsyncValidateOrFn<TFormData, TName>, FieldValidateOrFn<TFormData, TName>, FieldAsyncValidateOrFn<TFormData, TName>, FieldValidateOrFn<TFormData, TName>, FieldAsyncValidateOrFn<TFormData, TName>, FieldValidateOrFn<TFormData, TName>, FieldAsyncValidateOrFn<TFormData, TName>> : never;
+/**
+ * The full `AppField` binding surface every wrapper forwards, typed against the field's value.
+ *
+ * This is the **single source of truth** for which `form.AppField` props the `Form*Field` wrappers
+ * pass through — spread it into each wrapper's props so the set can't drift per-wrapper. The
+ * `app-field-coverage` type test asserts this stays in sync with `AppField`'s real prop surface:
+ * every `AppField` prop must be forwarded here or appear in that test's explicit omission list.
+ *
+ * Forwarded: `validators`, `listeners`, `defaultValue`, `asyncDebounceMs`, `asyncAlways`.
+ * Deliberately omitted (see the coverage test): `name`/`children` (owned by the wrapper),
+ * `defaultMeta`/`disableErrorFlat` (advanced escape hatches that fight the shared shell).
+ */
+type FieldBindingProps<TFormData, TName> = TName extends DeepKeys<TFormData> ? {
+  validators?: FormFieldValidators<TFormData, TName>;
+  listeners?: FieldListeners<TFormData, TName>;
+  defaultValue?: DeepValue<TFormData, TName>;
+  asyncDebounceMs?: number;
+  asyncAlways?: boolean;
+} : never;
+/**
+ * Presentational necessity props every wrapper exposes, forwarded to the DS `FieldLabel` to mark a
+ * field required/optional in the label. Enforcement stays in `validators` — this is label-only.
+ * Shared so the set can't drift per-wrapper.
+ */
+type NecessityProps = {
+  required?: boolean;
+  necessityIndicator?: 'icon' | 'label';
 };
 type FormFieldBaseProps<TData, TControl> = {
   form: Pick<BoundForm, 'AppField'>;
   name: string;
   validators?: unknown;
-  label: string;
-  description?: string; /** Builds the primitive-specific wiring bundle handed to `children`. */
+  listeners?: unknown;
+  defaultValue?: unknown;
+  asyncDebounceMs?: number;
+  asyncAlways?: boolean;
+  label?: string;
+  description?: string;
+  required?: boolean;
+  necessityIndicator?: 'icon' | 'label'; /** Builds the primitive-specific wiring bundle handed to `children`. */
   buildControl: (field: TypedField<TData>) => TControl;
   children: (field: TypedField<TData>, control: TControl) => React$1.ReactNode;
 };
@@ -1393,11 +1445,10 @@ type SelectControl = {
 type FormSelectFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], string>> = {
   /** The form instance from `useForm()` — threaded as a prop so `name`/`validators` are typed. */form: TForm;
   name: TName;
-  label: string;
-  description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>; /** Compose the Select yourself; spread the bundles. Trigger/content stay fully customizable. */
+  label?: string;
+  description?: string; /** Compose the Select yourself; spread the bundles. Trigger/content stay fully customizable. */
   children: (field: TypedField<string>, control: SelectControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Select field wrapper. Owns the binding + shared `Field/Label/Error` shell, and hands the
  * consumer pre-wired `selectProps` / `selectTriggerProps` to spread onto `@aircall/ds` Select
@@ -1434,11 +1485,10 @@ type InputControl = {
 type FormInputFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], string>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<string>, control: InputControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Text-input field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
  * with an `inputProps` bundle. Compose the input yourself (add adornments, counters, prefixes).
@@ -1470,11 +1520,10 @@ type ComboboxControl = {
 type FormComboboxFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], string>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<string>, control: ComboboxControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Combobox (searchable single-select) field wrapper for **string-valued** fields. Same threaded-
  * `form` typing and shared shell as the other wrappers; the render-prop hands you `comboboxProps`
@@ -1515,11 +1564,10 @@ type MultiComboboxControl = {
 type FormMultiComboboxFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], string[]>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<string[]>, control: MultiComboboxControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Multi-select combobox field wrapper — same threaded-`form` typing and shared shell as
  * `FormSelectField`, with `comboboxProps` / `comboboxInputProps` bundles. `name` is restricted
@@ -1552,11 +1600,10 @@ type TextareaControl = {
 type FormTextareaFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], string>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<string>, control: TextareaControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Multiline text-input field wrapper — same threaded-`form` typing and shared shell as
  * `FormSelectField`, with a `textareaProps` bundle. Compose the textarea yourself (rows,
@@ -1586,11 +1633,10 @@ type RadioGroupControl = {
 type FormRadioGroupFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], string>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<string>, control: RadioGroupControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Radio-group field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
  * with a `radioGroupProps` bundle. Compose the items yourself. `name` is restricted to the
@@ -1623,11 +1669,10 @@ type OTPControl = {
 type FormOTPFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], string>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<string>, control: OTPControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * One-time-code field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
  * with an `otpProps` bundle. Compose the slots yourself. `name` is restricted to the form's
@@ -1656,11 +1701,10 @@ type SwitchControl = {
 type FormSwitchFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], boolean>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<boolean>, control: SwitchControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Toggle field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
  * with a `switchProps` bundle. `name` is restricted to the form's **boolean** fields — a
@@ -1673,38 +1717,37 @@ type FormSwitchFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<
  */
 declare function FormSwitchField<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], boolean>>(props: FormSwitchFieldProps<TForm, TName>): react_jsx_runtime0.JSX.Element;
 //#endregion
-//#region src/components/form-number-field.d.ts
+//#region src/components/form-numeric-field.d.ts
 /**
- * Wiring bundle handed to a `FormNumberField` child. Spread `numberProps` onto a DS `Input`
- * with `type="number"` — value/onChange/onBlur/aria are pre-wired (empty input coerces to `0`).
+ * Wiring bundle handed to a `FormNumericField` child. Spread `numericProps` onto a DS
+ * `NumericInput` — value/onValueChange/onBlur/aria are pre-wired (a cleared input coerces to `0`).
  */
-type NumberControl = {
-  numberProps: {
+type NumericControl = {
+  numericProps: {
     value: number;
-    onChange: (event: React$1.ChangeEvent<HTMLInputElement>) => void;
+    onValueChange: (value: number | null) => void;
     onBlur: () => void;
     'aria-invalid': true | undefined;
   };
 };
-type FormNumberFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], number>> = {
+type FormNumericFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], number>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
-  children: (field: TypedField<number>, control: NumberControl) => React$1.ReactNode;
-};
+  children: (field: TypedField<number>, control: NumericControl) => React$1.ReactNode;
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
- * Numeric-input field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
- * with a `numberProps` bundle. `name` is restricted to the form's **number** fields — a
- * string/boolean `name` is a type error.
+ * Numeric field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
+ * with a `numericProps` bundle for the DS `NumericInput` (prefer it over `Input type="number"`).
+ * `name` is restricted to the form's **number** fields — a string/boolean `name` is a type error.
  *
  * @example
- * <FormNumberField form={form} name="age" label="Age" validators={{ onChange }}>
- *   {(field, { numberProps }) => <Input type="number" {...numberProps} />}
- * </FormNumberField>
+ * <FormNumericField form={form} name="age" label="Age" validators={{ onChange }}>
+ *   {(field, { numericProps }) => <NumericInput {...numericProps} />}
+ * </FormNumericField>
  */
-declare function FormNumberField<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], number>>(props: FormNumberFieldProps<TForm, TName>): react_jsx_runtime0.JSX.Element;
+declare function FormNumericField<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], number>>(props: FormNumericFieldProps<TForm, TName>): react_jsx_runtime0.JSX.Element;
 //#endregion
 //#region src/components/form-slider-field.d.ts
 /**
@@ -1721,11 +1764,10 @@ type SliderControl = {
 type FormSliderFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], number>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<number>, control: SliderControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Slider field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
  * with a `sliderProps` bundle. `name` is restricted to the form's **number** fields; the bundle
@@ -1754,11 +1796,10 @@ type ToggleGroupControl = {
 type FormToggleGroupFieldProps<TForm extends BoundForm, TName extends DeepKeysOfType<TForm['state']['values'], string | null>> = {
   form: TForm;
   name: TName;
-  label: string;
+  label?: string;
   description?: string;
-  validators?: FormFieldValidators<TForm['state']['values'], TName>;
   children: (field: TypedField<string | null>, control: ToggleGroupControl) => React$1.ReactNode;
-};
+} & FieldBindingProps<TForm['state']['values'], TName> & NecessityProps;
 /**
  * Single-select toggle-group field wrapper — same threaded-`form` typing and shared shell as
  * `FormSelectField`, with a `toggleGroupProps` bundle. `name` is restricted to the form's
@@ -2006,4 +2047,4 @@ declare namespace DashboardSidebarSubmenuSeparator {
   type Props = DashboardSidebarSubmenuSeparatorProps;
 }
 //#endregion
-export { BetaBadge, type BoundForm, CardSaveBar, type CardSaveBarProps, ChatbotExpandSuggestion, type ChatbotExpandSuggestionProps, ChatbotInput, type ChatbotInputProps, ChatbotPage, ChatbotPageBody, type ChatbotPageBodyProps, ChatbotPageContent, type ChatbotPageContentProps, ChatbotPageConversation, type ChatbotPageConversationProps, ChatbotPageFooter, type ChatbotPageFooterProps, ChatbotPageHeading, type ChatbotPageHeadingProps, ChatbotPageInputBar, type ChatbotPageInputBarProps, type ChatbotPageProps, ChatbotPanel, ChatbotPanelHeader, type ChatbotPanelHeaderProps, type ChatbotPanelProps, ChatbotPanelSuggestion, type ChatbotPanelSuggestionItem, type ChatbotPanelSuggestionProps, ChatbotPanelTrigger, type ChatbotPanelTriggerProps, ChatbotResponseBlock, type ChatbotResponseBlockFeedback, type ChatbotResponseBlockProps, ChatbotSidebar, type ChatbotSidebarConversation, ChatbotUserMessage, type ChatbotUserMessageProps, type ComboboxControl, ComingSoonDescription, ComingSoonEmptyState, ComingSoonMedia, ComingSoonTitle, CommonForm, CopyButton, CopyButtonIcon, CopyButtonLabel, DashboardPage, DashboardPageBanner, DashboardPageContent, DashboardPageHeader, DashboardPageHeaderAction, DashboardPageHeaderActions, DashboardPageHeaderDescription, DashboardPageHeaderNav, DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderSubtitle, DashboardPageHeaderTitle, DashboardPageHeaderTitleGroup, DashboardPageMain, DashboardPageTabs, DashboardSidebar, DashboardSidebarContent, DashboardSidebarFooter, DashboardSidebarGroup, DashboardSidebarGroupLabel, DashboardSidebarHeader, DashboardSidebarMenu, DashboardSidebarMenuBadge, DashboardSidebarMenuButton, DashboardSidebarMenuItem, DashboardSidebarNav, type DashboardSidebarNavGroup, type DashboardSidebarNavItem, type DashboardSidebarNavItemAction, type DashboardSidebarNavItemLink, type DashboardSidebarNavItemSubmenu, type DashboardSidebarNavSubmenuItem, DashboardSidebarProvider, DashboardSidebarSubmenu, DashboardSidebarSubmenuItem, DashboardSidebarSubmenuSeparator, DashboardSidebarTrigger, DashboardStandalonePage, DashboardStandalonePageAction, DashboardStandalonePageActions, DashboardStandalonePageContent, DashboardStandalonePageHeader, DashboardStandalonePageTitle, DeprecatedBadge, EmptyState, EmptyStateActions, EmptyStateButton, EmptyStateDescription, EmptyStateExternalLink, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, FormComboboxField, type FormComboboxFieldProps, FormFieldBase, type FormFieldValidators, FormInputField, type FormInputFieldProps, FormMultiComboboxField, type FormMultiComboboxFieldProps, FormNumberField, type FormNumberFieldProps, FormOTPField, type FormOTPFieldProps, FormRadioGroupField, type FormRadioGroupFieldProps, FormSelectField, type FormSelectFieldProps, FormSliderField, type FormSliderFieldProps, FormSwitchField, type FormSwitchFieldProps, FormTextareaField, type FormTextareaFieldProps, FormToggleGroupField, type FormToggleGroupFieldProps, type InputControl, type MultiComboboxControl, NewBadge, NoDataDescription, NoDataEmptyState, NoDataMedia, NoDataTitle, NoSupportDescription, NoSupportEmptyState, NoSupportMedia, NoSupportTitle, NotFoundDescription, NotFoundEmptyState, NotFoundMedia, NotFoundTitle, type NumberControl, type OTPControl, ProfessionalBadge, type RadioGroupControl, RestrictedAccessDescription, RestrictedAccessEmptyState, RestrictedAccessMedia, RestrictedAccessTitle, RoleBadge, type RoleBadgeRole, SaveBar, type SaveBarProps, type SelectControl, type SliderControl, SubmitButton, type SubmitButtonProps, type SwitchControl, type TextareaControl, type ToggleGroupControl, TrialBadge, type TypedField, UnknownErrorDescription, UnknownErrorEmptyState, UnknownErrorMedia, UnknownErrorTitle, fieldContext, formContext, toFieldErrors, useCopyToClipboard, useSidebar as useDashboardSidebar, useFieldContext, useForm, useFormContext, withForm };
+export { BetaBadge, type BoundForm, CardSaveBar, type CardSaveBarProps, ChatbotExpandSuggestion, type ChatbotExpandSuggestionProps, ChatbotInput, type ChatbotInputProps, ChatbotPage, ChatbotPageBody, type ChatbotPageBodyProps, ChatbotPageContent, type ChatbotPageContentProps, ChatbotPageConversation, type ChatbotPageConversationProps, ChatbotPageFooter, type ChatbotPageFooterProps, ChatbotPageHeading, type ChatbotPageHeadingProps, ChatbotPageInputBar, type ChatbotPageInputBarProps, type ChatbotPageProps, ChatbotPanel, ChatbotPanelHeader, type ChatbotPanelHeaderProps, type ChatbotPanelProps, ChatbotPanelSuggestion, type ChatbotPanelSuggestionItem, type ChatbotPanelSuggestionProps, ChatbotPanelTrigger, type ChatbotPanelTriggerProps, ChatbotResponseBlock, type ChatbotResponseBlockFeedback, type ChatbotResponseBlockProps, ChatbotSidebar, type ChatbotSidebarConversation, ChatbotUserMessage, type ChatbotUserMessageProps, type ComboboxControl, ComingSoonDescription, ComingSoonEmptyState, ComingSoonMedia, ComingSoonTitle, CommonForm, CopyButton, CopyButtonIcon, CopyButtonLabel, DashboardPage, DashboardPageBanner, DashboardPageContent, DashboardPageHeader, DashboardPageHeaderAction, DashboardPageHeaderActions, DashboardPageHeaderDescription, DashboardPageHeaderNav, DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderSubtitle, DashboardPageHeaderTitle, DashboardPageHeaderTitleGroup, DashboardPageMain, DashboardPageTabs, DashboardSidebar, DashboardSidebarContent, DashboardSidebarFooter, DashboardSidebarGroup, DashboardSidebarGroupLabel, DashboardSidebarHeader, DashboardSidebarMenu, DashboardSidebarMenuBadge, DashboardSidebarMenuButton, DashboardSidebarMenuItem, DashboardSidebarNav, type DashboardSidebarNavGroup, type DashboardSidebarNavItem, type DashboardSidebarNavItemAction, type DashboardSidebarNavItemLink, type DashboardSidebarNavItemSubmenu, type DashboardSidebarNavSubmenuItem, DashboardSidebarProvider, DashboardSidebarSubmenu, DashboardSidebarSubmenuItem, DashboardSidebarSubmenuSeparator, DashboardSidebarTrigger, DashboardStandalonePage, DashboardStandalonePageAction, DashboardStandalonePageActions, DashboardStandalonePageContent, DashboardStandalonePageHeader, DashboardStandalonePageTitle, DeprecatedBadge, EmptyState, EmptyStateActions, EmptyStateButton, EmptyStateDescription, EmptyStateExternalLink, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, type FieldBindingProps, FormComboboxField, type FormComboboxFieldProps, FormFieldBase, type FormFieldValidators, FormInputField, type FormInputFieldProps, FormMultiComboboxField, type FormMultiComboboxFieldProps, FormNumericField, type FormNumericFieldProps, FormOTPField, type FormOTPFieldProps, FormRadioGroupField, type FormRadioGroupFieldProps, FormSelectField, type FormSelectFieldProps, FormSliderField, type FormSliderFieldProps, FormSwitchField, type FormSwitchFieldProps, FormTextareaField, type FormTextareaFieldProps, FormToggleGroupField, type FormToggleGroupFieldProps, type InputControl, type MultiComboboxControl, type NecessityProps, NewBadge, NoDataDescription, NoDataEmptyState, NoDataMedia, NoDataTitle, NoSupportDescription, NoSupportEmptyState, NoSupportMedia, NoSupportTitle, NotFoundDescription, NotFoundEmptyState, NotFoundMedia, NotFoundTitle, type NumericControl, type OTPControl, ProfessionalBadge, type RadioGroupControl, RestrictedAccessDescription, RestrictedAccessEmptyState, RestrictedAccessMedia, RestrictedAccessTitle, RoleBadge, type RoleBadgeRole, SaveBar, type SaveBarProps, type SelectControl, type SliderControl, SubmitButton, type SubmitButtonProps, type SwitchControl, type TextareaControl, type ToggleGroupControl, TrialBadge, type TypedField, UnknownErrorDescription, UnknownErrorEmptyState, UnknownErrorMedia, UnknownErrorTitle, fieldContext, formContext, toFieldErrors, useCopyToClipboard, useSidebar as useDashboardSidebar, useFieldContext, useForm, useFormContext, withFieldGroup, withForm };

package/dist/index.js

@@ -1930,7 +1930,7 @@ const CommonForm = createFormHook({
 	}
 });
 const useForm = CommonForm.useAppForm;
-const { withForm } = CommonForm;
+const { withForm, withFieldGroup } = CommonForm;
 
 //#endregion
 //#region src/form/field-errors.ts
@@ -1950,12 +1950,16 @@ function toFieldErrors(errors) {
 
 //#endregion
 //#region src/components/form-field.tsx
-function FormFieldShell({ label, description, children }) {
+function FormFieldShell({ label, description, required, necessityIndicator, children }) {
 	const errors = useFieldContext().state.meta.errors;
 	return /* @__PURE__ */ jsxs(Field, {
 		"data-invalid": errors.length > 0 ? true : void 0,
 		children: [
-			/* @__PURE__ */ jsx(FieldLabel, { children: label }),
+			label && /* @__PURE__ */ jsx(FieldLabel, {
+				required,
+				necessityIndicator,
+				children: label
+			}),
 			description && /* @__PURE__ */ jsx(FieldDescription, { children: description }),
 			children,
 			/* @__PURE__ */ jsx(FieldError, { errors: toFieldErrors(errors) })
@@ -1968,14 +1972,20 @@ function FormFieldShell({ label, description, children }) {
 * the AppField + shared shell. `TData`/`TControl` carry the precise field + bundle shapes through.
 */
 function FormFieldBase(props) {
-	const { form, name, validators, label, description, buildControl, children } = props;
+	const { form, name, validators, listeners, defaultValue, asyncDebounceMs, asyncAlways, label, description, required, necessityIndicator, buildControl, children } = props;
 	const AppField = form.AppField;
 	return /* @__PURE__ */ jsx(AppField, {
 		name,
 		validators,
+		listeners,
+		defaultValue,
+		asyncDebounceMs,
+		asyncAlways,
 		children: (field) => /* @__PURE__ */ jsx(FormFieldShell, {
 			label,
 			description,
+			required,
+			necessityIndicator,
 			children: children(field, buildControl(field))
 		})
 	});
@@ -2235,29 +2245,29 @@ function FormSwitchField(props) {
 }
 
 //#endregion
-//#region src/components/form-number-field.tsx
-function numberControl(field) {
-	return { numberProps: {
+//#region src/components/form-numeric-field.tsx
+function numericControl(field) {
+	return { numericProps: {
 		value: field.state.value,
-		onChange: (event) => field.handleChange(event.target.value === "" ? 0 : event.target.valueAsNumber),
+		onValueChange: (value) => field.handleChange(value ?? 0),
 		onBlur: field.handleBlur,
 		"aria-invalid": field.state.meta.errors.length > 0 ? true : void 0
 	} };
 }
 /**
-* Numeric-input field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
-* with a `numberProps` bundle. `name` is restricted to the form's **number** fields — a
-* string/boolean `name` is a type error.
+* Numeric field wrapper — same threaded-`form` typing and shared shell as `FormSelectField`,
+* with a `numericProps` bundle for the DS `NumericInput` (prefer it over `Input type="number"`).
+* `name` is restricted to the form's **number** fields — a string/boolean `name` is a type error.
 *
 * @example
-* <FormNumberField form={form} name="age" label="Age" validators={{ onChange }}>
-*   {(field, { numberProps }) => <Input type="number" {...numberProps} />}
-* </FormNumberField>
+* <FormNumericField form={form} name="age" label="Age" validators={{ onChange }}>
+*   {(field, { numericProps }) => <NumericInput {...numericProps} />}
+* </FormNumericField>
 */
-function FormNumberField(props) {
+function FormNumericField(props) {
 	return /* @__PURE__ */ jsx(FormFieldBase, {
 		...props,
-		buildControl: numberControl
+		buildControl: numericControl
 	});
 }
 
@@ -2651,4 +2661,4 @@ function DashboardSidebarNav({ groups, renderLink }) {
 }
 
 //#endregion
-export { BetaBadge, CardSaveBar, ChatbotExpandSuggestion, ChatbotInput, ChatbotPage, ChatbotPageBody, ChatbotPageContent, ChatbotPageConversation, ChatbotPageFooter, ChatbotPageHeading, ChatbotPageInputBar, ChatbotPanel, ChatbotPanelHeader, ChatbotPanelSuggestion, ChatbotPanelTrigger, ChatbotResponseBlock, ChatbotSidebar, ChatbotUserMessage, ComingSoonDescription, ComingSoonEmptyState, ComingSoonMedia, ComingSoonTitle, CommonForm, CopyButton, CopyButtonIcon, CopyButtonLabel, DashboardPage, DashboardPageBanner, DashboardPageContent, DashboardPageHeader, DashboardPageHeaderAction, DashboardPageHeaderActions, DashboardPageHeaderDescription, DashboardPageHeaderNav, DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderSubtitle, DashboardPageHeaderTitle, DashboardPageHeaderTitleGroup, DashboardPageMain, DashboardPageTabs, DashboardSidebar, DashboardSidebarContent, DashboardSidebarFooter, DashboardSidebarGroup, DashboardSidebarGroupLabel, DashboardSidebarHeader, DashboardSidebarMenu, DashboardSidebarMenuBadge, DashboardSidebarMenuButton, DashboardSidebarMenuItem, DashboardSidebarNav, DashboardSidebarProvider, DashboardSidebarSubmenu, DashboardSidebarSubmenuItem, DashboardSidebarSubmenuSeparator, DashboardSidebarTrigger, DashboardStandalonePage, DashboardStandalonePageAction, DashboardStandalonePageActions, DashboardStandalonePageContent, DashboardStandalonePageHeader, DashboardStandalonePageTitle, DeprecatedBadge, EmptyState, EmptyStateActions, EmptyStateButton, EmptyStateDescription, EmptyStateExternalLink, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, FormComboboxField, FormFieldBase, FormInputField, FormMultiComboboxField, FormNumberField, FormOTPField, FormRadioGroupField, FormSelectField, FormSliderField, FormSwitchField, FormTextareaField, FormToggleGroupField, NewBadge, NoDataDescription, NoDataEmptyState, NoDataMedia, NoDataTitle, NoSupportDescription, NoSupportEmptyState, NoSupportMedia, NoSupportTitle, NotFoundDescription, NotFoundEmptyState, NotFoundMedia, NotFoundTitle, ProfessionalBadge, RestrictedAccessDescription, RestrictedAccessEmptyState, RestrictedAccessMedia, RestrictedAccessTitle, RoleBadge, SaveBar, SubmitButton, TrialBadge, UnknownErrorDescription, UnknownErrorEmptyState, UnknownErrorMedia, UnknownErrorTitle, fieldContext, formContext, toFieldErrors, useCopyToClipboard, useSidebar as useDashboardSidebar, useFieldContext, useForm, useFormContext, withForm };
+export { BetaBadge, CardSaveBar, ChatbotExpandSuggestion, ChatbotInput, ChatbotPage, ChatbotPageBody, ChatbotPageContent, ChatbotPageConversation, ChatbotPageFooter, ChatbotPageHeading, ChatbotPageInputBar, ChatbotPanel, ChatbotPanelHeader, ChatbotPanelSuggestion, ChatbotPanelTrigger, ChatbotResponseBlock, ChatbotSidebar, ChatbotUserMessage, ComingSoonDescription, ComingSoonEmptyState, ComingSoonMedia, ComingSoonTitle, CommonForm, CopyButton, CopyButtonIcon, CopyButtonLabel, DashboardPage, DashboardPageBanner, DashboardPageContent, DashboardPageHeader, DashboardPageHeaderAction, DashboardPageHeaderActions, DashboardPageHeaderDescription, DashboardPageHeaderNav, DashboardPageHeaderNavBack, DashboardPageHeaderPrefix, DashboardPageHeaderSubtitle, DashboardPageHeaderTitle, DashboardPageHeaderTitleGroup, DashboardPageMain, DashboardPageTabs, DashboardSidebar, DashboardSidebarContent, DashboardSidebarFooter, DashboardSidebarGroup, DashboardSidebarGroupLabel, DashboardSidebarHeader, DashboardSidebarMenu, DashboardSidebarMenuBadge, DashboardSidebarMenuButton, DashboardSidebarMenuItem, DashboardSidebarNav, DashboardSidebarProvider, DashboardSidebarSubmenu, DashboardSidebarSubmenuItem, DashboardSidebarSubmenuSeparator, DashboardSidebarTrigger, DashboardStandalonePage, DashboardStandalonePageAction, DashboardStandalonePageActions, DashboardStandalonePageContent, DashboardStandalonePageHeader, DashboardStandalonePageTitle, DeprecatedBadge, EmptyState, EmptyStateActions, EmptyStateButton, EmptyStateDescription, EmptyStateExternalLink, EmptyStateHeader, EmptyStateMedia, EmptyStateTitle, FormComboboxField, FormFieldBase, FormInputField, FormMultiComboboxField, FormNumericField, FormOTPField, FormRadioGroupField, FormSelectField, FormSliderField, FormSwitchField, FormTextareaField, FormToggleGroupField, NewBadge, NoDataDescription, NoDataEmptyState, NoDataMedia, NoDataTitle, NoSupportDescription, NoSupportEmptyState, NoSupportMedia, NoSupportTitle, NotFoundDescription, NotFoundEmptyState, NotFoundMedia, NotFoundTitle, ProfessionalBadge, RestrictedAccessDescription, RestrictedAccessEmptyState, RestrictedAccessMedia, RestrictedAccessTitle, RoleBadge, SaveBar, SubmitButton, TrialBadge, UnknownErrorDescription, UnknownErrorEmptyState, UnknownErrorMedia, UnknownErrorTitle, fieldContext, formContext, toFieldErrors, useCopyToClipboard, useSidebar as useDashboardSidebar, useFieldContext, useForm, useFormContext, withFieldGroup, withForm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aircall/blocks",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "private": false,
   "sideEffects": [
@@ -81,7 +81,7 @@
     "vite": "7.3.1",
     "vitest": "4.0.17",
     "zod": "4.4.3",
-    "@aircall/ds": "0.16.1",
+    "@aircall/ds": "0.17.0",
     "@aircall/hooks": "0.5.1"
   },
   "keywords": [
@@ -102,6 +102,7 @@
     "sb:dev": "storybook dev -p 6009",
     "sb:build": "storybook build",
     "sb:build:chromatic": "storybook build --test --stats-json",
+    "test": "vitest --project=unit",
     "sb:test": "vitest --project=storybook",
     "chromatic": "chromatic --storybook-build-dir=./storybook-static"
   },