@petrarca/sonnet-schema-designer 0.8.0 → 0.9.0

package/dist/index-Cu6JZdYj.d.ts

@@ -0,0 +1,875 @@
+import { JsonSchemaProperty, JsonSchema, UISchema, UILayoutConfig, UISchemaOptions, UILayoutGroupConfig, UILayoutRowConfig, ValueType, Binding } from '@petrarca/sonnet-core/schema';
+import { z } from 'zod';
+
+/**
+ * Path navigation over a JsonSchema tree.
+ *
+ * A path is a list of typed segments from the root down to a property. Most
+ * segments are property keys (`{kind:"prop"}`) -- object children nest through
+ * `properties`, array-of-object children through `items.properties`, and the
+ * navigator descends through `items` transparently so an array and its item
+ * object share one editing surface.
+ *
+ * Logic constructs introduce non-property segments: `{kind:"branch"}` for a
+ * `oneOf`/`allOf` element, and `{kind:"slot"}` for a fixed schema slot
+ * (`then`/`else`/`items`). The discriminated union keeps the distinction
+ * explicit and type-checked; a single codec (pathKey/parsePathKey) owns all
+ * conversion to/from strings.
+ */
+
+/** A fixed schema slot that holds a single sub-schema. */
+type PathSlot = "then" | "else" | "items";
+/**
+ * The array a conditional (if/then/else) member lives in. `allOf` = every
+ * condition must hold (AND); `anyOf` = any condition suffices (OR). Maps to
+ * FHIR `enableBehavior` "all" / "any".
+ */
+type ConditionCombinator = "allOf" | "anyOf";
+/** One step in a property path. */
+type PathSegment = {
+    kind: "prop";
+    key: string;
+} | {
+    kind: "branch";
+    index: number;
+} | {
+    kind: "condition";
+    combinator: ConditionCombinator;
+    index: number;
+} | {
+    kind: "slot";
+    slot: PathSlot;
+} | {
+    kind: "def";
+    name: string;
+};
+type PropertyPath = PathSegment[];
+/**
+ * Whether a property key is reserved by the path codec. Keys matching
+ * `/^#(branch|condition|def|slot):/` would corrupt the pathKey/parsePathKey
+ * round-trip. The designer guards against these at rename/add time.
+ */
+declare function isReservedKey(key: string): boolean;
+/** Construct a property-key segment. */
+declare function prop(key: string): PathSegment;
+/** Construct a branch (oneOf element) segment. */
+declare function branch(index: number): PathSegment;
+/** Construct a condition (if/then/else member) segment for a combinator array. */
+declare function condition(index: number, combinator?: ConditionCombinator): PathSegment;
+/** Construct a fixed-slot segment. */
+declare function slot(name: PathSlot): PathSegment;
+/** Construct a definition ($defs entry) segment. Root-only in practice. */
+declare function def(name: string): PathSegment;
+/** Serialize a path to a stable string (React key, selection id, scope value). */
+declare function pathKey(path: PropertyPath): string;
+/** Parse a string produced by {@link pathKey} back into a path. */
+declare function parsePathKey(key: string): PropertyPath;
+/** Whether two path segments refer to the same position. */
+declare function sameSegment(a: PathSegment, b: PathSegment): boolean;
+/** Whether two paths refer to the same node (structural comparison). */
+declare function samePath(a: PropertyPath | null, b: PropertyPath | null): boolean;
+/** How a child slot is presented and mutated. */
+type SlotKind = "property" | "branch" | "conditional" | "definition";
+/** A single editable child of a property (or the root). */
+interface ChildSlot {
+    /** Segment appended to the parent path to reach this child. */
+    segment: PathSegment;
+    /** Display label for the tree row. */
+    label: string;
+    /** The child schema. */
+    property: JsonSchemaProperty;
+    kind: SlotKind;
+    removable: boolean;
+    reorderable: boolean;
+}
+/**
+ * The properties map that holds a property's named children, or undefined when
+ * it has none. Object children live in `properties`; array-of-object children
+ * live in `items.properties`. (Logic constructs use branch/slot children and
+ * are surfaced via {@link childSlots}, not here.)
+ */
+declare function childContainer(prop: JsonSchemaProperty): Record<string, JsonSchemaProperty> | undefined;
+/**
+ * The reusable definitions map of a schema. Canonically 2020-12 `$defs`; also
+ * reads Draft-7 `definitions` so both dialects surface as editable nodes. New
+ * definitions are always authored into `$defs` (see mutate.addDefinition).
+ */
+declare function definitionsOf(property: JsonSchemaProperty): Record<string, JsonSchemaProperty> | undefined;
+/**
+ * The ordered child slots of a property (the single extension point for the
+ * tree/inspector/mutations). Surfaces object/array property children, oneOf
+ * branches, if/then/else conditionals (allOf/anyOf members), and $defs
+ * definitions (root-only in practice).
+ */
+declare function childSlots(property: JsonSchemaProperty): ChildSlot[];
+/**
+ * Wrap a JsonSchema root as an object-shaped JsonSchemaProperty so the path
+ * navigation machinery can traverse it with the same stepInto logic as any
+ * nested property. Pass the keys needed by the caller; unused fields default
+ * to undefined.
+ */
+declare function schemaAsRootProp(schema: JsonSchema): JsonSchemaProperty;
+/** Resolve a path to its property definition, or undefined if not found. */
+declare function getProperty(schema: JsonSchema, path: PropertyPath): JsonSchemaProperty | undefined;
+/** Whether a property has (or can have) child slots (properties, branches, conditionals). */
+declare function isContainer(prop: JsonSchemaProperty): boolean;
+
+/**
+ * Pure edit operations over { schema, uiSchema }.
+ *
+ * Every function returns a new pair; nothing mutates in place. Operations keep
+ * the schema and uiSchema consistent -- renaming a property rewrites the property
+ * key, the uiSchema entry, the required entry, and any x-ui-order reference at
+ * the same level. Mirrors the graph-model/mutate.ts discipline.
+ */
+
+type UiSchemaMap = Record<string, UISchema>;
+interface DesignerModel {
+    schema: JsonSchema;
+    uiSchema: UiSchemaMap;
+}
+/** Kinds that can be created as a new property. */
+type NewPropertyKind = "scalar" | "object" | "array" | "oneOf";
+/** A default property for a newly created property of a given kind. */
+declare function newProperty(kind: NewPropertyKind): JsonSchemaProperty;
+/** A default oneOf branch: an object with a const-valued `kind` discriminator. */
+declare function newBranch(value: string): JsonSchemaProperty;
+/** Add a property under a parent path (root when empty). Returns the new model. */
+declare function addProperty(model: DesignerModel, parentPath: PropertyPath, kind: NewPropertyKind): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Add a branch to the oneOf property at `path`. Returns the new model + branch path. */
+declare function addBranch(model: DesignerModel, path: PropertyPath): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Remove the branch at `path` (a branch segment). Returns the new model. */
+declare function removeBranch(model: DesignerModel, path: PropertyPath): DesignerModel;
+/** Move the branch at `path` up (-1) or down (+1) among its siblings. */
+declare function moveBranch(model: DesignerModel, path: PropertyPath, direction: -1 | 1): DesignerModel;
+/**
+ * A seed conditional member: an empty `if` (no field yet) plus an empty `then`.
+ * The condition is filled in by setCondition; `then` fields are added like any
+ * object's properties.
+ */
+declare function newCondition(): JsonSchemaProperty;
+/**
+ * Add a conditional (if/then/else) to the object at `objectPath` (root when
+ * empty), appended to the given combinator array (`allOf` = AND, default;
+ * `anyOf` = OR). Returns the new model + the condition path.
+ */
+declare function addConditional(model: DesignerModel, objectPath: PropertyPath, combinator?: ConditionCombinator): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Remove the conditional at `path` (a condition segment). Returns the new model. */
+declare function removeConditional(model: DesignerModel, path: PropertyPath): DesignerModel;
+/** Write the `if` of the conditional at `path` from a condition triple. */
+declare function setCondition(model: DesignerModel, path: PropertyPath, ifSchema: JsonSchemaProperty): DesignerModel;
+/** Add an empty `else` branch to the conditional at `path`. */
+declare function addElse(model: DesignerModel, path: PropertyPath): DesignerModel;
+/** Remove the `else` branch from the conditional at `path`. */
+declare function removeElse(model: DesignerModel, path: PropertyPath): DesignerModel;
+/**
+ * Switch the combinator (AND/OR) for the conditionals of the object at
+ * `objectPath`. Migrates every conditional member from the current combinator
+ * array to `next`. Non-conditional members (structural allOf/anyOf entries)
+ * stay put. No-op when already using `next` or when there are no conditionals.
+ */
+declare function setConditionalBehavior(model: DesignerModel, objectPath: PropertyPath, next: ConditionCombinator): DesignerModel;
+/** Delete the property at path. Returns the new model. */
+declare function deleteProperty(model: DesignerModel, path: PropertyPath): DesignerModel;
+/** Rename the property at path. Rewrites key, order, required, and uiSchema. */
+declare function renameProperty(model: DesignerModel, path: PropertyPath, nextKey: string): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Move the property at path up (-1) or down (+1) among its siblings. */
+declare function moveProperty(model: DesignerModel, path: PropertyPath, direction: -1 | 1): DesignerModel;
+/** Toggle whether the property at path is required among its siblings. */
+declare function setRequired(model: DesignerModel, path: PropertyPath, required: boolean): DesignerModel;
+/** Replace the property definition at path (merges the given partial). */
+declare function updateProperty(model: DesignerModel, path: PropertyPath, patch: Partial<JsonSchemaProperty>): DesignerModel;
+/** The kind a property can be changed to: a JSON Schema type, or a "oneOf" union. */
+type PropertyTypeChoice = NonNullable<JsonSchemaProperty["type"]> | "oneOf";
+/**
+ * Change the kind of the property at path, reshaping structural keys: object
+ * adds an empty `properties`; array adds `items`; oneOf adds branches + a
+ * discriminator; leaving a kind strips its keys. Type-specific validation keys
+ * that no longer apply are dropped.
+ */
+declare function changePropertyType(model: DesignerModel, path: PropertyPath, next: PropertyTypeChoice): DesignerModel;
+/**
+ * Point the property at path to a definition by name, writing a local `$ref`
+ * (`#/$defs/<name>`) and stripping type-specific keys. Turns a plain property
+ * into a reference usage. No-op for the root or an unknown target.
+ */
+declare function setReference(model: DesignerModel, path: PropertyPath, name: string): DesignerModel;
+/**
+ * Add a new empty object definition under `$defs`. Returns the new model and the
+ * path to the created definition for selection.
+ */
+declare function addDefinition(model: DesignerModel, name?: string): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/**
+ * Rename a `$defs` entry, preserving order, and rewrite every local `$ref` that
+ * targets it (both `#/$defs/` and `#/definitions/` forms) to the new pointer.
+ * No-op on collision, reserved, or empty names.
+ */
+declare function renameDefinition(model: DesignerModel, oldName: string, newName: string): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/**
+ * Remove a `$defs` entry. Blocked (no-op) while any local `$ref` still targets
+ * it; the UI surfaces the usage count. Drops the `$defs` map when it empties.
+ */
+declare function removeDefinition(model: DesignerModel, name: string): DesignerModel;
+/** Whether a definition is referenced anywhere (for UI delete-guard messaging). */
+declare function definitionUsageCount(schema: JsonSchema, name: string): number;
+/** One enum choice: a value and an optional display label. */
+interface EnumChoice {
+    value: string;
+    label?: string;
+}
+declare function setEnum(model: DesignerModel, path: PropertyPath, choices: EnumChoice[]): DesignerModel;
+/** Read the current enum choices for a property + its uiSchema entry. */
+declare function readEnumChoices(prop: JsonSchemaProperty, uiEntry: UISchema | undefined): EnumChoice[];
+/** Table presentation hints for a property (embedded in the schema). */
+interface TableHints {
+    cell?: string;
+    cellOptions?: Record<string, unknown>;
+    column?: NonNullable<JsonSchemaProperty["x-ui-column"]>;
+}
+/**
+ * Set (or clear) a property's table hints: x-ui-cell, x-ui-cell-options, and
+ * x-ui-column. These live embedded on the property (EntityTable reads them
+ * there). Empty values clear the corresponding key.
+ */
+declare function setTableHints(model: DesignerModel, path: PropertyPath, hints: TableHints): DesignerModel;
+/** Read a property's current table hints. */
+declare function readTableHints(prop: JsonSchemaProperty): TableHints;
+/** Read the UISchema entry for a property path, or undefined. */
+declare function getUiEntryAtPath(uiSchema: UiSchemaMap, path: PropertyPath): UISchema | undefined;
+/** Set (or clear) the UISchema entry at a property path (any nesting depth). */
+declare function setUiEntry(model: DesignerModel, path: PropertyPath, entry: UISchema | undefined): DesignerModel;
+/**
+ * Set (or clear) the x-ui-layout of an object/array property at path. Object
+ * layout lives on the property; array layout lives on `items`.
+ */
+declare function setPropertyLayout(model: DesignerModel, path: PropertyPath, layout: UILayoutConfig | undefined): DesignerModel;
+/** Set (or clear) the root form layout (uiSchema["x-ui-layout"]). */
+declare function setRootLayout(model: DesignerModel, layout: UILayoutConfig | undefined): DesignerModel;
+/**
+ * Set (or clear) the root layout rows (uiSchema["x-ui-layout"].rows),
+ * preserving other x-ui-layout keys. Clearing rows to empty removes the key;
+ * if x-ui-layout then has no keys, it is removed entirely.
+ */
+declare function setRootLayoutRows(model: DesignerModel, rows: UILayoutConfig["rows"]): DesignerModel;
+/**
+ * Set the layout rows for a scope: the root form (path []) or an object/array
+ * container (its property path). Root rows live in uiSchema["x-ui-layout"];
+ * a container's rows live on the property's x-ui-layout (array -> items).
+ * Preserves other x-ui-layout keys.
+ */
+declare function setScopedLayoutRows(model: DesignerModel, scopePath: PropertyPath, rows: UILayoutConfig["rows"]): DesignerModel;
+/** Read the current x-ui-layout for a scope (root or a container property). */
+declare function getScopedLayout(schema: JsonSchema, uiSchema: UiSchemaMap, scopePath: PropertyPath): UILayoutConfig | undefined;
+/**
+ * Merge scalar layout options (direction/gap/labels/compact) into a scope's
+ * x-ui-layout, preserving rows and other keys. Undefined values clear the key.
+ */
+declare function setScopedLayoutOptions(model: DesignerModel, scopePath: PropertyPath, options: Pick<UILayoutConfig, "direction" | "gap" | "labels" | "compact">): DesignerModel;
+/**
+ * Set the group definitions for a scope, preserving other x-ui-layout keys.
+ * Passing an empty list (or undefined) clears groups, returning the scope to the
+ * flat row layout. Root groups live in uiSchema["x-ui-layout"]; a container's
+ * live on the property's x-ui-layout (array -> items).
+ *
+ * Groups and flat rows are mutually exclusive (the renderer gives groups
+ * precedence), so setting groups drops `rows` -- otherwise the orphaned list
+ * would be invisible in both the form and the designer.
+ */
+declare function setScopedLayoutGroups(model: DesignerModel, scopePath: PropertyPath, groups: UILayoutConfig["groups"]): DesignerModel;
+/** Append an empty group. The label defaults to the next ordinal ("Group 3"). */
+declare function addLayoutGroup(model: DesignerModel, scopePath: PropertyPath, label?: string): DesignerModel;
+/** Rename one group. No-op for an unknown index or a blank label. */
+declare function renameLayoutGroup(model: DesignerModel, scopePath: PropertyPath, groupIndex: number, label: string): DesignerModel;
+/**
+ * Place a property into one group's row, removing it from wherever it currently
+ * sits across *all* groups. Passing a null target returns it to the pool.
+ *
+ * Needed because each group owns its own rows: without a cross-group operation a
+ * field could only be moved between groups by visiting its old group first.
+ */
+declare function placeFieldInGroup(model: DesignerModel, scopePath: PropertyPath, key: string, target: {
+    groupIndex: number;
+    rowIndex: number;
+} | null): DesignerModel;
+/** Move one group left (-1) or right (+1). No-op at the ends. */
+declare function moveLayoutGroup(model: DesignerModel, scopePath: PropertyPath, groupIndex: number, direction: -1 | 1): DesignerModel;
+/**
+ * Set (or clear) a group's show/hide rule. Passing undefined makes the group
+ * unconditional.
+ */
+declare function setLayoutGroupRule(model: DesignerModel, scopePath: PropertyPath, groupIndex: number, rule: UILayoutGroupConfig["rule"]): DesignerModel;
+/**
+ * Set the group presentation for a scope ("groups", "stepper", or a custom
+ * template name). Passing undefined restores the default group presentation.
+ */
+declare function setScopedLayoutVariant(model: DesignerModel, scopePath: PropertyPath, variant: UILayoutConfig["variant"]): DesignerModel;
+/**
+ * Remove one group. Its rows are not discarded: removing the last remaining group
+ * flattens them back into the scope's flat row layout, so a single click can
+ * never destroy every field placement.
+ */
+declare function removeLayoutGroup(model: DesignerModel, scopePath: PropertyPath, groupIndex: number): DesignerModel;
+/** Replace the rows of one group in a scope. No-op for an unknown group index. */
+declare function setScopedGroupRows(model: DesignerModel, scopePath: PropertyPath, groupIndex: number, rows: UILayoutRowConfig[]): DesignerModel;
+/**
+ * Switch a scope between flat rows and groups, carrying the existing layout over
+ * so no field placement is lost: rows become the first group's rows, and leaving
+ * group mode flattens every group's rows back into one list.
+ */
+declare function setScopedLayoutMode(model: DesignerModel, scopePath: PropertyPath, mode: "rows" | "groups"): DesignerModel;
+/** Set (or clear) the root global options (uiSchema["x-ui-globalOptions"]). */
+declare function setGlobalOptions(model: DesignerModel, options: UISchemaOptions | undefined): DesignerModel;
+
+/**
+ * Value types as answer types -- a value type contributed to the questionnaire
+ * designer: a question whose `$ref` is the type's id is that answer type, and
+ * its settings are fields the panel shows, read from and written to the
+ * question through the contribution. Sonnet contributes the core types the
+ * same way an application contributes its own. Pure, no React. See
+ * docs/design/value-types.md (workspace).
+ */
+
+/** A value type's settings: the panel's fields, read from and written to the question. */
+interface ValueTypeSettings {
+    /** The fields, by name, as JSON Schema properties of the panel's form. */
+    fields: Record<string, JsonSchemaProperty>;
+    /** The settings' values, read from the question's property and hints. */
+    read(prop: JsonSchemaProperty, ui: UISchema): Record<string, unknown>;
+    /** What the values write: keywords beside the `$ref`, and `x-ui-options` keys -- undefined removes one. */
+    write(values: Record<string, unknown>): {
+        prop: Partial<JsonSchemaProperty>;
+        options: Record<string, unknown>;
+    };
+}
+/** A value type contributed as an answer type of the questionnaire designer. */
+interface ValueTypeAnswer {
+    type: ValueType;
+    /** The keywords it narrows beside its `$ref` (the quantity's `properties`). */
+    keywords?: string[];
+    /** The `x-ui-options` keys its settings use (the quantity's `units`). */
+    options?: string[];
+    /** Whether a property of the type is one the designer understands; default: any. */
+    accepts?(prop: JsonSchemaProperty): boolean;
+    settings?: ValueTypeSettings;
+}
+/** The quantity as an answer type: narrowed at most to its units, each in its range. */
+declare const QUANTITY_ANSWER: ValueTypeAnswer;
+/** The binding a coded value's settings write; none without a list. */
+declare function codingBindingOf(values: Record<string, unknown>): Binding | undefined;
+/** The coded value as an answer type: a code from the list its binding names. */
+declare const CODING_ANSWER: ValueTypeAnswer;
+/** The codeable concept as an answer type: a concept coded in its first list and in further ones, or its text. */
+declare const CODEABLE_CONCEPT_ANSWER: ValueTypeAnswer;
+/** The value types sonnet contributes: the core types. */
+declare const DEFAULT_VALUE_TYPES: readonly ValueTypeAnswer[];
+/** The value type a property is, among those contributed -- by its `$ref`, or that or a text; undefined when none. */
+declare function valueTypeOf(prop: JsonSchemaProperty, types: readonly ValueTypeAnswer[]): ValueTypeAnswer | undefined;
+/** The contribution of an answer type, when it is a value type. */
+declare function valueTypeAnswer(answerType: string, types: readonly ValueTypeAnswer[]): ValueTypeAnswer | undefined;
+
+/**
+ * Answer types -- a question's kind of answer, as a pattern of schema keywords
+ * and form hints. Pure, no React.
+ *
+ * An answer type is never stored: `recognizeAnswerType` finds it in a property
+ * and its effective hints, and names the keywords the pattern does not account
+ * for (the question's extra settings, kept untouched). See
+ * docs/design/questionnaires.md, "Answer types".
+ */
+
+/** The answer types the questionnaire designer knows itself. */
+type BuiltinAnswerType = "yesNo" | "shortText" | "longText" | "integer" | "decimal" | "date" | "time" | "dateTime" | "singleChoice" | "multipleChoice" | "choiceWithText" | "listOfText" | "parts";
+/**
+ * An answer type: a built-in one, or a contributed value type -- by its id
+ * (see valueTypes.ts).
+ */
+type AnswerType = BuiltinAnswerType | (string & {});
+/** What each built-in answer type is called where an author sees it. */
+declare const ANSWER_TYPE_LABELS: Record<BuiltinAnswerType, string>;
+/** Whether an answer type is one the designer knows itself, not a contributed value type. */
+declare function isBuiltinAnswerType(type: string): type is BuiltinAnswerType;
+/** What an answer type is called: its label, or its contribution's. */
+declare function answerTypeLabel(type: AnswerType, types?: readonly ValueTypeAnswer[]): string;
+/**
+ * The container widget a choice with text renders with: it arranges its two
+ * children, `choice` and `text`, each rendered by its own widget -- a select,
+ * radio buttons, a terminology picker -- resolved as for any field.
+ */
+declare const CHOICE_WITH_TEXT_WIDGET = "choice-with-text";
+/** Whether an answer type is a container -- its children answers of their own, it no answer itself. */
+declare function isContainerType(type: AnswerType): boolean;
+/** A recognized answer: its type, and the keywords the pattern leaves unexplained. */
+interface RecognizedAnswer {
+    type: AnswerType;
+    /** Schema keywords and hints beyond the pattern -- shown as extra settings, kept as they are. */
+    extras: string[];
+}
+/**
+ * The option of a choice with text whose choice asks for the text ("other,
+ * please describe"); none for the variant whose text is an optional note.
+ *
+ * The note variant has `choice` and `text` as properties. The other variant
+ * has only `choice`, and one conditional of its own: if the choice is that
+ * option, then `text`, required.
+ */
+declare function choiceTextWhen(prop: JsonSchemaProperty): string | undefined;
+/** The conditional of a choice with text's "other" variant: if the choice is `when`, then the text, required. */
+declare function otherTextMember(when: string, text: JsonSchemaProperty): JsonSchemaProperty;
+/** A choice with text's choice and text, wherever its variant keeps the text -- unchecked. */
+declare function rawChoiceAndText(prop: JsonSchemaProperty): {
+    choice?: JsonSchemaProperty;
+    text?: JsonSchemaProperty;
+};
+/**
+ * The answer type a property follows, with its extra settings; null when the
+ * property follows no answer type -- the questionnaire designer then does not
+ * understand it. A widget the type does not know is an extra setting, not a
+ * reason: the type comes from the schema's shape.
+ */
+declare function recognizeAnswerType(prop: JsonSchemaProperty, ui: UISchema, types?: readonly ValueTypeAnswer[]): RecognizedAnswer | null;
+/** The hints a property carries on itself (embedded x-ui-* keys), as a UISchema entry. */
+declare function embeddedHints(prop: JsonSchemaProperty): UISchema;
+/** A new answer's schema and hints: what writing an answer type sets, as one unit. */
+interface AnswerFragment {
+    prop: JsonSchemaProperty;
+    ui: UISchema;
+}
+/**
+ * The schema and hints of an answer type -- the reverse of recognizeAnswerType:
+ * `recognizeAnswerType(fragment.prop, fragment.ui)` is the type, with no extras.
+ */
+declare function answerTypeFragment(type: AnswerType, options?: string[]): AnswerFragment;
+
+/**
+ * Condition builder: the bridge between a friendly (property, operator, value)
+ * triple and the JSON Schema `if` sub-schema the renderer evaluates.
+ *
+ * An `if` tests a sibling property. Operators map to standard schema keywords
+ * (mirrors the FHIR operator table in packages/sonnet-fhir/docs/design/fhir-questionnaire-adapter.md, tier 1):
+ *
+ *   =        -> { properties: { field: { const: value } }, required: [field] }
+ *   !=       -> { properties: { field: { not: { const: value } } }, required: [field] }
+ *   >  >= < <= -> exclusiveMinimum / minimum / exclusiveMaximum / maximum
+ *   exists   -> { required: [field] }
+ *
+ * A value operator always adds `required: [field]` so an absent field does not
+ * vacuously satisfy the condition.
+ */
+
+type ConditionOperator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "exists";
+/** A condition as edited in the inspector. */
+interface Condition {
+    field: string;
+    operator: ConditionOperator;
+    /** Raw string value from the inspector; coerced to number where numeric. */
+    value: string;
+    /** On a coded question that also takes a text: the value is that text, not a code. */
+    asText?: boolean;
+}
+
+/**
+ * Show only if -- when a question is asked: conditions on the answers to other
+ * questions of its section, all of them or any. Pure, no React.
+ *
+ * In the schema a conditional item is an `allOf` member of its section,
+ * `{ if, then: { properties: { <item> }, required } }`: the renderer adds the
+ * item to the form while the `if` holds and removes it -- with its answer --
+ * when it does not. "All" is one `if` testing every condition; "any" is an `if`
+ * of `anyOf` single conditions. Each condition is the schema designer's
+ * (model/conditions.ts). A member is understood only when writing back what
+ * was read gives exactly the member: what the questionnaire designer cannot
+ * show as conditions stays locked. See docs/design/questionnaires.md.
+ */
+
+/** When an item is shown: all of its conditions hold, or any of them. */
+interface ShowIf {
+    behavior: "all" | "any";
+    conditions: Condition[];
+}
+/** A section's field, by key -- the comparand is written as its type takes it. */
+type FieldType = (field: string) => JsonSchemaProperty | undefined;
+/** The `if` a show-if is written as. */
+declare function showIfToIf(showIf: ShowIf, typeOf: FieldType): JsonSchemaProperty;
+/** A conditional member's `then`: the items it shows and which of them are required. */
+interface ConditionalItems {
+    showIf: ShowIf;
+    properties: Record<string, JsonSchemaProperty>;
+    required: string[];
+}
+/**
+ * The show-if of a section's `allOf` member and the items it shows, or null
+ * when the member is not one the questionnaire designer understands -- its `if`
+ * is more than conditions on the section's fields, or its `then` more than items.
+ */
+declare function readConditional(member: JsonSchemaProperty, sectionKeys: ReadonlySet<string>, typeOf: FieldType): ConditionalItems | null;
+
+/**
+ * Limits -- what an answer may be: a text's length and pattern, a number's
+ * range, a date's or a time's (`formatMinimum` / `formatMaximum`), how many a
+ * list holds. Plain JSON Schema keywords on the question,
+ * which the form validates; each answer type takes its own. Pure, no React.
+ */
+
+type LimitKeyword = "minLength" | "maxLength" | "pattern" | "minimum" | "maximum" | "minItems" | "maxItems" | "formatMinimum" | "formatMaximum";
+/** A question's limits, by keyword: counts and bounds are numbers, a pattern its text. */
+interface Limits {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    /** The earliest date, time or datetime, as the answer is written. */
+    formatMinimum?: string;
+    formatMaximum?: string;
+}
+/** The limits each answer type takes; one not listed takes none. */
+declare const ANSWER_TYPE_LIMITS: Partial<Record<AnswerType, LimitKeyword[]>>;
+/** What each limit is called where an author sees it. */
+declare const LIMIT_LABELS: Record<LimitKeyword, string>;
+/** The limits an answer type takes. */
+declare function limitsFor(type: AnswerType): LimitKeyword[];
+/** The limits a question has, of those its answer type takes. */
+declare function limitsOf(prop: JsonSchemaProperty, type: AnswerType): Limits;
+
+/**
+ * classifyQuestionnaire -- a schema (with its uiSchema) read as a questionnaire:
+ * its sections, texts and questions, and in their place whatever the
+ * questionnaire designer does not understand. Pure, no React.
+ *
+ * Every part is sorted into one of three classes: understood (an item), partly
+ * understood (an item with `extras` -- the keywords it keeps untouched) and not
+ * understood (a `locked` item, with the reason). Nothing is dropped: the
+ * classification only reads. See docs/design/questionnaires.md, "The boundary
+ * with the schema designer".
+ */
+
+interface ItemBase {
+    key: string;
+    path: PropertyPath;
+    /** When the item is shown; none: always. */
+    showIf?: ShowIf;
+}
+/** A section: a heading, an introduction, its items; repeating when it is a list of them. */
+interface SectionItem extends ItemBase {
+    kind: "section";
+    title: string;
+    description?: string;
+    repeats: boolean;
+    required: boolean;
+    /** A repeating section's count: how many entries at least, at most. */
+    limits?: {
+        minItems?: number;
+        maxItems?: number;
+    };
+    items: QuestionnaireItem[];
+    extras: string[];
+}
+/** Static text between questions. */
+interface TextItem extends ItemBase {
+    kind: "text";
+    title?: string;
+    text?: string;
+    extras: string[];
+}
+/** One option of a choice: the value stored, the label shown. */
+interface ChoiceOption {
+    value: string;
+    label: string;
+}
+/** A question: its text, help, example, and its answer type. */
+interface QuestionItem extends ItemBase {
+    kind: "question";
+    title: string;
+    help?: string;
+    placeholder?: string;
+    required: boolean;
+    readOnly: boolean;
+    answerType: AnswerType;
+    /** How the question is shown, when it names a widget its answer type knows (`radio`, `select`, ...). */
+    presentation?: string;
+    /** A choice's options, in order (single, multiple, the choice of a choice with text). */
+    options?: ChoiceOption[];
+    /** The sub-answers of a container answer type (parts; a choice with text's choice and text). */
+    parts?: QuestionItem[];
+    /** A choice with text: the option that asks for the text ("other"); none: the text is a note. */
+    textWhen?: string;
+    /** What the answer may be: its length, pattern, range, count -- as its answer type takes them. */
+    limits?: Limits;
+    /** A value type's settings, read through its contribution (a quantity's units). */
+    settings?: Record<string, unknown>;
+    /** The answer given until the person answers (`default`); none for a container. */
+    defaultAnswer?: unknown;
+    extras: string[];
+}
+/** A part the questionnaire designer does not understand: kept, shown locked, edited in the schema designer. */
+interface LockedItem extends ItemBase {
+    kind: "locked";
+    title: string;
+    reason: string;
+}
+type QuestionnaireItem = SectionItem | TextItem | QuestionItem | LockedItem;
+/** A schema read as a questionnaire. */
+interface QuestionnaireView {
+    title?: string;
+    description?: string;
+    items: QuestionnaireItem[];
+    /** The root's keywords and hints the questionnaire designer keeps untouched (a layout, definitions). */
+    extras: string[];
+    /** The reasons a question may be left unanswered for; none declared: every question is answered. */
+    reasons?: ChoiceOption[];
+}
+/** A choice's options: its enum values with their labels (x-ui-options.enumNames); none for another type. */
+declare function optionsOf(prop: JsonSchemaProperty, ui: UISchema, type: AnswerType): ChoiceOption[] | undefined;
+/** What holds a section's items: the root schema, an object, or a repeating section's items. */
+type Container = Pick<JsonSchemaProperty, "properties" | "required" | "x-ui-order" | "allOf" | "anyOf">;
+/** Every item of a container by key: its properties, and those its conditionals show -- what a show-if may test. */
+declare function containerFields(container: Container): Record<string, JsonSchemaProperty>;
+/** The keys of a container's items in the order the form shows them -- conditional ones included. */
+declare function containerOrder(container: Container): string[];
+/** Every item of a questionnaire, at any depth: each section before what it holds. */
+declare function itemsOf(items: QuestionnaireItem[]): QuestionnaireItem[];
+/** The schema read as a questionnaire: every part an item, nothing dropped. */
+declare function classifyQuestionnaire(model: DesignerModel, types?: readonly ValueTypeAnswer[]): QuestionnaireView;
+
+/**
+ * Questionnaire edits -- what the questionnaire designer does to the schema,
+ * in the author's terms. Pure, no React; built on the schema designer's own
+ * operations (model/mutate.ts), so both designers edit the same way.
+ *
+ * Every edit changes only what it touches: the rest of the schema, its
+ * uiSchema and every keyword the designer does not understand stay as they
+ * are. Changing an answer type is the one edit that can drop something; it
+ * returns what it dropped, so the designer asks before applying it. See
+ * docs/design/questionnaires.md, "The boundary with the schema designer".
+ */
+
+/** What an author adds: a question of an answer type, a text, or a section. */
+type NewItem = {
+    kind: "question";
+    answerType: AnswerType;
+} | {
+    kind: "text";
+} | {
+    kind: "section";
+};
+/** A key from a question's text: lower case, words joined by `_`, unique among `taken`. */
+declare function keyFromText(text: string, taken: Iterable<string>): string;
+/** Whether a key may be set: lower case letters, digits and `_`, starting with a letter. */
+declare function isValidKey(key: string): boolean;
+/** Add a question, a text or a section at the end of a container; its key from its text. */
+declare function addItem(model: DesignerModel, parentPath: PropertyPath, item: NewItem, text: string): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Set a question's, a section's or a text's heading. */
+declare function setItemText(model: DesignerModel, path: PropertyPath, text: string): DesignerModel;
+/** Set a question's help, a section's introduction, a text's body. */
+declare function setHelp(model: DesignerModel, path: PropertyPath, help: string): DesignerModel;
+/** Set whether a question is shown, not entered. */
+declare function setReadOnly(model: DesignerModel, path: PropertyPath, readOnly: boolean): DesignerModel;
+/** Set how a question is shown -- a widget its answer type knows (`radio`, `select`, ...); undefined: its default. */
+declare function setPresentation(model: DesignerModel, path: PropertyPath, widget: string | undefined): DesignerModel;
+/**
+ * Set a question's default answer (`default`): given until the person
+ * answers, which they may change. An empty one removes it.
+ */
+declare function setDefaultAnswer(model: DesignerModel, path: PropertyPath, value: unknown): DesignerModel;
+/** Set a question's example: shown in the empty field, never stored. */
+declare function setPlaceholder(model: DesignerModel, path: PropertyPath, example: string): DesignerModel;
+/** Set an item's key; refused (the model unchanged) when the key is invalid or taken. */
+declare function setKey(model: DesignerModel, path: PropertyPath, key: string): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Set a choice's options, in order: their values in the schema, their labels as hints. */
+declare function setOptions(model: DesignerModel, path: PropertyPath, options: ChoiceOption[]): DesignerModel;
+/** The result of changing an answer type: the new model, and what it dropped. */
+interface AnswerTypeChange {
+    model: DesignerModel;
+    /** Settings the new type does not take -- a `pattern`, an unknown widget, the options. */
+    lost: string[];
+}
+/**
+ * Change a question's answer type. Its text, help, example and read-only flag
+ * stay; options move from one kind of choice to another. What the new type does
+ * not take is dropped and named in `lost` -- the designer asks before applying.
+ */
+declare function changeAnswerType(model: DesignerModel, path: PropertyPath, type: AnswerType, types?: readonly ValueTypeAnswer[], keep?: readonly string[]): AnswerTypeChange;
+/**
+ * Set keywords the questionnaire designer keeps but does not edit itself -- a
+ * converter's annotations, say -- on an item, or (an empty path) on the
+ * questionnaire; an undefined value removes one.
+ */
+declare function setKeywords(model: DesignerModel, path: PropertyPath, keywords: Record<string, unknown>): DesignerModel;
+/**
+ * Set whether a section repeats -- a list of entries, each with the section's
+ * items. Its items keep their paths: the list's entries are its container.
+ */
+declare function setSectionRepeats(model: DesignerModel, path: PropertyPath, repeats: boolean): DesignerModel;
+/** Set one of a question's limits -- its length, pattern, range or count; undefined or empty removes it. */
+declare function setLimit(model: DesignerModel, path: PropertyPath, keyword: LimitKeyword, value: number | string | undefined): DesignerModel;
+/** Set the questionnaire's own title or introduction (the root's title and description). */
+declare function setQuestionnaireText(model: DesignerModel, text: {
+    title?: string;
+    description?: string;
+}): DesignerModel;
+/** The path of the section an item is in -- the same for its conditional siblings. */
+declare function sectionPathOf(path: PropertyPath): PropertyPath;
+/**
+ * Show an item only if conditions hold, or (null) always. The item keeps its
+ * key, its place in the section's order and its hints; it moves into a
+ * conditional of its own -- or back among the section's properties.
+ */
+declare function setShowIf(model: DesignerModel, path: PropertyPath, showIf: ShowIf | null): {
+    model: DesignerModel;
+    path: PropertyPath;
+};
+/** Move an item up (-1) or down (+1) among its section's items -- conditional ones included. */
+declare function moveItem(model: DesignerModel, path: PropertyPath, direction: -1 | 1): DesignerModel;
+/** Put an item before another of its section (by key), or last (null) -- dragging it there. */
+declare function reorderItem(model: DesignerModel, path: PropertyPath, beforeKey: string | null): DesignerModel;
+/** Delete an item: its definition, its hints, its place in the order -- and its conditional, once empty. */
+declare function deleteItem(model: DesignerModel, path: PropertyPath): DesignerModel;
+/**
+ * Set a value type's settings on its question -- the quantity's units -- as its
+ * contribution writes them: keywords beside the `$ref`, `x-ui-options` keys.
+ */
+declare function setValueTypeSettings(model: DesignerModel, path: PropertyPath, answer: ValueTypeAnswer, values: Record<string, unknown>): DesignerModel;
+/** The option a choice with text's "other" variant adds when its options have none. */
+declare const OTHER_OPTION: {
+    value: string;
+    label: string;
+};
+/**
+ * Set what a choice with text's text is: a note, always offered (null), or
+ * asked for only when the choice is one option -- "other, please describe" --
+ * and then required. Switching to the latter adds an "other" option when the
+ * choice has none; the text keeps its definition either way.
+ */
+declare function setChoiceTextWhen(model: DesignerModel, path: PropertyPath, when: string | null): DesignerModel;
+/** The reasons the questionnaire declares (its root's `absent`); none: every question is answered. */
+declare function declaredReasons(model: DesignerModel): ChoiceOption[] | undefined;
+/**
+ * Set whether a question must be answered. With reasons declared, an always
+ * asked question is required unless a reason is given for it; a conditional
+ * one, and any question without reasons, is plainly required.
+ */
+declare function setQuestionRequired(model: DesignerModel, path: PropertyPath, required: boolean): DesignerModel;
+/**
+ * Declare the reasons a question may be left unanswered for -- or none (null),
+ * so every question is answered. Every section gets (or loses) its `absent`,
+ * and its required questions become required unless a reason is given (or
+ * plainly required again).
+ */
+declare function setReasons(model: DesignerModel, reasons: ChoiceOption[] | null): DesignerModel;
+
+/**
+ * Reasons for no answer -- *unknown*, *not applicable*: a statement about a
+ * question instead of its answer. Pure, no React.
+ *
+ * A questionnaire declares its reasons once; every section then carries them
+ * in its own `absent` property, an object of question keys whose values are
+ * the declared reasons, so an answer keeps its type and a reason sits beside
+ * it. A required question is required *unless* the section's `absent` names
+ * it -- one conditional per question, `{ if: { not: <absent names it> }, then:
+ * { required: [key] } }` -- so the form asks for an answer or a reason, and
+ * the renderer enforces it. See docs/design/questionnaires.md, "Reasons for no
+ * answer".
+ */
+
+/** The property of a section that holds its reasons. */
+declare const ABSENT_KEY = "absent";
+/** The widget a section's reasons are entered with. */
+declare const ABSENT_WIDGET = "absent-reasons";
+/** The `absent` property of a section: question keys to one of the reasons. */
+declare function absentProperty(reasons: ChoiceOption[]): JsonSchemaProperty;
+/** The reasons an `absent` property declares; none when the property is not of that shape. */
+declare function readReasons(prop: JsonSchemaProperty | undefined): ChoiceOption[] | undefined;
+/** The conditional that makes a question required unless a reason is given for it. */
+declare function unlessReasonMember(key: string): JsonSchemaProperty;
+/** The question an "unless a reason" conditional makes required; none for another member. */
+declare function unlessReasonKey(member: JsonSchemaProperty): string | undefined;
+/** The answers of one section: its values, and its reasons in `absent`. */
+type SectionAnswers = Record<string, unknown> & {
+    [ABSENT_KEY]?: Record<string, string>;
+};
+/** Whether a question has an answer or a reason in its section's answers. */
+declare function answeredOrExcused(answers: SectionAnswers | undefined, key: string): boolean;
+
+/**
+ * Completion -- whether a set of answers is complete: every question asked has
+ * an answer or a reason for none. A question shown only if conditions hold is
+ * asked while they hold. Distinct from `required`, which says an answer must
+ * be given. Pure, no React. See docs/design/questionnaires.md, "Reasons for no
+ * answer".
+ */
+
+type Answers = Record<string, unknown>;
+/** Whether the answers are complete, and the questions that still lack an answer or a reason. */
+interface Completion {
+    complete: boolean;
+    /** The missing questions, by key path (`company.vat_id`; a repeating section's entry by index). */
+    missing: string[];
+}
+/** Whether an item is asked, given its section's answers: always, or while its show-if holds. */
+declare function isAsked(showIf: ShowIf | undefined, answers: Answers): boolean;
+/** Whether a set of answers is complete: every question asked has an answer or a reason. */
+declare function isComplete(view: QuestionnaireView, answers: Answers): Completion;
+
+/**
+ * QuestionnaireDesigner capabilities -- a profile that limits what an author
+ * may build. As the schema designer's (../capabilities.ts): the Zod schema is
+ * the single source, every field optional and defaulting to the most
+ * permissive value, so adding a capability never tightens a profile already
+ * written. A profile limits authoring; it never hides what a schema holds --
+ * a question of a type the profile does not offer is still shown and edited.
+ */
+
+declare const questionnaireCapabilitiesSchema: z.ZodObject<{
+    answerTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sections: z.ZodDefault<z.ZodBoolean>;
+    logic: z.ZodDefault<z.ZodBoolean>;
+    reasons: z.ZodDefault<z.ZodBoolean>;
+    switchToDesigner: z.ZodDefault<z.ZodBoolean>;
+    previews: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        form: "form";
+        json: "json";
+        capabilities: "capabilities";
+    }>>>;
+}, z.core.$strip>;
+type QuestionnaireDesignerCapabilities = z.input<typeof questionnaireCapabilitiesSchema>;
+/** The resolved profile: every field set, the answer types listed. */
+type ResolvedQuestionnaireCapabilities = Required<z.output<typeof questionnaireCapabilitiesSchema>>;
+/** A profile checked: its value, or what is wrong with it, by path. */
+declare function validateQuestionnaireCapabilities(input: unknown): {
+    ok: true;
+    value: QuestionnaireDesignerCapabilities;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Resolve a profile: defaults applied; an invalid one warns and falls back to the defaults. */
+declare function resolveQuestionnaireCapabilities(capabilities: QuestionnaireDesignerCapabilities | undefined, valueTypes?: readonly ValueTypeAnswer[]): ResolvedQuestionnaireCapabilities;
+
+export { addLayoutGroup as $, ABSENT_KEY as A, LIMIT_LABELS as L, absentProperty as M, OTHER_OPTION as O, addBranch as W, addConditional as X, addDefinition as Y, addElse as Z, addItem as _, renameProperty as a$, addProperty as a0, answerTypeFragment as a1, answerTypeLabel as a2, answeredOrExcused as a3, branch as a4, changeAnswerType as a5, changePropertyType as a6, childContainer as a7, childSlots as a8, choiceTextWhen as a9, moveBranch as aA, moveItem as aB, moveLayoutGroup as aC, moveProperty as aD, newBranch as aE, newCondition as aF, newProperty as aG, optionsOf as aH, otherTextMember as aI, parsePathKey as aJ, pathKey as aK, placeFieldInGroup as aL, prop as aM, questionnaireCapabilitiesSchema as aN, rawChoiceAndText as aO, readConditional as aP, readEnumChoices as aQ, readReasons as aR, readTableHints as aS, recognizeAnswerType as aT, removeBranch as aU, removeConditional as aV, removeDefinition as aW, removeElse as aX, removeLayoutGroup as aY, renameDefinition as aZ, renameLayoutGroup as a_, classifyQuestionnaire as aa, codingBindingOf as ab, condition as ac, containerFields as ad, containerOrder as ae, declaredReasons as af, def as ag, definitionUsageCount as ah, definitionsOf as ai, deleteItem as aj, deleteProperty as ak, embeddedHints as al, getProperty as am, getScopedLayout as an, getUiEntryAtPath as ao, isAsked as ap, isBuiltinAnswerType as aq, isComplete as ar, isContainer as as, isContainerType as at, isReservedKey as au, isValidKey as av, itemsOf as aw, keyFromText as ax, limitsFor as ay, limitsOf as az, ABSENT_WIDGET as b, reorderItem as b0, resolveQuestionnaireCapabilities as b1, samePath as b2, sameSegment as b3, schemaAsRootProp as b4, sectionPathOf as b5, setChoiceTextWhen as b6, setCondition as b7, setConditionalBehavior as b8, setDefaultAnswer as b9, setSectionRepeats as bA, setShowIf as bB, setTableHints as bC, setUiEntry as bD, setValueTypeSettings as bE, showIfToIf as bF, slot as bG, unlessReasonKey as bH, unlessReasonMember as bI, updateProperty as bJ, validateQuestionnaireCapabilities as bK, valueTypeAnswer as bL, valueTypeOf as bM, setEnum as ba, setGlobalOptions as bb, setHelp as bc, setItemText as bd, setKey as be, setKeywords as bf, setLayoutGroupRule as bg, setLimit as bh, setOptions as bi, setPlaceholder as bj, setPresentation as bk, setPropertyLayout as bl, setQuestionRequired as bm, setQuestionnaireText as bn, setReadOnly as bo, setReasons as bp, setReference as bq, setRequired as br, setRootLayout as bs, setRootLayoutRows as bt, setScopedGroupRows as bu, setScopedLayoutGroups as bv, setScopedLayoutMode as bw, setScopedLayoutOptions as bx, setScopedLayoutRows as by, setScopedLayoutVariant as bz, ANSWER_TYPE_LABELS as c, ANSWER_TYPE_LIMITS as d, CHOICE_WITH_TEXT_WIDGET as h, CODEABLE_CONCEPT_ANSWER as i, CODING_ANSWER as j, DEFAULT_VALUE_TYPES as p, QUANTITY_ANSWER as w };
+export type { BuiltinAnswerType as B, ConditionCombinator as C, DesignerModel as D, EnumChoice as E, FieldType as F, ResolvedQuestionnaireCapabilities as G, SectionItem as H, ShowIf as I, TextItem as J, ValueTypeSettings as K, NewPropertyKind as N, PropertyPath as P, QuestionnaireDesignerCapabilities as Q, RecognizedAnswer as R, SlotKind as S, TableHints as T, UiSchemaMap as U, ValueTypeAnswer as V, PropertyTypeChoice as a, AnswerFragment as e, AnswerType as f, AnswerTypeChange as g, ChildSlot as k, ChoiceOption as l, Completion as m, Condition as n, ConditionalItems as o, LimitKeyword as q, Limits as r, LockedItem as s, NewItem as t, PathSegment as u, PathSlot as v, QuestionItem as x, QuestionnaireItem as y, QuestionnaireView as z };