@workerdeck/ui 0.15.0 → 0.17.0

package/src/components/terminal/markdown.tsx

@@ -0,0 +1,191 @@
+import { memo, type ReactNode } from 'react'
+import { Streamdown, type Components } from 'streamdown'
+import { cn } from '../../lib/utils.ts'
+import { CopyAction, WithActions } from './affordances.tsx'
+import { Band } from './row.tsx'
+
+/**
+ * Markdown on the character grid.
+ *
+ * The `lines` variant did this by letting the renderer draw its prose defaults
+ * and then overriding roughly sixty declarations back off with `!important` —
+ * every margin, every list gap, the fenced-code card's four nested boxes, the
+ * table's frame and its floating button pill. That is a losing position by
+ * construction: each renderer upgrade is a new set of boxes to find and unpaint,
+ * and the CSS says what the output must *not* look like rather than what it is.
+ *
+ * So this maps the elements instead. Streamdown keeps what only it can do —
+ * streaming-safe parsing of half-written markdown — and every block it emits is
+ * built from the same {@link Row}/{@link Band} primitives the rest of the theme
+ * uses. There is no `!important` here and there is no CSS fighting anything.
+ *
+ * The rendering rules are a terminal's, not a document's:
+ *
+ * - **One type size.** Headings are weight and colour; a bigger glyph would
+ *   break the only line height the grid has.
+ * - **Markers are cells.** A bullet is `- ` (two columns), an ordered marker
+ *   `1. ` (three), and the text starts on the next column exactly as it does in
+ *   the markdown source — so a wrapped line hangs under the text, not the
+ *   bullet, and nesting costs one marker width per level.
+ * - **Code is a band, not a card.** No frame, no language strip, no floating
+ *   buttons: a fenced block is a wash of dim text running to the screen edge,
+ *   which is what a terminal shows.
+ */
+
+/** Pull the text out of a fenced block's React children (`<code>…</code>`). */
+function codeText(node: ReactNode): string {
+  if (node === null || node === undefined || typeof node === 'boolean') return ''
+  if (typeof node === 'string' || typeof node === 'number') return String(node)
+  if (Array.isArray(node)) return node.map(codeText).join('')
+  const element = node as { props?: { children?: ReactNode } }
+  return element.props ? codeText(element.props.children) : ''
+}
+
+/** The language a fence declared, from the `language-*` class react-markdown
+ * puts on the inner `<code>`. Kept as a data attribute rather than used to
+ * highlight: the CLI does not colour a fenced block inside a message, and a
+ * second highlighter here would be a second theme to keep in sync. */
+function fenceLanguage(node: ReactNode): string | undefined {
+  const child = Array.isArray(node) ? node.find(Boolean) : node
+  const className = (child as { props?: { className?: string } } | undefined)?.props?.className
+  const match = /language-([\w-]+)/.exec(className ?? '')
+  return match?.[1]
+}
+
+/**
+ * A fenced block: a band of dim text, and the one place a copy affordance earns
+ * its keep most — a command in a message is there to be run.
+ *
+ * The renderer's own copy/download buttons are turned off (`controls={false}`)
+ * in favour of this: they are web buttons floating over the content in another
+ * application's idiom, and they are not switchable by the surface the way
+ * everything else here is.
+ */
+function CodeBand({ code, language }: { code: string; language?: string }) {
+  return (
+    <WithActions className='term-block' actions={<CopyAction text={code} label='Copy code' />}>
+      <Band className='term-code' data-language={language}>
+        <pre className='term-pre'>{code}</pre>
+      </Band>
+    </WithActions>
+  )
+}
+
+/** Headings differ only in tone — a terminal has one type size, so `h1` and `h4`
+ * cannot differ in anything else. Return-typed so the parameter picks up the
+ * renderer's own component signature rather than a narrower hand-written one. */
+const heading = (tone: 'bright' | 'fg'): Components['h1'] =>
+  function Heading({ children }) {
+    return (
+      <div className='term-block' data-tone={tone} data-weight='bold'>
+        {children}
+      </div>
+    )
+  }
+
+const TERMINAL_COMPONENTS: Components = {
+  p: ({ children }) => <div className='term-block'>{children}</div>,
+
+  h1: heading('bright'),
+  h2: heading('bright'),
+  h3: heading('bright'),
+  h4: heading('fg'),
+  h5: heading('fg'),
+  h6: heading('fg'),
+
+  // `term-block` on every block-level output, without exception: it is what the
+  // one-blank-line-between-blocks rule keys on, and a block that forgets it butts
+  // straight up against its neighbour (a list running into the paragraph after
+  // it, which is exactly how this was found).
+  ul: ({ children }) => <ul className='term-block term-list'>{children}</ul>,
+  ol: ({ children }) => <ol className='term-block term-list term-list-ordered'>{children}</ol>,
+  // The marker is the gutter's `::before` (a CSS counter for the ordered case),
+  // so a list item is literally a Row: same two columns, same hanging indent,
+  // and a nested list inside the body indents by exactly one marker width.
+  li: ({ children }) => (
+    <li className='term-row term-li'>
+      <span className='term-gutter' aria-hidden />
+      <div className='term-body'>{children}</div>
+    </li>
+  ),
+
+  blockquote: ({ children }) => (
+    <blockquote className='term-block term-quote' data-tone='dim'>
+      {children}
+    </blockquote>
+  ),
+
+  hr: () => <div className='term-block term-rule' aria-hidden />,
+
+  // Fenced code. `pre` owns the whole block — the inner `<code>` is only where
+  // the text and the language live — so the band is built here and `code` never
+  // sees a fence.
+  pre: ({ children }) => <CodeBand code={codeText(children)} language={fenceLanguage(children)} />,
+  code: ({ children }) => (
+    <code className='term-inline-code' data-tone='blue'>
+      {children}
+    </code>
+  ),
+
+  strong: ({ children }) => (
+    <strong data-tone='bright' data-weight='bold'>
+      {children}
+    </strong>
+  ),
+  em: ({ children }) => <em className='term-em'>{children}</em>,
+  a: ({ children, href }) => (
+    <a className='term-link' data-tone='blue' href={href} target='_blank' rel='noreferrer'>
+      {children}
+    </a>
+  ),
+
+  // Tables keep the grid by being a grid: monospace cells, one line per row, and
+  // dim box-drawing rules instead of borders that would land between cells.
+  table: ({ children }) => (
+    <div className='term-block term-table-wrap'>
+      <table className='term-table'>{children}</table>
+    </div>
+  ),
+  // Every table element, and not just the ones that looked wrong: any element
+  // left unmapped keeps the renderer's own padded, bordered default, and a
+  // single one of those puts its rows off the line grid (`td`'s `py-2` was
+  // making table rows 23px in an 18px theme).
+  thead: ({ children }) => <thead className='term-thead'>{children}</thead>,
+  tbody: ({ children }) => <tbody>{children}</tbody>,
+  tr: ({ children }) => <tr>{children}</tr>,
+  th: ({ children }) => (
+    <th data-tone='bright' data-weight='bold'>
+      {children}
+    </th>
+  ),
+  td: ({ children }) => <td>{children}</td>,
+}
+
+export interface TerminalMarkdownProps {
+  children: string
+  /** Streaming text: tolerate half-written markdown (unclosed fences, half links). */
+  streaming?: boolean
+  className?: string
+}
+
+export const TerminalMarkdown = memo(
+  function TerminalMarkdown({ children, streaming, className }: TerminalMarkdownProps) {
+    return (
+      <Streamdown
+        mode={streaming ? 'streaming' : 'static'}
+        parseIncompleteMarkdown={streaming}
+        // The renderer's copy/download affordances are web buttons floating over
+        // the content. A terminal has none, and the transcript's own selection
+        // is how you copy from one.
+        controls={false}
+        components={TERMINAL_COMPONENTS}
+        className={cn('term-md', className)}>
+        {children}
+      </Streamdown>
+    )
+  },
+  (prev, next) =>
+    prev.children === next.children &&
+    prev.streaming === next.streaming &&
+    prev.className === next.className,
+)

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 }