@adea-ai/ui 0.140.0 → 0.142.0

package/src/components/composites/chain-of-thought/chain-of-thought.tsx

@@ -0,0 +1,141 @@
+import { ListOrdered } from 'lucide-solid'
+import { children as resolveChildren, splitProps, type ComponentProps, type JSX } from 'solid-js'
+import { cn } from '#lib/utils'
+import { Badge } from '../../ui/badge'
+import { Trace, TraceLine, type TraceLineProps, type TraceStatus } from '../../ui/trace'
+
+// A function child runs once, when the content mounts (see `deferred` in `tool.tsx`).
+const deferred = (render: () => JSX.Element) => render as unknown as JSX.Element
+
+/**
+ * ChainOfThought.
+ *
+ * A summary line that opens onto the steps behind it: "Searched 3 sources and
+ * compared them", then each source and each comparison as its own line. Reach for
+ * `Reasoning` when the thinking is prose, for `Plan` when the steps are a
+ * proposal still to be carried out, and for a plain `Trace` when each line is a
+ * tool call — a step here is a statement about the agent's *method*, whatever
+ * the host chooses to put in it.
+ *
+ * Nothing here knows how the steps were produced. The host passes the summary and
+ * the steps it wants shown; the component does not imply there is more, and a
+ * summary with no steps is a plain line.
+ *
+ * ## Steps
+ *
+ * A `ChainOfThoughtStep` is a `TraceLine` with a three-state `status` — `complete`
+ * (keeps its own icon, or a tick), `active` (running mark and shimmer) and
+ * `pending` (dashed mark). Every status is also spoken. A step without a status
+ * makes no claim at all. A step's `children` are its evidence — search-result
+ * badges, a snippet — and are open by default: someone who unfolded the summary
+ * to see the working wants to see what the working found, and one more click per
+ * step to read it defeats the point of the summary.
+ *
+ * `description` is a single truncated row beside the label. Anything longer
+ * belongs in `children`.
+ *
+ * Both parts are lines: put a `ChainOfThought` inside a `Trace`, next to the
+ * other activity of the turn.
+ */
+export type ChainOfThoughtStepStatus = 'complete' | 'active' | 'pending'
+
+/** The words spoken for each step status. */
+export const CHAIN_OF_THOUGHT_STATUS_LABELS: Readonly<Record<ChainOfThoughtStepStatus, string>> = {
+  complete: 'Done',
+  active: 'In progress',
+  pending: 'Pending',
+}
+
+const TRACE_STATUS: Readonly<Record<ChainOfThoughtStepStatus, TraceStatus>> = {
+  complete: 'success',
+  active: 'running',
+  pending: 'pending',
+}
+
+export type ChainOfThoughtProps = Omit<
+  TraceLineProps,
+  'title' | 'href' | 'onSelect' | 'selectHaspopup'
+> & {
+  /** The one-line account of what the steps add up to. */
+  summary?: JSX.Element
+  /** The steps' accessible name. */
+  stepsLabel?: string
+}
+
+export function ChainOfThought(props: ChainOfThoughtProps) {
+  const [local, rest] = splitProps(props, ['summary', 'stepsLabel', 'icon', 'children'])
+  // Resolved once so the steps are created once: a step keeps its own open state
+  // and its DOM while the summary is folded and unfolded.
+  const steps = resolveChildren(() => local.children)
+  const hasSteps = () => steps.toArray().length > 0
+  // A function child runs only when the content mounts, and once.
+  const stepList = () => (
+    <Trace size="sm" aria-label={local.stepsLabel ?? 'Steps'}>
+      {steps()}
+    </Trace>
+  )
+
+  return (
+    <TraceLine icon={local.icon ?? <ListOrdered />} title={local.summary ?? 'Steps'} {...rest}>
+      {hasSteps() ? deferred(stepList) : undefined}
+    </TraceLine>
+  )
+}
+
+export type ChainOfThoughtStepProps = Omit<
+  TraceLineProps,
+  'title' | 'status' | 'href' | 'onSelect' | 'selectHaspopup'
+> & {
+  label: JSX.Element
+  status?: ChainOfThoughtStepStatus
+}
+
+export function ChainOfThoughtStep(props: ChainOfThoughtStepProps) {
+  const [local, rest] = splitProps(props, ['label', 'status', 'statusLabel', 'defaultOpen'])
+  return (
+    <TraceLine
+      title={local.label}
+      status={local.status ? TRACE_STATUS[local.status] : undefined}
+      statusLabel={
+        local.status
+          ? (local.statusLabel ?? CHAIN_OF_THOUGHT_STATUS_LABELS[local.status])
+          : undefined
+      }
+      defaultOpen={local.defaultOpen ?? true}
+      {...rest}
+    />
+  )
+}
+
+/** Evidence for a step: the sources it searched, as a wrapping row of badges. */
+export function ChainOfThoughtResults(props: ComponentProps<'ul'>) {
+  const [local, rest] = splitProps(props, ['class', 'children'])
+  return (
+    <ul
+      role="list"
+      data-slot="chain-of-thought-results"
+      class={cn('m-0 flex min-w-0 list-none flex-wrap gap-1.5 p-0', local.class)}
+      {...rest}
+    >
+      {local.children}
+    </ul>
+  )
+}
+
+export type ChainOfThoughtResultProps = Omit<ComponentProps<'li'>, 'children'> & {
+  /** Rendered as text. A long label truncates and keeps its full text in `title`. */
+  label: string
+  icon?: JSX.Element
+}
+
+export function ChainOfThoughtResult(props: ChainOfThoughtResultProps) {
+  const [local, rest] = splitProps(props, ['class', 'label', 'icon'])
+  return (
+    <li data-slot="chain-of-thought-result" class={cn('min-w-0 max-w-full', local.class)} {...rest}>
+      <Badge variant="outline" class="max-w-full min-w-0" title={local.label}>
+        {local.icon}
+        <span class="truncate">{local.label}</span>
+      </Badge>
+    </li>
+  )
+}

package/src/components/composites/chain-of-thought/index.ts

@@ -0,0 +1,11 @@
+export {
+  CHAIN_OF_THOUGHT_STATUS_LABELS,
+  ChainOfThought,
+  ChainOfThoughtResult,
+  ChainOfThoughtResults,
+  ChainOfThoughtStep,
+  type ChainOfThoughtProps,
+  type ChainOfThoughtResultProps,
+  type ChainOfThoughtStepProps,
+  type ChainOfThoughtStepStatus,
+} from './chain-of-thought'

package/src/components/composites/chat/chat.tsx

@@ -0,0 +1,190 @@
+import { CircleAlert, Info, TriangleAlert } from 'lucide-solid'
+import { Show, splitProps, type ComponentProps, type JSX } from 'solid-js'
+import { Dynamic } from 'solid-js/web'
+import { cn } from '#lib/utils'
+import { cva, type VariantProps } from '#lib/variants'
+
+/**
+ * Chat.
+ *
+ * The frame a conversation lives in: a header, a strip for things the reader
+ * must know before reading anything else, the thread, and the composer. It is a
+ * layout and nothing more — the thread is a `MessageScroller`, the input is a
+ * composer, and what happens in between is the host's — which is why it takes
+ * slots instead of data.
+ *
+ * ## Why notices have their own row
+ *
+ * "The connection dropped", "this transcript has a gap", "this session is
+ * read-only" are about the whole conversation, not about a turn, and they must
+ * not scroll away with the turns. They sit between the header and the thread in
+ * their own grid track, so a notice appearing never steals the thread's row and
+ * collapses to zero height when there are none. Each notice states its cause in
+ * words and carries its own remedy (`action`); one that reports a *change*
+ * (`live`) is announced, one that describes a standing condition is not.
+ *
+ * ## Layout
+ *
+ * `h-full min-h-0`, so the thread scrolls inside the frame rather than the page
+ * growing, and a `min-w-0` track, so a long unbroken token in a turn cannot widen
+ * the whole conversation. Nothing here sets a width: the reading column is the
+ * turn's, and the composer sets its own measure.
+ */
+export type ChatProps = ComponentProps<'section'> & {
+  header?: JSX.Element
+  /** `ChatNotice`s. The row collapses when this is empty. */
+  notices?: JSX.Element
+  /** The composer. */
+  composer?: JSX.Element
+}
+
+export function Chat(props: ChatProps) {
+  const [local, rest] = splitProps(props, ['class', 'header', 'notices', 'composer', 'children'])
+  return (
+    <section
+      data-slot="chat"
+      class={cn(
+        'grid h-full min-h-0 min-w-0 grid-cols-[minmax(0,1fr)] grid-rows-[auto_auto_minmax(0,1fr)_auto] bg-background text-foreground',
+        local.class
+      )}
+      {...rest}
+    >
+      <div class="row-start-1 min-w-0">{local.header}</div>
+      <div class="row-start-2 flex min-w-0 flex-col">{local.notices}</div>
+      <div class="row-start-3 flex min-h-0 min-w-0 flex-col">{local.children}</div>
+      <div class="row-start-4 min-w-0">{local.composer}</div>
+    </section>
+  )
+}
+
+export type ChatHeaderProps = Omit<ComponentProps<'header'>, 'title'> & {
+  title: JSX.Element
+  /** One line under the title: identity, scope, generation. */
+  subtitle?: JSX.Element
+  /** The conversation's state in words (a `StatusChip`). */
+  status?: JSX.Element
+  /** Host actions: rename, archive, hand off. */
+  actions?: JSX.Element
+}
+
+export function ChatHeader(props: ChatHeaderProps) {
+  const [local, rest] = splitProps(props, ['class', 'title', 'subtitle', 'status', 'actions'])
+  return (
+    <header
+      data-slot="chat-header"
+      class={cn(
+        'flex min-h-topbar min-w-0 items-center gap-3 border-b border-border px-4 py-2',
+        local.class
+      )}
+      {...rest}
+    >
+      <div class="flex min-w-0 flex-1 flex-col">
+        <h2 class="m-0 truncate text-sm font-semibold tracking-tight">{local.title}</h2>
+        <Show when={local.subtitle}>
+          <p class="m-0 truncate text-xs text-muted-foreground">{local.subtitle}</p>
+        </Show>
+      </div>
+      <Show when={local.status}>{local.status}</Show>
+      <Show when={local.actions}>
+        <div class="flex shrink-0 items-center gap-1">{local.actions}</div>
+      </Show>
+    </header>
+  )
+}
+
+export const chatNoticeVariants = cva(
+  'flex min-w-0 items-start gap-2.5 border-b px-4 py-2 text-sm',
+  {
+    variants: {
+      tone: {
+        info: 'border-border bg-muted/40',
+        warning: 'border-warning/30 bg-warning-subtle',
+        danger: 'border-destructive/30 bg-destructive-subtle',
+      },
+    },
+    defaultVariants: { tone: 'info' },
+  }
+)
+
+export type ChatNoticeProps = Omit<ComponentProps<'div'>, 'title'> &
+  VariantProps<typeof chatNoticeVariants> & {
+    title: JSX.Element
+    description?: JSX.Element
+    /** The remedy: Reconnect, Jump to terminal. */
+    action?: JSX.Element
+    /** Announce it. Use for a change (connection lost), not a standing condition. */
+    live?: 'polite' | 'assertive'
+  }
+
+export function ChatNotice(props: ChatNoticeProps) {
+  const [local, rest] = splitProps(props, [
+    'class',
+    'tone',
+    'title',
+    'description',
+    'action',
+    'live',
+  ])
+  const Glyph = () =>
+    local.tone === 'danger' ? CircleAlert : local.tone === 'warning' ? TriangleAlert : Info
+  return (
+    <div
+      data-slot="chat-notice"
+      role={local.live === 'assertive' ? 'alert' : local.live === 'polite' ? 'status' : undefined}
+      class={cn(chatNoticeVariants({ tone: local.tone }), local.class)}
+      {...rest}
+    >
+      <span
+        aria-hidden="true"
+        class={cn('mt-0.5 shrink-0 [&_svg]:size-4', {
+          'text-muted-foreground': (local.tone ?? 'info') === 'info',
+          'text-warning': local.tone === 'warning',
+          'text-destructive': local.tone === 'danger',
+        })}
+      >
+        <Dynamic component={Glyph()} />
+      </span>
+      <div class="min-w-0 flex-1">
+        <p class="m-0 font-medium [overflow-wrap:anywhere]">{local.title}</p>
+        <Show when={local.description}>
+          <p class="m-0 text-xs text-muted-foreground [overflow-wrap:anywhere]">
+            {local.description}
+          </p>
+        </Show>
+      </div>
+      <Show when={local.action}>
+        <div class="flex shrink-0 items-center gap-1.5">{local.action}</div>
+      </Show>
+    </div>
+  )
+}
+
+export type ChatEmptyProps = Omit<ComponentProps<'div'>, 'title'> & {
+  title: JSX.Element
+  description?: JSX.Element
+  /** Prompt chips (`Suggestions`), shown only when the host has real ones. */
+  suggestions?: JSX.Element
+}
+
+/** A conversation with no turns yet. Centred in the thread, never in a card. */
+export function ChatEmpty(props: ChatEmptyProps) {
+  const [local, rest] = splitProps(props, ['class', 'title', 'description', 'suggestions'])
+  return (
+    <div
+      data-slot="chat-empty"
+      class={cn(
+        'mx-auto flex min-h-full w-full max-w-xl flex-col items-center justify-center gap-4 px-6 py-10 text-center',
+        local.class
+      )}
+      {...rest}
+    >
+      <div class="flex flex-col gap-1">
+        <h3 class="m-0 text-base font-semibold tracking-tight text-balance">{local.title}</h3>
+        <Show when={local.description}>
+          <p class="m-0 text-sm text-muted-foreground text-balance">{local.description}</p>
+        </Show>
+      </div>
+      <Show when={local.suggestions}>{local.suggestions}</Show>
+    </div>
+  )
+}

package/src/components/composites/chat/index.ts

@@ -0,0 +1,11 @@
+export {
+  Chat,
+  ChatEmpty,
+  ChatHeader,
+  ChatNotice,
+  chatNoticeVariants,
+  type ChatEmptyProps,
+  type ChatHeaderProps,
+  type ChatNoticeProps,
+  type ChatProps,
+} from './chat'

package/src/components/composites/checkpoint/checkpoint-model.ts

@@ -0,0 +1,71 @@
+import { boundText } from '../sources/source'
+
+/**
+ * Where a restore stands. `idle` is the resting state of a checkpoint that has
+ * not been restored from; the other three are only ever set because something
+ * happened — the host passes them, or the component sets them from the promise
+ * `onRestore` returned.
+ */
+export type CheckpointState = 'idle' | 'restoring' | 'restored' | 'failed'
+
+/** The checkpoint's name as drawn; a blank label is the honest generic word. */
+export function checkpointLabel(label: string | undefined): string {
+  return (label ? boundText(label, 80) : '') || 'Checkpoint'
+}
+
+/**
+ * The sentence for the status region. `idle` says nothing, because a
+ * checkpoint that has not been touched makes no statement. A failure carries the
+ * host's text when there is one.
+ */
+export function checkpointStatus(
+  state: CheckpointState,
+  error?: string,
+  disabledReason?: string
+): string | undefined {
+  switch (state) {
+    case 'restoring':
+      return 'Restoring…'
+    case 'restored':
+      return 'Restored'
+    case 'failed': {
+      const detail = error ? boundText(error, 240) : ''
+      return detail ? `Restore failed: ${detail}` : 'Restore failed'
+    }
+    case 'idle':
+      return disabledReason ? boundText(disabledReason, 240) : undefined
+  }
+}
+
+/**
+ * The confirmation dialog's words. The host's `consequence` is what actually
+ * names what will change, so it is used verbatim (bounded); without one the dialog
+ * says only what a restore always means and does not guess at the rest.
+ */
+export function restoreDialogCopy(
+  label: string | undefined,
+  consequence: string | undefined
+): { title: string; description: string } {
+  return {
+    title: `Restore to “${checkpointLabel(label)}”?`,
+    description: consequence
+      ? boundText(consequence, 400)
+      : 'Restoring returns to this checkpoint.',
+  }
+}
+
+/**
+ * Whether the Restore control exists, and whether it can be used. It exists only
+ * when the host passed a handler — a checkpoint that cannot be restored must not
+ * look as if it can — and goes once the restore has succeeded.
+ */
+export function restoreControl(
+  hasHandler: boolean,
+  state: CheckpointState,
+  disabledReason: string | undefined
+): { visible: boolean; disabled: boolean } {
+  return {
+    visible: hasHandler && state !== 'restored',
+    disabled: state === 'restoring' || disabledReason !== undefined,
+  }
+}

package/src/components/composites/checkpoint/checkpoint.tsx

@@ -0,0 +1,214 @@
+import { Flag } from 'lucide-solid'
+import {
+  createEffect,
+  createMemo,
+  createSignal,
+  createUniqueId,
+  on,
+  Show,
+  splitProps,
+  type ComponentProps,
+} from 'solid-js'
+import { cn } from '#lib/utils'
+import { Button } from '../../ui/button'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from '../../ui/alert-dialog'
+import { Marker } from '../../ui/marker'
+import { Spinner } from '../../ui/spinner'
+import { settleDecision } from '../confirmation/confirmation-model'
+import { boundText } from '../sources/source'
+import {
+  checkpointLabel,
+  checkpointStatus,
+  restoreControl,
+  restoreDialogCopy,
+  type CheckpointState,
+} from './checkpoint-model'
+
+/**
+ * Checkpoint.
+ *
+ * A point in the conversation the host can name: a divider in the transcript with
+ * a label and a time. It always renders — as a `Marker`, the quietest thing in the
+ * column — and it is honest about what it is:
+ *
+ * - **Without `onRestore` it is only a marker.** Not a disabled button, not a
+ *   greyed-out "Restore": nothing. Whether a checkpoint can be returned to is a
+ *   fact about the host's storage and permissions, and a control that implies it
+ *   can would be a claim nobody made.
+ * - **With `onRestore` it offers Restore, and Restore asks first.** An
+ *   `AlertDialog` (Escape and the scrim do nothing; every exit is a named choice)
+ *   states what will change in the host's own words (`consequence`) before the
+ *   handler is called. A restore throws work away; the confirmation is the point.
+ *
+ * ## States
+ *
+ * `idle` → `restoring` → `restored`, or `failed` with `error`. Pass `state` to
+ * drive it from the host; omit it and the component follows the promise
+ * `onRestore` returns. The status sentence is a live region that exists from the
+ * start, so a change is announced. While restoring, the control stays focusable
+ * (`aria-disabled`, not `disabled`) so focus is not dropped when the dialog hands
+ * it back; once restored the control goes and focus moves to the status line.
+ *
+ * A restore that cannot happen now takes `disabledReason`, shown in words under
+ * the divider; the host decides, the component explains.
+ */
+export type CheckpointProps = Omit<ComponentProps<'div'>, 'children' | 'onError'> & {
+  /** The checkpoint's name. Defaults to "Checkpoint". */
+  label?: string
+  /** When it was taken, already formatted for the reader. */
+  time?: string
+  state?: CheckpointState
+  /** Supplying this is what makes the checkpoint restorable. */
+  onRestore?: () => void | Promise<void>
+  /** What restoring will change, in the host's words. Shown in the confirmation. */
+  consequence?: string
+  restoreLabel?: string
+  /** Why Restore cannot be used right now. */
+  disabledReason?: string
+  /** Why a restore failed. */
+  error?: string
+}
+
+export function Checkpoint(props: CheckpointProps) {
+  const [local, rest] = splitProps(props, [
+    'class',
+    'label',
+    'time',
+    'state',
+    'onRestore',
+    'consequence',
+    'restoreLabel',
+    'disabledReason',
+    'error',
+  ])
+  const uid = createUniqueId()
+  const reasonId = `${uid}-status`
+  const [followed, setFollowed] = createSignal<CheckpointState>('idle')
+  const [failure, setFailure] = createSignal<string | undefined>(undefined)
+  const [confirming, setConfirming] = createSignal(false)
+  let inflight = false
+  let root: HTMLDivElement | undefined
+  let status: HTMLParagraphElement | undefined
+
+  const state = (): CheckpointState => local.state ?? followed()
+  const error = () => local.error ?? failure()
+  const control = () => restoreControl(local.onRestore !== undefined, state(), local.disabledReason)
+  const copy = () => restoreDialogCopy(local.label, local.consequence)
+  const statusText = () => checkpointStatus(state(), error(), local.disabledReason)
+
+  const restore = async () => {
+    if (inflight || control().disabled) return
+    inflight = true
+    setFailure(undefined)
+    setFollowed('restoring')
+    const result = await settleDecision(local.onRestore)
+    inflight = false
+    if (result.ok) {
+      setFollowed('restored')
+    } else {
+      setFailure(result.message)
+      setFollowed('failed')
+    }
+  }
+
+  // The control is replaced by the status line on success; do not strand focus.
+  createEffect(
+    on(
+      () => state() === 'restored',
+      (restored) => {
+        if (!restored) return
+        const active = document.activeElement
+        if (active === null || active === document.body || root?.contains(active)) {
+          status?.focus()
+        }
+      },
+      { defer: true }
+    )
+  )
+
+  // Built once. `Marker` reads `action` twice (to test it, then to draw it), and a
+  // JSX prop re-creates its component on every read: a second AlertDialog root
+  // would portal a second, invisible-to-the-tree dialog when this one opens.
+  const restoreAction = createMemo(() => (
+    <Show when={control().visible}>
+      <AlertDialog
+        open={confirming()}
+        onOpenChange={(open) => setConfirming(open && !control().disabled)}
+      >
+        <AlertDialogTrigger
+          as={Button}
+          variant="ghost"
+          size="2xs"
+          aria-disabled={control().disabled || undefined}
+          aria-describedby={statusText() ? reasonId : undefined}
+        >
+          <Show when={state() === 'restoring'}>
+            <Spinner size="xs" label={false} />
+          </Show>
+          {state() === 'restoring'
+            ? 'Restoring…'
+            : (local.restoreLabel ?? (state() === 'failed' ? 'Try again' : 'Restore'))}
+        </AlertDialogTrigger>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>{copy().title}</AlertDialogTitle>
+            <AlertDialogDescription class="[overflow-wrap:anywhere]">
+              {copy().description}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel as={Button} variant="ghost">
+              Do not restore
+            </AlertDialogCancel>
+            <AlertDialogAction as={Button} onClick={() => void restore()}>
+              {local.restoreLabel ?? 'Restore'}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </Show>
+  ))
+
+  return (
+    <div
+      ref={(element) => (root = element)}
+      data-slot="checkpoint"
+      data-state={state()}
+      class={local.class}
+      {...rest}
+    >
+      <Marker
+        variant="rule"
+        icon={<Flag />}
+        tone={state() === 'failed' ? 'danger' : 'neutral'}
+        label={checkpointLabel(local.label)}
+        description={local.time ? boundText(local.time, 60) : undefined}
+        action={restoreAction()}
+      />
+      {/* Always present, so a state change is a change to a live region rather than
+          the arrival of one. Empty while idle, which takes no space. */}
+      <p
+        id={reasonId}
+        ref={(element) => (status = element)}
+        role="status"
+        tabindex="-1"
+        class={cn('m-0 text-center text-xs outline-none [overflow-wrap:anywhere]', {
+          'text-destructive': state() === 'failed',
+          'text-muted-foreground': state() !== 'failed',
+        })}
+      >
+        {statusText()}
+      </p>
+    </div>
+  )
+}

package/src/components/composites/checkpoint/index.ts

@@ -0,0 +1,8 @@
+export { Checkpoint, type CheckpointProps } from './checkpoint'
+export {
+  checkpointLabel,
+  checkpointStatus,
+  restoreControl,
+  restoreDialogCopy,
+  type CheckpointState,
+} from './checkpoint-model'