@insticc/genericform 2.0.4 → 2.0.6

package/README.md

@@ -0,0 +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
+
+---

package/build/index.css

@@ -254,6 +254,7 @@
 	height: 18px;
 	cursor: pointer;
 	margin: 0;
+	aspect-ratio: 1;
 }
 
 .ufg-checkbox-item label,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insticc/genericform",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "A generic form with a comprehensive set of field types, validation, and external state management",
   "main": "build/index.js",
   "scripts": {