@dynamic-field-kit/react 1.2.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,17 @@ 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.
 
 Default layouts are registered automatically when you import the package root.
 
@@ -132,6 +136,96 @@ layoutRegistry.register('stack-tight', ({ children }) => (
 ));
 ```
 
+## Derived fields with `computeValue`
+
+Give a field a `computeValue` to derive its value from the rest of the form data whenever any field changes:
+
+```tsx
+const fields: FieldDescription[] = [
+  { name: 'firstName', type: 'text' },
+  { name: 'lastName', type: 'text' },
+  {
+    name: 'fullName',
+    type: 'text',
+    computeValue: (data) =>
+      `${data.firstName ?? ''} ${data.lastName ?? ''}`.trim(),
+  },
+];
+```
+
+## 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.
+
+```tsx
+const fields: FieldDescription[] = [
+  {
+    name: 'contacts',
+    type: 'group',
+    label: 'Contacts',
+    fields: [
+      { name: 'email', type: 'text', label: 'Email' },
+      { name: 'phone', type: 'text', label: 'Phone' },
+    ],
+    defaultItem: { email: '', phone: '' },
+    keyField: 'id', // optional: stable list key instead of the array index
+    minItems: 1,
+    maxItems: 5,
+  },
+];
+
+<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:
@@ -151,8 +245,9 @@ declare module '@dynamic-field-kit/core' {
 
 - `@dynamic-field-kit/core` stays framework-agnostic and does not export React-specific JSX types.
 - `@dynamic-field-kit/react` narrows the shared registry to React component types so `fieldRegistry.get(type)` can be rendered safely in TSX.
-- `MultiFieldInput` filters fields using `appearCondition`.
+- `MultiFieldInput` filters fields using `appearCondition` and derives fields using `computeValue`.
 - `DynamicInput` renders `Unknown field type: ...` when a renderer is missing.
+- Fields with `fields` render as repeatable groups instead of going through `fieldRegistry`.
 
 ## License
 

package/dist/index.d.mts

@@ -1,9 +1,9 @@
 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 = any> = (props: {
+type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
     config?: C;
 }) => React.ReactElement;
@@ -14,48 +14,75 @@ 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?: any;
-    onChange?: (value: any) => void;
+    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 DynamicInput: <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;
-    onValueChangeField: (value: any, key: string) => void;
+    rootData?: Properties;
+    touched?: boolean;
+    dirty?: boolean;
+    onBlurField?: (key: string) => void;
+    onValueChangeField: (value: unknown, key: string) => void;
 }
-declare const FieldInput: ({ 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 = any> = ComponentType<FieldRendererProps<T>>;
+type ReactFieldRenderer<T = unknown> = ComponentType<FieldRendererProps<T>>;
 interface ReactFieldRegistry {
     register<K extends keyof FieldTypeMap>(type: K, renderer: ReactFieldRenderer<FieldTypeMap[K]>): void;
     get<K extends keyof FieldTypeMap>(type: K): ReactFieldRenderer<FieldTypeMap[K]> | undefined;
 }
 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,9 +1,9 @@
 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 = any> = (props: {
+type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
     config?: C;
 }) => React.ReactElement;
@@ -14,48 +14,75 @@ 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?: any;
-    onChange?: (value: any) => void;
+    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 DynamicInput: <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;
-    onValueChangeField: (value: any, key: string) => void;
+    rootData?: Properties;
+    touched?: boolean;
+    dirty?: boolean;
+    onBlurField?: (key: string) => void;
+    onValueChangeField: (value: unknown, key: string) => void;
 }
-declare const FieldInput: ({ 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 = any> = ComponentType<FieldRendererProps<T>>;
+type ReactFieldRenderer<T = unknown> = ComponentType<FieldRendererProps<T>>;
 interface ReactFieldRegistry {
     register<K extends keyof FieldTypeMap>(type: K, renderer: ReactFieldRenderer<FieldTypeMap[K]>): void;
     get<K extends keyof FieldTypeMap>(type: K): ReactFieldRenderer<FieldTypeMap[K]> | undefined;
 }
 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 };