@workerdeck/ui 0.22.0 → 1.0.0

package/src/components/terminal/markdown.tsx

@@ -4,47 +4,20 @@ 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('')
+  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
@@ -52,39 +25,28 @@ function fenceLanguage(node: ReactNode): string | undefined {
   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>
+    <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 }) {
+function heading(tone: 'bright' | 'fg'): Components['h1'] {
+  return function Heading({ children }) {
     return (
-      <div className='term-block' data-tone={tone} data-weight='bold'>
+      <div className="term-block" data-tone={tone} data-weight="bold">
         {children}
       </div>
     )
   }
+}
 
 const TERMINAL_COMPONENTS: Components = {
-  p: ({ children }) => <div className='term-block'>{children}</div>,
+  p: ({ children }) => <div className="term-block">{children}</div>,
 
   h1: heading('bright'),
   h2: heading('bright'),
@@ -93,68 +55,53 @@ const TERMINAL_COMPONENTS: Components = {
   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.
+  ul: ({ children }) => <ul className="term-block term-list">{children}</ul>,
+  ol: ({ children }) => <ol className="term-block term-list term-list-ordered">{children}</ol>,
   li: ({ children }) => (
-    <li className='term-row term-li'>
-      <span className='term-gutter' aria-hidden />
-      <div className='term-body'>{children}</div>
+    <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'>
+    <blockquote className="term-block term-quote" data-tone="dim">
       {children}
     </blockquote>
   ),
 
-  hr: () => <div className='term-block term-rule' aria-hidden />,
+  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'>
+    <code className="term-inline-code" data-tone="blue">
       {children}
     </code>
   ),
 
   strong: ({ children }) => (
-    <strong data-tone='bright' data-weight='bold'>
+    <strong data-tone="bright" data-weight="bold">
       {children}
     </strong>
   ),
-  em: ({ children }) => <em className='term-em'>{children}</em>,
+  em: ({ children }) => <em className="term-em">{children}</em>,
   a: ({ children, href }) => (
-    <a className='term-link' data-tone='blue' href={href} target='_blank' rel='noreferrer'>
+    <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 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>,
+  // Every table element must be mapped: an unmapped `td` keeps its `py-2` and puts rows off the line grid (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'>
+    <th data-tone="bright" data-weight="bold">
       {children}
     </th>
   ),
@@ -163,7 +110,6 @@ const TERMINAL_COMPONENTS: Components = {
 
 export interface TerminalMarkdownProps {
   children: string
-  /** Streaming text: tolerate half-written markdown (unclosed fences, half links). */
   streaming?: boolean
   className?: string
 }
@@ -174,18 +120,13 @@ export const TerminalMarkdown = memo(
       <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)}>
+        className={cn('term-md', className)}
+      >
         {children}
       </Streamdown>
     )
   },
-  (prev, next) =>
-    prev.children === next.children &&
-    prev.streaming === next.streaming &&
-    prev.className === next.className,
+  (prev, next) => prev.children === next.children && prev.streaming === next.streaming && prev.className === next.className,
 )

package/src/components/terminal/press.tsx

@@ -1,21 +1,6 @@
 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({
@@ -25,7 +10,6 @@ export function Pressable({
   children,
 }: {
   onPress: () => void
-  /** Mirrored to `aria-expanded` when this press opens something. */
   expanded?: boolean
   className?: string
   children: ReactNode
@@ -33,7 +17,7 @@ export function Pressable({
   const origin = useRef<{ x: number; y: number } | null>(null)
   return (
     <div
-      role='button'
+      role="button"
       tabIndex={0}
       aria-expanded={expanded}
       className={cn('term-press', className)}
@@ -43,62 +27,51 @@ export function Pressable({
       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)
+        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))
+        if (selection && !selection.isCollapsed && selection.containsNode(event.currentTarget, true)) {
           return
+        }
         onPress()
       }}
       onKeyDown={(event) => {
-        if (event.key !== 'Enter' && event.key !== ' ') return
+        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
+    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.
+    if (!element) {
+      return
+    }
+    // After paint: the new rows must be laid out and the virtualizer's size-change correction run before an offset read 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.
+      if (!scroller) {
+        return
+      }
+      const top = element.getBoundingClientRect().top - scroller.getBoundingClientRect().top + scroller.scrollTop
+      if (top >= scroller.scrollTop) {
+        return
+      }
       const line = Number.parseFloat(getComputedStyle(element).lineHeight) || 0
       scroller.scrollTop = Math.max(0, top - line)
     })
@@ -107,13 +80,13 @@ export function useRevealOnOpen(open: boolean) {
   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)
+    if ((overflow === 'auto' || overflow === 'scroll') && node.scrollHeight > node.clientHeight) {
       return node
+    }
     node = node.parentElement
   }
   return null