@theoremjs/react 0.0.0-stage → 0.3.1

package/ui/ShapedData.js

@@ -0,0 +1,196 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CodeBlock } from '@astryxdesign/core/CodeBlock';
+import { Collapsible, CollapsibleGroup } from '@astryxdesign/core/Collapsible';
+import { HStack } from '@astryxdesign/core/HStack';
+import { useLocale } from '@astryxdesign/core/i18n';
+import { Link } from '@astryxdesign/core/Link';
+import { List, ListItem } from '@astryxdesign/core/List';
+import { Markdown } from '@astryxdesign/core/Markdown';
+import { MetadataList, MetadataListItem } from '@astryxdesign/core/MetadataList';
+import { SegmentedControl, SegmentedControlItem } from '@astryxdesign/core/SegmentedControl';
+import { Table } from '@astryxdesign/core/Table';
+import { Text } from '@astryxdesign/core/Text';
+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'),
+    number: ({ value, unit }, formats) => withUnit((Number.isInteger(value) ? formats.integer : formats.decimal).format(value), unit),
+    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),
+    // 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(() => ({
+        // 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' }),
+        // 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);
+    return READINGS[reading.kind](reading, formats, t);
+}
+/** JSON past this many characters isn't laid out or highlighted in full: the page stays responsive however big the payload. */
+const LARGE_JSON_CHARS = 200_000;
+function Json({ text }) {
+    const code = text.length > LARGE_JSON_CHARS ? `${text.slice(0, LARGE_JSON_CHARS)}\n…` : text;
+    return _jsx(CodeBlock, { code: code, language: "json", hasLanguageLabel: false, size: "sm", width: "100%" });
+}
+/** Past MAX_ROWS, a note that the rest are in the JSON view. */
+function More({ total }) {
+    const t = useLabels();
+    if (total <= MAX_ROWS)
+        return null;
+    return (_jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.data.more', { count: String(total - MAX_ROWS) }) }));
+}
+function DataTable({ columns, rows, units, }) {
+    const tableColumns = columns.map((key, index) => {
+        const { label, unit } = fieldLabel(key, units);
+        return {
+            key: `c${String(index)}`,
+            header: unit ? `${label} (${unit})` : label,
+            renderCell: (row) => _jsx(Plain, { value: row.cells[key] }),
+        };
+    });
+    const data = rows.slice(0, MAX_ROWS).map((cells, index) => ({ id: String(index), cells }));
+    return (_jsxs(VStack, { gap: 1, children: [_jsx(Table, { data: data, columns: tableColumns, idKey: "id", density: "compact", textOverflow: "truncate" }), _jsx(More, { total: rows.length })] }));
+}
+/** A list row's extra fields and tags, at its end. */
+function ListRowEnd({ row }) {
+    if (row.tags.length + row.extras.length === 0)
+        return undefined;
+    return (_jsxs(HStack, { gap: 2, vAlign: "center", children: [row.extras.map(([key, value]) => {
+                const { label, unit } = fieldReading(key, value);
+                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 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 }),
+    };
+}
+/** 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();
+    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 (_jsxs(VStack, { gap: 2, children: [depth > 0 && fields, sections.length > 0 && (_jsx(CollapsibleGroup, { type: "multiple", hasDividers: true, density: "compact", 
+                // 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: 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, }) {
+    const t = useLabels();
+    const value = unpacked(raw);
+    const shape = shapeOf(value, depth);
+    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 {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch() {
+        this.props.onFallback();
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+/** A tool call's input, output or failure, or a structured reply, with a switch to its JSON. */
+export function ShapedData({ value: raw, title, lead, ledKeys = [] }) {
+    const t = useLabels();
+    const locale = useLocale();
+    const [view, setView] = useState('data');
+    const value = unpacked(raw);
+    const structured = !isPlain(value);
+    const text = useMemo(() => (structured ? json(value) : ''), [structured, value]);
+    const rest = useMemo(() => {
+        if (!ledKeys.length || !isRow(value))
+            return value;
+        const left = Object.entries(value).filter(([key]) => !ledKeys.includes(key));
+        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);
+        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 }), onFallback: () => setView('json'), children: _jsxs(VStack, { gap: 3, children: [lead, rest === undefined ? null : _jsx(Node, { value: rest, depth: 0 })] }) }))] }));
+}

package/ui/SidePanel.d.ts

@@ -0,0 +1,126 @@
+import { type ResizableRegion } from '@astryxdesign/core/Resizable';
+import { type ReactNode, type RefObject } from 'react';
+/** Whether a side panel is wide enough for two readable columns: twice its minimum. */
+export declare function isSidePanelWide(size: number): boolean;
+/** A side panel's open state and size. `containerRef` is the Layout its percentages resolve against. */
+export declare function useSidePanel(containerRef: RefObject<HTMLDivElement | null>, initiallyOpen: boolean): {
+    id: string;
+    open: boolean;
+    toggle: () => void;
+    resizable: ResizableRegion;
+};
+/** The Layout header row: side panel toggles, at the end. */
+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 = {
+    name: string;
+    show: string;
+    hide: string;
+    resize: string;
+};
+/** Shows or hides one side panel (`panelId` from useSidePanel). */
+export declare function SidePanelToggle({ labels, icon, panelId, open, onToggle, }: {
+    labels: SidePanelLabels;
+    icon: ReactNode;
+    panelId: string;
+    open: boolean;
+    onToggle: () => void;
+}): import("react").JSX.Element;
+export type SidePanelProps = {
+    id?: string;
+    labels: SidePanelLabels;
+    /** From `useResizable`: the panel's width and its handle's drag state. */
+    resizable: ResizableRegion;
+    /**
+     * Closed panels stay mounted at zero width and inert, so the theme can ease
+     * their width; their content renders only while open, so it never reflows
+     * into the collapsing width.
+     */
+    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 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, 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

@@ -0,0 +1,123 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card } from '@astryxdesign/core/Card';
+import { HStack } from '@astryxdesign/core/HStack';
+import { IconButton } from '@astryxdesign/core/IconButton';
+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';
+/**
+ * `useResizable` sizing for side panels: a third of the layout (pass the
+ * Layout as `containerRef` so the percentages resolve), dragged between a
+ * readable minimum and half.
+ */
+const SIDE_PANEL_SIZING = {
+    defaultSize: '33%',
+    minSize: 280,
+    maxSize: '50%',
+};
+/** Whether a side panel is wide enough for two readable columns: twice its minimum. */
+export function isSidePanelWide(size) {
+    return size >= SIDE_PANEL_SIZING.minSize * 2;
+}
+/** A side panel's open state and size. `containerRef` is the Layout its percentages resolve against. */
+export function useSidePanel(containerRef, initiallyOpen) {
+    const id = useId();
+    const [open, setOpen] = useState(initiallyOpen);
+    const toggle = useCallback(() => setOpen((value) => !value), []);
+    const resizable = useResizable({ ...SIDE_PANEL_SIZING, containerRef });
+    return { id, open, toggle, resizable };
+}
+/** The Layout header row: side panel toggles, at the end. */
+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: 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(--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 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, 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

@@ -0,0 +1,44 @@
+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?: React.ReactNode;
+};
+/** Several fields under one name, in the same label a single field has. */
+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. */
+export declare function Group({ children, ...label }: GroupLabel & {
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+/** One more row at the end of a list. */
+export declare function AddRow({ field, onAdd }: {
+    field: string;
+    onAdd: () => void;
+}): import("react").JSX.Element;
+/** Removes a list's row, named by its place. */
+export declare function RemoveRow({ index, onRemove }: {
+    index: number;
+    onRemove: () => void;
+}): import("react").JSX.Element;
+/**
+ * A decision's state edited field by field: objects as labelled fields, lists
+ * of words as tokens, other lists as rows. The shape itself (new keys, other
+ * types) is edited as JSON.
+ */
+export declare function StateFields({ value, onChange, label }: Edit & {
+    label: string;
+}): import("react").JSX.Element;

package/ui/StateFields.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@astryxdesign/core/Button';
+import { FieldLabel } from '@astryxdesign/core/Field';
+import { FileInput } from '@astryxdesign/core/FileInput';
+import { HStack } from '@astryxdesign/core/HStack';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { Lightbox } from '@astryxdesign/core/Lightbox';
+import { NumberInput } from '@astryxdesign/core/NumberInput';
+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 { Thumbnail } from '@astryxdesign/core/Thumbnail';
+import { Tokenizer } from '@astryxdesign/core/Tokenizer';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconPlus, IconX } from '@tabler/icons-react';
+import { createContext, useContext, useId, useState } from 'react';
+import { IMAGE_ACCEPT, imageSrc } from "../client/decision-images.js";
+import { humanize, isPlain } from "../client/shaped-data.js";
+import { blankLike, isWordList, tableColumns } from "../client/state-fields.js";
+import { useImageReader } from "./DecisionImages.js";
+import { useLabels } from "./labels-provider.js";
+import { useKeyedRows } from "./row-keys.js";
+const NO_SUGGESTIONS = { search: () => [], bootstrap: () => [] };
+/** Text this long, or on several lines, gets a text area. */
+const LONG_TEXT = 48;
+/** A text area's height: one row per line of its text, within `min` and `max`. Wrapped lines do not count. */
+export function textRows(text, min, max) {
+    return Math.min(Math.max(text.split('\n').length, min), max);
+}
+/** The images the state names, and how to change them; a field whose whole text names one shows it. */
+export const StateImages = createContext({ images: {}, onImages: () => { } });
+/** A field that holds an image: the image, and a file input that replaces it. */
+function ImageField({ value, label, isLabelHidden, }) {
+    const t = useLabels();
+    const { images, onImages } = useContext(StateImages);
+    const { read, status } = useImageReader();
+    const [isOpen, setOpen] = useState(false);
+    const src = Object.hasOwn(images, value) ? imageSrc(images[value]) : undefined;
+    return (_jsxs(HStack, { gap: 2, vAlign: "center", children: [_jsx(Thumbnail, { src: src, alt: label, label: value, onClick: src ? () => setOpen(true) : undefined }), src ? (_jsx(Lightbox, { isOpen: isOpen, onOpenChange: setOpen, media: { src, alt: label, caption: value }, hasZoom: true })) : null, _jsx(StackItem, { size: "fill", children: _jsx(FileInput, { label: label, isLabelHidden: isLabelHidden, accept: IMAGE_ACCEPT, value: null, placeholder: t('@theorem.decision.replace_image'), status: status, statusVariant: "detached", onChange: (files) => {
+                        void read(files).then(([first]) => {
+                            if (first)
+                                onImages({ ...images, [value]: first[1] });
+                        });
+                    } }) })] }));
+}
+/** A string, number, true/false, or null, as its input. */
+function PlainField({ value, onChange, label, isLabelHidden }) {
+    const { images } = useContext(StateImages);
+    // why: Decided once, so the field doesn't swap inputs (and lose focus) as the text grows or changes.
+    const [isLong] = useState(() => typeof value === 'string' && (value.length > LONG_TEXT || value.includes('\n')));
+    const [isImage] = useState(() => typeof value === 'string' && Object.hasOwn(images, value));
+    if (isImage && typeof value === 'string')
+        return _jsx(ImageField, { value: value, label: label, isLabelHidden: isLabelHidden });
+    if (typeof value === 'boolean')
+        return _jsx(Switch, { label: label, value: value, onChange: onChange });
+    if (typeof value === 'number') {
+        return (_jsx(NumberInput, { label: label, isLabelHidden: isLabelHidden, size: "sm", value: value, isWheelEnabled: false, onChange: onChange }));
+    }
+    if (value === null)
+        return (_jsx(TextInput, { label: label, isLabelHidden: isLabelHidden, size: "sm", value: "", placeholder: "null", isDisabled: true, onChange: () => { } }));
+    const text = String(value);
+    return isLong ? (_jsx(TextArea, { label: label, isLabelHidden: isLabelHidden, size: "sm", rows: textRows(text, 2, 12), value: text, onChange: onChange })) : (_jsx(TextInput, { label: label, isLabelHidden: isLabelHidden, size: "sm", value: text, onChange: onChange }));
+}
+/** Several fields under one name, in the same label a single field has. */
+export function Labelled({ label, isRequired, description, children, }) {
+    const id = useId();
+    return (_jsxs(VStack, { gap: 2, role: "group", "aria-labelledby": id, children: [_jsx(FieldLabel, { label: label, inputID: "", labelID: id, isGroupLabel: true, isRequired: isRequired, description: description }), children] }));
+}
+/** Nested fields sit under their name, set in by a rule. */
+export function Group({ children, ...label }) {
+    return (_jsx(Labelled, { ...label, children: _jsx("div", { style: { paddingInlineStart: 12, borderInlineStart: '1px solid var(--color-border)' }, children: children }) }));
+}
+/** One more row at the end of a list. */
+export function AddRow({ field, onAdd }) {
+    const t = useLabels();
+    return (_jsx(HStack, { children: _jsx(Button, { label: t('@theorem.decision.add_item', { field }), size: "sm", variant: "ghost", icon: _jsx(IconPlus, { size: 14 }), onClick: onAdd }) }));
+}
+/** Removes a list's row, named by its place. */
+export function RemoveRow({ index, onRemove }) {
+    const t = useLabels();
+    return (_jsx(IconButton, { label: t('@theorem.decision.remove_item', {
+            item: t('@theorem.data.item', { index: String(index + 1) }),
+        }), size: "sm", variant: "ghost", icon: _jsx(IconX, { size: 14 }), onClick: onRemove }));
+}
+function ObjectFields({ value, onChange }) {
+    return (_jsx(VStack, { gap: 3, children: Object.entries(value).map(([key, entry]) => (_jsx(Field, { label: humanize(key), value: entry, onChange: (next) => onChange({ ...value, [key]: next }) }, key))) }));
+}
+/** A list of words as tokens; any other list as rows, each removable, with one more shaped like the last. */
+function ListField({ value, onChange, label }) {
+    const t = useLabels();
+    const keyed = useKeyedRows(value);
+    if (isWordList(value)) {
+        return (_jsx(Tokenizer, { label: label, size: "sm", value: value.map((word, index) => ({ id: `${String(index)}:${word}`, label: word })), searchSource: NO_SUGGESTIONS, hasCreate: true, debounceMs: 0, placeholder: t('@theorem.decision.add_value'), onChange: (items) => onChange(items.map((item) => item.label)) }));
+    }
+    const columns = tableColumns(value);
+    const add = _jsx(AddRow, { field: label, onAdd: () => onChange([...value, blankLike(value.at(-1))]) });
+    const remove = (index) => (_jsx(RemoveRow, { index: index, onRemove: () => {
+            keyed.drop(index);
+            onChange(value.filter((_, at) => at !== index));
+        } }));
+    if (columns) {
+        const grid = {
+            display: 'grid',
+            gap: 8,
+            alignItems: 'start',
+            gridTemplateColumns: `${columns.map((column) => `minmax(0, ${String(column.weight)}fr)`).join(' ')} auto`,
+        };
+        const rows = value;
+        return (_jsxs(Labelled, { label: label, children: [_jsxs("div", { style: grid, "aria-hidden": true, children: [columns.map((column) => (_jsx(Text, { type: "supporting", color: "secondary", maxLines: 1, children: humanize(column.key) }, column.key))), _jsx("span", { style: { width: 28 } })] }), keyed.rows.map(({ index, key }) => {
+                    const row = rows[index];
+                    return (_jsxs("div", { style: grid, children: [columns.map((column) => (_jsx(PlainField, { label: `${humanize(column.key)} ${String(index + 1)}`, isLabelHidden: true, value: row[column.key] ?? null, onChange: (next) => onChange(rows.map((old, at) => (at === index ? { ...old, [column.key]: next } : old))) }, column.key))), remove(index)] }, key));
+                }), add] }));
+    }
+    return (_jsx(Group, { label: label, children: _jsxs(VStack, { gap: 3, children: [keyed.rows.map(({ item: entry, index, key }) => {
+                    const item = t('@theorem.data.item', { index: String(index + 1) });
+                    const set = (next) => onChange(value.map((old, at) => (at === index ? next : old)));
+                    return (_jsxs(HStack, { gap: 2, vAlign: "start", children: [_jsx(StackItem, { size: "fill", children: isPlain(entry) ? (_jsx(PlainField, { label: item, isLabelHidden: true, value: entry, onChange: set })) : (_jsx(Field, { label: item, value: entry, onChange: set })) }), remove(index)] }, key));
+                }), add] }) }));
+}
+function Field({ value, onChange, label }) {
+    if (Array.isArray(value))
+        return _jsx(ListField, { label: label, value: value, onChange: onChange });
+    if (value !== null && typeof value === 'object') {
+        return (_jsx(Group, { label: label, children: _jsx(ObjectFields, { value: value, onChange: onChange }) }));
+    }
+    return _jsx(PlainField, { label: label, value: value, onChange: onChange });
+}
+/**
+ * A decision's state edited field by field: objects as labelled fields, lists
+ * of words as tokens, other lists as rows. The shape itself (new keys, other
+ * types) is edited as JSON.
+ */
+export function StateFields({ value, onChange, label }) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value))
+        return _jsx(ObjectFields, { value: value, onChange: onChange });
+    return _jsx(Field, { label: label, value: value, onChange: onChange });
+}