@petrarca/sonnet-forms 0.2.0 → 0.4.0

package/README.md

@@ -1,14 +1,23 @@
 # @petrarca/sonnet-forms
 
-Schema-driven form renderer and field components for the Petrarca Sonnet component library.
+Schema-driven form renderer and field components for the Petrarca Sonnet
+component library.
 
 ## What's included
 
-**JsonSchemaFormRenderer** -- Renders a complete form from a JSON Schema definition with automatic widget resolution, validation, nested objects, and repeatable arrays.
+**JsonSchemaFormRenderer** — Renders a complete form from a JSON Schema with
+automatic widget resolution, validation, nested objects, arrays, and custom
+UI schema overrides.
 
-**Field components** -- Standalone form fields with label, description, error, and compact mode support: FormInput, FormTextarea, FormSelect, FormMultiSelect, FormCheckbox, FormTagsInput, FormQuantityInput.
+**Form field components** — Standalone fields with label, description, error,
+and compact mode: `FormInput`, `FormTextarea`, `FormSelect`, `FormMultiSelect`,
+`FormCheckbox`, `FormTagsInput`, `FormNumberInput`, `FormQuantityInput`.
 
-**Widget system** -- Extensible widget registry for mapping schema types to UI controls. Built-in widgets for text, number, select, checkbox, textarea, tags, quantity, arrays, objects, entity references, and JSON editing.
+**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.
+
+---
 
 ## Install
 
@@ -16,8 +25,252 @@ Schema-driven form renderer and field components for the Petrarca Sonnet compone
 pnpm add @petrarca/sonnet-forms @petrarca/sonnet-ui @petrarca/sonnet-core
 ```
 
-Peer dependencies: `react`, `react-dom`, `tailwindcss`.
+Peer dependencies: `react >=19`, `react-dom >=19`, `tailwindcss`.
+
+---
+
+## Basic usage
+
+### JsonSchemaFormRenderer
+
+```tsx
+import { JsonSchemaFormRenderer } from "@petrarca/sonnet-forms";
+
+const schema = {
+  type: "object",
+  properties: {
+    name:  { type: "string", title: "Name" },
+    email: { type: "string", format: "email", title: "Email" },
+    age:   { type: "integer", title: "Age" },
+  },
+  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}
+  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
+  : {};
+```
+
+---
+
+## 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 |
+
+---
 
 ## License
 
-Apache 2.0
+See [LICENSE.md](../../LICENSE.md).

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
-import React__default, { ComponentType } from 'react';
+import React__default, { ComponentType, ReactNode } from 'react';
 import { Input, Textarea, badgeVariants } from '@petrarca/sonnet-ui';
 import { JsonSchemaProperty, UILayoutConfig, JsonSchema, UISchema, UISchemaOptions, FormDiff } from '@petrarca/sonnet-core/schema';
 export { UISchema, UISchemaOptions } from '@petrarca/sonnet-core/schema';
@@ -591,14 +591,6 @@ interface FormQuantityInputProps {
  */
 declare const FormQuantityInput: React__default.ForwardRefExoticComponent<FormQuantityInputProps & React__default.RefAttributes<HTMLInputElement>>;
 
-/**
- * FormActions - Save / Cancel button row for buffered forms
- *
- * Rendered only when the parent JsonSchemaFormRenderer is in buffered mode
- * (showActions=true). Keeps button logic out of the orchestrator.
- *
- * @module components/Forms/FormActions
- */
 interface FormActionsProps {
     onSave: () => void;
     onCancel: () => void;
@@ -608,8 +600,13 @@ interface FormActionsProps {
     saveLabel?: string;
     cancelLabel?: string;
     showCancel?: boolean;
+    /**
+     * Optional content rendered left-aligned in the action row (e.g. a secondary
+     * action like "Test connection"). Cancel/Save stay grouped on the right.
+     */
+    leadingActions?: ReactNode;
 }
-declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveLabel, cancelLabel, showCancel, }: FormActionsProps): react_jsx_runtime.JSX.Element;
+declare function FormActions({ onSave, onCancel, disabled, hasChanges, isValid, saveLabel, cancelLabel, showCancel, leadingActions, }: FormActionsProps): react_jsx_runtime.JSX.Element;
 
 type Props = {
     properties: Record<string, any>;
@@ -944,6 +941,11 @@ type JsonSchemaFormRendererProps = {
     cancelLabel?: string;
     /** Show the Cancel button (default: true) */
     showCancel?: boolean;
+    /**
+     * Optional content rendered left-aligned in the Save/Cancel action row
+     * (only when showActions=true), e.g. a secondary action like "Test connection".
+     */
+    leadingActions?: React__default.ReactNode;
     /** Show extra properties card (default: true) */
     showExtraProperties?: boolean;
     /** Widget registry for custom widgets (default: DEFAULT_WIDGETS) */

package/dist/index.js

@@ -1417,11 +1417,15 @@ function FormActions({
   isValid,
   saveLabel = "Save",
   cancelLabel = "Cancel",
-  showCancel = true
+  showCancel = true,
+  leadingActions
 }) {
-  return /* @__PURE__ */ jsxs9(SimpleGroup, { justify: "flex-end", mt: "md", children: [
-    showCancel && /* @__PURE__ */ jsx10(Button3, { variant: "outline", onClick: onCancel, disabled, children: cancelLabel }),
-    /* @__PURE__ */ jsx10(Button3, { onClick: onSave, disabled: disabled || !hasChanges || !isValid, children: saveLabel })
+  return /* @__PURE__ */ jsxs9("div", { className: "flex items-center justify-between mt-4", children: [
+    /* @__PURE__ */ jsx10("div", { className: "flex items-center gap-2", children: leadingActions }),
+    /* @__PURE__ */ jsxs9(SimpleGroup, { justify: "flex-end", children: [
+      showCancel && /* @__PURE__ */ jsx10(Button3, { variant: "outline", onClick: onCancel, disabled, children: cancelLabel }),
+      /* @__PURE__ */ jsx10(Button3, { onClick: onSave, disabled: disabled || !hasChanges || !isValid, children: saveLabel })
+    ] })
   ] });
 }
 
@@ -3323,6 +3327,7 @@ function FormContainer({
   saveLabel,
   cancelLabel,
   showCancel,
+  leadingActions,
   children
 }) {
   if (displayContents) {
@@ -3341,7 +3346,8 @@ function FormContainer({
         isValid,
         saveLabel,
         cancelLabel,
-        showCancel
+        showCancel,
+        leadingActions
       }
     )
   ] });
@@ -3355,7 +3361,8 @@ function JsonSchemaFormRenderer(props) {
     onValidationChange,
     onUpdate,
     onCancel,
-    templates
+    templates,
+    leadingActions
   } = props;
   const {
     disabled,
@@ -3458,6 +3465,7 @@ function JsonSchemaFormRenderer(props) {
       saveLabel,
       cancelLabel,
       showCancel,
+      leadingActions,
       children: layoutFields
     }
   ) });