@insticc/genericform 2.1.2 → 2.1.4

package/README.md

@@ -1,500 +1,500 @@
-# @insticc/genericform
-
-A flexible, schema-driven React form component that renders any combination of field types from a plain JavaScript array. No boilerplate, built-in validation, modal support, and full external state control out of the box.
-
----
-
-## Table of Contents
-
-- [@insticc/genericform](#insticcgenericform)
-  - [Table of Contents](#table-of-contents)
-  - [Installation](#installation)
-  - [Peer Dependencies](#peer-dependencies)
-  - [Quick Start](#quick-start)
-  - [Field Types](#field-types)
-    - [Options format](#options-format)
-  - [Field Schema Reference](#field-schema-reference)
-    - [Common properties](#common-properties)
-    - [Style properties (all optional)](#style-properties-all-optional)
-    - [Type-specific properties](#type-specific-properties)
-  - [GenericForm Props](#genericform-props)
-    - [`customActions`](#customactions)
-  - [Validation](#validation)
-  - [Layout \& Grouping](#layout--grouping)
-    - [Inline fields](#inline-fields)
-    - [Groups](#groups)
-    - [Two-column split](#two-column-split)
-  - [External State Control](#external-state-control)
-  - [Modal Mode](#modal-mode)
-  - [Theming (CSS Variables)](#theming-css-variables)
-  - [Demo Components](#demo-components)
-  - [License](#license)
-
----
-
-## Installation
-
-```bash
-npm install @insticc/genericform
-```
-
-Import the component and its stylesheet:
-
-```jsx
-import GenericForm from '@insticc/genericform';
-```
-
----
-
-## Peer Dependencies
-
-The following must be installed in your project:
-
-| Package | Version |
-|---|---|
-| `react` | ≥ 17 |
-| `react-dom` | ≥ 17 |
-| `react-bootstrap` | ≥ 2 |
-| `semantic-ui-react` | ≥ 2 |
-| `react-datetime` | ≥ 3 |
-
----
-
-## Quick Start
-
-```jsx
-import { useState } from 'react';
-import GenericForm from '@insticc/genericform';
-import '@insticc/genericform/dist/index.css';
-
-const MyForm = () => {
-  const [result, setResult] = useState(null);
-
-  const fields = [
-    { name: 'firstName', type: 'text',   label: 'First Name', required: true,  value: '' },
-    { name: 'lastName',  type: 'text',   label: 'Last Name',  required: true,  value: '' },
-    { name: 'email',     type: 'email',  label: 'Email',      required: true,  value: '' },
-    { name: 'age',       type: 'int',    label: 'Age',        min: 0, max: 120, value: '' },
-    {
-      name: 'country', type: 'select', label: 'Country', value: '',
-      options: [
-        { value: 'PT', text: 'Portugal' },
-        { value: 'ES', text: 'Spain' },
-        { value: 'FR', text: 'France' },
-      ],
-    },
-  ];
-
-  return (
-    <GenericForm
-      title="New User"
-      fields={fields}
-      submitText="Save"
-      onSubmit={(data) => setResult(data)}
-      onCancel={() => setResult(null)}
-    />
-  );
-};
-```
-
-The `onSubmit` callback receives the complete form data object keyed by each field's `name`.
-
----
-
-## Field Types
-
-| `type` value | Rendered as | Key extra props |
-|---|---|---|
-| `text` / `string` | Text input | `placeholder`, `minLength`, `maxLength` |
-| `email` | Email input (format validated) | `placeholder` |
-| `password` | Password input | `placeholder` |
-| `int` / `number` | Number input | `min`, `max`, `step` |
-| `textArea` | Textarea | `rows`, `height`, `maxLength` |
-| `date` | Date picker (DD/MM/YYYY) | `placeholder` |
-| `datetime` | Date + time picker | `placeholder` |
-| `time` | Time picker (HH:mm) | `placeholder` |
-| `year` | Year picker | `minYear`, `maxYear` |
-| `select` | Native `<select>` | `options`, `placeholder`, `multiple` |
-| `multipleDropdown` | Semantic UI multi-select | `options`, `placeholder` |
-| `search` | Semantic UI Search | `options`, `isLoading`, `resultRenderer` |
-| `toggle` | Toggle switch | — |
-| `checkbox` | Single checkbox | `onOptionChange` |
-| `checkboxGroup` | Group of checkboxes | `options`, `grouped`, `onOptionChange` |
-| `radioGroup` | Stacked radio buttons | `options`, `onOptionChange` |
-| `radioGroupInline` | Inline radio buttons | `options`, `onOptionChange` |
-| `json` | JSON textarea editor | `datatype`, `allowModeSwitch`, `storeAsString`, `rows` |
-| `accordion` | Collapsible section | `sections`, `defaultOpen`, `activeAllIndex` |
-| `component` | Arbitrary JSX embed | `component` |
-| `label` | Section heading | — |
-| `hr` / `separator` | Horizontal rule | — |
-
-### Options format
-
-The `select`, `multipleDropdown`, `checkboxGroup`, and radio types all accept options in any of these shapes — the component resolves them automatically:
-
-```js
-{ value: 'pt', text: 'Portugal' }   // most common
-{ id: 'admin', label: 'Admin' }
-{ name: 'read', label: 'Read' }
-```
-
----
-
-## Field Schema Reference
-
-Every item in the `fields` array is a plain object. The properties below apply across all (or most) field types.
-
-### Common properties
-
-| Property | Type | Default | Description |
-|---|---|---|---|
-| `name` | `string` | — | **Required.** Unique key; used as the form data key. |
-| `type` | `string` | `'text'` | Field type (see table above). |
-| `label` / `displayName` | `string \| node` | — | Label shown above the field. |
-| `value` | `any` | — | Initial (or controlled) value. |
-| `required` | `bool` | `false` | Adds `*` indicator and enforces non-empty on submit. |
-| `disabled` | `bool` | `false` | Disables the input. |
-| `placeholder` | `string` | `displayName` | Input placeholder text. |
-| `tooltip` | `string` | — | Tooltip shown next to the label. |
-| `showHelp` | `bool` | `false` | Show ⓘ help icon. |
-| `helpText` | `string` | — | Text shown in the help icon tooltip. |
-| `errorMessage` | `string` | auto | Custom message shown on validation failure. |
-| `validate` | `function` | — | `(value, formData) => string \| null`. Return a string to show as error. |
-| `onChange` | `function` | — | `(value, formData) => void`. Per-field change callback (in addition to `onFieldChange`). |
-| `hide` | `bool \| function` | `false` | `(formData, field) => bool`. Hides the field dynamically. |
-| `inline` | `bool` | `false` | Renders this field side-by-side with adjacent `inline` fields. |
-| `group` | `string` | — | Groups fields under a named section heading. Groups render in alphabetical order, ungrouped fields last. |
-
-### Style properties (all optional)
-
-| Property | Type | Description |
-|---|---|---|
-| `style` / `mainDivStyle` | `object` | Style applied to the outer wrapper `<div>`. |
-| `labelStyle` | `object` | Style applied to the `<label>` element. |
-| `spanStyle` | `object` | Style applied to the required `*` span. |
-| `inputStyle` | `object` | Style applied to the input element. |
-| `tooltipStyle` | `object` | Style applied to the tooltip span. |
-| `className` | `string` | Extra CSS class for text/email/password inputs. |
-
-### Type-specific properties
-
-**`int` / `number`**
-```js
-{ name: 'score', type: 'number', min: 0, max: 100, step: 0.5, value: '' }
-```
-
-**`textArea`**
-```js
-{ name: 'bio', type: 'textArea', rows: 4, height: '120px', maxLength: 300, value: '' }
-```
-
-**`select`**
-```js
-{
-  name: 'country', type: 'select',
-  options: [{ value: 'PT', text: 'Portugal' }],
-  multiple: false,   // set true for native multi-select
-  value: '',
-}
-```
-
-**`checkboxGroup`**
-```js
-{
-  name: 'perms', type: 'checkboxGroup',
-  value: ['read'],   // array of selected names
-  options: [
-    { name: 'read',   label: 'Read' },
-    { name: 'write',  label: 'Write' },
-    { name: 'delete', label: 'Delete' },
-  ],
-  grouped: false,   // true renders a visual group border
-}
-```
-
-**`json`**
-```js
-{
-  name: 'config', type: 'json',
-  datatype: 'object',       // 'string' | 'number' | 'object'
-  allowModeSwitch: true,    // toggle between single / multiple (array) mode
-  storeAsString: false,     // keep raw string in formData instead of parsed value
-  rows: 6,
-  value: '',
-}
-```
-
-**`accordion`**
-```js
-{
-  name: 'advanced', type: 'accordion',
-  defaultOpen: false,
-  activeAllIndex: false,   // open all sections by default
-  sections: [
-    { title: 'Config',      icon: '⚙️', content: <p>…</p> },
-    { title: 'Danger zone', icon: '⚠️', content: <p>…</p> },
-  ],
-}
-```
-
-**`component`**
-```js
-{
-  name: 'avatar', type: 'component',
-  displayName: 'Avatar preview',
-  component: <MyAvatarWidget />,
-}
-```
-
----
-
-## GenericForm Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `fields` | `array` | `[]` | **Required.** Array of field schema objects. |
-| `title` | `string \| node` | — | Form heading. |
-| `titleIcon` | `node` | — | Icon rendered before the title. |
-| `titleStyle` | `object` | — | Style for the title element. |
-| `onSubmit` | `async function` | — | `(formData) => void`. Called after successful validation. |
-| `handleSubmit` | `function` | — | Legacy: receives the native submit event instead of formData. |
-| `onCancel` | `function` | — | Called when the Cancel button is clicked. |
-| `onDataChange` | `function` | — | `(formData) => void`. Fired on every field change with the full snapshot. |
-| `onFieldChange` | `function` | — | `({ name, value, option? }) => void`. Fired per field change. |
-| `validateOnChange` | `bool` | `true` | Validate each field as the user types. |
-| `validateOnSubmit` | `bool` | `true` | Validate all fields before calling `onSubmit`. |
-| `submitText` | `string` | `'Submit'` | Label on the submit button. |
-| `cancelText` | `string` | `'Cancel'` | Label on the cancel button. |
-| `showSubmit` | `bool` | `true` | Show the submit button. |
-| `showCancel` | `bool` | `true` | Show the cancel button. |
-| `haveSaveButton` | `bool` | `true` | Alias for `showSubmit`. |
-| `submitButton` | `object` | `{}` | `{ className, style, icon }` overrides for the submit button. |
-| `cancelButton` | `object` | `{}` | `{ className, style, icon }` overrides for the cancel button. |
-| `customActions` | `array` | `[]` | Extra buttons in the actions bar (see below). |
-| `splitForm` | `bool` | `false` | Render fields in a two-column layout. |
-| `splitField` | `string` | — | Field `name` at which to split left/right columns. |
-| `splitGroup` | `bool` | `false` | Split at the group boundary instead of a specific field. |
-| `enableModal` | `bool` | `false` | Wrap the form in a React Bootstrap `<Modal>`. |
-| `modalShow` | `bool` | `false` | Controls modal visibility. |
-| `modalSize` | `string` | `'lg'` | Bootstrap modal size (`'sm'`, `'lg'`, `'xl'`). |
-| `disableDefaultContainer` | `bool` | `false` | Remove the default card/shadow wrapper `<div>`. |
-| `containerStyle` | `object` | `{}` | Style for the outermost container. |
-| `formStyle` | `object` | — | Style for the `<form>` element. |
-| `fieldsStyle` | `object` | — | Style for each fields section wrapper. |
-| `actionsDivStyle` | `object` | — | Style for the actions bar wrapper. |
-| `actionsStyle` | `object` | — | Style applied to every action button. |
-| `handleSearchChange` | `function` | — | Passed directly to the `search` field type. |
-| `handleResultSelect` | `function` | — | Passed directly to the `search` field type. |
-| `resultRenderer` | `function` | — | Custom result item renderer for the `search` type. |
-
-### `customActions`
-
-Inject additional buttons into the actions bar:
-
-```jsx
-<GenericForm
-  fields={fields}
-  customActions={[
-    {
-      label: 'Reset',
-      icon: <ResetIcon />,        // optional
-      className: 'ufg-button-secondary',
-      style: {},
-      disabled: false,
-      onClick: () => resetMyForm(),
-    },
-  ]}
-/>
-```
-
----
-
-## Validation
-
-Validation runs on change (if `validateOnChange`) and on submit (if `validateOnSubmit`). Built-in rules cover the most common cases:
-
-| Rule | Prop | Example |
-|---|---|---|
-| Required | `required: true` | Non-empty value |
-| Email format | `type: 'email'` | Must match `x@x.x` |
-| Min length | `minLength: 3` | At least 3 characters |
-| Max length | `maxLength: 20` | At most 20 characters |
-| Numeric min | `min: 0` | Value ≥ 0 |
-| Numeric max | `max: 100` | Value ≤ 100 |
-| Custom | `validate` function | Any logic |
-
-**Custom validation:**
-
-```js
-{
-  name: 'website', type: 'text', value: '',
-  validate: (value, formData) => {
-    if (value && !value.startsWith('https://')) return 'Must start with https://';
-    return null; // no error
-  },
-}
-```
-
-**Cross-field validation** — the second argument is the live form data object:
-
-```js
-{
-  name: 'notifyEmail', type: 'email', value: '',
-  hide: (fd) => !fd.notify,
-  validate: (value, fd) =>
-    fd.notify && !value ? 'Required when notifications are enabled' : null,
-}
-```
-
-Override the default error message with `errorMessage`:
-
-```js
-{ name: 'name', type: 'text', required: true, errorMessage: 'Please enter your full name.' }
-```
-
----
-
-## Layout & Grouping
-
-### Inline fields
-
-Set `inline: true` on consecutive fields to render them side-by-side:
-
-```js
-{ name: 'firstName', type: 'text', label: 'First name', inline: true, value: '' },
-{ name: 'lastName',  type: 'text', label: 'Last name',  inline: true, value: '' },
-```
-
-### Groups
-
-Assign a `group` string to organise fields under labelled sections. Groups are sorted alphabetically; ungrouped fields appear last.
-
-```js
-{ name: 'email',   type: 'email', group: 'Contact', value: '' },
-{ name: 'phone',   type: 'text',  group: 'Contact', value: '' },
-{ name: 'country', type: 'select', group: 'Address', value: '', options: [...] },
-```
-
-### Two-column split
-
-```jsx
-<GenericForm
-  fields={fields}
-  splitForm
-  splitField="address"   // everything up to and including 'address' goes left
-/>
-```
-
-Use `splitGroup` to split at a group boundary rather than a specific field.
-
----
-
-## External State Control
-
-`GenericForm` manages its own internal state, but every field's `value` prop is watched. When a `value` changes, the form merges only that field — which means you can drive specific fields from a parent `useState` without re-initialising the whole form.
-
-The recommended pattern for full external control uses `onDataChange`:
-
-```jsx
-const [formState, setFormState] = useState({
-  firstName: '', lastName: '', country: '', city: '',
-});
-
-// Auto-fill city when country changes
-const handleFieldChange = ({ name, value }) => {
-  if (name === 'country') {
-    setFormState(prev => ({ ...prev, city: CITY_BY_COUNTRY[value] ?? '' }));
-  }
-};
-
-const fields = [
-  { name: 'firstName', type: 'text',   label: 'First name', value: formState.firstName },
-  { name: 'lastName',  type: 'text',   label: 'Last name',  value: formState.lastName  },
-  { name: 'country',   type: 'select', label: 'Country',    value: formState.country, options: COUNTRIES },
-  { name: 'city',      type: 'text',   label: 'City',       value: formState.city, disabled: true },
-];
-
-<GenericForm
-  fields={fields}
-  onDataChange={setFormState}
-  onFieldChange={handleFieldChange}
-  onSubmit={(data) => console.log('Saved:', data)}
-/>
-```
-
-You can also write directly to `formState` from outside the form (e.g. a "Load profile" button) — the form will detect the changed `value` props and update only the affected fields.
-
----
-
-## Modal Mode
-
-Wrap the form in a React Bootstrap modal with no extra markup:
-
-```jsx
-const [show, setShow] = useState(false);
-
-<GenericForm
-  title="Edit User"
-  fields={fields}
-  enableModal
-  modalShow={show}
-  modalSize="lg"
-  onSubmit={(data) => { saveUser(data); setShow(false); }}
-  onCancel={() => setShow(false)}
-/>
-```
-
-> **Note:** Import React Bootstrap's CSS in your app root if you haven't already:
-> ```js
-> import 'bootstrap/dist/css/bootstrap.min.css';
-> ```
-
----
-
-## Theming (CSS Variables)
-
-Override any of the following CSS custom properties to match your design system:
-
-```css
-:root {
-  --ufg-primary:        #1d4ed8;   /* submit button, active toggle */
-  --ufg-primary-dark:   #1e40af;
-  --ufg-primary-darker: #1e3a8a;
-  --ufg-error:          #dc2626;   /* validation error text */
-  --ufg-border:         #cbd5e1;   /* input borders */
-  --ufg-bg:             #ffffff;   /* card background */
-  --ufg-surface:        #fafafa;   /* secondary surfaces */
-  --ufg-text:           #111111;   /* primary text */
-  --ufg-text-secondary: #6b7280;   /* placeholder, help text */
-  --ufg-radius:         10px;      /* input border radius */
-  --ufg-shadow:         0 10px 30px rgba(0, 0, 0, 0.12);
-}
-```
-
----
-
-## Demo Components
-
-Two reference implementations are bundled and exported:
-
-```jsx
-import GenericForm, { Demo, Demo2 } from '@insticc/genericform';
-
-// Every field type, conditional visibility, validation, custom actions:
-<Demo />
-
-// Full external state management with live formState sidebar:
-<Demo2 />
-```
-
-`Demo` covers all 18 field types, conditional field visibility via `hide`, cross-field validation, inline layout, accordion, and custom action buttons.
-
-`Demo2` demonstrates the `onDataChange` + `onFieldChange` pattern for parent-driven state, including dependent field auto-fill (country → city) and a live field-change event log.
-
----
-
-## License
-
-ISC
-
+# @insticc/genericform
+
+A flexible, schema-driven React form component that renders any combination of field types from a plain JavaScript array. No boilerplate, built-in validation, modal support, and full external state control out of the box.
+
+---
+
+## Table of Contents
+
+- [@insticc/genericform](#insticcgenericform)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Peer Dependencies](#peer-dependencies)
+  - [Quick Start](#quick-start)
+  - [Field Types](#field-types)
+    - [Options format](#options-format)
+  - [Field Schema Reference](#field-schema-reference)
+    - [Common properties](#common-properties)
+    - [Style properties (all optional)](#style-properties-all-optional)
+    - [Type-specific properties](#type-specific-properties)
+  - [GenericForm Props](#genericform-props)
+    - [`customActions`](#customactions)
+  - [Validation](#validation)
+  - [Layout \& Grouping](#layout--grouping)
+    - [Inline fields](#inline-fields)
+    - [Groups](#groups)
+    - [Two-column split](#two-column-split)
+  - [External State Control](#external-state-control)
+  - [Modal Mode](#modal-mode)
+  - [Theming (CSS Variables)](#theming-css-variables)
+  - [Demo Components](#demo-components)
+  - [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @insticc/genericform
+```
+
+Import the component and its stylesheet:
+
+```jsx
+import GenericForm from '@insticc/genericform';
+```
+
+---
+
+## Peer Dependencies
+
+The following must be installed in your project:
+
+| Package | Version |
+|---|---|
+| `react` | ≥ 17 |
+| `react-dom` | ≥ 17 |
+| `react-bootstrap` | ≥ 2 |
+| `semantic-ui-react` | ≥ 2 |
+| `react-datetime` | ≥ 3 |
+
+---
+
+## Quick Start
+
+```jsx
+import { useState } from 'react';
+import GenericForm from '@insticc/genericform';
+import '@insticc/genericform/dist/index.css';
+
+const MyForm = () => {
+  const [result, setResult] = useState(null);
+
+  const fields = [
+    { name: 'firstName', type: 'text',   label: 'First Name', required: true,  value: '' },
+    { name: 'lastName',  type: 'text',   label: 'Last Name',  required: true,  value: '' },
+    { name: 'email',     type: 'email',  label: 'Email',      required: true,  value: '' },
+    { name: 'age',       type: 'int',    label: 'Age',        min: 0, max: 120, value: '' },
+    {
+      name: 'country', type: 'select', label: 'Country', value: '',
+      options: [
+        { value: 'PT', text: 'Portugal' },
+        { value: 'ES', text: 'Spain' },
+        { value: 'FR', text: 'France' },
+      ],
+    },
+  ];
+
+  return (
+    <GenericForm
+      title="New User"
+      fields={fields}
+      submitText="Save"
+      onSubmit={(data) => setResult(data)}
+      onCancel={() => setResult(null)}
+    />
+  );
+};
+```
+
+The `onSubmit` callback receives the complete form data object keyed by each field's `name`.
+
+---
+
+## Field Types
+
+| `type` value | Rendered as | Key extra props |
+|---|---|---|
+| `text` / `string` | Text input | `placeholder`, `minLength`, `maxLength` |
+| `email` | Email input (format validated) | `placeholder` |
+| `password` | Password input | `placeholder` |
+| `int` / `number` | Number input | `min`, `max`, `step` |
+| `textArea` | Textarea | `rows`, `height`, `maxLength` |
+| `date` | Date picker (DD/MM/YYYY) | `placeholder` |
+| `datetime` | Date + time picker | `placeholder` |
+| `time` | Time picker (HH:mm) | `placeholder` |
+| `year` | Year picker | `minYear`, `maxYear` |
+| `select` | Native `<select>` | `options`, `placeholder`, `multiple` |
+| `multipleDropdown` | Semantic UI multi-select | `options`, `placeholder` |
+| `search` | Semantic UI Search | `options`, `isLoading`, `resultRenderer` |
+| `toggle` | Toggle switch | — |
+| `checkbox` | Single checkbox | `onOptionChange` |
+| `checkboxGroup` | Group of checkboxes | `options`, `grouped`, `onOptionChange` |
+| `radioGroup` | Stacked radio buttons | `options`, `onOptionChange` |
+| `radioGroupInline` | Inline radio buttons | `options`, `onOptionChange` |
+| `json` | JSON textarea editor | `datatype`, `allowModeSwitch`, `storeAsString`, `rows` |
+| `accordion` | Collapsible section | `sections`, `defaultOpen`, `activeAllIndex` |
+| `component` | Arbitrary JSX embed | `component` |
+| `label` | Section heading | — |
+| `hr` / `separator` | Horizontal rule | — |
+
+### Options format
+
+The `select`, `multipleDropdown`, `checkboxGroup`, and radio types all accept options in any of these shapes — the component resolves them automatically:
+
+```js
+{ value: 'pt', text: 'Portugal' }   // most common
+{ id: 'admin', label: 'Admin' }
+{ name: 'read', label: 'Read' }
+```
+
+---
+
+## Field Schema Reference
+
+Every item in the `fields` array is a plain object. The properties below apply across all (or most) field types.
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | — | **Required.** Unique key; used as the form data key. |
+| `type` | `string` | `'text'` | Field type (see table above). |
+| `label` / `displayName` | `string \| node` | — | Label shown above the field. |
+| `value` | `any` | — | Initial (or controlled) value. |
+| `required` | `bool` | `false` | Adds `*` indicator and enforces non-empty on submit. |
+| `disabled` | `bool` | `false` | Disables the input. |
+| `placeholder` | `string` | `displayName` | Input placeholder text. |
+| `tooltip` | `string` | — | Tooltip shown next to the label. |
+| `showHelp` | `bool` | `false` | Show ⓘ help icon. |
+| `helpText` | `string` | — | Text shown in the help icon tooltip. |
+| `errorMessage` | `string` | auto | Custom message shown on validation failure. |
+| `validate` | `function` | — | `(value, formData) => string \| null`. Return a string to show as error. |
+| `onChange` | `function` | — | `(value, formData) => void`. Per-field change callback (in addition to `onFieldChange`). |
+| `hide` | `bool \| function` | `false` | `(formData, field) => bool`. Hides the field dynamically. |
+| `inline` | `bool` | `false` | Renders this field side-by-side with adjacent `inline` fields. |
+| `group` | `string` | — | Groups fields under a named section heading. Groups render in alphabetical order, ungrouped fields last. |
+
+### Style properties (all optional)
+
+| Property | Type | Description |
+|---|---|---|
+| `style` / `mainDivStyle` | `object` | Style applied to the outer wrapper `<div>`. |
+| `labelStyle` | `object` | Style applied to the `<label>` element. |
+| `spanStyle` | `object` | Style applied to the required `*` span. |
+| `inputStyle` | `object` | Style applied to the input element. |
+| `tooltipStyle` | `object` | Style applied to the tooltip span. |
+| `className` | `string` | Extra CSS class for text/email/password inputs. |
+
+### Type-specific properties
+
+**`int` / `number`**
+```js
+{ name: 'score', type: 'number', min: 0, max: 100, step: 0.5, value: '' }
+```
+
+**`textArea`**
+```js
+{ name: 'bio', type: 'textArea', rows: 4, height: '120px', maxLength: 300, value: '' }
+```
+
+**`select`**
+```js
+{
+  name: 'country', type: 'select',
+  options: [{ value: 'PT', text: 'Portugal' }],
+  multiple: false,   // set true for native multi-select
+  value: '',
+}
+```
+
+**`checkboxGroup`**
+```js
+{
+  name: 'perms', type: 'checkboxGroup',
+  value: ['read'],   // array of selected names
+  options: [
+    { name: 'read',   label: 'Read' },
+    { name: 'write',  label: 'Write' },
+    { name: 'delete', label: 'Delete' },
+  ],
+  grouped: false,   // true renders a visual group border
+}
+```
+
+**`json`**
+```js
+{
+  name: 'config', type: 'json',
+  datatype: 'object',       // 'string' | 'number' | 'object'
+  allowModeSwitch: true,    // toggle between single / multiple (array) mode
+  storeAsString: false,     // keep raw string in formData instead of parsed value
+  rows: 6,
+  value: '',
+}
+```
+
+**`accordion`**
+```js
+{
+  name: 'advanced', type: 'accordion',
+  defaultOpen: false,
+  activeAllIndex: false,   // open all sections by default
+  sections: [
+    { title: 'Config',      icon: '⚙️', content: <p>…</p> },
+    { title: 'Danger zone', icon: '⚠️', content: <p>…</p> },
+  ],
+}
+```
+
+**`component`**
+```js
+{
+  name: 'avatar', type: 'component',
+  displayName: 'Avatar preview',
+  component: <MyAvatarWidget />,
+}
+```
+
+---
+
+## GenericForm Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `fields` | `array` | `[]` | **Required.** Array of field schema objects. |
+| `title` | `string \| node` | — | Form heading. |
+| `titleIcon` | `node` | — | Icon rendered before the title. |
+| `titleStyle` | `object` | — | Style for the title element. |
+| `onSubmit` | `async function` | — | `(formData) => void`. Called after successful validation. |
+| `handleSubmit` | `function` | — | Legacy: receives the native submit event instead of formData. |
+| `onCancel` | `function` | — | Called when the Cancel button is clicked. |
+| `onDataChange` | `function` | — | `(formData) => void`. Fired on every field change with the full snapshot. |
+| `onFieldChange` | `function` | — | `({ name, value, option? }) => void`. Fired per field change. |
+| `validateOnChange` | `bool` | `true` | Validate each field as the user types. |
+| `validateOnSubmit` | `bool` | `true` | Validate all fields before calling `onSubmit`. |
+| `submitText` | `string` | `'Submit'` | Label on the submit button. |
+| `cancelText` | `string` | `'Cancel'` | Label on the cancel button. |
+| `showSubmit` | `bool` | `true` | Show the submit button. |
+| `showCancel` | `bool` | `true` | Show the cancel button. |
+| `haveSaveButton` | `bool` | `true` | Alias for `showSubmit`. |
+| `submitButton` | `object` | `{}` | `{ className, style, icon }` overrides for the submit button. |
+| `cancelButton` | `object` | `{}` | `{ className, style, icon }` overrides for the cancel button. |
+| `customActions` | `array` | `[]` | Extra buttons in the actions bar (see below). |
+| `splitForm` | `bool` | `false` | Render fields in a two-column layout. |
+| `splitField` | `string` | — | Field `name` at which to split left/right columns. |
+| `splitGroup` | `bool` | `false` | Split at the group boundary instead of a specific field. |
+| `enableModal` | `bool` | `false` | Wrap the form in a React Bootstrap `<Modal>`. |
+| `modalShow` | `bool` | `false` | Controls modal visibility. |
+| `modalSize` | `string` | `'lg'` | Bootstrap modal size (`'sm'`, `'lg'`, `'xl'`). |
+| `disableDefaultContainer` | `bool` | `false` | Remove the default card/shadow wrapper `<div>`. |
+| `containerStyle` | `object` | `{}` | Style for the outermost container. |
+| `formStyle` | `object` | — | Style for the `<form>` element. |
+| `fieldsStyle` | `object` | — | Style for each fields section wrapper. |
+| `actionsDivStyle` | `object` | — | Style for the actions bar wrapper. |
+| `actionsStyle` | `object` | — | Style applied to every action button. |
+| `handleSearchChange` | `function` | — | Passed directly to the `search` field type. |
+| `handleResultSelect` | `function` | — | Passed directly to the `search` field type. |
+| `resultRenderer` | `function` | — | Custom result item renderer for the `search` type. |
+
+### `customActions`
+
+Inject additional buttons into the actions bar:
+
+```jsx
+<GenericForm
+  fields={fields}
+  customActions={[
+    {
+      label: 'Reset',
+      icon: <ResetIcon />,        // optional
+      className: 'ufg-button-secondary',
+      style: {},
+      disabled: false,
+      onClick: () => resetMyForm(),
+    },
+  ]}
+/>
+```
+
+---
+
+## Validation
+
+Validation runs on change (if `validateOnChange`) and on submit (if `validateOnSubmit`). Built-in rules cover the most common cases:
+
+| Rule | Prop | Example |
+|---|---|---|
+| Required | `required: true` | Non-empty value |
+| Email format | `type: 'email'` | Must match `x@x.x` |
+| Min length | `minLength: 3` | At least 3 characters |
+| Max length | `maxLength: 20` | At most 20 characters |
+| Numeric min | `min: 0` | Value ≥ 0 |
+| Numeric max | `max: 100` | Value ≤ 100 |
+| Custom | `validate` function | Any logic |
+
+**Custom validation:**
+
+```js
+{
+  name: 'website', type: 'text', value: '',
+  validate: (value, formData) => {
+    if (value && !value.startsWith('https://')) return 'Must start with https://';
+    return null; // no error
+  },
+}
+```
+
+**Cross-field validation** — the second argument is the live form data object:
+
+```js
+{
+  name: 'notifyEmail', type: 'email', value: '',
+  hide: (fd) => !fd.notify,
+  validate: (value, fd) =>
+    fd.notify && !value ? 'Required when notifications are enabled' : null,
+}
+```
+
+Override the default error message with `errorMessage`:
+
+```js
+{ name: 'name', type: 'text', required: true, errorMessage: 'Please enter your full name.' }
+```
+
+---
+
+## Layout & Grouping
+
+### Inline fields
+
+Set `inline: true` on consecutive fields to render them side-by-side:
+
+```js
+{ name: 'firstName', type: 'text', label: 'First name', inline: true, value: '' },
+{ name: 'lastName',  type: 'text', label: 'Last name',  inline: true, value: '' },
+```
+
+### Groups
+
+Assign a `group` string to organise fields under labelled sections. Groups are sorted alphabetically; ungrouped fields appear last.
+
+```js
+{ name: 'email',   type: 'email', group: 'Contact', value: '' },
+{ name: 'phone',   type: 'text',  group: 'Contact', value: '' },
+{ name: 'country', type: 'select', group: 'Address', value: '', options: [...] },
+```
+
+### Two-column split
+
+```jsx
+<GenericForm
+  fields={fields}
+  splitForm
+  splitField="address"   // everything up to and including 'address' goes left
+/>
+```
+
+Use `splitGroup` to split at a group boundary rather than a specific field.
+
+---
+
+## External State Control
+
+`GenericForm` manages its own internal state, but every field's `value` prop is watched. When a `value` changes, the form merges only that field — which means you can drive specific fields from a parent `useState` without re-initialising the whole form.
+
+The recommended pattern for full external control uses `onDataChange`:
+
+```jsx
+const [formState, setFormState] = useState({
+  firstName: '', lastName: '', country: '', city: '',
+});
+
+// Auto-fill city when country changes
+const handleFieldChange = ({ name, value }) => {
+  if (name === 'country') {
+    setFormState(prev => ({ ...prev, city: CITY_BY_COUNTRY[value] ?? '' }));
+  }
+};
+
+const fields = [
+  { name: 'firstName', type: 'text',   label: 'First name', value: formState.firstName },
+  { name: 'lastName',  type: 'text',   label: 'Last name',  value: formState.lastName  },
+  { name: 'country',   type: 'select', label: 'Country',    value: formState.country, options: COUNTRIES },
+  { name: 'city',      type: 'text',   label: 'City',       value: formState.city, disabled: true },
+];
+
+<GenericForm
+  fields={fields}
+  onDataChange={setFormState}
+  onFieldChange={handleFieldChange}
+  onSubmit={(data) => console.log('Saved:', data)}
+/>
+```
+
+You can also write directly to `formState` from outside the form (e.g. a "Load profile" button) — the form will detect the changed `value` props and update only the affected fields.
+
+---
+
+## Modal Mode
+
+Wrap the form in a React Bootstrap modal with no extra markup:
+
+```jsx
+const [show, setShow] = useState(false);
+
+<GenericForm
+  title="Edit User"
+  fields={fields}
+  enableModal
+  modalShow={show}
+  modalSize="lg"
+  onSubmit={(data) => { saveUser(data); setShow(false); }}
+  onCancel={() => setShow(false)}
+/>
+```
+
+> **Note:** Import React Bootstrap's CSS in your app root if you haven't already:
+> ```js
+> import 'bootstrap/dist/css/bootstrap.min.css';
+> ```
+
+---
+
+## Theming (CSS Variables)
+
+Override any of the following CSS custom properties to match your design system:
+
+```css
+:root {
+  --ufg-primary:        #1d4ed8;   /* submit button, active toggle */
+  --ufg-primary-dark:   #1e40af;
+  --ufg-primary-darker: #1e3a8a;
+  --ufg-error:          #dc2626;   /* validation error text */
+  --ufg-border:         #cbd5e1;   /* input borders */
+  --ufg-bg:             #ffffff;   /* card background */
+  --ufg-surface:        #fafafa;   /* secondary surfaces */
+  --ufg-text:           #111111;   /* primary text */
+  --ufg-text-secondary: #6b7280;   /* placeholder, help text */
+  --ufg-radius:         10px;      /* input border radius */
+  --ufg-shadow:         0 10px 30px rgba(0, 0, 0, 0.12);
+}
+```
+
+---
+
+## Demo Components
+
+Two reference implementations are bundled and exported:
+
+```jsx
+import GenericForm, { Demo, Demo2 } from '@insticc/genericform';
+
+// Every field type, conditional visibility, validation, custom actions:
+<Demo />
+
+// Full external state management with live formState sidebar:
+<Demo2 />
+```
+
+`Demo` covers all 18 field types, conditional field visibility via `hide`, cross-field validation, inline layout, accordion, and custom action buttons.
+
+`Demo2` demonstrates the `onDataChange` + `onFieldChange` pattern for parent-driven state, including dependent field auto-fill (country → city) and a live field-change event log.
+
+---
+
+## License
+
+ISC
+
 ---