dynamic-modal 1.1.23 → 1.1.25

package/README.md

@@ -1,203 +1,253 @@
 # dynamic-modal
 
-`dynamic-modal` is a TypeScript library for creating reusable modals in React and Next.js applications. It uses JSON objects to configure the modal structure, eliminating the need to write HTML. This approach simplifies modal creation and customization, allowing you to open and close modals using a custom hook.
+`dynamic-modal` is a React library for building configurable modals from JSON.
+Instead of hand-writing a modal UI every time, you describe fields, actions, and
+conditional behavior in a config object and open it through a hook.
 
-## Requirements
+It is designed for projects that want:
 
-To use `dynamic-modal` properly, ensure you have the following dependencies installed:
+- reusable modal definitions
+- dynamic forms inside modals
+- conditional rendering with `renderIf`
+- conditional enabling with `enableIf`
+- dependent remote options with `liveData`
+- full UI customization through your own design system components
 
-- React
+## Compatibility
 
-Additionally, `dynamic-modal` is compatible with **Next.js**.
+According to `package.json`, this library is compatible with:
 
-## Installation
+- `react`: `^18.0.0 || ^19.0.0`
+- `react-dom`: `^18.0.0 || ^19.0.0`
+- `react-hook-form`: `^7.54.2`
+
+The library itself is currently built with:
+
+- `react`: `^19.0.0`
+- `react-dom`: `^19.0.0`
+- `react-hook-form`: `^7.54.2`
 
-Install the library via npm:
+It works well in React apps and in Next.js projects that support client
+components.
+
+## Installation
 
 ```bash
 npm install dynamic-modal
 ```
 
-## Setup for Next.js (14 or 15)
-Define your components for use inside modal, create file and configure all modal components. Here´s an example using HeroUI (previously NextUI):
+If your project does not already include the required peers, install them too:
 
-```jsx
-'use client'
-import { Autocomplete, AutocompleteItem, Button, Input, Select, SelectItem, Switch, Textarea } from "@heroui/react"
-import { IComponentState } from "dynamic-modal/src/interfaces/component-state"
+```bash
+npm install react react-dom react-hook-form
+```
 
-export const ModalComponents: IComponentState = {
-  ModalButtonCancel: (props) => {
-    return (
-      <Button 
-        {...props} 
-        color={props.color as "default" | "primary" | "secondary" | "success" | "warning" | "danger" | undefined}  
-        variant={'bordered'}
-      >
-        {props.text}
-      </Button>
-    )
-  },
-  ModalButtonAction: (props) => {
-    return (
-      <Button 
-        {...props} 
-        color={props.color as "default" | "primary" | "secondary" | "success" | "warning" | "danger" | undefined} 
-        variant={'solid'}
-      >
-        {props.text}
-      </Button>)
-  },
-  Button: ({ text, ...props }) => {
-    return (
-      <Button 
-        {...props} 
-        color={props.color as "default" | "primary" | "secondary" | "success" | "warning" | "danger" | undefined}  
-        variant={props.variant as "flat" | "bordered" | "solid" | "light" | "faded" | "shadow" | "ghost" | undefined}
-      >
-        {text}
-      </Button>)
-  },
-  Input: ({ invalid, error, disabled, onChange, ...props }) => {
-    return (
-      <Input 
-        {...props}
-        onValueChange={onChange}
-        errorMessage={error?.message}
-        isInvalid={invalid}
-        isDisabled={disabled}
-        />
-    )
-  },
-  Select: ({ options, invalid, error, isMulti, isSearch, disabled, onChange, value, ...props }) => {
-    return (
-      !isSearch ?
-      <Select 
+## Exports
+
+The package exposes:
+
+- `DynamicModal`
+- `useModalHandler`
+- `ComponentState`
+- `ComponentStateContext`
+- `IComponentState`
+- `IModalConfigLoader`
+- `IModalConfigProps`
+- `IModalRenderCondition`
+- `IModalField`
+- `IModalLiveDataCondition`
+- `IOption`
+
+## Mental model
+
+You use the library in 4 steps:
+
+1. Define the UI components the modal should use in your app.
+2. Wrap your app with `ComponentState`.
+3. Render `DynamicModal` and control it with `useModalHandler`.
+4. Build modal configs as plain objects and open them when needed.
+
+## 1. Provide your own components
+
+`dynamic-modal` does not force a UI kit on you.
+You provide your own inputs, selects, buttons, toggles, and textarea components
+through `ComponentState`, so the modal matches your app visually.
+
+Example:
+
+```tsx
+'use client';
+
+import { ReactNode } from 'react';
+import {
+  Autocomplete,
+  AutocompleteItem,
+  Button,
+  Input,
+  Select,
+  SelectItem,
+  Switch,
+  Textarea,
+} from '@heroui/react';
+import type { IComponentState } from 'dynamic-modal';
+
+export const modalComponents: IComponentState = {
+  ModalButtonCancel: ({ text, color, ...props }) => (
+    <Button {...props} color={color as any} variant="bordered">
+      {text}
+    </Button>
+  ),
+  ModalButtonAction: ({ text, color, ...props }) => (
+    <Button {...props} color={color as any} variant="solid">
+      {text}
+    </Button>
+  ),
+  Button: ({ text, color, variant, ...props }) => (
+    <Button {...props} color={color as any} variant={variant as any}>
+      {text}
+    </Button>
+  ),
+  Input: ({ invalid, error, disabled, onChange, value, ...props }) => (
+    <Input
+      {...props}
+      value={value ?? ''}
+      onValueChange={onChange}
+      errorMessage={error?.message}
+      isInvalid={invalid}
+      isDisabled={disabled}
+    />
+  ),
+  Select: ({
+    options,
+    invalid,
+    error,
+    isMulti,
+    isSearch,
+    disabled,
+    onChange,
+    value,
+    ...props
+  }) =>
+    isSearch ? (
+      <Autocomplete
         {...props}
-        selectedKeys={isMulti ? value : [value]}
-        onSelectionChange={onChange}
-        selectionMode={isMulti ? 'multiple' : 'single'}
-        errorMessage={error?.message}
-        isInvalid={invalid}
-        isDisabled={disabled}
-        >
-        {options.map((option) => (
-          <SelectItem key={option.id}>{option.name}</SelectItem>
-        ))}
-      </Select> :
-      <Autocomplete 
-        {...props} 
         selectedKey={value}
-        onSelectionChange={onChange}
+        onSelectionChange={onChange as any}
         errorMessage={error?.message}
         isInvalid={invalid}
         isDisabled={disabled}
-        >
+      >
         {options.map((item) => (
           <AutocompleteItem key={item.id}>{item.name}</AutocompleteItem>
         ))}
       </Autocomplete>
-    )
-  },
-  Textarea: ({ invalid, error, disabled, ...props }) => {
-    return (
-      <Textarea 
+    ) : (
+      <Select
         {...props}
+        selectedKeys={isMulti ? (value ?? []) : value ? [value] : []}
+        onSelectionChange={onChange as any}
+        selectionMode={isMulti ? 'multiple' : 'single'}
         errorMessage={error?.message}
         isInvalid={invalid}
         isDisabled={disabled}
-        />
-    )
-  },
-  Toggle: ({ value, onChange, label, invalid, ...props }) => {
-    return(
-      <Switch {...props} isSelected={value} onValueChange={onChange}>
-        {label}
-      </Switch>
-    )
-  }
+      >
+        {options.map((option) => (
+          <SelectItem key={option.id}>{option.name}</SelectItem>
+        ))}
+      </Select>
+    ),
+  Textarea: ({ invalid, error, disabled, value, onChange, ...props }) => (
+    <Textarea
+      {...props}
+      value={value ?? ''}
+      onValueChange={onChange}
+      errorMessage={error?.message}
+      isInvalid={invalid}
+      isDisabled={disabled}
+    />
+  ),
+  Toggle: ({ value, onChange, label, ...props }) => (
+    <Switch {...props} isSelected={!!value} onValueChange={onChange}>
+      {label}
+    </Switch>
+  ),
+};
+
+export function ModalProvider({ children }: { children: ReactNode }) {
+  return <ComponentState components={modalComponents}>{children}</ComponentState>;
 }
 ```
 
-In the main provider of your React application, import your modal components (defined previously) and wrap your app with the `ComponentState` component to ensure `dynamic-modal` functions properly. Here’s an example:
-
-```jsx
-import { ComponentState } from 'dynamic-modal'
-import { ModalComponents } from "@data/modal-component/modal-component"
-
-function Provider({ children }: Readonly<{ children: ReactNode }>) {
-  return (
-    <ComponentState components={ModalComponents}>
-      <Component {...pageProps} />
-    </ComponentState>
-  )
-}
+## 2. Add the provider and portal
 
-export default Provider
+Wrap your app with `ComponentState` and add a portal target with the id
+`modal-portal`.
 
-```
-In the root layout define `portal` for modal (this component use react portal)
+### Next.js App Router
 
-```jsx
-//imports...
+```tsx
+import type { ReactNode } from 'react';
 
-export default function RootLayout ({
-  children
-}: Readonly<{
-  children: ReactNode
-}>) {
+export default function RootLayout({
+  children,
+}: Readonly<{ children: ReactNode }>) {
   return (
     <html lang="en">
-      <body className={inter.className}>
-        <Provider>
-          {children}
-        </Provider>
-        <div id='modal-portal'/>
+      <body>
+        <ModalProvider>{children}</ModalProvider>
+        <div id="modal-portal" />
       </body>
     </html>
-  )
+  );
 }
 ```
 
-## Setup for Next.js 13 and old
-Edit file named `_document.tsx` and define `portal` for modal (this component use react portal)
+### Next.js Pages Router
 
-```jsx
-import { Html, Head, Main, NextScript } from 'next/document'
+```tsx
+import { Html, Head, Main, NextScript } from 'next/document';
 
-export default function Document () {
+export default function Document() {
   return (
     <Html>
       <Head />
       <body>
         <Main />
-        <div id='modal-portal'/>
+        <div id="modal-portal" />
         <NextScript />
       </body>
     </Html>
-  )
+  );
 }
 ```
 
-## Usage
-To control the modal’s open and close states, use the `useModalHandler` custom hook and call `openModal` whenever you need to display the modal.
+## 3. Render and control the modal
+
+Use `useModalHandler` to open the modal and render `DynamicModal` once in your
+page or component tree.
+
+```tsx
+'use client';
 
-```jsx
-import { useModalHandler, DynamicModal } from 'dynamic-modal'
-import { Button } from '@nextui-org/react'
-//Create your modal, import and use
-import testModal from '@modal-config/test'
+import { DynamicModal, useModalHandler } from 'dynamic-modal';
+import { Button } from '@heroui/react';
+import simpleModal from './modal-config/simple-modal';
 
-function ExampleComponent() {
-  const { openModal, modalProps } = useModalHandler()
+export default function ExamplePage() {
+  const { openModal, modalProps } = useModalHandler();
 
   return (
     <>
       <Button
         onClick={() => {
-          openModal(testModal.default({}, (data) => {
-            console.log('modal data', data)
-          }))
+          openModal(
+            simpleModal.default(
+              { reserved: 'abc', input1: 'Initial value', store: false },
+              (data) => {
+                console.log('modal result', data);
+              },
+            ),
+          );
         }}
       >
         Open modal
@@ -205,12 +255,462 @@ function ExampleComponent() {
 
       <DynamicModal {...modalProps} />
     </>
-  )
+  );
+}
+```
+
+## 4. Create modal configs
+
+The recommended pattern is to define modal configs with `IModalConfigLoader`.
+This lets you:
+
+- receive input props
+- return a typed modal config
+- receive typed modal output in the `action` callback
+
+Basic example:
+
+```ts
+import type { IModalConfigLoader } from 'dynamic-modal';
+
+type IncomingProps = {
+  reserved: string;
+  input1: string;
+  store?: boolean;
+  clear?: boolean;
+};
+
+type ResultProps = IncomingProps;
+
+const simpleModal: {
+  default: IModalConfigLoader<IncomingProps, ResultProps>;
+} = {
+  default: (props, action) => ({
+    reservedData: {
+      reserved: props.reserved,
+    },
+    title: 'Basic modal',
+    style: {
+      width: '500px',
+    },
+    fields: [
+      {
+        elementType: 'input',
+        label: 'Input 1',
+        name: 'input1',
+        defaultValue: props.input1,
+        validation: {
+          required: true,
+          message: 'This field is required',
+        },
+      },
+      {
+        elementType: 'group',
+        groups: [
+          {
+            elementType: 'toggle',
+            label: 'Store',
+            name: 'store',
+            defaultValue: `${props.store ?? false}`,
+            style: { width: '50%' },
+            validation: {
+              required: false,
+            },
+          },
+          {
+            elementType: 'toggle',
+            label: 'Clear',
+            name: 'clear',
+            defaultValue: `${props.clear ?? false}`,
+            style: { width: '50%' },
+            validation: {
+              required: false,
+            },
+          },
+        ],
+      },
+    ],
+    out: action,
+    actions: {
+      action: { text: 'Save', color: 'primary' },
+      cancel: { text: 'Cancel', color: 'danger' },
+    },
+  }),
+};
+
+export default simpleModal;
+```
+
+## Supported field types
+
+You can build modal UIs with these field types:
+
+- `input`
+- `select`
+- `textarea`
+- `toggle`
+- `text`
+- `upload`
+- `custom-upload`
+- `watcher`
+- `button`
+- `table`
+- `group`
+
+`group` lets you place multiple fields in the same row.
+
+## Conditional behavior
+
+One of the main strengths of the library is dynamic behavior based on form
+state.
+
+### `renderIf`
+
+Use `renderIf` when a field should appear only if another field matches one or
+more values.
+
+```ts
+{
+  elementType: 'input',
+  label: 'Company name',
+  name: 'companyName',
+  validation: {
+    required: true,
+    message: 'Write a company name',
+  },
+  renderIf: {
+    personType: ['company'],
+  },
+}
+```
+
+You can also use `'*'` as a wildcard:
+
+```ts
+renderIf: {
+  personType: ['*'],
+}
+```
+
+### `enableIf`
+
+Use `enableIf` when a field should stay visible but only become editable if a
+condition is met.
+
+```ts
+{
+  elementType: 'input',
+  label: 'Discount code',
+  name: 'discountCode',
+  validation: {
+    required: false,
+  },
+  enableIf: {
+    hasDiscount: ['true'],
+  },
+}
+```
+
+### `liveData`
+
+Use `liveData` when one field depends on another and must fetch options
+dynamically.
+
+```ts
+{
+  elementType: 'select',
+  label: 'City',
+  name: 'cityId',
+  options: [],
+  validation: {
+    required: true,
+    message: 'Select a city',
+  },
+  liveData: {
+    condition: ['countryId'],
+    action: async (countryId, formData) => {
+      const response = await fetch(`/api/cities?countryId=${countryId}`);
+      const data = await response.json();
+
+      return data.map((city: { id: string; name: string }) => ({
+        id: city.id,
+        name: city.name,
+      }));
+    },
+  },
+}
+```
+
+### `watcher`
+
+Use `watcher` when you want to display a derived read-only value built from
+other fields in the same modal.
+
+`watcher` listens to the fields listed in `watchList`, joins their current
+values, and renders the result using your custom `Input` component in disabled
+mode.
+
+Example:
+
+```ts
+{
+  elementType: 'watcher',
+  label: 'Full name preview',
+  watchList: ['firstName', 'middleName', 'lastName'],
+  style: {
+    width: '100%',
+  },
+}
+```
+
+Typical use cases:
+
+- preview a full name from multiple inputs
+- build a quick summary field for the user
+- show a composed display value without storing it as a real form field
+
+## Advanced conditions with async actions
+
+`renderIf` and `enableIf` can also use async logic instead of static value maps.
+This is useful if the decision depends on the backend or on custom business
+rules.
+
+Example:
+
+```ts
+renderIf: {
+  condition: ['customerId'],
+  action: async (customerId, formData) => {
+    const response = await fetch(`/api/customers/${customerId}/can-edit`);
+    const data = await response.json();
+    return data.allowed;
+  },
 }
+```
+
+The same shape works for `enableIf`.
+
+## Examples by use case
 
-export default ExampleComponent
+### 1. Basic modal
 
+Use this when you just need a standard modal with fixed fields.
+
+```ts
+fields: [
+  {
+    elementType: 'input',
+    label: 'Name',
+    name: 'name',
+    validation: { required: true, message: 'Required' },
+  },
+  {
+    elementType: 'textarea',
+    label: 'Description',
+    name: 'description',
+    validation: { required: false },
+  },
+];
+```
+
+### 2. Render fields depending on a select
+
+Use `renderIf` for mutually exclusive sections.
+
+```ts
+fields: [
+  {
+    elementType: 'select',
+    label: 'Mode',
+    name: 'mode',
+    defaultValue: 'email',
+    options: [
+      { id: 'email', name: 'Email' },
+      { id: 'sms', name: 'SMS' },
+    ],
+    validation: { required: true, message: 'Select a mode' },
+  },
+  {
+    elementType: 'input',
+    label: 'Email',
+    name: 'email',
+    validation: { required: true, message: 'Write an email' },
+    renderIf: { mode: ['email'] },
+  },
+  {
+    elementType: 'input',
+    label: 'Phone',
+    name: 'phone',
+    validation: { required: true, message: 'Write a phone' },
+    renderIf: { mode: ['sms'] },
+  },
+];
 ```
 
-## Examples
-The examples folder in the repository contains different configuration modes to help you customize your modal.
+### 3. Keep the field visible but disabled
+
+Use `enableIf` if the user should see the field before it becomes available.
+
+```ts
+{
+  elementType: 'input',
+  label: 'Approval note',
+  name: 'approvalNote',
+  validation: { required: false },
+  enableIf: {
+    status: ['approved'],
+  },
+}
+```
+
+### 4. Load options from another field
+
+Use `liveData` for dependent selects.
+
+```ts
+fields: [
+  {
+    elementType: 'select',
+    label: 'Type',
+    name: 'typeId',
+    options: props.typeList,
+    validation: {
+      required: true,
+      message: 'Please select a valid type',
+    },
+  },
+  {
+    elementType: 'select',
+    label: 'Options',
+    name: 'optionId',
+    options: [],
+    validation: {
+      required: true,
+      message: 'Please select a valid option',
+    },
+    liveData: {
+      condition: ['typeId'],
+      action: props.optionReadAction,
+    },
+  },
+];
+```
+
+### 5. Reserve data that should travel with the result
+
+Use `reservedData` when you want to preserve contextual information without
+showing it in the modal.
+
+```ts
+reservedData: {
+  customerId: props.customerId,
+  source: 'customer-profile',
+}
+```
+
+That data will be merged into the object returned by `out`.
+
+### 6. Compose a read-only value with `watcher`
+
+Use `watcher` when you want the modal to display a value derived from multiple
+fields while the user types.
+
+```ts
+fields: [
+  {
+    elementType: 'input',
+    label: 'First name',
+    name: 'firstName',
+    validation: { required: true, message: 'Required' },
+  },
+  {
+    elementType: 'input',
+    label: 'Last name',
+    name: 'lastName',
+    validation: { required: true, message: 'Required' },
+  },
+  {
+    elementType: 'watcher',
+    label: 'Preview',
+    watchList: ['firstName', 'lastName'],
+    style: { width: '100%' },
+  },
+];
+```
+
+Important notes:
+
+- `watcher` is display-only
+- it does not submit its own value in the modal result
+- it is useful for previews, concatenations, and human-readable summaries
+
+## Configuration reference
+
+### Modal-level config
+
+Common properties of `IModalConfigProps`:
+
+- `title`: modal title
+- `fields`: list of modal elements
+- `out`: callback invoked on submit
+- `reservedData`: extra data merged into the result
+- `onClose`: callback when the modal closes
+- `style`: styles for the modal container
+- `overFlowBody`: body height/overflow control
+- `minHeightBody`: minimum body height
+- `useSubmit`: if `false`, action button uses manual validation mode
+- `useBlur`: enables backdrop blur style
+- `actions.action`: main action button props
+- `actions.cancel`: optional cancel button props
+- `actions.containerStyle`: style for the action buttons container
+
+### Common field properties
+
+Most form fields share:
+
+- `name`
+- `label`
+- `placeholder`
+- `defaultValue`
+- `style`
+- `disabled`
+- `validation`
+- `renderIf`
+- `enableIf`
+
+`watcher` uses:
+
+- `label`
+- `style`
+- `watchList`
+
+Validation supports:
+
+- `required`
+- `message`
+- `regex`
+- `maxLength`
+- `minLength`
+- `min`
+- `max`
+
+## Notes and recommendations
+
+- Render `DynamicModal` only once per screen or page branch when possible.
+- Prefer stable `name` values because they are used to manage form state.
+- Use `renderIf` for hidden sections and `enableIf` for visible-but-locked
+  sections.
+- Keep `liveData` actions fast and deterministic when possible.
+- If your custom UI components use different event contracts, adapt them inside
+  `ComponentState` rather than changing modal configs.
+
+## Repository examples
+
+This repository includes working examples in:
+
+- `examples/simple.ts`
+- `examples/render-if.ts`
+- `examples/enable-if.ts`
+- `examples/live-data.ts`
+
+These are useful starting points for building your own modal catalog.