@dynamic-field-kit/react 1.3.0 → 1.4.0

package/README.md

@@ -12,9 +12,7 @@ Demo app: https://github.com/vannt-dev/dynamic-field-kit-demo
 npm install @dynamic-field-kit/core @dynamic-field-kit/react react
 ```
 
-Note: Core is shared runtime. Install core separately and ensure a single version is used across adapters to avoid duplicate registries.
-
-- Install with core: `npm install @dynamic-field-kit/core @dynamic-field-kit/react`
+Note: `@dynamic-field-kit/core`, `react`, and `react-dom` are **peer dependencies** — this adapter does not bundle or auto-install them, so add them to your app explicitly (as shown above). Keep a single `@dynamic-field-kit/core` version across all adapters so they share one registry.
 
 ## Exports
 
@@ -23,11 +21,15 @@ Note: Core is shared runtime. Install core separately and ensure a single versio
 - `MultiFieldInput`
 - `layoutRegistry`
 - `fieldRegistry`
+- `FieldRegistry` (class, for scoped registries)
+- `FieldRegistryProvider` / `useFieldRegistry` / `FieldRegistryProviderProps`
 - `ReactFieldRenderer`
 - `ReactFieldRegistry`
 - `FieldDescription`
 - `FieldTypeKey`
 - `FieldRendererProps`
+- `LayoutConfig`
+- `validateField` / `validateFields` / `resolveDisabled` / `resolveReadOnly` / `ValidationResult`
 
 `FieldGroupInput` (repeatable field groups) is used internally by `FieldInput` and doesn't need to be imported directly - see "Repeatable field groups" below.
 
@@ -151,6 +153,36 @@ const fields: FieldDescription[] = [
 ];
 ```
 
+## Validation & conditions
+
+Declare a `validate` hook and dynamic `disabledCondition`/`readOnlyCondition`;
+your renderer receives `error`, `disabled`, and `readOnly`. `MultiFieldInput`
+emits `onValidityChange`:
+
+```tsx
+<MultiFieldInput
+  fieldDescriptions={fields}
+  properties={data}
+  onChange={setData}
+  onValidityChange={({ valid, errors }) => setCanSubmit(valid)}
+/>
+```
+
+Read the props inside a renderer:
+
+```tsx
+fieldRegistry.register('text', ({ value, onValueChange, error, disabled }) => (
+  <label>
+    <input
+      disabled={disabled}
+      value={value ?? ''}
+      onChange={(e) => onValueChange?.(e.target.value)}
+    />
+    {error && <span className="error">{[].concat(error).join(', ')}</span>}
+  </label>
+));
+```
+
 ## Repeatable field groups
 
 A field with `fields` renders as a repeatable group: `data[name]` becomes an array of items, each shaped by the nested `fields`, with "Add"/"Remove" controls rendered automatically.
@@ -166,6 +198,7 @@ const fields: FieldDescription[] = [
       { name: 'phone', type: 'text', label: 'Phone' },
     ],
     defaultItem: { email: '', phone: '' },
+    keyField: 'id', // optional: stable list key instead of the array index
     minItems: 1,
     maxItems: 5,
   },
@@ -174,6 +207,25 @@ const fields: FieldDescription[] = [
 <MultiFieldInput fieldDescriptions={fields} />;
 ```
 
+## Scoped registries
+
+`fieldRegistry` is a process-wide singleton. To give a subtree its own renderers, create an isolated `FieldRegistry` and wrap the subtree in `FieldRegistryProvider`. Anything not wrapped keeps using the global singleton.
+
+```tsx
+import {
+  FieldRegistry,
+  FieldRegistryProvider,
+  MultiFieldInput,
+} from '@dynamic-field-kit/react';
+
+const registry = new FieldRegistry();
+registry.register('text', MyTextRenderer);
+
+<FieldRegistryProvider registry={registry}>
+  <MultiFieldInput fieldDescriptions={fields} />
+</FieldRegistryProvider>;
+```
+
 ## Type augmentation
 
 Add your app's field types through module augmentation:

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import React, { ReactNode, ComponentType } from 'react';
+import { FieldTypeKey, Properties, FieldDescription, LayoutConfig, ValidationResult, FieldTypeMap, FieldRendererProps } 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 * as react_jsx_runtime from 'react/jsx-runtime';
-import { FieldTypeKey, Properties, FieldDescription, FieldTypeMap, FieldRendererProps } from '@dynamic-field-kit/core';
-export { FieldDescription, FieldRendererProps, FieldTypeKey } from '@dynamic-field-kit/core';
 
 type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
@@ -14,43 +14,61 @@ declare class LayoutRegistry {
 }
 declare const layoutRegistry: LayoutRegistry;
 
-type BaseLayout = 'column' | 'row' | {
-    type: 'grid';
-    columns?: number;
-    gap?: number;
-};
-type LayoutConfig = BaseLayout | {
-    type: 'responsive';
-    mobile: BaseLayout;
-    desktop: BaseLayout;
-};
-
 interface Props$2<T extends FieldTypeKey> {
     type: T;
     value?: unknown;
     onChange?: (value: unknown) => void;
+    onBlur?: () => void;
     label?: string;
     options?: Properties[];
     className?: string;
     description?: ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    touched?: boolean;
+    dirty?: boolean;
+    error?: string | string[];
+    id?: string;
+    ariaInvalid?: boolean;
+    ariaDescribedBy?: string;
+    ariaRequired?: boolean;
+    /** Extra, framework-agnostic props forwarded verbatim to the renderer. */
+    extraProps?: Properties;
 }
-declare const DynamicInputInner: <T extends FieldTypeKey>({ type, value, onChange, label, options, className, description, }: Props$2<T>) => react_jsx_runtime.JSX.Element;
+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_runtime.JSX.Element;
 declare const DynamicInput: typeof DynamicInputInner;
 
 interface Props$1 {
     fieldDescription: FieldDescription;
     renderInfos: Properties;
+    rootData?: Properties;
+    touched?: boolean;
+    dirty?: boolean;
+    onBlurField?: (key: string) => void;
     onValueChangeField: (value: unknown, key: string) => void;
 }
-declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, onValueChangeField, }: Props$1) => react_jsx_runtime.JSX.Element>;
+declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, touched, dirty, onBlurField, onValueChangeField, }: Props$1) => react_jsx_runtime.JSX.Element>;
 
 interface Props {
     fieldDescriptions: FieldDescription[];
     properties?: Properties;
     onChange?: (data: Properties) => void;
     layout?: LayoutConfig;
+    /**
+     * Top-level form data, threaded down through repeatable groups so a nested
+     * field's `appearCondition`/`computeValue` can read the root form. Omitted at
+     * the top level, where the form's own data is the root.
+     */
+    rootData?: Properties;
+    /**
+     * Called with the recursive validation result ({ valid, errors }) on every
+     * change. On the top-level component this covers the whole form (groups
+     * included).
+     */
+    onValidityChange?: (result: ValidationResult) => void;
 }
-declare const MultiFieldInput: ({ fieldDescriptions, properties, onChange, layout, }: Props) => react_jsx_runtime.JSX.Element;
+declare const MultiFieldInput: ({ fieldDescriptions, properties, onChange, layout, rootData, onValidityChange, }: Props) => react_jsx_runtime.JSX.Element;
 
 type ReactFieldRenderer<T = unknown> = ComponentType<FieldRendererProps<T>>;
 interface ReactFieldRegistry {
@@ -59,4 +77,12 @@ interface ReactFieldRegistry {
 }
 declare const fieldRegistry: ReactFieldRegistry;
 
-export { DynamicInput, FieldInput, type LayoutConfig, MultiFieldInput, type ReactFieldRegistry, type ReactFieldRenderer, fieldRegistry, layoutRegistry };
+interface FieldRegistryProviderProps {
+    registry: ReactFieldRegistry;
+    children: React.ReactNode;
+}
+declare const FieldRegistryProvider: ({ registry, children, }: FieldRegistryProviderProps) => React.ReactElement;
+/** The registry for the nearest provider, or the global singleton. */
+declare function useFieldRegistry(): ReactFieldRegistry;
+
+export { DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type ReactFieldRegistry, type ReactFieldRenderer, fieldRegistry, layoutRegistry, useFieldRegistry };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import React, { ReactNode, ComponentType } from 'react';
+import { FieldTypeKey, Properties, FieldDescription, LayoutConfig, ValidationResult, FieldTypeMap, FieldRendererProps } 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 * as react_jsx_runtime from 'react/jsx-runtime';
-import { FieldTypeKey, Properties, FieldDescription, FieldTypeMap, FieldRendererProps } from '@dynamic-field-kit/core';
-export { FieldDescription, FieldRendererProps, FieldTypeKey } from '@dynamic-field-kit/core';
 
 type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
@@ -14,43 +14,61 @@ declare class LayoutRegistry {
 }
 declare const layoutRegistry: LayoutRegistry;
 
-type BaseLayout = 'column' | 'row' | {
-    type: 'grid';
-    columns?: number;
-    gap?: number;
-};
-type LayoutConfig = BaseLayout | {
-    type: 'responsive';
-    mobile: BaseLayout;
-    desktop: BaseLayout;
-};
-
 interface Props$2<T extends FieldTypeKey> {
     type: T;
     value?: unknown;
     onChange?: (value: unknown) => void;
+    onBlur?: () => void;
     label?: string;
     options?: Properties[];
     className?: string;
     description?: ReactNode;
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    touched?: boolean;
+    dirty?: boolean;
+    error?: string | string[];
+    id?: string;
+    ariaInvalid?: boolean;
+    ariaDescribedBy?: string;
+    ariaRequired?: boolean;
+    /** Extra, framework-agnostic props forwarded verbatim to the renderer. */
+    extraProps?: Properties;
 }
-declare const DynamicInputInner: <T extends FieldTypeKey>({ type, value, onChange, label, options, className, description, }: Props$2<T>) => react_jsx_runtime.JSX.Element;
+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_runtime.JSX.Element;
 declare const DynamicInput: typeof DynamicInputInner;
 
 interface Props$1 {
     fieldDescription: FieldDescription;
     renderInfos: Properties;
+    rootData?: Properties;
+    touched?: boolean;
+    dirty?: boolean;
+    onBlurField?: (key: string) => void;
     onValueChangeField: (value: unknown, key: string) => void;
 }
-declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, onValueChangeField, }: Props$1) => react_jsx_runtime.JSX.Element>;
+declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, touched, dirty, onBlurField, onValueChangeField, }: Props$1) => react_jsx_runtime.JSX.Element>;
 
 interface Props {
     fieldDescriptions: FieldDescription[];
     properties?: Properties;
     onChange?: (data: Properties) => void;
     layout?: LayoutConfig;
+    /**
+     * Top-level form data, threaded down through repeatable groups so a nested
+     * field's `appearCondition`/`computeValue` can read the root form. Omitted at
+     * the top level, where the form's own data is the root.
+     */
+    rootData?: Properties;
+    /**
+     * Called with the recursive validation result ({ valid, errors }) on every
+     * change. On the top-level component this covers the whole form (groups
+     * included).
+     */
+    onValidityChange?: (result: ValidationResult) => void;
 }
-declare const MultiFieldInput: ({ fieldDescriptions, properties, onChange, layout, }: Props) => react_jsx_runtime.JSX.Element;
+declare const MultiFieldInput: ({ fieldDescriptions, properties, onChange, layout, rootData, onValidityChange, }: Props) => react_jsx_runtime.JSX.Element;
 
 type ReactFieldRenderer<T = unknown> = ComponentType<FieldRendererProps<T>>;
 interface ReactFieldRegistry {
@@ -59,4 +77,12 @@ interface ReactFieldRegistry {
 }
 declare const fieldRegistry: ReactFieldRegistry;
 
-export { DynamicInput, FieldInput, type LayoutConfig, MultiFieldInput, type ReactFieldRegistry, type ReactFieldRenderer, fieldRegistry, layoutRegistry };
+interface FieldRegistryProviderProps {
+    registry: ReactFieldRegistry;
+    children: React.ReactNode;
+}
+declare const FieldRegistryProvider: ({ registry, children, }: FieldRegistryProviderProps) => React.ReactElement;
+/** The registry for the nearest provider, or the global singleton. */
+declare function useFieldRegistry(): ReactFieldRegistry;
+
+export { DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type ReactFieldRegistry, type ReactFieldRenderer, fieldRegistry, layoutRegistry, useFieldRegistry };