@petrarca/sonnet-playground 0.6.0 → 0.8.0

package/README.md

@@ -1,21 +1,30 @@
 # @petrarca/sonnet-playground
 
-Playground framework and built-in component demos for the Petrarca Sonnet
-component library.
+The living reference for the Petrarca Sonnet component library: a registry of
+demonstration pages and a factory that turns it into a `ShellModule`. It is a
+library, not a hosted site -- you mount it in your own application and get a
+working component reference inside your own build
+([ADR-0005](../../docs/adr/0005-the-playground-is-the-living-documentation.md)).
 
-## What's included
+## What it provides
 
-**Playground framework** — Registry, overview tile grid, and `createPlaygroundModule()`
-factory. Wire a playground into any `sonnet-shell` app with a few lines.
+**A registry.** `PlaygroundRegistry` and `createPlaygroundRegistry`, which
+returns one pre-populated with the built-in entries. Register your own pages
+beside them, grouped under a label you choose.
 
-**Built-in demos** — Pre-built showcase pages for all Sonnet components:
-Typography, Color Palette, Core UI, Advanced Components, JSON Editor, Forms,
-Form Components, Form Widgets, Data Components, Graph Visualization, Shell API.
+**A module factory.** `createPlaygroundModule` turns a registry into a
+`ShellModule` with an overview page, generated routes and navigation, ready to
+pass to `createModuleRegistry`.
 
-**PlaygroundSection** — Shared section wrapper (`default` and `card` variants)
-used by all playground pages.
+**Twelve built-in pages**, each lazily loaded: Typography and Color Palette
+under Design System; Core UI Components, Advanced Components and JSON Editor
+under Components; Form Components, Forms Renderer and Form Widgets under Forms;
+Schema Designer under Schemas; Data Components under Data; Graph Visualization
+under Graph; Shell API under Shell.
 
----
+**Page building blocks.** `PlaygroundSection` for consistent section chrome,
+`PlaygroundOverview` for the tile grid, and the playground settings provider,
+hook and panel.
 
 ## Install
 
@@ -23,120 +32,73 @@ used by all playground pages.
 pnpm add @petrarca/sonnet-playground
 ```
 
-Peer dependencies: `react`, `react-dom`, `@petrarca/sonnet-shell`,
-`@petrarca/sonnet-ui`, `@petrarca/sonnet-forms`, `@petrarca/sonnet-graph`.
+That single install pulls in all six other `@petrarca/sonnet-*` packages --
+`sonnet-core`, `sonnet-ui`, `sonnet-forms`, `sonnet-shell`, `sonnet-graph` and
+`sonnet-schema-designer` -- as regular dependencies, because the pages import
+from every one of them.
 
----
-
-## Basic usage
-
-```ts
-// src/modules/playground/index.ts
-import {
-  createPlaygroundRegistry,
-  createPlaygroundModule,
-} from "@petrarca/sonnet-playground";
-
-const registry = createPlaygroundRegistry();
-
-// Optionally add app-specific pages:
-registry.register({
-  id: "app.my-page",
-  title: "My Page",
-  description: "Custom demo page.",
-  icon: SomeIcon,
-  color: "teal",
-  path: "my-page",
-  component: React.lazy(() => import("./pages/MyPage")),
-  group: "App",
-  order: 0,
-});
-
-export default createPlaygroundModule(registry);
-```
-
-```ts
-// src/modules/registry.ts
-import { createModuleRegistry } from "@petrarca/sonnet-shell";
-import home from "./home";
-import playground from "./playground";
-
-export const registry = createModuleRegistry([
-  home,
-  playground, // pinBottom: true is set automatically by createPlaygroundModule
-]);
-```
-
-`createPlaygroundModule` returns a `ShellModule` — pass it directly to
-`createModuleRegistry` alongside your app's own modules.
-
----
+| Peer | Range | Needed for |
+|---|---|---|
+| `react`, `react-dom` | `>=19` | Everything |
+| `react-router-dom` | `>=7` | The generated routes and the layout outlet |
+| `tailwindcss` | `>=3` | Every page's styling |
 
-## Adding app-specific pages
+Those dependencies carry further peers of their own, and some that are only
+optional down there are required here -- the graph page needs every renderer
+peer, and the JSON editor page needs CodeMirror. Getting that wrong shows up as
+one page throwing rather than as an install error. See
+[getting started](docs/usage/getting-started.md).
 
-Register your own pages alongside the built-in demos by calling
-`registry.register()` before passing the registry to `createPlaygroundModule`.
-Pages appear in the overview tile grid grouped under your chosen `group` label.
+## Usage
 
 ```ts
 // src/modules/playground/index.ts
 import { lazy } from "react";
-import { Search } from "lucide-react";
+import { Boxes } from "lucide-react";
 import {
-  createPlaygroundRegistry,
   createPlaygroundModule,
+  createPlaygroundRegistry,
 } from "@petrarca/sonnet-playground";
 
 const registry = createPlaygroundRegistry();
 
-// Register app-specific pages
 registry.register({
-  id: "app.my-widget",
-  title: "My Widget",
-  description: "Interactive demo of MyWidget with live configuration.",
-  icon: Search,
+  id: "app.widgets",
+  title: "Widgets",
+  description: "Interactive demo of the Widget components.",
+  icon: Boxes,
   color: "teal",
-  path: "my-widget",
-  component: lazy(() => import("./pages/PlayMyWidget")),
-  group: "App Components",  // appears as a group heading in the overview
+  path: "widgets",
+  component: lazy(() => import("./pages/PlayWidgets")),
+  group: "App Components",
   order: 0,
 });
 
 export default createPlaygroundModule(registry);
 ```
 
-Pages are lazy-loaded automatically — wrap the component in `React.lazy()`
-as shown above. The framework handles the `Suspense` boundary.
+`createPlaygroundModule` returns a `ShellModule`, so it goes into
+`createModuleRegistry` alongside your own modules. Its options are `icon`,
+`label`, `basePath`, `overviewTitle`, `overviewSubtitle` and `grouped`; the
+defaults are `FlaskConical`, `"Playground"`, `"/playground"`,
+`"Developer Playground"`, `"Experiment with components, test features, and
+explore capabilities."` and `true`.
 
-`group` is optional. Pages without a group appear under the default group in
-the overview. Pages with the same `group` string are grouped together.
+Individual built-in pages are available from
+`@petrarca/sonnet-playground/pages` when you want one on a route of your own.
 
----
-
-## Pages subpath
-
-Individual built-in pages are available at `@petrarca/sonnet-playground/pages`
-for consumers who want to cherry-pick or re-export them:
-
-```tsx
-import { PlayTypography, PlayColorPalette } from "@petrarca/sonnet-playground/pages";
-```
-
----
-
-## createPlaygroundModule options
-
-| Option | Type | Default |
-|---|---|---|
-| `icon` | `LucideIcon` | `FlaskConical` |
-| `label` | `string` | `"Playground"` |
-| `basePath` | `string` | `"/playground"` |
-| `overviewTitle` | `string` | `"Developer Playground"` |
-| `overviewSubtitle` | `string` | `""` |
-| `grouped` | `boolean` | `true` |
+## Documentation
 
----
+- [Usage guides](docs/usage/index.md) -- getting started,
+  [adding pages](docs/usage/adding-pages.md) and
+  [embedding](docs/usage/embedding.md).
+- [Design docs](docs/design/index.md) -- the registry model and the page
+  contract.
+- [sonnet-shell: getting started](../sonnet-shell/docs/usage/getting-started.md)
+  -- the application frame this module plugs into.
+- [Workspace documentation](../../docs/README.md) -- how the packages layer and
+  the architecture decision records.
 
 ## License
 
-See [LICENSE.md](../../LICENSE.md).
+Apache 2.0. See [LICENSE.md](../../LICENSE.md).

package/dist/PlayAuth-SOEYPOOL.js

@@ -0,0 +1,8 @@
+import {
+  PlayAuth
+} from "./chunk-RYCRENYO.js";
+import "./chunk-C2EZ2ECG.js";
+export {
+  PlayAuth as default
+};
+//# sourceMappingURL=PlayAuth-SOEYPOOL.js.map

package/dist/PlayForms-U2TWUX5L.js

@@ -0,0 +1,7 @@
+import {
+  PlayForms
+} from "./chunk-BRH3FFFT.js";
+export {
+  PlayForms as default
+};
+//# sourceMappingURL=PlayForms-U2TWUX5L.js.map

package/dist/PlayGraph-M4KQSFI7.js

@@ -0,0 +1,7 @@
+import {
+  PlayGraph
+} from "./chunk-E5X7GVLU.js";
+export {
+  PlayGraph as default
+};
+//# sourceMappingURL=PlayGraph-M4KQSFI7.js.map

package/dist/PlaySchemaDesigner-S4DBB53G.js

@@ -0,0 +1,7 @@
+import {
+  PlaySchemaDesigner
+} from "./chunk-2XMWOZ5O.js";
+export {
+  PlaySchemaDesigner as default
+};
+//# sourceMappingURL=PlaySchemaDesigner-S4DBB53G.js.map

package/dist/PlaySchemaDesigner-S4DBB53G.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/{chunk-6VQJFBTM.js → chunk-2XMWOZ5O.js}

@@ -312,4 +312,4 @@ function PlaySchemaDesigner() {
 export {
   PlaySchemaDesigner
 };
-//# sourceMappingURL=chunk-6VQJFBTM.js.map
+//# sourceMappingURL=chunk-2XMWOZ5O.js.map

package/dist/chunk-2XMWOZ5O.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pages/PlaySchemaDesigner.tsx"],"sourcesContent":["import { useState } from \"react\";\nimport {\n  SchemaDesigner,\n  type SchemaDesignerCapabilities,\n} from \"@petrarca/sonnet-schema-designer\";\nimport { FormSelect } from \"@petrarca/sonnet-forms\";\nimport type { JsonSchema, UISchema } from \"@petrarca/sonnet-core/schema\";\n\nconst SAMPLE_SCHEMA: JsonSchema = {\n  title: \"Patient\",\n  type: \"object\",\n  properties: {\n    first_name: { type: \"string\", title: \"First name\", minLength: 1 },\n    last_name: { type: \"string\", title: \"Last name\", minLength: 1 },\n    date_of_birth: { type: \"string\", format: \"date\", title: \"Date of birth\" },\n    gender: {\n      type: \"string\",\n      title: \"Gender\",\n      enum: [\"male\", \"female\", \"other\", \"unknown\"],\n    },\n    active: { type: \"boolean\", title: \"Active\" },\n    contact: {\n      type: \"object\",\n      title: \"Contact\",\n      properties: {\n        email: { type: \"string\", format: \"email\", title: \"Email\" },\n        phone: { type: \"string\", title: \"Phone\" },\n      },\n      required: [\"email\"],\n    },\n    addresses: {\n      type: \"array\",\n      title: \"Addresses\",\n      minItems: 1,\n      maxItems: 3,\n      items: {\n        type: \"object\",\n        properties: {\n          street: { type: \"string\", title: \"Street\" },\n          city: { type: \"string\", title: \"City\" },\n          zip: { type: \"string\", title: \"ZIP\" },\n          country: { type: \"string\", title: \"Country\" },\n        },\n        required: [\"street\", \"city\"],\n      },\n    },\n  },\n  required: [\"first_name\", \"last_name\"],\n};\n\n// An audit-event-like schema: a fixed envelope (actor, targets) with three\n// extensible metadata containers. Used to demo scoped editing.\nconst AUDIT_SCHEMA: JsonSchema = {\n  title: \"AuditEvent\",\n  type: \"object\",\n  properties: {\n    actor: {\n      type: \"object\",\n      title: \"Actor\",\n      properties: {\n        type: { type: \"string\", title: \"Type\" },\n        id: { type: \"string\", title: \"ID\" },\n        metadata: {\n          type: \"object\",\n          title: \"Actor metadata\",\n          properties: { role: { type: \"string\", title: \"Role\" } },\n        },\n      },\n    },\n    targets: {\n      type: \"array\",\n      title: \"Targets\",\n      items: {\n        type: \"object\",\n        properties: {\n          type: { type: \"string\", title: \"Type\" },\n          id: { type: \"string\", title: \"ID\" },\n          metadata: {\n            type: \"object\",\n            title: \"Target metadata\",\n            properties: { ward: { type: \"string\", title: \"Ward\" } },\n          },\n        },\n      },\n    },\n    metadata: {\n      type: \"object\",\n      title: \"Metadata\",\n      properties: { reason: { type: \"string\", title: \"Reason\" } },\n    },\n  },\n};\n\n// A schema exercising every logic construct the designer can author: a oneOf\n// discriminated variant (payment method), if/then/else conditionals (authored\n// as allOf members), a const-tagged field, and a nullable anyOf optional field.\n// x-ui-order places each conditional field right after the property it depends\n// on (see docs/design/logic-authoring.md in the schema-designer package,\n// ordering note).\nconst LOGIC_SCHEMA: JsonSchema = {\n  title: \"Checkout\",\n  type: \"object\",\n  // A reusable definition referenced by $ref (shows read-only expansion).\n  $defs: {\n    Address: {\n      type: \"object\",\n      properties: {\n        street: { type: \"string\", title: \"Street\" },\n        city: { type: \"string\", title: \"City\" },\n        zip: { type: \"string\", title: \"ZIP\" },\n      },\n    },\n  },\n  \"x-ui-order\": [\n    \"schema_version\",\n    \"amount\",\n    \"requires_approval\",\n    \"currency\",\n    \"expedited\",\n    \"delivery_window\",\n    \"gift_wrap\",\n    \"gift_message\",\n    \"shipping_address\",\n    \"note\",\n    \"payment\",\n  ],\n  properties: {\n    // A $ref to the shared Address definition (read-only in the tree).\n    shipping_address: { $ref: \"#/$defs/Address\", title: \"Shipping address\" },\n    // A fixed value carried by every document (const authoring).\n    schema_version: {\n      type: \"string\",\n      title: \"Schema version\",\n      const: \"checkout/v1\",\n    },\n    amount: { type: \"number\", title: \"Amount\", minimum: 0 },\n    currency: {\n      type: \"string\",\n      title: \"Currency\",\n      enum: [\"EUR\", \"USD\", \"GBP\"],\n    },\n    expedited: { type: \"boolean\", title: \"Expedited\" },\n    gift_wrap: { type: \"boolean\", title: \"Gift wrap\" },\n    // Declarative visibility rule (x-ui-rule): declared at its own position,\n    // shown only when gift_wrap is checked. Contrast with the if/then/else\n    // fields above, which are structurally added by their conditionals.\n    gift_message: {\n      type: \"string\",\n      title: \"Gift message\",\n      \"x-ui-rule\": {\n        effect: \"show\",\n        condition: { scope: \"/gift_wrap\", schema: { const: true } },\n      },\n    },\n    // Nullable optional (anyOf [T, null]) -- the renderer unwraps to T.\n    note: {\n      title: \"Note (optional)\",\n      anyOf: [{ type: \"string\" }, { type: \"null\" }],\n    },\n    // A discriminated union (oneOf): the payment method.\n    payment: {\n      type: \"object\",\n      title: \"Payment method\",\n      discriminator: { propertyName: \"kind\" },\n      oneOf: [\n        {\n          title: \"Card\",\n          properties: {\n            kind: { const: \"card\" },\n            card_number: { type: \"string\", title: \"Card number\" },\n            cvc: { type: \"string\", title: \"CVC\" },\n          },\n        },\n        {\n          title: \"Bank transfer\",\n          properties: {\n            kind: { const: \"bank\" },\n            iban: { type: \"string\", title: \"IBAN\" },\n          },\n        },\n        {\n          title: \"Cash\",\n          properties: { kind: { const: \"cash\" } },\n        },\n      ],\n    },\n  },\n  required: [\"amount\", \"currency\"],\n  // Conditionals (if/then/else) authored as allOf members.\n  allOf: [\n    {\n      // Large amounts require an approval reference.\n      if: {\n        properties: { amount: { exclusiveMinimum: 1000 } },\n        required: [\"amount\"],\n      },\n      then: {\n        properties: {\n          requires_approval: {\n            type: \"string\",\n            title: \"Approval reference\",\n          },\n        },\n        required: [\"requires_approval\"],\n      },\n    },\n    {\n      // Expedited orders ask for a delivery window; otherwise none.\n      if: {\n        properties: { expedited: { const: true } },\n        required: [\"expedited\"],\n      },\n      then: {\n        properties: {\n          delivery_window: {\n            type: \"string\",\n            title: \"Delivery window\",\n            enum: [\"morning\", \"afternoon\", \"evening\"],\n          },\n        },\n      },\n    },\n  ],\n};\n\nconst AUDIT_EDITABLE_PATHS = [\n  \"/properties/metadata/properties\",\n  \"/properties/actor/properties/metadata/properties\",\n  \"/properties/targets/items/properties/metadata/properties\",\n];\n\ntype ProfileKey = \"full\" | \"data\" | \"scoped\" | \"structure\" | \"logic\";\n\ninterface Profile {\n  label: string;\n  description: string;\n  schema: JsonSchema;\n  capabilities?: SchemaDesignerCapabilities;\n  readOnly?: boolean;\n}\n\nconst PROFILES: Record<ProfileKey, Profile> = {\n  full: {\n    label: \"Full (schema + uiSchema)\",\n    description: \"Default: author the schema and its form presentation hints.\",\n    schema: SAMPLE_SCHEMA,\n    capabilities: { previews: [\"form\", \"table\", \"json\", \"capabilities\"] },\n  },\n  data: {\n    label: \"Data schema only\",\n    description:\n      \"Pure JSON Schema (audit, terminology): no UI/Combined tabs, JSON preview only.\",\n    schema: SAMPLE_SCHEMA,\n    capabilities: { mode: \"data\", previews: [\"json\", \"capabilities\"] },\n  },\n  scoped: {\n    label: \"Scoped (audit event)\",\n    description:\n      \"Fixed envelope; only the three metadata containers are editable.\",\n    schema: AUDIT_SCHEMA,\n    capabilities: {\n      mode: \"data\",\n      editablePaths: AUDIT_EDITABLE_PATHS,\n      previews: [\"json\", \"capabilities\"],\n    },\n  },\n  structure: {\n    label: \"Structure only (no preview)\",\n    description: \"Tree + inspector only; the center preview pane is hidden.\",\n    schema: SAMPLE_SCHEMA,\n    capabilities: { mode: \"data\", previews: [] },\n  },\n  logic: {\n    label: \"Logic (variants + conditionals)\",\n    description:\n      \"Shows every logic construct: a oneOf variant, if/then/else conditionals, a const field, and a nullable optional.\",\n    schema: LOGIC_SCHEMA,\n    capabilities: { previews: [\"form\", \"table\", \"json\", \"capabilities\"] },\n  },\n};\n\n/**\n * PlaySchemaDesigner -- exercises SchemaDesigner: visually author a JsonSchema\n * (and its uiSchema presentation hints), with a live preview. The profile\n * switcher presets the capability profile (data/full triage, scoped editing,\n * read-only); the in-designer Capabilities tab tweaks it live.\n */\nexport default function PlaySchemaDesigner() {\n  const [profileKey, setProfileKey] = useState<ProfileKey>(\"full\");\n  const profile = PROFILES[profileKey];\n\n  const [schema, setSchema] = useState<JsonSchema>(profile.schema);\n  const [uiSchema, setUiSchema] = useState<Record<string, UISchema>>({});\n\n  const selectProfile = (key: ProfileKey) => {\n    setProfileKey(key);\n    setSchema(PROFILES[key].schema);\n    setUiSchema({});\n  };\n\n  return (\n    <div className=\"w-full flex flex-col gap-3 h-[calc(100vh-8rem)]\">\n      <div>\n        <h1>Schema Designer</h1>\n        <p className=\"text-sm text-muted-foreground mb-3\">\n          Visually author a JSON Schema and its UI presentation hints. Edits\n          flow through onChange as a valid schema + uiSchema.\n        </p>\n      </div>\n\n      <div className=\"flex items-center gap-3\">\n        <label\n          htmlFor=\"capability-profile\"\n          className=\"shrink-0 text-sm font-medium\"\n        >\n          Capability profile\n        </label>\n        <div className=\"w-72\">\n          <FormSelect\n            id=\"capability-profile\"\n            name=\"profile\"\n            value={profileKey}\n            options={(Object.keys(PROFILES) as ProfileKey[]).map((k) => ({\n              value: k,\n              label: PROFILES[k].label,\n            }))}\n            onChange={(v) => selectProfile((v as ProfileKey) ?? \"full\")}\n            clearable={false}\n          />\n        </div>\n        <p className=\"text-sm text-muted-foreground\">{profile.description}</p>\n      </div>\n\n      <div style={{ flex: 1, minHeight: 0 }}>\n        <SchemaDesigner\n          key={profileKey}\n          schema={schema}\n          uiSchema={uiSchema}\n          capabilities={profile.capabilities}\n          readOnly={profile.readOnly}\n          onChange={(nextSchema, nextUiSchema) => {\n            setSchema(nextSchema);\n            setUiSchema(nextUiSchema);\n          }}\n        />\n      </div>\n    </div>\n  );\n}\n"],"mappings":";AAAA,SAAS,gBAAgB;AACzB;AAAA,EACE;AAAA,OAEK;AACP,SAAS,kBAAkB;AAySrB,SACE,KADF;AAtSN,IAAM,gBAA4B;AAAA,EAChC,OAAO;AAAA,EACP,MAAM;AAAA,EACN,YAAY;AAAA,IACV,YAAY,EAAE,MAAM,UAAU,OAAO,cAAc,WAAW,EAAE;AAAA,IAChE,WAAW,EAAE,MAAM,UAAU,OAAO,aAAa,WAAW,EAAE;AAAA,IAC9D,eAAe,EAAE,MAAM,UAAU,QAAQ,QAAQ,OAAO,gBAAgB;AAAA,IACxE,QAAQ;AAAA,MACN,MAAM;AAAA,MACN,OAAO;AAAA,MACP,MAAM,CAAC,QAAQ,UAAU,SAAS,SAAS;AAAA,IAC7C;AAAA,IACA,QAAQ,EAAE,MAAM,WAAW,OAAO,SAAS;AAAA,IAC3C,SAAS;AAAA,MACP,MAAM;AAAA,MACN,OAAO;AAAA,MACP,YAAY;AAAA,QACV,OAAO,EAAE,MAAM,UAAU,QAAQ,SAAS,OAAO,QAAQ;AAAA,QACzD,OAAO,EAAE,MAAM,UAAU,OAAO,QAAQ;AAAA,MAC1C;AAAA,MACA,UAAU,CAAC,OAAO;AAAA,IACpB;AAAA,IACA,WAAW;AAAA,MACT,MAAM;AAAA,MACN,OAAO;AAAA,MACP,UAAU;AAAA,MACV,UAAU;AAAA,MACV,OAAO;AAAA,QACL,MAAM;AAAA,QACN,YAAY;AAAA,UACV,QAAQ,EAAE,MAAM,UAAU,OAAO,SAAS;AAAA,UAC1C,MAAM,EAAE,MAAM,UAAU,OAAO,OAAO;AAAA,UACtC,KAAK,EAAE,MAAM,UAAU,OAAO,MAAM;AAAA,UACpC,SAAS,EAAE,MAAM,UAAU,OAAO,UAAU;AAAA,QAC9C;AAAA,QACA,UAAU,CAAC,UAAU,MAAM;AAAA,MAC7B;AAAA,IACF;AAAA,EACF;AAAA,EACA,UAAU,CAAC,cAAc,WAAW;AACtC;AAIA,IAAM,eAA2B;AAAA,EAC/B,OAAO;AAAA,EACP,MAAM;AAAA,EACN,YAAY;AAAA,IACV,OAAO;AAAA,MACL,MAAM;AAAA,MACN,OAAO;AAAA,MACP,YAAY;AAAA,QACV,MAAM,EAAE,MAAM,UAAU,OAAO,OAAO;AAAA,QACtC,IAAI,EAAE,MAAM,UAAU,OAAO,KAAK;AAAA,QAClC,UAAU;AAAA,UACR,MAAM;AAAA,UACN,OAAO;AAAA,UACP,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,OAAO,OAAO,EAAE;AAAA,QACxD;AAAA,MACF;AAAA,IACF;AAAA,IACA,SAAS;AAAA,MACP,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO;AAAA,QACL,MAAM;AAAA,QACN,YAAY;AAAA,UACV,MAAM,EAAE,MAAM,UAAU,OAAO,OAAO;AAAA,UACtC,IAAI,EAAE,MAAM,UAAU,OAAO,KAAK;AAAA,UAClC,UAAU;AAAA,YACR,MAAM;AAAA,YACN,OAAO;AAAA,YACP,YAAY,EAAE,MAAM,EAAE,MAAM,UAAU,OAAO,OAAO,EAAE;AAAA,UACxD;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,IACA,UAAU;AAAA,MACR,MAAM;AAAA,MACN,OAAO;AAAA,MACP,YAAY,EAAE,QAAQ,EAAE,MAAM,UAAU,OAAO,SAAS,EAAE;AAAA,IAC5D;AAAA,EACF;AACF;AAQA,IAAM,eAA2B;AAAA,EAC/B,OAAO;AAAA,EACP,MAAM;AAAA;AAAA,EAEN,OAAO;AAAA,IACL,SAAS;AAAA,MACP,MAAM;AAAA,MACN,YAAY;AAAA,QACV,QAAQ,EAAE,MAAM,UAAU,OAAO,SAAS;AAAA,QAC1C,MAAM,EAAE,MAAM,UAAU,OAAO,OAAO;AAAA,QACtC,KAAK,EAAE,MAAM,UAAU,OAAO,MAAM;AAAA,MACtC;AAAA,IACF;AAAA,EACF;AAAA,EACA,cAAc;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,YAAY;AAAA;AAAA,IAEV,kBAAkB,EAAE,MAAM,mBAAmB,OAAO,mBAAmB;AAAA;AAAA,IAEvE,gBAAgB;AAAA,MACd,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO;AAAA,IACT;AAAA,IACA,QAAQ,EAAE,MAAM,UAAU,OAAO,UAAU,SAAS,EAAE;AAAA,IACtD,UAAU;AAAA,MACR,MAAM;AAAA,MACN,OAAO;AAAA,MACP,MAAM,CAAC,OAAO,OAAO,KAAK;AAAA,IAC5B;AAAA,IACA,WAAW,EAAE,MAAM,WAAW,OAAO,YAAY;AAAA,IACjD,WAAW,EAAE,MAAM,WAAW,OAAO,YAAY;AAAA;AAAA;AAAA;AAAA,IAIjD,cAAc;AAAA,MACZ,MAAM;AAAA,MACN,OAAO;AAAA,MACP,aAAa;AAAA,QACX,QAAQ;AAAA,QACR,WAAW,EAAE,OAAO,cAAc,QAAQ,EAAE,OAAO,KAAK,EAAE;AAAA,MAC5D;AAAA,IACF;AAAA;AAAA,IAEA,MAAM;AAAA,MACJ,OAAO;AAAA,MACP,OAAO,CAAC,EAAE,MAAM,SAAS,GAAG,EAAE,MAAM,OAAO,CAAC;AAAA,IAC9C;AAAA;AAAA,IAEA,SAAS;AAAA,MACP,MAAM;AAAA,MACN,OAAO;AAAA,MACP,eAAe,EAAE,cAAc,OAAO;AAAA,MACtC,OAAO;AAAA,QACL;AAAA,UACE,OAAO;AAAA,UACP,YAAY;AAAA,YACV,MAAM,EAAE,OAAO,OAAO;AAAA,YACtB,aAAa,EAAE,MAAM,UAAU,OAAO,cAAc;AAAA,YACpD,KAAK,EAAE,MAAM,UAAU,OAAO,MAAM;AAAA,UACtC;AAAA,QACF;AAAA,QACA;AAAA,UACE,OAAO;AAAA,UACP,YAAY;AAAA,YACV,MAAM,EAAE,OAAO,OAAO;AAAA,YACtB,MAAM,EAAE,MAAM,UAAU,OAAO,OAAO;AAAA,UACxC;AAAA,QACF;AAAA,QACA;AAAA,UACE,OAAO;AAAA,UACP,YAAY,EAAE,MAAM,EAAE,OAAO,OAAO,EAAE;AAAA,QACxC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EACA,UAAU,CAAC,UAAU,UAAU;AAAA;AAAA,EAE/B,OAAO;AAAA,IACL;AAAA;AAAA,MAEE,IAAI;AAAA,QACF,YAAY,EAAE,QAAQ,EAAE,kBAAkB,IAAK,EAAE;AAAA,QACjD,UAAU,CAAC,QAAQ;AAAA,MACrB;AAAA,MACA,MAAM;AAAA,QACJ,YAAY;AAAA,UACV,mBAAmB;AAAA,YACjB,MAAM;AAAA,YACN,OAAO;AAAA,UACT;AAAA,QACF;AAAA,QACA,UAAU,CAAC,mBAAmB;AAAA,MAChC;AAAA,IACF;AAAA,IACA;AAAA;AAAA,MAEE,IAAI;AAAA,QACF,YAAY,EAAE,WAAW,EAAE,OAAO,KAAK,EAAE;AAAA,QACzC,UAAU,CAAC,WAAW;AAAA,MACxB;AAAA,MACA,MAAM;AAAA,QACJ,YAAY;AAAA,UACV,iBAAiB;AAAA,YACf,MAAM;AAAA,YACN,OAAO;AAAA,YACP,MAAM,CAAC,WAAW,aAAa,SAAS;AAAA,UAC1C;AAAA,QACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAEA,IAAM,uBAAuB;AAAA,EAC3B;AAAA,EACA;AAAA,EACA;AACF;AAYA,IAAM,WAAwC;AAAA,EAC5C,MAAM;AAAA,IACJ,OAAO;AAAA,IACP,aAAa;AAAA,IACb,QAAQ;AAAA,IACR,cAAc,EAAE,UAAU,CAAC,QAAQ,SAAS,QAAQ,cAAc,EAAE;AAAA,EACtE;AAAA,EACA,MAAM;AAAA,IACJ,OAAO;AAAA,IACP,aACE;AAAA,IACF,QAAQ;AAAA,IACR,cAAc,EAAE,MAAM,QAAQ,UAAU,CAAC,QAAQ,cAAc,EAAE;AAAA,EACnE;AAAA,EACA,QAAQ;AAAA,IACN,OAAO;AAAA,IACP,aACE;AAAA,IACF,QAAQ;AAAA,IACR,cAAc;AAAA,MACZ,MAAM;AAAA,MACN,eAAe;AAAA,MACf,UAAU,CAAC,QAAQ,cAAc;AAAA,IACnC;AAAA,EACF;AAAA,EACA,WAAW;AAAA,IACT,OAAO;AAAA,IACP,aAAa;AAAA,IACb,QAAQ;AAAA,IACR,cAAc,EAAE,MAAM,QAAQ,UAAU,CAAC,EAAE;AAAA,EAC7C;AAAA,EACA,OAAO;AAAA,IACL,OAAO;AAAA,IACP,aACE;AAAA,IACF,QAAQ;AAAA,IACR,cAAc,EAAE,UAAU,CAAC,QAAQ,SAAS,QAAQ,cAAc,EAAE;AAAA,EACtE;AACF;AAQe,SAAR,qBAAsC;AAC3C,QAAM,CAAC,YAAY,aAAa,IAAI,SAAqB,MAAM;AAC/D,QAAM,UAAU,SAAS,UAAU;AAEnC,QAAM,CAAC,QAAQ,SAAS,IAAI,SAAqB,QAAQ,MAAM;AAC/D,QAAM,CAAC,UAAU,WAAW,IAAI,SAAmC,CAAC,CAAC;AAErE,QAAM,gBAAgB,CAAC,QAAoB;AACzC,kBAAc,GAAG;AACjB,cAAU,SAAS,GAAG,EAAE,MAAM;AAC9B,gBAAY,CAAC,CAAC;AAAA,EAChB;AAEA,SACE,qBAAC,SAAI,WAAU,mDACb;AAAA,yBAAC,SACC;AAAA,0BAAC,QAAG,6BAAe;AAAA,MACnB,oBAAC,OAAE,WAAU,sCAAqC,oIAGlD;AAAA,OACF;AAAA,IAEA,qBAAC,SAAI,WAAU,2BACb;AAAA;AAAA,QAAC;AAAA;AAAA,UACC,SAAQ;AAAA,UACR,WAAU;AAAA,UACX;AAAA;AAAA,MAED;AAAA,MACA,oBAAC,SAAI,WAAU,QACb;AAAA,QAAC;AAAA;AAAA,UACC,IAAG;AAAA,UACH,MAAK;AAAA,UACL,OAAO;AAAA,UACP,SAAU,OAAO,KAAK,QAAQ,EAAmB,IAAI,CAAC,OAAO;AAAA,YAC3D,OAAO;AAAA,YACP,OAAO,SAAS,CAAC,EAAE;AAAA,UACrB,EAAE;AAAA,UACF,UAAU,CAAC,MAAM,cAAe,KAAoB,MAAM;AAAA,UAC1D,WAAW;AAAA;AAAA,MACb,GACF;AAAA,MACA,oBAAC,OAAE,WAAU,iCAAiC,kBAAQ,aAAY;AAAA,OACpE;AAAA,IAEA,oBAAC,SAAI,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,GAClC;AAAA,MAAC;AAAA;AAAA,QAEC;AAAA,QACA;AAAA,QACA,cAAc,QAAQ;AAAA,QACtB,UAAU,QAAQ;AAAA,QAClB,UAAU,CAAC,YAAY,iBAAiB;AACtC,oBAAU,UAAU;AACpB,sBAAY,YAAY;AAAA,QAC1B;AAAA;AAAA,MARK;AAAA,IASP,GACF;AAAA,KACF;AAEJ;","names":[]}

package/dist/{chunk-ZSUCFEB6.js → chunk-BRH3FFFT.js}

@@ -21,7 +21,8 @@ import { JsonEditor } from "@petrarca/sonnet-ui/json-editor";
 import {
   ArrowRight,
   ChevronLeft,
-  ChevronRight as ChevronRightIcon
+  ChevronRight as ChevronRightIcon,
+  ChevronDown
 } from "lucide-react";
 import { jsx, jsxs } from "react/jsx-runtime";
 var SAMPLE_SCHEMA = {
@@ -50,6 +51,64 @@ var SAMPLE_SCHEMA = {
   },
   required: ["name", "npi"]
 };
+var VALIDATION_SCHEMA = {
+  title: "Validation showcase",
+  type: "object",
+  // Cross-field / form validator (registered by the app): confirmEmail == email.
+  "x-ui-validate": ["emailsMatch"],
+  properties: {
+    email: {
+      type: "string",
+      title: "Email",
+      format: "email",
+      description: "Built-in: format: email"
+    },
+    confirmEmail: {
+      type: "string",
+      title: "Confirm email",
+      format: "email",
+      description: "Cross-field: must match Email (x-ui-validate on the object)"
+    },
+    website: {
+      type: "string",
+      title: "Website",
+      format: "uri",
+      description: "Built-in: format: uri"
+    },
+    zip: {
+      type: "string",
+      title: "ZIP code",
+      pattern: "^[0-9]{5}$",
+      description: "Built-in: pattern (five digits)"
+    },
+    age: {
+      type: "integer",
+      title: "Age",
+      minimum: 18,
+      maximum: 120,
+      description: "Built-in: minimum / maximum"
+    },
+    plan: {
+      type: "string",
+      title: "Plan",
+      enum: ["free", "pro", "enterprise"],
+      description: "Built-in: enum"
+    },
+    slug: {
+      type: "string",
+      title: "Slug",
+      "x-ui-validate": "slug",
+      description: "Custom: x-ui-validate: 'slug' (registered by the app)"
+    },
+    handle: {
+      type: "string",
+      title: "Handle",
+      "x-ui-validate": "uniqueHandle",
+      description: "Async: remote uniqueness check -- try 'taken'"
+    }
+  },
+  required: ["email"]
+};
 var NESTED_OBJECT_SCHEMA = {
   title: "Patient",
   type: "object",
@@ -402,6 +461,7 @@ var SECTIONS_LAYOUT_UISCHEMA = {
 };
 var sampleSchemas = {
   flat: SAMPLE_SCHEMA,
+  validation: VALIDATION_SCHEMA,
   nested_object: NESTED_OBJECT_SCHEMA,
   one_of: ONEOF_SCHEMA,
   array_of_objects: ARRAY_OF_OBJECTS_SCHEMA,
@@ -495,9 +555,16 @@ function usePlayFormsState() {
   const [dataError, setDataError] = useState("");
   const [activeTab, setActiveTab] = useState("schema");
   const [deferStateUpdates, setDeferStateUpdates] = useState(false);
+  const [validationDisplay, setValidationDisplay] = useState("onSubmit");
   const [dataCollapsed, setDataCollapsed] = useState(false);
+  const [errorsCollapsed, setErrorsCollapsed] = useState(false);
+  const [injectServerError, setInjectServerError] = useState(false);
   const [lastDiff, setLastDiff] = useState(null);
   const toggleDataPanel = useCallback(() => setDataCollapsed((v) => !v), []);
+  const toggleErrorsPanel = useCallback(
+    () => setErrorsCollapsed((v) => !v),
+    []
+  );
   const loadSchemaPreset = useCallback((value) => {
     if (!value || !sampleSchemas[value]) return;
     const text = JSON.stringify(sampleSchemas[value], null, 2);
@@ -533,7 +600,10 @@ function usePlayFormsState() {
     dataError,
     activeTab,
     deferStateUpdates,
+    validationDisplay,
     dataCollapsed,
+    errorsCollapsed,
+    injectServerError,
     lastDiff,
     setSchemaText,
     setUiSchemaText,
@@ -548,7 +618,10 @@ function usePlayFormsState() {
     setDataError,
     setActiveTab,
     setDeferStateUpdates,
+    setValidationDisplay,
     toggleDataPanel,
+    toggleErrorsPanel,
+    setInjectServerError,
     setLastDiff,
     loadSchemaPreset,
     loadUiSchemaPreset
@@ -725,8 +798,37 @@ function SchemaEditorColumn({
     }
   );
 }
+var DEMO_SERVER_ERRORS = [
+  { pointer: "/name", message: "Server: this name is already taken" },
+  { pointer: "", message: "Server: could not save (example form-level error)" }
+];
+var DEMO_VALIDATORS = {
+  field: {
+    slug: (value) => /^[a-z0-9-]+$/.test(String(value ?? "")) ? null : "Lowercase letters, digits and hyphens only"
+  },
+  form: {
+    // Cross-field: confirmEmail must equal email. Error attaches to the
+    // confirmEmail field by pointer.
+    emailsMatch: (data) => data.email && data.confirmEmail && data.email !== data.confirmEmail ? [{ pointer: "/confirmEmail", message: "Emails do not match" }] : []
+  },
+  // Declared in the `asyncField` namespace so the engine knows it is async and
+  // fires it only on value change. Demo: a simulated remote uniqueness check
+  // (200ms) where "taken" is unavailable.
+  asyncField: {
+    uniqueHandle: async (value) => {
+      await new Promise((r) => setTimeout(r, 200));
+      return String(value ?? "") === "taken" ? "Handle is already taken (async check)" : null;
+    }
+  }
+};
+var VALIDATION_DISPLAY_OPTIONS = [
+  { value: "onSubmit", label: "Errors: on submit" },
+  { value: "onTouched", label: "Errors: on blur" },
+  { value: "always", label: "Errors: always" }
+];
 var SCHEMA_PRESET_OPTIONS = [
   { value: "flat", label: "Practitioner (flat fields)" },
+  { value: "validation", label: "Validation showcase (built-in + custom)" },
   { value: "nested_object", label: "Patient (nested object)" },
   { value: "one_of", label: "Payment (oneOf variant)" },
   { value: "array_of_objects", label: "Medication Request (array)" },
@@ -791,9 +893,9 @@ function FormColumn({
               flexDirection: "column"
             },
             children: [
-              /* @__PURE__ */ jsxs("div", { children: [
-                /* @__PURE__ */ jsx("p", { className: "text-sm font-semibold mb-1", children: "Rendered Form" }),
-                /* @__PURE__ */ jsxs(SimpleGroup, { gap: "xs", align: "center", className: "mb-1", children: [
+              /* @__PURE__ */ jsxs("div", { className: "space-y-2", children: [
+                /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+                  /* @__PURE__ */ jsx("p", { className: "text-sm font-semibold", children: "Rendered Form" }),
                   /* @__PURE__ */ jsx(
                     Badge,
                     {
@@ -801,21 +903,53 @@ function FormColumn({
                       className: "text-xs",
                       children: state.isValid ? "Valid" : "Invalid"
                     }
-                  ),
-                  /* @__PURE__ */ jsx(
-                    FormCheckbox,
-                    {
-                      label: "Defer state updates (change on blur)",
-                      checked: state.deferStateUpdates,
-                      onChange: (checked) => {
-                        if (checked !== "indeterminate") {
-                          state.setDeferStateUpdates(checked);
-                        }
-                      }
-                    }
                   )
                 ] }),
-                state.validationErrors.length > 0 && /* @__PURE__ */ jsx("div", { style: { marginTop: "4px" }, children: state.validationErrors.map((err, idx) => /* @__PURE__ */ jsx("p", { className: "text-xs text-destructive", children: err }, idx)) })
+                /* @__PURE__ */ jsxs("div", { className: "rounded-md border border-border p-2", children: [
+                  /* @__PURE__ */ jsx("p", { className: "text-[11px] font-medium text-muted-foreground mb-1.5", children: "Options" }),
+                  /* @__PURE__ */ jsxs(SimpleGroup, { gap: "md", align: "center", wrap: "wrap", children: [
+                    /* @__PURE__ */ jsx(
+                      FormSelect,
+                      {
+                        label: false,
+                        "aria-label": "Validation display timing",
+                        options: VALIDATION_DISPLAY_OPTIONS,
+                        value: state.validationDisplay,
+                        onChange: (value) => {
+                          if (value) {
+                            state.setValidationDisplay(value);
+                          }
+                        },
+                        className: "text-xs",
+                        wrapperClassName: "w-44"
+                      }
+                    ),
+                    /* @__PURE__ */ jsx(
+                      FormCheckbox,
+                      {
+                        label: "Change on blur",
+                        checked: state.deferStateUpdates,
+                        onChange: (checked) => {
+                          if (checked !== "indeterminate") {
+                            state.setDeferStateUpdates(checked);
+                          }
+                        }
+                      }
+                    ),
+                    /* @__PURE__ */ jsx(
+                      FormCheckbox,
+                      {
+                        label: "Inject server error",
+                        checked: state.injectServerError,
+                        onChange: (checked) => {
+                          if (checked !== "indeterminate") {
+                            state.setInjectServerError(checked);
+                          }
+                        }
+                      }
+                    )
+                  ] })
+                ] })
               ] }),
               /* @__PURE__ */ jsxs(
                 "div",
@@ -836,7 +970,11 @@ function FormColumn({
                         onCancel: handleCancel,
                         onValidationChange: handleValidationChange,
                         showActions: true,
+                        allowPristineSave: true,
                         deferStateUpdates: state.deferStateUpdates,
+                        validationDisplay: state.validationDisplay,
+                        validators: DEMO_VALIDATORS,
+                        extraErrors: state.injectServerError ? DEMO_SERVER_ERRORS : void 0,
                         saveLabel: "Save Changes",
                         cancelLabel: "Reset",
                         showExtraProperties: true,
@@ -862,6 +1000,31 @@ function FormColumn({
     }
   );
 }
+function ErrorsCard({
+  state
+}) {
+  if (state.validationErrors.length === 0) return null;
+  return /* @__PURE__ */ jsxs(Card, { className: "border shadow-sm shrink-0 flex flex-col overflow-hidden", children: [
+    /* @__PURE__ */ jsxs(
+      "button",
+      {
+        type: "button",
+        onClick: state.toggleErrorsPanel,
+        className: "flex items-center gap-2 px-4 py-3 text-left rounded focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        children: [
+          state.errorsCollapsed ? /* @__PURE__ */ jsx(ChevronRightIcon, { className: "h-4 w-4 text-muted-foreground" }) : /* @__PURE__ */ jsx(ChevronDown, { className: "h-4 w-4 text-muted-foreground" }),
+          /* @__PURE__ */ jsxs("span", { className: "text-sm font-semibold text-destructive", children: [
+            "Errors (",
+            state.validationErrors.length,
+            ")"
+          ] }),
+          /* @__PURE__ */ jsx("span", { className: "ml-auto text-[11px] font-medium text-muted-foreground", children: "via onValidationChange" })
+        ]
+      }
+    ),
+    !state.errorsCollapsed && /* @__PURE__ */ jsx("div", { className: "px-4 pb-4 space-y-0.5", children: state.validationErrors.map((err, idx) => /* @__PURE__ */ jsx("p", { className: "text-xs text-destructive", children: err }, idx)) })
+  ] });
+}
 function DataColumn({
   state
 }) {
@@ -881,6 +1044,7 @@ function DataColumn({
         transition: "flex 200ms ease"
       },
       children: [
+        !state.dataCollapsed && /* @__PURE__ */ jsx(ErrorsCard, { state }),
         /* @__PURE__ */ jsxs(
           Card,
           {
@@ -974,4 +1138,4 @@ function PlayForms() {
 export {
   PlayForms
 };
-//# sourceMappingURL=chunk-ZSUCFEB6.js.map
+//# sourceMappingURL=chunk-BRH3FFFT.js.map