@theoremjs/react 0.3.0 → 0.3.1

package/ui/SchemaFields.js

@@ -9,27 +9,35 @@ import { Selector } from '@astryxdesign/core/Selector';
 import { Slider } from '@astryxdesign/core/Slider';
 import { StackItem } from '@astryxdesign/core/Stack';
 import { Switch } from '@astryxdesign/core/Switch';
+import { Text } from '@astryxdesign/core/Text';
 import { TextArea } from '@astryxdesign/core/TextArea';
 import { TextInput } from '@astryxdesign/core/TextInput';
 import { Tokenizer } from '@astryxdesign/core/Tokenizer';
 import { VStack } from '@astryxdesign/core/VStack';
 import { useState } from 'react';
-import { blankRow, schemaFields, withField } from "../client/schema-fields.js";
+import { blankRow, schemaFields, withField, } from "../client/schema-fields.js";
 import { isRow, json } from "../client/shaped-data.js";
 import { useLabels } from "./labels-provider.js";
+import { useKeyedRows } from "./row-keys.js";
 import { AddRow, Group, Labelled, RemoveRow } from "./StateFields.js";
 const NO_SUGGESTIONS = { search: () => [], bootstrap: () => [] };
 const CODE_FONT = { '--font-family-body': 'var(--font-family-code)' };
+/** Lines a description shows before it is cut short. */
+const DESCRIPTION_LINES = 2;
+/** What a field is for, cut to a couple of lines. Hovering a cut one shows all of it. */
+function Description({ text }) {
+    return (_jsx(Text, { type: "supporting", color: "secondary", maxLines: DESCRIPTION_LINES, children: text }));
+}
 /** A field whose input carries no label of its own, labelled as one. */
 function Described({ field, children }) {
-    return (_jsx(Labelled, { label: field.label, isRequired: field.isRequired, description: field.description, children: children }));
+    return (_jsx(Labelled, { label: field.label, isRequired: field.isRequired, children: children }));
 }
 /** A field the schema doesn't shape (no type, a union, a free object), as its JSON. */
 function JsonField({ field, value, onChange }) {
     const t = useLabels();
     const [text, setText] = useState(() => (value === undefined ? '' : json(value)));
     const [isValid, setValid] = useState(true);
-    return (_jsx(TextArea, { label: field.label, description: field.description, isRequired: field.isRequired, size: "sm", rows: 3, value: text, hasSpellCheck: false, status: isValid ? undefined : { type: 'error', message: t('@theorem.decision.invalid_json') }, style: CODE_FONT, onChange: (next) => {
+    return (_jsx(TextArea, { label: field.label, isRequired: field.isRequired, size: "sm", rows: 3, value: text, hasSpellCheck: false, status: isValid ? undefined : { type: 'error', message: t('@theorem.decision.invalid_json') }, controlStyle: CODE_FONT, onChange: (next) => {
             setText(next);
             if (next.trim() === '') {
                 setValid(true);
@@ -46,51 +54,69 @@ function JsonField({ field, value, onChange }) {
         } }));
 }
 /** A list of objects: each row its own fields, removable, and one more at the end. */
-function RowsField({ field, item, value, onChange }) {
+function RowsField({ field, item, value, onChange, }) {
     const rows = Array.isArray(value) ? value : [];
-    return (_jsx(Group, { label: field.label, isRequired: field.isRequired, description: field.description, children: _jsxs(VStack, { gap: 3, children: [rows.map((row, index) => (_jsxs(HStack, { gap: 2, vAlign: "start", children: [_jsx(StackItem, { size: "fill", children: _jsx(ObjectFields, { schema: item, value: isRow(row) ? row : {}, onChange: (next) => onChange(rows.map((old, at) => (at === index ? next : old))) }) }), _jsx(RemoveRow, { index: index, onRemove: () => onChange(rows.filter((_, at) => at !== index)) })] }, index))), _jsx(AddRow, { field: field.label, onAdd: () => onChange([...rows, blankRow(item)]) })] }) }));
+    const keyed = useKeyedRows(rows);
+    return (_jsx(Group, { label: field.label, isRequired: field.isRequired, description: field.description && _jsx(Description, { text: field.description }), children: _jsxs(VStack, { gap: 3, children: [keyed.rows.map(({ item: row, index, key }) => (_jsxs(HStack, { gap: 2, vAlign: "start", children: [_jsx(StackItem, { size: "fill", children: _jsx(ObjectFields, { schema: item, value: isRow(row) ? row : {}, onChange: (next) => onChange(rows.map((old, at) => (at === index ? next : old))) }) }), _jsx(RemoveRow, { index: index, onRemove: () => {
+                                keyed.drop(index);
+                                onChange(rows.filter((_, at) => at !== index));
+                            } })] }, key))), _jsx(AddRow, { field: field.label, onAdd: () => onChange([...rows, blankRow(item)]) })] }) }));
 }
 function common(field) {
-    return { label: field.label, description: field.description, isRequired: field.isRequired, size: 'sm' };
+    return {
+        label: field.label,
+        isRequired: field.isRequired,
+        size: 'sm',
+    };
 }
 /** One of a few options as segments; more as a menu. */
-function ChoiceField({ field, options, isMenu, value, onChange }) {
+function ChoiceField({ field, options, isMenu, value, onChange, }) {
     if (isMenu) {
-        return _jsx(Selector, { ...common(field), options: options, value: typeof value === 'string' ? value : undefined, hasSearch: options.length > 10, onChange: onChange });
+        return (_jsx(Selector, { ...common(field), options: options, value: typeof value === 'string' ? value : undefined, hasSearch: options.length > 10, onChange: onChange }));
     }
     return (_jsx(Described, { field: field, children: _jsx(HStack, { children: _jsx(SegmentedControl, { label: field.label, size: "sm", value: typeof value === 'string' ? value : '', onChange: onChange, children: options.map((option) => (_jsx(SegmentedControlItem, { value: option, label: option }, option))) }) }) }));
 }
-function TextField({ field, isLong, type, value, onChange }) {
+function TextField({ field, isLong, type, value, onChange, }) {
     const text = typeof value === 'string' ? value : '';
-    return isLong ? _jsx(TextArea, { ...common(field), rows: 3, value: text, onChange: onChange }) : _jsx(TextInput, { ...common(field), type: type, value: text, onChange: onChange });
+    return isLong ? (_jsx(TextArea, { ...common(field), rows: 3, value: text, onChange: onChange })) : (_jsx(TextInput, { ...common(field), type: type, value: text, onChange: onChange }));
 }
 /** A list of words or numbers as tokens. */
 function WordsField({ field, value, onChange }) {
     const t = useLabels();
     const words = Array.isArray(value) ? value : [];
-    return (_jsx(Tokenizer, { ...common(field), value: words.map((word, index) => ({ id: `${String(index)}:${String(word)}`, label: String(word) })), searchSource: NO_SUGGESTIONS, hasCreate: true, debounceMs: 0, placeholder: t('@theorem.decision.add_value'), onChange: (items) => 
-        // Numbers stay numbers when every word reads as one and the list held numbers.
-        onChange(items.map((item) => (typeof words[0] === 'number' && Number.isFinite(Number(item.label)) ? Number(item.label) : item.label))) }));
+    return (_jsx(Tokenizer, { ...common(field), value: words.map((word, index) => ({
+            id: `${String(index)}:${String(word)}`,
+            label: String(word),
+        })), searchSource: NO_SUGGESTIONS, hasCreate: true, debounceMs: 0, placeholder: t('@theorem.decision.add_value'), onChange: (items) => onChange(items.map((item) => typeof words[0] === 'number' && Number.isFinite(Number(item.label))
+            ? Number(item.label)
+            : item.label)) }));
 }
 /** Each control's input, as the schema asks for it. */
 const CONTROLS = {
     choice: ({ field, control, value, onChange }) => (_jsx(ChoiceField, { field: field, options: control.options, isMenu: control.isMenu, value: value, onChange: onChange })),
-    range: ({ field, control, value, onChange }) => (_jsx(Slider, { label: field.label, description: field.description, isRequired: field.isRequired, min: control.min, max: control.max, step: 1, value: typeof value === 'number' ? value : control.min, valueDisplay: "text", onChange: onChange })),
+    range: ({ field, control, value, onChange }) => (_jsx(Slider, { label: field.label, isRequired: field.isRequired, min: control.min, max: control.max, step: 1, value: typeof value === 'number' ? value : control.min, valueDisplay: "text", onChange: onChange })),
     number: ({ field, control, value, onChange }) => (_jsx(NumberInput, { ...common(field), value: typeof value === 'number' ? value : undefined, min: control.min, max: control.max, isIntegerOnly: control.isInteger, isWheelEnabled: false, onChange: (next) => onChange(next ?? undefined) })),
-    switch: ({ field, value, onChange }) => _jsx(Switch, { label: field.label, description: field.description, value: value === true, onChange: onChange }),
+    switch: ({ field, value, onChange }) => (_jsx(Switch, { label: field.label, value: value === true, onChange: onChange })),
     date: ({ field, value, onChange }) => (_jsx(DateInput, { ...common(field), value: typeof value === 'string' ? value : undefined, onChange: onChange })),
-    text: ({ field, control, value, onChange }) => _jsx(TextField, { field: field, isLong: control.isLong, type: control.type, value: value, onChange: onChange }),
-    choices: ({ field, control, value, onChange }) => (_jsx(CheckboxList, { label: field.label, description: field.description, value: Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [], onChange: onChange, children: control.options.map((option) => (_jsx(CheckboxListItem, { label: option, value: option }, option))) })),
-    words: ({ field, value, onChange }) => _jsx(WordsField, { field: field, value: value, onChange: onChange }),
-    rows: ({ field, control, value, onChange }) => _jsx(RowsField, { field: field, item: control.item, value: value, onChange: onChange }),
-    group: ({ field, control, value, onChange }) => (_jsx(Group, { label: field.label, isRequired: field.isRequired, description: field.description, children: _jsx(ObjectFields, { schema: control.schema, value: isRow(value) ? value : {}, onChange: onChange }) })),
-    json: ({ field, value, onChange }) => _jsx(JsonField, { field: field, value: value, onChange: onChange }),
+    text: ({ field, control, value, onChange }) => (_jsx(TextField, { field: field, isLong: control.isLong, type: control.type, value: value, onChange: onChange })),
+    choices: ({ field, control, value, onChange }) => (_jsx(CheckboxList, { label: field.label, value: Array.isArray(value)
+            ? value.filter((entry) => typeof entry === 'string')
+            : [], onChange: onChange, children: control.options.map((option) => (_jsx(CheckboxListItem, { label: option, value: option }, option))) })),
+    words: ({ field, value, onChange }) => (_jsx(WordsField, { field: field, value: value, onChange: onChange })),
+    rows: ({ field, control, value, onChange }) => (_jsx(RowsField, { field: field, item: control.item, value: value, onChange: onChange })),
+    group: ({ field, control, value, onChange }) => (_jsx(Group, { label: field.label, isRequired: field.isRequired, description: field.description && _jsx(Description, { text: field.description }), children: _jsx(ObjectFields, { schema: control.schema, value: isRow(value) ? value : {}, onChange: onChange }) })),
+    json: ({ field, value, onChange }) => (_jsx(JsonField, { field: field, value: value, onChange: onChange })),
 };
 function Field({ field, value, onChange }) {
     const control = CONTROLS[field.control.kind];
-    return control({ field, control: field.control, value, onChange });
+    const input = control({ field, control: field.control, value, onChange });
+    // why: A group already says its description under its name.
+    const isGroup = field.control.kind === 'rows' || field.control.kind === 'group';
+    if (!field.description || isGroup)
+        return input;
+    return (_jsxs(VStack, { gap: 1, children: [input, _jsx(Description, { text: field.description })] }));
 }
-/** Room a short field takes: numbers, dates, menus and one-line text sit side by side. */
+/** Room a short field takes: numbers, dates, menus, and one-line text sit side by side. */
 const SHORT_FIELD_PX = 200;
 /** Segments whose labels run this long in all still fit a short field's width. */
 const SHORT_SEGMENT_CHARS = 18;
@@ -109,14 +135,16 @@ function isShort({ control }) {
             return false;
     }
 }
-function ObjectFields({ schema, value, onChange }) {
-    return (_jsx(Grid, { columns: { minWidth: SHORT_FIELD_PX, repeat: 'fill' }, gap: 3, children: schemaFields(schema).map((field) => (_jsx("div", { style: isShort(field) ? { minWidth: 0, alignSelf: 'end' } : { gridColumn: '1 / -1', minWidth: 0 }, children: _jsx(Field, { field: field, value: value[field.key], onChange: (next) => onChange(withField(value, field.key, next)) }) }, field.key))) }));
+function ObjectFields({ schema, value, onChange, }) {
+    return (_jsx(Grid, { columns: { minWidth: SHORT_FIELD_PX, repeat: 'fill' }, gap: 3, children: schemaFields(schema).map((field) => (_jsx("div", { style: isShort(field)
+                ? { minWidth: 0, alignSelf: 'start' }
+                : { gridColumn: '1 / -1', minWidth: 0 }, children: _jsx(Field, { field: field, value: value[field.key], onChange: (next) => onChange(withField(value, field.key, next)) }) }, field.key))) }));
 }
 /**
  * A tool's request as a form drawn from its input schema: each field the
  * input its type asks for, labelled by its title or key and described by its
  * description. Optional fields left empty aren't sent.
  */
-export function SchemaFields({ schema, value, onChange }) {
+export function SchemaFields({ schema, value, onChange, }) {
     return _jsx(ObjectFields, { schema: schema, value: value, onChange: onChange });
 }

package/ui/ShapedData.js

@@ -14,8 +14,14 @@ import { Token } from '@astryxdesign/core/Token';
 import { VStack } from '@astryxdesign/core/VStack';
 import { Component, useMemo, useState } from 'react';
 import { fieldLabel, fieldReading, isPlain, isProse, isRow, json, MAX_ROWS, plainReading, rowHeading, shapeOf, splitFields, unpacked, withUnit, } from "../client/shaped-data.js";
+import { Arrive, useArrive } from "./arrive.js";
 import { useLabels } from "./labels-provider.js";
+import { useMarkdownPlugins } from "./markdown-plugins.js";
+import { keyedByContent } from "./row-keys.js";
 /** Each way a plain value reads, drawn. */
+function ProseReading({ text }) {
+    return (_jsx(Markdown, { density: "compact", headingLevelStart: 4, plugins: useMarkdownPlugins(), children: text }));
+}
 const READINGS = {
     none: () => _jsx(Text, { color: "secondary", children: "\u2014" }),
     boolean: ({ value }, _, t) => t(value ? '@theorem.data.yes' : '@theorem.data.no'),
@@ -23,18 +29,18 @@ const READINGS = {
     link: ({ href }) => (_jsx(Link, { href: href, target: "_blank", rel: "noreferrer", children: href })),
     date: ({ date }, formats) => formats.date.format(date),
     'date-time': ({ date }, formats) => formats.dateTime.format(date),
-    // Prose (an answer, a summary) is usually Markdown; headings start small, under the section's own.
-    text: ({ text }) => isProse(text) ? (_jsx(Markdown, { density: "compact", headingLevelStart: 4, children: text })) : (_jsx("span", { style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: text })),
+    // why: Prose (an answer, a summary) is usually Markdown; headings start small, under the section's own.
+    text: ({ text }) => isProse(text) ? (_jsx(ProseReading, { text: text })) : (_jsx("span", { style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: text })),
 };
 function Plain({ value, unit }) {
     const t = useLabels();
     const locale = useLocale();
     const formats = useMemo(() => ({
-        // No grouping: ids and years read as written. Six significant digits: a timing reads 1.40369.
+        // why: No grouping: ids and years read as written. Six significant digits: a timing reads 1.40369.
         integer: new Intl.NumberFormat(locale, { useGrouping: false }),
         decimal: new Intl.NumberFormat(locale, { useGrouping: false, maximumSignificantDigits: 6 }),
         dateTime: new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short' }),
-        // A bare date is a calendar day, parsed at UTC midnight: read it in UTC, or it slips a day west of Greenwich.
+        // why: A bare date is a calendar day, parsed at UTC midnight: read it in UTC, or it slips a day west of Greenwich.
         date: new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeZone: 'UTC' }),
     }), [locale]);
     const reading = plainReading(value, unit);
@@ -53,7 +59,7 @@ function More({ total }) {
         return null;
     return (_jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.data.more', { count: String(total - MAX_ROWS) }) }));
 }
-function DataTable({ columns, rows, units }) {
+function DataTable({ columns, rows, units, }) {
     const tableColumns = columns.map((key, index) => {
         const { label, unit } = fieldLabel(key, units);
         return {
@@ -74,46 +80,80 @@ function ListRowEnd({ row }) {
                 return (_jsxs(Text, { type: "supporting", color: "secondary", children: [label, " ", _jsx(Plain, { value: value, unit: unit })] }, key));
             }), row.tags.map((tag) => (_jsx(Token, { label: tag, size: "sm" }, tag)))] }));
 }
-function DataList({ rows }) {
-    return (_jsxs(VStack, { gap: 1, children: [_jsx(List, { hasDividers: true, density: "compact", children: rows.slice(0, MAX_ROWS).map((row, index) => (_jsx(ListItem
-                // biome-ignore lint/suspicious/noArrayIndexKey: rows have no identity of their own
-                , { label: row.title, description: row.description, href: row.href, target: row.href ? '_blank' : undefined, rel: row.href ? 'noreferrer' : undefined, endContent: _jsx(ListRowEnd, { row: row }) }, index))) }), _jsx(More, { total: rows.length })] }));
+function dataListItem(row) {
+    return {
+        label: row.title,
+        description: row.description,
+        href: row.href,
+        target: row.href ? '_blank' : undefined,
+        rel: row.href ? 'noreferrer' : undefined,
+        endContent: _jsx(ListRowEnd, { row: row }),
+    };
 }
-function Rows({ items, depth }) {
+/** A top-level row eases in with the rest of a returned result. Nested rows stay put. */
+function ArrivingDataRow({ row }) {
+    const arrive = useArrive();
+    return _jsx(ListItem, { className: arrive?.className, style: arrive?.style, ...dataListItem(row) });
+}
+function DataList({ rows, depth }) {
+    return (_jsxs(VStack, { gap: 1, children: [_jsx(List, { hasDividers: true, density: "compact", children: keyedByContent(rows.slice(0, MAX_ROWS), (row) => row.title).map(({ item: row, key }) => depth === 0 ? (_jsx(ArrivingDataRow, { row: row }, key)) : (_jsx(ListItem, { ...dataListItem(row) }, key))) }), _jsx(More, { total: rows.length })] }));
+}
+function ObjectRow({ item, index, depth, className, style, }) {
     const t = useLabels();
-    return (_jsxs(VStack, { gap: 1, children: [_jsx(CollapsibleGroup, { type: "multiple", hasDividers: true, density: "compact", children: items.slice(0, MAX_ROWS).map((item, index) => {
-                    const heading = rowHeading(item);
-                    return (_jsx(Collapsible
-                    // biome-ignore lint/suspicious/noArrayIndexKey: rows have no identity of their own
-                    , { value: String(index), trigger: _jsxs(HStack, { gap: 2, vAlign: "center", wrap: "wrap", children: [_jsx(Text, { type: "body", children: heading.title ?? t('@theorem.data.item', { index: String(index + 1) }) }), heading.tags.map((tag) => (_jsx(Token, { label: tag, size: "sm" }, tag)))] }), children: _jsx(Node, { value: heading.rest, depth: depth + 1 }) }, index));
-                }) }), _jsx(More, { total: items.length })] }));
+    const heading = rowHeading(item);
+    return (_jsx(Collapsible, { className: className, style: style, value: String(index), trigger: _jsxs(HStack, { gap: 2, vAlign: "center", wrap: "wrap", children: [_jsx(Text, { type: "body", children: heading.title ?? t('@theorem.data.item', { index: String(index + 1) }) }), heading.tags.map((tag) => (_jsx(Token, { label: tag, size: "sm" }, tag)))] }), children: _jsx(Node, { value: heading.rest, depth: depth + 1 }) }));
+}
+/** A top-level object row eases in with the result. One nested under it does not. */
+function ArrivingObjectRow({ item, index, depth, }) {
+    const arrive = useArrive();
+    return (_jsx(ObjectRow, { item: item, index: index, depth: depth, className: arrive?.className, style: arrive?.style }));
+}
+function Rows({ items, depth }) {
+    return (_jsxs(VStack, { gap: 1, children: [_jsx(CollapsibleGroup, { type: "multiple", hasDividers: true, density: "compact", children: keyedByContent(items.slice(0, MAX_ROWS), (item) => JSON.stringify(item) ?? '').map(({ item, index, key }) => depth === 0 ? (_jsx(ArrivingObjectRow, { item: item, index: index, depth: depth }, key)) : (_jsx(ObjectRow, { item: item, index: index, depth: depth }, key))) }), _jsx(More, { total: items.length })] }));
+}
+function FieldSection({ shown, depth, className, style, }) {
+    return (_jsx(Collapsible, { className: className, style: style, value: shown.key, trigger: _jsx(Text, { type: "label", children: shown.title }), children: _jsx(VStack, { paddingInlineStart: 3, children: _jsx(Node, { value: shown.value, depth: depth + 1, units: shown.units }) }) }));
+}
+function ArrivingFieldSection({ shown, depth }) {
+    const arrive = useArrive();
+    return (_jsx(FieldSection, { shown: shown, depth: depth, className: arrive?.className, style: arrive?.style }));
 }
 function Fields({ row, depth, units }) {
     const { plain, sections } = splitFields(row);
     const fields = plain.length > 0 && (_jsx(MetadataList, { label: { position: 'start', width: '40%' }, children: plain.map(([key, value]) => {
             const { label, unit } = fieldReading(key, value, units);
-            return (_jsx(MetadataListItem, { label: label, children: Array.isArray(unpacked(value)) ? _jsx(Node, { value: value, depth: depth + 1 }) : _jsx(Plain, { value: value, unit: unit }) }, key));
+            return (_jsx(MetadataListItem, { label: label, children: Array.isArray(unpacked(value)) ? (_jsx(Node, { value: value, depth: depth + 1 })) : (_jsx(Plain, { value: value, unit: unit })) }, key));
         }) }));
     return (_jsxs(VStack, { gap: 2, children: [depth > 0 && fields, sections.length > 0 && (_jsx(CollapsibleGroup, { type: "multiple", hasDividers: true, density: "compact", 
-                // The top level's first section starts open: it's usually the payload. The rest wait to be asked for.
-                defaultValue: depth === 0 ? sections.slice(0, 1).map((shown) => shown.key) : [], children: sections.map((shown) => (_jsx(Collapsible, { value: shown.key, trigger: _jsx(Text, { type: "label", children: shown.title }), children: _jsx(VStack, { paddingInlineStart: 3, children: _jsx(Node, { value: shown.value, depth: depth + 1, units: shown.units }) }) }, shown.key))) })), depth === 0 && fields] }));
+                // why: The top level's first section starts open: it's usually the payload. The rest wait to be asked for.
+                defaultValue: depth === 0 ? sections.slice(0, 1).map((shown) => shown.key) : [], children: sections.map((shown) => depth === 0 ? (_jsx(ArrivingFieldSection, { shown: shown, depth: depth }, shown.key)) : (_jsx(FieldSection, { shown: shown, depth: depth }, shown.key))) })), depth === 0 && fields ? _jsx(Arrive, { children: fields }) : null] }));
 }
 /** Each shape a value takes, drawn. */
 const SHAPES = {
     json: (_, { value }) => _jsx(Json, { text: json(value) }),
     none: (_, { t }) => _jsx(Text, { color: "secondary", children: t('@theorem.data.none') }),
     plain: (_, { value }) => (_jsx(Text, { type: "body", children: _jsx(Plain, { value: value }) })),
-    tokens: ({ items }) => (_jsxs(VStack, { gap: 1, children: [_jsx(HStack, { gap: 1, wrap: "wrap", children: items.slice(0, MAX_ROWS).map((item, index) => (_jsx(Token, { label: item === null ? '—' : String(item), size: "sm" }, index))) }), _jsx(More, { total: items.length })] })),
-    list: ({ rows }) => _jsx(DataList, { rows: rows }),
-    table: ({ columns, rows }, { units }) => _jsx(DataTable, { columns: columns, rows: rows, units: units }),
+    tokens: ({ items }) => (_jsxs(VStack, { gap: 1, children: [_jsx(HStack, { gap: 1, wrap: "wrap", children: keyedByContent(items.slice(0, MAX_ROWS), (item) => String(item)).map(({ item, key }) => (_jsx(Token, { label: item === null ? '—' : String(item), size: "sm" }, key))) }), _jsx(More, { total: items.length })] })),
+    list: ({ rows }, { depth }) => _jsx(DataList, { rows: rows, depth: depth }),
+    table: ({ columns, rows }, { units }) => (_jsx(DataTable, { columns: columns, rows: rows, units: units })),
     rows: ({ items }, { depth }) => _jsx(Rows, { items: items, depth: depth }),
     fields: ({ row }, { depth, units }) => _jsx(Fields, { row: row, depth: depth, units: units }),
 };
-function Node({ value: raw, depth, units }) {
+function Node({ value: raw, depth, units, }) {
     const t = useLabels();
     const value = unpacked(raw);
     const shape = shapeOf(value, depth);
-    return SHAPES[shape.kind](shape, { value, depth, units, t });
+    const body = SHAPES[shape.kind](shape, {
+        value,
+        depth,
+        units,
+        t,
+    });
+    // why: A list, a set of rows, or an object's sections stagger their own children. Anything else at the top of a result is one arrival.
+    if (depth !== 0 || shape.kind === 'list' || shape.kind === 'rows' || shape.kind === 'fields') {
+        return body;
+    }
+    return _jsx(Arrive, { children: body });
 }
 /** A render the rules didn't foresee throws into the JSON, never into the transcript. */
 class ShapeBoundary extends Component {
@@ -121,6 +161,9 @@ class ShapeBoundary extends Component {
     static getDerivedStateFromError() {
         return { failed: true };
     }
+    componentDidCatch() {
+        this.props.onFallback();
+    }
     render() {
         return this.state.failed ? this.props.fallback : this.props.children;
     }
@@ -131,10 +174,8 @@ export function ShapedData({ value: raw, title, lead, ledKeys = [] }) {
     const locale = useLocale();
     const [view, setView] = useState('data');
     const value = unpacked(raw);
-    // A plain value reads the same either way; only structure gets the switch.
     const structured = !isPlain(value);
     const text = useMemo(() => (structured ? json(value) : ''), [structured, value]);
-    // What the lead hasn't shown; nothing when it showed every field.
     const rest = useMemo(() => {
         if (!ledKeys.length || !isRow(value))
             return value;
@@ -142,10 +183,14 @@ export function ShapedData({ value: raw, title, lead, ledKeys = [] }) {
         return left.length ? Object.fromEntries(left) : undefined;
     }, [value, ledKeys]);
     if (text.length > LARGE_JSON_CHARS) {
-        const size = new Intl.NumberFormat(locale, { style: 'unit', unit: 'kilobyte', maximumFractionDigits: 0 }).format(LARGE_JSON_CHARS / 1000);
+        const size = new Intl.NumberFormat(locale, {
+            style: 'unit',
+            unit: 'kilobyte',
+            maximumFractionDigits: 0,
+        }).format(LARGE_JSON_CHARS / 1000);
         return (_jsxs(VStack, { gap: 2, children: [_jsx(Text, { type: "supporting", color: "secondary", children: title }), _jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.data.large', { size }) }), _jsx(Json, { text: text })] }));
     }
     return (_jsxs(VStack, { gap: 2, children: [_jsxs(HStack, { gap: 2, vAlign: "center", hAlign: "between", children: [_jsx(Text, { type: "supporting", color: "secondary", children: title }), structured && (_jsxs(SegmentedControl, { label: t('@theorem.data.view'), size: "sm", value: view, onChange: (next) => {
                             setView(next === 'json' ? 'json' : 'data');
-                        }, children: [_jsx(SegmentedControlItem, { value: "data", label: t('@theorem.data.shaped') }), _jsx(SegmentedControlItem, { value: "json", label: t('@theorem.data.json') })] }))] }), view === 'json' && structured ? (_jsx(Json, { text: text })) : (_jsx(ShapeBoundary, { fallback: _jsx(Json, { text: text }), children: _jsxs(VStack, { gap: 3, children: [lead, rest === undefined ? null : _jsx(Node, { value: rest, depth: 0 })] }) }))] }));
+                        }, children: [_jsx(SegmentedControlItem, { value: "data", label: t('@theorem.data.shaped') }), _jsx(SegmentedControlItem, { value: "json", label: t('@theorem.data.json') })] }))] }), view === 'json' && structured ? (_jsx(Json, { text: text })) : (_jsx(ShapeBoundary, { fallback: _jsx(Json, { text: text }), onFallback: () => setView('json'), children: _jsxs(VStack, { gap: 3, children: [lead, rest === undefined ? null : _jsx(Node, { value: rest, depth: 0 })] }) }))] }));
 }

package/ui/SidePanel.d.ts

@@ -10,8 +10,9 @@ export declare function useSidePanel(containerRef: RefObject<HTMLDivElement | nu
     resizable: ResizableRegion;
 };
 /** The Layout header row: side panel toggles, at the end. */
-export declare function SidePanelHeader({ children }: {
+export declare function SidePanelHeader({ children, floating, }: {
     children?: ReactNode;
+    floating?: boolean;
 }): import("react").JSX.Element;
 /** A side panel's words: its name, and its toggle and drag handle actions. */
 export type SidePanelLabels = {
@@ -41,17 +42,85 @@ export type SidePanelProps = {
     open?: boolean;
     /** Card padding; 0 for content that brings its own (e.g. ChatLayout). */
     padding?: 0;
+    /**
+     * `end` docks on the trailing edge: the handle, then the panel. `start`
+     * docks on the leading edge: the panel, then the handle.
+     */
+    side?: 'start' | 'end';
+    className?: string;
     children?: ReactNode;
 };
 /** Page corners like the host's raised panels, no border or shadow; the card fill, so surface-filled cards read on it. */
 export declare const RAISED: {
     background: string;
     borderRadius: string;
+    overflow: string;
 };
+/** A docked panel's inset: 12px off the outer edge, 16px off the bottom (the page inset). */
+export declare const PANEL_EDGE = 3;
+export declare const PANEL_BOTTOM = 4;
+/** The raised card every docked panel and the content beside one share. */
+export declare function PanelBody({ padding, inset, className, children, }: {
+    padding?: 0;
+    /**
+     * `end` insets the trailing edge (a panel docked there, or the content
+     * filling beside a start panel). `start` insets the leading edge. `beside`
+     * insets both.
+     */
+    inset?: 'end' | 'start' | 'beside';
+    className?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** The scroll inside a panel card. The same area the trace uses, so a short body sizes to its rows. */
+export declare function PanelScroll({ label, padding, children, }: {
+    label: string;
+    padding?: 4;
+    children?: ReactNode;
+}): import("react").JSX.Element;
 /**
- * A Layout `end` panel as Astryx's IDE template builds one (a reversed
- * `ResizeHandle` before a `LayoutPanel` sized by `useResizable`), holding a
- * raised section inset from the layout edge and bottom instead of a flat pane.
+ * A Layout side panel as Astryx's IDE template builds one (a `ResizeHandle`
+ * beside a `LayoutPanel` sized by `useResizable`), holding a raised section
+ * inset from the layout's outer edge and bottom instead of a flat pane.
+ * `end` puts the handle first and reverses it; `start` puts the panel first.
  * For more than one panel, nest Layouts, one panel each, as the template does.
  */
-export declare function SidePanel({ id, labels, resizable, open, padding, children }: SidePanelProps): import("react").JSX.Element;
+export declare function SidePanel({ id, labels, resizable, open, padding, side, className, children, }: SidePanelProps): import("react").JSX.Element;
+/** The element's width, kept current. */
+export declare function useWidth(): {
+    ref: (node: HTMLDivElement | null) => (() => void) | undefined;
+    width: number;
+};
+/**
+ * A raised pane that fills its place, inset from the sides. Its content is
+ * told whether the pane is wide enough for two readable columns.
+ */
+export declare function RaisedPane({ id, header, children, }: {
+    id?: string;
+    header?: ReactNode;
+    children: (isWide: boolean) => ReactNode;
+}): import("react").JSX.Element;
+/** A raised pane's content. Narrow, the detail takes the overview's place; wide, it sits beside it. */
+export declare function PaneLayout({ isWide, label, detailLabel, lead, overview, detail, }: {
+    isWide: boolean;
+    label: string;
+    detailLabel: string;
+    /** Rendered once, ahead of the content. */
+    lead?: ReactNode;
+    overview: ReactNode;
+    detail: ReactNode;
+}): import("react").JSX.Element;
+/** One titled block of a pane's detail; `doc` says what the title means, on hover. */
+export declare function PanePanel({ title, doc, children, }: {
+    title: string;
+    doc?: string;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Text as it was written: its line breaks kept, long words wrapped. */
+export declare function Prose({ text }: {
+    text: string;
+}): import("react").JSX.Element;
+/** The surface, or the view in its place; the surface stays mounted underneath, so nothing it holds is lost. */
+export declare function InPlace({ view, children }: {
+    view: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/ui/SidePanel.js

@@ -2,8 +2,12 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
 import { Card } from '@astryxdesign/core/Card';
 import { HStack } from '@astryxdesign/core/HStack';
 import { IconButton } from '@astryxdesign/core/IconButton';
-import { LayoutHeader, LayoutPanel } from '@astryxdesign/core/Layout';
+import { Layout, LayoutContent, LayoutHeader, LayoutPanel } from '@astryxdesign/core/Layout';
 import { ResizeHandle, useResizable, } from '@astryxdesign/core/Resizable';
+import { ScrollableArea } from '@astryxdesign/core/ScrollableArea';
+import { StackItem } from '@astryxdesign/core/Stack';
+import { Text } from '@astryxdesign/core/Text';
+import { Tooltip as HoverTip } from '@astryxdesign/core/Tooltip';
 import { VStack } from '@astryxdesign/core/VStack';
 import { useCallback, useId, useState } from 'react';
 /**
@@ -29,22 +33,91 @@ export function useSidePanel(containerRef, initiallyOpen) {
     return { id, open, toggle, resizable };
 }
 /** The Layout header row: side panel toggles, at the end. */
-export function SidePanelHeader({ children }) {
+export function SidePanelHeader({ children, floating = false, }) {
+    if (floating)
+        return (_jsx("div", { style: {
+                position: 'absolute',
+                insetBlockStart: 'var(--spacing-4)',
+                insetInlineEnd: 'var(--spacing-4)',
+                zIndex: 3,
+            }, children: _jsx(HStack, { hAlign: "end", gap: 1, children: children }) }));
     return (_jsx(LayoutHeader, { hasDivider: false, children: _jsx(HStack, { hAlign: "end", gap: 1, children: children }) }));
 }
 /** Shows or hides one side panel (`panelId` from useSidePanel). */
 export function SidePanelToggle({ labels, icon, panelId, open, onToggle, }) {
     const action = open ? labels.hide : labels.show;
-    return (_jsx(IconButton, { label: action, tooltip: action, variant: "ghost", "aria-expanded": open, "aria-controls": panelId, icon: icon, onClick: onToggle }));
+    return (_jsx(IconButton, { label: action, tooltip: action, variant: open ? 'secondary' : 'ghost', "aria-expanded": open, "aria-controls": panelId, icon: icon, onClick: onToggle }));
 }
 /** Page corners like the host's raised panels, no border or shadow; the card fill, so surface-filled cards read on it. */
-export const RAISED = { background: 'var(--color-background-card)', borderRadius: 'var(--radius-page)' };
+export const RAISED = {
+    background: 'var(--theorem-pane-background, var(--color-background-card))',
+    borderRadius: 'var(--radius-page)',
+    overflow: 'hidden',
+};
+/** A docked panel's inset: 12px off the outer edge, 16px off the bottom (the page inset). */
+export const PANEL_EDGE = 3;
+export const PANEL_BOTTOM = 4;
+/** The raised card every docked panel and the content beside one share. */
+export function PanelBody({ padding, inset = 'end', className, children, }) {
+    return (_jsx(VStack, { height: "100%", className: className, paddingInlineStart: inset === 'end' ? undefined : PANEL_EDGE, paddingInlineEnd: inset === 'start' ? undefined : PANEL_EDGE, paddingBlockEnd: PANEL_BOTTOM, children: _jsx(Card, { variant: "transparent", height: "100%", padding: padding, style: RAISED, children: children }) }));
+}
+/** The scroll inside a panel card. The same area the trace uses, so a short body sizes to its rows. */
+export function PanelScroll({ label, padding, children, }) {
+    return (_jsx(ScrollableArea, { className: "theorem-panel-scroll", label: label, height: "100%", padding: padding, children: children }));
+}
 /**
- * A Layout `end` panel as Astryx's IDE template builds one (a reversed
- * `ResizeHandle` before a `LayoutPanel` sized by `useResizable`), holding a
- * raised section inset from the layout edge and bottom instead of a flat pane.
+ * A Layout side panel as Astryx's IDE template builds one (a `ResizeHandle`
+ * beside a `LayoutPanel` sized by `useResizable`), holding a raised section
+ * inset from the layout's outer edge and bottom instead of a flat pane.
+ * `end` puts the handle first and reverses it; `start` puts the panel first.
  * For more than one panel, nest Layouts, one panel each, as the template does.
  */
-export function SidePanel({ id, labels, resizable, open = true, padding, children }) {
-    return (_jsxs(_Fragment, { children: [open ? (_jsx(ResizeHandle, { direction: "horizontal", isReversed: true, hasDivider: false, isAlwaysVisible: false, resizable: resizable.props, label: labels.resize })) : null, _jsx(LayoutPanel, { id: id, label: labels.name, role: "complementary", width: open ? resizable.size : 0, hasDivider: false, padding: 0, isScrollable: false, inert: !open, children: _jsx(VStack, { height: "100%", paddingInlineEnd: 3, paddingBlockEnd: 3, children: _jsx(Card, { variant: "transparent", height: "100%", padding: padding, style: RAISED, children: open ? children : null }) }) })] }));
+export function SidePanel({ id, labels, resizable, open = true, padding, side = 'end', className, children, }) {
+    const handle = open ? (_jsx(ResizeHandle, { direction: "horizontal", isReversed: side === 'end', hasDivider: false, isAlwaysVisible: false, resizable: resizable.props, label: labels.resize })) : null;
+    const panel = (_jsx(LayoutPanel, { id: id, className: className, label: labels.name, role: "complementary", width: open ? resizable.size : 0, hasDivider: false, padding: 0, isScrollable: false, inert: !open, children: _jsx(PanelBody, { padding: padding, inset: side, children: open ? children : null }) }));
+    return side === 'start' ? (_jsxs(_Fragment, { children: [panel, handle] })) : (_jsxs(_Fragment, { children: [handle, panel] }));
+}
+/** The element's width, kept current. */
+export function useWidth() {
+    const [width, setWidth] = useState(0);
+    const ref = useCallback((node) => {
+        if (!node)
+            return;
+        const observer = new ResizeObserver(([entry]) => setWidth(entry?.contentRect.width ?? 0));
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, []);
+    return { ref, width };
+}
+/**
+ * A raised pane that fills its place, inset from the sides. Its content is
+ * told whether the pane is wide enough for two readable columns.
+ */
+export function RaisedPane({ id, header, children, }) {
+    const { ref, width } = useWidth();
+    return (_jsx(Layout, { height: "fill", style: { position: 'relative' }, header: header, content: _jsx(LayoutContent, { padding: 0, isScrollable: false, children: _jsx(VStack, { height: "100%", padding: 3, children: _jsx(Card, { variant: "transparent", height: "100%", padding: 0, style: RAISED, children: _jsx("div", { id: id, ref: ref, style: { height: '100%' }, children: children(isSidePanelWide(width)) }) }) }) }) }));
+}
+/** A raised pane's content. Narrow, the detail takes the overview's place; wide, it sits beside it. */
+export function PaneLayout({ isWide, label, detailLabel, lead, overview, detail, }) {
+    if (!isWide) {
+        return (_jsxs(PanelScroll, { label: label, children: [lead, detail || overview] }));
+    }
+    return (_jsxs(HStack, { height: "100%", gap: 0, children: [_jsx(StackItem, { size: "fill", children: _jsxs(PanelScroll, { label: label, children: [lead, overview] }) }), detail ? (_jsx("div", { style: {
+                    width: '48%',
+                    flexShrink: 0,
+                    height: '100%',
+                    borderInlineStart: '1px solid var(--color-border)',
+                }, children: _jsx(PanelScroll, { label: detailLabel, children: detail }) })) : null] }));
+}
+/** One titled block of a pane's detail; `doc` says what the title means, on hover. */
+export function PanePanel({ title, doc, children, }) {
+    return (_jsx(Card, { padding: 3, variant: "muted", style: { background: 'var(--color-background-surface)' }, children: _jsxs(VStack, { gap: 2, children: [_jsx(HoverTip, { content: doc ?? title, children: _jsx(Text, { type: "supporting", color: "secondary", children: title }) }), children] }) }));
+}
+/** Text as it was written: its line breaks kept, long words wrapped. */
+export function Prose({ text }) {
+    return _jsx("span", { style: { whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: text });
+}
+/** The surface, or the view in its place; the surface stays mounted underneath, so nothing it holds is lost. */
+export function InPlace({ view, children }) {
+    return (_jsxs(_Fragment, { children: [view, _jsx("div", { style: { display: view ? 'none' : 'contents' }, children: children })] }));
 }

package/ui/StateFields.d.ts

@@ -1,15 +1,23 @@
 import type { DecisionJson } from '@theoremjs/agents';
+import { type DecisionImages } from '../client/decision-images.ts';
 export type Edit<T = DecisionJson> = {
     value: T;
     onChange: (next: T) => void;
 };
+/** A text area's height: one row per line of its text, within `min` and `max`. Wrapped lines do not count. */
+export declare function textRows(text: string, min: number, max: number): number;
+/** The images the state names, and how to change them; a field whose whole text names one shows it. */
+export declare const StateImages: import("react").Context<{
+    images: DecisionImages;
+    onImages: (next: DecisionImages) => void;
+}>;
 export type GroupLabel = {
     label: string;
     isRequired?: boolean;
-    description?: string;
+    description?: React.ReactNode;
 };
 /** Several fields under one name, in the same label a single field has. */
-export declare function Labelled({ label, isRequired, description, children }: GroupLabel & {
+export declare function Labelled({ label, isRequired, description, children, }: GroupLabel & {
     children: React.ReactNode;
 }): import("react").JSX.Element;
 /** Nested fields sit under their name, set in by a rule. */