@theoremjs/react 0.0.0-stage → 0.3.1

package/ui/code-language.d.ts

@@ -0,0 +1,12 @@
+import type { MarkdownAstRoot } from '@astryxdesign/core/Markdown';
+import type { MarkdownExtensionNode } from '@astryxdesign/core/Markdown/plugins';
+/** The language of untagged code, or `undefined` when the detector is unsure or the language would not be coloured. */
+export declare function detectedCodeLanguage(code: string): string | undefined;
+/** The document with its untagged fences labelled. Unsettled while streaming: the last block may be an open fence. */
+export declare function labelUntaggedCode(document: MarkdownAstRoot<MarkdownExtensionNode>, isFinal: boolean): MarkdownAstRoot<MarkdownExtensionNode>;
+/**
+ * A Markdown plugin that labels fenced code the reply left untagged, so it is coloured like a tagged
+ * fence. A fence with a language is left as written. While the reply streams, the last block is left
+ * alone: it may be a fence still open, and its language would change as it grows.
+ */
+export declare const codeLanguagePlugin: import("@astryxdesign/core/Markdown/plugins").MarkdownPluginEntry<never>;

package/ui/code-language.js

@@ -0,0 +1,50 @@
+import { createMarkdownPlugin } from '@astryxdesign/core/Markdown/plugins';
+import { detectLanguage } from '@speed-highlight/core/detect';
+/** The languages Astryx's `CodeBlock` colours, as the detector names them. A guess outside it would only add a label. */
+const COLOURED = new Set(['js', 'ts', 'py', 'bash', 'json', 'css', 'html', 'xml', 'yaml', 'md']);
+/** The language of untagged code, or `undefined` when the detector is unsure or the language would not be coloured. */
+export function detectedCodeLanguage(code) {
+    const language = detectLanguage(code);
+    return COLOURED.has(language) ? language : undefined;
+}
+function tagged(node) {
+    if (node.type === 'code') {
+        const code = node;
+        if (code.lang !== null)
+            return node;
+        const lang = detectedCodeLanguage(code.value);
+        return lang === undefined ? node : { ...code, lang };
+    }
+    if (node.children === undefined)
+        return node;
+    let changed = false;
+    const children = node.children.map((child) => {
+        const next = tagged(child);
+        if (next !== child)
+            changed = true;
+        return next;
+    });
+    return changed ? { ...node, children } : node;
+}
+/** The document with its untagged fences labelled. Unsettled while streaming: the last block may be an open fence. */
+export function labelUntaggedCode(document, isFinal) {
+    const { children } = document;
+    const settled = isFinal ? children : children.slice(0, -1);
+    const next = settled.map((child) => tagged(child));
+    if (next.every((child, index) => child === settled[index]))
+        return document;
+    return {
+        ...document,
+        children: [...next, ...children.slice(settled.length)],
+    };
+}
+/**
+ * A Markdown plugin that labels fenced code the reply left untagged, so it is coloured like a tagged
+ * fence. A fence with a language is left as written. While the reply streams, the last block is left
+ * alone: it may be a fence still open, and its language would change as it grows.
+ */
+export const codeLanguagePlugin = createMarkdownPlugin({
+    apiVersion: 1,
+    name: 'theorem-code-language',
+    transform: (document, { isFinal }) => labelUntaggedCode(document, isFinal),
+});

package/ui/disclosure-motion.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject } from 'react';
+/**
+ * Eases every disclosure under `ref` open and shut. `onOpened` runs once the
+ * new panel is in the DOM, with a promise for its motion finishing.
+ */
+export declare function useDisclosureMotion(ref: RefObject<HTMLElement | null>, onOpened?: (trigger: Element, panel: HTMLElement, motion: Promise<unknown>) => void): void;

package/ui/disclosure-motion.js

@@ -0,0 +1,207 @@
+import { useEffect } from 'react';
+/**
+ * Easing for disclosures whose panel mounts on open and unmounts on close
+ * (ChatToolCalls row details, TreeList branches): CSS can't ease an element
+ * that's already gone, so a close is held until the panel has eased shut,
+ * then replayed; an open eases the new panel up from nothing. Panels that
+ * carry their own transition (the themed Collapsible) are left alone.
+ */
+/** The panel a disclosure trigger shows: its aria-controls target, or a tree item's group. */
+function panelOf(trigger) {
+    const id = trigger.getAttribute('aria-controls');
+    if (id)
+        return document.getElementById(id);
+    return (trigger.closest('[role="treeitem"]')?.querySelector(':scope > [role="group"]') ??
+        null);
+}
+function ownsMotion(panel) {
+    return getComputedStyle(panel)
+        .transitionDuration.split(',')
+        .some((d) => Number.parseFloat(d) > 0);
+}
+function isToggleKey(event) {
+    return !(event instanceof KeyboardEvent) || event.key === 'Enter' || event.key === ' ';
+}
+/**
+ * The element pressed and the disclosure trigger it sits in, when that trigger is under `root`. In a
+ * tree, the press is the row's own: a leaf's row toggles nothing, and a row with an action of its own
+ * (a label that selects it, a button at its end) toggles only at its chevron.
+ */
+function pressedToggle(event, root) {
+    if (!(event.target instanceof Element))
+        return undefined;
+    const row = event.target.closest('[role="treeitem"]');
+    const trigger = row ? treeToggle(event.target, row) : event.target.closest('[aria-expanded]');
+    if (!trigger || !root.contains(trigger))
+        return undefined;
+    return { target: event.target, trigger };
+}
+/** The tree row a press toggles: none for a leaf, and for a row with an action of its own, only a press at its chevron. */
+function treeToggle(target, row) {
+    if (!row.hasAttribute('aria-expanded'))
+        return undefined;
+    if (target.closest('[data-tree-toggle]') !== null)
+        return row;
+    const acts = row.querySelector(':scope > div :is(button:not([data-tree-toggle]), a[href])') !== null;
+    return acts ? undefined : row;
+}
+/** Stops the event: the component does not see it. */
+function hold(event) {
+    event.stopPropagation();
+    event.preventDefault();
+}
+/** A copy of the pressed key or click, to send once the panel has eased shut. */
+function replayOf(event) {
+    return event instanceof KeyboardEvent
+        ? new KeyboardEvent(event.type, { key: event.key, bubbles: true, cancelable: true })
+        : new MouseEvent(event.type, { bubbles: true, cancelable: true });
+}
+/** CSS time (`0.3s`, `300ms`) in milliseconds. */
+function ms(time) {
+    const value = Number.parseFloat(time);
+    return time.trim().endsWith('ms') ? value : value * 1000;
+}
+/** Eases a panel's height between shut and its natural height, the theme's medium duration and standard curve. */
+function ease(panel, direction) {
+    const style = getComputedStyle(panel);
+    const open = {
+        height: `${String(panel.getBoundingClientRect().height)}px`,
+        paddingTop: style.paddingTop,
+        paddingBottom: style.paddingBottom,
+    };
+    const shut = { height: '0px', paddingTop: '0px', paddingBottom: '0px' };
+    const frames = direction === 'open' ? [shut, open] : [open, shut];
+    for (const animation of panel.getAnimations())
+        animation.cancel();
+    return panel.animate(frames.map((frame) => ({ ...frame, boxSizing: 'border-box', overflow: 'clip' })), {
+        duration: ms(style.getPropertyValue('--duration-medium')),
+        easing: style.getPropertyValue('--ease-standard').trim(),
+        // why: A shut panel stays shut until its unmount; an open one hands back to its natural height.
+        fill: direction === 'close' ? 'forwards' : 'none',
+    });
+}
+/** Every animation on a panel, settled; a cancelled one rejects `finished`, so settle rather than await all. */
+function settled(panel) {
+    return Promise.allSettled(panel.getAnimations().map((animation) => animation.finished));
+}
+/** The attribute Astryx's chat sets on its scroller while it follows new content to the bottom. */
+const FOLLOWING = 'data-astryx-chat-following';
+/** How far from its bottom a scroll up must land for Astryx's chat to stop following: past its 10px lock threshold. */
+const LET_GO = 11;
+/**
+ * Keeps a trigger the reader opened where it was while its panel grows. A
+ * chat that follows its bottom would spring past it, so the follow is let go
+ * first: a scroll up just past the chat's threshold reads as the reader's.
+ * The panel's growth then gives the room back, and the trigger ends where it
+ * was. A chat too short to scroll yet is held after each layout instead,
+ * after the follow's own frame, which also lets it go.
+ */
+function holdInPlace(trigger, panel, motion) {
+    const scroller = trigger.closest(`[${FOLLOWING}]`);
+    if (!scroller)
+        return;
+    const top = trigger.getBoundingClientRect().top;
+    const room = () => scroller.scrollHeight - scroller.clientHeight - scroller.scrollTop;
+    scroller.scrollTop -= Math.max(0, LET_GO - room());
+    let done = false;
+    void motion.then(() => setTimeout(() => (done = true), 1000));
+    const held = new ResizeObserver(() => {
+        const drift = trigger.getBoundingClientRect().top - top;
+        if (drift && scroller.hasAttribute(FOLLOWING))
+            scroller.scrollTop += drift;
+    });
+    held.observe(panel);
+    const giveBack = () => {
+        const drift = trigger.getBoundingClientRect().top - top;
+        // invariant: Never back within the threshold, or the chat would follow again.
+        if (drift > 0 && !scroller.hasAttribute(FOLLOWING)) {
+            scroller.scrollTop += Math.max(0, Math.min(drift, room() - LET_GO));
+        }
+        if (done || (drift <= 0.5 && !scroller.hasAttribute(FOLLOWING)))
+            held.disconnect();
+        else
+            requestAnimationFrame(giveBack);
+    };
+    requestAnimationFrame(giveBack);
+}
+/**
+ * Eases every disclosure under `ref` open and shut. `onOpened` runs once the
+ * new panel is in the DOM, with a promise for its motion finishing.
+ */
+export function useDisclosureMotion(ref, onOpened) {
+    useEffect(() => {
+        const root = ref.current;
+        if (!root)
+            return;
+        const still = matchMedia('(prefers-reduced-motion: reduce)');
+        const closing = new WeakSet();
+        const replaying = new WeakSet();
+        // why: The trigger the reader just pressed to open; opens the page makes itself aren't eased or followed.
+        let opening;
+        /** The trigger the reader pressed opens: note it until the toggle commits, within this event. */
+        const noteOpening = (trigger) => {
+            opening = trigger;
+            // why: A stale note must not claim a later change.
+            setTimeout(() => {
+                if (opening === trigger)
+                    opening = undefined;
+            });
+        };
+        /** The panel a close should ease shut first; none when motion is off or the panel eases itself. */
+        const panelToEase = (trigger) => {
+            const panel = panelOf(trigger);
+            return panel && !still.matches && !ownsMotion(panel) ? panel : undefined;
+        };
+        const before = (event) => {
+            if (!isToggleKey(event) || replaying.has(event))
+                return;
+            const pressed = pressedToggle(event, root);
+            if (!pressed)
+                return;
+            const { target, trigger } = pressed;
+            if (closing.has(trigger)) {
+                hold(event);
+                return;
+            }
+            if (trigger.getAttribute('aria-expanded') !== 'true') {
+                noteOpening(trigger);
+                return;
+            }
+            const panel = panelToEase(trigger);
+            if (!panel)
+                return;
+            hold(event);
+            closing.add(trigger);
+            const replay = replayOf(event);
+            void ease(panel, 'close').finished.then(() => {
+                closing.delete(trigger);
+                replaying.add(replay);
+                target.dispatchEvent(replay);
+            });
+        };
+        // why: After the component commits the toggle (a component may stop the event, so
+        // watch the attribute rather than wait for the event to bubble): ease the new panel.
+        const opened = new MutationObserver(() => {
+            const trigger = opening;
+            if (trigger?.getAttribute('aria-expanded') !== 'true')
+                return;
+            opening = undefined;
+            const panel = panelOf(trigger);
+            if (!panel)
+                return;
+            if (!still.matches && !ownsMotion(panel))
+                ease(panel, 'open');
+            const motion = settled(panel);
+            holdInPlace(trigger, panel, motion);
+            onOpened?.(trigger, panel, motion);
+        });
+        opened.observe(root, { subtree: true, attributeFilter: ['aria-expanded'] });
+        root.addEventListener('click', before, true);
+        root.addEventListener('keydown', before, true);
+        return () => {
+            opened.disconnect();
+            root.removeEventListener('click', before, true);
+            root.removeEventListener('keydown', before, true);
+        };
+    }, [ref, onOpened]);
+}

package/ui/embedding-space-gl.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Draws the embedding space with WebGL2 and nothing else: anti-aliased lines,
+ * solid dots and the query's white dot, laid over the card with premultiplied
+ * alpha so the card shows through. Dots cover whatever lies behind them, and
+ * every line stops just short of the dot it reaches; the far side of the
+ * ball draws smaller and fainter. No React here: the component owns one
+ * renderer and feeds it.
+ *
+ * @module
+ */
+import type { EmbeddingSpace, SpacePoint } from '../client/embedding-space.ts';
+import { type QueryMatch } from '../client/space-geometry.ts';
+/** What the space highlights: a query's matches, and the document under the pointer. */
+export type SpaceFocus = {
+    query: SpacePoint | null;
+    matches: readonly QueryMatch[];
+    hovered: number | null;
+};
+export type SpaceRenderer = {
+    /** Shows a new index: its clusters grow in, one after another. */
+    setSpace(space: EmbeddingSpace): void;
+    setFocus(focus: SpaceFocus): void;
+    /** The document nearest a point in CSS pixels from the canvas's corner, if one is close and facing. */
+    pick(x: number, y: number): number | null;
+    /** Turns the sphere as a drag moves, in CSS pixels. */
+    drag(dx: number, dy: number): void;
+    release(): void;
+};
+/**
+ * One renderer for one canvas. Throws {@link SpaceUnavailable} when the
+ * browser cannot draw it, so the caller shows the list instead.
+ */
+export declare function createSpaceRenderer(canvas: HTMLCanvasElement, { still }: {
+    still: boolean;
+}): SpaceRenderer & {
+    destroy(): void;
+};