@adecore/agents-react 0.20.0 → 0.21.0

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

@@ -0,0 +1,84 @@
+import { createContext, useContext, useId } from 'react';
+import clsx from 'clsx';
+import { ChevronRight } from 'lucide-react';
+import type { UiProps } from '@adecore/intelligent-ui';
+import { Icon, Tabs } from '@adecore/ui';
+import { useBlockLocal } from '../block-local';
+import { uiChildrenOf } from '../node-text';
+import type { UiRendererProps } from '../render-context';
+
+interface SectionsFold {
+    /* Whether the person opened or closed a section of this set, after which nothing opens by itself. */
+    touched: boolean;
+    touch(): void;
+}
+
+const SectionsContext = createContext<SectionsFold>({ touched: false, touch: () => undefined });
+
+/* A tab that arrives while the block streams is not picked: the one that was open stays open. */
+export function TabsRenderer({ node, children, context }: UiRendererProps<UiProps<'Tabs'>>) {
+    const tabs = uiChildrenOf(node, 'Tab');
+    const [picked, setPicked] = useBlockLocal<string | null>(context, node.id, () => null);
+    const value = picked !== null && tabs.some((tab) => tab.id === picked) ? picked : (tabs[0]?.id ?? null);
+    return (
+        <Tabs.Root value={value} onValueChange={(next) => setPicked(String(next))} className="flex flex-col gap-3">
+            <Tabs.List className="px-2">
+                {tabs.map((tab) => (
+                    <Tabs.Tab key={tab.id} value={tab.id} data-ui-reveal={tab.id}>
+                        {tab.props.title}
+                    </Tabs.Tab>
+                ))}
+            </Tabs.List>
+            {children}
+        </Tabs.Root>
+    );
+}
+
+export function TabRenderer({ node, children }: UiRendererProps<UiProps<'Tab'>>) {
+    return (
+        <Tabs.Panel value={node.id} className="chat-ui-nodes flex flex-col gap-3">
+            {children}
+        </Tabs.Panel>
+    );
+}
+
+export function SectionsRenderer({ node, children, context }: UiRendererProps<UiProps<'Sections'>>) {
+    const [touched, setTouched] = useBlockLocal(context, node.id, () => false);
+    return (
+        <SectionsContext value={{ touched, touch: () => setTouched(true) }}>
+            <div className="chat-ui-nodes flex flex-col divide-y divide-border-soft">{children}</div>
+        </SectionsContext>
+    );
+}
+
+/* Arrives open until the person folds a section of the set themselves; the content starts under the title. */
+export function SectionRenderer({ node, children, context }: UiRendererProps<UiProps<'Section'>>) {
+    const fold = useContext(SectionsContext);
+    const [open, setOpen] = useBlockLocal(context, node.id, () => !fold.touched);
+    const contentId = useId();
+    return (
+        <section>
+            <button
+                type="button"
+                data-ui-reveal={node.id}
+                aria-expanded={open}
+                aria-controls={contentId}
+                className="flex h-8 w-full items-center gap-2 rounded-md px-2 text-left text-sm font-medium text-text hover:bg-surface-hover"
+                onClick={() => {
+                    fold.touch();
+                    setOpen(!open);
+                }}
+            >
+                <Icon
+                    icon={ChevronRight}
+                    size={14}
+                    className={clsx('shrink-0 text-text-faint transition-transform duration-150 motion-reduce:transition-none', open && 'rotate-90')}
+                />
+                <span className="min-w-0 truncate">{node.props.title}</span>
+            </button>
+            <div id={contentId} hidden={!open} className="chat-ui-nodes flex flex-col gap-3 pt-1 pr-2 pb-2 pl-7.5">
+                {children}
+            </div>
+        </section>
+    );
+}

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

@@ -0,0 +1,124 @@
+import { useContext } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { Circle, CircleCheck, CircleDot, CircleMinus, CircleX, type LucideIcon } from 'lucide-react';
+import type { UiProps } from '@adecore/intelligent-ui';
+import { Icon, Meter, Pill, Spinner } from '@adecore/ui';
+import { formatNumber, formatPercent } from '@adecore/ui/format';
+import { UiHeadContext, type UiRenderContext, type UiRendererProps } from '../render-context';
+import { uiNodeLabel } from '../node-text';
+import { UI_TONE_ICONS, UI_TONE_PILL, UI_TONE_SURFACE, UI_TONE_TEXT } from '../tones';
+
+type StepState = UiProps<'Step'>['state'];
+
+const STEP_ICONS: Readonly<Record<Exclude<StepState, 'running'>, LucideIcon>> = {
+    done: CircleCheck,
+    pending: Circle,
+    failed: CircleX,
+    skipped: CircleMinus
+};
+
+const STEP_TONES: Readonly<Record<StepState, string>> = {
+    done: 'text-status-idle',
+    running: 'text-accent',
+    pending: 'text-text-faint',
+    failed: 'text-status-error',
+    skipped: 'text-text-faint'
+};
+
+/* Whether the block still changes: while it streams, or while it reads live data. Only then does anything spin. */
+function isLive(context: UiRenderContext): boolean {
+    return context.phase === 'streaming' || (context.live !== undefined && context.live !== null && context.live.state !== 'refused');
+}
+
+/* The head of the block when it is the first node, a subheading without an icon further down. */
+export function SummaryRenderer({ node, children }: UiRendererProps<UiProps<'Summary'>>) {
+    const headId = useContext(UiHeadContext);
+    const head = headId === undefined || headId === node.id;
+    const { tone, badge } = node.props;
+    return (
+        <div className="flex items-start gap-2 px-2">
+            {head && tone !== undefined && <Icon icon={UI_TONE_ICONS[tone]} size={16} className={clsx('mt-0.75 shrink-0', UI_TONE_TEXT[tone])} />}
+            <div className="min-w-0 grow text-sm font-semibold text-balance text-text">{children}</div>
+            {badge !== undefined && badge !== '' && (
+                <Pill shape="tag" tone={tone === undefined ? 'muted' : UI_TONE_PILL[tone]} className="shrink-0">
+                    {badge}
+                </Pill>
+            )}
+        </div>
+    );
+}
+
+export function CalloutRenderer({ node, children }: UiRendererProps<UiProps<'Callout'>>) {
+    const { tone, title } = node.props;
+    return (
+        <div className={clsx('flex gap-2 rounded-md p-2 text-sm', UI_TONE_SURFACE[tone])}>
+            <Icon icon={UI_TONE_ICONS[tone]} size={16} className={clsx('mt-0.75 shrink-0', UI_TONE_TEXT[tone])} />
+            <div className="min-w-0 grow">
+                {title !== undefined && title !== '' && <div className="font-medium text-text">{title}</div>}
+                <div className="text-text-muted">{children}</div>
+            </div>
+        </div>
+    );
+}
+
+export function TagRenderer({ node, children }: UiRendererProps<UiProps<'Tag'>>) {
+    const { tone } = node.props;
+    return (
+        <Pill shape="tag" size="sm" tone={tone === undefined ? 'muted' : UI_TONE_PILL[tone]}>
+            {children}
+        </Pill>
+    );
+}
+
+/* Without a value the progress is indeterminate; without a max the value is a percentage. */
+export function ProgressRenderer({ node, children, context }: UiRendererProps<UiProps<'Progress'>>) {
+    const { t } = useTranslation('agent-chat');
+    const { value, max } = node.props;
+    const limit = max ?? 100;
+    const reading =
+        value === undefined ? null : limit === 100 ? formatPercent(value) : t('blocks.progress.of', { value: formatNumber(value), max: formatNumber(limit) });
+    const label = uiNodeLabel(node);
+    return (
+        <div className="flex flex-col gap-1 px-2">
+            <div className="flex items-baseline justify-between gap-3 text-xs">
+                <span className="min-w-0 text-text">{children}</span>
+                {reading !== null ? (
+                    <span className="shrink-0 text-text-muted tabular-nums">{reading}</span>
+                ) : (
+                    isLive(context) && <Spinner size={12} className="shrink-0 self-center text-text-faint" />
+                )}
+            </div>
+            <Meter value={value ?? null} max={limit} label={label === '' ? t('blocks.progress.label') : label} valueText={reading ?? undefined} />
+        </div>
+    );
+}
+
+export function StepsRenderer({ children }: UiRendererProps<UiProps<'Steps'>>) {
+    return <ol className="chat-ui-nodes flex flex-col px-2">{children}</ol>;
+}
+
+/* A running step spins only while the block is live; in a quiet block it is a still dot. */
+export function StepRenderer({ node, children, context }: UiRendererProps<UiProps<'Step'>>) {
+    const { t } = useTranslation('agent-chat');
+    const { state, detail } = node.props;
+    const quiet = state === 'pending' || state === 'skipped';
+    return (
+        <li className="flex min-h-7 items-center gap-2 text-sm">
+            <span className={clsx('grid size-4 shrink-0 place-items-center', STEP_TONES[state])}>
+                {state === 'running' ? (
+                    isLive(context) ? (
+                        <Spinner size={14} />
+                    ) : (
+                        <Icon icon={CircleDot} size={14} />
+                    )
+                ) : (
+                    <Icon icon={STEP_ICONS[state]} size={14} />
+                )}
+            </span>
+            <span className="sr-only">{t(`blocks.step.${state}`)}</span>
+            <span className={clsx('min-w-0 grow', quiet ? 'text-text-faint' : 'text-text')}>{children}</span>
+            {detail !== undefined && detail !== '' && <span className="shrink-0 text-xs text-text-faint tabular-nums">{detail}</span>}
+        </li>
+    );
+}

package/src/chat/ui/intelligent-ui/reply-parts.ts

@@ -0,0 +1,22 @@
+import type { UiBlock } from '@adecore/intelligent-ui';
+
+export type UiReplyPart = { kind: 'text'; text: string } | { kind: 'ui'; block: UiBlock };
+
+export function uiReplyParts(text: string, blocks: readonly UiBlock[], streaming = false): UiReplyPart[] {
+    const parts: UiReplyPart[] = [];
+    let position = 0;
+    for (const block of [...blocks].sort((left, right) => left.start - right.start)) {
+        if (!Number.isInteger(block.start) || !Number.isInteger(block.end) || block.start < position || block.end < block.start || block.end > text.length) {
+            continue;
+        }
+        if (block.start > position) {
+            parts.push({ kind: 'text', text: text.slice(position, block.start) });
+        }
+        parts.push({ kind: 'ui', block });
+        position = streaming && !block.complete ? text.length : block.end;
+    }
+    if (position < text.length) {
+        parts.push({ kind: 'text', text: text.slice(position) });
+    }
+    return parts;
+}

package/src/chat/ui/intelligent-ui/table-data.ts

@@ -0,0 +1,104 @@
+import type { UiProps, UiViewNode } from '@adecore/intelligent-ui';
+import { uiChildrenOf } from './node-text';
+
+export type UiColumnKind = NonNullable<UiProps<'Column'>['as']>;
+
+export interface UiTableColumn {
+    key: string;
+    title: string;
+    unit?: string;
+    as: UiColumnKind;
+}
+
+/* What one cell shows, decided before drawing so a value of the wrong kind never reaches a formatter. */
+export type UiTableCell =
+    | { kind: 'empty' }
+    | { kind: 'text'; text: string }
+    | { kind: 'number'; as: 'number' | 'bytes' | 'duration'; value: number }
+    | { kind: 'date'; at: number }
+    | { kind: 'file'; path: string }
+    | { kind: 'tag'; text: string };
+
+/* Rows shown before a person asks for all of them. */
+export const UI_TABLE_ROWS = 50;
+/* Columns a table without Column children takes from its rows. */
+const DERIVED_COLUMNS = 8;
+const NUMERIC_KINDS: ReadonlySet<UiColumnKind> = new Set(['number', 'bytes', 'duration']);
+
+export function isNumericColumn(column: UiTableColumn): boolean {
+    return NUMERIC_KINDS.has(column.as);
+}
+
+/*
+ * The columns a table can draw: its Column children whose key some row has, each key once. A table
+ * without columns takes the keys of its rows, as numbers when every value there is one. Empty when
+ * nothing is usable, which draws the fallback.
+ */
+export function uiTableColumns(node: UiViewNode<UiProps<'Table'>>): UiTableColumn[] {
+    const rows = node.props.rows;
+    const present = (key: string): boolean => rows.some((row) => Object.hasOwn(row, key));
+    const declared = uiChildrenOf(node, 'Column');
+    if (declared.length > 0) {
+        const seen = new Set<string>();
+        return declared.flatMap(({ props }) => {
+            if (seen.has(props.key) || (rows.length > 0 && !present(props.key))) {
+                return [];
+            }
+            seen.add(props.key);
+            return [{ key: props.key, title: props.title ?? props.key, unit: props.unit, as: props.as ?? 'text' }];
+        });
+    }
+    const keys: string[] = [];
+    for (const row of rows) {
+        for (const key of Object.keys(row)) {
+            if (!keys.includes(key) && keys.length < DERIVED_COLUMNS) {
+                keys.push(key);
+            }
+        }
+    }
+    return keys.map((key) => {
+        const values = rows.map((row) => row[key]).filter((value) => value !== undefined && value !== null);
+        const numeric = values.length > 0 && values.every((value) => typeof value === 'number' && Number.isFinite(value));
+        return { key, title: key, as: numeric ? 'number' : 'text' };
+    });
+}
+
+function textOf(value: unknown): string {
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+
+function numberOf(value: unknown): number | null {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+
+/* A duration is in milliseconds and a date is milliseconds since the epoch or an ISO string; anything else reads as text. */
+export function uiTableCell(value: unknown, column: UiTableColumn): UiTableCell {
+    if (value === undefined || value === null || value === '') {
+        return { kind: 'empty' };
+    }
+    switch (column.as) {
+        case 'number':
+        case 'bytes':
+        case 'duration': {
+            const number = numberOf(value);
+            return number === null ? { kind: 'text', text: textOf(value) } : { kind: 'number', as: column.as, value: number };
+        }
+        case 'date': {
+            const at = typeof value === 'number' ? value : typeof value === 'string' ? Date.parse(value) : Number.NaN;
+            return Number.isFinite(at) ? { kind: 'date', at } : { kind: 'text', text: textOf(value) };
+        }
+        case 'file':
+            return typeof value === 'string' ? { kind: 'file', path: value } : { kind: 'text', text: textOf(value) };
+        case 'tag':
+            return { kind: 'tag', text: textOf(value) };
+        case 'text':
+            return { kind: 'text', text: textOf(value) };
+    }
+}

package/src/chat/ui/intelligent-ui/tones.ts

@@ -0,0 +1,37 @@
+import { CircleCheck, Info, MessageCircle, OctagonAlert, TriangleAlert, type LucideIcon } from 'lucide-react';
+import type { UiTone } from '@adecore/intelligent-ui';
+import type { PillProps } from '@adecore/ui';
+
+/* Every tone has an icon of its own, so color is never the only thing that tells two apart. */
+export const UI_TONE_ICONS: Readonly<Record<UiTone, LucideIcon>> = {
+    neutral: MessageCircle,
+    info: Info,
+    success: CircleCheck,
+    warning: TriangleAlert,
+    danger: OctagonAlert
+};
+
+export const UI_TONE_TEXT: Readonly<Record<UiTone, string>> = {
+    neutral: 'text-text-muted',
+    info: 'text-status-running',
+    success: 'text-positive',
+    warning: 'text-status-needs-you',
+    danger: 'text-status-error'
+};
+
+/* The tone mixed over the ground, for a surface such as a callout. */
+export const UI_TONE_SURFACE: Readonly<Record<UiTone, string>> = {
+    neutral: 'bg-text/7',
+    info: 'bg-status-running/10',
+    success: 'bg-positive/10',
+    warning: 'bg-status-needs-you/12',
+    danger: 'bg-status-error/10'
+};
+
+export const UI_TONE_PILL: Readonly<Record<UiTone, NonNullable<PillProps['tone']>>> = {
+    neutral: 'muted',
+    info: 'accent',
+    success: 'idle',
+    warning: 'needsYou',
+    danger: 'error'
+};

package/src/chat/ui/intelligent-ui/use-later.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+
+/* True once `on` has held for `ms`, for a spinner that only shows when waiting takes long. */
+export function useLater(on: boolean, ms: number): boolean {
+    const [late, setLate] = useState(false);
+    useEffect(() => {
+        if (!on) {
+            return;
+        }
+        const timer = setTimeout(() => setLate(true), ms);
+        return () => {
+            clearTimeout(timer);
+            setLate(false);
+        };
+    }, [on, ms]);
+    return on && late;
+}

package/src/chat/ui/intelligent-ui/use-ui-links.ts

@@ -0,0 +1,123 @@
+import { useEffect, useState } from 'react';
+import type { ChatUiLinkReading, ChatUiQueryState } from '@adecore/agent-contracts';
+import { uiLinkTargets, type UiLinkTarget } from '@adecore/intelligent-ui/links';
+import { uiInputValues, type UiBlock, UiState } from '@adecore/intelligent-ui';
+import { chatHost } from '../../../host';
+import type { UiRenderContext } from './render-context';
+
+interface LinkState {
+    target: string;
+    reading: ChatUiLinkReading;
+}
+
+export function useUiLinks(
+    block: UiBlock,
+    state: UiState,
+    context: UiRenderContext,
+    reads: Readonly<Record<string, string>>,
+    frozen?: ChatUiQueryState['blocks'][string]
+) {
+    const [checked, setChecked] = useState<Record<string, LinkState>>({});
+    const host = chatHost().intelligentUi;
+    const values = uiInputValues(block, state);
+    const scope = state.scope();
+    const queryValues = Object.fromEntries(
+        Object.keys(block.queries)
+            .filter((name) => Object.hasOwn(scope, name))
+            .map((name) => [name, scope[name]])
+    );
+    let targets: Record<string, UiLinkTarget> = {};
+    try {
+        if (block.complete) {
+            targets = uiLinkTargets(block, values, queryValues);
+        }
+    } catch {}
+    const signature = JSON.stringify(targets);
+    const input = JSON.stringify(values);
+    const tickets = JSON.stringify(reads);
+    const link = host?.link;
+    useEffect(() => {
+        if (!link || !block.revision || context.phase !== 'final') {
+            return;
+        }
+        let stopped = false;
+        const validate = async () => {
+            for (const [nodeId, target] of Object.entries(JSON.parse(signature) as Record<string, UiLinkTarget>).slice(0, 64)) {
+                try {
+                    const reading = await link(context.scopeId, {
+                        chatId: context.chatId,
+                        itemId: context.itemId,
+                        blockId: block.id,
+                        revision: block.revision!,
+                        nodeId,
+                        values: JSON.parse(input),
+                        reads: JSON.parse(tickets)
+                    });
+                    if (stopped) {
+                        return;
+                    }
+                    setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading } }));
+                } catch {
+                    if (stopped) {
+                        return;
+                    }
+                    setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading: { state: 'plain' } } }));
+                }
+            }
+        };
+        void validate();
+        return () => {
+            stopped = true;
+        };
+    }, [block.id, block.revision, context.scopeId, context.chatId, context.itemId, context.phase, signature, input, tickets, link]);
+    const idOf = (target: UiLinkTarget) => Object.entries(targets).find(([, entry]) => JSON.stringify(entry) === JSON.stringify(target))?.[0];
+    const resolution = (target: UiLinkTarget): ChatUiLinkReading => {
+        const id = idOf(target);
+        if (id === undefined) {
+            return { state: 'plain' };
+        }
+        if (checked[id]?.target === JSON.stringify(target)) {
+            return checked[id].reading;
+        }
+        if (input === JSON.stringify(uiInputValues(block, new UiState(block))) && frozen && frozen.revision === block.revision) {
+            const firstQueries = Object.fromEntries(
+                Object.entries(frozen.readings)
+                    .filter(([, reading]) => reading.state === 'fresh')
+                    .map(([name, reading]) => [name, reading.value])
+            );
+            if (JSON.stringify(queryValues) === JSON.stringify(firstQueries)) {
+                return frozen.links?.[id] ?? { state: 'plain' };
+            }
+        }
+        return { state: 'plain' };
+    };
+    const open = (target: UiLinkTarget) => {
+        const nodeId = idOf(target);
+        if (!nodeId || !link || !block.revision) {
+            return;
+        }
+        void link(context.scopeId, {
+            chatId: context.chatId,
+            itemId: context.itemId,
+            blockId: block.id,
+            revision: block.revision,
+            nodeId,
+            values,
+            reads: { ...reads }
+        })
+            .then((reading) => {
+                setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading } }));
+                if (reading.state === 'chip' && reading.target) {
+                    host?.openLink?.(context.scopeId, reading);
+                }
+            })
+            .catch(() => {
+                setChecked((previous) => ({ ...previous, [nodeId]: { target: JSON.stringify(target), reading: { state: 'plain' } } }));
+            });
+    };
+    return {
+        link: link ? resolution : context.link,
+        openLink: link && host?.openLink ? open : context.openLink,
+        openUrl: host?.openUrl ? (url: string) => host.openUrl!(context.scopeId, url) : context.openUrl
+    };
+}