@petrarca/sonnet-forms 0.6.0 → 0.7.0

package/README.md

@@ -1,276 +1,101 @@
 # @petrarca/sonnet-forms
 
-Schema-driven form renderer and field components for the Petrarca Sonnet
-component library.
+Schema-driven forms for the Petrarca Sonnet component library. One component,
+`JsonSchemaFormRenderer`, takes a JSON Schema and a data object and produces
+labelled, validated controls.
 
-## What's included
+## What it provides
 
-**JsonSchemaFormRenderer** — Renders a complete form from a JSON Schema with
-automatic widget resolution, validation, nested objects, arrays, and custom
-UI schema overrides.
+**The renderer.** `$ref` resolution, `if`/`then`/`else` and `allOf`/`anyOf`
+flattening against the current values, schema defaults, nested objects and
+arrays, buffered or live editing, and a change set on save.
 
-**Form field components** — Standalone fields with label, description, error,
-and compact mode: `FormInput`, `FormTextarea`, `FormSelect`, `FormMultiSelect`,
-`FormCheckbox`, `FormTagsInput`, `FormNumberInput`, `FormQuantityInput`.
+**A widget registry.** Sixteen built-in controls covering text, numbers,
+quantities, enums, checkboxes, tags, arrays, objects, entity references and
+embedded JSON, plus your own controls keyed by `x-ui-widget`. A parallel
+template registry makes the structure around a field -- the array-item row, the
+object container, the group chrome -- replaceable without touching the widgets.
 
-**Widget system** — Extensible widget registry mapping schema types/formats to
-UI controls. Built-in widgets for text, number, select, checkbox, textarea,
-tags, quantity, arrays, objects, entity references, and JSON editing.
+**Layout.** Rows, tabs, steps and sections, declared as `x-ui-*` hints on the
+schema or in a UI schema passed beside it.
 
----
+**Standalone field components.** `FormInput`, `FormTextarea`, `FormSelect`,
+`FormMultiSelect`, `FormCheckbox`, `FormNumberInput`, `FormQuantityInput` and
+`FormTagsInput`, for labelled inputs outside a schema-driven form.
+
+**Change tracking.** `onUpdate` reports what changed, including inside arrays,
+so a caller can send a targeted update rather than the whole object.
 
 ## Install
 
 ```bash
-pnpm add @petrarca/sonnet-forms @petrarca/sonnet-ui @petrarca/sonnet-core
+pnpm add @petrarca/sonnet-forms
 ```
 
-Peer dependencies: `react >=19`, `react-dom >=19`, `tailwindcss`.
+`@petrarca/sonnet-core` and `@petrarca/sonnet-ui` are regular dependencies and
+arrive with it.
 
----
+| Peer | Range | Needed for |
+|---|---|---|
+| `react`, `react-dom` | `>=19` | Everything |
+| `tailwindcss` | `>=3` | The classes every component emits |
 
-## Basic usage
+The output assumes `sonnet-ui`'s stylesheet and Tailwind preset are already
+wired up. Do that first -- see
+[sonnet-ui: getting started](../sonnet-ui/docs/usage/getting-started.md).
 
-### JsonSchemaFormRenderer
+## Usage
 
 ```tsx
 import { JsonSchemaFormRenderer } from "@petrarca/sonnet-forms";
+import type { JsonSchema } from "@petrarca/sonnet-core/schema";
 
-const schema = {
+const WIDGET_SCHEMA: JsonSchema = {
+  title: "Widget",
   type: "object",
+  required: ["name"],
   properties: {
-    name:  { type: "string", title: "Name" },
-    email: { type: "string", format: "email", title: "Email" },
-    age:   { type: "integer", title: "Age" },
+    name: { type: "string", title: "Name" },
+    status: {
+      type: "string",
+      title: "Status",
+      enum: ["draft", "active", "retired"],
+      default: "draft",
+    },
+    notes: { type: "string", title: "Notes", "x-ui-widget": "textarea" },
   },
-  required: ["name", "email"],
 };
 
 <JsonSchemaFormRenderer
-  schema={schema}
-  data={formData}
-  onUpdate={(data, changedFields) => save(data)}
-  onCancel={handleClose}
-  showActions
-  saveLabel="Save"
-/>
-```
-
-### Key props
-
-| Prop | Type | Default | Purpose |
-|---|---|---|---|
-| `schema` | `JsonSchema` | required | JSON Schema describing the form |
-| `data` | `Record<string, unknown>` | required | Current form values |
-| `onUpdate` | `(data, changedFields, diff) => void` | — | Called on save |
-| `onCancel` | `() => void` | — | Called on cancel |
-| `onChange` | `(data) => void` | — | Called on every field change (use instead of `onUpdate` when managing your own buttons) |
-| `showActions` | `boolean` | `false` | Render built-in Save / Cancel buttons inside the form |
-| `showCancel` | `boolean` | `true` | Show the Cancel button (requires `showActions`) |
-| `saveLabel` | `string` | `"Save"` | Save button label |
-| `cancelLabel` | `string` | `"Cancel"` | Cancel button label |
-| `showExtraProperties` | `boolean` | `false` | Preserve form keys not in the schema. Set `true` for open-ended data (e.g. graph node properties) |
-| `uiSchema` | `Record<string, UISchema>` | — | Per-field UI overrides |
-| `widgets` | `WidgetRegistry` | `DEFAULT_WIDGETS` | Custom widget map |
-| `deferStateUpdates` | `boolean` | `false` | Update state on blur instead of on change |
-
----
-
-## Schema construction
-
-The recommended pattern is Zod + `toJsonSchema()` with `.meta()` for UI hints:
-
-```ts
-import { z } from "zod";
-import { toJsonSchema } from "@petrarca/sonnet-core/schema";
-
-const UserSchema = z.object({
-  name: z.string().meta({
-    "x-ui-title": "Full name",
-    "x-ui-description": "As it appears on official documents.",
-  }),
-  role: z.enum(["admin", "user"]).meta({
-    "x-ui-title": "Role",
-    "x-ui-options": { enumNames: ["Administrator", "Standard user"] },
-  }),
-  bio: z.string().optional().meta({
-    "x-ui-title": "Bio",
-    "x-ui-widget": "textarea",
-  }),
-});
-
-// Convert once, store as a module-level constant:
-const USER_FORM_SCHEMA = toJsonSchema(UserSchema);
-```
-
-Or write the JSON Schema directly for dynamic / server-driven forms.
-
----
-
-## Schema UI annotations
-
-Annotate individual fields with `x-ui-*` to control rendering:
-
-| Annotation | Purpose |
-|---|---|
-| `"x-ui-title"` | Override the field label (`false` to hide) |
-| `"x-ui-description"` | Override the field description |
-| `"x-ui-widget"` | Force a specific widget: `"textarea"`, `"tags"`, `"entity-select"`, or a custom key |
-| `"x-ui-options"` | Widget-specific options (see widget docs) |
-| `"x-ui-order"` | Array of field names to control rendering order in an object |
-| `"x-ui-layout"` | Array layout config: `{ direction: "horizontal", columns, gap, compact }` |
-
----
-
-## onChange mode (external buttons)
-
-When you want to drive your own Submit button outside the form, omit `showActions`
-and use `onChange` instead of `onUpdate`:
-
-```tsx
-const [formData, setFormData] = useState({});
-
-<JsonSchemaFormRenderer
-  schema={schema}
-  data={formData}
-  onChange={setFormData}
-  // no showActions — caller owns the buttons
-/>
-
-<Button onClick={() => submit(formData)}>Submit</Button>
-```
-
----
-
-## UISchema
-
-Override rendering per-field without modifying the schema:
-
-```tsx
-<JsonSchemaFormRenderer
-  schema={schema}
-  data={data}
-  uiSchema={{
-    name:        { "x-ui-title": "Display name" },   // override label
-    internal_id: { "x-ui-title": false },             // hide label entirely
-    notes:       { "x-ui-widget": "textarea" },       // force widget
-  }}
-  onUpdate={onUpdate}
+  schema={WIDGET_SCHEMA}
+  data={widget}
   showActions
-/>
-```
-
----
-
-## Custom widgets
-
-Extend `DEFAULT_WIDGETS` with your own widget components:
-
-```ts
-import { DEFAULT_WIDGETS, type WidgetRegistry, type WidgetProps } from "@petrarca/sonnet-forms";
-
-function MyColorWidget({ value, onChange, schema }: WidgetProps) {
-  return (
-    <input
-      type="color"
-      value={String(value ?? "#000000")}
-      onChange={(e) => onChange(e.target.value)}
-    />
-  );
-}
-
-export const MY_WIDGETS: WidgetRegistry = {
-  ...DEFAULT_WIDGETS,
-  "color-picker": MyColorWidget,   // key matches "x-ui-widget": "color-picker" in schema
-};
-
-// Usage:
-<JsonSchemaFormRenderer schema={schema} data={data} widgets={MY_WIDGETS} onUpdate={onUpdate} showActions />
-```
-
-`WidgetProps` includes `formData` (the full current form state) — use this to
-build dependent widgets that react to sibling field values.
-
----
-
-## Dynamic schema (edit vs. create)
-
-To hide fields that are immutable after creation, delete them from a cloned
-schema. Also exclude them from `data` — if a key exists in `data` but not
-the schema, the form engine treats it as a dirty field immediately:
-
-```ts
-const schema = useMemo(() => {
-  if (!isEditing) return BASE_SCHEMA;
-  const s = structuredClone(BASE_SCHEMA);
-  delete s.properties?.app_key;   // read-only after creation
-  return s;
-}, [isEditing]);
-
-const data = isEditing
-  ? { name: entity.name }          // omit app_key from data too
-  : {};
+  saveLabel="Save changes"
+  onUpdate={(data, changedFields) => save(changedFields)}
+  onCancel={close}
+  showExtraProperties={false}
+/>;
 ```
 
----
-
-## Standalone field components
-
-Use field components directly outside the renderer — in sidebars, toolbars,
-or any custom form layout:
-
-```tsx
-import {
-  FormInput, FormTextarea, FormSelect,
-  FormCheckbox, FormMultiSelect, FormTagsInput,
-} from "@petrarca/sonnet-forms";
-
-<FormInput
-  label="Name"
-  description="Your full name"
-  value={name}
-  onChange={(e) => setName(e.currentTarget.value)}
-  error={nameError}
-/>
-
-<FormSelect
-  label="Role"
-  options={[{ value: "admin", label: "Admin" }, { value: "user", label: "User" }]}
-  value={role}
-  onChange={setRole}
-  clearable={false}
-/>
-
-<FormCheckbox
-  label="Active"
-  checked={active}
-  onChange={(checked) => setActive(checked === true)}
-/>
-
-<FormTextarea
-  label="Notes"
-  value={notes}
-  onChange={(e) => setNotes(e.currentTarget.value)}
-  autosize
-  minRows={3}
-  rightSection={<ClearButton />}
-  rightSectionWidth={40}
-/>
-```
-
-**Common props on all field components:**
-
-| Prop | Purpose |
-|---|---|
-| `label` | Field label. Pass `false` to suppress. |
-| `description` | Help text below the field |
-| `error` | Error message (also sets error styling) |
-| `compact` | Tighter vertical spacing |
-| `disabled` | Disables the field |
-| `wrapperClassName` | Class on the outer wrapper div |
-
----
+Hold the schema as a module-level constant; rebuilding it on every render
+re-resolves references and conditionals. `showExtraProperties` defaults to
+`true` and shows a card listing data keys absent from the schema -- most forms
+want it off. The twenty-four props, the three edit modes and what validation
+actually enforces are in [getting started](docs/usage/getting-started.md).
+
+## Documentation
+
+- [Usage guides](docs/usage/index.md) -- getting started, the
+  [`x-ui-*` vocabulary](docs/usage/ui-schema.md),
+  [layout](docs/usage/layout.md), [widgets](docs/usage/widgets.md),
+  [templates](docs/usage/templates.md),
+  [field components](docs/usage/field-components.md) and
+  [change tracking](docs/usage/change-tracking.md).
+- [Design docs](docs/design/index.md) -- form layout, nested fields and the
+  change-tracking model.
+- [Workspace documentation](../../docs/README.md) -- how the packages layer and
+  the shared schema extension contract.
 
 ## License
 
-See [LICENSE.md](../../LICENSE.md).
+Apache 2.0. See [LICENSE.md](../../LICENSE.md).

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { Input, Textarea, badgeVariants } from '@petrarca/sonnet-ui';
 import { JsonSchemaProperty, UILayoutConfig, JsonSchema, UISchema, UISchemaOptions, FormDiff, RefResolver, FieldError } from '@petrarca/sonnet-core/schema';
 export { UISchema, UISchemaOptions } from '@petrarca/sonnet-core/schema';
 import { VariantProps } from 'class-variance-authority';
+import { SaveWhenInvalid, ValidationDisplay } from '@petrarca/sonnet-core/config';
 
 interface FormFieldWrapperProps {
     /** Field id -- wired to the label's htmlFor */
@@ -663,6 +664,12 @@ interface FormActionsProps {
     disabled?: boolean;
     hasChanges: boolean;
     isValid: boolean;
+    /**
+     * Whether Save is available while invalid. `reveal` (default) keeps it
+     * enabled -- an invalid click reveals errors and does not submit; `disable`
+     * greys it out while invalid.
+     */
+    saveWhenInvalid?: SaveWhenInvalid;
     saveLabel?: string;
     cancelLabel?: string;
     showCancel?: boolean;
@@ -672,7 +679,7 @@ interface FormActionsProps {
      */
     leadingActions?: ReactNode;
 }
-declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveLabel, cancelLabel, showCancel, leadingActions, }: FormActionsProps): react_jsx_runtime.JSX.Element;
+declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveWhenInvalid, saveLabel, cancelLabel, showCancel, leadingActions, }: FormActionsProps): react_jsx_runtime.JSX.Element;
 
 type Props = {
     properties: Record<string, any>;
@@ -845,7 +852,7 @@ declare function EntitySelectWidget({ id, name, value, onChange, onBlur, label,
  * compact / label suppression propagates to all nested widgets.
  */
 
-declare function ObjectWidget({ propertySchema, value, onChange, registry, uiSchema, disabled, readonly, label, description, options, }: WidgetProps): React.ReactElement | null;
+declare function ObjectWidget({ id, propertySchema, value, onChange, onBlur, registry, uiSchema, disabled, readonly, label, description, options, }: WidgetProps): React.ReactElement | null;
 
 /**
  * ArrayWidget -- renders a repeatable list of sub-forms for
@@ -1091,6 +1098,17 @@ type JsonSchemaFormRendererProps = {
      * caller pre-loads referenced schemas into a map and passes a lookup.
      */
     refResolver?: RefResolver;
+    /**
+     * When to reveal field validation errors. Overrides the app-wide default set
+     * in SonnetConfigProvider globals. Defaults to `onSubmit`.
+     */
+    validationDisplay?: ValidationDisplay;
+    /**
+     * Whether Save is available while the form is invalid. Overrides the app-wide
+     * default set in SonnetConfigProvider globals. Defaults to `reveal` (Save
+     * stays enabled; an invalid click reveals errors and does not submit).
+     */
+    saveWhenInvalid?: SaveWhenInvalid;
     /** Label for Save button (default: "Save") */
     saveLabel?: string;
     /** Label for Cancel button (default: "Cancel") */
@@ -1177,8 +1195,10 @@ interface FormFieldRendererProps {
      * to keep ids unique.
      */
     idPrefix?: string;
+    /** Validation messages for this field, rendered inline by the widget. */
+    rawErrors?: string[];
 }
-declare function FormFieldRenderer({ fieldName, property, value, onChange, onBlur, required, disabled, readOnly, schema, uiSchema, registry, globalOptions, formData, idPrefix, }: FormFieldRendererProps): React__default.ReactElement | null;
+declare function FormFieldRenderer({ fieldName, property, value, onChange, onBlur, required, disabled, readOnly, schema, uiSchema, registry, globalOptions, formData, idPrefix, rawErrors, }: FormFieldRendererProps): React__default.ReactElement | null;
 
 /**
  * useFormEngine - Core form state, schema resolution, and update-mode logic
@@ -1248,6 +1268,10 @@ interface UseFormEngineResult {
      * Lets the renderer surface problems for fields that are not on screen.
      */
     fieldErrors: FieldError[];
+    /** Fields the user has touched (focused then blurred). */
+    touched: Record<string, boolean>;
+    /** Whether a save has been attempted (reveals all errors under any policy). */
+    submitAttempted: boolean;
     handleFieldChange: (fieldName: string, value: any) => void;
     handleFieldBlur: (fieldName: string) => void;
     handleSave: () => void;
@@ -1299,6 +1323,19 @@ type NestedRenderer = (props: Omit<JsonSchemaFormRendererProps, "onUpdate" | "on
 interface NestedFormContextValue {
     renderer: NestedRenderer;
     templates: TemplateRegistry;
+    /**
+     * The whole form's data, carried down so a nested renderer can evaluate an
+     * `x-ui-rule` scope against the form root rather than its own slice.
+     *
+     * Every other JSON Pointer in the vocabulary (`editablePaths`, validation
+     * error pointers) is root-anchored; without this, a rule on a nested field
+     * could only ever see its immediate object, so a rule referencing a
+     * top-level field silently never fired.
+     *
+     * The outermost renderer sets this to its own data; nested renderers inherit
+     * it unchanged.
+     */
+    rootData: Record<string, unknown>;
 }
 
 /**