@adecore/agents-react 0.20.1 → 0.21.0

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

@@ -0,0 +1,52 @@
+import type { UiRenderers } from './render-context';
+import { ChartRenderer } from './renderers/chart';
+import { ChoiceRenderer, ChoicesRenderer } from './renderers/choices';
+import { CodeBlockRenderer, ImageRenderer, SourceRenderer, SourcesRenderer } from './renderers/content';
+import { EntityListRenderer, EntryRenderer, StatRenderer, StatsRenderer, TableRenderer } from './renderers/data';
+import { ChecklistRenderer, ItemRenderer, SegmentedRenderer, SliderRenderer, SwitchRenderer } from './renderers/inputs';
+import { CommitRenderer, DiffRenderer, FileRenderer, NodeRenderer } from './renderers/links';
+import { SectionRenderer, SectionsRenderer, TabRenderer, TabsRenderer } from './renderers/structure';
+import { CalloutRenderer, ProgressRenderer, StepRenderer, StepsRenderer, SummaryRenderer, TagRenderer } from './renderers/text';
+
+/*
+ * A renderer for every component of the catalog; a name missing here fails the typecheck. Null draws
+ * nothing for the node itself: the runtime resolves Show and Each before rendering, and Column and
+ * Option are metadata their parent reads from its node (a table its columns, Segmented its segments).
+ */
+export const UI_RENDERERS: UiRenderers = {
+    Summary: SummaryRenderer,
+    Callout: CalloutRenderer,
+    Tag: TagRenderer,
+    Progress: ProgressRenderer,
+    Steps: StepsRenderer,
+    Step: StepRenderer,
+    Stats: StatsRenderer,
+    Stat: StatRenderer,
+    EntityList: EntityListRenderer,
+    Entry: EntryRenderer,
+    Table: TableRenderer,
+    Column: null,
+    Chart: ChartRenderer,
+    Tabs: TabsRenderer,
+    Tab: TabRenderer,
+    Sections: SectionsRenderer,
+    Section: SectionRenderer,
+    CodeBlock: CodeBlockRenderer,
+    Image: ImageRenderer,
+    Sources: SourcesRenderer,
+    Source: SourceRenderer,
+    File: FileRenderer,
+    Diff: DiffRenderer,
+    Commit: CommitRenderer,
+    Node: NodeRenderer,
+    Checklist: ChecklistRenderer,
+    Item: ItemRenderer,
+    Switch: SwitchRenderer,
+    Slider: SliderRenderer,
+    Segmented: SegmentedRenderer,
+    Option: null,
+    Show: null,
+    Each: null,
+    Choices: ChoicesRenderer,
+    Choice: ChoiceRenderer
+};

package/src/chat/ui/intelligent-ui/render-context.ts

@@ -0,0 +1,78 @@
+import { createContext, type ReactNode } from 'react';
+import type { UiComponentName, UiProps, UiViewNode } from '@adecore/intelligent-ui';
+
+export type { UiLinkTarget } from '@adecore/intelligent-ui/links';
+import type { UiLinkTarget } from '@adecore/intelligent-ui/links';
+
+/* How the host lets a link be drawn: a chip it can open, or plain text it cannot. */
+export interface UiLink {
+    state: 'chip' | 'plain';
+    /* What the host calls the target, such as the title of a node or the subject of a commit. */
+    label?: string;
+    /* Why a plain link is not a chip, in its tooltip. */
+    reason?: string;
+}
+
+/* The Choice that answered a block. `sending` already reads as sent, so a second click does nothing. */
+export interface UiAnswer {
+    choiceId: string;
+    state: 'sending' | 'sent' | 'queued';
+}
+
+/* What the footer of a block that reads live data says about its last reading. */
+export interface UiLiveStatus {
+    state: 'fresh' | 'reading' | 'failed' | 'refused';
+    /* What the block reads, by the names a person knows them by. */
+    sources: readonly string[];
+    /* The last reading that succeeded, in milliseconds since the epoch; null when nothing was read yet. */
+    readAt: number | null;
+    /* The source that failed or was refused. */
+    source?: string;
+    /* Why a reading failed, in its tooltip. */
+    reason?: string;
+}
+
+/* Live history is separate from the comparison the agent supplies in Stat.previous. */
+export interface UiLiveValue {
+    previous?: unknown;
+    changed: boolean;
+    stale: boolean;
+}
+
+/*
+ * What every renderer of a block knows besides its node. The callbacks are the host's: left out, a link
+ * stays plain text, a source cannot be opened and a choice stays closed.
+ */
+export interface UiRenderContext {
+    scopeId: string;
+    chatId: string;
+    itemId: string;
+    blockId: string;
+    phase: 'streaming' | 'final';
+    answer: UiAnswer | null;
+    /* The Choice whose last send failed, which opened the block again. */
+    failedChoiceId?: string | null;
+    live?: UiLiveStatus | null;
+    link?(target: UiLinkTarget): UiLink;
+    openLink?(target: UiLinkTarget): void;
+    openUrl?(url: string): void;
+    onChoose?(nodeId: string): void;
+    /* Table cells use the evaluated rows index and column key. */
+    liveValue?(nodeId: string, prop: string, path?: readonly [row: number, key: string]): UiLiveValue | undefined;
+}
+
+export interface UiRendererProps<Props> {
+    /* Valid and evaluated; its children are there as metadata, such as the columns of a table. */
+    node: UiViewNode<Props>;
+    /* The rendered children, in order, each inside its own error boundary. */
+    children: ReactNode;
+    context: UiRenderContext;
+}
+
+export type UiRenderer<Props> = (props: UiRendererProps<Props>) => ReactNode;
+
+/* A renderer for every name in the catalog, or null where the runtime draws the node some other way. */
+export type UiRenderers = { readonly [Name in UiComponentName]: UiRenderer<UiProps<Name>> | null };
+
+/* The id of the Summary that heads the block. Undefined outside a frame, where every Summary heads. */
+export const UiHeadContext = createContext<string | null | undefined>(undefined);

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

@@ -0,0 +1,321 @@
+import { useMemo, useState } from 'react';
+import type { TFunction } from 'i18next';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import type { UiProps } from '@adecore/intelligent-ui';
+import { SegmentBar, useMeasuredWidth } from '@adecore/ui';
+import { formatRounded } from '@adecore/ui/format';
+import { niceCeiling, UI_CHART_ROWS, uiChartData, type UiChartData } from '../chart-data';
+import type { UiRendererProps } from '../render-context';
+import { UiFallbackPart } from '../UiFallbackPart';
+
+type ChartKind = UiProps<'Chart'>['kind'];
+
+const HEIGHT = 160;
+const HBAR_ROW = 24;
+const STACKED_ROW = 28;
+const AXIS_WIDTH = 44;
+const PLOT_TOP = 8;
+const LABEL_ROOM = 20;
+/* The narrowest band a category label is written under; narrower bands skip labels. */
+const LABEL_BAND = 56;
+/* Points get a dot up to this many categories; more would crowd the line. */
+const DOTS_UP_TO = 30;
+const GROW = 'transition-[scale,opacity] duration-400 ease-out motion-reduce:transition-none';
+
+function seriesColor(index: number): string {
+    return `var(--chart-${index + 1})`;
+}
+
+function valueText(value: number | null, unit: string | undefined): string {
+    if (value === null) {
+        return '';
+    }
+    const text = formatRounded(value, 2);
+    return unit === undefined || unit === '' ? text : unit === '%' ? `${text}%` : `${text} ${unit}`;
+}
+
+/* The height a chart will take, which its place holds while the node streams. */
+function chartHeight(kind: ChartKind, rows: number): number {
+    const count = Math.max(1, Math.min(rows, UI_CHART_ROWS));
+    return kind === 'hbar' ? count * HBAR_ROW : kind === 'stacked' ? count * STACKED_ROW : HEIGHT;
+}
+
+/* One sentence with the main point, which a screen reader hears in place of the drawing. */
+function chartSummary(chart: UiChartData, unit: string | undefined, t: TFunction<'agent-chat'>): string {
+    let top: { label: string; series: string; value: number } | null = null;
+    for (const series of chart.series) {
+        for (let i = 0; i < series.values.length; i++) {
+            const value = series.values[i];
+            if (value !== null && value !== undefined && (top === null || value > top.value)) {
+                top = { label: chart.labels[i] ?? '', series: series.key, value };
+            }
+        }
+    }
+    if (top === null) {
+        return t('blocks.chart.values');
+    }
+    return chart.series.length > 1
+        ? t('blocks.chart.summarySeries', { count: chart.labels.length, series: top.series, label: top.label, value: valueText(top.value, unit) })
+        : t('blocks.chart.summary', { count: chart.labels.length, label: top.label, value: valueText(top.value, unit) });
+}
+
+function Legend({ chart }: { chart: UiChartData }) {
+    return (
+        <div aria-hidden className="flex flex-wrap gap-x-3 gap-y-1 text-xs text-text-muted">
+            {chart.series.map((series, index) => (
+                <span key={series.key} className="flex items-center gap-1.5">
+                    <span className="size-2 rounded-sm" style={{ backgroundColor: seriesColor(index) }} />
+                    {series.key}
+                </span>
+            ))}
+        </div>
+    );
+}
+
+/* The numbers behind the drawing, for a screen reader. */
+function ValuesTable({ chart, unit }: { chart: UiChartData; unit: string | undefined }) {
+    const { t } = useTranslation('agent-chat');
+    return (
+        <table className="sr-only">
+            <caption>{t('blocks.chart.values')}</caption>
+            <thead>
+                <tr>
+                    <td />
+                    {chart.series.map((series) => (
+                        <th key={series.key} scope="col">
+                            {series.key}
+                        </th>
+                    ))}
+                </tr>
+            </thead>
+            <tbody>
+                {chart.labels.map((label, index) => (
+                    <tr key={index}>
+                        <th scope="row">{label}</th>
+                        {chart.series.map((series) => (
+                            <td key={series.key}>{valueText(series.values[index] ?? null, unit)}</td>
+                        ))}
+                    </tr>
+                ))}
+            </tbody>
+        </table>
+    );
+}
+
+/* The values of one category beside the pointer. */
+function Readout({ chart, index, left, unit }: { chart: UiChartData; index: number; left: number; unit: string | undefined }) {
+    return (
+        <div
+            aria-hidden
+            className="pointer-events-none absolute top-0 z-1 flex -translate-x-1/2 flex-col gap-0.5 rounded-md bg-surface-raised px-2 py-1 text-xs whitespace-nowrap shadow-raised"
+            style={{ left }}
+        >
+            <span className="font-medium text-text">{chart.labels[index]}</span>
+            {chart.series.map((series, at) => (
+                <span key={series.key} className="flex items-center gap-1.5 text-text-muted tabular-nums">
+                    <span className="size-2 rounded-sm" style={{ backgroundColor: seriesColor(at) }} />
+                    {chart.series.length > 1 && <span>{series.key}</span>}
+                    <span className="text-text">{valueText(series.values[index] ?? null, unit)}</span>
+                </span>
+            ))}
+        </div>
+    );
+}
+
+/* Bars and lines over a value axis, in SVG at the measured width. */
+function VerticalChart({ chart, kind, unit, width }: { chart: UiChartData; kind: 'bar' | 'line'; unit: string | undefined; width: number }) {
+    const [hover, setHover] = useState<number | null>(null);
+    const low = chart.min < 0 ? -niceCeiling(-chart.min) : 0;
+    const high = chart.max > 0 ? niceCeiling(chart.max) : low === 0 ? 1 : 0;
+    const plotWidth = Math.max(0, width - AXIS_WIDTH);
+    const plotHeight = HEIGHT - PLOT_TOP - LABEL_ROOM;
+    const band = plotWidth / chart.labels.length;
+    const y = (value: number): number => Math.round(PLOT_TOP + ((high - value) / (high - low)) * plotHeight);
+    const baseline = y(0);
+    const ticks = low === 0 ? [0, high / 2, high] : [low, 0, high];
+    const labelEvery = Math.max(1, Math.ceil(LABEL_BAND / Math.max(1, band)));
+    const center = (index: number): number => Math.round(AXIS_WIDTH + band * index + band / 2);
+    const gap = band * 0.2;
+    const barWidth = Math.max(1, (band - gap) / chart.series.length);
+
+    const segments = (values: (number | null)[]): string =>
+        values
+            .map((value, index) => (value === null ? null : `${center(index)} ${y(value)}`))
+            .reduce<string[]>((paths, point, index, all) => {
+                if (point !== null) {
+                    paths.push(`${index === 0 || all[index - 1] === null ? 'M' : 'L'}${point}`);
+                }
+                return paths;
+            }, [])
+            .join(' ');
+
+    return (
+        <>
+            <svg width={width} height={HEIGHT} aria-hidden className="block overflow-visible" onPointerLeave={() => setHover(null)}>
+                {hover !== null && (
+                    <rect x={Math.round(AXIS_WIDTH + band * hover)} y={PLOT_TOP} width={Math.round(band)} height={plotHeight} className="fill-surface-hover" />
+                )}
+                {ticks.map((tick) => (
+                    <g key={tick}>
+                        <line
+                            x1={AXIS_WIDTH}
+                            x2={width}
+                            y1={y(tick)}
+                            y2={y(tick)}
+                            className={tick === 0 ? 'stroke-border' : 'stroke-border-soft'}
+                            shapeRendering="crispEdges"
+                        />
+                        <text x={AXIS_WIDTH - 6} y={y(tick)} dy="0.32em" textAnchor="end" className="fill-text-faint text-xs tabular-nums">
+                            {valueText(tick, unit)}
+                        </text>
+                    </g>
+                ))}
+                {chart.labels.map((label, index) =>
+                    index % labelEvery === 0 ? (
+                        <text key={index} x={center(index)} y={HEIGHT - 4} textAnchor="middle" className="fill-text-faint text-xs">
+                            {label}
+                        </text>
+                    ) : null
+                )}
+                {kind === 'bar' ? (
+                    <g className={clsx(GROW, 'starting:scale-y-0')} style={{ transformOrigin: `0px ${baseline}px` }}>
+                        {chart.series.map((series, at) =>
+                            series.values.map((value, index) =>
+                                value === null ? null : (
+                                    <rect
+                                        key={`${series.key}:${index}`}
+                                        x={Math.round(AXIS_WIDTH + band * index + gap / 2 + barWidth * at)}
+                                        y={Math.min(y(value), baseline)}
+                                        width={Math.max(1, Math.round(barWidth) - 1)}
+                                        height={Math.abs(y(value) - baseline)}
+                                        rx={2}
+                                        style={{ fill: seriesColor(at) }}
+                                    />
+                                )
+                            )
+                        )}
+                    </g>
+                ) : (
+                    <g className={clsx(GROW, 'starting:opacity-0')}>
+                        {chart.series.map((series, at) => (
+                            <g key={series.key} style={{ color: seriesColor(at) }}>
+                                <path
+                                    d={segments(series.values)}
+                                    fill="none"
+                                    stroke="currentColor"
+                                    strokeWidth={2}
+                                    strokeLinejoin="round"
+                                    strokeLinecap="round"
+                                />
+                                {chart.labels.length <= DOTS_UP_TO &&
+                                    series.values.map((value, index) =>
+                                        value === null ? null : <circle key={index} cx={center(index)} cy={y(value)} r={2.5} fill="currentColor" />
+                                    )}
+                            </g>
+                        ))}
+                    </g>
+                )}
+                {chart.labels.map((_, index) => (
+                    <rect
+                        key={index}
+                        x={Math.round(AXIS_WIDTH + band * index)}
+                        y={0}
+                        width={Math.max(1, Math.round(band))}
+                        height={HEIGHT}
+                        fill="transparent"
+                        onPointerEnter={() => setHover(index)}
+                    />
+                ))}
+            </svg>
+            {hover !== null && <Readout chart={chart} index={hover} unit={unit} left={Math.min(Math.max(center(hover), 64), Math.max(64, width - 64))} />}
+        </>
+    );
+}
+
+/* A row of 24px per category, its label beside the bars. */
+function HorizontalChart({ chart, unit }: { chart: UiChartData; unit: string | undefined }) {
+    const high = niceCeiling(chart.max);
+    const single = chart.series.length === 1;
+    return (
+        <div aria-hidden className="flex flex-col">
+            {chart.labels.map((label, index) => (
+                <div key={index} className="flex h-6 items-center gap-2 text-xs">
+                    <span className="w-2/5 max-w-36 shrink-0 truncate text-text-muted">{label}</span>
+                    <span className="flex min-w-0 grow flex-col justify-center gap-px">
+                        {chart.series.map((series, at) => (
+                            <span
+                                key={series.key}
+                                className={clsx(GROW, 'block origin-left rounded-sm starting:scale-x-0', single ? 'h-3' : 'h-1')}
+                                style={{ width: `${(Math.max(0, series.values[index] ?? 0) / high) * 100}%`, backgroundColor: seriesColor(at) }}
+                            />
+                        ))}
+                    </span>
+                    {single && (
+                        <span className="w-16 shrink-0 text-right text-text-faint tabular-nums">{valueText(chart.series[0]!.values[index] ?? null, unit)}</span>
+                    )}
+                </div>
+            ))}
+        </div>
+    );
+}
+
+/* A bar per category split into its series, on one scale so the rows compare. */
+function StackedChart({ chart, unit }: { chart: UiChartData; unit: string | undefined }) {
+    return (
+        <div className="flex flex-col gap-2">
+            {chart.labels.map((label, index) => (
+                <div key={index} className="flex items-center gap-2 text-xs">
+                    {chart.labels.length > 1 && <span className="w-2/5 max-w-36 shrink-0 truncate text-text-muted">{label}</span>}
+                    <SegmentBar
+                        size="sm"
+                        className="grow"
+                        label={label}
+                        range={[0, chart.max]}
+                        parts={chart.series.map((series, at) => ({
+                            value: Math.max(0, series.values[index] ?? 0),
+                            color: seriesColor(at),
+                            label: `${series.key} ${valueText(series.values[index] ?? 0, unit)}`
+                        }))}
+                    />
+                </div>
+            ))}
+        </div>
+    );
+}
+
+function DrawnChart({ chart, kind, unit }: { chart: UiChartData; kind: ChartKind; unit: string | undefined }) {
+    const { t } = useTranslation('agent-chat');
+    const [measure, width] = useMeasuredWidth();
+    return (
+        <figure className="flex flex-col gap-2 px-2">
+            {chart.series.length > 1 && <Legend chart={chart} />}
+            <div ref={measure} role="img" aria-label={chartSummary(chart, unit, t)} className="relative">
+                {kind === 'hbar' ? (
+                    <HorizontalChart chart={chart} unit={unit} />
+                ) : kind === 'stacked' ? (
+                    <StackedChart chart={chart} unit={unit} />
+                ) : (
+                    <div style={{ height: HEIGHT }}>{width > 0 && <VerticalChart chart={chart} kind={kind} unit={unit} width={width} />}</div>
+                )}
+            </div>
+            <ValuesTable chart={chart} unit={unit} />
+        </figure>
+    );
+}
+
+/*
+ * Draws only once its node closed; until then a quiet surface of the height it will take holds its
+ * place. It grows in once, and not at all for a person who asked for less motion.
+ */
+export function ChartRenderer({ node }: UiRendererProps<UiProps<'Chart'>>) {
+    const { kind, data, unit } = node.props;
+    const chart = useMemo(() => (node.complete ? uiChartData(data, kind) : null), [node.complete, data, kind]);
+    if (!node.complete) {
+        return <div aria-hidden className="mx-2 rounded-md bg-surface-hover" style={{ height: chartHeight(kind, data.length) }} />;
+    }
+    if (chart === null) {
+        return <UiFallbackPart fallback={node.fallback} problem={{ kind: 'failed' }} />;
+    }
+    return <DrawnChart chart={chart} kind={kind} unit={unit} />;
+}

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

@@ -0,0 +1,98 @@
+import { useId, useState } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { ArrowRight, Check } from 'lucide-react';
+import type { UiProps } from '@adecore/intelligent-ui';
+import { DisabledReason, Icon, Spinner, Tooltip } from '@adecore/ui';
+import type { UiRendererProps } from '../render-context';
+import { useLater } from '../use-later';
+
+/* A context this long may run past its two lines, so the row offers all of it in a tooltip. */
+const LONG_CONTEXT = 120;
+const SPINNER_AFTER_MS = 300;
+
+/* Says once, politely, that the choices opened when the reply was done; never on a block that was already done. */
+export function ChoicesRenderer({ children, context }: UiRendererProps<UiProps<'Choices'>>) {
+    const { t } = useTranslation('agent-chat');
+    const [streamed] = useState(context.phase === 'streaming');
+    return (
+        <div role="group" aria-label={t('blocks.choices')} className="chat-ui-nodes flex flex-col gap-1.5">
+            {children}
+            <span className="sr-only" role="status">
+                {streamed && context.phase === 'final' ? t('blocks.choice.ready') : ''}
+            </span>
+        </div>
+    );
+}
+
+/*
+ * A row that shows what it sends: the label, and under it the context the agent receives. It stays
+ * closed while the reply streams, once the block is answered and without a host to send it, and
+ * remains focusable then so a screen reader hears why.
+ */
+export function ChoiceRenderer({ node, children, context }: UiRendererProps<UiProps<'Choice'>>) {
+    const { t } = useTranslation('agent-chat');
+    const descriptionId = useId();
+    const { context: detail, primary, disabled } = node.props;
+    const { answer, onChoose } = context;
+    const chosen = answer !== null && answer.choiceId === node.id;
+    const waiting = context.phase === 'streaming';
+    const unavailable = disabled === true || onChoose === undefined;
+    const failed = answer === null && context.failedChoiceId === node.id;
+    const closed = waiting || unavailable || answer !== null;
+    const slow = useLater(chosen && answer.state === 'sending', SPINNER_AFTER_MS);
+    const reason = waiting ? t('blocks.choice.waiting') : answer === null && unavailable ? t('blocks.choice.unavailable') : null;
+    const described = detail !== undefined && detail !== '';
+
+    const row = (
+        <button
+            type="button"
+            aria-disabled={closed || undefined}
+            aria-describedby={described ? descriptionId : undefined}
+            className={clsx(
+                'flex w-full items-start gap-2 rounded-md border px-2 py-1.5 text-left transition-[opacity,scale,background-color] duration-150 motion-reduce:transition-none',
+                chosen ? 'border-accent bg-accent-soft' : failed ? 'border-status-error bg-surface-hover' : 'border-border bg-surface-hover',
+                !closed && 'hover:bg-surface-active active:scale-99',
+                waiting ? 'opacity-60' : closed && !chosen && 'opacity-50'
+            )}
+            onClick={() => {
+                if (!closed) {
+                    onChoose?.(node.id);
+                }
+            }}
+        >
+            <Icon icon={ArrowRight} size={14} className={clsx('mt-1 shrink-0', primary === true ? 'text-accent' : 'text-text-faint')} />
+            <span className="flex min-w-0 grow flex-col">
+                <span className="text-sm font-semibold text-text">{children}</span>
+                {described && (
+                    <span id={descriptionId} className="line-clamp-2 text-xs text-text-muted">
+                        {detail}
+                    </span>
+                )}
+            </span>
+            {chosen && (
+                <span className="mt-0.5 flex shrink-0 items-center gap-1 text-xs text-accent">
+                    {slow ? <Spinner size={12} /> : <Icon icon={Check} size={12} />}
+                    {answer.state === 'queued' ? t('blocks.choice.queued') : t('blocks.choice.sent')}
+                </span>
+            )}
+        </button>
+    );
+
+    return (
+        <div className={clsx('flex flex-col gap-1', primary === true && 'order-first')}>
+            {reason !== null ? (
+                <DisabledReason reason={reason}>{row}</DisabledReason>
+            ) : described && detail.length > LONG_CONTEXT ? (
+                <Tooltip label={detail}>{row}</Tooltip>
+            ) : (
+                row
+            )}
+            {failed && (
+                <p role="alert" className="px-2 text-xs text-status-error">
+                    {t('blocks.choice.failed')}
+                </p>
+            )}
+        </div>
+    );
+}