@particle-academy/react-fancy 5.14.0 → 5.16.0

package/dist/index-BfFk-CIv.d.ts

@@ -0,0 +1,330 @@
+import * as react from 'react';
+import { HTMLAttributes } from 'react';
+import { F as FieldMode, b as InputOption } from './inputs.types-DERzxpe1.js';
+import { S as Size } from './types-8Sv0rCjw.js';
+
+type JsonPrimitive = string | number | boolean | null;
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+type JsonArray = JsonValue[];
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * A location inside a JSON document, one array element per segment. Array
+ * indices are decimal STRINGS (`["orders", "0", "total"]`) so a path is a plain
+ * `string[]` an agent can emit without a tagged union, and so object keys and
+ * array indices are addressed identically.
+ *
+ * The wire form is the dotted string produced by `pathToString` — see
+ * `JsonEditor.paths.ts` for the escaping rule.
+ */
+type JsonPath = string[];
+/**
+ * The data types a `keyMap` can impose on a JSON value.
+ *
+ * Each one owes BOTH a read-only representation and an edit control — that
+ * pairing is the whole point of the feature, so a type with no distinct input
+ * does not earn a place here.
+ *
+ * `json` is the escape hatch: it matches any value and edits as raw text, which
+ * is how a sub-document opts out of the row-per-key treatment.
+ */
+declare const JSON_FIELD_TYPES: readonly ["string", "text", "number", "integer", "boolean", "date", "datetime", "enum", "secret", "url", "email", "color", "json", "object", "array"];
+type JsonFieldType = (typeof JSON_FIELD_TYPES)[number];
+/**
+ * The long form of a `keyMap` entry. The short form — a bare type name — is
+ * sugar for `{ type }`.
+ */
+interface JsonKeyRule {
+    type: JsonFieldType;
+    /** Overrides the raw key as the row's label. */
+    label?: string;
+    /** Choices for `type: "enum"`. Required there; ignored elsewhere. */
+    options?: InputOption[];
+    /** Render the value but never offer a control for it. */
+    readOnly?: boolean;
+    /** The key must be present. Only enforced on wildcard-free patterns. */
+    required?: boolean;
+    description?: string;
+    placeholder?: string;
+    /** Forwarded to the control for `number` / `integer` / `date` / `datetime`. */
+    min?: number | string;
+    max?: number | string;
+}
+/** One compiled `keyMap` entry: a path pattern plus the rule it imposes. */
+interface JsonKeyMapEntry {
+    /** Path pattern; a `"*"` segment matches any single key or index. */
+    pattern: JsonPath;
+    rule: JsonKeyRule;
+    /** The key exactly as written in the `keyMap`, for error messages. */
+    source: string;
+    /** Non-wildcard segment count — the specificity score. */
+    literals: number;
+    /** Declaration order, the tie-breaker at equal specificity. */
+    order: number;
+}
+interface ParsedKeyMap {
+    /**
+     * `false` only when the STRING itself was unusable (unparseable, or valid
+     * JSON of the wrong shape). Individual bad rules leave this `true` — they are
+     * reported and skipped so one typo cannot silently disable a whole map.
+     */
+    ok: boolean;
+    rules: JsonKeyMapEntry[];
+    issues: JsonEditorIssue[];
+}
+/**
+ * Everything the editor knows to be wrong, in one shape.
+ *
+ * A typing feature that silently stops typing things is worse than no typing at
+ * all, because the caller believes the constraint is in force. So a broken
+ * `keyMap`, a broken rule inside a working one, and a value that contradicts
+ * its declared type all surface through the SAME channel — the panel, the
+ * `data-issues` count, and `onIssuesChange`.
+ */
+interface JsonEditorIssue {
+    /**
+     * - `keymap` — the `keyMap` string could not be used at all.
+     * - `rule`   — one entry in an otherwise-usable map is malformed.
+     * - `type`   — a value contradicts the type declared for its path.
+     * - `edit`   — a structural edit was refused (duplicate key, and the like).
+     */
+    kind: "keymap" | "rule" | "type" | "edit";
+    /** Dotted path; `""` for the `keyMap` as a whole. */
+    path: string;
+    message: string;
+    /** The declared type, when the issue has one. */
+    expected?: JsonFieldType;
+    /** What the value actually is: `"string"`, `"array"`, `"null"`, … */
+    actual?: string;
+}
+/**
+ * One mutation, as data.
+ *
+ * Every change the UI makes is expressed as one of these and applied through
+ * `applyJsonEdit`, which means an MCP bridge can replay exactly what a human
+ * did — and `pendingMode` can hold one in a queue instead of applying it —
+ * without a second code path.
+ */
+type JsonEditorEditBase = {
+    id?: string;
+    /** Human-readable summary, used by the pending strip. */
+    label?: string;
+};
+type JsonEditorEdit = (JsonEditorEditBase & {
+    op: "set";
+    path: string;
+    value: JsonValue;
+}) | (JsonEditorEditBase & {
+    op: "remove";
+    path: string;
+}) | (JsonEditorEditBase & {
+    op: "rename";
+    path: string;
+    key: string;
+})
+/** `path` is the CONTAINER. `key` is required for an object, ignored for an array. */
+ | (JsonEditorEditBase & {
+    op: "insert";
+    path: string;
+    key?: string;
+    value: JsonValue;
+})
+/** `path` is the element; `to` is its new index in the same array. */
+ | (JsonEditorEditBase & {
+    op: "move";
+    path: string;
+    to: number;
+});
+type JsonEditorPendingEdit = JsonEditorEdit & {
+    id: string;
+};
+interface JsonEditorActivity {
+    /** `commit` — applied to the document. `stage` / `accept` / `reject` — pending flow. */
+    type: "commit" | "stage" | "accept" | "reject";
+    edit: JsonEditorEdit;
+}
+/** One rendered key/value row — also the unit a bridge would address. */
+interface JsonEditorNode {
+    path: JsonPath;
+    /** `pathToString(path)`; `""` for a scalar root. */
+    dotted: string;
+    /** The last segment: an object key or an array index. */
+    key: string;
+    depth: number;
+    value: JsonValue;
+    parentKind: "object" | "array" | "root";
+    /** The rule that matched, if any. */
+    rule?: JsonKeyRule;
+    /** Declared type if a rule matched, otherwise inferred from the value. */
+    type: JsonFieldType;
+    declared: boolean;
+    /** Renders as a collapsible branch rather than a value. */
+    container: boolean;
+    childCount: number;
+    /** Set when the value contradicts its declared type. */
+    conflict?: JsonEditorIssue;
+}
+interface JsonEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** The document. Controlled — the editor keeps no copy of it. */
+    value: JsonValue;
+    /**
+     * Called with the WHOLE next document plus the edit that produced it. The
+     * edit is what a bridge would log, replay, or undo.
+     */
+    onChange?: (value: JsonValue, edit: JsonEditorEdit) => void;
+    /**
+     * Type declarations, as a **JSON string** — not an object, and an object is
+     * NOT accepted as a convenience overload.
+     *
+     * A string survives every boundary this prop actually crosses: an MCP tool
+     * argument, a config column, a `data-*` attribute, a form field. A live
+     * object survives none of them, so accepting both would make the documented
+     * form the second-class one in practice.
+     *
+     * ```jsonc
+     * {
+     *   "user.age":       "number",           // short form: a bare type name
+     *   "tags.*":         "string",           // every element of an array
+     *   "orders.*.total": "number",
+     *   "role": { "type": "enum", "options": ["admin", "member"] }
+     * }
+     * ```
+     *
+     * Malformed input is never thrown and never silently ignored — see
+     * {@link JsonEditorIssue}.
+     */
+    keyMap?: string | null;
+    /**
+     * `"view"` (the default here) renders values as text that turns into the
+     * typed control when clicked; `"edit"` renders every control at once.
+     *
+     * The kit default is `"edit"`, and this component deliberately differs: a
+     * forty-key document drawn as forty boxed inputs is not a document you can
+     * read, and reading is most of what a JSON editor is for.
+     */
+    mode?: FieldMode;
+    size?: Size;
+    /** Show every value, offer no control. Overrides `mode` and every `allow*`. */
+    readOnly?: boolean;
+    /**
+     * Dotted paths of the expanded containers. Omit BOTH this and
+     * `defaultExpanded` to expand everything (pass `defaultExpanded={[]}` for a
+     * large document).
+     */
+    expanded?: string[];
+    defaultExpanded?: string[];
+    onExpandedChange?: (expanded: string[]) => void;
+    /** Render the issues panel. The `data-issues` count and `onIssuesChange` are unaffected. */
+    showIssues?: boolean;
+    onIssuesChange?: (issues: JsonEditorIssue[]) => void;
+    /**
+     * Trust-but-verify. With this on, an edit is STAGED into `pending` instead of
+     * being applied: `onChange` does not fire until a human accepts it.
+     */
+    pendingMode?: boolean;
+    /** Staged edits. Controlled, so an agent's proposals are inspectable. */
+    pending?: JsonEditorPendingEdit[];
+    onPendingChange?: (pending: JsonEditorPendingEdit[]) => void;
+    /** Every mutation, staged or applied — the hook presence / undo layers listen on. */
+    onActivity?: (event: JsonEditorActivity) => void;
+    allowAdd?: boolean;
+    allowRemove?: boolean;
+    allowRename?: boolean;
+    allowReorder?: boolean;
+    /** Label for a scalar root document. Default `"value"`. */
+    rootLabel?: string;
+    /** Shown when the document has no keys. */
+    emptyLabel?: string;
+    /** Prefix for generated control ids — `<idPrefix>-<dotted path>`. */
+    idPrefix?: string;
+}
+
+/**
+ * JsonEditor — a key/value editor over arbitrary, arbitrarily-nested JSON, with
+ * a caller-supplied `keyMap` imposing a data type on any path.
+ *
+ * The type does two jobs at once, which is the point of the feature: it decides
+ * how a value is RENDERED when you are reading, and which control appears when
+ * you are editing. `{"user.age": "number"}` is not documentation — it is the
+ * reason that row is a numeric field and the reason `"thirty-six"` shows up in
+ * red instead of quietly becoming `0`.
+ *
+ * The three design decisions worth knowing before you use it:
+ *
+ *  - **`keyMap` is a JSON string, and only a string.** It has to survive an MCP
+ *    tool argument, a config column and a `data-*` attribute; a live object
+ *    survives none of those. See {@link JsonEditorProps.keyMap}.
+ *  - **Nothing is coerced and nothing is dropped.** A value that contradicts
+ *    its declared type keeps its real value, renders through the raw editor,
+ *    and is reported through the issues panel, the `data-issues` count and
+ *    `onIssuesChange` — the same channel a broken `keyMap` uses.
+ *  - **It is controlled, all the way down.** The document lives in `value`.
+ *    The only state here is which rows are expanded, which add-form is open,
+ *    and the half-typed text inside a control that has not committed yet.
+ *
+ * Every control is a `react-fancy` primitive, so restyling the kit restyles
+ * this, and `mode="view"` gets the kit's click-to-edit behaviour for free.
+ */
+declare const JsonEditor: react.ForwardRefExoticComponent<JsonEditorProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Compile a `keyMap` JSON **string**.
+ *
+ * Never throws. Two failure modes, deliberately distinct:
+ *
+ *  - The string itself is unusable (not JSON, or JSON that is not an object) —
+ *    `ok: false`, no rules, one `keymap` issue. The caller must show this: an
+ *    editor that quietly runs untyped is worse than one that refuses, because
+ *    the person editing believes the constraint is in force.
+ *  - One entry is malformed — `ok: true`, that entry dropped, one `rule` issue.
+ *    A typo in `orders.*.totl` must not disable the other forty rules.
+ */
+declare function parseKeyMap(source?: string | null): ParsedKeyMap;
+/**
+ * The rule governing `segments`, or `undefined` when the map is silent.
+ *
+ * Specificity: the pattern with the most literal (non-`*`) segments wins, and
+ * at equal specificity the one declared LAST wins — so a general
+ * `orders.*.total` can be overridden by a specific `orders.0.total` placed
+ * anywhere in the map.
+ */
+declare function resolveKeyRule(rules: JsonKeyMapEntry[], segments: JsonPath): JsonKeyRule | undefined;
+/** The type a value carries on its own, when nothing declares one for it. */
+declare function inferType(value: JsonValue | undefined): JsonFieldType;
+/**
+ * Does the value satisfy the declared type?
+ *
+ * Deliberately strict and deliberately non-coercing. `"36"` is NOT a number
+ * here — the whole reason a `keyMap` exists is to make that visible rather than
+ * to paper over it.
+ */
+declare function typeMatches(rule: JsonKeyRule, value: JsonValue | undefined): boolean;
+/**
+ * Every place the document contradicts its `keyMap`.
+ *
+ * Walks the value (so a conflict is found at any depth, arrays included), then
+ * checks `required` on the wildcard-free patterns — a wildcard cannot say "this
+ * must exist" about a key nobody has named.
+ */
+declare function findJsonConflicts(value: JsonValue, rules: JsonKeyMapEntry[]): JsonEditorIssue[];
+
+/** Split a dotted path into segments, honouring `\.` and `\\`. */
+declare function parsePath(path: string): JsonPath;
+/** The inverse of {@link parsePath}. */
+declare function pathToString(segments: JsonPath): string;
+declare function getAtPath(value: JsonValue, segments: JsonPath): JsonValue | undefined;
+/**
+ * Apply one {@link JsonEditorEdit} and return a NEW document.
+ *
+ * Pure and total: an edit that cannot be applied — a path that does not exist,
+ * a rename onto an occupied key, an insert without a key into an object —
+ * returns the input unchanged rather than throwing or half-applying. The
+ * component checks those cases first and raises an issue; this function is the
+ * backstop for the same op arriving from a bridge, where there is no UI to warn.
+ */
+declare function applyJsonEdit(value: JsonValue, edit: JsonEditorEdit): JsonValue;
+/** A one-line summary of an edit, for the pending strip and activity events. */
+declare function describeEdit(edit: JsonEditorEdit): string;
+
+export { JSON_FIELD_TYPES as J, type ParsedKeyMap as P, type JsonArray as a, JsonEditor as b, type JsonEditorActivity as c, type JsonEditorEdit as d, type JsonEditorIssue as e, type JsonEditorNode as f, type JsonEditorPendingEdit as g, type JsonEditorProps as h, type JsonFieldType as i, type JsonKeyMapEntry as j, type JsonKeyRule as k, type JsonObject as l, type JsonPath as m, type JsonPrimitive as n, type JsonValue as o, applyJsonEdit as p, describeEdit as q, findJsonConflicts as r, getAtPath as s, inferType as t, parseKeyMap as u, parsePath as v, pathToString as w, resolveKeyRule as x, typeMatches as y };

package/dist/index-BypPN_6l.d.cts

@@ -0,0 +1,330 @@
+import * as react from 'react';
+import { HTMLAttributes } from 'react';
+import { F as FieldMode, b as InputOption } from './inputs.types-CkWdvN-t.cjs';
+import { S as Size } from './types-8Sv0rCjw.cjs';
+
+type JsonPrimitive = string | number | boolean | null;
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+type JsonArray = JsonValue[];
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * A location inside a JSON document, one array element per segment. Array
+ * indices are decimal STRINGS (`["orders", "0", "total"]`) so a path is a plain
+ * `string[]` an agent can emit without a tagged union, and so object keys and
+ * array indices are addressed identically.
+ *
+ * The wire form is the dotted string produced by `pathToString` — see
+ * `JsonEditor.paths.ts` for the escaping rule.
+ */
+type JsonPath = string[];
+/**
+ * The data types a `keyMap` can impose on a JSON value.
+ *
+ * Each one owes BOTH a read-only representation and an edit control — that
+ * pairing is the whole point of the feature, so a type with no distinct input
+ * does not earn a place here.
+ *
+ * `json` is the escape hatch: it matches any value and edits as raw text, which
+ * is how a sub-document opts out of the row-per-key treatment.
+ */
+declare const JSON_FIELD_TYPES: readonly ["string", "text", "number", "integer", "boolean", "date", "datetime", "enum", "secret", "url", "email", "color", "json", "object", "array"];
+type JsonFieldType = (typeof JSON_FIELD_TYPES)[number];
+/**
+ * The long form of a `keyMap` entry. The short form — a bare type name — is
+ * sugar for `{ type }`.
+ */
+interface JsonKeyRule {
+    type: JsonFieldType;
+    /** Overrides the raw key as the row's label. */
+    label?: string;
+    /** Choices for `type: "enum"`. Required there; ignored elsewhere. */
+    options?: InputOption[];
+    /** Render the value but never offer a control for it. */
+    readOnly?: boolean;
+    /** The key must be present. Only enforced on wildcard-free patterns. */
+    required?: boolean;
+    description?: string;
+    placeholder?: string;
+    /** Forwarded to the control for `number` / `integer` / `date` / `datetime`. */
+    min?: number | string;
+    max?: number | string;
+}
+/** One compiled `keyMap` entry: a path pattern plus the rule it imposes. */
+interface JsonKeyMapEntry {
+    /** Path pattern; a `"*"` segment matches any single key or index. */
+    pattern: JsonPath;
+    rule: JsonKeyRule;
+    /** The key exactly as written in the `keyMap`, for error messages. */
+    source: string;
+    /** Non-wildcard segment count — the specificity score. */
+    literals: number;
+    /** Declaration order, the tie-breaker at equal specificity. */
+    order: number;
+}
+interface ParsedKeyMap {
+    /**
+     * `false` only when the STRING itself was unusable (unparseable, or valid
+     * JSON of the wrong shape). Individual bad rules leave this `true` — they are
+     * reported and skipped so one typo cannot silently disable a whole map.
+     */
+    ok: boolean;
+    rules: JsonKeyMapEntry[];
+    issues: JsonEditorIssue[];
+}
+/**
+ * Everything the editor knows to be wrong, in one shape.
+ *
+ * A typing feature that silently stops typing things is worse than no typing at
+ * all, because the caller believes the constraint is in force. So a broken
+ * `keyMap`, a broken rule inside a working one, and a value that contradicts
+ * its declared type all surface through the SAME channel — the panel, the
+ * `data-issues` count, and `onIssuesChange`.
+ */
+interface JsonEditorIssue {
+    /**
+     * - `keymap` — the `keyMap` string could not be used at all.
+     * - `rule`   — one entry in an otherwise-usable map is malformed.
+     * - `type`   — a value contradicts the type declared for its path.
+     * - `edit`   — a structural edit was refused (duplicate key, and the like).
+     */
+    kind: "keymap" | "rule" | "type" | "edit";
+    /** Dotted path; `""` for the `keyMap` as a whole. */
+    path: string;
+    message: string;
+    /** The declared type, when the issue has one. */
+    expected?: JsonFieldType;
+    /** What the value actually is: `"string"`, `"array"`, `"null"`, … */
+    actual?: string;
+}
+/**
+ * One mutation, as data.
+ *
+ * Every change the UI makes is expressed as one of these and applied through
+ * `applyJsonEdit`, which means an MCP bridge can replay exactly what a human
+ * did — and `pendingMode` can hold one in a queue instead of applying it —
+ * without a second code path.
+ */
+type JsonEditorEditBase = {
+    id?: string;
+    /** Human-readable summary, used by the pending strip. */
+    label?: string;
+};
+type JsonEditorEdit = (JsonEditorEditBase & {
+    op: "set";
+    path: string;
+    value: JsonValue;
+}) | (JsonEditorEditBase & {
+    op: "remove";
+    path: string;
+}) | (JsonEditorEditBase & {
+    op: "rename";
+    path: string;
+    key: string;
+})
+/** `path` is the CONTAINER. `key` is required for an object, ignored for an array. */
+ | (JsonEditorEditBase & {
+    op: "insert";
+    path: string;
+    key?: string;
+    value: JsonValue;
+})
+/** `path` is the element; `to` is its new index in the same array. */
+ | (JsonEditorEditBase & {
+    op: "move";
+    path: string;
+    to: number;
+});
+type JsonEditorPendingEdit = JsonEditorEdit & {
+    id: string;
+};
+interface JsonEditorActivity {
+    /** `commit` — applied to the document. `stage` / `accept` / `reject` — pending flow. */
+    type: "commit" | "stage" | "accept" | "reject";
+    edit: JsonEditorEdit;
+}
+/** One rendered key/value row — also the unit a bridge would address. */
+interface JsonEditorNode {
+    path: JsonPath;
+    /** `pathToString(path)`; `""` for a scalar root. */
+    dotted: string;
+    /** The last segment: an object key or an array index. */
+    key: string;
+    depth: number;
+    value: JsonValue;
+    parentKind: "object" | "array" | "root";
+    /** The rule that matched, if any. */
+    rule?: JsonKeyRule;
+    /** Declared type if a rule matched, otherwise inferred from the value. */
+    type: JsonFieldType;
+    declared: boolean;
+    /** Renders as a collapsible branch rather than a value. */
+    container: boolean;
+    childCount: number;
+    /** Set when the value contradicts its declared type. */
+    conflict?: JsonEditorIssue;
+}
+interface JsonEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** The document. Controlled — the editor keeps no copy of it. */
+    value: JsonValue;
+    /**
+     * Called with the WHOLE next document plus the edit that produced it. The
+     * edit is what a bridge would log, replay, or undo.
+     */
+    onChange?: (value: JsonValue, edit: JsonEditorEdit) => void;
+    /**
+     * Type declarations, as a **JSON string** — not an object, and an object is
+     * NOT accepted as a convenience overload.
+     *
+     * A string survives every boundary this prop actually crosses: an MCP tool
+     * argument, a config column, a `data-*` attribute, a form field. A live
+     * object survives none of them, so accepting both would make the documented
+     * form the second-class one in practice.
+     *
+     * ```jsonc
+     * {
+     *   "user.age":       "number",           // short form: a bare type name
+     *   "tags.*":         "string",           // every element of an array
+     *   "orders.*.total": "number",
+     *   "role": { "type": "enum", "options": ["admin", "member"] }
+     * }
+     * ```
+     *
+     * Malformed input is never thrown and never silently ignored — see
+     * {@link JsonEditorIssue}.
+     */
+    keyMap?: string | null;
+    /**
+     * `"view"` (the default here) renders values as text that turns into the
+     * typed control when clicked; `"edit"` renders every control at once.
+     *
+     * The kit default is `"edit"`, and this component deliberately differs: a
+     * forty-key document drawn as forty boxed inputs is not a document you can
+     * read, and reading is most of what a JSON editor is for.
+     */
+    mode?: FieldMode;
+    size?: Size;
+    /** Show every value, offer no control. Overrides `mode` and every `allow*`. */
+    readOnly?: boolean;
+    /**
+     * Dotted paths of the expanded containers. Omit BOTH this and
+     * `defaultExpanded` to expand everything (pass `defaultExpanded={[]}` for a
+     * large document).
+     */
+    expanded?: string[];
+    defaultExpanded?: string[];
+    onExpandedChange?: (expanded: string[]) => void;
+    /** Render the issues panel. The `data-issues` count and `onIssuesChange` are unaffected. */
+    showIssues?: boolean;
+    onIssuesChange?: (issues: JsonEditorIssue[]) => void;
+    /**
+     * Trust-but-verify. With this on, an edit is STAGED into `pending` instead of
+     * being applied: `onChange` does not fire until a human accepts it.
+     */
+    pendingMode?: boolean;
+    /** Staged edits. Controlled, so an agent's proposals are inspectable. */
+    pending?: JsonEditorPendingEdit[];
+    onPendingChange?: (pending: JsonEditorPendingEdit[]) => void;
+    /** Every mutation, staged or applied — the hook presence / undo layers listen on. */
+    onActivity?: (event: JsonEditorActivity) => void;
+    allowAdd?: boolean;
+    allowRemove?: boolean;
+    allowRename?: boolean;
+    allowReorder?: boolean;
+    /** Label for a scalar root document. Default `"value"`. */
+    rootLabel?: string;
+    /** Shown when the document has no keys. */
+    emptyLabel?: string;
+    /** Prefix for generated control ids — `<idPrefix>-<dotted path>`. */
+    idPrefix?: string;
+}
+
+/**
+ * JsonEditor — a key/value editor over arbitrary, arbitrarily-nested JSON, with
+ * a caller-supplied `keyMap` imposing a data type on any path.
+ *
+ * The type does two jobs at once, which is the point of the feature: it decides
+ * how a value is RENDERED when you are reading, and which control appears when
+ * you are editing. `{"user.age": "number"}` is not documentation — it is the
+ * reason that row is a numeric field and the reason `"thirty-six"` shows up in
+ * red instead of quietly becoming `0`.
+ *
+ * The three design decisions worth knowing before you use it:
+ *
+ *  - **`keyMap` is a JSON string, and only a string.** It has to survive an MCP
+ *    tool argument, a config column and a `data-*` attribute; a live object
+ *    survives none of those. See {@link JsonEditorProps.keyMap}.
+ *  - **Nothing is coerced and nothing is dropped.** A value that contradicts
+ *    its declared type keeps its real value, renders through the raw editor,
+ *    and is reported through the issues panel, the `data-issues` count and
+ *    `onIssuesChange` — the same channel a broken `keyMap` uses.
+ *  - **It is controlled, all the way down.** The document lives in `value`.
+ *    The only state here is which rows are expanded, which add-form is open,
+ *    and the half-typed text inside a control that has not committed yet.
+ *
+ * Every control is a `react-fancy` primitive, so restyling the kit restyles
+ * this, and `mode="view"` gets the kit's click-to-edit behaviour for free.
+ */
+declare const JsonEditor: react.ForwardRefExoticComponent<JsonEditorProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Compile a `keyMap` JSON **string**.
+ *
+ * Never throws. Two failure modes, deliberately distinct:
+ *
+ *  - The string itself is unusable (not JSON, or JSON that is not an object) —
+ *    `ok: false`, no rules, one `keymap` issue. The caller must show this: an
+ *    editor that quietly runs untyped is worse than one that refuses, because
+ *    the person editing believes the constraint is in force.
+ *  - One entry is malformed — `ok: true`, that entry dropped, one `rule` issue.
+ *    A typo in `orders.*.totl` must not disable the other forty rules.
+ */
+declare function parseKeyMap(source?: string | null): ParsedKeyMap;
+/**
+ * The rule governing `segments`, or `undefined` when the map is silent.
+ *
+ * Specificity: the pattern with the most literal (non-`*`) segments wins, and
+ * at equal specificity the one declared LAST wins — so a general
+ * `orders.*.total` can be overridden by a specific `orders.0.total` placed
+ * anywhere in the map.
+ */
+declare function resolveKeyRule(rules: JsonKeyMapEntry[], segments: JsonPath): JsonKeyRule | undefined;
+/** The type a value carries on its own, when nothing declares one for it. */
+declare function inferType(value: JsonValue | undefined): JsonFieldType;
+/**
+ * Does the value satisfy the declared type?
+ *
+ * Deliberately strict and deliberately non-coercing. `"36"` is NOT a number
+ * here — the whole reason a `keyMap` exists is to make that visible rather than
+ * to paper over it.
+ */
+declare function typeMatches(rule: JsonKeyRule, value: JsonValue | undefined): boolean;
+/**
+ * Every place the document contradicts its `keyMap`.
+ *
+ * Walks the value (so a conflict is found at any depth, arrays included), then
+ * checks `required` on the wildcard-free patterns — a wildcard cannot say "this
+ * must exist" about a key nobody has named.
+ */
+declare function findJsonConflicts(value: JsonValue, rules: JsonKeyMapEntry[]): JsonEditorIssue[];
+
+/** Split a dotted path into segments, honouring `\.` and `\\`. */
+declare function parsePath(path: string): JsonPath;
+/** The inverse of {@link parsePath}. */
+declare function pathToString(segments: JsonPath): string;
+declare function getAtPath(value: JsonValue, segments: JsonPath): JsonValue | undefined;
+/**
+ * Apply one {@link JsonEditorEdit} and return a NEW document.
+ *
+ * Pure and total: an edit that cannot be applied — a path that does not exist,
+ * a rename onto an occupied key, an insert without a key into an object —
+ * returns the input unchanged rather than throwing or half-applying. The
+ * component checks those cases first and raises an issue; this function is the
+ * backstop for the same op arriving from a bridge, where there is no UI to warn.
+ */
+declare function applyJsonEdit(value: JsonValue, edit: JsonEditorEdit): JsonValue;
+/** A one-line summary of an edit, for the pending strip and activity events. */
+declare function describeEdit(edit: JsonEditorEdit): string;
+
+export { JSON_FIELD_TYPES as J, type ParsedKeyMap as P, type JsonArray as a, JsonEditor as b, type JsonEditorActivity as c, type JsonEditorEdit as d, type JsonEditorIssue as e, type JsonEditorNode as f, type JsonEditorPendingEdit as g, type JsonEditorProps as h, type JsonFieldType as i, type JsonKeyMapEntry as j, type JsonKeyRule as k, type JsonObject as l, type JsonPath as m, type JsonPrimitive as n, type JsonValue as o, applyJsonEdit as p, describeEdit as q, findJsonConflicts as r, getAtPath as s, inferType as t, parseKeyMap as u, parsePath as v, pathToString as w, resolveKeyRule as x, typeMatches as y };