@theoremjs/react 0.3.0 → 0.3.1

package/ui/EmbeddingDocuments.js

@@ -0,0 +1,278 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { FileInput } from '@astryxdesign/core/FileInput';
+import { Grid, GridSpan } from '@astryxdesign/core/Grid';
+import { HStack } from '@astryxdesign/core/HStack';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { SegmentedControl, SegmentedControlItem } from '@astryxdesign/core/SegmentedControl';
+import { StackItem } from '@astryxdesign/core/Stack';
+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 { Tooltip } from '@astryxdesign/core/Tooltip';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconBaselineDensityMedium, IconCsv, IconFileText, IconPilcrow, IconScissors, IconX, } from '@tabler/icons-react';
+import { attachmentIssueText, base64Bytes } from '@theoremjs/agents';
+import { useMemo, useState } from 'react';
+import { checkInputs, embeddingBatches, readEmbeddingInputs, readsAsText, splitText, } from "../client/embedding-input.js";
+import { encodeFiles } from "../client/encode-files.js";
+import { JsonRequest, RequestCard, RunBar, useBytes } from "./ConsoleFrame.js";
+import { useLabels } from "./labels-provider.js";
+import { textRows } from "./StateFields.js";
+/** The ways to split, coarsest first, each with its icon. */
+const SPLITS = [
+    { value: 'whole', icon: _jsx(IconFileText, { size: 16 }) },
+    { value: 'paragraphs', icon: _jsx(IconPilcrow, { size: 16 }) },
+    { value: 'lines', icon: _jsx(IconBaselineDensityMedium, { size: 16 }) },
+    { value: 'commas', icon: _jsx(IconCsv, { size: 16 }) },
+    { value: 'custom', icon: _jsx(IconScissors, { size: 16 }) },
+];
+const REASON_LABELS = {
+    invalid_json: '@theorem.embedding.empty',
+    no_inputs: '@theorem.embedding.empty',
+    empty_input: '@theorem.embedding.empty',
+    text_off: '@theorem.embedding.text_off',
+};
+/** What the check says is wrong, about the input it names. */
+export function inputIssue(t, check, name) {
+    if (check.ok)
+        return null;
+    if (check.reason === 'attachments')
+        return `${name}: ${check.issues.map((issue) => attachmentIssueText(issue)).join(' ')}`;
+    if (check.reason === 'too_many_inputs')
+        return t('@theorem.embedding.too_many', { max: check.max });
+    return t(REASON_LABELS[check.reason], { name });
+}
+/**
+ * The documents: pasted text split as chosen, then files and JSON, in that
+ * order. Text files are split as the text is; any other file is one document.
+ */
+export function useEmbeddingDocuments(defaultText, rules, defaultDocuments = []) {
+    const t = useLabels();
+    const [text, setText] = useState(defaultText);
+    const [choice, setChoice] = useState('paragraphs');
+    const [separator, setSeparator] = useState('');
+    const [added, setAdded] = useState(() => [...defaultDocuments]);
+    const [view, setView] = useState('fields');
+    const [json, setJson] = useState(null);
+    const split = choice === 'custom' ? { separator } : choice;
+    const documents = useMemo(() => [
+        ...splitText(text, choice === 'custom' ? { separator } : choice).map((input) => ({ input })),
+        ...added,
+    ], [text, choice, separator, added]);
+    const inputs = useMemo(() => documents.map((document) => document.input), [documents]);
+    // why: The inputs hold every attachment as base64; writing them out on each render blocks the page.
+    const shownJson = useMemo(() => (view === 'json' ? (json ?? JSON.stringify(inputs, null, 2)) : ''), [view, json, inputs]);
+    const jsonInvalid = json !== null && readEmbeddingInputs(json) === undefined;
+    const issue = useMemo(() => {
+        for (const [at, input] of inputs.entries()) {
+            const found = inputIssue(t, checkInputs([input], rules), t('@theorem.embedding.document', { number: at + 1 }));
+            if (found)
+                return found;
+        }
+        return null;
+    }, [inputs, rules, t]);
+    const requests = useMemo(() => embeddingBatches(inputs, rules).length, [inputs, rules]);
+    const addFiles = async (files) => {
+        const words = files.filter(readsAsText);
+        const media = files.filter((file) => !readsAsText(file));
+        const pieces = await Promise.all(words.map(async (file) => splitText(await file.text(), split).map((input) => ({ input, from: file.name }))));
+        const encoded = await encodeFiles(media);
+        setAdded((previous) => [
+            ...previous,
+            ...pieces.flat(),
+            ...encoded.map(({ name, mimeType, data }) => ({
+                input: { parts: [{ type: 'media', mimeType, data }] },
+                from: name,
+            })),
+        ]);
+    };
+    return {
+        text,
+        setText,
+        choice,
+        setChoice,
+        separator,
+        setSeparator,
+        documents,
+        inputs,
+        issue,
+        requests,
+        view,
+        setView: (next) => {
+            setJson(null);
+            setView(next);
+        },
+        json: shownJson,
+        jsonInvalid,
+        setJson: (next) => {
+            setJson(next);
+            const parsed = readEmbeddingInputs(next);
+            if (parsed === undefined)
+                return;
+            setText('');
+            setAdded(parsed.map((input) => ({ input })));
+        },
+        addFiles,
+        remove: (at) => {
+            const shift = documents.length - added.length;
+            setAdded((previous) => previous.filter((_, other) => !at.includes(other + shift)));
+        },
+        /** Where the pasted text's documents end and the removable ones begin. */
+        fromText: documents.length - added.length,
+    };
+}
+function mediaOf(input) {
+    return typeof input === 'string' ? undefined : input.parts.find((part) => part.type !== 'text');
+}
+function textOf(input) {
+    if (typeof input === 'string')
+        return input;
+    return input.parts.flatMap((part) => (part.type === 'text' ? [part.text] : [])).join(' ');
+}
+/** What a document reads as in a list: its text, or its file's name, type, and size. */
+export function documentLabel(t, bytes, document, number) {
+    const media = mediaOf(document.input);
+    const words = textOf(document.input);
+    if (!media)
+        return { label: words, detail: null };
+    const size = media.type === 'media' ? bytes(base64Bytes(media.data)) : t('@theorem.embedding.held_file');
+    return {
+        label: words || (document.from ?? t('@theorem.embedding.document', { number })),
+        detail: `${media.mimeType} · ${size}`,
+    };
+}
+/** Where the text is cut, and the separator when it is one of the user's own. */
+/** A file field that reads what is dropped or chosen, and says which files it could not read. */
+export function EmbeddingFileDrop({ label, placeholder, accept, isMultiple = false, onFiles, }) {
+    const t = useLabels();
+    const [unreadable, setUnreadable] = useState(null);
+    return (_jsx(FileInput, { label: label, isLabelHidden: true, mode: "dropzone", isMultiple: isMultiple, accept: accept.join(','), value: null, placeholder: placeholder, status: unreadable ? { type: 'error', message: unreadable } : undefined, onChange: (files) => {
+            const list = files === null ? [] : Array.isArray(files) ? files : [files];
+            if (list.length === 0)
+                return;
+            setUnreadable(null);
+            onFiles(list).catch(() => {
+                setUnreadable(t('@theorem.embedding.unreadable', { name: list.map((file) => file.name).join(', ') }));
+            });
+        } }));
+}
+function SplitFields({ form }) {
+    const t = useLabels();
+    return (_jsxs(HStack, { gap: 2, vAlign: "center", wrap: "wrap", children: [_jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.embedding.split') }), _jsx(SegmentedControl, { label: t('@theorem.embedding.split'), size: "sm", value: form.choice, onChange: (next) => {
+                    form.setChoice(next);
+                }, children: SPLITS.map(({ value, icon }) => {
+                    const label = t(`@theorem.embedding.split_${value}`);
+                    return (_jsx(Tooltip, { content: label, children: _jsx(SegmentedControlItem, { value: value, label: label, icon: icon, isLabelHidden: true }) }, value));
+                }) }), form.choice === 'custom' ? (_jsx(StackItem, { size: "fill", children: _jsx(TextInput, { label: t('@theorem.embedding.separator'), isLabelHidden: true, placeholder: t('@theorem.embedding.separator'), size: "sm", value: form.separator, onChange: form.setSeparator }) })) : null] }));
+}
+/** How many pieces of a text a group previews; the rest are counted. */
+const PREVIEWED = 3;
+/** The added documents that are words, grouped by where they came from; the pasted text is already on screen. */
+function groupDocuments(form, t) {
+    const groups = new Map();
+    for (const [at, document] of form.documents.entries()) {
+        if (mediaOf(document.input))
+            continue;
+        if (at < form.fromText)
+            continue;
+        const source = document.from
+            ? t('@theorem.embedding.from_file', { name: document.from })
+            : t('@theorem.embedding.from_json');
+        const group = groups.get(source) ?? { source, at: [] };
+        group.at.push(at);
+        groups.set(source, group);
+    }
+    return [...groups.values()];
+}
+/** The first few pieces of one source, with the source and how many it made. */
+function TextGroup({ group, form }) {
+    const t = useLabels();
+    return (_jsxs(VStack, { gap: 1, children: [_jsxs(HStack, { gap: 1, vAlign: "center", children: [_jsx(StackItem, { size: "fill", children: _jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.embedding.group', { source: group.source, count: group.at.length }) }) }), _jsx(IconButton, { label: t('@theorem.embedding.remove', { name: group.source }), size: "sm", variant: "ghost", icon: _jsx(IconX, { size: 14 }), onClick: () => {
+                            form.remove(group.at);
+                        } })] }), group.at.slice(0, PREVIEWED).map((at) => (_jsx(Text, { maxLines: 2, children: textOf(form.documents[at]?.input ?? '') }, String(at)))), group.at.length > PREVIEWED ? (_jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.embedding.more', { count: group.at.length - PREVIEWED }) })) : null] }));
+}
+/** One file: its picture above its type, with its name and size on hover and Remove. */
+export function FileTile({ part, name, label, onRemove, }) {
+    const image = part.type === 'media' && part.mimeType.startsWith('image/');
+    return (_jsxs(VStack, { gap: 1, hAlign: "center", style: { width: TILE_PX, flexShrink: 0 }, children: [_jsx(Thumbnail, { ...(image && part.type === 'media'
+                    ? { src: `data:${part.mimeType};base64,${part.data}` }
+                    : {}), alt: "", label: label, onRemove: onRemove }), _jsx(Text, { type: "supporting", color: "secondary", maxLines: 1, style: { width: '100%', textAlign: 'center' }, children: name ?? part.mimeType })] }));
+}
+/** The width a tile keeps, so a long name is cut instead of widening it. */
+const TILE_PX = 72;
+const documentKeys = new WeakMap();
+let nextKey = 0;
+/** A key that follows the document, not its place, so removing one leaves the others' images alone. */
+function documentKey(document) {
+    let key = documentKeys.get(document);
+    if (key === undefined) {
+        key = nextKey;
+        nextKey += 1;
+        documentKeys.set(document, key);
+    }
+    return String(key);
+}
+/** Each file as a tile in a scrolling row. */
+function FileTiles({ form }) {
+    const t = useLabels();
+    const bytes = useBytes();
+    const files = form.documents.flatMap((document, at) => {
+        const part = mediaOf(document.input);
+        return part ? [{ document, part, at }] : [];
+    });
+    if (files.length === 0)
+        return null;
+    return (_jsx(HStack, { gap: 2, wrap: "nowrap", style: { overflowX: 'auto' }, children: files.map(({ document, part, at }) => {
+            const { label, detail } = documentLabel(t, bytes, document, at + 1);
+            return (_jsx(FileTile, { name: document.from, part: part, label: [label, detail].filter(Boolean).join(' · '), onRemove: () => {
+                    form.remove([at]);
+                } }, documentKey(document)));
+        }) }));
+}
+/** A preview of the documents: a few pieces per source, and every file as a tile. */
+function DocumentList({ form }) {
+    const t = useLabels();
+    const groups = groupDocuments(form, t);
+    if (groups.length === 0 && form.documents.length === 0)
+        return null;
+    return (_jsxs(VStack, { gap: 3, children: [groups.map((group) => (_jsx(TextGroup, { group: group, form: form }, group.source))), _jsx(FileTiles, { form: form })] }));
+}
+/** Text with its file beside it at two thirds and one third, or whichever of them there is. */
+export function TextBesideFile({ text, file }) {
+    if (!text || !file)
+        return _jsx(_Fragment, { children: text ?? file });
+    return (_jsxs(Grid, { columns: 3, gap: 3, children: [_jsx(GridSpan, { columns: 2, children: text }), _jsx(GridSpan, { columns: 1, children: file })] }));
+}
+/** The file types the documents take: the profile's attachments, and text files when it takes text. */
+function acceptedFiles(rules) {
+    const text = rules.text ? ['text/*', '.md', '.csv', '.json'] : [];
+    return [...(rules.attachments?.accept ?? []), ...text];
+}
+/** The text to split, and how it splits. */
+function DocumentText({ form }) {
+    const t = useLabels();
+    return (_jsxs(VStack, { gap: 3, children: [_jsx(TextArea, { label: t('@theorem.embedding.text'), isLabelHidden: true, value: form.text, placeholder: t('@theorem.embedding.text_placeholder'), rows: textRows(form.text, 4, 12), onChange: form.setText }), _jsx(SplitFields, { form: form })] }));
+}
+/** Text to split, files to add, and the documents they make. */
+function DocumentFields({ form, rules }) {
+    const t = useLabels();
+    const accept = acceptedFiles(rules);
+    const drop = accept.length > 0 ? (_jsx(EmbeddingFileDrop, { label: t('@theorem.embedding.files'), placeholder: t('@theorem.embedding.drop_files'), accept: accept, isMultiple: true, onFiles: form.addFiles })) : null;
+    return (_jsxs(VStack, { gap: 3, children: [_jsx(TextBesideFile, { text: rules.text ? _jsx(DocumentText, { form: form }) : null, file: drop }), _jsx(DocumentList, { form: form })] }));
+}
+/** What the documents still lack, or how many requests they make and the shortcut. */
+function documentsNote(t, form) {
+    if (form.jsonInvalid)
+        return t('@theorem.embedding.invalid_json');
+    if (form.inputs.length === 0)
+        return t('@theorem.embedding.no_documents');
+    return (form.issue ??
+        t('@theorem.embedding.ready', { count: form.inputs.length, requests: form.requests }));
+}
+/** The documents card: text and files as fields, or the inputs as JSON, and Index. */
+export function EmbeddingDocuments({ form, rules, isRunning, onRun, onStop, }) {
+    const t = useLabels();
+    const isReady = !form.jsonInvalid && form.inputs.length > 0 && form.issue === null;
+    return (_jsxs(RequestCard, { title: t('@theorem.embedding.documents'), view: form.view, hasFields: true, onView: form.setView, onRun: onRun, children: [form.view === 'fields' ? (_jsx(DocumentFields, { form: form, rules: rules })) : (_jsx(JsonRequest, { label: t('@theorem.embedding.documents'), text: form.json, isInvalid: form.jsonInvalid, onChange: form.setJson })), _jsx(RunBar, { note: documentsNote(t, form), isReady: isReady, isRunning: isRunning, runLabel: t('@theorem.embedding.index'), runningLabel: t('@theorem.embedding.indexing'), stopLabel: t('@theorem.embedding.stop'), onRun: onRun, onStop: onStop })] }));
+}

package/ui/EmbeddingQuery.d.ts

@@ -0,0 +1,27 @@
+import { type EmbeddingInput } from '@theoremjs/agents';
+import { type EmbeddingFields } from '../client/embedding-input.ts';
+import { type ConsoleView } from './ConsoleFrame.tsx';
+import { type Rules } from './EmbeddingDocuments.tsx';
+/** Where the embedded documents stand for a search: as embedded, or changed since. */
+export type IndexState = 'fresh' | 'stale' | 'model';
+/** The query, held as the JSON of the one input it sends, and the view it is edited in. */
+export declare function useEmbeddingQuery(defaultQuery: string, rules: Rules): {
+    json: string;
+    setJson: import("react").Dispatch<import("react").SetStateAction<string>>;
+    input: EmbeddingInput | undefined;
+    fields: EmbeddingFields | null;
+    issue: string | null;
+    shown: ConsoleView;
+    setView: import("react").Dispatch<import("react").SetStateAction<ConsoleView>>;
+    setFields: (next: EmbeddingFields) => void;
+};
+export type EmbeddingQueryForm = ReturnType<typeof useEmbeddingQuery>;
+/** The query card: its words and file, or its input as JSON, and Search. */
+export declare function EmbeddingQuery({ form, rules, index, isRunning, onRun, onStop, }: {
+    form: EmbeddingQueryForm;
+    rules: Rules;
+    index: IndexState;
+    isRunning: boolean;
+    onRun: (input: EmbeddingInput) => void;
+    onStop: () => void;
+}): import("react").JSX.Element;

package/ui/EmbeddingQuery.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { TextArea } from '@astryxdesign/core/TextArea';
+import { base64Bytes } from '@theoremjs/agents';
+import { useState } from 'react';
+import { checkInputs, fieldsInput, inputFields, readEmbeddingInput, } from "../client/embedding-input.js";
+import { encodeFiles } from "../client/encode-files.js";
+import { JsonRequest, RequestCard, RunBar, useBytes } from "./ConsoleFrame.js";
+import { EmbeddingFileDrop, FileTile, inputIssue, TextBesideFile, } from "./EmbeddingDocuments.js";
+import { useLabels } from "./labels-provider.js";
+import { textRows } from "./StateFields.js";
+/** The query, held as the JSON of the one input it sends, and the view it is edited in. */
+export function useEmbeddingQuery(defaultQuery, rules) {
+    const t = useLabels();
+    const [json, setJson] = useState(() => JSON.stringify(defaultQuery));
+    const input = readEmbeddingInput(json);
+    const fields = input === undefined ? null : inputFields(input);
+    const [view, setView] = useState('fields');
+    const issue = input === undefined
+        ? t('@theorem.embedding.query_invalid_json')
+        : inputIssue(t, checkInputs([input], rules), t('@theorem.embedding.query'));
+    return {
+        json,
+        setJson,
+        input,
+        fields,
+        issue,
+        shown: fields === null ? 'json' : view,
+        setView,
+        setFields: (next) => {
+            setJson(JSON.stringify(fieldsInput(next), null, 2));
+        },
+    };
+}
+/** The query's one file, or a drop for it when the profile takes files. */
+function QueryFile({ fields, accept, onChange, }) {
+    const t = useLabels();
+    const bytes = useBytes();
+    const part = fields.media[0];
+    if (part) {
+        const size = part.type === 'media' ? bytes(base64Bytes(part.data)) : t('@theorem.embedding.held_file');
+        return (_jsx(FileTile, { part: part, label: [part.mimeType, size].join(' · '), onRemove: () => {
+                onChange({ ...fields, media: [] });
+            } }));
+    }
+    if (!accept)
+        return null;
+    return (_jsx(EmbeddingFileDrop, { label: t('@theorem.embedding.query_file'), placeholder: t('@theorem.embedding.query_file'), accept: accept, onFiles: async (files) => {
+            const encoded = await encodeFiles(files);
+            onChange({
+                ...fields,
+                media: encoded.map(({ mimeType, data }) => ({
+                    type: 'media',
+                    mimeType,
+                    data,
+                })),
+            });
+        } }));
+}
+/** The query's words, and one file to search with when the profile takes files. */
+function QueryFields({ fields, rules, onChange, }) {
+    const t = useLabels();
+    const accept = rules.attachments?.accept;
+    const text = rules.text ? (_jsx(TextArea, { label: t('@theorem.embedding.query'), isLabelHidden: true, value: fields.text, placeholder: t('@theorem.embedding.query_placeholder'), rows: textRows(fields.text, 2, 6), onChange: (next) => {
+            onChange({ ...fields, text: next });
+        } })) : null;
+    const hasFile = fields.media.length > 0 || accept !== undefined;
+    const file = hasFile ? _jsx(QueryFile, { fields: fields, accept: accept, onChange: onChange }) : null;
+    return _jsx(TextBesideFile, { text: text, file: file });
+}
+/** What stands between the query and a search, once someone has tried one. */
+function queryNote(t, form, index, tried) {
+    if (!tried)
+        return null;
+    if (form.issue)
+        return form.issue;
+    if (index === 'stale')
+        return t('@theorem.embedding.stale');
+    if (index === 'model')
+        return t('@theorem.embedding.remodelled');
+    return null;
+}
+/** The query card: its words and file, or its input as JSON, and Search. */
+export function EmbeddingQuery({ form, rules, index, isRunning, onRun, onStop, }) {
+    const t = useLabels();
+    const { input } = form;
+    const isReady = form.issue === null && index === 'fresh' && input !== undefined;
+    // why: What blocks a search is said only once someone tries one, not before they have started.
+    const [tried, setTried] = useState(false);
+    const run = () => {
+        setTried(true);
+        if (isReady)
+            onRun(input);
+    };
+    return (_jsxs(RequestCard, { title: t('@theorem.embedding.query'), view: form.shown, hasFields: form.fields !== null, onView: form.setView, onRun: run, children: [form.shown === 'fields' && form.fields !== null ? (_jsx(QueryFields, { fields: form.fields, rules: rules, onChange: form.setFields })) : (_jsx(JsonRequest, { label: t('@theorem.embedding.query'), text: form.json, isInvalid: input === undefined, onChange: form.setJson })), _jsx(RunBar, { note: queryNote(t, form, index, tried), isReady: isReady || !tried, isRunning: isRunning, runLabel: t('@theorem.embedding.search'), runningLabel: t('@theorem.embedding.searching'), stopLabel: t('@theorem.embedding.stop'), onRun: run, onStop: onStop })] }));
+}

package/ui/EmbeddingResults.d.ts

@@ -0,0 +1,41 @@
+import type { EmbeddingResult } from '@theoremjs/agents';
+import type { EmbeddingMatch } from '../client/embedding-input.ts';
+import type { EmbeddingIndex, IndexProgress } from '../hooks/use-embedding-index.ts';
+import type { OneCallState } from '../hooks/use-one-call.ts';
+import { type EmbeddingDocument } from './EmbeddingDocuments.tsx';
+/** Which document the space and the matches both point at, and how either changes it. */
+export type Pointing = {
+    hovered: number | null;
+    onHover(index: number | null): void;
+};
+/** Where indexing is, as `useEmbeddingIndex` reports it. */
+export type IndexRun = OneCallState<'indexing', EmbeddingIndex> & {
+    progress: IndexProgress | null;
+};
+/** Where the search is, as `useTheoremEmbedding` reports it. */
+export type SearchRun = OneCallState<'embedding', EmbeddingResult>;
+export type IndexCardProps = {
+    run: IndexRun;
+    /** The documents as they were indexed. */
+    documents: readonly EmbeddingDocument[];
+    /** The last query's vector, once a search has run. */
+    query: readonly number[] | null;
+    /** The documents ranked by the query, best first. */
+    matches: readonly EmbeddingMatch[];
+    pointing: Pointing;
+};
+/** The index: the documents as a space or a list, or why it failed. */
+export declare function IndexCard(props: IndexCardProps): import("react").JSX.Element;
+/**
+ * What the search found: the matches for the last query, ranked in the index,
+ * best first. Each keeps one quiet line for the model, time, tokens,
+ * and cost of its own calls.
+ */
+export declare function EmbeddingResults({ index, search, documents, matches, pointing, }: {
+    index: IndexRun;
+    search: SearchRun;
+    documents: readonly EmbeddingDocument[];
+    /** The documents ranked by the last query, best first. */
+    matches: readonly EmbeddingMatch[];
+    pointing: Pointing;
+}): import("react").JSX.Element;

package/ui/EmbeddingResults.js

@@ -0,0 +1,165 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Banner } from '@astryxdesign/core/Banner';
+import { Button } from '@astryxdesign/core/Button';
+import { HStack } from '@astryxdesign/core/HStack';
+import { useClipboard } from '@astryxdesign/core/hooks';
+import { Icon } from '@astryxdesign/core/Icon';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { SegmentedControl, SegmentedControlItem } from '@astryxdesign/core/SegmentedControl';
+import { StackItem } from '@astryxdesign/core/Stack';
+import { Text } from '@astryxdesign/core/Text';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconCheck, IconCopy } from '@tabler/icons-react';
+import { lazy, Suspense, useEffect, useMemo, useState } from 'react';
+import { layoutSpaceSoon, outlierThreshold, placeQuery, } from "../client/embedding-space.js";
+import { Arrive } from "./arrive.js";
+import { useBytes } from "./ConsoleFrame.js";
+import { ResultStack, Share, useNumbers } from "./DecisionAnswers.js";
+import { documentLabel } from "./EmbeddingDocuments.js";
+import { useLabels } from "./labels-provider.js";
+import { keyedByContent } from "./row-keys.js";
+import { ChartBody, ChartCard } from "./trace-patterns.js";
+const EmbeddingSpaceView = lazy(() => import("./embedding-space-view.js").then((module) => ({ default: module.EmbeddingSpaceView })));
+/** Matches the card lists, best first; the space highlights the same ones. */
+const MATCHES_SHOWN = 10;
+/** The most the space or the list stands, in pixels. */
+const SPACE_PX = 460;
+/** Values a vector shows before the rest are counted. */
+const PREVIEW_VALUES = 4;
+/** A list that reads as one to a screen reader and looks like none: no bullets, no indent. */
+const BARE_LIST = {
+    listStyle: 'none',
+    margin: 0,
+    padding: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 12,
+};
+/** Ground behind the document both views point at. */
+const POINTED = 'var(--color-background-muted)';
+function Failure({ failure }) {
+    return failure ? _jsx(Banner, { status: "error", role: "alert", title: failure.error }) : null;
+}
+/** A document's name as both cards word it: its words, its file's name, or its number. */
+function useDocumentName(inputs, documents) {
+    const t = useLabels();
+    const bytes = useBytes();
+    return (at) => documentLabel(t, bytes, documents[at] ?? { input: inputs[at] }, at + 1).label;
+}
+/** The documents most like the query, each with its cosine similarity, best first. */
+function MatchesBody({ matches, index, documents, pointing, }) {
+    const t = useLabels();
+    const n = useNumbers();
+    const label = useDocumentName(index.inputs, documents);
+    const lead = matches[0];
+    if (!lead)
+        return _jsx(Banner, { status: "warning", title: t('@theorem.embedding.no_matches') });
+    const shown = matches.slice(0, MATCHES_SHOWN);
+    return (_jsx(ChartBody, { title: t('@theorem.embedding.matches'), value: n.decimal.format(lead.score), note: matches.length > shown.length
+            ? t('@theorem.embedding.matches_shown', { shown: shown.length, count: matches.length })
+            : t('@theorem.embedding.best', { name: label(lead.index) }), children: _jsx("ul", { style: BARE_LIST, children: shown.map((match, at) => {
+                const name = label(match.index);
+                const score = n.decimal.format(match.score);
+                return (_jsx("li", { "aria-label": `${name}: ${score}`, onPointerEnter: () => pointing.onHover(match.index), onPointerLeave: () => pointing.onHover(null), style: {
+                        borderRadius: 'var(--radius-container)',
+                        margin: '-4px -8px',
+                        padding: '4px 8px',
+                        background: pointing.hovered === match.index ? POINTED : undefined,
+                    }, children: _jsxs(VStack, { gap: 1, children: [_jsxs(HStack, { gap: 3, vAlign: "start", "aria-hidden": true, children: [_jsx(StackItem, { size: "fill", children: _jsx(Text, { type: "supporting", maxLines: 2, children: name }) }), _jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: score })] }), _jsx(Share, { value: Math.max(match.score, 0), isLead: at === 0 })] }) }, match.index));
+            }) }) }));
+}
+/** Copies a text; the button says so for a moment after. */
+function CopyText({ text, label, isIcon }) {
+    const t = useLabels();
+    const copied = t('@theorem.embedding.copied');
+    const { copy, isCopied } = useClipboard({ announce: copied });
+    const shown = isCopied ? copied : label;
+    return isIcon ? (_jsx(IconButton, { label: shown, tooltip: shown, size: "sm", variant: "ghost", icon: _jsx(Icon, { icon: isCopied ? IconCheck : IconCopy, size: "xsm", color: "secondary" }), onClick: () => void copy(text) })) : (_jsx(Button, { label: shown, size: "sm", variant: "ghost", onClick: () => void copy(text) }));
+}
+/** Every document with the first values of its vector, each vector copyable, or all of them at once. */
+function VectorList({ vectors, name, pointing, }) {
+    const t = useLabels();
+    const all = useMemo(() => JSON.stringify(vectors), [vectors]);
+    return (_jsxs(VStack, { gap: 2, children: [_jsxs(HStack, { gap: 2, vAlign: "center", children: [_jsx(StackItem, { size: "fill", children: _jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.embedding.width', { dimensions: vectors[0]?.length ?? 0 }) }) }), _jsx(CopyText, { text: all, label: t('@theorem.embedding.copy_vectors') })] }), _jsx("ul", { style: { ...BARE_LIST, gap: 0, maxHeight: SPACE_PX, overflowY: 'auto' }, children: keyedByContent(vectors, (vector) => vector.slice(0, PREVIEW_VALUES * 2).join()).map(({ item: vector, index: at, key }) => (_jsx("li", { onPointerEnter: () => pointing.onHover(at), onPointerLeave: () => pointing.onHover(null), style: {
+                        borderRadius: 'var(--radius-container)',
+                        padding: '4px 8px',
+                        background: pointing.hovered === at ? POINTED : undefined,
+                    }, children: _jsxs(HStack, { gap: 2, vAlign: "center", children: [_jsx(StackItem, { size: "fill", children: _jsxs(VStack, { gap: 0, children: [_jsx(Text, { type: "supporting", maxLines: 1, children: name(at) }), _jsx(Text, { type: "supporting", color: "secondary", maxLines: 1, hasTabularNumbers: true, children: `[${vector
+                                                .slice(0, PREVIEW_VALUES)
+                                                .map((v) => v.toFixed(4))
+                                                .join(', ')}${vector.length > PREVIEW_VALUES ? ', …' : ''}]` })] }) }), _jsx(CopyText, { text: JSON.stringify(vector), label: t('@theorem.embedding.copy_vector'), isIcon: true })] }) }, key))) })] }));
+}
+/** The space for an index, laid out in slices so a large one never freezes the page; `null` until it is ready. */
+function useSpace(vectors) {
+    const [space, setSpace] = useState(null);
+    useEffect(() => {
+        const stop = new AbortController();
+        layoutSpaceSoon(vectors, stop.signal).then((next) => setSpace({ of: vectors, space: next }), 
+        // why: only the abort rejects, when the vectors changed or the card went; the newer run answers.
+        () => { });
+        return () => stop.abort();
+    }, [vectors]);
+    return space?.of === vectors ? space.space : null;
+}
+/**
+ * The matches the space joins to the query: those shown whose similarity
+ * stands out against the query's similarity to every document, each with how
+ * far it passes that threshold, from 0 at it to 1 at identical.
+ */
+function closenessOf(matches) {
+    const threshold = outlierThreshold(matches.map((m) => m.score));
+    return matches
+        .slice(0, MATCHES_SHOWN)
+        .filter((m) => m.score > threshold)
+        .map((m) => ({
+        index: m.index,
+        closeness: threshold < 1 ? Math.min((m.score - threshold) / (1 - threshold), 1) : 1,
+    }));
+}
+const SPACE_ROOM = { width: '100%', aspectRatio: '1 / 1', maxHeight: SPACE_PX };
+/** The space, with the last query landed among its matches; an empty box of the same size until it is laid out. */
+function IndexSpace({ space, query, matches, name, pointing, onUnavailable, }) {
+    const t = useLabels();
+    const landed = useMemo(() => (space && query ? placeQuery(space, query) : null), [space, query]);
+    const close = useMemo(() => (landed ? closenessOf(matches) : []), [landed, matches]);
+    if (!space)
+        return _jsx("div", { style: SPACE_ROOM });
+    const label = t('@theorem.embedding.space_label', { count: space.documents.length });
+    return (_jsx(Suspense, { fallback: _jsx("div", { style: SPACE_ROOM }), children: _jsx(EmbeddingSpaceView, { space: space, query: landed, matches: close, hovered: pointing.hovered, onHover: pointing.onHover, nameOf: name, label: landed ? `${label} ${t('@theorem.embedding.space_query')}` : label, onUnavailable: onUnavailable }) }));
+}
+/** The switch between the space and the list. */
+function ViewSwitch({ view, onChange }) {
+    const t = useLabels();
+    return (_jsxs(SegmentedControl, { label: t('@theorem.embedding.view'), size: "sm", value: view, onChange: (next) => onChange(next === 'list' ? 'list' : 'space'), children: [_jsx(SegmentedControlItem, { value: "space", label: t('@theorem.embedding.space') }), _jsx(SegmentedControlItem, { value: "list", label: t('@theorem.embedding.list') })] }));
+}
+/** The vectors listed, saying first when the space could not be drawn. */
+function IndexList({ vectors, name, pointing, isDrawable, }) {
+    const t = useLabels();
+    return (_jsxs(VStack, { gap: 2, children: [isDrawable ? null : (_jsx(Text, { type: "supporting", color: "secondary", children: t('@theorem.embedding.space_off') })), _jsx(VectorList, { vectors: vectors, name: name, pointing: pointing })] }));
+}
+/** The finished index, as a space or a list. */
+function IndexedCard({ run, result, documents, query, matches, pointing, }) {
+    const t = useLabels();
+    const [view, setView] = useState('space');
+    const [isDrawable, setDrawable] = useState(true);
+    const space = useSpace(result.vectors);
+    const name = useDocumentName(result.inputs, documents);
+    return (_jsxs(VStack, { gap: 4, children: [_jsx(Failure, { failure: run.failure }), _jsx(ResultStack, { model: result.model, usage: result.usage, elapsedMs: run.elapsedMs, tokens: (count) => t('@theorem.embedding.tokens', { count }), children: _jsx(ChartCard, { title: t('@theorem.embedding.index'), value: t('@theorem.embedding.indexed', { count: result.vectors.length }), aside: isDrawable ? _jsx(ViewSwitch, { view: view, onChange: setView }) : null, children: isDrawable && view === 'space' ? (_jsx(IndexSpace, { space: space, query: query, matches: matches, name: name, pointing: pointing, onUnavailable: () => setDrawable(false) })) : (_jsx(IndexList, { vectors: result.vectors, name: name, pointing: pointing, isDrawable: isDrawable })) }) })] }));
+}
+/** The index: the documents as a space or a list, or why it failed. */
+export function IndexCard(props) {
+    const { result, failure } = props.run;
+    if (!result)
+        return _jsx(Failure, { failure: failure });
+    return _jsx(IndexedCard, { ...props, result: result });
+}
+/**
+ * What the search found: the matches for the last query, ranked in the index,
+ * best first. Each keeps one quiet line for the model, time, tokens,
+ * and cost of its own calls.
+ */
+export function EmbeddingResults({ index, search, documents, matches, pointing, }) {
+    const t = useLabels();
+    const searched = search.result?.embeddings[0]?.values;
+    return (_jsxs(VStack, { gap: 4, children: [_jsx(Failure, { failure: search.failure }), searched && index.result ? (_jsx(ResultStack, { model: search.result?.model ?? '', usage: search.result?.usage, elapsedMs: search.elapsedMs, isStale: search.status === 'embedding', tokens: (count) => t('@theorem.embedding.tokens', { count }), children: _jsx(Arrive, { children: _jsx(MatchesBody, { matches: matches, index: index.result, documents: documents, pointing: pointing }) }) })) : null] }));
+}

package/ui/EmbeddingSpace.d.ts

@@ -0,0 +1,26 @@
+import type { EmbeddingSpace, SpacePoint } from '../client/embedding-space.ts';
+import type { QueryMatch } from '../client/space-geometry.ts';
+export type EmbeddingSpaceViewProps = {
+    space: EmbeddingSpace;
+    /** Where the last query landed, or `null` before any. */
+    query: SpacePoint | null;
+    matches: readonly QueryMatch[];
+    hovered: number | null;
+    onHover(index: number | null): void;
+    /** A document's name, as the matches list words it. */
+    nameOf(index: number): string;
+    /** What the canvas says to a screen reader. */
+    label: string;
+    /** The browser cannot draw the space. */
+    onUnavailable(): void;
+};
+/**
+ * The index drawn as a space: each document a dot in a ball, placed by the
+ * three directions the vectors differ most along, with a circle round the rim
+ * in each plane two of them span. Each document is joined to its nearest
+ * neighbour by cosine similarity when that pair stands out from the index's
+ * typical pair; documents the lines connect share a colour, and a query's
+ * white dot has a line to each match that stands out the same way. Drag to turn
+ * it; point at a dot to name its document.
+ */
+export declare function EmbeddingSpaceView(props: EmbeddingSpaceViewProps): import("react").JSX.Element;