@workerdeck/ui 0.23.0 → 1.0.0

package/src/components/terminal/prompt.tsx

@@ -2,64 +2,25 @@ 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>
-  )
+  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>
+      <Row tone="blue" bold>
         {title}
       </Row>
-      {subject ? <Row tone='dim'>{subject}</Row> : null}
+      {subject ? <Row tone="dim">{subject}</Row> : null}
     </>
   )
 }
@@ -67,30 +28,14 @@ export function PromptTitle({ title, subject }: { title: string; subject?: strin
 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: ['( )', '(•)'],
@@ -98,103 +43,49 @@ const MARKERS = {
 
 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 ?? '')
+  if (!(element instanceof HTMLElement)) {
+    return false
+  }
+  const editable = element.tagName === 'INPUT' || element.tagName === 'TEXTAREA' || element.isContentEditable
+  if (!editable) {
+    return false
+  }
+  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) {
+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
+    if (!active) {
+      return
+    }
+    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)
+    if (options.length > 0) {
+      onFocus((focused + delta + options.length) % options.length)
+    }
   }
 
   return (
     <div
-      role='group'
+      role="group"
       aria-label={label}
       onKeyDown={(event) => {
         if (event.key === 'ArrowDown') {
@@ -207,16 +98,14 @@ export function Choices({
           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 (
@@ -225,34 +114,32 @@ export function Choices({
               ref={(element) => {
                 refs.current[index] = element
               }}
-              type='button'
+              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. */}
+              className="term-press"
+            >
               <Row
                 columns={5}
                 glyph={`${isFocused ? '❯' : ' '} ${index + 1}.`}
                 glyphTone={isFocused ? 'fg' : 'faint'}
                 tone={option.danger ? 'red' : option.selected ? 'green' : 'fg'}
-                data-focused={isFocused ? '' : undefined}>
+                data-focused={isFocused ? '' : undefined}
+              >
                 {option.checked !== undefined ? (
-                  <Ink tone={option.checked ? 'green' : 'faint'}>
-                    {MARKERS[option.marker ?? 'check'][option.checked ? 1 : 0]}{' '}
-                  </Ink>
+                  <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'>
+              <Row columns={5} tone="dim">
                 {option.description}
               </Row>
             ) : null}
-            {option.detail ? <div className='term-detail'>{option.detail}</div> : null}
+            {option.detail ? <div className="term-detail">{option.detail}</div> : null}
           </div>
         )
       })}
@@ -260,10 +147,6 @@ export function Choices({
   )
 }
 
-/**
- * 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,
@@ -278,7 +161,7 @@ export function PromptInput({
   placeholder?: string
 }) {
   return (
-    <Row columns={5} glyph='   ›' glyphTone='dim'>
+    <Row columns={5} glyph="   ›" glyphTone="dim">
       <input
         autoFocus
         value={value}
@@ -290,52 +173,39 @@ export function PromptInput({
             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'
+        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'>
+    <Row glyph="←" glyphTone="faint">
       {tabs.map((tab, index) => (
         <button
           key={tab.key}
-          type='button'
+          type="button"
           tabIndex={-1}
           onClick={() => onSelect(index)}
-          className={cn('term-tab', index === active && 'term-tab-active')}>
+          className={cn('term-tab', index === active && 'term-tab-active')}
+        >
           {tab.glyph} {tab.label}
         </button>
       ))}
-      <Ink tone='faint'> →</Ink>
+      <Ink tone="faint"> →</Ink>
     </Row>
   )
 }

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

@@ -1,59 +1,11 @@
-/**
- * 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.
- */
-/**
- * `totalChars` is the **untruncated** length when the replay delivered only a
- * head (protocol's `ToolResultBlock.total_chars`). Passing it is not cosmetic:
- * computed from the head this row would say "… +7,600 chars" where the truth is
- * 641,003, and the wrong string is a *different pixel height* — which is exactly
- * the drift this module exists to prevent, since `height.ts` sizes the row by
- * wrapping this same text. Omitted for a whole result, where the lines are the
- * whole truth.
- */
 export function collapsedResult(lines: string[], totalChars?: number): CollapsedResult {
   const shown: string[] = []
   let chars = 0
@@ -66,21 +18,21 @@ export function collapsedResult(lines: string[], totalChars?: number): Collapsed
       cut = true
       break
     }
-    if (shown.length > 0 && chars + line.length > PREVIEW_CHARS) break
+    if (shown.length > 0 && chars + line.length > PREVIEW_CHARS) {
+      break
+    }
     shown.push(line)
     chars += line.length + 1
   }
 
-  // `join` because the newlines are part of what is not being shown — and
-  // `totalChars` wins when it exists, because the lines in hand are then a head
-  // rather than the result.
   const held = lines.join('\n').length
   const total = totalChars ?? held
-  if (cut) return { shown, more: `… +${(total - chars).toLocaleString()} chars` }
-  // A truncated result always has more, even when its head happened to fit the
-  // line budget: the row must never claim to be showing everything.
-  if (totalChars !== undefined && total > held)
+  if (cut) {
     return { shown, more: `… +${(total - chars).toLocaleString()} chars` }
+  }
+  if (totalChars !== undefined && total > held) {
+    return { shown, more: `… +${(total - chars).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

@@ -1,132 +1,45 @@
 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 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) {
+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>
+      // `!== undefined`, not truthiness: `columns={0}` is a real request for a gutterless row.
+      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 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 />
+  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}
-    />
-  )
+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} />
 }