@reformer/cdk 1.0.0-beta.1

package/dist/components/form-field/FormField.d.ts

@@ -0,0 +1,107 @@
+import { FormFieldRoot } from './FormFieldRoot';
+import { FormFieldLabel } from './FormFieldLabel';
+import { FormFieldControl } from './FormFieldControl';
+import { FormFieldError } from './FormFieldError';
+import { FormFieldDescription } from './FormFieldDescription';
+/**
+ * Compound component type with all sub-components attached
+ */
+type FormFieldComponent = typeof FormFieldRoot & {
+    Root: typeof FormFieldRoot;
+    Label: typeof FormFieldLabel;
+    Control: typeof FormFieldControl;
+    Error: typeof FormFieldError;
+    Description: typeof FormFieldDescription;
+};
+/**
+ * FormField - Headless compound component for accessible form field anatomy.
+ *
+ * Provides complete freedom in building field UI while handling all accessible
+ * ID wiring (htmlFor, aria-labelledby, aria-describedby, aria-errormessage)
+ * and field state management internally.
+ *
+ * ## Features
+ * - **Headless** — complete freedom in building UI, no styles imposed
+ * - **Compound Components** — declarative API via nested components
+ * - **Accessible by default** — all ARIA relationships wired automatically
+ * - **Type Safe** — full TypeScript support with generics
+ *
+ * ## Sub-components
+ * - `FormField.Root` — context provider, accepts `control` and optional `id`
+ * - `FormField.Label` — `<label>` with automatic `htmlFor` and required indicator
+ * - `FormField.Control` — auto-renders `control.component` or wraps custom children
+ * - `FormField.Error` — error message with `role="alert"`, supports multi-error
+ * - `FormField.Description` — helper text with stable `id` for `aria-describedby`
+ *
+ * @example Minimal (auto-renders everything from field config)
+ * ```tsx
+ * <FormField.Root control={control.email}>
+ *   <FormField.Label />
+ *   <FormField.Control />
+ *   <FormField.Error />
+ * </FormField.Root>
+ * ```
+ *
+ * @example Full control with custom styling
+ * ```tsx
+ * <FormField.Root control={control.email} hasDescription>
+ *   <div className="space-y-1">
+ *     <FormField.Label className="text-sm font-medium text-gray-700" />
+ *
+ *     <FormField.Control asChild>
+ *       <Input type="email" className="border rounded-md px-3 py-2 w-full" />
+ *     </FormField.Control>
+ *
+ *     <FormField.Description className="text-xs text-gray-500">
+ *       We'll never share your email.
+ *     </FormField.Description>
+ *
+ *     <FormField.Error className="text-xs text-red-600" />
+ *   </div>
+ * </FormField.Root>
+ * ```
+ *
+ * @example Multiple errors with custom rendering
+ * ```tsx
+ * <FormField.Root control={control.password}>
+ *   <FormField.Label />
+ *   <FormField.Control />
+ *   <FormField.Error
+ *     multi
+ *     render={(err) => (
+ *       <span className={err.severity === 'warning' ? 'text-yellow-600' : 'text-red-600'}>
+ *         {err.message}
+ *       </span>
+ *     )}
+ *   />
+ * </FormField.Root>
+ * ```
+ *
+ * @example Using useFormField hook for full customization
+ * ```tsx
+ * import { useFormField } from '@reformer/cdk/form-field';
+ *
+ * function EmailField({ control }: { control: FieldNode<string> }) {
+ *   const { labelProps, controlProps, errorProps, state, ids } = useFormField(control);
+ *
+ *   return (
+ *     <div>
+ *       <label {...labelProps}>{state.label}</label>
+ *       <Input
+ *         {...controlProps}
+ *         aria-describedby={ids.descriptionId}
+ *         type="email"
+ *       />
+ *       <p id={ids.descriptionId} className="text-xs text-gray-500">
+ *         Helper text
+ *       </p>
+ *       {state.shouldShowError && (
+ *         <p {...errorProps} className="text-xs text-red-600">{state.error}</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare const FormField: FormFieldComponent;
+export {};

package/dist/components/form-field/FormFieldContext.d.ts

@@ -0,0 +1,56 @@
+import { FormValue } from '@reformer/core';
+import { FormFieldContextValue } from './types';
+/**
+ * React context, который снабжает дочерние компоненты `FormField` (Label, Error,
+ * Hint, Control) текущим контролом. Создаётся `FormField.Root`. Читать через
+ * {@link useFormFieldContext}.
+ *
+ * @example
+ * ```tsx
+ * import { FormFieldContext } from '@reformer/cdk/form-field';
+ *
+ * function CurrentValue() {
+ *   const ctx = useContext(FormFieldContext);
+ *   return <pre>{JSON.stringify(ctx?.control.value)}</pre>;
+ * }
+ * ```
+ */
+export declare const FormFieldContext: import('react').Context<FormFieldContextValue<any> | null>;
+/**
+ * Хук для доступа к контексту `FormField`. Бросает исключение, если вызван
+ * вне `FormField.Root`.
+ *
+ * @returns Текущий {@link FormFieldContextValue}.
+ * @throws Error если используется вне `<FormField.Root>`.
+ *
+ * @example Счётчик символов рядом с label
+ * ```tsx
+ * import { useFormFieldContext } from '@reformer/cdk/form-field';
+ *
+ * function CharCount() {
+ *   const { control } = useFormFieldContext<string>();
+ *   return <small>{control.value.length} chars</small>;
+ * }
+ * ```
+ *
+ * @example Async pending-индикатор и required-астериск
+ * ```tsx
+ * function PendingBadge() {
+ *   const { pending, required, error } = useFormFieldContext();
+ *   if (pending) return <Spinner size="xs" aria-label="Проверяем..." />;
+ *   if (error) return <span className="text-red-600 text-xs">!</span>;
+ *   if (required) return <span className="text-gray-400">*</span>;
+ *   return null;
+ * }
+ *
+ * <FormField.Root control={form.username}>
+ *   <div className="flex items-center gap-2">
+ *     <FormField.Label />
+ *     <PendingBadge />
+ *   </div>
+ *   <FormField.Control />
+ *   <FormField.Error />
+ * </FormField.Root>
+ * ```
+ */
+export declare function useFormFieldContext<T extends FormValue = FormValue>(): FormFieldContextValue<T>;

package/dist/components/form-field/FormFieldControl.d.ts

@@ -0,0 +1,35 @@
+import { default as React } from 'react';
+import { FormFieldControlProps } from './types';
+/**
+ * FormField.Control - Renders the interactive form control.
+ *
+ * **Auto-render mode** (default): renders `control.component` with all necessary
+ * props pre-wired: `value`, `onChange`, `onBlur`, `disabled`, `aria-*` attributes,
+ * and all `componentProps` from the field config.
+ *
+ * **Custom children mode** (`asChild` or `children`): merges accessible props
+ * into the provided child element via Slot, letting you use any custom component.
+ *
+ * @example Auto-render (renders control.component)
+ * ```tsx
+ * <FormField.Root control={control.email}>
+ *   <FormField.Label />
+ *   <FormField.Control />
+ * </FormField.Root>
+ * ```
+ *
+ * @example Custom input with asChild (merges aria-* into your element)
+ * ```tsx
+ * <FormField.Control asChild>
+ *   <MyInput type="email" className="custom-input" />
+ * </FormField.Control>
+ * ```
+ *
+ * @example Custom children (same as asChild)
+ * ```tsx
+ * <FormField.Control>
+ *   <MyInput type="email" />
+ * </FormField.Control>
+ * ```
+ */
+export declare const FormFieldControl: React.ForwardRefExoticComponent<FormFieldControlProps & React.RefAttributes<HTMLElement>>;

package/dist/components/form-field/FormFieldDescription.d.ts

@@ -0,0 +1,30 @@
+import { FormFieldDescriptionProps } from './types';
+/**
+ * FormField.Description - Helper text for the form field.
+ *
+ * Renders with a stable `id` (descriptionId) that can be wired to
+ * `aria-describedby` on the control. To enable automatic wiring, pass
+ * `hasDescription` to the parent `FormField.Root`.
+ *
+ * @example
+ * ```tsx
+ * <FormField.Root control={control.email} hasDescription>
+ *   <FormField.Label />
+ *   <FormField.Control />
+ *   <FormField.Description className="text-xs text-gray-500">
+ *     We'll never share your email with anyone.
+ *   </FormField.Description>
+ *   <FormField.Error />
+ * </FormField.Root>
+ * ```
+ *
+ * @example With custom element (asChild)
+ * ```tsx
+ * <FormField.Description asChild>
+ *   <Tooltip content="More info">
+ *     <InfoIcon />
+ *   </Tooltip>
+ * </FormField.Description>
+ * ```
+ */
+export declare const FormFieldDescription: import('react').ForwardRefExoticComponent<FormFieldDescriptionProps & import('react').RefAttributes<HTMLParagraphElement>>;

package/dist/components/form-field/FormFieldError.d.ts

@@ -0,0 +1,36 @@
+import { FormFieldErrorProps } from './types';
+/**
+ * FormField.Error - Displays validation error message(s).
+ *
+ * Renders nothing when `shouldShowError` is false (field not touched or no errors).
+ * The first error paragraph receives `id={ids.errorId}` for `aria-errormessage` wiring.
+ *
+ * @example Single error (default)
+ * ```tsx
+ * <FormField.Error className="text-xs text-red-600" />
+ * ```
+ *
+ * @example All errors
+ * ```tsx
+ * <FormField.Error multi className="text-xs text-red-600" />
+ * ```
+ *
+ * @example Custom render per error
+ * ```tsx
+ * <FormField.Error
+ *   render={(err) => (
+ *     <span className={err.severity === 'warning' ? 'text-yellow-600' : 'text-red-600'}>
+ *       {err.message}
+ *     </span>
+ *   )}
+ * />
+ * ```
+ *
+ * @example Custom error content
+ * ```tsx
+ * <FormField.Error className="text-xs">
+ *   This field is required
+ * </FormField.Error>
+ * ```
+ */
+export declare const FormFieldError: import('react').ForwardRefExoticComponent<FormFieldErrorProps & import('react').RefAttributes<HTMLParagraphElement>>;

package/dist/components/form-field/FormFieldLabel.d.ts

@@ -0,0 +1,35 @@
+import { FormFieldLabelProps } from './types';
+/**
+ * FormField.Label - Accessible label for the form field.
+ *
+ * Automatically wires `htmlFor` to the control ID and `id` to the label ID
+ * so that `aria-labelledby` on FormField.Control works correctly.
+ *
+ * The label text defaults to `componentProps.label` from the field config.
+ * Pass `children` to override or enrich the label content.
+ *
+ * A required indicator `*` is appended automatically when `componentProps.required` is set.
+ *
+ * @example Auto label from field config
+ * ```tsx
+ * <FormField.Root control={control.email}>
+ *   <FormField.Label />  {/* renders componentProps.label *\/}
+ *   <FormField.Control />
+ * </FormField.Root>
+ * ```
+ *
+ * @example Custom label content
+ * ```tsx
+ * <FormField.Label className="font-semibold">
+ *   Email Address <span className="text-gray-400">(optional)</span>
+ * </FormField.Label>
+ * ```
+ *
+ * @example With custom element (asChild)
+ * ```tsx
+ * <FormField.Label asChild>
+ *   <Typography variant="label">{label}</Typography>
+ * </FormField.Label>
+ * ```
+ */
+export declare const FormFieldLabel: import('react').ForwardRefExoticComponent<FormFieldLabelProps & import('react').RefAttributes<HTMLLabelElement>>;

package/dist/components/form-field/FormFieldRoot.d.ts

@@ -0,0 +1,32 @@
+import { FormValue } from '@reformer/core';
+import { FormFieldRootProps } from './types';
+/**
+ * FormField.Root - Context provider for form field compound component.
+ *
+ * Computes stable accessible IDs (controlId, labelId, descriptionId, errorId)
+ * and provides all field state to child FormField.* components.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * <FormField.Root control={control.email}>
+ *   <FormField.Label />
+ *   <FormField.Control />
+ *   <FormField.Error />
+ * </FormField.Root>
+ * ```
+ *
+ * @example With description (pass hasDescription to auto-wire aria-describedby)
+ * ```tsx
+ * <FormField.Root control={control.email} hasDescription>
+ *   <FormField.Label />
+ *   <FormField.Control />
+ *   <FormField.Description>Helper text</FormField.Description>
+ *   <FormField.Error />
+ * </FormField.Root>
+ * ```
+ */
+declare function FormFieldRoot<T extends FormValue>({ control, children, id, hasDescription, }: FormFieldRootProps<T>): import("react/jsx-runtime").JSX.Element;
+declare namespace FormFieldRoot {
+    var displayName: string;
+}
+export { FormFieldRoot };

package/dist/components/form-field/index.d.ts

@@ -0,0 +1,10 @@
+export { FormField } from './FormField';
+export { FormFieldRoot } from './FormFieldRoot';
+export { FormFieldLabel } from './FormFieldLabel';
+export { FormFieldControl } from './FormFieldControl';
+export { FormFieldError } from './FormFieldError';
+export { FormFieldDescription } from './FormFieldDescription';
+export { useFormField } from './useFormField';
+export type { UseFormFieldReturn, UseFormFieldState, UseFormFieldLabelProps, UseFormFieldControlProps, UseFormFieldErrorProps, UseFormFieldDescriptionProps, } from './useFormField';
+export { FormFieldContext, useFormFieldContext } from './FormFieldContext';
+export type { FormFieldIds, FormFieldContextValue, FormFieldRootProps, FormFieldLabelProps, FormFieldControlProps, FormFieldErrorProps, FormFieldDescriptionProps, } from './types';

package/dist/components/form-field/types.d.ts

@@ -0,0 +1,114 @@
+import { HTMLAttributes, LabelHTMLAttributes, ReactNode } from 'react';
+import { FieldNode, FormValue, ValidationError } from '@reformer/core';
+/**
+ * Stable IDs for all accessible elements of a form field
+ */
+export interface FormFieldIds {
+    /** ID placed on the interactive control element (<input>, etc.) */
+    controlId: string;
+    /** ID placed on the <label> element */
+    labelId: string;
+    /** ID placed on the description paragraph */
+    descriptionId: string;
+    /** ID placed on the first error paragraph */
+    errorId: string;
+}
+/**
+ * Context value provided by FormField.Root
+ */
+export interface FormFieldContextValue<T extends FormValue = FormValue> {
+    value: T;
+    errors: ValidationError[];
+    pending: boolean;
+    disabled: boolean;
+    valid: boolean;
+    invalid: boolean;
+    touched: boolean;
+    shouldShowError: boolean;
+    /** First error message, only set when shouldShowError is true */
+    error: string | undefined;
+    label: string | undefined;
+    required: boolean;
+    /** Full componentProps bag */
+    componentProps: Record<string, unknown>;
+    control: FieldNode<T>;
+    ids: FormFieldIds;
+    /** Whether a FormField.Description is present (drives aria-describedby on Control) */
+    hasDescription: boolean;
+}
+/**
+ * Props for FormField.Root
+ */
+export interface FormFieldRootProps<T extends FormValue = FormValue> {
+    /** The FieldNode control from the form */
+    control: FieldNode<T>;
+    children: ReactNode;
+    /** Explicit id prefix; if omitted, useId() is used */
+    id?: string;
+    /**
+     * Set to true when the field has a description element so that
+     * FormField.Control automatically wires aria-describedby.
+     * Avoids the double-render caused by dynamic description registration.
+     * @default false
+     */
+    hasDescription?: boolean;
+}
+/**
+ * Props for FormField.Label
+ */
+export interface FormFieldLabelProps extends Omit<LabelHTMLAttributes<HTMLLabelElement>, 'htmlFor'> {
+    /** Render as child element via Slot (merges accessible props into the child) */
+    asChild?: boolean;
+    /**
+     * Override label text. Defaults to componentProps.label.
+     * Pass children explicitly when you need custom content inside the label.
+     */
+    children?: ReactNode;
+    /**
+     * If true, always renders even when no label text is available.
+     * Useful when the consumer provides children.
+     * @default false
+     */
+    forceRender?: boolean;
+}
+/**
+ * Props for FormField.Control
+ */
+export interface FormFieldControlProps extends Omit<HTMLAttributes<HTMLElement>, 'id' | 'onChange' | 'onBlur'> {
+    /**
+     * Merge accessible props into a custom child element instead of
+     * auto-rendering control.component.
+     */
+    asChild?: boolean;
+    /**
+     * Custom children. When provided, control.component is NOT auto-rendered.
+     * Accessible props are merged into the child via Slot.
+     */
+    children?: ReactNode;
+}
+/**
+ * Props for FormField.Error
+ */
+export interface FormFieldErrorProps extends Omit<HTMLAttributes<HTMLParagraphElement>, 'id' | 'role'> {
+    asChild?: boolean;
+    /**
+     * When true, renders all errors instead of only the first.
+     * @default false
+     */
+    multi?: boolean;
+    /**
+     * Custom render function per error. When provided, multi is implied true.
+     */
+    render?: (error: ValidationError, index: number) => ReactNode;
+    /**
+     * Override error content. Defaults to errors[0].message.
+     */
+    children?: ReactNode;
+}
+/**
+ * Props for FormField.Description
+ */
+export interface FormFieldDescriptionProps extends Omit<HTMLAttributes<HTMLParagraphElement>, 'id'> {
+    asChild?: boolean;
+    children: ReactNode;
+}

package/dist/components/form-field/useFormField.d.ts

@@ -0,0 +1,111 @@
+import { FieldNode, FormValue, ValidationError } from '@reformer/core';
+import { FormFieldIds } from './types';
+/**
+ * Field state returned by useFormField
+ */
+export interface UseFormFieldState<T extends FormValue = FormValue> {
+    value: T;
+    errors: ValidationError[];
+    /** First error message, only set when shouldShowError is true */
+    error: string | undefined;
+    isPending: boolean;
+    isDisabled: boolean;
+    isValid: boolean;
+    isInvalid: boolean;
+    isTouched: boolean;
+    shouldShowError: boolean;
+    label: string | undefined;
+    required: boolean;
+    /** Full componentProps bag from FieldNode config */
+    componentProps: Record<string, unknown>;
+}
+/** Props to spread onto a <label> element */
+export interface UseFormFieldLabelProps {
+    id: string;
+    htmlFor: string;
+}
+/** Props to spread onto the interactive control element */
+export interface UseFormFieldControlProps {
+    id: string;
+    disabled: boolean;
+    'aria-labelledby': string;
+    'aria-invalid': true | undefined;
+    'aria-errormessage': string | undefined;
+    'aria-required': true | undefined;
+    /** Direct-value onChange compatible with ReFormer field components */
+    onChange: (value: unknown) => void;
+    onBlur: () => void;
+}
+/** Props to spread onto an error paragraph */
+export interface UseFormFieldErrorProps {
+    id: string;
+    role: 'alert';
+}
+/** Props to spread onto a description paragraph */
+export interface UseFormFieldDescriptionProps {
+    id: string;
+}
+/**
+ * Return type of useFormField hook
+ */
+export interface UseFormFieldReturn<T extends FormValue = FormValue> {
+    /** Spread onto <label> */
+    labelProps: UseFormFieldLabelProps;
+    /** Spread onto the interactive control; includes value */
+    controlProps: UseFormFieldControlProps & {
+        value: T;
+    };
+    /** Spread onto the first error paragraph */
+    errorProps: UseFormFieldErrorProps;
+    /** Spread onto the description paragraph */
+    descriptionProps: UseFormFieldDescriptionProps;
+    /** Structured field state */
+    state: UseFormFieldState<T>;
+    /** Field actions */
+    actions: {
+        setValue: (value: T) => void;
+        markAsTouched: () => void;
+        markAsUntouched: () => void;
+        reset: (value?: T) => void;
+    };
+    /** Raw IDs for manual wiring (e.g. aria-describedby) */
+    ids: FormFieldIds;
+}
+/**
+ * Primary hook for building accessible form fields.
+ *
+ * Returns partitioned prop collections and structured state that you can spread
+ * directly onto your own elements. No prescribed DOM structure.
+ *
+ * @example Basic usage
+ * ```tsx
+ * function EmailField({ control }: { control: FieldNode<string> }) {
+ *   const { labelProps, controlProps, errorProps, state } = useFormField(control);
+ *
+ *   return (
+ *     <div>
+ *       <label {...labelProps}>{state.label}</label>
+ *       <input {...controlProps} type="email" />
+ *       {state.shouldShowError && (
+ *         <p {...errorProps}>{state.error}</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With description (manual aria-describedby wiring)
+ * ```tsx
+ * const { labelProps, controlProps, errorProps, descriptionProps, state, ids } =
+ *   useFormField(control);
+ *
+ * const enrichedControlProps = {
+ *   ...controlProps,
+ *   'aria-describedby': [
+ *     ids.descriptionId,
+ *     state.shouldShowError ? ids.errorId : null,
+ *   ].filter(Boolean).join(' ') || undefined,
+ * };
+ * ```
+ */
+export declare function useFormField<T extends FormValue>(control: FieldNode<T>, id?: string): UseFormFieldReturn<T>;

package/dist/components/form-wizard/FormWizard.d.ts

@@ -0,0 +1,47 @@
+import { FormWizardStep } from './FormWizardStep';
+import { FormWizardIndicator } from './FormWizardIndicator';
+import { FormWizardActions } from './FormWizardActions';
+import { FormWizardProgress } from './FormWizardProgress';
+import { FormWizardPrev } from './FormWizardPrev';
+import { FormWizardNext } from './FormWizardNext';
+import { FormWizardSubmit } from './FormWizardSubmit';
+import { FormWizardHandle, FormWizardProps } from './types';
+declare const FormWizardBase: <T extends Record<string, any>>(props: FormWizardProps<T> & {
+    ref?: React.ForwardedRef<FormWizardHandle<T>>;
+}) => React.ReactElement;
+type FormWizardComponent = typeof FormWizardBase & {
+    Step: typeof FormWizardStep;
+    Indicator: typeof FormWizardIndicator;
+    Actions: typeof FormWizardActions;
+    Progress: typeof FormWizardProgress;
+    Prev: typeof FormWizardPrev;
+    Next: typeof FormWizardNext;
+    Submit: typeof FormWizardSubmit;
+};
+/**
+ * Headless multi-step wizard. Compound-компонент: `FormWizard` + `FormWizard.Step`,
+ * `FormWizard.Actions`, `FormWizard.Indicator`, `FormWizard.Progress`,
+ * `FormWizard.Prev`, `FormWizard.Next`, `FormWizard.Submit`.
+ *
+ * @example
+ * ```tsx
+ * import { FormWizard } from '@reformer/cdk/form-wizard';
+ *
+ * <FormWizard form={form} steps={[{ name: 'profile' }, { name: 'review' }]}>
+ *   <FormWizard.Step name="profile"><ProfileFields /></FormWizard.Step>
+ *   <FormWizard.Step name="review"><Review /></FormWizard.Step>
+ *   <FormWizard.Actions>
+ *     {({ prev, next, submit, isLastStep }) => (
+ *       <div>
+ *         <button {...prev}>Prev</button>
+ *         {isLastStep ? <button {...submit}>Submit</button> : <button {...next}>Next</button>}
+ *       </div>
+ *     )}
+ *   </FormWizard.Actions>
+ * </FormWizard>
+ * ```
+ *
+ * @see [docs/llms/03-form-navigation.md](../../../docs/llms/03-form-navigation.md)
+ */
+export declare const FormWizard: FormWizardComponent;
+export {};