@workerdeck/ui 0.15.0 → 0.17.0

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

@@ -0,0 +1,86 @@
+/**
+ * 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
+  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
+  }
+
+  // `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)
+    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

@@ -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}
+    />
+  )
+}