@petrarca/sonnet-schema-designer 0.6.0 → 0.8.0

package/README.md

@@ -0,0 +1,97 @@
+# @petrarca/sonnet-schema-designer
+
+A visual editor for JSON Schema, part of the Petrarca Sonnet component library.
+One component, `SchemaDesigner`, edits a schema in place. Presentation hints
+travel beside it in a UI Schema map, or embedded on the schema when you ask for
+that shape.
+
+## What it provides
+
+**Three panes.** A property tree on the left for structure -- select, add,
+delete, reorder, rename, with a collapsible region for `$defs`. A preview in
+the centre with tabs over the live form, the form layout designer, a table and
+the JSON source. An inspector on the right with Data, Enum, UI, Rule and Table
+editors for the selected node. Both side panes resize and collapse.
+
+**Schema authoring.** Types and validation, nesting, `oneOf` variants,
+conditionals, definitions and references. Local `#/$defs/...` and
+`#/definitions/...` references resolve on their own; anything else goes through
+a synchronous `refResolver` and expands read-only in the tree.
+
+**Presentation authoring.** Widgets and their options, table hints, visibility
+rules and form layout, in the same `x-ui-*` vocabulary
+`JsonSchemaFormRenderer` reads. `embedUiSchema` merges the top-level form hints
+onto the schema when a single self-contained artifact is wanted.
+
+**Capability gating.** A profile restricts what a user may author -- a
+data-only profile, a fixed schema with editable areas, or a locked view --
+validated by `resolveCapabilities`, `validateCapabilities` and
+`capabilitiesSchema`.
+
+**The pieces behind the shell.** `useDesignerState` holds the whole model and
+every mutation; `PropertyTree`, `Inspector`, `PreviewPane`,
+`FormLayoutDesigner` and `FormSettingsSheet` each take that state. A real seam,
+though the shell is the supported way to use them.
+
+## Install
+
+```bash
+pnpm add @petrarca/sonnet-schema-designer
+```
+
+`@petrarca/sonnet-core`, `@petrarca/sonnet-ui` and `@petrarca/sonnet-forms` are
+regular dependencies and arrive with it, as do `lucide-react` and Zod.
+
+| Peer | Range | Needed for |
+|---|---|---|
+| `react`, `react-dom` | `>=19` | Everything |
+| `tailwindcss` | `>=3` | The styles the components emit |
+
+It renders through `sonnet-ui`'s stylesheet and Tailwind preset, so set those
+up first -- see
+[sonnet-ui: getting started](../sonnet-ui/docs/usage/getting-started.md).
+
+## Usage
+
+```tsx
+import { SchemaDesigner } from "@petrarca/sonnet-schema-designer";
+import type { JsonSchema, UISchema } from "@petrarca/sonnet-core/schema";
+
+const [schema, setSchema] = useState<JsonSchema>(initial);
+const [uiSchema, setUiSchema] = useState<Record<string, UISchema>>({});
+
+<SchemaDesigner
+  schema={schema}
+  uiSchema={uiSchema}
+  onChange={(nextSchema, nextUiSchema) => {
+    setSchema(nextSchema);
+    setUiSchema(nextUiSchema);
+  }}
+/>;
+```
+
+All nine props are optional -- `schema`, `uiSchema`, `initialSchema`,
+`initialUiSchema`, `onChange`, `readOnly`, `capabilities`, `widgetOptions` and
+`refResolver`. The mode is decided by whether `schema` is `undefined`: omit it
+and seed with `initialSchema` for uncontrolled use, where the designer keeps
+the model internally and still reports every edit through `onChange`. With
+neither, it starts from an empty object schema.
+
+The root element is `w-full h-full`, so the parent must have a resolved height.
+
+## Documentation
+
+- [Usage guides](docs/usage/index.md) -- getting started,
+  [authoring schemas](docs/usage/authoring-schemas.md),
+  [UI hints](docs/usage/ui-hints.md) and
+  [capabilities](docs/usage/capabilities.md).
+- [Design docs](docs/design/index.md) -- the designer's structure, logic
+  authoring, and references and definitions.
+- [The UISchema vocabulary](../sonnet-forms/docs/usage/ui-schema.md) -- what the
+  `x-ui-*` keys mean to the form renderer.
+- [Workspace documentation](../../docs/README.md) -- how the packages layer and
+  the architecture decision records.
+
+## License
+
+Apache 2.0. See [LICENSE.md](../../LICENSE.md).

package/dist/index.d.ts

@@ -443,7 +443,8 @@ declare function embedUiSchema(schema: JsonSchema, uiSchema: Record<string, UISc
  * fully-locked shorthand). Every field is optional and defaults to the most
  * permissive value, so adding a capability never tightens an existing profile.
  *
- * Design: docs/design/schema-designer.md, section "Capability gating".
+ * Design: docs/design/schema-designer.md in this package; usage in
+ * docs/usage/capabilities.md.
  */
 
 /**
@@ -451,11 +452,17 @@ declare function embedUiSchema(schema: JsonSchema, uiSchema: Record<string, UISc
  * schema; "capabilities" is a meta-editor for the profile itself (a dev /
  * power-user affordance), not a preview -- it is opt-in and never in a default.
  */
-type PreviewKind = "form" | "table" | "json" | "capabilities";
+declare const previewKindSchema: z.ZodEnum<{
+    form: "form";
+    table: "table";
+    json: "json";
+    capabilities: "capabilities";
+}>;
+type PreviewKind = z.infer<typeof previewKindSchema>;
 /**
  * The capabilities schema. Small by design -- it covers the real consumer needs
- * (sestina's audit-event and terminology schema editors) without a per-area
- * matrix we do not use yet.
+ * (locked-down, single-schema editors embedded in an application) without a
+ * per-area matrix we do not use yet.
  */
 declare const capabilitiesSchema: z.ZodObject<{
     mode: z.ZodDefault<z.ZodEnum<{
@@ -475,13 +482,15 @@ declare const capabilitiesSchema: z.ZodObject<{
  * fields optional on input (defaults are applied by resolveCapabilities).
  */
 type SchemaDesignerCapabilities = z.input<typeof capabilitiesSchema>;
+/**
+ * The schema's own fields once resolved. Derived from the schema rather than
+ * restated, so adding or retyping a capability cannot silently drift from it.
+ * `Required` because resolveCapabilities defaults every optional field --
+ * `previews` by mode, `editablePaths` to empty -- so none is absent downstream.
+ */
+type ResolvedSchemaFields = Required<z.output<typeof capabilitiesSchema>>;
 /** The fully-resolved capabilities, plus the derived flags used for gating. */
-interface ResolvedCapabilities {
-    mode: "data" | "full";
-    /** Effective preview list (defaulted by mode when not provided). */
-    previews: PreviewKind[];
-    /** JSON Pointer paths whose children are editable; empty = no scoping. */
-    editablePaths: string[];
+interface ResolvedCapabilities extends ResolvedSchemaFields {
     /** No structural edits at all (readOnly shorthand). */
     locked: boolean;
     /** editablePaths is non-empty -- only designated subtrees are editable. */
@@ -829,4 +838,4 @@ interface FormSettingsSheetProps {
 }
 declare function FormSettingsSheet({ open, onOpenChange, state, }: FormSettingsSheetProps): React.ReactElement;
 
-export { type CapabilitiesValidation, type ChildSlot, type ConditionCombinator, DataTab, type DesignerModel, type DesignerState, type EnumChoice, EnumEditor, FormLayoutDesigner, FormSettingsSheet, Inspector, type LayoutScope, type NewPropertyKind, type PathSegment, type PathSlot, PreviewPane, type PropertyKind, type PropertyNode, type PropertyPath, PropertyTree, type PropertyTypeChoice, type ResolvedCapabilities, SchemaDesigner, type SchemaDesignerCapabilities, type SchemaDesignerProps, type SlotKind, type TableHints, TableHintsTab, TablePreview, UITab, type UiSchemaMap, type UseDesignerStateArgs, type WidgetChoice, addBranch, addConditional, addDefinition, addElse, addLayoutGroup, addProperty, branch, buildPropertyTree, capabilitiesSchema, changePropertyType, childContainer, childSlots, compatibleWidgets, condition, def, definitionUsageCount, definitionsOf, deleteProperty, embedUiSchema, getProperty, getScopedLayout, getUiEntryAtPath, isContainer, isReservedKey, layoutScopes, moveBranch, moveLayoutGroup, moveProperty, newBranch, newCondition, newProperty, orderedKeys, parsePathKey, pathKey, placeFieldInGroup, prop, propertyKind, readEnumChoices, readTableHints, removeBranch, removeConditional, removeDefinition, removeElse, removeLayoutGroup, renameDefinition, renameLayoutGroup, renameProperty, resolveCapabilities, samePath, sameSegment, sampleRows, schemaAsRootProp, setCondition, setConditionalBehavior, setEnum, setGlobalOptions, setLayoutGroupRule, setPropertyLayout, setReference, setRequired, setRootLayout, setRootLayoutRows, setScopedGroupRows, setScopedLayoutGroups, setScopedLayoutMode, setScopedLayoutOptions, setScopedLayoutRows, setScopedLayoutVariant, setTableHints, setUiEntry, slot, updateProperty, useDesignerState, validateCapabilities };
+export { type CapabilitiesValidation, type ChildSlot, type ConditionCombinator, DataTab, type DesignerModel, type DesignerState, type EnumChoice, EnumEditor, FormLayoutDesigner, FormSettingsSheet, Inspector, type LayoutScope, type NewPropertyKind, type PathSegment, type PathSlot, type PreviewKind, PreviewPane, type PropertyKind, type PropertyNode, type PropertyPath, PropertyTree, type PropertyTypeChoice, type ResolvedCapabilities, SchemaDesigner, type SchemaDesignerCapabilities, type SchemaDesignerProps, type SlotKind, type TableHints, TableHintsTab, TablePreview, UITab, type UiSchemaMap, type UseDesignerStateArgs, type WidgetChoice, addBranch, addConditional, addDefinition, addElse, addLayoutGroup, addProperty, branch, buildPropertyTree, capabilitiesSchema, changePropertyType, childContainer, childSlots, compatibleWidgets, condition, def, definitionUsageCount, definitionsOf, deleteProperty, embedUiSchema, getProperty, getScopedLayout, getUiEntryAtPath, isContainer, isReservedKey, layoutScopes, moveBranch, moveLayoutGroup, moveProperty, newBranch, newCondition, newProperty, orderedKeys, parsePathKey, pathKey, placeFieldInGroup, prop, propertyKind, readEnumChoices, readTableHints, removeBranch, removeConditional, removeDefinition, removeElse, removeLayoutGroup, renameDefinition, renameLayoutGroup, renameProperty, resolveCapabilities, samePath, sameSegment, sampleRows, schemaAsRootProp, setCondition, setConditionalBehavior, setEnum, setGlobalOptions, setLayoutGroupRule, setPropertyLayout, setReference, setRequired, setRootLayout, setRootLayoutRows, setScopedGroupRows, setScopedLayoutGroups, setScopedLayoutMode, setScopedLayoutOptions, setScopedLayoutRows, setScopedLayoutVariant, setTableHints, setUiEntry, slot, updateProperty, useDesignerState, validateCapabilities };

package/dist/index.js

@@ -1261,11 +1261,12 @@ import { useCallback, useMemo, useRef, useState } from "react";
 // src/capabilities.ts
 import { z } from "zod";
 import { warnLog } from "@petrarca/sonnet-core";
+var previewKindSchema = z.enum(["form", "table", "json", "capabilities"]);
 var capabilitiesSchema = z.object({
   mode: z.enum(["data", "full"]).default("full").meta({
     description: "What the designer authors. 'full' (default): JSON Schema + uiSchema (form presentation hints). 'data': JSON Schema only -- the UI Schema tab, Combined tab, and the inspector's per-field UI tab are hidden (pure data schemas: audit events, terminology)."
   }),
-  previews: z.array(z.enum(["form", "table", "json", "capabilities"])).optional().meta({
+  previews: z.array(previewKindSchema).optional().meta({
     description: "Which tabs the center pane offers, in order. 'form'/'table'/'json' preview the schema; 'capabilities' is a JSON editor for this profile (opt-in, never in a default). When omitted, defaults to ['form','table','json'] in 'full' mode and ['json'] in 'data' mode. An empty list hides the center pane entirely."
   }),
   editablePaths: z.array(z.string()).optional().meta({
@@ -4730,11 +4731,36 @@ function ConditionEditor({
 
 // src/inspector/RuleEditor.tsx
 import { useMemo as useMemo12 } from "react";
-import { jsx as jsx15, jsxs as jsxs13 } from "react/jsx-runtime";
-function siblingPointers(state, node) {
-  const parentProps = node.path.length <= 1 ? state.schema.properties : findParentProperties(state, node);
-  const self = node.key;
-  return Object.entries(parentProps ?? {}).filter(([k]) => k !== self).map(([k, prop2]) => ({ pointer: `/${k}`, type: prop2.type }));
+
+// src/inspector/ruleScopes.ts
+function dataPointerPrefix(node) {
+  let prefix = "";
+  for (let i = 0; i < node.path.length - 1; i++) {
+    const seg = node.path[i];
+    if (seg.kind !== "prop") return void 0;
+    prefix += `/${seg.key}`;
+  }
+  return prefix;
+}
+function scopePointers(state, node) {
+  const options = /* @__PURE__ */ new Map();
+  const prefix = dataPointerPrefix(node);
+  const selfPointer = prefix === void 0 ? void 0 : `${prefix}/${node.key}`;
+  const add = (pointer, prop2) => {
+    if (pointer === selfPointer) return;
+    if (!options.has(pointer))
+      options.set(pointer, { pointer, type: prop2.type });
+  };
+  for (const [k, prop2] of Object.entries(state.schema.properties ?? {})) {
+    add(`/${k}`, prop2);
+  }
+  if (prefix) {
+    const siblings = findParentProperties(state, node);
+    for (const [k, prop2] of Object.entries(siblings ?? {})) {
+      add(`${prefix}/${k}`, prop2);
+    }
+  }
+  return [...options.values()];
 }
 function findParentProperties(state, node) {
   let props = state.schema.properties;
@@ -4747,11 +4773,14 @@ function findParentProperties(state, node) {
   }
   return props;
 }
+
+// src/inspector/RuleEditor.tsx
+import { jsx as jsx15, jsxs as jsxs13 } from "react/jsx-runtime";
 function RuleEditor({
   node,
   state
 }) {
-  const scopes = useMemo12(() => siblingPointers(state, node), [state, node]);
+  const scopes = useMemo12(() => scopePointers(state, node), [state, node]);
   return /* @__PURE__ */ jsxs13("div", { className: "space-y-3", children: [
     /* @__PURE__ */ jsx15("p", { className: "text-xs text-muted-foreground", children: "Toggle this field's visibility (or enabled state) based on another field's value. The field keeps its position in the form." }),
     /* @__PURE__ */ jsx15(