@adea-ai/ui 0.140.0 → 0.142.0

package/src/components/composites/model-selector/models.ts

@@ -0,0 +1,103 @@
+import { boundText } from '../sources/source'
+
+/**
+ * An effort level a model supports: just its id (`'high'`), or an id with the
+ * words to show. A bare id is labelled by capitalising it, which is right for
+ * `low` / `medium` / `high` and wrong for anything else — pass a label then.
+ */
+export type ModelEffort = string | Readonly<{ id: string; label?: string; description?: string }>
+
+export type EffortOption = Readonly<{ id: string; label: string; description?: string }>
+
+/**
+ * A model the person may pick. `efforts` lists the effort levels *this* model
+ * advertises; a model without it has no effort control, because showing one would
+ * claim the model can be told how hard to think. `disabledReason` is the host's
+ * authority speaking (plan, quota, region): the model stays in the list, disabled,
+ * with the reason beside it.
+ */
+export type ModelOption = Readonly<{
+  /** Unique within the list. */
+  id: string
+  label: string
+  provider: string
+  description?: string
+  disabledReason?: string
+  efforts?: readonly ModelEffort[]
+}>
+
+const LABEL_LIMIT = 60
+const DESCRIPTION_LIMIT = 160
+
+function titleCase(id: string): string {
+  const clean = boundText(id, LABEL_LIMIT)
+  return clean.charAt(0).toUpperCase() + clean.slice(1)
+}
+
+/** Efforts as options: blanks dropped, duplicate ids kept once (first wins), text bounded. */
+export function normalizeEfforts(efforts: readonly ModelEffort[] | undefined): EffortOption[] {
+  const seen = new Set<string>()
+  const out: EffortOption[] = []
+  for (const effort of efforts ?? []) {
+    const id = typeof effort === 'string' ? effort : effort.id
+    if (id.trim() === '' || seen.has(id)) continue
+    seen.add(id)
+    if (typeof effort === 'string') {
+      out.push({ id, label: titleCase(id) })
+    } else {
+      out.push({
+        id,
+        label: (effort.label ? boundText(effort.label, LABEL_LIMIT) : '') || titleCase(id),
+        description: effort.description
+          ? boundText(effort.description, DESCRIPTION_LIMIT)
+          : undefined,
+      })
+    }
+  }
+  return out
+}
+
+export function findModel(
+  models: readonly ModelOption[],
+  id: string | undefined
+): ModelOption | undefined {
+  return id === undefined ? undefined : models.find((model) => model.id === id)
+}
+
+/** The selected effort, only if the selected model actually offers it. */
+export function resolveEffort(
+  model: ModelOption | undefined,
+  effort: string | undefined
+): EffortOption | undefined {
+  if (!model || effort === undefined) return undefined
+  return normalizeEfforts(model.efforts).find((option) => option.id === effort)
+}
+
+export type ModelGroup = Readonly<{ provider: string; models: readonly ModelOption[] }>
+
+/** Group by provider, in the order providers first appear, so the host controls ranking. */
+export function groupModels(models: readonly ModelOption[]): ModelGroup[] {
+  const groups = new Map<string, ModelOption[]>()
+  for (const model of models) {
+    const provider = boundText(model.provider, LABEL_LIMIT) || 'Other'
+    const bucket = groups.get(provider)
+    if (bucket) bucket.push(model)
+    else groups.set(provider, [model])
+  }
+  return [...groups].map(([provider, list]) => ({ provider, models: list }))
+}
+
+/** Past this many models the list gets a search box; a short list is quicker to read. */
+export const MODEL_SEARCH_THRESHOLD = 7
+
+export function needsSearch(count: number, threshold = MODEL_SEARCH_THRESHOLD): boolean {
+  return count > threshold
+}
+
+/**
+ * What the search matches against: everything a person might type to find a model
+ * — its name, its provider, its id, and its description.
+ */
+export function modelSearchValue(model: ModelOption): string {
+  return [model.label, model.provider, model.id, model.description ?? ''].join(' ')
+}

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

@@ -0,0 +1 @@
+export { Plan, type PlanProps, type PlanStep, type PlanStepStatus } from './plan'

package/src/components/composites/plan/plan.tsx

@@ -0,0 +1,155 @@
+import { ListTodo } from 'lucide-solid'
+import { createMemo, Index, Show, splitProps, type JSX } from 'solid-js'
+import { Progress } from '../../ui/progress'
+import { TraceDetail, TraceLine, type TraceLineProps } from '../../ui/trace'
+import {
+  TaskItemList,
+  TaskItemRow,
+  taskProgress,
+  taskProgressLabel,
+  type TaskItemStatus,
+} from '../task'
+
+// 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
+
+/**
+ * Plan.
+ *
+ * What the agent intends to do, as a `TraceLine` that opens onto the steps: a
+ * title, an optional description, the steps with their status, how far along
+ * they are, and — when the host supplies them — the actions the reader can take
+ * (approve, edit, run). Reach for `Task` when the list is a unit of work that is
+ * already under way and not a proposal, for `Queue` when it is the agent's
+ * running todo list, and for `ChainOfThought` when the steps describe how an
+ * answer was reached rather than what will be done.
+ *
+ * ## It opens by default
+ *
+ * Unlike a tool call, the plan is the thing being decided or followed, so it
+ * starts open (`defaultOpen={false}` folds it). A plan with no steps, no
+ * description and no actions is a plain line.
+ *
+ * ## Progress is derived, in words
+ *
+ * "2 of 5 steps done" and the bar come from the steps' own `status` and appear
+ * only when at least one step has one; a step with no status counts toward the
+ * total and not toward "done" (the host did not say it was finished). The bar is
+ * the shared `Progress`, which publishes the same phrase to assistive
+ * technology, so the number is never only a length.
+ *
+ * ## Streaming
+ *
+ * While `streaming` the plan is still being written, so its length is not known
+ * and no progress is claimed: the title shimmers, the line says "Drafting", and
+ * a caret trails the last step. Finished steps keep their DOM while the last one
+ * grows (rows are kept by position).
+ *
+ * ## The host owns authority
+ *
+ * `actions` is a slot. The plan neither enables nor disables what is in it, and
+ * with no `actions` there are no controls — a plan the reader may not approve
+ * simply has no Approve button.
+ *
+ * A `Plan` is a line: place it inside a `Trace`.
+ */
+export type PlanStepStatus = TaskItemStatus
+
+export type PlanStep = Readonly<{
+  id?: string
+  label: string
+  description?: string
+  status?: PlanStepStatus
+}>
+
+export type PlanProps = Omit<
+  TraceLineProps,
+  'description' | 'href' | 'onSelect' | 'selectHaspopup' | 'children' | 'status' | 'statusLabel'
+> & {
+  steps: readonly PlanStep[]
+  /** What the plan is for, above the steps. */
+  description?: JSX.Element
+  /** True while the plan is still being generated. */
+  streaming?: boolean
+  /** Controls for the reader: approve, edit, run. Absent means there are none. */
+  actions?: JSX.Element
+}
+
+export function Plan(props: PlanProps) {
+  const [local, rest] = splitProps(props, [
+    'steps',
+    'description',
+    'streaming',
+    'actions',
+    'icon',
+    'meta',
+    'defaultOpen',
+  ])
+  const progress = createMemo(() => (local.streaming ? undefined : taskProgress(local.steps)))
+  const meta = () => {
+    if (local.meta !== undefined) return local.meta
+    if (local.streaming) return 'Drafting'
+    const value = progress()
+    return value ? taskProgressLabel(value) : undefined
+  }
+  const hasDetail = () =>
+    local.steps.length > 0 ||
+    local.description !== undefined ||
+    local.actions !== undefined ||
+    local.streaming === true
+
+  const detail = () => (
+    <TraceDetail class="flex flex-col gap-2">
+      <Show when={local.description}>
+        <div class="text-sm text-muted-foreground">{local.description}</div>
+      </Show>
+      <Show when={progress()}>
+        {(value) => (
+          <Progress
+            value={value().done}
+            minValue={0}
+            maxValue={Math.max(1, value().total)}
+            aria-label="Plan progress"
+            getValueLabel={({ value: done, max }) =>
+              `${done} of ${max} ${max === 1 ? 'step' : 'steps'} done`
+            }
+          />
+        )}
+      </Show>
+      <Show when={local.steps.length > 0}>
+        <TaskItemList label="Plan steps">
+          <Index each={local.steps}>
+            {(step) => (
+              <TaskItemRow
+                text={step().label}
+                description={step().description}
+                status={step().status}
+              />
+            )}
+          </Index>
+        </TaskItemList>
+      </Show>
+      <Show when={local.streaming}>
+        <span class="streaming-caret" aria-hidden="true" />
+      </Show>
+      <Show when={local.actions}>
+        <div data-slot="plan-actions" class="flex flex-wrap items-center gap-2 pt-1">
+          {local.actions}
+        </div>
+      </Show>
+    </TraceDetail>
+  )
+
+  return (
+    <TraceLine
+      icon={local.icon ?? <ListTodo />}
+      status={local.streaming ? 'running' : undefined}
+      statusLabel="Generating"
+      meta={meta()}
+      defaultOpen={local.defaultOpen ?? true}
+      {...rest}
+    >
+      {hasDetail() ? deferred(detail) : undefined}
+    </TraceLine>
+  )
+}

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

@@ -0,0 +1,10 @@
+export {
+  partitionQueue,
+  Queue,
+  QueueFollowUps,
+  type QueueFollowUp,
+  type QueueFollowUpsProps,
+  type QueueItem,
+  type QueueItemStatus,
+  type QueueProps,
+} from './queue'

package/src/components/composites/queue/queue.tsx

@@ -0,0 +1,264 @@
+import { CornerDownRight, ListChecks, ListTodo, MessageSquarePlus, X } from 'lucide-solid'
+import {
+  createMemo,
+  Index,
+  onCleanup,
+  Show,
+  splitProps,
+  type ComponentProps,
+  type JSX,
+} from 'solid-js'
+import { Button } from '../../ui/button'
+import { Trace, TraceLine } from '../../ui/trace'
+import { TaskItemList, TaskItemRow } from '../task'
+
+// 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
+
+/**
+ * Queue.
+ *
+ * The agent's todo list, split the way a reader asks about it: what is still to
+ * do, and what is already done. Two collapsible sections with their counts,
+ * "Pending" open and "Completed" folded — the finished work is the record, the
+ * pending work is the question. Reach for `Plan` when the list is a proposal
+ * awaiting a decision, for `Task` when it is one piece of work with files
+ * attached, and for `QueueFollowUps` (below) when the things waiting are
+ * *messages from the person*, not work the agent set itself.
+ *
+ * ## Sorting is the host's statement, not ours
+ *
+ * An item is in the Completed section only if its `status` is `complete`.
+ * Everything else — `pending`, `active`, or no status at all — is still to do,
+ * which is what "not marked done" means; the mark shown matches (an item with
+ * no status gets the pending mark, because it is in the Pending section). An
+ * empty section is not drawn: "Completed (0)" is noise, and a list with nothing
+ * in either section renders nothing, or the `empty` content if the host gave
+ * some, rather than a heading over a void.
+ *
+ * ## Bounded
+ *
+ * Each section scrolls inside a capped, keyboard-focusable region, and rows are
+ * kept by position, so a list of two hundred items does not push the answer out
+ * of view and a status change updates a row instead of recreating it. Item text
+ * wraps to three lines and is clamped (see `Task`).
+ *
+ * A `Queue` is a block (its own `Trace`) and can sit between other parts of a
+ * turn.
+ */
+export type QueueItemStatus = 'pending' | 'active' | 'complete'
+
+export type QueueItem = Readonly<{
+  id?: string
+  text: string
+  description?: string
+  status?: QueueItemStatus
+}>
+
+/** Split a todo list into the two sections. Order is preserved within each. */
+export function partitionQueue(items: readonly QueueItem[]): Readonly<{
+  pending: readonly QueueItem[]
+  completed: readonly QueueItem[]
+}> {
+  return {
+    pending: items.filter((item) => item.status !== 'complete'),
+    completed: items.filter((item) => item.status === 'complete'),
+  }
+}
+
+function itemCount(count: number): string {
+  return `${count} ${count === 1 ? 'item' : 'items'}`
+}
+
+/** The count, shown as a number and spoken as a phrase. */
+function Count(props: { count: number; noun?: string }) {
+  return (
+    <>
+      <span aria-hidden="true">{props.count}</span>
+      <span class="sr-only">{props.noun ?? itemCount(props.count)}</span>
+    </>
+  )
+}
+
+export type QueueProps = Omit<ComponentProps<typeof Trace>, 'children'> & {
+  items: readonly QueueItem[]
+  pendingLabel?: string
+  completedLabel?: string
+  /** Shown when there is nothing in either section. Omit to draw nothing. */
+  empty?: JSX.Element
+  /** Open the Completed section initially. */
+  defaultCompletedOpen?: boolean
+}
+
+export function Queue(props: QueueProps) {
+  const [local, rest] = splitProps(props, [
+    'items',
+    'pendingLabel',
+    'completedLabel',
+    'empty',
+    'defaultCompletedOpen',
+  ])
+  const sections = createMemo(() => partitionQueue(local.items))
+  const pending = () => sections().pending
+  const completed = () => sections().completed
+  const pendingLabel = () => local.pendingLabel ?? 'Pending'
+  const completedLabel = () => local.completedLabel ?? 'Completed'
+
+  return (
+    <Show
+      when={local.items.length > 0}
+      fallback={
+        <Show when={local.empty}>
+          <Trace aria-label="Queue" {...rest}>
+            <TraceLine title={local.empty} />
+          </Trace>
+        </Show>
+      }
+    >
+      <Trace aria-label="Queue" {...rest}>
+        <Show when={pending().length > 0}>
+          <TraceLine
+            icon={<ListTodo />}
+            title={pendingLabel()}
+            meta={<Count count={pending().length} />}
+            defaultOpen
+          >
+            {deferred(() => (
+              <TaskItemList label={pendingLabel()}>
+                <Index each={pending()}>
+                  {(item) => (
+                    <TaskItemRow
+                      text={item().text}
+                      description={item().description}
+                      status={item().status ?? 'pending'}
+                    />
+                  )}
+                </Index>
+              </TaskItemList>
+            ))}
+          </TraceLine>
+        </Show>
+        <Show when={completed().length > 0}>
+          <TraceLine
+            icon={<ListChecks />}
+            title={completedLabel()}
+            meta={<Count count={completed().length} />}
+            defaultOpen={local.defaultCompletedOpen ?? false}
+          >
+            {deferred(() => (
+              <TaskItemList label={completedLabel()}>
+                <Index each={completed()}>
+                  {(item) => (
+                    <TaskItemRow
+                      text={item().text}
+                      description={item().description}
+                      status="complete"
+                    />
+                  )}
+                </Index>
+              </TaskItemList>
+            ))}
+          </TraceLine>
+        </Show>
+      </Trace>
+    </Show>
+  )
+}
+
+export type QueueFollowUp = Readonly<{
+  id?: string
+  text: string
+  /** Removes it from the queue. Omit it and the row has no remove control. */
+  onRemove?: () => void
+}>
+
+const REMOVE_LABEL_CHARS = 60
+
+function FollowUpRow(props: { item: QueueFollowUp }) {
+  let remove: HTMLButtonElement | undefined
+
+  // Rows are kept by position, so removing a middle row leaves the focused
+  // button where it is (now on the next message). Only the last row is ever
+  // disposed under focus; hand focus to the one before it rather than to `body`.
+  onCleanup(() => {
+    if (!remove || document.activeElement !== remove) return
+    const buttons = remove
+      .closest('ul')
+      ?.querySelectorAll<HTMLButtonElement>('button[data-slot="queue-follow-up-remove"]')
+    const previous = Array.from(buttons ?? []).filter((button) => button !== remove)
+    previous.at(-1)?.focus()
+  })
+
+  const text = () =>
+    props.item.text.length > 1_000 ? `${props.item.text.slice(0, 1_000)}…` : props.item.text
+  const label = () =>
+    props.item.text.length > REMOVE_LABEL_CHARS
+      ? `${props.item.text.slice(0, REMOVE_LABEL_CHARS)}…`
+      : props.item.text
+
+  return (
+    <li data-slot="queue-follow-up" class="flex min-w-0 items-start gap-2 rounded-md px-1.5 py-0.5">
+      <CornerDownRight aria-hidden="true" class="mt-0.5 size-3.5 shrink-0 text-muted-foreground" />
+      <p
+        title={text()}
+        class="m-0 line-clamp-3 min-w-0 flex-1 text-sm [overflow-wrap:anywhere] whitespace-pre-wrap text-foreground"
+      >
+        {text()}
+      </p>
+      <Show when={props.item.onRemove}>
+        {(onRemove) => (
+          <Button
+            ref={(element) => (remove = element)}
+            data-slot="queue-follow-up-remove"
+            type="button"
+            variant="ghost"
+            size="icon-2xs"
+            class="shrink-0"
+            aria-label={`Remove queued message: ${label()}`}
+            onClick={() => onRemove()()}
+          >
+            <X aria-hidden="true" />
+          </Button>
+        )}
+      </Show>
+    </li>
+  )
+}
+
+export type QueueFollowUpsProps = Omit<ComponentProps<typeof Trace>, 'children'> & {
+  items: readonly QueueFollowUp[]
+  /** The section's title. */
+  title?: string
+  defaultOpen?: boolean
+}
+
+/**
+ * Follow-up messages the person sent that have not been delivered yet. They are
+ * the person's words, so they are shown as sent (wrapped, clamped to three
+ * lines) rather than as work. The remove control exists per message only when
+ * that message carries `onRemove`: whether it may still be withdrawn is the
+ * runtime's to say, and a message past recall simply has no button. With no
+ * messages the component draws nothing.
+ */
+export function QueueFollowUps(props: QueueFollowUpsProps) {
+  const [local, rest] = splitProps(props, ['items', 'title', 'defaultOpen'])
+  const title = () => local.title ?? 'Queued follow-ups'
+  return (
+    <Show when={local.items.length > 0}>
+      <Trace aria-label={title()} {...rest}>
+        <TraceLine
+          icon={<MessageSquarePlus />}
+          title={title()}
+          meta={<Count count={local.items.length} noun={`${local.items.length} waiting`} />}
+          defaultOpen={local.defaultOpen ?? true}
+        >
+          {deferred(() => (
+            <TaskItemList label={title()}>
+              <Index each={local.items}>{(item) => <FollowUpRow item={item()} />}</Index>
+            </TaskItemList>
+          ))}
+        </TraceLine>
+      </Trace>
+    </Show>
+  )
+}

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

@@ -0,0 +1 @@
+export { formatDuration, Reasoning, reasoningTitle, type ReasoningProps } from './reasoning'