@adea-ai/ui 0.140.0 → 0.142.0

package/dist/r/src/components/composites/reasoning/reasoning.tsx

@@ -0,0 +1,176 @@
+import { Brain } from 'lucide-solid'
+import { createEffect, createSignal, on, splitProps, type JSX } from 'solid-js'
+import { MessageText } from '../../ui/message'
+import { ScrollArea } from '../../ui/scroll-area'
+import { TraceDetail, TraceLine, type TraceLineProps } 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
+
+/**
+ * Reasoning.
+ *
+ * The agent's thinking, as a `TraceLine`: a title that says what state it is in,
+ * and a body that is the text the host chose to show. Reach for `ChainOfThought`
+ * when the thinking is a sequence of discrete steps with their own status, and
+ * for a plain `MessageText` when the text is simply part of the answer.
+ *
+ * ## It shows what it is given, and nothing else
+ *
+ * `text` is whatever the host has decided is user-visible — a provider's reasoning
+ * summary, a model's visible scratchpad. This component never implies there is
+ * more behind it: no "show full reasoning" control, no placeholder body, no
+ * ellipsis standing in for hidden content. With no `text` and no `streaming` the
+ * line is a plain, non-expandable line titled "Reasoning", because there is
+ * nothing to open.
+ *
+ * ## The title is the state
+ *
+ * - `streaming` — "Thinking…", with the running mark and shimmer.
+ * - finished with a `duration` (seconds) — "Thought for 4s".
+ * - finished without one — "Reasoning". A duration the host did not measure is
+ *   not invented.
+ *
+ * ## Open while it is arriving, closed once it is done
+ *
+ * While streaming the body is open so the reader can follow along; when the
+ * stream ends it folds away so the settled transcript stays one quiet column. The
+ * reader's own toggle wins in both directions and is remembered until the next
+ * stream begins, so someone who closed it mid-stream is not re-opened and
+ * someone who opened it afterwards is not folded. Pass `open` and `onOpenChange`
+ * to own the state instead.
+ *
+ * ## Bounded, and stable while it grows
+ *
+ * The body is `MessageText`, so the text is untrusted and rendered as text (see
+ * its doc comment), and earlier paragraphs keep their DOM while the last one
+ * grows. The scroller is capped; while streaming it follows the newest text only
+ * if the reader has not scrolled up, so reading the start of a long thought is
+ * not interrupted by the end of it.
+ */
+
+/** `4` → `4s`, `65` → `1m 5s`. Nothing for a value that is not a finite duration. */
+export function formatDuration(seconds: number | undefined): string | undefined {
+  if (seconds === undefined || !Number.isFinite(seconds) || seconds < 0) return undefined
+  const total = Math.round(seconds)
+  if (total === 0) return '<1s'
+  if (total < 60) return `${total}s`
+  const hours = Math.floor(total / 3600)
+  const minutes = Math.floor((total % 3600) / 60)
+  const rest = total % 60
+  if (hours > 0) return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`
+  return rest > 0 ? `${minutes}m ${rest}s` : `${minutes}m`
+}
+
+/** The line's title for a state. Exported so a host can say the same thing elsewhere. */
+export function reasoningTitle(state: { streaming?: boolean; duration?: number }): string {
+  if (state.streaming) return 'Thinking…'
+  const duration = formatDuration(state.duration)
+  return duration ? `Thought for ${duration}` : 'Reasoning'
+}
+
+/** Within this many pixels of the end counts as "following". */
+const FOLLOW_SLOP = 16
+
+export type ReasoningProps = Omit<
+  TraceLineProps,
+  | 'title'
+  | 'description'
+  | 'status'
+  | 'statusLabel'
+  | 'defaultOpen'
+  | 'children'
+  | 'href'
+  | 'onSelect'
+  | 'selectHaspopup'
+> & {
+  /** The reasoning the host marked as user-visible. Untrusted text. */
+  text?: string
+  /** True while text may still arrive. */
+  streaming?: boolean
+  /** Seconds the thinking took, if the host measured it. */
+  duration?: number
+  /** Replaces the state-derived title, e.g. for another language. */
+  title?: JSX.Element
+}
+
+function ReasoningBody(props: { text: string; streaming?: boolean }) {
+  let scroller: HTMLDivElement | undefined
+  let following = true
+
+  createEffect(() => {
+    // Read for the dependency: new text is the event that may need following.
+    void props.text
+    if (props.streaming && following && scroller) scroller.scrollTop = scroller.scrollHeight
+  })
+
+  return (
+    <TraceDetail>
+      <ScrollArea
+        ref={(element) => (scroller = element)}
+        role="region"
+        aria-label="Reasoning text"
+        class="max-h-72"
+        onScroll={(event) => {
+          const element = event.currentTarget
+          following = element.scrollHeight - element.scrollTop - element.clientHeight <= FOLLOW_SLOP
+        }}
+      >
+        <MessageText
+          text={props.text}
+          streaming={props.streaming}
+          codeBlockProps={{ maxHeight: '16rem', wrap: true }}
+        />
+      </ScrollArea>
+    </TraceDetail>
+  )
+}
+
+export function Reasoning(props: ReasoningProps) {
+  const [local, rest] = splitProps(props, [
+    'text',
+    'streaming',
+    'duration',
+    'title',
+    'icon',
+    'open',
+    'onOpenChange',
+  ])
+  // `undefined` means "the reader has not decided", which is what lets the stream
+  // open and close the line on its own.
+  const [chosen, setChosen] = createSignal<boolean>()
+  const open = () => local.open ?? chosen() ?? local.streaming === true
+  const hasBody = () => (local.text ?? '').trim() !== '' || local.streaming === true
+
+  createEffect(
+    on(
+      () => local.streaming,
+      (streaming) => {
+        if (streaming) setChosen(undefined)
+      },
+      { defer: true }
+    )
+  )
+
+  // A function child runs only when the content mounts, so a folded line parses nothing.
+  const body = () => <ReasoningBody text={local.text ?? ''} streaming={local.streaming} />
+
+  return (
+    <TraceLine
+      icon={local.icon ?? <Brain />}
+      title={
+        local.title ?? reasoningTitle({ streaming: local.streaming, duration: local.duration })
+      }
+      status={local.streaming ? 'running' : undefined}
+      statusLabel="In progress"
+      open={open()}
+      onOpenChange={(value) => {
+        setChosen(value)
+        local.onOpenChange?.(value)
+      }}
+      {...rest}
+    >
+      {hasBody() ? deferred(body) : undefined}
+    </TraceLine>
+  )
+}

package/dist/r/src/components/composites/sources/index.ts

@@ -0,0 +1,11 @@
+export { Sources, type SourcesProps } from './sources'
+export {
+  boundText,
+  safeSourceUrl,
+  sourceHost,
+  sourceTitle,
+  sourcesLabel,
+  SOURCE_SNIPPET_LIMIT,
+  SOURCE_TITLE_LIMIT,
+  type Source,
+} from './source'

package/dist/r/src/components/composites/sources/source.ts

@@ -0,0 +1,116 @@
+import { safeHref } from '../../ui/message/parse-message-text'
+
+/**
+ * What a reply drew on.
+ *
+ * Every field except `title` is optional because a source is only as much as the
+ * host knew: a search result has a snippet, a file has no URL, a tool result has
+ * neither. Nothing is inferred from what is missing, and two entries that share a
+ * URL stay two entries — the host may have cited two passages of one page, and a
+ * list that quietly merged them would also renumber every citation after it.
+ */
+export type Source = Readonly<{
+  /** A stable key for streaming updates. Falls back to position. */
+  id?: string
+  title: string
+  url?: string
+  snippet?: string
+}>
+
+/** Titles and snippets come from the open web; these keep one of them from owning the layout. */
+export const SOURCE_TITLE_LIMIT = 160
+export const SOURCE_SNIPPET_LIMIT = 480
+
+// C0 controls other than tab and newline, DEL, and the bidirectional marks,
+// overrides and isolates: the last group is how a title can be made to read as a
+// different string than the one that is stored. Tested by code point rather than
+// by a regular expression so no control or invisible character appears in this file.
+function isHidden(code: number): boolean {
+  return (
+    code <= 0x08 ||
+    code === 0x0b ||
+    code === 0x0c ||
+    (code >= 0x0e && code <= 0x1f) ||
+    code === 0x7f ||
+    code === 0x200e ||
+    code === 0x200f ||
+    (code >= 0x202a && code <= 0x202e) ||
+    (code >= 0x2066 && code <= 0x2069)
+  )
+}
+
+function stripHidden(value: string): string {
+  let out = ''
+  for (let index = 0; index < value.length; index += 1) {
+    if (!isHidden(value.charCodeAt(index))) out += value.charAt(index)
+  }
+  return out
+}
+
+/**
+ * Untrusted text, made safe to lay out: hidden and direction-overriding
+ * characters removed, runs of whitespace (including newlines) collapsed to one
+ * space, and clipped to `limit` with an ellipsis. It is still only ever rendered
+ * as a text node — this is about length and spoofing, not escaping.
+ */
+export function boundText(value: string, limit: number): string {
+  // Clip before the regex passes so a multi-megabyte value costs a slice, not a scan.
+  const head = value.length > limit * 4 ? value.slice(0, limit * 4) : value
+  const clean = stripHidden(head).replace(/\s+/g, ' ').trim()
+  if (clean.length <= limit) return clean
+  const clipped = clean.slice(0, limit)
+  // Never end on half of a surrogate pair: it renders as a replacement glyph.
+  const last = clipped.charCodeAt(clipped.length - 1)
+  const whole = last >= 0xd800 && last <= 0xdbff ? clipped.slice(0, -1) : clipped
+  return `${whole.trimEnd()}…`
+}
+
+/**
+ * A URL a link may point at: `http:`, `https:` or `mailto:`, no embedded
+ * credentials. `safeHref` (the message parser's own gate) already refuses other
+ * schemes, whitespace and control characters and over-long values; credentials are
+ * refused here as well because `https://trusted.example@evil.example/` shows a
+ * host that is not the one the link goes to.
+ */
+export function safeSourceUrl(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined
+  const href = safeHref(value)
+  if (href === undefined) return undefined
+  try {
+    const url = new URL(href)
+    if (url.username !== '' || url.password !== '') return undefined
+  } catch {
+    return undefined
+  }
+  return href
+}
+
+/**
+ * The host to show beside a title, taken from the parsed URL (so an
+ * internationalised name appears in its `xn--` form and a look-alike cannot pass
+ * for the real one). A mailto source shows its address. Undefined when the URL is
+ * absent or unsafe: nothing is guessed.
+ */
+export function sourceHost(value: string | undefined): string | undefined {
+  const href = safeSourceUrl(value)
+  if (href === undefined) return undefined
+  try {
+    const url = new URL(href)
+    if (url.protocol === 'mailto:') {
+      return boundText(decodeURIComponent(url.pathname), 80) || undefined
+    }
+    return url.hostname || undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** The line a collapsed list shows. One source is singular; the count is the list's length. */
+export function sourcesLabel(count: number): string {
+  return `Used ${count} ${count === 1 ? 'source' : 'sources'}`
+}
+
+/** What to call a source: its title, else its host, else an honest placeholder. */
+export function sourceTitle(source: Source): string {
+  return boundText(source.title, SOURCE_TITLE_LIMIT) || sourceHost(source.url) || 'Untitled source'
+}

package/dist/r/src/components/composites/sources/sources.tsx

@@ -0,0 +1,163 @@
+import { BookOpen } from 'lucide-solid'
+import { createSignal, For, Show, splitProps } from 'solid-js'
+import { Button } from '../../ui/button'
+import { TextLink } from '../../ui/text-link'
+import { Trace, TraceDetail, TraceLine, type TraceProps } from '../../ui/trace'
+import {
+  SOURCE_SNIPPET_LIMIT,
+  boundText,
+  safeSourceUrl,
+  sourceHost,
+  sourceTitle,
+  sourcesLabel,
+  type Source,
+} from './source'
+
+/**
+ * Sources.
+ *
+ * The links a reply used, as one `Trace` line — "Used 4 sources" — that expands
+ * into the list. It lives under the answer with the rest of the agent's activity
+ * rather than as a card of its own, because a reader who wants to check a claim
+ * will open it and one who does not should not have to scroll past it. For a
+ * marker inside a sentence use `InlineCitation`, which points at the same
+ * `Source` shape; the two are numbered the same way (position in this list).
+ *
+ * ## What it will and will not say
+ *
+ * - **No sources, no line.** An empty list renders nothing: "Used 0 sources" is a
+ *   claim about an answer that may simply not have been grounded.
+ * - **A row is a link only with a safe address.** `http:`, `https:` and `mailto:`
+ *   without embedded credentials (`safeSourceUrl`). Any other address is not
+ *   linked and not printed — the row says the address was not linked, so the
+ *   reader knows something was withheld instead of finding a dead title.
+ * - **The host is read from the parsed URL**, never from the title, so a title
+ *   that reads "docs.example.com" cannot make a link to somewhere else look like it.
+ * - **Nothing is merged.** Two entries that share a URL are two rows, with their
+ *   own numbers; the host may have cited two passages and the citations point at
+ *   positions.
+ * - **Hostile and long values are bounded.** Titles, hosts and snippets are
+ *   clipped and stripped of direction overrides (`boundText`), and are only ever
+ *   text nodes.
+ * - **A long list is shown in pages.** Past `initialVisible` the rest is behind a
+ *   button that names how many there are, so a 200-source answer is not 200 rows
+ *   the moment it opens. The button stays in place and toggles, so focus is never
+ *   left on a control that has just disappeared.
+ */
+export type SourcesProps = Omit<TraceProps, 'children'> & {
+  sources: readonly Source[]
+  /** Replaces the default "Used N sources" for another language or a different verb. */
+  label?: string
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Rows shown before the "Show all" button. Default 25. */
+  initialVisible?: number
+}
+
+const DEFAULT_VISIBLE = 25
+
+export function Sources(props: SourcesProps) {
+  const [local, rest] = splitProps(props, [
+    'sources',
+    'label',
+    'open',
+    'defaultOpen',
+    'onOpenChange',
+    'initialVisible',
+  ])
+  const [expanded, setExpanded] = createSignal(false)
+  const limit = () => Math.max(1, Math.floor(local.initialVisible ?? DEFAULT_VISIBLE))
+  const hidden = () => Math.max(0, local.sources.length - limit())
+  const visible = () => (expanded() ? local.sources : local.sources.slice(0, limit()))
+
+  return (
+    <Show when={local.sources.length > 0}>
+      <Trace aria-label="Sources" data-slot="sources" {...rest}>
+        <TraceLine
+          icon={<BookOpen />}
+          title={local.label ?? sourcesLabel(local.sources.length)}
+          open={local.open}
+          defaultOpen={local.defaultOpen}
+          onOpenChange={local.onOpenChange}
+        >
+          <TraceDetail>
+            <ol class="m-0 flex list-none flex-col gap-2 p-0" aria-label="Sources used">
+              <For each={visible()}>
+                {(source, index) => <SourceRow source={source} position={index() + 1} />}
+              </For>
+            </ol>
+            <Show when={hidden() > 0}>
+              <Button
+                type="button"
+                variant="ghost"
+                size="xs"
+                class="mt-1"
+                aria-expanded={expanded()}
+                onClick={() => setExpanded((value) => !value)}
+              >
+                {expanded() ? 'Show fewer sources' : `Show all ${local.sources.length} sources`}
+              </Button>
+            </Show>
+          </TraceDetail>
+        </TraceLine>
+      </Trace>
+    </Show>
+  )
+}
+
+function SourceRow(props: { source: Source; position: number }) {
+  const href = () => safeSourceUrl(props.source.url)
+  const host = () => sourceHost(props.source.url)
+  const title = () => sourceTitle(props.source)
+  const snippet = () =>
+    props.source.snippet ? boundText(props.source.snippet, SOURCE_SNIPPET_LIMIT) : ''
+  // An address was supplied but is not one we link: say so rather than go silent.
+  const withheld = () => props.source.url !== undefined && props.source.url !== '' && !href()
+
+  return (
+    <li data-slot="source" class="flex min-w-0 items-baseline gap-2">
+      <span
+        aria-hidden="true"
+        class="w-5 shrink-0 text-end text-xs text-muted-foreground tabular-nums"
+      >
+        {props.position}
+      </span>
+      <div class="flex min-w-0 flex-1 flex-col gap-0.5">
+        <Show
+          when={href()}
+          fallback={
+            <span class="text-sm text-foreground [overflow-wrap:anywhere]">
+              <span class="visually-hidden">Source {props.position}: </span>
+              {title()}
+            </span>
+          }
+        >
+          {(url) => (
+            <TextLink
+              href={url()}
+              target="_blank"
+              rel="noreferrer noopener"
+              class="w-fit max-w-full text-sm [overflow-wrap:anywhere]"
+            >
+              <span class="visually-hidden">Source {props.position}: </span>
+              {title()}
+              <span class="visually-hidden"> (opens in a new tab)</span>
+            </TextLink>
+          )}
+        </Show>
+        <Show when={host() || withheld()}>
+          <span class="text-xs text-muted-foreground [overflow-wrap:anywhere]">
+            {host()}
+            <Show when={withheld()}>{host() ? ' · ' : ''}Address not linked</Show>
+          </span>
+        </Show>
+        <Show when={snippet()}>
+          <p class="m-0 line-clamp-3 text-xs text-muted-foreground [overflow-wrap:anywhere]">
+            {snippet()}
+          </p>
+        </Show>
+      </div>
+    </li>
+  )
+}

package/dist/r/src/components/composites/stack-trace/index.ts

@@ -0,0 +1,19 @@
+export { StackTrace, STACK_TRACE_MAX_BLOCKS, type StackTraceProps } from './stack-trace'
+export {
+  classifyFrame,
+  dedentLines,
+  describeFrameGroup,
+  frameLocation,
+  groupStackEntries,
+  parseStackTrace,
+  splitLocation,
+  STACK_MAX_LINES,
+  type ParsedStackTrace,
+  type ParseStackTraceOptions,
+  type StackBlock,
+  type StackEntry,
+  type StackFrame,
+  type StackFrameKind,
+  type StackTraceFormat,
+  type StackTraceHeader,
+} from './parse-stack-trace'