@adecore/agents-react 0.24.2 → 0.25.0

package/src/chat/ui/intelligent-ui/renderers/content.tsx

@@ -1,8 +1,8 @@
 import clsx from 'clsx';
-import { createContext, useContext, useId } from 'react';
+import { createContext, useContext, useId, useState, type ReactNode } from 'react';
 import { useTranslation } from 'react-i18next';
 import type { UiProps } from '@adecore/intelligent-ui';
-import { PreviewCard, Tooltip } from '@adecore/ui';
+import { Pill, PreviewCard, Tooltip, Wipe } from '@adecore/ui';
 import { formatNumber } from '@adecore/ui/format';
 import { useChatHost } from '../../../../host';
 import { CodeBlock } from '../../CodeBlock';
@@ -24,11 +24,39 @@ export function CodeBlockRenderer({ node }: UiRendererProps<UiProps<'CodeBlock'>
     );
 }
 
-/* Its own component, so the host's hook is only called for an image that names an attachment. */
-function AttachedImage({ scopeId, chatId, attachmentId, alt }: { scopeId: string; chatId: string; attachmentId: string; alt: string }) {
+// Set by a Gallery, so the images inside it draw as cells of its grid.
+const GalleryContext = createContext(false);
+
+/*
+ * Its own component, so the host's hook is only called for an image that names an attachment. In a
+ * gallery a cell that cannot show its picture says what it was, since the square alone tells nothing.
+ */
+function AttachedImage({
+    scopeId,
+    chatId,
+    attachmentId,
+    alt,
+    cell,
+    unnamed
+}: {
+    scopeId: string;
+    chatId: string;
+    attachmentId: string;
+    alt: string;
+    cell: boolean;
+    unnamed: boolean;
+}) {
     const host = useChatHost();
     const source = host.attachments.useUrl(scopeId, chatId, attachmentId);
-    return <ImageThumb source={source} alt={alt} className="max-h-70 max-w-full object-contain" />;
+    if (!cell) {
+        return <ImageThumb source={source} alt={alt} className="max-h-70 max-w-full object-contain" />;
+    }
+    return (
+        <>
+            <ImageThumb source={source} alt={alt} aspect={1} />
+            {unnamed && source.failure !== null && <figcaption className="text-xs wrap-anywhere text-text-faint">{alt}</figcaption>}
+        </>
+    );
 }
 
 /*
@@ -37,21 +65,128 @@ function AttachedImage({ scopeId, chatId, attachmentId, alt }: { scopeId: string
  */
 export function ImageRenderer({ node, children, context }: UiRendererProps<UiProps<'Image'>>) {
     const { t } = useTranslation('agent-chat');
+    const cell = useContext(GalleryContext);
     const { attachment, alt } = node.props;
     const caption = uiNodeLabel(node);
     const name = alt ?? (caption === '' ? t('blocks.image.label') : caption);
     return (
-        <figure className="flex flex-col items-start gap-1.5">
+        <figure className={cell ? 'flex min-w-0 flex-col gap-1' : 'flex flex-col items-start gap-1.5'}>
             {attachment === undefined ? (
-                <ImageThumb source={{ url: null, failure: t('blocks.image.unavailable') }} alt={name} />
+                <ImageThumb source={{ url: null, failure: t('blocks.image.unavailable') }} alt={name} aspect={cell ? 1 : undefined} />
             ) : (
-                <AttachedImage scopeId={context.scopeId} chatId={context.chatId} attachmentId={attachment} alt={name} />
+                <AttachedImage scopeId={context.scopeId} chatId={context.chatId} attachmentId={attachment} alt={name} cell={cell} unnamed={caption === ''} />
+            )}
+            {caption !== '' && <figcaption className={cell ? 'text-xs wrap-anywhere text-text-muted' : 'px-2 text-xs text-text-muted'}>{children}</figcaption>}
+            {cell && caption === '' && attachment === undefined && (
+                <figcaption className="text-xs wrap-anywhere text-text-faint">{alt ?? t('blocks.image.unavailable')}</figcaption>
             )}
-            {caption !== '' && <figcaption className="px-2 text-xs text-text-muted">{children}</figcaption>}
         </figure>
     );
 }
 
+/* Three columns, two in a narrow block; the container decides, not the window, since a chat can be any width. */
+export function GalleryRenderer({ node, children }: UiRendererProps<UiProps<'Gallery'>>) {
+    const { t } = useTranslation('agent-chat');
+    return (
+        <GalleryContext value>
+            <div role="group" aria-label={t('blocks.gallery.label', { count: uiChildrenOf(node, 'Image').length })} className="@container px-2">
+                <div className="chat-ui-nodes grid grid-cols-2 gap-2 @min-[420px]:grid-cols-3">{children}</div>
+            </div>
+        </GalleryContext>
+    );
+}
+
+// The shape of the frame until the first picture reports its own.
+const COMPARE_ASPECT = 4 / 3;
+
+/* The tallest a comparison stands, in pixels: `max-h-96`. */
+const COMPARE_MAX_HEIGHT = 384;
+
+/*
+ * Two attachments in one frame, shaped like the first. The split is only this renderer's state. With one
+ * attachment gone the other stands alone with the reason; with both gone the thumbnail says why.
+ */
+export function CompareRenderer({ node, children, context }: UiRendererProps<UiProps<'Compare'>>) {
+    const { t } = useTranslation('agent-chat');
+    const host = useChatHost();
+    const { before, after } = node.props;
+    const beforeLabel = node.props.beforeLabel || t('blocks.compare.before');
+    const afterLabel = node.props.afterLabel || t('blocks.compare.after');
+    const first = host.attachments.useUrl(context.scopeId, context.chatId, before);
+    const second = host.attachments.useUrl(context.scopeId, context.chatId, after);
+    const [split, setSplit] = useState(0.5);
+    const [aspect, setAspect] = useState(COMPARE_ASPECT);
+    const caption = uiNodeLabel(node);
+    // Each picture is named by its side and by what the whole comparison shows.
+    const describe = (side: string): string => (caption === '' ? side : `${side}: ${caption}`);
+    const loading = (source: typeof first) => source.url === null && source.failure === null;
+    const label = t('blocks.compare.label', { before: beforeLabel, after: afterLabel });
+    let body: ReactNode;
+    if (loading(first) || loading(second)) {
+        body = <ImageThumb source={{ url: null, failure: null }} alt={label} aspect={COMPARE_ASPECT} />;
+    } else if (first.url !== null && second.url !== null) {
+        body = (
+            // The frame keeps the picture's shape inside its tallest height: past it the width follows, so a portrait picture is not letterboxed.
+            <div
+                className="relative max-h-96 overflow-hidden rounded-lg border border-border bg-surface-sunken"
+                style={{ aspectRatio: aspect, width: `min(100%, ${COMPARE_MAX_HEIGHT * aspect}px)` }}
+            >
+                <Wipe
+                    value={split}
+                    onValueChange={setSplit}
+                    label={label}
+                    before={
+                        <img
+                            src={first.url}
+                            alt={describe(beforeLabel)}
+                            draggable={false}
+                            className="size-full object-contain select-none"
+                            onLoad={(event) => {
+                                const { naturalWidth, naturalHeight } = event.currentTarget;
+                                if (naturalWidth > 0 && naturalHeight > 0) {
+                                    setAspect(naturalWidth / naturalHeight);
+                                }
+                            }}
+                        />
+                    }
+                    after={<img src={second.url} alt={describe(afterLabel)} draggable={false} className="size-full object-contain select-none" />}
+                />
+                <CompareChip side="left" label={beforeLabel} />
+                <CompareChip side="right" label={afterLabel} />
+            </div>
+        );
+    } else if (first.url === null && second.url === null) {
+        body = <ImageThumb source={first} alt={label} aspect={COMPARE_ASPECT} />;
+    } else {
+        const shown = first.url !== null ? { source: first, name: describe(beforeLabel) } : { source: second, name: describe(afterLabel) };
+        body = (
+            <>
+                <ImageThumb source={shown.source} alt={shown.name} className="max-h-70 max-w-full object-contain" />
+                <span className="px-2 text-xs text-text-faint">{t('blocks.compare.missing')}</span>
+            </>
+        );
+    }
+    return (
+        <figure className="flex flex-col items-start gap-1.5 px-2">
+            {body}
+            {caption !== '' && <figcaption className="text-xs text-text-muted">{children}</figcaption>}
+        </figure>
+    );
+}
+
+/* A chip on the picture gets a ground of its own, since a pill's alpha ground would vanish over an image. */
+function CompareChip({ side, label }: { side: 'left' | 'right'; label: string }) {
+    return (
+        <span
+            className={clsx('pointer-events-none absolute top-2 z-20 max-w-2/5 truncate rounded-md bg-surface-raised', side === 'left' ? 'left-2' : 'right-2')}
+        >
+            <Pill shape="tag" size="sm" tone="muted">
+                {label}
+            </Pill>
+        </span>
+    );
+}
+
 export function SourcesRenderer({ node, children }: UiRendererProps<UiProps<'Sources'>>) {
     const { t } = useTranslation('agent-chat');
     const headingId = useId();

package/src/chat/ui/intelligent-ui/renderers/inputs.tsx

@@ -1,11 +1,13 @@
-import { createContext, useContext, type MouseEvent, type ReactNode } from 'react';
+import { createContext, useContext, useId, type MouseEvent, type ReactNode } from 'react';
 import clsx from 'clsx';
 import { useTranslation } from 'react-i18next';
-import type { UiBinding, UiProps, UiViewNode } from '@adecore/intelligent-ui';
-import { Button, Checkbox, Segmented, Slider, Switch, Tooltip } from '@adecore/ui';
-import { uiChildrenOf, uiNodeLabel, uiWithUnit } from '../node-text';
-import type { UiRenderContext, UiRendererProps } from '../render-context';
+import type { UiProps } from '@adecore/intelligent-ui';
+import { Button, Checkbox, Input, Segmented, Select, Slider, Switch, Tooltip } from '@adecore/ui';
+import { formatNumber } from '@adecore/ui/format';
+import { uiChildrenOf, uiNodeLabel, uiOwnLabel, uiWithUnit } from '../node-text';
+import type { UiRendererProps } from '../render-context';
 import { useTruncated } from '../use-truncated';
+import { bindingOf, PENDING } from './binding';
 
 type Scalar = UiProps<'Item'>['value'];
 
@@ -17,18 +19,6 @@ interface ChecklistState {
 
 const ChecklistContext = createContext<ChecklistState>({ values: [], enabled: false, toggle: () => undefined });
 
-/*
- * The binding of an input, or null for a read-only node. An input works once its own node closed and
- * only through its binding, so the value never leaves the block until a Choice carries it.
- */
-function bindingOf<Value>(node: UiViewNode<{ value: Value }>, context: UiRenderContext): UiBinding<Value> | null {
-    const binding = node.bindings.value as UiBinding<Value> | undefined;
-    return binding === undefined || !node.complete || context.answer !== null ? null : binding;
-}
-
-/* An input whose node has not closed yet stands at 60% and takes no pointer. */
-const PENDING = 'pointer-events-none opacity-60';
-
 /* The rows of a checklist as one named group. */
 function ChecklistGroup({ pending, children }: { pending: boolean; children: ReactNode }) {
     const { t } = useTranslation('agent-chat');
@@ -136,6 +126,78 @@ export function SegmentedRenderer({ node, context }: UiRendererProps<UiProps<'Se
     );
 }
 
+/* The longest a text field takes when its agent names none; the schema allows up to 1024. */
+const DEFAULT_MAX_LENGTH = 256;
+
+/* The count under a field appears once the field is this full, and never nags before. */
+const COUNT_FROM = 0.8;
+
+/*
+ * A line of text: the label above the field, which stops taking characters at its limit. Nothing here binds
+ * a key or submits on Enter, so the value reaches the agent only through a Choice.
+ */
+export function TextFieldRenderer({ node, children, context }: UiRendererProps<UiProps<'TextField'>>) {
+    const { t } = useTranslation('agent-chat');
+    const id = useId();
+    const binding = bindingOf(node, context);
+    const { maxLength = DEFAULT_MAX_LENGTH, placeholder } = node.props;
+    const value = binding?.value ?? node.props.value;
+    const countId = `${id}-count`;
+    const counting = value.length >= maxLength * COUNT_FROM;
+    return (
+        <div className={clsx('flex flex-col gap-1 px-2', !node.complete && PENDING)}>
+            <label htmlFor={id} className="text-sm text-text-muted">
+                {children}
+            </label>
+            <Input
+                id={id}
+                value={value}
+                size="sm"
+                maxLength={maxLength}
+                placeholder={placeholder}
+                disabled={binding === null}
+                aria-describedby={counting ? countId : undefined}
+                className="max-w-96"
+                onChange={(event) => binding?.onValueChange(event.target.value)}
+            />
+            {counting && (
+                <span id={countId} className="text-xs text-text-faint tabular-nums">
+                    {t('blocks.textField.count', { used: formatNumber(value.length), max: formatNumber(maxLength) })}
+                </span>
+            )}
+        </div>
+    );
+}
+
+/*
+ * Left aligned, never the full width. Like Segmented, each Option is an item by its place, since a value may be any scalar.
+ * The text beside its options is its label, drawn above it and read as its name.
+ */
+export function SelectRenderer({ node, context }: UiRendererProps<UiProps<'Select'>>) {
+    const { t } = useTranslation('agent-chat');
+    const binding = bindingOf(node, context);
+    const current = binding?.value ?? node.props.value;
+    const options = uiChildrenOf(node, 'Option').map((option, index) => ({ id: String(index), label: uiNodeLabel(option), value: option.props.value }));
+    const label = uiOwnLabel(node);
+    return (
+        <div className={clsx('flex flex-col items-start gap-1 px-2', !node.complete && PENDING)}>
+            {label !== '' && <span className="text-sm text-text-muted">{label}</span>}
+            <Select
+                value={options.find((option) => option.value === current)?.id ?? null}
+                items={options.map((option) => ({ value: option.id, label: option.label }))}
+                label={label === '' ? t('blocks.options') : label}
+                disabled={binding === null || options.length === 0}
+                onValueChange={(id) => {
+                    const option = options[Number(id)];
+                    if (option !== undefined) {
+                        binding?.onValueChange(option.value);
+                    }
+                }}
+            />
+        </div>
+    );
+}
+
 /* Runs its local action once its own node closed; like an input, it closes once the block is answered. A label cut to the button's one line reads whole in its tooltip. */
 export function ButtonRenderer({ node, children, context }: UiRendererProps<UiProps<'Button'>>) {
     const enabled = node.onAction !== undefined && node.complete && context.answer === null && node.props.disabled !== true;

package/src/chat/ui/intelligent-ui/renderers/map-slots.ts

@@ -0,0 +1,105 @@
+import { useEffect, useSyncExternalStore } from 'react';
+
+/*
+ * A map holds a WebGL context for as long as it is drawn, and a browser keeps only so many of them before
+ * it drops the oldest without a word. This is the page's budget of them for maps, kept under what the
+ * terminals of `@adecore/terminal` take from the same pool.
+ */
+export const MAX_LIVE_MAPS = 4;
+
+export type MapSlotState = 'idle' | 'granted' | 'queued';
+
+/*
+ * Who may draw a map right now. A map in view asks for a slot and gets one while there are fewer than
+ * `capacity` held; the others queue, in the order they asked, and are granted a slot as one is given back.
+ * A person can `take` one for a queued map: the longest-held map gives its slot up and queues first.
+ */
+export class MapSlots {
+    private readonly capacity: number;
+    private readonly held: string[] = [];
+    private readonly queue: string[] = [];
+    private readonly listeners = new Set<() => void>();
+
+    constructor(capacity: number) {
+        this.capacity = capacity;
+    }
+
+    request(id: string): void {
+        if (this.held.includes(id) || this.queue.includes(id)) {
+            return;
+        }
+        (this.held.length < this.capacity ? this.held : this.queue).push(id);
+        this.changed();
+    }
+
+    release(id: string): void {
+        const wasHeld = this.held.includes(id);
+        const wasQueued = this.queue.includes(id);
+        if (!wasHeld && !wasQueued) {
+            return;
+        }
+        this.held.splice(0, this.held.length, ...this.held.filter((entry) => entry !== id));
+        this.queue.splice(0, this.queue.length, ...this.queue.filter((entry) => entry !== id));
+        while (this.held.length < this.capacity && this.queue.length > 0) {
+            this.held.push(this.queue.shift()!);
+        }
+        this.changed();
+    }
+
+    take(id: string): void {
+        if (this.held.includes(id)) {
+            return;
+        }
+        const at = this.queue.indexOf(id);
+        if (at >= 0) {
+            this.queue.splice(at, 1);
+        }
+        if (this.held.length >= this.capacity) {
+            this.queue.unshift(this.held.shift()!);
+        }
+        this.held.push(id);
+        this.changed();
+    }
+
+    stateOf(id: string): MapSlotState {
+        return this.held.includes(id) ? 'granted' : this.queue.includes(id) ? 'queued' : 'idle';
+    }
+
+    subscribe = (listener: () => void): (() => void) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+
+    private changed(): void {
+        for (const listener of [...this.listeners]) {
+            listener();
+        }
+    }
+}
+
+let page: MapSlots | null = null;
+
+/* The one budget of the page, made on first use. */
+export function pageMapSlots(): MapSlots {
+    page ??= new MapSlots(MAX_LIVE_MAPS);
+    return page;
+}
+
+/* A map's place in the budget while it `wanted`, which is while it is in view; gone from it otherwise and on unmount. */
+export function useMapSlot(id: string, wanted: boolean, slots: MapSlots = pageMapSlots()): { state: MapSlotState; take(): void } {
+    const state = useSyncExternalStore(
+        slots.subscribe,
+        () => slots.stateOf(id),
+        () => 'idle' as const
+    );
+    useEffect(() => {
+        if (!wanted) {
+            return;
+        }
+        slots.request(id);
+        return () => slots.release(id);
+    }, [slots, id, wanted]);
+    return { state, take: () => slots.take(id) };
+}

package/src/chat/ui/intelligent-ui/renderers/map-style.ts

@@ -0,0 +1,96 @@
+import type { LngLatBoundsLike, MapOptions } from 'maplibre-gl';
+import { BASE_LAND_JSON } from './base-land';
+
+// The package does not export its style type, only the options that take one.
+export type MapStyle = Exclude<MapOptions['style'], string | undefined>;
+
+type Expression = unknown[];
+
+/* The two grounds of the built-in map, as the page paints them. */
+export interface MapColors {
+    land: string;
+    water: string;
+}
+
+export interface MapPoint {
+    id: string;
+    lat: number;
+    lon: number;
+}
+
+/* How far a map zooms to fit its points: street level with tiles, and only a country or two on the outline, which has nothing finer. */
+export const MAP_MAX_ZOOM = { tiles: 16, outline: 6 } as const;
+
+/* The map a page draws without tiles: land over water, from the outline of the world that ships with the package. */
+export function baseMapStyle({ land, water }: MapColors): MapStyle {
+    return {
+        version: 8,
+        sources: { land: { type: 'geojson', data: JSON.parse(BASE_LAND_JSON) } },
+        layers: [
+            { id: 'water', type: 'background', paint: { 'background-color': water } },
+            { id: 'land', type: 'fill', source: 'land', paint: { 'fill-color': land } }
+        ]
+    };
+}
+
+const TOKEN = /\{([^{}]+)\}/g;
+
+/* A `{name}` text field as the expression it stands for, since a field combined with another expression is no longer read for tokens. */
+function tokenExpression(text: string): Expression | string {
+    const parts: (Expression | string)[] = [];
+    let at = 0;
+    for (const match of text.matchAll(TOKEN)) {
+        if (match.index > at) {
+            parts.push(text.slice(at, match.index));
+        }
+        parts.push(['to-string', ['coalesce', ['get', match[1]], '']]);
+        at = match.index + match[0].length;
+    }
+    if (parts.length === 0) {
+        return text;
+    }
+    if (at < text.length) {
+        parts.push(text.slice(at));
+    }
+    return parts.length === 1 && typeof parts[0] !== 'string' ? parts[0] : ['concat', ...parts];
+}
+
+/*
+ * A label that prefers the property `field` of a feature and falls back to what the style wrote. A text
+ * field that is neither a string nor an expression (a legacy zoom function) is left as it is.
+ */
+export function localizedTextField(original: unknown, field: string): unknown {
+    const fallback = typeof original === 'string' ? tokenExpression(original) : original;
+    if (typeof fallback !== 'string' && !Array.isArray(fallback)) {
+        return original;
+    }
+    return ['coalesce', ['get', field], fallback];
+}
+
+/*
+ * The bounds that hold every point, or null for none. Longitudes go round the globe, so the bounds leave out
+ * the widest gap between two neighbors: points on both sides of the date line span a few degrees, not 360.
+ * The east edge may then pass 180, which the map takes.
+ */
+export function boundsOf(points: readonly MapPoint[]): LngLatBoundsLike | null {
+    if (points.length === 0) {
+        return null;
+    }
+    const lons = points.map((point) => point.lon).sort((a, b) => a - b);
+    let widest = lons[0]! + 360 - lons[lons.length - 1]!;
+    let west = lons[0]!;
+    let east = lons[lons.length - 1]!;
+    for (let i = 1; i < lons.length; i++) {
+        const gap = lons[i]! - lons[i - 1]!;
+        if (gap > widest) {
+            widest = gap;
+            west = lons[i]!;
+            east = lons[i - 1]! + 360;
+        }
+    }
+    const lats = points.map((point) => point.lat);
+    return [
+        [west, Math.min(...lats)],
+        [east, Math.max(...lats)]
+    ];
+}