@design-edito/tools 0.5.2 → 0.5.4

package/components/JsonEditor/index.d.ts

@@ -1,10 +1,7 @@
-import { type FunctionComponent } from 'react';
+import { type FunctionComponent, type EventHandler, type ChangeEvent } from 'react';
 import { type ZodType, type core } from 'zod';
 import type { WithClassName } from '../utils/types.js';
-type JsonPrimitive = string | number | boolean | null;
-type JsonValue = JsonPrimitive | JsonValue[] | {
-    [k: string]: JsonValue;
-};
+import type { JsonValue } from './types.js';
 /**
  * Props for the {@link JsonEditor} component.
  *
@@ -14,6 +11,9 @@ type JsonValue = JsonPrimitive | JsonValue[] | {
  * with the list of Zod issues. Not called when no `schema` is provided.
  * @property schema - Optional Zod schema used to validate the value after each change.
  * When provided, validation runs after `onChange` is dispatched.
+ * @property preventSameNameKeys - Refuses a record key rename that would collide
+ * with a sibling key, instead of letting the renamed entry replace it. Applies to
+ * every record in the tree. Defaults to `false`.
  * @property className - Additional class name(s) applied to the root element.
  */
 export type Props = WithClassName<{
@@ -21,6 +21,7 @@ export type Props = WithClassName<{
     onChange?: (val: JsonValue) => void;
     onValidationError?: (issues: core.$ZodIssue[]) => void;
     schema?: ZodType<JsonValue>;
+    preventSameNameKeys?: boolean;
 }>;
 /**
  * Interactive JSON editor component.
@@ -38,22 +39,189 @@ export type Props = WithClassName<{
  *   matching the current value type (`string`, `number`, `boolean`, `null`, `array`, `record`).
  * - `type` — the type selector control.
  * - `string`, `number`, `boolean`, `null` — primitive value inputs.
- * - `record` — record entry list.
- * - `array` — array entry list items.
+ * - `record` — record entry list; `record-item` — one entry of it.
+ * - `array` — array item list; `array-item` — one item of it.
  * - `prop-name` — key input for record entries.
  * - `create-prop` — button to append a new entry to a record or array.
  * - `delete-prop` — button to remove an existing entry.
  * - `lift-prop` — button to move an array entry up.
  * - `drop-prop` — button to move an array entry down.
+ * - `preview` — the serialized JSON preview.
  *
  * @param props - Component properties.
  * @see {@link Props}
  * @returns A recursive JSON value editor with a live serialized preview.
+ *
+ * @remarks
+ * **The editor is uncontrolled, at every level of the tree, and there is no
+ * controlled variant.** Each node seeds its state from its `defaultValue` on
+ * mount and never reads it again, so handing a mounted editor a new
+ * `defaultValue` changes nothing on screen — remount it with a different `key`
+ * to load another document. A controlled mode would mean rebuilding the state
+ * model so the whole tree reads from a single owner, which is why none of these
+ * components accepts a `value` prop.
  */
 export declare const JsonEditor: FunctionComponent<Props>;
-export declare const ValueEditor: FunctionComponent<{
+/**
+ * Props for the {@link ValueEditor} component.
+ *
+ * @property defaultValue - Initial value of this node. Read on mount only.
+ * @property onChange - Called after the node's value changed, with the new value.
+ * @property path - Keys and indices leading to this node from the document root,
+ * exposed on the node as `data-path` and passed down to its children.
+ * @property preventSameNameKeys - Forwarded to every record below this node.
+ * @property className - Additional class name(s) applied to the root element.
+ */
+export type ValueEditorProps = WithClassName<{
     defaultValue?: JsonValue;
     onChange?: (newValue: JsonValue) => void;
     path?: Array<string | number>;
+    preventSameNameKeys?: boolean;
+}>;
+/**
+ * One node of the editor tree: a type selector, plus the editor matching the
+ * value's current type. Switching type replaces the value with an empty one of
+ * the new type.
+ *
+ * @param props - Component properties.
+ * @see {@link ValueEditorProps}
+ * @returns A span holding the type selector and the type-appropriate editor.
+ */
+export declare const ValueEditor: FunctionComponent<ValueEditorProps>;
+/**
+ * Props for the {@link StringEditor} component.
+ *
+ * @property type - Which control to render. Defaults to a single-line `input`.
+ * @property defaultValue - Initial text. Read on mount only.
+ * @property onChange - Native change handler, forwarded to the control.
+ * @property className - Additional class name(s) applied to the control.
+ */
+export type StringEditorProps = WithClassName<{
+    type?: 'input' | 'textarea';
+    defaultValue?: string;
+    onChange?: EventHandler<ChangeEvent<HTMLTextAreaElement | HTMLInputElement>>;
+}>;
+/**
+ * The editor for a string value.
+ *
+ * @param props - Component properties.
+ * @see {@link StringEditorProps}
+ * @returns A textarea or a text input, depending on `type`.
+ */
+export declare const StringEditor: FunctionComponent<StringEditorProps>;
+/**
+ * Props for the {@link NumberEditor} component.
+ *
+ * @property defaultValue - Initial number. Read on mount only.
+ * @property onChange - Native change handler, forwarded to the input.
+ * @property className - Additional class name(s) applied to the input.
+ */
+export type NumberEditorProps = WithClassName<{
+    defaultValue?: number;
+    onChange?: EventHandler<ChangeEvent<HTMLInputElement>>;
+}>;
+/**
+ * The editor for a number value.
+ *
+ * @param props - Component properties.
+ * @see {@link NumberEditorProps}
+ * @returns A number input.
+ */
+export declare const NumberEditor: FunctionComponent<NumberEditorProps>;
+/**
+ * Props for the {@link BooleanEditor} component.
+ *
+ * @property defaultValue - Initial checked state. Read on mount only.
+ * @property onChange - Native change handler, forwarded to the input.
+ * @property className - Additional class name(s) applied to the input.
+ */
+export type BooleanEditorProps = WithClassName<{
+    defaultValue?: boolean;
+    onChange?: EventHandler<ChangeEvent<HTMLInputElement>>;
 }>;
-export {};
+/**
+ * The editor for a boolean value.
+ *
+ * @param props - Component properties.
+ * @see {@link BooleanEditorProps}
+ * @returns A checkbox.
+ */
+export declare const BooleanEditor: FunctionComponent<BooleanEditorProps>;
+/**
+ * Props for the {@link NullEditor} component.
+ *
+ * @property className - Additional class name(s) applied to the root element.
+ */
+export type NullEditorProps = WithClassName<Record<string, never>>;
+/**
+ * The editor for a null value — there is nothing to edit, so it only states the
+ * type.
+ *
+ * @param props - Component properties.
+ * @see {@link NullEditorProps}
+ * @returns A span reading `null`.
+ */
+export declare const NullEditor: FunctionComponent<NullEditorProps>;
+/**
+ * Props for the {@link RecordEditor} component.
+ *
+ * @property defaultValue - Initial entries. Read on mount only.
+ * @property onChange - Called after any entry is added, removed, renamed or
+ * edited, with the rebuilt record.
+ * @property path - Keys and indices leading to this record from the document
+ * root, extended with each entry's key before being passed down.
+ * @property preventSameNameKeys - Refuses a rename that would collide with a
+ * sibling key, instead of letting the renamed entry replace it. Defaults to
+ * `false`. Forwarded to every record nested below.
+ * @property className - Additional class name(s) applied to the root element.
+ */
+export type RecordEditorProps = WithClassName<{
+    defaultValue?: Record<string, JsonValue>;
+    onChange?: (newValue: Record<string, JsonValue>) => void;
+    path?: Array<string | number>;
+    preventSameNameKeys?: boolean;
+}>;
+/**
+ * The editor for a record: one renamable, removable entry per key, each holding
+ * a nested {@link ValueEditor}.
+ *
+ * @param props - Component properties.
+ * @see {@link RecordEditorProps}
+ * @returns A list of entries, followed by the button that appends one.
+ *
+ * @remarks
+ * Entries are held in a `Map` keyed by property name, each carrying a stable id
+ * used as the React key — so renaming a property doesn't remount its editor and
+ * lose the subtree's state.
+ */
+export declare const RecordEditor: FunctionComponent<RecordEditorProps>;
+/**
+ * Props for the {@link ArrayEditor} component.
+ *
+ * @property defaultValue - Initial items. Read on mount only.
+ * @property onChange - Called after any item is added, removed, moved or edited,
+ * with the rebuilt array.
+ * @property path - Keys and indices leading to this array from the document
+ * root, extended with each item's index before being passed down.
+ * @property preventSameNameKeys - Forwarded to every record nested below.
+ * @property className - Additional class name(s) applied to the root element.
+ */
+export type ArrayEditorProps = WithClassName<{
+    defaultValue?: JsonValue[];
+    onChange?: (newValue: JsonValue[]) => void;
+    path?: Array<string | number>;
+    preventSameNameKeys?: boolean;
+}>;
+/**
+ * The editor for an array: one removable, movable item per index, each holding a
+ * nested {@link ValueEditor}.
+ *
+ * @param props - Component properties.
+ * @see {@link ArrayEditorProps}
+ * @returns An ordered list of items, followed by the button that appends one.
+ *
+ * @remarks
+ * Items are held in a `Map` keyed by a stable id used as the React key, so
+ * reordering moves the editors rather than remounting them.
+ */
+export declare const ArrayEditor: FunctionComponent<ArrayEditorProps>;

package/components/JsonEditor/index.js

@@ -1,17 +1,13 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { ZodError } from 'zod';
-import { clss } from '../../agnostic/css/clss/index.js';
-import { isNonNullObject } from '../../agnostic/objects/is-object/index.js';
 import { randomHash } from '../../agnostic/random/uuid/index.js';
+import { isNonNullObject } from '../../agnostic/objects/is-object/index.js';
 import { Input } from '../Input/index.js';
 import { Select } from '../Select/index.js';
 import { Textarea } from '../Textarea/index.js';
 import { mergeClassNames } from '../utils/index.js';
-import { jsonEditor as publicClassName } from '../public-classnames.js';
-import cssModule from './styles.module.css';
-/* Shared across all sub components */
-const c = clss(publicClassName, { cssModule });
+import { c, getValueType } from './utils.js';
 /**
  * Interactive JSON editor component.
  *
@@ -28,19 +24,29 @@ const c = clss(publicClassName, { cssModule });
  *   matching the current value type (`string`, `number`, `boolean`, `null`, `array`, `record`).
  * - `type` — the type selector control.
  * - `string`, `number`, `boolean`, `null` — primitive value inputs.
- * - `record` — record entry list.
- * - `array` — array entry list items.
+ * - `record` — record entry list; `record-item` — one entry of it.
+ * - `array` — array item list; `array-item` — one item of it.
  * - `prop-name` — key input for record entries.
  * - `create-prop` — button to append a new entry to a record or array.
  * - `delete-prop` — button to remove an existing entry.
  * - `lift-prop` — button to move an array entry up.
  * - `drop-prop` — button to move an array entry down.
+ * - `preview` — the serialized JSON preview.
  *
  * @param props - Component properties.
  * @see {@link Props}
  * @returns A recursive JSON value editor with a live serialized preview.
+ *
+ * @remarks
+ * **The editor is uncontrolled, at every level of the tree, and there is no
+ * controlled variant.** Each node seeds its state from its `defaultValue` on
+ * mount and never reads it again, so handing a mounted editor a new
+ * `defaultValue` changes nothing on screen — remount it with a different `key`
+ * to load another document. A controlled mode would mean rebuilding the state
+ * model so the whole tree reads from a single owner, which is why none of these
+ * components accepts a `value` prop.
  */
-export const JsonEditor = ({ defaultValue = null, onChange, onValidationError, schema, className }) => {
+export const JsonEditor = ({ defaultValue = null, onChange, onValidationError, schema, preventSameNameKeys, className }) => {
     const [value, setValue] = useState(defaultValue);
     const setValueAndDispatch = (val) => {
         setValue(val);
@@ -57,23 +63,19 @@ export const JsonEditor = ({ defaultValue = null, onChange, onValidationError, s
                 throw err;
         }
     };
-    const rootClss = mergeClassNames(c(null, {}), className);
-    return _jsxs("div", { className: rootClss, children: [_jsx(ValueEditor, { defaultValue: defaultValue, onChange: val => setValueAndDispatch(val), path: [] }), _jsx("pre", { children: JSON.stringify(value, null, 2) })] });
+    const rootClss = mergeClassNames(c(), className);
+    return _jsxs("div", { className: rootClss, children: [_jsx(ValueEditor, { defaultValue: defaultValue, onChange: val => setValueAndDispatch(val), preventSameNameKeys: preventSameNameKeys, path: [] }), _jsx("pre", { className: c('preview'), children: JSON.stringify(value, null, 2) })] });
 };
-function getValueType(value) {
-    if (value === null)
-        return 'null';
-    if (Array.isArray(value))
-        return 'array';
-    if (isNonNullObject(value))
-        return 'record';
-    if (typeof value === 'string')
-        return 'string';
-    if (typeof value === 'number')
-        return 'number';
-    return 'boolean';
-}
-export const ValueEditor = ({ defaultValue = {}, onChange, path = [] }) => {
+/**
+ * One node of the editor tree: a type selector, plus the editor matching the
+ * value's current type. Switching type replaces the value with an empty one of
+ * the new type.
+ *
+ * @param props - Component properties.
+ * @see {@link ValueEditorProps}
+ * @returns A span holding the type selector and the type-appropriate editor.
+ */
+export const ValueEditor = ({ defaultValue = null, onChange, path = [], preventSameNameKeys, className }) => {
     // State
     const [value, setValue] = useState(defaultValue);
     const setValueAndDispatch = (newValue) => {
@@ -92,7 +94,7 @@ export const ValueEditor = ({ defaultValue = {}, onChange, path = [] }) => {
         if (newType === 'null')
             return setValueAndDispatch(null);
         if (newType === 'record')
-            return setValueAndDispatch({ a: 0, b: false });
+            return setValueAndDispatch({});
         if (newType === 'array')
             return setValueAndDispatch([]);
     };
@@ -103,48 +105,66 @@ export const ValueEditor = ({ defaultValue = {}, onChange, path = [] }) => {
     const handleArrayValueChange = e => setValueAndDispatch(e);
     // Rendering
     const valueType = getValueType(value);
-    const valueEditorClss = c('value', valueType);
+    const valueEditorClss = mergeClassNames(c('value', valueType), className);
     const pathStringDataAttr = path.map(e => e.toString()).join('.');
-    return _jsxs("span", { className: valueEditorClss, "data-path": pathStringDataAttr, children: [_jsxs(Select, { className: c('type'), value: valueType, onChange: handleTypeSelectChange, children: [_jsx("option", { value: 'string', children: "string" }), _jsx("option", { value: 'number', children: "number" }), _jsx("option", { value: 'boolean', children: "boolean" }), _jsx("option", { value: 'null', children: "null" }), _jsx("option", { value: 'record', children: "record" }), _jsx("option", { value: 'array', children: "array" })] }), typeof value === 'string' && _jsx(StringEditor, { type: 'textarea', defaultValue: value, onChange: handleStringValueChange }), typeof value === 'number' && _jsx(NumberEditor, { defaultValue: value, onChange: handleNumberValueChange }), typeof value === 'boolean' && _jsx(BooleanEditor, { defaultValue: value, onChange: handleBooleanValueChange }), value === null && _jsx(NullEditor, { defaultValue: value }), isNonNullObject(value) && !Array.isArray(value) && _jsx(RecordEditor, { defaultValue: value, onChange: handleRecordValueChange, path: path }), Array.isArray(value) && _jsx(ArrayEditor, { defaultValue: value, onChange: handleArrayValueChange, path: path })] });
+    return _jsxs("span", { className: valueEditorClss, "data-path": pathStringDataAttr, children: [_jsxs(Select, { className: c('type'), value: valueType, onChange: handleTypeSelectChange, children: [_jsx("option", { value: 'string', children: "string" }), _jsx("option", { value: 'number', children: "number" }), _jsx("option", { value: 'boolean', children: "boolean" }), _jsx("option", { value: 'null', children: "null" }), _jsx("option", { value: 'record', children: "record" }), _jsx("option", { value: 'array', children: "array" })] }), typeof value === 'string' && _jsx(StringEditor, { type: 'textarea', defaultValue: value, onChange: handleStringValueChange }), typeof value === 'number' && _jsx(NumberEditor, { defaultValue: value, onChange: handleNumberValueChange }), typeof value === 'boolean' && _jsx(BooleanEditor, { defaultValue: value, onChange: handleBooleanValueChange }), value === null && _jsx(NullEditor, {}), isNonNullObject(value) && !Array.isArray(value) && _jsx(RecordEditor, { defaultValue: value, onChange: handleRecordValueChange, preventSameNameKeys: preventSameNameKeys, path: path }), Array.isArray(value) && _jsx(ArrayEditor, { defaultValue: value, onChange: handleArrayValueChange, preventSameNameKeys: preventSameNameKeys, path: path })] });
 };
-/* * * * * * * * * * * * * * * * *
- *
- * String
- *
- * * * * * * * * * * * * * * * * */
-const StringEditor = (props) => props.type === 'textarea'
-    ? _jsx(Textarea, { className: c('string'), defaultValue: props.defaultValue ?? '', onChange: props.onChange })
-    : _jsx(Input, { type: 'text', className: c('string'), defaultValue: props.defaultValue ?? '', onChange: props.onChange });
-/* * * * * * * * * * * * * * * * *
- *
- * Number
- *
- * * * * * * * * * * * * * * * * */
-const NumberEditor = (props) => _jsx(Input, { className: c('number'), type: 'number', defaultValue: props.defaultValue ?? 0, onChange: props.onChange });
-/* * * * * * * * * * * * * * * * *
+/**
+ * The editor for a string value.
  *
- * Boolean
+ * @param props - Component properties.
+ * @see {@link StringEditorProps}
+ * @returns A textarea or a text input, depending on `type`.
+ */
+export const StringEditor = ({ type, defaultValue, onChange, className }) => type === 'textarea'
+    ? _jsx(Textarea, { className: mergeClassNames(c('string'), className), defaultValue: defaultValue ?? '', onChange: onChange })
+    : _jsx(Input, { type: 'text', className: mergeClassNames(c('string'), className), defaultValue: defaultValue ?? '', onChange: onChange });
+/**
+ * The editor for a number value.
  *
- * * * * * * * * * * * * * * * * */
-const BooleanEditor = (props) => _jsx(Input, { className: c('boolean'), type: 'checkbox', defaultChecked: props.defaultValue ?? false, onChange: props.onChange });
-/* * * * * * * * * * * * * * * * *
+ * @param props - Component properties.
+ * @see {@link NumberEditorProps}
+ * @returns A number input.
+ */
+export const NumberEditor = ({ defaultValue, onChange, className }) => _jsx(Input, { className: mergeClassNames(c('number'), className), type: 'number', defaultValue: defaultValue ?? 0, onChange: onChange });
+/**
+ * The editor for a boolean value.
  *
- * Null
+ * @param props - Component properties.
+ * @see {@link BooleanEditorProps}
+ * @returns A checkbox.
+ */
+export const BooleanEditor = ({ defaultValue, onChange, className }) => _jsx(Input, { className: mergeClassNames(c('boolean'), className), type: 'checkbox', defaultChecked: defaultValue ?? false, onChange: onChange });
+/**
+ * The editor for a null value — there is nothing to edit, so it only states the
+ * type.
  *
- * * * * * * * * * * * * * * * * */
-const NullEditor = () => _jsx("span", { className: c('null'), children: "null" });
-/* * * * * * * * * * * * * * * * *
+ * @param props - Component properties.
+ * @see {@link NullEditorProps}
+ * @returns A span reading `null`.
+ */
+export const NullEditor = ({ className }) => _jsx("span", { className: mergeClassNames(c('null'), className), children: "null" });
+/**
+ * The editor for a record: one renamable, removable entry per key, each holding
+ * a nested {@link ValueEditor}.
  *
- * Record
+ * @param props - Component properties.
+ * @see {@link RecordEditorProps}
+ * @returns A list of entries, followed by the button that appends one.
  *
- * * * * * * * * * * * * * * * * */
-const RecordEditor = ({ defaultValue = {}, onChange, path }) => {
+ * @remarks
+ * Entries are held in a `Map` keyed by property name, each carrying a stable id
+ * used as the React key — so renaming a property doesn't remount its editor and
+ * lose the subtree's state.
+ */
+export const RecordEditor = ({ defaultValue = {}, onChange, path, preventSameNameKeys = false, className }) => {
     const [value, setValue] = useState(new Map(Object
         .entries(defaultValue)
         .map(([key, val]) => [key, {
             id: randomHash(8),
             val
         }])));
+    const [refusedRenames, setRefusedRenames] = useState(0);
     const setValueAndDispatch = (newValue) => {
         setValue(newValue);
         onChange?.(Array.from(newValue).reduce((acc, [key, { val }]) => ({
@@ -158,7 +178,7 @@ const RecordEditor = ({ defaultValue = {}, onChange, path }) => {
         setValueAndDispatch(newValue);
     };
     const handleCreateProp = () => {
-        let propName = '';
+        let propName = randomHash(4);
         while (value.get(propName) !== undefined) {
             propName = randomHash(4);
         }
@@ -168,12 +188,24 @@ const RecordEditor = ({ defaultValue = {}, onChange, path }) => {
     };
     const handleRenameProp = (oldName) => e => {
         const newName = e.target.value;
+        if (newName === oldName)
+            return;
+        if (preventSameNameKeys && value.has(newName)) {
+            // Refusing leaves the state untouched, and the name input is uncontrolled —
+            // it would go on showing what was typed. Bumping this counter is what puts
+            // the field back: it feeds the input's key, so the input remounts and reads
+            // its `defaultValue` again.
+            setRefusedRenames(count => count + 1);
+            return;
+        }
+        // Dropping the colliding entry first is what makes the outcome predictable:
+        // the renamed entry wins, and keeps its own position in the record. Rebuilding
+        // the Map without this leaves two entries under the same key, and `new Map`
+        // silently keeps the last one — losing the value being renamed.
         const newValue = new Map(Array
             .from(value)
-            .map(([key, { id, val }]) => [
-            key === oldName ? newName : key,
-            { id, val }
-        ]));
+            .filter(([key]) => key !== newName)
+            .map(([key, entry]) => [key === oldName ? newName : key, entry]));
         setValueAndDispatch(newValue);
     };
     const handleChangeProp = (changedKey) => (newValue) => {
@@ -183,14 +215,21 @@ const RecordEditor = ({ defaultValue = {}, onChange, path }) => {
             }]));
         setValueAndDispatch(newVal);
     };
-    return _jsxs("ul", { className: c('record'), children: [Array.from(value).map(([key, { id, val }]) => _jsxs("li", { "data-key": key, "data-path": [...(path ?? []), key].join('.'), children: [_jsx("button", { className: c('delete-prop'), onClick: () => handleDeleteProp(key), children: "x" }), _jsx("span", { className: c('prop-name'), children: _jsx(StringEditor, { type: 'input', defaultValue: key, onChange: handleRenameProp(key) }) }), _jsx(ValueEditor, { defaultValue: val, onChange: handleChangeProp(key), path: [...(path ?? []), key] })] }, id)), _jsx("button", { className: c('create-prop'), onClick: handleCreateProp, children: "+" })] });
+    return _jsxs("ul", { className: mergeClassNames(c('record'), className), children: [Array.from(value).map(([key, { id, val }]) => _jsxs("li", { className: c('record-item'), "data-key": key, "data-path": [...(path ?? []), key].join('.'), children: [_jsx("button", { className: c('delete-prop'), onClick: () => handleDeleteProp(key), children: "x" }), _jsx("span", { className: c('prop-name'), children: _jsx(StringEditor, { type: 'input', defaultValue: key, onChange: handleRenameProp(key) }, `${id}-${refusedRenames}`) }), _jsx(ValueEditor, { defaultValue: val, onChange: handleChangeProp(key), preventSameNameKeys: preventSameNameKeys, path: [...(path ?? []), key] })] }, id)), _jsx("button", { className: c('create-prop'), onClick: handleCreateProp, children: "+" })] });
 };
-/* * * * * * * * * * * * * * * * *
+/**
+ * The editor for an array: one removable, movable item per index, each holding a
+ * nested {@link ValueEditor}.
  *
- * Array
+ * @param props - Component properties.
+ * @see {@link ArrayEditorProps}
+ * @returns An ordered list of items, followed by the button that appends one.
  *
- * * * * * * * * * * * * * * * * */
-const ArrayEditor = ({ defaultValue = [], onChange, path }) => {
+ * @remarks
+ * Items are held in a `Map` keyed by a stable id used as the React key, so
+ * reordering moves the editors rather than remounting them.
+ */
+export const ArrayEditor = ({ defaultValue = [], onChange, path, preventSameNameKeys, className }) => {
     const [value, setValue] = useState(new Map(defaultValue.map(val => [randomHash(8), val])));
     const setValueAndDispatch = (newValue) => {
         setValue(newValue);
@@ -209,17 +248,34 @@ const ArrayEditor = ({ defaultValue = [], onChange, path }) => {
         [Array.from(value)[pos]?.[0] ?? randomHash(8), newValue],
         ...Array.from(value).slice(pos + 1)
     ]));
-    const handleLiftProp = (pos) => setValueAndDispatch(new Map([
-        ...Array.from(value).slice(0, pos - 1),
-        Array.from(value)[pos],
-        Array.from(value)[pos - 1],
-        ...Array.from(value).slice(pos + 1)
-    ].filter(e => e !== undefined)));
-    const handleDropProp = (pos) => setValueAndDispatch(new Map([
-        ...Array.from(value).slice(0, pos),
-        Array.from(value)[pos + 1],
-        Array.from(value)[pos],
-        ...Array.from(value).slice(pos + 2)
-    ].filter(e => e !== undefined)));
-    return _jsxs("ol", { children: [Array.from(value).map(([id, val], pos) => _jsxs("li", { className: c('array'), "data-path": [...(path ?? []), pos].join('.'), children: [_jsx("button", { className: c('delete-prop'), onClick: () => handleDeleteProp(pos), children: "x" }), _jsx("button", { className: c('lift-prop'), disabled: pos === 0, onClick: () => handleLiftProp(pos), children: "\u2191" }), _jsx("button", { className: c('drop-prop'), disabled: pos === value.size - 1, onClick: () => handleDropProp(pos), children: "\u2193" }), _jsx(ValueEditor, { defaultValue: val, onChange: handleChangeProp(pos), path: [...(path ?? []), pos] })] }, id)), _jsx("button", { className: c('create-prop'), onClick: handleCreateProp, children: "+" })] });
+    // Swapping with the entry before, so position 0 has nothing to swap with. The
+    // guard is what keeps `pos - 1` from reaching back into the array as `-1`.
+    const handleLiftProp = (pos) => {
+        if (pos <= 0)
+            return;
+        const entries = Array.from(value);
+        setValueAndDispatch(new Map([
+            ...entries.slice(0, pos - 1),
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            entries[pos],
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            entries[pos - 1],
+            ...entries.slice(pos + 1)
+        ]));
+    };
+    // Same, mirrored: the last entry has nothing to swap with.
+    const handleDropProp = (pos) => {
+        const entries = Array.from(value);
+        if (pos < 0 || pos >= entries.length - 1)
+            return;
+        setValueAndDispatch(new Map([
+            ...entries.slice(0, pos),
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            entries[pos + 1],
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            entries[pos],
+            ...entries.slice(pos + 2)
+        ]));
+    };
+    return _jsxs("ol", { className: mergeClassNames(c('array'), className), children: [Array.from(value).map(([id, val], pos) => _jsxs("li", { className: c('array-item'), "data-path": [...(path ?? []), pos].join('.'), children: [_jsx("button", { className: c('delete-prop'), onClick: () => handleDeleteProp(pos), children: "x" }), _jsx("button", { className: c('lift-prop'), disabled: pos === 0, onClick: () => handleLiftProp(pos), children: "\u2191" }), _jsx("button", { className: c('drop-prop'), disabled: pos === value.size - 1, onClick: () => handleDropProp(pos), children: "\u2193" }), _jsx(ValueEditor, { defaultValue: val, onChange: handleChangeProp(pos), preventSameNameKeys: preventSameNameKeys, path: [...(path ?? []), pos] })] }, id)), _jsx("button", { className: c('create-prop'), onClick: handleCreateProp, children: "+" })] });
 };

package/components/JsonEditor/types.d.ts

@@ -0,0 +1,11 @@
+/** A JSON value that contains no other value. */
+export type JsonPrimitive = string | number | boolean | null;
+/** Any value `JSON.parse` can produce, and the type the editor reads and emits. */
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+/**
+ * The editor's name for a value's kind. It is what the type selector offers, and
+ * what modifies the `value` class name on each node.
+ */
+export type ValueType = 'string' | 'number' | 'boolean' | 'null' | 'array' | 'record';

package/components/JsonEditor/types.js

@@ -0,0 +1 @@
+export {};

package/components/JsonEditor/utils.d.ts

@@ -0,0 +1,8 @@
+import type { JsonValue, ValueType } from './types.js';
+/**
+ * Shared by every editor in the tree — they all emit class names under the same
+ * public prefix, so a single instance is what keeps them consistent.
+ */
+export declare const c: import("../../agnostic/css/clss/index.js").ClssMaker;
+/** Which {@link ValueType} a value belongs to. */
+export declare function getValueType(value: JsonValue): ValueType;

package/components/JsonEditor/utils.js

@@ -0,0 +1,23 @@
+import { clss } from '../../agnostic/css/clss/index.js';
+import { isNonNullObject } from '../../agnostic/objects/is-object/index.js';
+import { jsonEditor as publicClassName } from '../public-classnames.js';
+import cssModule from './styles.module.css';
+/**
+ * Shared by every editor in the tree — they all emit class names under the same
+ * public prefix, so a single instance is what keeps them consistent.
+ */
+export const c = clss(publicClassName, { cssModule });
+/** Which {@link ValueType} a value belongs to. */
+export function getValueType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (isNonNullObject(value))
+        return 'record';
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number')
+        return 'number';
+    return 'boolean';
+}

package/components/ListLoader/index.controlled.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 import type { WithClassName } from '../utils/types.js';
 /**
- * Props for the {@link ListLoaderControlled} component.
+ * Props for the {@link ControlledListLoader} component.
  *
  * @template T - The item type carried by each page.
  *
@@ -21,10 +21,10 @@ import type { WithClassName } from '../utils/types.js';
  * back to a positional key.
  * @property loadingPages - Page positions currently being fetched. Exposed on the
  * root element as `data-loading-pages`.
- * @property onLoadPageClick - Called with the page position a load button targets,
+ * @property onLoadPageClicked - Called with the page position a load button targets,
  * either on click or on viewport entry when auto-loading is enabled.
  * @property autoLoadPrevWhenVisible - Wraps the leading load button in an
- * {@link IntersectionObserverComponent} and fires `onLoadPageClick` when it enters the viewport.
+ * {@link IntersectionObserverComponent} and fires `onLoadPageClicked` when it enters the viewport.
  * @property autoLoadNextWhenVisible - Same, for the trailing load button.
  * @property className - Additional class name(s) applied to the root element.
  */
@@ -37,7 +37,7 @@ export type Props<T> = WithClassName<{
     display: (item: T) => ReactNode;
     getIdentifier?: (item: T) => string | undefined;
     loadingPages?: number[];
-    onLoadPageClick?: (pagePos: number) => void;
+    onLoadPageClicked?: (pagePos: number) => void;
     autoLoadPrevWhenVisible?: boolean;
     autoLoadNextWhenVisible?: boolean;
 }>;
@@ -75,4 +75,4 @@ export type Props<T> = WithClassName<{
  * Deduplication runs after `filter`, so an item hidden by `filter` never evicts
  * an earlier duplicate.
  */
-export declare const ListLoaderControlled: <T>({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClick, autoLoadPrevWhenVisible, autoLoadNextWhenVisible }: Props<T>) => ReactNode;
+export declare const ControlledListLoader: <T>({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible }: Props<T>) => ReactNode;

package/components/ListLoader/index.controlled.js

@@ -39,7 +39,7 @@ import cssModule from './styles.module.css';
  * Deduplication runs after `filter`, so an item hidden by `filter` never evicts
  * an earlier duplicate.
  */
-export const ListLoaderControlled = ({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClick, autoLoadPrevWhenVisible, autoLoadNextWhenVisible }) => {
+export const ControlledListLoader = ({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible }) => {
     const inBoundsPages = pages.filter(pagePos => pagePos >= firstPagePos && pagePos <= lastPagePos);
     const filteredItems = Array.from(itemsPages)
         .filter(([pagePos]) => inBoundsPages.includes(pagePos))
@@ -78,9 +78,9 @@ export const ListLoaderControlled = ({ className, pages, firstPagePos, lastPageP
         .filter(pagePos => inBoundsPages.includes(pagePos))
         .sort((a, b) => a - b);
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(null), className);
+    const rootClss = mergeClassNames(c(), className);
     const renderLoadButton = (pagePos, kind) => {
-        const button = _jsx("button", { className: c('load', kind), "data-page": pagePos, onClick: () => onLoadPageClick?.(pagePos) }, `load/${pagePos}`);
+        const button = _jsx("button", { className: c('load', kind), "data-page": pagePos, onClick: () => onLoadPageClicked?.(pagePos) }, `load/${pagePos}`);
         const autoLoads = (kind === 'prev' && autoLoadPrevWhenVisible === true)
             || (kind === 'next' && autoLoadNextWhenVisible === true);
         if (!autoLoads)
@@ -88,7 +88,7 @@ export const ListLoaderControlled = ({ className, pages, firstPagePos, lastPageP
         return _jsx(IntersectionObserverComponent, { className: c('load-observer', kind), onIntersected: ({ ioEntry }) => {
                 if (ioEntry?.isIntersecting !== true)
                     return;
-                onLoadPageClick?.(pagePos);
+                onLoadPageClicked?.(pagePos);
             }, children: button }, `load/${pagePos}`);
     };
     return _jsx("div", { className: rootClss, "data-loading-pages": sortedLoadingPages.length === 0 ? undefined : sortedLoadingPages.join(','), children: slots.map(({ pagePos, kind }) => kind === 'items'