@dynamic-field-kit/react 1.5.1 → 1.7.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import React, { ReactNode, ComponentType } from 'react';
-import { FieldTypeKey, Properties, FieldDescription, LayoutConfig, ValidationResult, FieldRendererProps, FieldTypeMap } from '@dynamic-field-kit/core';
-export { FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationResult, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } from '@dynamic-field-kit/core';
+import { FieldTypeKey, Properties, OptionsStatus, FieldDescription, LayoutConfig, ValidationResult, MessageCatalog, FieldRendererProps, FieldTypeMap } from '@dynamic-field-kit/core';
+export { FIELD_RENDERER_PROP_KEYS, FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationContext, ValidationResult, buildFieldRendererProps, collectFieldPaths, indexGroupPathMap, makeErrorId, makeFieldId, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } from '@dynamic-field-kit/core';
 
 type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
@@ -19,7 +19,10 @@ interface Props$2<T extends FieldTypeKey> {
     onChange?: (value: unknown) => void;
     onBlur?: () => void;
     label?: string;
+    placeholder?: string;
     options?: Properties[];
+    optionsStatus?: OptionsStatus;
+    optionsError?: unknown;
     className?: string;
     description?: ReactNode;
     disabled?: boolean;
@@ -32,28 +35,80 @@ interface Props$2<T extends FieldTypeKey> {
     ariaInvalid?: boolean;
     ariaDescribedBy?: string;
     ariaRequired?: boolean;
+    min?: number | string;
+    max?: number | string;
+    step?: number | string;
+    accept?: string;
+    multiple?: boolean;
     /** Extra, framework-agnostic props forwarded verbatim to the renderer. */
     extraProps?: Properties;
+    /** Renderer-driven refetch for a search-remote field. */
+    onOptionsQuery?: (query: string) => void;
 }
-declare const DynamicInputInner: <T extends FieldTypeKey>({ type, value, onChange, onBlur, label, options, className, description, disabled, readOnly, required, touched, dirty, error, id, ariaInvalid, ariaDescribedBy, ariaRequired, extraProps, }: Props$2<T>) => React.JSX.Element;
+declare const DynamicInputInner: <T extends FieldTypeKey>({ type, onChange, onBlur, extraProps, onOptionsQuery, ...rendererProps }: Props$2<T>) => React.JSX.Element;
 declare const DynamicInput: typeof DynamicInputInner;
 
 interface Props$1 {
     fieldDescription: FieldDescription;
     renderInfos: Properties;
     rootData?: Properties;
+    /** Per-form-instance id namespace; see core's `makeFieldId`. */
+    idPrefix?: string;
     touched?: boolean;
+    touchedMap?: Record<string, boolean>;
     dirty?: boolean;
+    errors?: Record<string, string[]>;
     onBlurField?: (key: string) => void;
     onValueChangeField: (value: unknown, key: string) => void;
 }
-declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, touched, dirty, onBlurField, onValueChangeField, }: Props$1) => React.JSX.Element>;
+declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, idPrefix, touched, touchedMap, dirty, errors, onBlurField, onValueChangeField, }: Props$1) => React.JSX.Element>;
 
+/**
+ * The slice of `useDynamicForm`'s result `MultiFieldInput` needs to drive
+ * itself. Structural, so the hook result can be passed straight in.
+ */
+interface DynamicFormBinding {
+    data: Properties;
+    errors: Record<string, string[]>;
+    touched: Record<string, boolean>;
+    /** The values per-field `dirty` is measured against. See `useDynamicForm`. */
+    baselineValues?: Properties;
+    handleChange: (data: Properties) => void;
+    handleBlur: (fieldName: string) => void;
+}
+/** Imperative handle exposed on a `MultiFieldInput` ref. */
+interface MultiFieldInputHandle {
+    /**
+     * Clears the internally tracked touched state. Only meaningful in
+     * uncontrolled mode - when `touched` is passed as a prop, resetting the form
+     * store (e.g. `useDynamicForm().reset()`) already clears it.
+     */
+    resetTouched: () => void;
+    setFieldTouched: (fieldName: string, isTouched?: boolean) => void;
+    /** The touched map currently in effect, controlled or internal. */
+    getTouched: () => Record<string, boolean>;
+}
 interface Props {
     fieldDescriptions: FieldDescription[];
     properties?: Properties;
     onChange?: (data: Properties) => void;
     layout?: LayoutConfig;
+    /**
+     * Namespace for generated field ids: a field renders with
+     * `${idPrefix}-${name}`. Defaults to a value unique to this component
+     * instance, so two forms containing the same field name do not emit
+     * duplicate DOM ids. Pass a fixed string to pin ids (`idPrefix="dfk-field"`
+     * restores the pre-1.6 ids), or set `FieldDescription.id` per field.
+     */
+    idPrefix?: string;
+    /**
+     * The values per-field `dirty` is measured against. Defaults to the first
+     * non-`undefined` `properties` this component sees - which is what an edit
+     * form wants when its values arrive from a fetch after mount. Supplied
+     * automatically by the `form` shorthand; pass it explicitly to re-base
+     * `dirty` without going through a form store.
+     */
+    initialProperties?: Properties;
     /**
      * Top-level form data, threaded down through repeatable groups so a nested
      * field's `appearCondition`/`computeValue` can read the root form. Omitted at
@@ -73,8 +128,26 @@ interface Props {
      * map and `validateOnBlur` behaviour.
      */
     onBlurField?: (fieldName: string) => void;
+    /**
+     * Controlled touched map. When provided it is the single source of truth and
+     * the internal tracker is bypassed entirely, so `useDynamicForm().touched`
+     * (updated by `setFieldTouched`, `touchAll`, `handleSubmit` and cleared by
+     * `reset`) is what renderers actually see. Omit it to keep the internal,
+     * blur-only tracker.
+     */
+    touched?: Record<string, boolean>;
+    /** Controlled validation errors. Empty means no renderer error. */
+    errors?: Record<string, string[]>;
+    /** Fires with the next touched map whenever a field is blurred. */
+    onTouchedChange?: (touched: Record<string, boolean>) => void;
+    /**
+     * Shorthand that wires `properties`, `onChange`, `onBlurField` and `touched`
+     * from a `useDynamicForm` result in one prop. Individually passed props win
+     * over the ones derived from here.
+     */
+    form?: DynamicFormBinding;
 }
-declare const MultiFieldInput: ({ fieldDescriptions, properties, onChange, layout, rootData, onValidityChange, onBlurField, }: Props) => React.JSX.Element;
+declare const MultiFieldInput: React.ForwardRefExoticComponent<Props & React.RefAttributes<MultiFieldInputHandle>>;
 
 interface DynamicFormDevToolsProps {
     data: Properties;
@@ -91,25 +164,59 @@ interface UseDynamicFormOptions {
     initialValues?: Properties;
     validateOnBlur?: boolean;
     validateOnChange?: boolean;
+    /**
+     * Messages for the built-in validators, set once for the whole form instead
+     * of per field. A message passed directly to a validator still wins, and any
+     * key omitted here falls back to the validator's English default. See core's
+     * `MessageCatalog`.
+     */
+    messages?: MessageCatalog;
 }
 interface UseDynamicFormResult {
     data: Properties;
     errors: Record<string, string[]>;
     isValid: boolean;
+    isValidating: boolean;
+    isValidationComplete: boolean;
+    validationStatus: ValidationResult['status'];
     isDirty: boolean;
+    /**
+     * The values `dirty` is measured against: the `initialValues` option until
+     * `reset(newValues)` replaces them. Distinct from that option, which never
+     * changes - pass this to `MultiFieldInput` (or use the `form` shorthand) so
+     * per-field `dirty` survives a reset.
+     */
+    baselineValues: Properties;
+    /**
+     * The entries of `data` that differ from `baselineValues`. Intended for
+     * PATCH-style submits that should carry only what the user actually edited.
+     */
+    getDirtyValues: () => Properties;
     isSubmitting: boolean;
     isSubmitted: boolean;
     touched: Record<string, boolean>;
     setData: React.Dispatch<React.SetStateAction<Properties>>;
     setFieldValue: (name: string, value: unknown) => void;
     setFieldTouched: (name: string, isTouched?: boolean) => void;
+    /** Replaces the whole touched map. */
+    setTouched: React.Dispatch<React.SetStateAction<Record<string, boolean>>>;
+    /**
+     * Marks every field touched at once. `handleSubmit` calls this for you, so
+     * an invalid submit surfaces errors on fields the user never focused - pass
+     * `touched` into `MultiFieldInput` for it to take effect.
+     */
+    touchAll: () => void;
+    /** Clears the touched map without touching data, errors or dirty state. */
+    resetTouched: () => void;
     handleChange: (newData: Properties) => void;
     handleBlur: (fieldName: string) => void;
     reset: (newValues?: Properties) => void;
     validate: () => boolean;
+    /** Validate all fields and await Promise-based rules. */
+    validateAsync: () => Promise<boolean>;
     handleSubmit: (onValid: (data: Properties) => void | Promise<void>, onInvalid?: (errors: Record<string, string[]>) => void) => (e?: React.FormEvent) => Promise<void>;
 }
-declare function useDynamicForm({ fields, initialValues, validateOnBlur, validateOnChange, }: UseDynamicFormOptions): UseDynamicFormResult;
+declare function useDynamicForm({ fields, initialValues, validateOnBlur, validateOnChange, messages, }: UseDynamicFormOptions): UseDynamicFormResult;
 
 declare const defaultRenderersMap: Record<string, React.FC<FieldRendererProps>>;
 declare function getDefaultRenderer(type: string): React.FC<FieldRendererProps> | undefined;
@@ -129,4 +236,4 @@ declare const FieldRegistryProvider: ({ registry, children, }: FieldRegistryProv
 /** The registry for the nearest provider, or the global singleton. */
 declare function useFieldRegistry(): ReactFieldRegistry;
 
-export { DynamicFormDevTools, DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type ReactFieldRegistry, type ReactFieldRenderer, defaultRenderersMap, fieldRegistry, getDefaultRenderer, layoutRegistry, useDynamicForm, useFieldRegistry };
+export { type DynamicFormBinding, DynamicFormDevTools, DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type MultiFieldInputHandle, type ReactFieldRegistry, type ReactFieldRenderer, type UseDynamicFormOptions, type UseDynamicFormResult, defaultRenderersMap, fieldRegistry, getDefaultRenderer, layoutRegistry, useDynamicForm, useFieldRegistry };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import React, { ReactNode, ComponentType } from 'react';
-import { FieldTypeKey, Properties, FieldDescription, LayoutConfig, ValidationResult, FieldRendererProps, FieldTypeMap } from '@dynamic-field-kit/core';
-export { FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationResult, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } from '@dynamic-field-kit/core';
+import { FieldTypeKey, Properties, OptionsStatus, FieldDescription, LayoutConfig, ValidationResult, MessageCatalog, FieldRendererProps, FieldTypeMap } from '@dynamic-field-kit/core';
+export { FIELD_RENDERER_PROP_KEYS, FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationContext, ValidationResult, buildFieldRendererProps, collectFieldPaths, indexGroupPathMap, makeErrorId, makeFieldId, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } from '@dynamic-field-kit/core';
 
 type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
@@ -19,7 +19,10 @@ interface Props$2<T extends FieldTypeKey> {
     onChange?: (value: unknown) => void;
     onBlur?: () => void;
     label?: string;
+    placeholder?: string;
     options?: Properties[];
+    optionsStatus?: OptionsStatus;
+    optionsError?: unknown;
     className?: string;
     description?: ReactNode;
     disabled?: boolean;
@@ -32,28 +35,80 @@ interface Props$2<T extends FieldTypeKey> {
     ariaInvalid?: boolean;
     ariaDescribedBy?: string;
     ariaRequired?: boolean;
+    min?: number | string;
+    max?: number | string;
+    step?: number | string;
+    accept?: string;
+    multiple?: boolean;
     /** Extra, framework-agnostic props forwarded verbatim to the renderer. */
     extraProps?: Properties;
+    /** Renderer-driven refetch for a search-remote field. */
+    onOptionsQuery?: (query: string) => void;
 }
-declare const DynamicInputInner: <T extends FieldTypeKey>({ type, value, onChange, onBlur, label, options, className, description, disabled, readOnly, required, touched, dirty, error, id, ariaInvalid, ariaDescribedBy, ariaRequired, extraProps, }: Props$2<T>) => React.JSX.Element;
+declare const DynamicInputInner: <T extends FieldTypeKey>({ type, onChange, onBlur, extraProps, onOptionsQuery, ...rendererProps }: Props$2<T>) => React.JSX.Element;
 declare const DynamicInput: typeof DynamicInputInner;
 
 interface Props$1 {
     fieldDescription: FieldDescription;
     renderInfos: Properties;
     rootData?: Properties;
+    /** Per-form-instance id namespace; see core's `makeFieldId`. */
+    idPrefix?: string;
     touched?: boolean;
+    touchedMap?: Record<string, boolean>;
     dirty?: boolean;
+    errors?: Record<string, string[]>;
     onBlurField?: (key: string) => void;
     onValueChangeField: (value: unknown, key: string) => void;
 }
-declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, touched, dirty, onBlurField, onValueChangeField, }: Props$1) => React.JSX.Element>;
+declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, idPrefix, touched, touchedMap, dirty, errors, onBlurField, onValueChangeField, }: Props$1) => React.JSX.Element>;
 
+/**
+ * The slice of `useDynamicForm`'s result `MultiFieldInput` needs to drive
+ * itself. Structural, so the hook result can be passed straight in.
+ */
+interface DynamicFormBinding {
+    data: Properties;
+    errors: Record<string, string[]>;
+    touched: Record<string, boolean>;
+    /** The values per-field `dirty` is measured against. See `useDynamicForm`. */
+    baselineValues?: Properties;
+    handleChange: (data: Properties) => void;
+    handleBlur: (fieldName: string) => void;
+}
+/** Imperative handle exposed on a `MultiFieldInput` ref. */
+interface MultiFieldInputHandle {
+    /**
+     * Clears the internally tracked touched state. Only meaningful in
+     * uncontrolled mode - when `touched` is passed as a prop, resetting the form
+     * store (e.g. `useDynamicForm().reset()`) already clears it.
+     */
+    resetTouched: () => void;
+    setFieldTouched: (fieldName: string, isTouched?: boolean) => void;
+    /** The touched map currently in effect, controlled or internal. */
+    getTouched: () => Record<string, boolean>;
+}
 interface Props {
     fieldDescriptions: FieldDescription[];
     properties?: Properties;
     onChange?: (data: Properties) => void;
     layout?: LayoutConfig;
+    /**
+     * Namespace for generated field ids: a field renders with
+     * `${idPrefix}-${name}`. Defaults to a value unique to this component
+     * instance, so two forms containing the same field name do not emit
+     * duplicate DOM ids. Pass a fixed string to pin ids (`idPrefix="dfk-field"`
+     * restores the pre-1.6 ids), or set `FieldDescription.id` per field.
+     */
+    idPrefix?: string;
+    /**
+     * The values per-field `dirty` is measured against. Defaults to the first
+     * non-`undefined` `properties` this component sees - which is what an edit
+     * form wants when its values arrive from a fetch after mount. Supplied
+     * automatically by the `form` shorthand; pass it explicitly to re-base
+     * `dirty` without going through a form store.
+     */
+    initialProperties?: Properties;
     /**
      * Top-level form data, threaded down through repeatable groups so a nested
      * field's `appearCondition`/`computeValue` can read the root form. Omitted at
@@ -73,8 +128,26 @@ interface Props {
      * map and `validateOnBlur` behaviour.
      */
     onBlurField?: (fieldName: string) => void;
+    /**
+     * Controlled touched map. When provided it is the single source of truth and
+     * the internal tracker is bypassed entirely, so `useDynamicForm().touched`
+     * (updated by `setFieldTouched`, `touchAll`, `handleSubmit` and cleared by
+     * `reset`) is what renderers actually see. Omit it to keep the internal,
+     * blur-only tracker.
+     */
+    touched?: Record<string, boolean>;
+    /** Controlled validation errors. Empty means no renderer error. */
+    errors?: Record<string, string[]>;
+    /** Fires with the next touched map whenever a field is blurred. */
+    onTouchedChange?: (touched: Record<string, boolean>) => void;
+    /**
+     * Shorthand that wires `properties`, `onChange`, `onBlurField` and `touched`
+     * from a `useDynamicForm` result in one prop. Individually passed props win
+     * over the ones derived from here.
+     */
+    form?: DynamicFormBinding;
 }
-declare const MultiFieldInput: ({ fieldDescriptions, properties, onChange, layout, rootData, onValidityChange, onBlurField, }: Props) => React.JSX.Element;
+declare const MultiFieldInput: React.ForwardRefExoticComponent<Props & React.RefAttributes<MultiFieldInputHandle>>;
 
 interface DynamicFormDevToolsProps {
     data: Properties;
@@ -91,25 +164,59 @@ interface UseDynamicFormOptions {
     initialValues?: Properties;
     validateOnBlur?: boolean;
     validateOnChange?: boolean;
+    /**
+     * Messages for the built-in validators, set once for the whole form instead
+     * of per field. A message passed directly to a validator still wins, and any
+     * key omitted here falls back to the validator's English default. See core's
+     * `MessageCatalog`.
+     */
+    messages?: MessageCatalog;
 }
 interface UseDynamicFormResult {
     data: Properties;
     errors: Record<string, string[]>;
     isValid: boolean;
+    isValidating: boolean;
+    isValidationComplete: boolean;
+    validationStatus: ValidationResult['status'];
     isDirty: boolean;
+    /**
+     * The values `dirty` is measured against: the `initialValues` option until
+     * `reset(newValues)` replaces them. Distinct from that option, which never
+     * changes - pass this to `MultiFieldInput` (or use the `form` shorthand) so
+     * per-field `dirty` survives a reset.
+     */
+    baselineValues: Properties;
+    /**
+     * The entries of `data` that differ from `baselineValues`. Intended for
+     * PATCH-style submits that should carry only what the user actually edited.
+     */
+    getDirtyValues: () => Properties;
     isSubmitting: boolean;
     isSubmitted: boolean;
     touched: Record<string, boolean>;
     setData: React.Dispatch<React.SetStateAction<Properties>>;
     setFieldValue: (name: string, value: unknown) => void;
     setFieldTouched: (name: string, isTouched?: boolean) => void;
+    /** Replaces the whole touched map. */
+    setTouched: React.Dispatch<React.SetStateAction<Record<string, boolean>>>;
+    /**
+     * Marks every field touched at once. `handleSubmit` calls this for you, so
+     * an invalid submit surfaces errors on fields the user never focused - pass
+     * `touched` into `MultiFieldInput` for it to take effect.
+     */
+    touchAll: () => void;
+    /** Clears the touched map without touching data, errors or dirty state. */
+    resetTouched: () => void;
     handleChange: (newData: Properties) => void;
     handleBlur: (fieldName: string) => void;
     reset: (newValues?: Properties) => void;
     validate: () => boolean;
+    /** Validate all fields and await Promise-based rules. */
+    validateAsync: () => Promise<boolean>;
     handleSubmit: (onValid: (data: Properties) => void | Promise<void>, onInvalid?: (errors: Record<string, string[]>) => void) => (e?: React.FormEvent) => Promise<void>;
 }
-declare function useDynamicForm({ fields, initialValues, validateOnBlur, validateOnChange, }: UseDynamicFormOptions): UseDynamicFormResult;
+declare function useDynamicForm({ fields, initialValues, validateOnBlur, validateOnChange, messages, }: UseDynamicFormOptions): UseDynamicFormResult;
 
 declare const defaultRenderersMap: Record<string, React.FC<FieldRendererProps>>;
 declare function getDefaultRenderer(type: string): React.FC<FieldRendererProps> | undefined;
@@ -129,4 +236,4 @@ declare const FieldRegistryProvider: ({ registry, children, }: FieldRegistryProv
 /** The registry for the nearest provider, or the global singleton. */
 declare function useFieldRegistry(): ReactFieldRegistry;
 
-export { DynamicFormDevTools, DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type ReactFieldRegistry, type ReactFieldRenderer, defaultRenderersMap, fieldRegistry, getDefaultRenderer, layoutRegistry, useDynamicForm, useFieldRegistry };
+export { type DynamicFormBinding, DynamicFormDevTools, DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type MultiFieldInputHandle, type ReactFieldRegistry, type ReactFieldRenderer, type UseDynamicFormOptions, type UseDynamicFormResult, defaultRenderersMap, fieldRegistry, getDefaultRenderer, layoutRegistry, useDynamicForm, useFieldRegistry };