@workerdeck/ui 0.13.0 → 0.16.0

package/src/components/terminal/press.tsx

@@ -0,0 +1,120 @@
+import { useEffect, useRef, type ReactNode } from 'react'
+import { cn } from '../../lib/utils.ts'
+
+/**
+ * A row you can open, that you can also select text out of.
+ *
+ * A `<button>` cannot be both: text inside one is selectable in principle, but
+ * the drag that selects it ends in a `click`, so releasing the mouse collapses
+ * the very block you were highlighting — and the selection is discarded with it.
+ * A transcript is *read* far more often than it is opened, so copying a command
+ * out of a row has to win over the affordance that expands it.
+ *
+ * So: a `div` with the button role and the keyboard behaviour restored by hand,
+ * and a press that is refused when the pointer travelled (a drag, not a click)
+ * or when a selection is standing. Both checks are cheap and neither is a
+ * heuristic about intent — a pointer that moved four pixels was dragging, and a
+ * non-collapsed selection *is* the user having selected something.
+ */
+const DRAG_SLOP = 4
+
+export function Pressable({
+  onPress,
+  expanded,
+  className,
+  children,
+}: {
+  onPress: () => void
+  /** Mirrored to `aria-expanded` when this press opens something. */
+  expanded?: boolean
+  className?: string
+  children: ReactNode
+}) {
+  const origin = useRef<{ x: number; y: number } | null>(null)
+  return (
+    <div
+      role='button'
+      tabIndex={0}
+      aria-expanded={expanded}
+      className={cn('term-press', className)}
+      onPointerDown={(event) => {
+        origin.current = { x: event.clientX, y: event.clientY }
+      }}
+      onClick={(event) => {
+        const from = origin.current
+        origin.current = null
+        if (from && Math.abs(event.clientX - from.x) + Math.abs(event.clientY - from.y) > DRAG_SLOP)
+          return
+        // A click that merely *ends* a selection elsewhere on the page still
+        // reads as a click; one that ends a selection inside this row is the
+        // tail of a drag the slop check may have missed (a slow, short drag).
+        const selection = window.getSelection?.()
+        if (selection && !selection.isCollapsed && selection.containsNode(event.currentTarget, true))
+          return
+        onPress()
+      }}
+      onKeyDown={(event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') return
+        event.preventDefault()
+        onPress()
+      }}>
+      {children}
+    </div>
+  )
+}
+
+/**
+ * Keep an expanding block's *first* line reachable.
+ *
+ * A row that grows from one line to eighty pushes its own top off the screen:
+ * the reader presses a summary and lands somewhere in the middle of what they
+ * opened, with no clue that the beginning is above them. The fix is not a
+ * scroll-into-view on every expand — that would yank a block already fully in
+ * view — but the narrow one: if the block now starts above the fold, bring its
+ * first line back to the top edge.
+ *
+ * Deliberately one-directional and only on the open transition. Collapsing needs
+ * nothing (the block shrinks toward its own top, which is already on screen),
+ * and a block whose top is already visible must not move at all.
+ */
+export function useRevealOnOpen(open: boolean) {
+  const ref = useRef<HTMLDivElement>(null)
+  const previous = useRef(open)
+  useEffect(() => {
+    const opened = open && !previous.current
+    previous.current = open
+    if (!opened) return
+    const element = ref.current
+    if (!element) return
+    // After paint: the rows this block just grew by have to be laid out, and
+    // the virtualizer's own size-change correction has to have run, before an
+    // offset read here means anything.
+    const frame = requestAnimationFrame(() => {
+      const scroller = scrollParent(element)
+      if (!scroller) return
+      const top =
+        element.getBoundingClientRect().top -
+        scroller.getBoundingClientRect().top +
+        scroller.scrollTop
+      if (top >= scroller.scrollTop) return
+      // One line of air above it, so the first row isn't flush against the
+      // scroller's edge — the same blank line every block gets.
+      const line = Number.parseFloat(getComputedStyle(element).lineHeight) || 0
+      scroller.scrollTop = Math.max(0, top - line)
+    })
+    return () => cancelAnimationFrame(frame)
+  }, [open])
+  return ref
+}
+
+/** The nearest ancestor that actually scrolls. */
+function scrollParent(from: HTMLElement): HTMLElement | null {
+  let node = from.parentElement
+  while (node) {
+    const overflow = getComputedStyle(node).overflowY
+    if ((overflow === 'auto' || overflow === 'scroll') && node.scrollHeight > node.clientHeight)
+      return node
+    node = node.parentElement
+  }
+  return null
+}

package/src/components/terminal/prompt.tsx

@@ -0,0 +1,343 @@
+import { useEffect, useRef, type ReactNode } from 'react'
+import { cn } from '../../lib/utils.ts'
+import { Blank, Ink, Row } from './row.tsx'
+
+/**
+ * The parts a terminal prompt is built from.
+ *
+ * An approval and a question are the two places the transcript stops being a log
+ * and becomes a form, and "no boxes" has to be paid for by something. In the CLI
+ * it is paid for three ways, and all three are here: a **rule** marks where the
+ * run stops and the decision starts, the options are **numbered** so a key press
+ * is an answer, and a **hint line** says which keys. That is what makes a prompt
+ * answerable without reaching for the mouse — which is the whole reason a
+ * terminal UI can be faster than a dialog.
+ *
+ * Everything stays on the grid: the rules are one line tall with the stroke
+ * drawn through the middle by a background (a border would cost layout), and the
+ * roving `❯` lives in the same gutter cell every other row uses.
+ */
+
+/**
+ * The boundary above a prompt. Solid separates the run from the decision; dashed
+ * separates parts *within* it (the CLI puts one between a diff and its question),
+ * which is why there are two weights and not one.
+ */
+export function Rule({ dashed }: { dashed?: boolean }) {
+  return <div className={cn('term-rule-row', dashed && 'term-rule-dashed')} aria-hidden />
+}
+
+/** The dim `·`-separated key legend under a prompt. */
+export function Hint({ children }: { children: ReactNode }) {
+  return (
+    <Row tone='faint'>
+      {children}
+    </Row>
+  )
+}
+
+/**
+ * A framed payload — a preview, a snippet. The frame is drawn with four
+ * background gradients rather than a border, so it costs no layout: a 1px border
+ * would push its contents a pixel off the column every other row sits on.
+ */
+export function Box({ children, className }: { children: ReactNode; className?: string }) {
+  return <div className={cn('term-box', className)}>{children}</div>
+}
+
+/**
+ * The prompt's heading: what is being asked, and about what.
+ *
+ * Two lines because the engine gives two — `displayName` ("Edit file") is the
+ * action, and the subject (the path) is the thing it acts on. The CLI shows them
+ * exactly this way, and it is the one place in the theme where colour is used
+ * for emphasis rather than for state.
+ */
+export function PromptTitle({ title, subject }: { title: string; subject?: string }) {
+  return (
+    <>
+      <Row tone='blue' bold>
+        {title}
+      </Row>
+      {subject ? <Row tone='dim'>{subject}</Row> : null}
+    </>
+  )
+}
+
+export type Choice = {
+  key: string
+  label: string
+  /** Rendered dim on its own row under the label, as the CLI does for a
+   * multi-select's options — never appended to the label, which would make the
+   * row wrap and cost the list its scannability. */
+  description?: string
+  /**
+   * Present → the row carries selection state and draws it. `marker` says in
+   * which idiom: `[x]` for a multi-select, `(•)` for a one-of. Absent → the row
+   * is an action (Allow, Cancel), which has no state to show.
+   */
+  checked?: boolean
+  marker?: 'check' | 'radio'
+  /**
+   * Chosen, in a list that draws no markers (a one-of). The colour is the whole
+   * signal there: without it, tabbing back to an answered question would show no
+   * trace of the answer given.
+   */
+  selected?: boolean
+  danger?: boolean
+  /** Rendered under the row, outside the button — a preview, a text field. The
+   * caller decides when it exists (focused, checked); a button may not hold one. */
+  detail?: ReactNode
+}
+
+/** The two-state glyph pairs, in the forms a terminal would use. */
+const MARKERS = {
+  check: ['[ ]', '[✓]'],
+  radio: ['( )', '(•)'],
+} as const
+
+export interface ChoicesProps {
+  options: Choice[]
+  /** Roving index: the one row that is tab-reachable and wears the `❯`. */
+  focused: number
+  onFocus: (index: number) => void
+  onChoose: (index: number) => void
+  /**
+   * Own the DOM focus, moving it with the roving index. False while something
+   * else inside the prompt holds it (a text field, another question's list) —
+   * two lists both chasing `focused` would tear the caret back and forth.
+   */
+  active?: boolean
+  /**
+   * Take the keyboard when the list first appears. True by default — a prompt
+   * whose whole affordance is "press 1" is useless if the keys go somewhere
+   * else, and the CLI hands the keyboard over the moment it asks.
+   *
+   * It is a *first mount* decision only, and it declines when the reader is
+   * already typing (see {@link isTyping}): an approval landing mid-sentence must
+   * not pull the caret out of the composer and scatter the rest of the sentence
+   * across an option list.
+   */
+  autoFocus?: boolean
+  label: string
+}
+
+/** Is the reader mid-keystroke somewhere that keeps its own caret? */
+function isTyping(element: Element | null): boolean {
+  if (!(element instanceof HTMLElement)) return false
+  const editable =
+    element.tagName === 'INPUT' || element.tagName === 'TEXTAREA' || element.isContentEditable
+  if (!editable) return false
+  // Focus in a field is not the same as a message in progress, and only the
+  // second is worth protecting. This used to return true for any focused
+  // editable, which read fine until a host that keeps the composer focused at
+  // all times ran it: VS Code puts the caret in the composer when a session is
+  // shown and again on any click in dead space, so the field was *always* the
+  // active element and the prompt therefore *never* took the keyboard. The
+  // approval that has to be answered was the one thing you could not answer
+  // without reaching for the mouse.
+  //
+  // An empty field has nothing to lose, so the takeover proceeds; a half-typed
+  // message still wins, which is the case the guard was written for.
+  const text =
+    element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement
+      ? element.value
+      : (element.textContent ?? '')
+  return text.trim().length > 0
+}
+
+/**
+ * A keyboard-first list of choices, as rows: `↑`/`↓` move, `1`–`9` pick
+ * directly, `Enter`/`Space` take the focused one (the button does that itself).
+ *
+ * The number is part of the gutter, not the label, so every option's text starts
+ * on the same column and the list reads as a column of answers rather than a
+ * ragged paragraph.
+ */
+export function Choices({
+  options,
+  focused,
+  onFocus,
+  onChoose,
+  active = true,
+  autoFocus = true,
+  label,
+}: ChoicesProps) {
+  const refs = useRef<Array<HTMLButtonElement | null>>([])
+
+  useEffect(() => {
+    if (!active) return
+    // Two different jobs, told apart by where the keyboard already is rather
+    // than by how many times this has run.
+    //
+    // If focus is already on one of these rows, the roving cursor is moving and
+    // the DOM must follow `focused` unconditionally — otherwise the `❯` and the
+    // real caret drift apart. If it is not, this is the initial takeover, which
+    // is refusable so it cannot snatch a half-written message.
+    //
+    // This used to be a `mounted` ref: refuse on the first pass, follow on
+    // every pass after. That is not safe under StrictMode, which mounts,
+    // unmounts and remounts in development — the ref survives the simulated
+    // remount, so the second pass saw `mounted === true`, skipped the guard
+    // entirely and stole focus from whatever you were typing. It read as
+    // correct in production and wrong in dev, which is the worst way round.
+    const focusIsInList = refs.current.some(
+      (row) => row !== null && row === document.activeElement,
+    )
+    if (!focusIsInList && (!autoFocus || isTyping(document.activeElement))) return
+    refs.current[focused]?.focus()
+  }, [active, focused, autoFocus])
+
+  const move = (delta: number) => {
+    if (options.length > 0) onFocus((focused + delta + options.length) % options.length)
+  }
+
+  return (
+    <div
+      role='group'
+      aria-label={label}
+      onKeyDown={(event) => {
+        if (event.key === 'ArrowDown') {
+          move(1)
+          event.preventDefault()
+          return
+        }
+        if (event.key === 'ArrowUp') {
+          move(-1)
+          event.preventDefault()
+          return
+        }
+        // Digits are the whole point of numbering the rows — but only as far as
+        // the rows that exist, so `9` on a three-option prompt stays a no-op
+        // rather than a silent miss.
+        const digit = Number(event.key)
+        if (Number.isInteger(digit) && digit >= 1 && digit <= Math.min(options.length, 9)) {
+          onFocus(digit - 1)
+          onChoose(digit - 1)
+          event.preventDefault()
+        }
+      }}>
+      {options.map((option, index) => {
+        const isFocused = index === focused
+        return (
+          <div key={option.key}>
+            <button
+              ref={(element) => {
+                refs.current[index] = element
+              }}
+              type='button'
+              tabIndex={isFocused ? 0 : -1}
+              aria-pressed={option.checked}
+              onFocus={() => onFocus(index)}
+              onClick={() => onChoose(index)}
+              className='term-press'>
+              {/* `❯ 1.` is the gutter: marker and number together, so the label
+                  starts on one column whether or not the row is focused. */}
+              <Row
+                columns={5}
+                glyph={`${isFocused ? '❯' : ' '} ${index + 1}.`}
+                glyphTone={isFocused ? 'fg' : 'faint'}
+                tone={option.danger ? 'red' : option.selected ? 'green' : 'fg'}
+                data-focused={isFocused ? '' : undefined}>
+                {option.checked !== undefined ? (
+                  <Ink tone={option.checked ? 'green' : 'faint'}>
+                    {MARKERS[option.marker ?? 'check'][option.checked ? 1 : 0]}{' '}
+                  </Ink>
+                ) : null}
+                <Ink bold={isFocused || option.selected}>{option.label}</Ink>
+              </Row>
+            </button>
+            {option.description ? (
+              <Row columns={5} tone='dim'>
+                {option.description}
+              </Row>
+            ) : null}
+            {option.detail ? <div className='term-detail'>{option.detail}</div> : null}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+/**
+ * A single-line text field in the terminal idiom: a caret and a rule, no box.
+ * `Enter` commits, `Escape` backs out — the caller says what those mean.
+ */
+export function PromptInput({
+  value,
+  onChange,
+  onSubmit,
+  onCancel,
+  placeholder,
+}: {
+  value: string
+  onChange: (value: string) => void
+  onSubmit: () => void
+  onCancel: () => void
+  placeholder?: string
+}) {
+  return (
+    <Row columns={5} glyph='   ›' glyphTone='dim'>
+      <input
+        autoFocus
+        value={value}
+        placeholder={placeholder}
+        onChange={(event) => onChange(event.target.value)}
+        onKeyDown={(event) => {
+          if (event.key === 'Enter') {
+            event.preventDefault()
+            onSubmit()
+          }
+          if (event.key === 'Escape') {
+            // The prompt's own Escape means deny/dismiss; inside the field it
+            // only closes the field, so it must not travel further.
+            event.stopPropagation()
+            onCancel()
+          }
+        }}
+        className='term-input'
+      />
+    </Row>
+  )
+}
+
+/**
+ * The question strip: one chip per question plus the submit step, with the
+ * active one filled.
+ *
+ * It exists because the CLI asks **one question at a time**, and a form that
+ * hides two of its three questions has to say so — otherwise answering the first
+ * looks like finishing. The arrows are not controls, they are the legend for
+ * `Tab`/`Shift+Tab`, which is what actually moves between them.
+ */
+export function TabStrip({
+  tabs,
+  active,
+  onSelect,
+}: {
+  /** `glyph` rather than a derived done/not-done mark: the submit step is always
+   * a `✓` (it is the act of finishing, not a thing to answer), and deriving it
+   * would make it a hollow box until every question was done. */
+  tabs: { key: string; label: string; glyph: string }[]
+  active: number
+  onSelect: (index: number) => void
+}) {
+  return (
+    <Row glyph='←' glyphTone='faint'>
+      {tabs.map((tab, index) => (
+        <button
+          key={tab.key}
+          type='button'
+          tabIndex={-1}
+          onClick={() => onSelect(index)}
+          className={cn('term-tab', index === active && 'term-tab-active')}>
+          {tab.glyph} {tab.label}
+        </button>
+      ))}
+      <Ink tone='faint'> →</Ink>
+    </Row>
+  )
+}
+
+export { Blank }

package/src/components/terminal/result-preview.ts

@@ -0,0 +1,72 @@
+/**
+ * How much of a tool result a collapsed row shows, and what it says it hid.
+ *
+ * Its own module, and pure, because **two** consumers must agree on it to the
+ * character: `items.tsx` draws these rows, and `height.ts` predicts their pixel
+ * height for the virtualizer's `estimateSize` without a DOM. The budget used to
+ * be a private constant in `items.tsx` restated as a copy in `height.ts` with a
+ * comment admitting the drift risk — this is that comment's fix.
+ *
+ * **Two budgets, not one.** Lines alone was the old rule and it has an exact
+ * blind spot: a minified JSON reply — which is every MCP tool's reply — is ONE
+ * line, so a four-line slice kept all thirty thousand characters of it and the
+ * row wrapped to a screenful. `hidden` was computed as `lines.length -
+ * shown.length`, so it came out zero and the row did not even offer the "+N"
+ * affordance: the whole blob was simply the transcript now. Characters alone
+ * would be wrong the other way, cutting an ordinary short-line result mid-way
+ * for no reason. So both apply, and a *first* line longer than the budget is
+ * truncated rather than shown whole — a row has to show something or it opens
+ * onto nothing.
+ */
+
+/** At most this many lines, however short they are. */
+const PREVIEW_LINES = 4
+/**
+ * …and at most this many characters, however few lines they are. Four lines'
+ * worth at any realistic terminal width — the row is indented six cells, so a
+ * 100ch panel fits ~94 per line — which keeps the budget honest whether the
+ * result arrives as four lines or as one long one.
+ */
+const PREVIEW_CHARS = 400
+
+export type CollapsedResult = {
+  /** The lines to draw. The last may be truncated (it ends in `…`). */
+  shown: string[]
+  /**
+   * The trailing "there is more" row, already spelled. The *string* rather than
+   * a count, because `height.ts` wraps this exact text to size the row, and two
+   * spellings would be two different heights.
+   */
+  more?: string
+}
+
+/**
+ * Reported in characters when the truncation happened *inside* a line and in
+ * lines otherwise — a one-line JSON blob has no hidden lines to count, and
+ * "+0 lines" under a visibly cut-off row is worse than saying nothing.
+ */
+export function collapsedResult(lines: string[]): CollapsedResult {
+  const shown: string[] = []
+  let chars = 0
+  let cut = false
+
+  for (const line of lines.slice(0, PREVIEW_LINES)) {
+    if (shown.length === 0 && line.length > PREVIEW_CHARS) {
+      shown.push(`${line.slice(0, PREVIEW_CHARS)}…`)
+      chars = PREVIEW_CHARS
+      cut = true
+      break
+    }
+    if (shown.length > 0 && chars + line.length > PREVIEW_CHARS) break
+    shown.push(line)
+    chars += line.length + 1
+  }
+
+  if (cut) {
+    // `join` because the newlines are part of what is not being shown.
+    const hidden = lines.join('\n').length - chars
+    return { shown, more: `… +${hidden.toLocaleString()} chars` }
+  }
+  const hidden = lines.length - shown.length
+  return { shown, more: hidden > 0 ? `… +${hidden} line${hidden === 1 ? '' : 's'}` : undefined }
+}

package/src/components/terminal/row.tsx

@@ -0,0 +1,132 @@
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
+import { cn } from '../../lib/utils.ts'
+
+/**
+ * The primitives every terminal row is built from.
+ *
+ * There are three, and that is the whole vocabulary: a {@link Row} (a gutter
+ * cell and a body cell), a {@link Blank} (one empty line), and a {@link Band} (a
+ * run of rows carrying a full-bleed background). Anything the theme draws — a
+ * message, a tool call, a diff hunk, an approval prompt — is some arrangement of
+ * those, which is what keeps the grid a property of the renderer rather than a
+ * thing each component re-derives.
+ *
+ * Geometry is in `styles/terminal.css`. These components choose a class, a
+ * marker and a tone; they never carry a measurement.
+ */
+
+/** The palette, as a name. See the `[data-tone]` rules in `terminal.css`. */
+export type Tone =
+  | 'fg'
+  | 'bright'
+  | 'dim'
+  | 'faint'
+  | 'mark'
+  | 'blue'
+  | 'green'
+  | 'red'
+  | 'yellow'
+  | 'magenta'
+
+export interface RowProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /**
+   * What sits in the gutter — `●`, `⎿`, `>`, a list bullet, or nothing. Kept to
+   * the width of the gutter (`--term-cell`, two columns by default): a wider
+   * marker would push its own body off the column every other row starts on.
+   * Omitted, the gutter is still drawn as empty space, so an unmarked row's
+   * text lines up with a marked one's.
+   */
+  glyph?: ReactNode
+  /** The marker's colour. Defaults to dim — the marker is structure, not content. */
+  glyphTone?: Tone
+  /** The body's colour. */
+  tone?: Tone
+  bold?: boolean
+  /** Indent levels, one character cell each. A child row's marker then sits
+   * exactly under its parent row's first letter. */
+  indent?: 0 | 1 | 2 | 3
+  /**
+   * Gutter width in columns, when the marker needs other than two — an ordered
+   * list's `10.` is four, a prompt's `❯ 1.` is five, and a framed payload wants
+   * `0`. Changes only this row's split, so the body still starts on a whole
+   * column.
+   */
+  columns?: number
+  children?: ReactNode
+}
+
+export function Row({
+  glyph,
+  glyphTone,
+  tone,
+  bold,
+  indent,
+  columns,
+  className,
+  children,
+  style,
+  ...props
+}: RowProps) {
+  return (
+    <div
+      className={cn('term-row', className)}
+      data-indent={indent ? String(indent) : undefined}
+      data-tone={tone}
+      data-weight={bold ? 'bold' : undefined}
+      // `!== undefined`, not truthiness: `columns={0}` is a real request for a
+      // gutterless row (a framed payload) and must not fall back to the default.
+      style={
+        columns === undefined
+          ? style
+          : ({ ...style, '--term-cell': `${columns}ch` } as CSSProperties)
+      }
+      {...props}>
+      <span className='term-gutter' data-tone={glyphTone} aria-hidden>
+        {glyph ?? ' '}
+      </span>
+      {/* A div, not a span: a body holds block content (a markdown message, a
+          band of output) as often as it holds a line of text. */}
+      <div className='term-body'>{children}</div>
+    </div>
+  )
+}
+
+/**
+ * One empty line — the theme's only vertical spacing.
+ *
+ * A terminal separates blocks with a blank line, not with padding, and saying it
+ * that way has a practical payoff: spacing is part of the row list, so it can be
+ * decided by whoever knows whether two blocks belong together (a tool call and
+ * its output do not get one; two assistant turns do), instead of by a margin
+ * rule that cannot tell them apart.
+ */
+export function Blank() {
+  return <div className='term-blank' aria-hidden />
+}
+
+/**
+ * A run of rows under a background: a code block, a command's output, a diff
+ * hunk. Full-bleed — the wash reaches the scroller's edges, because in a
+ * terminal the line is the full width of the screen. See `--term-bleed` on
+ * {@link TerminalSurface}.
+ */
+export function Band({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cn('term-band', className)} {...props} />
+}
+
+/** Inline colour/weight inside a row's body. */
+export function Ink({
+  tone,
+  bold,
+  className,
+  ...props
+}: HTMLAttributes<HTMLSpanElement> & { tone?: Tone; bold?: boolean }) {
+  return (
+    <span
+      data-tone={tone}
+      data-weight={bold ? 'bold' : undefined}
+      className={className}
+      {...props}
+    />
+  )
+}