@theoremjs/react 0.0.0-stage → 0.3.1

package/ui/TraceValues.js

@@ -0,0 +1,123 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@astryxdesign/core/Button';
+import { CodeBlock } from '@astryxdesign/core/CodeBlock';
+import { useLocale } from '@astryxdesign/core/i18n';
+import { MetadataList, MetadataListItem } from '@astryxdesign/core/MetadataList';
+import { Text } from '@astryxdesign/core/Text';
+import { Timestamp } from '@astryxdesign/core/Timestamp';
+import { Tooltip } from '@astryxdesign/core/Tooltip';
+import { VStack } from '@astryxdesign/core/VStack';
+import { inlineContent, TRACE_ATTRIBUTE_GROUPS, traceAttributeMeta, } from '@theoremjs/agents';
+import { useMemo, useState } from 'react';
+import { nanosToMs, traceValueShape, } from "../client/trace-view.js";
+import { workDuration } from "./labels.js";
+import { useLabels } from "./labels-provider.js";
+import { keyedByContent } from "./row-keys.js";
+/** Width of every label column in the panel's lists, so they line up. */
+export const TRACE_LABEL_PX = 120;
+/** A span's attributes by catalog group, in the catalog's order; keys it does not name last. */
+export function attributeSections(attributes) {
+    const byGroup = new Map();
+    for (const [key, value] of Object.entries(attributes)) {
+        const group = traceAttributeMeta(key)?.group ?? 'other';
+        byGroup.set(group, { ...byGroup.get(group), [key]: value });
+    }
+    const order = [
+        ...Object.keys(TRACE_ATTRIBUTE_GROUPS),
+        'other',
+    ];
+    return order.flatMap((key) => {
+        const grouped = byGroup.get(key);
+        return grouped ? [{ key, attributes: grouped }] : [];
+    });
+}
+export function useTraceFormat() {
+    const t = useLabels();
+    const locale = useLocale();
+    return useMemo(() => {
+        const number = new Intl.NumberFormat(locale);
+        const usd = new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: 'USD',
+            maximumFractionDigits: 6,
+        });
+        const list = new Intl.ListFormat(locale, { type: 'conjunction' });
+        return {
+            t,
+            number: (value) => number.format(value),
+            usd: (value) => usd.format(value),
+            duration: (ms) => workDuration(t, ms),
+            list: (items) => list.format(items),
+            sum(total, format) {
+                const value = 'estimated' in total && total.estimated
+                    ? t('@theorem.panel.trace.about', { value: format(total.value) })
+                    : format(total.value);
+                return total.complete ? value : t('@theorem.panel.trace.at_least', { value });
+            },
+        };
+    }, [t, locale]);
+}
+/** A value as it was stored, with its references rebuilt, shown on click. */
+function StoredText({ record, value }) {
+    const { t } = useTraceFormat();
+    const [isShown, setIsShown] = useState(false);
+    const inlined = inlineContent(record, value);
+    return (_jsxs(VStack, { gap: 1, children: [_jsx(Button, { label: t(isShown ? '@theorem.panel.trace.hide_text' : '@theorem.panel.trace.show_text'), variant: "ghost", size: "sm", "aria-expanded": isShown, onClick: () => setIsShown((shown) => !shown) }), isShown ? (_jsx(CodeBlock, { code: typeof inlined === 'string' ? inlined : JSON.stringify(inlined, null, 2), language: typeof inlined === 'string' ? 'text' : 'json', isWrapped: true, size: "sm", hasCopyButton: true })) : null] }));
+}
+/** An option's label, with its meaning on hover. */
+function OptionValue({ option }) {
+    return (_jsx(Tooltip, { content: option.doc, children: _jsx(Text, { children: option.label }) }));
+}
+function formatNumber(format, meta, value) {
+    switch (meta?.format) {
+        case 'usd':
+            return format.usd(value);
+        case 'milliseconds':
+            return format.duration(value);
+        case 'seconds':
+            return format.duration(value * 1_000);
+        default:
+            return format.number(value);
+    }
+}
+function StringValue({ meta, value }) {
+    const option = meta?.options?.[value];
+    if (option)
+        return _jsx(OptionValue, { option: option });
+    if (meta?.format === 'time')
+        return (_jsx(Timestamp, { value: nanosToMs(value), format: "system_date_time", size: "base", color: "primary" }));
+    return _jsx(Text, { wordBreak: "break-word", children: value });
+}
+function ScalarValue({ meta, value, }) {
+    const format = useTraceFormat();
+    if (typeof value === 'boolean')
+        return _jsx(Text, { children: format.t(value ? '@theorem.panel.trace.yes' : '@theorem.panel.trace.no') });
+    return _jsx(Text, { hasTabularNumbers: true, children: formatNumber(format, meta, value) });
+}
+function ListValue({ meta, value, }) {
+    const format = useTraceFormat();
+    return _jsx(Text, { children: format.list(value.map((item) => meta?.options?.[item]?.label ?? item)) });
+}
+/** One attribute value, read by its catalog entry; a key the catalog does not name reads by its shape. */
+export function TraceValue({ record, meta, value, }) {
+    const shape = traceValueShape(meta, value);
+    switch (shape.kind) {
+        case 'text':
+            return _jsx(StringValue, { meta: meta, value: shape.value });
+        case 'scalar':
+            return _jsx(ScalarValue, { meta: meta, value: shape.value });
+        case 'list':
+            return _jsx(ListValue, { meta: meta, value: shape.value });
+        case 'fields':
+            return (_jsx(VStack, { gap: 2, children: keyedByContent(shape.items, (item) => JSON.stringify(item)).map(({ item, key }) => (_jsx(TraceAttributeList, { record: record, attributes: item, metaOf: (key) => shape.fields[key] }, key))) }));
+        case 'stored':
+            return _jsx(StoredText, { record: record, value: value });
+    }
+}
+/** Attributes as label and value rows, worded by `metaOf`; a key it does not name shows as recorded. */
+export function TraceAttributeList({ record, attributes, metaOf, maxNumOfItems, title, }) {
+    const entries = Object.entries(attributes);
+    if (entries.length === 0)
+        return null;
+    return (_jsx(MetadataList, { columns: "single", label: { position: 'start', width: TRACE_LABEL_PX }, maxNumOfItems: maxNumOfItems, title: title, children: entries.map(([key, value]) => (_jsx(MetadataListItem, { label: metaOf(key)?.label ?? key, children: _jsx(TraceValue, { record: record, meta: metaOf(key), value: value }) }, key))) }));
+}

package/ui/TraceWaterfall.d.ts

@@ -0,0 +1,13 @@
+import type { TraceNode } from '../client/trace-view.ts';
+/**
+ * Every span of the turn on one time axis, nested by depth and coloured by
+ * who acted. Above it, how busy the model and tools were over the turn; drag
+ * across that strip to zoom the rows into the window, as in a performance
+ * profile. A bar opens its span.
+ */
+export declare function TraceWaterfall({ root, selectedId, matches, onSelect, }: {
+    root: TraceNode;
+    selectedId: string | undefined;
+    matches: ReadonlySet<string> | undefined;
+    onSelect: (node: TraceNode) => void;
+}): import("react").JSX.Element;

package/ui/TraceWaterfall.js

@@ -0,0 +1,135 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@astryxdesign/core/Button';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { Text } from '@astryxdesign/core/Text';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconZoomOut } from '@tabler/icons-react';
+import { useMemo, useRef, useState } from 'react';
+import { Area, AreaChart, Bar, BarChart, CartesianGrid, Cell, ReferenceArea, ResponsiveContainer, Tooltip, XAxis, YAxis, } from 'recharts';
+import { traceActivity, traceActor, traceBars, traceOutcome, } from "../client/trace-story.js";
+import { ChartFrame, ChartTip, FIRST_WIDTH_PX } from "./TraceOverview.js";
+import { useTraceFormat } from "./TraceValues.js";
+import { TRACE_HUE } from "./trace-palette.js";
+import { ACTOR_FILL, TRACE_RADIUS, traceFill } from "./trace-patterns.js";
+/** Slices in the activity strip. */
+const BUCKETS = 120;
+/** Height of one span's row, in pixels. */
+const ROW_PX = 22;
+/** Height of the time axis under the rows. */
+const AXIS_PX = 24;
+/** Height of the activity strip. */
+const STRIP_PX = 36;
+/** Room right of the plot, so the last tick's label fits. */
+const PLOT_RIGHT_PX = 4;
+/** Width of the name column, in pixels. */
+const NAME_PX = 132;
+/** Indent per level of nesting in the name column. */
+const INDENT_PX = 8;
+function barHatch(node) {
+    return ACTOR_FILL[traceActor(node)];
+}
+function BarTip({ active, payload }) {
+    const format = useTraceFormat();
+    const row = payload?.[0]?.payload;
+    if (!active || !row)
+        return null;
+    const { node, from } = row.bar;
+    const outcome = traceOutcome(node);
+    const cost = node.span.attributes['theorem.usage.cost_usd'];
+    return (_jsx(ChartTip, { children: _jsxs(VStack, { gap: 0, children: [_jsx(Text, { weight: "medium", children: row.name }), _jsx(Text, { type: "supporting", color: "secondary", children: node.meta.label }), _jsx(Text, { type: "supporting", hasTabularNumbers: true, children: [
+                        format.duration(node.durationMs),
+                        format.t('@theorem.panel.trace.offset', { duration: format.duration(from) }),
+                        ...(typeof cost === 'number' ? [format.usd(cost)] : []),
+                    ].join(format.t('@theorem.panel.trace.separator')) }), outcome ? (_jsx(Text, { type: "supporting", children: _jsx("span", { style: {
+                            color: outcome.tone === 'error' ? TRACE_HUE.oxblood : 'var(--color-text-secondary)',
+                        }, children: outcome.label }) })) : null] }) }));
+}
+/** A row's name, from the chart's left edge, set in by its depth and cut to the column. */
+function NameTick({ y: rawY, payload, rows, }) {
+    const row = typeof payload?.value === 'string' ? rows.get(payload.value) : undefined;
+    const y = Number(rawY);
+    if (!row || Number.isNaN(y))
+        return null;
+    const indent = Math.min(row.bar.depth, 4) * INDENT_PX;
+    const room = Math.floor((NAME_PX - indent - 10) / 6.2);
+    const name = row.name.length > room ? `${row.name.slice(0, Math.max(1, room - 1))}…` : row.name;
+    return (_jsxs("text", { x: indent, y: y, dy: "0.35em", fontSize: 11, fill: row.bar.node.span.status.code === 'ERROR'
+            ? TRACE_HUE.oxblood
+            : 'var(--color-text-secondary)', children: [_jsx("title", { children: row.name }), name] }));
+}
+/** How busy the model and tools were over the turn; a drag across it picks the window to zoom into. */
+function ActivityStrip({ root, zoom, onZoom, }) {
+    const activity = useMemo(() => traceActivity(root, BUCKETS), [root]);
+    const total = Math.max(root.durationMs, 1);
+    const [drag, setDrag] = useState(null);
+    // why: Pointer events can outrun a render; the ref always holds the drag so far.
+    const dragRef = useRef(null);
+    const moveDrag = (next) => {
+        dragRef.current = next;
+        setDrag(next);
+    };
+    /** The time under a pointer on the strip, in ms from the turn's start. */
+    const timeAt = (event) => {
+        const box = event.currentTarget.getBoundingClientRect();
+        const share = (event.clientX - box.left - NAME_PX) / Math.max(box.width - NAME_PX - PLOT_RIGHT_PX, 1);
+        return Math.min(Math.max(share, 0), 1) * total;
+    };
+    const endDrag = () => {
+        const done = dragRef.current;
+        if (done) {
+            const from = Math.min(done.from, done.to);
+            const to = Math.max(done.from, done.to);
+            if (to - from >= total / BUCKETS)
+                onZoom({ root: root.id, from, to });
+        }
+        moveDrag(null);
+    };
+    const shown = drag ?? zoom;
+    return (_jsx("div", { role: "application", style: { cursor: 'col-resize', userSelect: 'none', touchAction: 'none' }, onPointerDown: (event) => {
+            event.currentTarget.setPointerCapture(event.pointerId);
+            const value = timeAt(event);
+            moveDrag({ from: value, to: value });
+        }, onPointerMove: (event) => {
+            const current = dragRef.current;
+            if (current)
+                moveDrag({ from: current.from, to: timeAt(event) });
+        }, onPointerUp: endDrag, onPointerCancel: () => moveDrag(null), onMouseDown: (event) => event.preventDefault(), children: _jsx(ResponsiveContainer, { width: "100%", height: STRIP_PX, initialDimension: { width: FIRST_WIDTH_PX, height: STRIP_PX }, children: _jsxs(AreaChart, { data: activity, margin: { top: 2, right: PLOT_RIGHT_PX, bottom: 0, left: NAME_PX }, accessibilityLayer: false, children: [_jsx(XAxis, { dataKey: "at", type: "number", domain: [0, total], hide: true }), _jsx(YAxis, { hide: true, domain: [0, 2] }), _jsx(Area, { type: "monotone", dataKey: "model", stackId: "busy", activeDot: false, stroke: "none", fill: traceFill('clear'), fillOpacity: 1, isAnimationActive: false }), _jsx(Area, { type: "monotone", dataKey: "tools", stackId: "busy", activeDot: false, stroke: "none", fill: traceFill('hatch'), fillOpacity: 1, isAnimationActive: false }), shown ? (_jsx(ReferenceArea, { x1: shown.from, x2: shown.to, fill: "var(--color-text-primary)", fillOpacity: drag ? 0.12 : 0.08, stroke: "var(--color-border-emphasized)" })) : null] }) }) }));
+}
+/** A bar's opacity: faded when the search passed it over, the turn itself half-strength, and the rest dimmed around a selection. */
+function barOpacity(row, selectedId, matches) {
+    if (matches && !matches.has(row.id))
+        return 0.25;
+    if (row.bar.depth === 0)
+        return 0.45;
+    return !selectedId || row.id === selectedId ? 1 : 0.5;
+}
+/** One bar per span over the time window, named on the left. */
+function SpanBars({ root, domain, selectedId, matches, onSelect, }) {
+    const format = useTraceFormat();
+    const rows = useMemo(() => traceBars(root).map((bar) => ({
+        id: bar.node.id,
+        bar,
+        range: [bar.from, bar.to],
+        name: bar.node.meta.subject ?? bar.node.meta.label,
+    })), [root]);
+    const byId = useMemo(() => new Map(rows.map((row) => [row.id, row])), [rows]);
+    const height = rows.length * ROW_PX + AXIS_PX;
+    return (_jsx(ChartFrame, { children: _jsx(ResponsiveContainer, { width: "100%", height: height, initialDimension: { width: FIRST_WIDTH_PX, height }, children: _jsxs(BarChart, { data: rows, layout: "vertical", accessibilityLayer: false, margin: { top: 0, right: PLOT_RIGHT_PX, bottom: 0, left: 0 }, barCategoryGap: 4, onClick: (state) => {
+                    const row = rows[Number(state?.activeIndex)];
+                    if (row)
+                        onSelect(row.bar.node);
+                }, style: { cursor: 'pointer' }, children: [_jsx(CartesianGrid, { horizontal: false, stroke: "var(--color-border)", strokeDasharray: "2 4" }), _jsx(XAxis, { type: "number", domain: domain, allowDataOverflow: true, tickFormatter: (value) => format.duration(value), tick: { fill: 'var(--color-text-secondary)', fontSize: 11 }, axisLine: { stroke: 'var(--color-border)' }, tickLine: false, height: AXIS_PX, tickCount: 5 }), _jsx(YAxis, { type: "category", dataKey: "id", width: NAME_PX, axisLine: false, tickLine: false, interval: 0, tick: (props) => _jsx(NameTick, { ...props, rows: byId }) }), _jsx(Tooltip, { content: (props) => _jsx(BarTip, { ...props }), cursor: { fill: 'var(--color-overlay-hover)' }, isAnimationActive: false }), _jsx(Bar, { dataKey: "range", minPointSize: 2, radius: TRACE_RADIUS, isAnimationActive: false, style: { cursor: 'pointer' }, children: rows.map((row) => (_jsx(Cell, { fill: traceFill(barHatch(row.bar.node)), opacity: barOpacity(row, selectedId, matches) }, row.id))) })] }) }) }));
+}
+/**
+ * Every span of the turn on one time axis, nested by depth and coloured by
+ * who acted. Above it, how busy the model and tools were over the turn; drag
+ * across that strip to zoom the rows into the window, as in a performance
+ * profile. A bar opens its span.
+ */
+export function TraceWaterfall({ root, selectedId, matches, onSelect, }) {
+    const { t } = useTraceFormat();
+    const [picked, setPicked] = useState(null);
+    const zoom = picked?.root === root.id ? picked : null;
+    return (_jsxs(VStack, { gap: 2, className: "theorem-arrive", children: [_jsxs(HStack, { gap: 2, align: "center", justify: "between", children: [_jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.panel.trace.timeline.zoom') }), zoom ? (_jsx(Button, { label: t('@theorem.panel.trace.timeline.reset'), variant: "ghost", size: "sm", icon: _jsx(Icon, { icon: IconZoomOut }), onClick: () => setPicked(null) })) : null] }), _jsx(ActivityStrip, { root: root, zoom: zoom, onZoom: setPicked }), _jsx(SpanBars, { root: root, domain: zoom ? [zoom.from, zoom.to] : [0, Math.max(root.durationMs, 1)], selectedId: selectedId, matches: matches, onSelect: onSelect })] }));
+}

package/ui/VoiceNote.d.ts

@@ -0,0 +1,12 @@
+export type VoiceNoteProps = {
+    src: string;
+    mimeType?: string;
+    label?: string;
+    /** Composer only: removes the staged note. */
+    onRemove?: () => void;
+};
+/**
+ * Voice note as an Astryx ClickableCard holding the ink waveform (the one live
+ * uses): click to play or pause; the bars move while it plays.
+ */
+export declare function VoiceNote({ src, mimeType, label, onRemove }: VoiceNoteProps): import("react").JSX.Element;

package/ui/VoiceNote.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ClickableCard } from '@astryxdesign/core/ClickableCard';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconX } from '@tabler/icons-react';
+import { voiceFormatFromMime } from "../client/voice-label.js";
+import { InkWaveform } from "../components/InkWaveform.js";
+import { useVoicePlayback } from "../components/use-voice-playback.js";
+import { voiceNoteName } from "./labels.js";
+import { useLabels } from "./labels-provider.js";
+/** Astryx Thumbnail's height, so voice notes sit level with image attachments. */
+const VOICE_NOTE_HEIGHT = 64;
+const VOICE_NOTE_WIDTH = 160;
+/**
+ * Voice note as an Astryx ClickableCard holding the ink waveform (the one live
+ * uses): click to play or pause; the bars move while it plays.
+ */
+export function VoiceNote({ src, mimeType = 'audio/webm', label, onRemove }) {
+    const t = useLabels();
+    const { playing, levelsRef, toggle, audioProps } = useVoicePlayback();
+    const name = label ?? voiceNoteName(t, voiceFormatFromMime(mimeType));
+    const remove = t('@theorem.voice_note.remove', { name });
+    return (_jsxs(HStack, { gap: 1, vAlign: "center", children: [_jsx(ClickableCard, { label: t(playing ? '@theorem.voice_note.pause' : '@theorem.voice_note.play', { name }), onClick: () => {
+                    void toggle();
+                }, padding: 0, width: VOICE_NOTE_WIDTH, height: VOICE_NOTE_HEIGHT, children: _jsx(VStack, { width: "100%", height: "100%", paddingInline: 2, paddingBlockStart: 2, style: { color: 'var(--color-icon-primary)' }, "aria-hidden": "true", children: _jsx(InkWaveform, { frozen: !playing, levelsRef: levelsRef, status: playing ? 'speaking' : 'ready', variant: "pill" }) }) }), onRemove ? (_jsx(IconButton, { label: remove, tooltip: remove, variant: "ghost", size: "sm", icon: _jsx(Icon, { icon: IconX }), onClick: onRemove })) : null, _jsx("audio", { ...audioProps, src: src, hidden: true })] }));
+}

package/ui/approval-heading.d.ts

@@ -0,0 +1,4 @@
+import type { ToolGate } from '@theoremjs/agents/kernel';
+import type { LabelText } from './labels.ts';
+/** "@concierge wants to check the weather": the tool's `labels.request`, else its name in words. */
+export declare function approvalHeading(t: LabelText, gate: ToolGate, toolName: string, agent?: string): string;

package/ui/approval-heading.js

@@ -0,0 +1,9 @@
+import { humanize } from "../client/shaped-data.js";
+/** "@concierge wants to check the weather": the tool's `labels.request`, else its name in words. */
+export function approvalHeading(t, gate, toolName, agent) {
+    const request = gate.request ??
+        t('@theorem.gate.approval.use_tool', { tool: humanize(toolName).toLowerCase() });
+    return agent
+        ? t('@theorem.gate.approval.title', { agent, request })
+        : t('@theorem.gate.approval.title_no_agent', { request });
+}

package/ui/arrive.d.ts

@@ -0,0 +1,18 @@
+import { type CSSProperties, type ReactNode } from 'react';
+/**
+ * Items under this ease in one after another, in tree order. An item that
+ * mounts later (a span that just landed, a chart whose module just loaded)
+ * eases in on its own. Already-shown items do not replay.
+ */
+export declare function Stream({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Class and delay for one item. Nothing outside a {@link Stream}. */
+export declare function useArrive(): {
+    className: string;
+    style?: CSSProperties;
+} | null;
+/** A block that eases in with its siblings under {@link Stream}. */
+export declare function Arrive({ children }: {
+    children: ReactNode;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;

package/ui/arrive.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, use, useRef, useState } from 'react';
+/**
+ * How long each later item waits. Short enough that a handful still read as
+ * one arrival, long enough that the order is visible.
+ */
+const STEP_MS = 64;
+/** Past this, the rest start together so a long list is not still waiting. */
+const CAP = 10;
+const ArriveSeq = createContext(null);
+/**
+ * Items under this ease in one after another, in tree order. An item that
+ * mounts later (a span that just landed, a chart whose module just loaded)
+ * eases in on its own. Already-shown items do not replay.
+ */
+export function Stream({ children }) {
+    const seq = useRef(0);
+    // why: Each render starts again. Items remember the place they took, so a
+    // re-render does not hand that place to someone else.
+    seq.current = 0;
+    return _jsx(ArriveSeq, { value: seq, children: children });
+}
+/** Class and delay for one item. Nothing outside a {@link Stream}. */
+export function useArrive() {
+    const seq = use(ArriveSeq);
+    const slot = useRef(null);
+    if (seq && slot.current === null) {
+        slot.current = seq.current;
+        seq.current += 1;
+    }
+    const index = seq ? slot.current : null;
+    const [delay] = useState(() => (index === null ? 0 : Math.min(index, CAP) * STEP_MS));
+    if (index === null)
+        return null;
+    return {
+        className: 'theorem-arrive',
+        style: delay > 0 ? { animationDelay: `${String(delay)}ms` } : undefined,
+    };
+}
+/** A block that eases in with its siblings under {@link Stream}. */
+export function Arrive({ children }) {
+    const arrive = useArrive();
+    if (!arrive)
+        return children;
+    return (_jsx("div", { className: arrive.className, style: arrive.style, children: children }));
+}