@theoremjs/react 0.0.0-stage → 0.3.0

package/client/shaped-data.js

@@ -0,0 +1,314 @@
+/**
+ * The rules `ShapedData` draws a payload by, as plain decisions: which shape a
+ * value takes, what a row is called, what a field's label and unit are. The
+ * component only maps each decision to its Astryx part.
+ */
+/** Fields that name a row, in the order they're tried. */
+const TITLE_KEYS = ['name', 'title', 'label', 'headline', 'subject', 'id'];
+/** Fields that place or sort a row, shown as tokens beside its title. */
+const TAG_KEYS = ['country', 'region', 'state', 'admin1', 'city', 'category', 'type', 'kind', 'status'];
+const MAX_TAGS = 2;
+const MAX_TAG_LENGTH = 24;
+/** Fields that say, in a line, what a row is. */
+const DESCRIPTION_KEYS = ['description', 'summary', 'snippet', 'extract', 'subtitle', 'address', 'display_name', 'text'];
+/** Fields that link a row to its page. */
+const LINK_KEYS = ['url', 'link', 'href'];
+/** Fields a list row shows beyond its name, line, link and tags, at its end. */
+const MAX_LIST_EXTRAS = 2;
+/** A list of flat objects with at most this many fields reads as a table. */
+const MAX_TABLE_COLUMNS = 6;
+/** Rows shown before the rest are left to the JSON view. */
+export const MAX_ROWS = 50;
+/** A list of plain values this short sits inline as tokens beside the other fields. */
+const MAX_INLINE_TOKENS = 8;
+/** Levels drawn before a subtree shows as JSON. */
+const MAX_DEPTH = 8;
+export const ISO_DATE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+export function isRow(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isPlain(value) {
+    return value === null || typeof value !== 'object';
+}
+const UNREADABLE = '[Unreadable]';
+const NO_TO_JSON = Symbol('no toJSON');
+/** A read that throws reads as a marker. */
+function readSafe(read) {
+    try {
+        return read();
+    }
+    catch {
+        return UNREADABLE;
+    }
+}
+/** What the value's own toJSON gives, made safe; NO_TO_JSON when it has none. */
+function viaToJSON(value, inside) {
+    const own = value.toJSON;
+    return typeof own === 'function' ? jsonSafe(own.call(value), inside) : NO_TO_JSON;
+}
+/**
+ * What JSON.stringify can't take, made plain: a cycle, a BigInt, a property
+ * that throws when read. Each becomes a marker in place, so the rest still shows.
+ */
+function jsonSafe(value, ancestors = []) {
+    if (typeof value === 'bigint')
+        return String(value);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (ancestors.includes(value))
+        return '[Circular]';
+    const inside = [...ancestors, value];
+    const converted = readSafe(() => viaToJSON(value, inside));
+    if (converted !== NO_TO_JSON)
+        return converted;
+    if (Array.isArray(value))
+        return value.map((item) => jsonSafe(item, inside));
+    return Object.fromEntries(Object.keys(value).map((key) => [key, readSafe(() => jsonSafe(value[key], inside))]));
+}
+/** The value as indented JSON, whatever it holds. */
+export function json(value) {
+    try {
+        return JSON.stringify(value, null, 2) ?? String(value);
+    }
+    catch {
+        return JSON.stringify(jsonSafe(value), null, 2) ?? String(value);
+    }
+}
+/** A string that holds a JSON object or list, parsed; anything else as it came. */
+export function unpacked(value) {
+    if (typeof value !== 'string')
+        return value;
+    const text = value.trim();
+    if (!/^[[{]/.test(text))
+        return value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return value;
+    }
+}
+/** `country_code`, `countryCode` → "Country code". */
+export function humanize(key) {
+    const words = key
+        .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+        .replace(/([a-zA-Z])(\d)/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .trim()
+        .toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** A unit worth printing: a symbol or abbreviation, not a format name like `iso8601` or `wmo code`. */
+export function printableUnit(unit) {
+    if (typeof unit !== 'string' || unit === '' || /\s/.test(unit) || unit === 'iso8601')
+        return undefined;
+    return unit;
+}
+/** Unit suffixes a key can end in (`distance_m`, `duration_ms`), and the unit each prints as. */
+const SUFFIX_UNITS = {
+    m: 'm',
+    km: 'km',
+    mi: 'mi',
+    ms: 'ms',
+    s: 's',
+    sec: 's',
+    min: 'min',
+    h: 'h',
+    kg: 'kg',
+    g: 'g',
+    pct: '%',
+    percent: '%',
+    c: '°C',
+    f: '°F',
+    usd: 'USD',
+    eur: 'EUR',
+    gbp: 'GBP',
+    jpy: 'JPY',
+};
+/** The unit a key's suffix names, and the key without it: `distance_m` → Distance, m. */
+function suffixUnit(key) {
+    const match = /^(.+?)[_-]([a-z]+)$/i.exec(key);
+    const unit = match ? SUFFIX_UNITS[(match[2] ?? '').toLowerCase()] : undefined;
+    return match?.[1] && unit ? { label: humanize(match[1]), unit } : undefined;
+}
+/** A column's label and unit: from its `<key>_units` entry, else its key's suffix. */
+export function fieldLabel(key, units) {
+    const listed = printableUnit(units?.[key]);
+    if (listed)
+        return { label: humanize(key), unit: listed };
+    return suffixUnit(key) ?? { label: humanize(key) };
+}
+/** A field's label and the unit its value reads with. A unit only reads onto a number: `country_code` stays "Country code". */
+export function fieldReading(key, value, units) {
+    if (typeof value !== 'number')
+        return { label: humanize(key) };
+    return fieldLabel(key, units);
+}
+/** The `<key>_units` object beside `key`, if there is one. */
+export function unitsOf(row, key) {
+    const units = row[`${key}_units`];
+    return isRow(units) ? units : undefined;
+}
+/** A row's fields, less the units objects its other fields read. */
+export function shownEntries(row) {
+    return Object.entries(row).filter(([key, value]) => !(key.endsWith('_units') && isRow(value) && key.slice(0, -'_units'.length) in row));
+}
+/** A string that's a date: a bare day or a moment. */
+function dateReading(text) {
+    if (!ISO_DATE.test(text))
+        return undefined;
+    const date = new Date(text);
+    if (Number.isNaN(date.getTime()))
+        return undefined;
+    return text.includes('T') ? { kind: 'date-time', date } : { kind: 'date', date };
+}
+export function plainReading(value, unit) {
+    if (value === null || value === undefined)
+        return { kind: 'none' };
+    if (typeof value === 'boolean')
+        return { kind: 'boolean', value };
+    if (typeof value === 'number')
+        return unit ? { kind: 'number', value, unit } : { kind: 'number', value };
+    const text = String(value);
+    if (/^https?:\/\/\S+$/.test(text))
+        return { kind: 'link', href: text };
+    return dateReading(text) ?? { kind: 'text', text };
+}
+/** A formatted number with its unit: symbols sit close (21°C, 35%), words stand apart (320 m). */
+export function withUnit(number, unit) {
+    if (!unit)
+        return number;
+    return /^[°%]/.test(unit) ? `${number}${unit}` : `${number} ${unit}`;
+}
+/** The field that names a row, if it has one. */
+export function titleKey(row) {
+    return TITLE_KEYS.find((key) => typeof row[key] === 'string' || typeof row[key] === 'number');
+}
+/** Up to two short strings that place or sort a row. */
+function tags(row, skip) {
+    return TAG_KEYS.filter((key) => {
+        const value = row[key];
+        return key !== skip && typeof value === 'string' && value.length > 0 && value.length <= MAX_TAG_LENGTH;
+    })
+        .slice(0, MAX_TAGS)
+        .map((key) => row[key]);
+}
+/** A flat row's parts, if a name and a line say what it is. */
+function listRow(item) {
+    if (!isRow(item) || !Object.values(item).every(isPlain))
+        return undefined;
+    const title = titleKey(item);
+    const description = DESCRIPTION_KEYS.find((key) => typeof item[key] === 'string' && item[key] !== '');
+    if (!title || !description)
+        return undefined;
+    const link = LINK_KEYS.find((key) => typeof item[key] === 'string' && /^https?:\/\//.test(item[key]));
+    const rowTags = tags(item, title);
+    const shown = new Set([title, description, link]);
+    const extras = Object.entries(item).filter(([key, value]) => !shown.has(key) && !(TAG_KEYS.includes(key) && rowTags.includes(value)));
+    if (extras.length > MAX_LIST_EXTRAS)
+        return undefined;
+    return {
+        title: String(item[title]),
+        description: item[description],
+        href: link ? item[link] : undefined,
+        tags: rowTags,
+        extras,
+    };
+}
+/** A collapsible row's heading and what it opens to: a titled row loses its title field; else it's named by its place. */
+export function rowHeading(item) {
+    if (!isRow(item))
+        return { tags: [], rest: item };
+    const key = titleKey(item);
+    if (!key)
+        return { tags: tags(item, undefined), rest: item };
+    return {
+        title: String(item[key]),
+        tags: tags(item, key),
+        rest: Object.fromEntries(Object.entries(item).filter(([k]) => k !== key)),
+    };
+}
+/** Small flat objects sharing their fields: a table's rows. */
+function tableColumns(items) {
+    if (items.length < 2 || !items.every((item) => isRow(item) && Object.values(item).every(isPlain)))
+        return undefined;
+    const columns = [...new Set(items.flatMap((item) => Object.keys(item)))];
+    return columns.length <= MAX_TABLE_COLUMNS ? columns : undefined;
+}
+/** An object of equal-length lists of plain values (a column store): a table's columns. */
+export function columnStore(row) {
+    const entries = shownEntries(row);
+    if (entries.length < 2)
+        return undefined;
+    const lengths = new Set(entries.map(([, value]) => (Array.isArray(value) && value.every(isPlain) ? value.length : -1)));
+    const [length] = lengths;
+    return lengths.size === 1 && length !== undefined && length >= 2 ? entries.map(([key]) => key) : undefined;
+}
+/** A column store's lists, turned into rows. */
+export function storeRows(row, columns) {
+    const lists = columns.map((key) => row[key]);
+    return (lists[0] ?? []).map((_, index) => Object.fromEntries(columns.map((key, k) => [key, lists[k]?.[index]])));
+}
+function listShape(items) {
+    if (items.length === 0)
+        return { kind: 'none' };
+    if (items.every(isPlain))
+        return { kind: 'tokens', items };
+    const listed = items.map(listRow);
+    if (listed.every((row) => row !== undefined))
+        return { kind: 'list', rows: listed };
+    const columns = tableColumns(items);
+    return columns ? { kind: 'table', columns, rows: items } : { kind: 'rows', items };
+}
+function rowShape(row) {
+    if (Object.keys(row).length === 0)
+        return { kind: 'none' };
+    const store = columnStore(row);
+    return store ? { kind: 'table', columns: store, rows: storeRows(row, store) } : { kind: 'fields', row };
+}
+/** How a value (already unpacked) at `depth` is drawn. */
+export function shapeOf(value, depth) {
+    if (depth > MAX_DEPTH)
+        return { kind: 'json' };
+    if (Array.isArray(value))
+        return listShape(value);
+    return isRow(value) ? rowShape(value) : { kind: 'plain' };
+}
+/** Text this long, or on several lines, reads as prose: full width, as Markdown. */
+const PROSE_CHARS = 160;
+export function isProse(value) {
+    return typeof value === 'string' && (value.length > PROSE_CHARS || value.includes('\n'));
+}
+/** A field that sits in the field list: a plain value (prose aside), or a short list of them. */
+function isInline(value) {
+    const inner = unpacked(value);
+    if (isProse(inner))
+        return false;
+    if (isPlain(inner))
+        return true;
+    return Array.isArray(inner) && inner.length > 0 && inner.length <= MAX_INLINE_TOKENS && inner.every(isPlain);
+}
+function section(row, key) {
+    const path = [key];
+    let inner = unpacked(row[key]);
+    let units = unitsOf(row, key);
+    while (isRow(inner)) {
+        // A units object beside the one field doesn't count: `{ hourly, hourly_units }` is still a wrapper.
+        const entries = shownEntries(inner);
+        const only = entries.length === 1 ? entries[0] : undefined;
+        if (!only || isPlain(unpacked(only[1])))
+            break;
+        path.push(only[0]);
+        units = unitsOf(inner, only[0]);
+        inner = unpacked(only[1]);
+    }
+    return { key, title: path.map(humanize).join(' › '), value: inner, units };
+}
+/** An object's fields split: plain ones for the field list, nested ones as sections. */
+export function splitFields(row) {
+    const entries = shownEntries(row);
+    return {
+        plain: entries.filter(([, value]) => isInline(value)),
+        sections: entries.filter(([, value]) => !isInline(value)).map(([key]) => section(row, key)),
+    };
+}

package/client/source-citations.d.ts

@@ -0,0 +1,13 @@
+import type { TranscriptBlock } from '@theoremjs/agents/interface';
+/** One source as a citation: its title, and when it's on the web, its link and favicon. */
+export type SourceCitation = {
+    key: string;
+    title: string;
+    href?: string;
+    icon?: string;
+};
+export type SourceCitationBlock = Extract<TranscriptBlock, {
+    kind: 'citation';
+}>;
+/** A citation's sources, in the order they were cited. */
+export declare function citationsFromBlock(block: SourceCitationBlock): SourceCitation[];

package/client/source-citations.js

@@ -0,0 +1,56 @@
+/**
+ * Gemini grounding links through this host rather than to the page, and names
+ * the page's own site in the source title instead.
+ */
+const GROUNDING_REDIRECT_HOST = 'vertexaisearch.cloud.google.com';
+/** A citation's sources, in the order they were cited. */
+export function citationsFromBlock(block) {
+    return block.sources.map((source, i) => citationFromSource(source, `c-${String(i)}`));
+}
+function citationFromSource(source, key) {
+    const url = webUrl(source.uri);
+    const site = url && siteOf(url, source.title);
+    return {
+        key,
+        title: source.title.trim() || hostLabel(source.uri) || source.type,
+        ...(url ? { href: url.href } : {}),
+        ...(site ? { icon: faviconUrl(site) } : {}),
+    };
+}
+/**
+ * A source is linked only at an http(s) URL. Sources come from the model and
+ * from tool output, so a `javascript:`, `data:` or other scheme never becomes
+ * a clickable link.
+ */
+function webUrl(uri) {
+    if (!URL.canParse(uri))
+        return undefined;
+    const url = new URL(uri);
+    return url.protocol === 'https:' || url.protocol === 'http:' ? url : undefined;
+}
+/** The site a source is on: the link's host, or for a grounding redirect, the site its title names. */
+function siteOf(url, title) {
+    if (url.hostname !== GROUNDING_REDIRECT_HOST)
+        return url.hostname;
+    const named = title.trim().toLowerCase();
+    if (!named.includes('.') || !URL.canParse(`https://${named}`))
+        return undefined;
+    return new URL(`https://${named}`).hostname === named ? named : undefined;
+}
+/** Google's favicon service; the visitor's browser sends it the site's host, never the page. */
+function faviconUrl(site) {
+    return `https://www.google.com/s2/favicons?domain=${encodeURIComponent(site)}&sz=32`;
+}
+function hostLabel(uri) {
+    try {
+        return new URL(uri).hostname.replace(/^www\./, '');
+    }
+    catch {
+        return truncate(uri, 40);
+    }
+}
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 1)}…`;
+}

package/client/state-fields.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The rules behind editing a decision's state as fields: which lists read as
+ * words, and what a new row in a list starts as.
+ *
+ * @module
+ */
+import type { DecisionJson } from '@theoremjs/agents';
+/** A list edited as tokens: empty, or every entry a string. */
+export declare function isWordList(value: DecisionJson[]): value is string[];
+/** A new row shaped like `like`: its fields kept, its values emptied. */
+export declare function blankLike(like: DecisionJson | undefined): DecisionJson;
+/** Columns a list of rows edits as a table in, or `null` when its rows are not all small, flat, and alike. */
+export declare function tableColumns(value: DecisionJson[]): {
+    key: string;
+    weight: number;
+}[] | null;

package/client/state-fields.js

@@ -0,0 +1,44 @@
+/**
+ * The rules behind editing a decision's state as fields: which lists read as
+ * words, and what a new row in a list starts as.
+ *
+ * @module
+ */
+/** A list edited as tokens: empty, or every entry a string. */
+export function isWordList(value) {
+    return value.every((entry) => typeof entry === 'string');
+}
+/** A new row shaped like `like`: its fields kept, its values emptied. */
+export function blankLike(like) {
+    if (like === undefined || like === null || typeof like === 'string')
+        return '';
+    if (typeof like === 'number')
+        return 0;
+    if (typeof like === 'boolean')
+        return false;
+    if (Array.isArray(like))
+        return [];
+    return Object.fromEntries(Object.entries(like).map(([key, value]) => [key, blankLike(value)]));
+}
+/** Columns a list of rows edits as a table in, or `null` when its rows are not all small, flat, and alike. */
+export function tableColumns(value) {
+    const first = value[0];
+    if (first === undefined || first === null || typeof first !== 'object' || Array.isArray(first))
+        return null;
+    const keys = Object.keys(first);
+    if (keys.length === 0 || keys.length > 4)
+        return null;
+    const alike = value.every((row) => row !== null &&
+        typeof row === 'object' &&
+        !Array.isArray(row) &&
+        Object.keys(row).join() === keys.join() &&
+        Object.values(row).every((cell) => cell === null || typeof cell !== 'object'));
+    if (!alike)
+        return null;
+    // Wider columns for longer values: a role stays narrow beside its message.
+    return keys.map((key) => {
+        const lengths = value.map((row) => String(row[key] ?? '').length);
+        const longest = Math.max(key.length, ...lengths);
+        return { key, weight: Math.min(4, Math.max(1, Math.round(longest / 10))) };
+    });
+}

package/client/tool-result.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What a tool's result leads with, above its data: the figures that answer it,
+ * the series worth a chart, and the images it links. Plain decisions over the
+ * value alone, so any tool's output gets them without a schema saying so; the
+ * data itself still reads in full below, drawn by `ShapedData`.
+ *
+ * @module
+ */
+import { type Row } from './shaped-data.ts';
+/** One number that answers the call, as a stat card shows it. */
+export type ResultFigure = {
+    key: string;
+    label: string;
+    value: number;
+    unit?: string;
+};
+/** One numeric field drawn across a chart's rows. */
+export type ResultSeries = {
+    key: string;
+    label: string;
+    unit?: string;
+};
+/** A time chart draws its series over dates; a category chart ranks rows by one series. */
+export type ResultChart = {
+    kind: 'time';
+    key: string;
+    title: string;
+    x: string;
+    series: ResultSeries[];
+    rows: Row[];
+} | {
+    kind: 'category';
+    key: string;
+    title: string;
+    series: ResultSeries;
+    rows: {
+        label: string;
+        value: number;
+    }[];
+};
+export type ResultImage = {
+    src: string;
+    alt: string;
+};
+export type ResultLayout = {
+    figures: ResultFigure[];
+    charts: ResultChart[];
+    images: ResultImage[];
+};
+/** Media a tool returned beside its value, as the complete event carries it. */
+export type ResultMedia = {
+    type: string;
+    mimeType?: string;
+    data?: string;
+};
+/** What a call returned to see or hear: its image parts, then the images its value links; its audio parts. */
+export type ReturnedMedia = {
+    images: ResultImage[];
+    audio: {
+        src: string;
+        mimeType?: string;
+    }[];
+};
+/** What a tool's output leads with. Empty when nothing stands out: the data alone reads best. */
+export declare function layoutResult(output: unknown): ResultLayout;
+/** The images and audio a call returned, each with its bytes; parts without them are left out. */
+export declare function returnedMedia(layout: ResultLayout, parts: readonly ResultMedia[], imageAlt: string): ReturnedMedia;
+/** Whether the result has anything to lead with above its data. */
+export declare function hasLead(layout: ResultLayout, media: ReturnedMedia): boolean;
+/**
+ * How a time chart's dates read, on its axis and in its tooltip: hours within
+ * a day, else dates. A bare date is a calendar day, parsed at UTC midnight, so
+ * it reads in UTC and doesn't slip a day.
+ */
+export declare function timeFormats(dates: readonly string[]): {
+    tick: Intl.DateTimeFormatOptions;
+    when: Intl.DateTimeFormatOptions;
+};