@mxfb/tools 1.0.5 → 1.0.8

package/components/JsonEditor/index.d.ts

@@ -0,0 +1,227 @@
+import { type FunctionComponent, type EventHandler, type ChangeEvent } from 'react';
+import { type ZodType, type core } from 'zod';
+import type { WithClassName } from '../utils/types.js';
+import type { JsonValue } from './types.js';
+/**
+ * Props for the {@link JsonEditor} component.
+ *
+ * @property defaultValue - Initial JSON value rendered by the editor. Defaults to `null`.
+ * @property onChange - Called after any value change with the updated JSON value.
+ * @property onValidationError - Called when the updated value fails schema validation,
+ * 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<{
+    defaultValue?: JsonValue;
+    onChange?: (val: JsonValue) => void;
+    onValidationError?: (issues: core.$ZodIssue[]) => void;
+    schema?: ZodType<JsonValue>;
+    preventSameNameKeys?: boolean;
+}>;
+/**
+ * Interactive JSON editor component.
+ *
+ * Renders a recursive value editor tree alongside a live JSON preview.
+ * Supports all JSON value types: strings, numbers, booleans, null, arrays,
+ * and records. Each node exposes a type selector and a type-appropriate input.
+ *
+ * When a `schema` is provided, the current value is validated against it after
+ * every change. Validation errors are reported through `onValidationError` and
+ * do not block editing.
+ *
+ * ### CSS elements
+ * - `value` — wraps each node in the editor tree; receives a type modifier
+ *   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; `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>;
+/**
+ * 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>>;
+}>;
+/**
+ * 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

@@ -0,0 +1,281 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { ZodError } from 'zod';
+import { isNonNullObject } from '@design-edito/tools/agnostic/objects/is-object/index.js';
+import { randomHash } from '@design-edito/tools/agnostic/random/uuid/index.js';
+import { Input } from '@design-edito/tools/components/Input/index.js';
+import { Select } from '@design-edito/tools/components/Select/index.js';
+import { Textarea } from '@design-edito/tools/components/Textarea/index.js';
+import { mergeClassNames } from '../utils/index.js';
+import { c, getValueType } from './utils.js';
+/**
+ * Interactive JSON editor component.
+ *
+ * Renders a recursive value editor tree alongside a live JSON preview.
+ * Supports all JSON value types: strings, numbers, booleans, null, arrays,
+ * and records. Each node exposes a type selector and a type-appropriate input.
+ *
+ * When a `schema` is provided, the current value is validated against it after
+ * every change. Validation errors are reported through `onValidationError` and
+ * do not block editing.
+ *
+ * ### CSS elements
+ * - `value` — wraps each node in the editor tree; receives a type modifier
+ *   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; `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, preventSameNameKeys, className }) => {
+    const [value, setValue] = useState(defaultValue);
+    const setValueAndDispatch = (val) => {
+        setValue(val);
+        onChange?.(val);
+        try {
+            schema?.parse(val);
+        }
+        catch (err) {
+            if (err instanceof ZodError) {
+                const { issues } = err;
+                onValidationError?.(issues);
+            }
+            else
+                throw err;
+        }
+    };
+    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) })] });
+};
+/**
+ * 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) => {
+        setValue(newValue);
+        onChange?.(newValue);
+    };
+    // Handlers
+    const handleTypeSelectChange = e => {
+        const newType = e.target.value;
+        if (newType === 'string')
+            return setValueAndDispatch('');
+        if (newType === 'number')
+            return setValueAndDispatch(0);
+        if (newType === 'boolean')
+            return setValueAndDispatch(false);
+        if (newType === 'null')
+            return setValueAndDispatch(null);
+        if (newType === 'record')
+            return setValueAndDispatch({});
+        if (newType === 'array')
+            return setValueAndDispatch([]);
+    };
+    const handleStringValueChange = e => setValueAndDispatch(e.target.value);
+    const handleNumberValueChange = e => setValueAndDispatch(parseFloat(e.target.value));
+    const handleBooleanValueChange = e => setValueAndDispatch(e.target.checked);
+    const handleRecordValueChange = e => setValueAndDispatch(e);
+    const handleArrayValueChange = e => setValueAndDispatch(e);
+    // Rendering
+    const valueType = getValueType(value);
+    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, {}), 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 })] });
+};
+/**
+ * The editor for a string value.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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}.
+ *
+ * @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 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 }]) => ({
+            ...acc,
+            [key]: val
+        }), {}));
+    };
+    const handleDeleteProp = (key) => {
+        const newValue = new Map(value);
+        newValue.delete(key);
+        setValueAndDispatch(newValue);
+    };
+    const handleCreateProp = () => {
+        let propName = randomHash(4);
+        while (value.get(propName) !== undefined) {
+            propName = randomHash(4);
+        }
+        const newValue = new Map(value);
+        newValue.set(propName, { id: randomHash(8), val: null });
+        setValueAndDispatch(newValue);
+    };
+    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)
+            .filter(([key]) => key !== newName)
+            .map(([key, entry]) => [key === oldName ? newName : key, entry]));
+        setValueAndDispatch(newValue);
+    };
+    const handleChangeProp = (changedKey) => (newValue) => {
+        const newVal = new Map(Array.from(value).map(([key, { id, val }]) => [key, {
+                id,
+                val: key === changedKey ? newValue : val
+            }]));
+        setValueAndDispatch(newVal);
+    };
+    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}.
+ *
+ * @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 const ArrayEditor = ({ defaultValue = [], onChange, path, preventSameNameKeys, className }) => {
+    const [value, setValue] = useState(new Map(defaultValue.map(val => [randomHash(8), val])));
+    const setValueAndDispatch = (newValue) => {
+        setValue(newValue);
+        onChange?.(Array.from(newValue).map(([, val]) => val));
+    };
+    const handleDeleteProp = (pos) => setValueAndDispatch(new Map([
+        ...Array.from(value).slice(0, pos),
+        ...Array.from(value).slice(pos + 1)
+    ]));
+    const handleCreateProp = () => {
+        const newValue = new Map([...Array.from(value), [randomHash(8), null]]);
+        setValueAndDispatch(newValue);
+    };
+    const handleChangeProp = (pos) => (newValue) => setValueAndDispatch(new Map([
+        ...Array.from(value).slice(0, pos),
+        [Array.from(value)[pos]?.[0] ?? randomHash(8), newValue],
+        ...Array.from(value).slice(pos + 1)
+    ]));
+    // 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,5 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+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,3 @@
+import type { JsonValue, ValueType } from './types.js';
+export declare const c: import("@design-edito/tools/agnostic/css/clss/index.js").ClssMaker;
+export declare function getValueType(value: JsonValue): ValueType;

package/components/JsonEditor/utils.js

@@ -0,0 +1,18 @@
+import { clss } from '@design-edito/tools/agnostic/css/clss/index.js';
+import { isNonNullObject } from '@design-edito/tools/agnostic/objects/is-object/index.js';
+import { jsonEditor as publicClassName } from '../public-classnames.js';
+import cssModule from './styles.module.css';
+export const c = clss(publicClassName, { cssModule });
+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

@@ -0,0 +1,87 @@
+import type { ReactNode } from 'react';
+import type { ObserverOptions } from '@design-edito/tools/components/utils/intersection/index.js';
+import type { WithClassName } from '../utils/types.js';
+/**
+ * Props for the {@link ControlledListLoader} component.
+ *
+ * @template T - The item type carried by each page.
+ *
+ * @property pages - Page positions the consumer wants rendered. Entries outside
+ * `firstPagePos`–`lastPagePos` are ignored, as are entries absent from `itemsPages`.
+ * @property firstPagePos - Lowest page position that exists. No load button is
+ * ever rendered below it.
+ * @property lastPagePos - Highest page position that exists. No load button is
+ * ever rendered above it.
+ * @property itemsPages - Already-loaded items, keyed by page position. The
+ * component holds no data of its own and renders only what this map contains.
+ * @property filter - Decides whether an item is rendered. Applied before deduplication.
+ * @property display - Renders a single item.
+ * @property getIdentifier - Item identity, used as React key and to deduplicate.
+ * When two rendered items share an identifier, only the later one in page order
+ * survives. Returning `undefined` opts an item out of deduplication, and falls
+ * back to a positional key.
+ * @property loadingPages - Page positions currently being fetched. Exposed on the
+ * root element as `data-loading-pages`.
+ * @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 `onLoadPageClicked` when it enters the viewport.
+ * @property autoLoadNextWhenVisible - Same, for the trailing load button.
+ * @property threshold - How much of a load button has to be in view before it
+ * counts as visible, forwarded to each observer.
+ * @property root - Their root. Defaults to the viewport.
+ * @property rootMargin - Grows or shrinks that root before measuring — the way to
+ * start loading a page before its button actually shows.
+ * @property className - Additional class name(s) applied to the root element.
+ */
+export type Props<T> = WithClassName<ObserverOptions & {
+    pages: number[];
+    firstPagePos: number;
+    lastPagePos: number;
+    itemsPages: Map<number, T[]>;
+    filter: (item: T) => boolean;
+    display: (item: T) => ReactNode;
+    getIdentifier?: (item: T) => string | undefined;
+    loadingPages?: number[];
+    onLoadPageClicked?: (pagePos: number) => void;
+    autoLoadPrevWhenVisible?: boolean;
+    autoLoadNextWhenVisible?: boolean;
+}>;
+/**
+ * Presentational layer of the paginated list. Renders already-loaded pages as a
+ * single flat item list, and interleaves load buttons wherever a page is missing.
+ *
+ * This component holds no state and performs no fetching. Loaded pages are sorted
+ * by position and flattened, so items appear in page order then in item order,
+ * with no per-page wrapper element.
+ *
+ * ### Load buttons
+ * One button is rendered per missing page position:
+ * - before the first loaded page, unless it is already `firstPagePos`,
+ * - in place of each page missing between two loaded pages,
+ * - after the last loaded page, unless it is already `lastPagePos`.
+ *
+ * ### Root element modifiers
+ * - `--loading` — at least one page is being fetched.
+ *
+ * ### CSS elements
+ * - `item` — wraps each rendered item. Carries `data-page`.
+ * - `load` — a load button. Rendered empty, so its label belongs in CSS.
+ *   Carries `data-page` and a `prev`, `next` or `gap` modifier.
+ * - `load-observer` — the intersection observer wrapping an auto-loading button.
+ *   Present only when `autoLoadPrevWhenVisible` or `autoLoadNextWhenVisible` is on.
+ *   Carries a `prev` or `next` modifier.
+ *
+ * ### Data attributes on the root element
+ * - `data-loading-pages` — comma-separated ascending list of the pages being
+ *   fetched, e.g. `"1,3,6"`. Absent entirely when nothing is loading.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A flat list of items with load buttons in place of missing pages.
+ *
+ * @remarks
+ * Deduplication runs after `filter`, so an item hidden by `filter` never evicts
+ * an earlier duplicate.
+ */
+export declare const ControlledListLoader: <T>({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin }: Props<T>) => ReactNode;