herm-tui 1.0.0-dev.1

package/src/ui/command.tsx

@@ -0,0 +1,104 @@
+/**
+ * Command palette — registry of named commands, each optionally bound
+ * to a catalog ActionId. The palette (palette.open) is just one way to
+ * reach them; any command with an `action` also fires when that chord
+ * is pressed, so the registry doubles as the dispatch table for global
+ * actions that don't need useAppKeys' composer/renderer state.
+ *
+ *   const cmd = useCommand()
+ *   useEffect(() => cmd.register([
+ *     { title: "Help", value: "help", action: "help.open", onSelect: ... },
+ *   ]), [])
+ */
+
+import { createContext, useContext, useState, useCallback, useRef, useMemo } from "react"
+import type { ReactNode } from "react"
+import { useKeyboard } from "@opentui/react"
+import { useKeys, type ActionId } from "../keys"
+import { useDialog } from "./dialog"
+import { DialogSelect, type SelectOption } from "./dialog-select"
+
+type Command = {
+  readonly title: string
+  readonly value: string
+  readonly action?: ActionId
+  readonly description?: string
+  readonly category?: string
+  readonly onSelect: () => void
+}
+
+type CommandContext = {
+  readonly register: (cmds: ReadonlyArray<Command>) => () => void
+  readonly setEnabled: (val: boolean) => void
+}
+
+const Ctx = createContext<CommandContext | null>(null)
+
+export const CommandProvider = ({ children }: { children: ReactNode }) => {
+  const registry = useRef<Map<string, ReadonlyArray<Command>>>(new Map())
+  const [, setRevision] = useState(0)
+  const enabled = useRef(true)
+  const dialog = useDialog()
+  const keys = useKeys()
+
+  const all = useCallback((): Command[] => {
+    const result: Command[] = []
+    registry.current.forEach(cmds => cmds.forEach(c => result.push(c)))
+    return result
+  }, [])
+
+  const register = useCallback((cmds: ReadonlyArray<Command>) => {
+    const id = String(Date.now()) + Math.random()
+    registry.current.set(id, cmds)
+    setRevision(r => r + 1)
+    return () => {
+      registry.current.delete(id)
+      setRevision(r => r + 1)
+    }
+  }, [])
+
+  const setEnabled = useCallback((val: boolean) => {
+    enabled.current = val
+  }, [])
+
+  const open = useCallback(() => {
+    const cmds = all()
+    const options: SelectOption[] = cmds.map(c => ({
+      title: c.title,
+      value: c.value,
+      description: c.description,
+      hint: c.action ? keys.print(c.action) : undefined,
+      category: c.category,
+    }))
+    dialog.replace(
+      <DialogSelect
+        title="Command Palette"
+        options={options}
+        onSelect={(opt) => {
+          dialog.clear()
+          const found = cmds.find(c => c.value === opt.value)
+          if (found) found.onSelect()
+        }}
+        placeholder="Search commands..."
+      />
+    )
+  }, [all, dialog, keys])
+
+  useKeyboard((key) => {
+    if (!enabled.current || dialog.stack.length > 0) return
+    if (keys.match("palette.open", key)) return open()
+    for (const c of all()) {
+      if (c.action && keys.match(c.action, key)) return c.onSelect()
+    }
+  })
+
+  const value = useMemo<CommandContext>(() => ({ register, setEnabled }), [register, setEnabled])
+
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>
+}
+
+export const useCommand = (): CommandContext => {
+  const ctx = useContext(Ctx)
+  if (!ctx) throw new Error("useCommand() must be inside <CommandProvider>")
+  return ctx
+}

package/src/ui/dialog-select.tsx

@@ -0,0 +1,164 @@
+/**
+ * Filterable select dialog — reusable pick-list for dialogs.
+ *
+ * Keyboard: up/down navigate, enter selects, typing filters.
+ * Mouse: hover highlights, click selects.
+ * Grouped by category with headers.
+ */
+
+import { useState, useMemo, useEffect, useRef } from "react"
+import type { ReactNode } from "react"
+import { useKeyboard } from "@opentui/react"
+import type { ParsedKey, ScrollBoxRenderable } from "@opentui/core"
+import { useTheme } from "../theme"
+
+export type SelectOption = {
+  readonly title: string
+  readonly value: string
+  readonly description?: string
+  readonly hint?: string
+  readonly category?: string
+}
+
+type Props = {
+  readonly title: string
+  readonly options: ReadonlyArray<SelectOption>
+  readonly onSelect: (option: SelectOption) => void
+  readonly onMove?: (option: SelectOption) => void
+  /** Printable-key interceptor — return true to consume (skip filter append). */
+  readonly onKey?: (key: ParsedKey) => boolean
+  readonly placeholder?: string
+  readonly current?: string
+  readonly footer?: ReactNode
+}
+
+export const DialogSelect = (props: Props) => {
+  const [filter, setFilter] = useState("")
+  const [cursor, setCursor] = useState(0)
+  const sb = useRef<ScrollBoxRenderable | null>(null)
+  const theme = useTheme().theme
+
+  const filtered = useMemo(() => {
+    const lower = filter.toLowerCase()
+    return props.options.filter(o =>
+      o.title.toLowerCase().includes(lower) ||
+      (o.description ?? "").toLowerCase().includes(lower)
+    )
+  }, [filter, props.options])
+
+  // Group by category
+  const groups = useMemo(() => {
+    const map = new Map<string, SelectOption[]>()
+    filtered.forEach(o => {
+      const cat = o.category ?? ""
+      const arr = map.get(cat) ?? []
+      arr.push(o)
+      map.set(cat, arr)
+    })
+    return map
+  }, [filtered])
+
+  // Clamp cursor
+  useEffect(() => {
+    if (cursor >= filtered.length) setCursor(Math.max(0, filtered.length - 1))
+  }, [filtered.length, cursor])
+
+  const rowId = (i: number) => `ds-row-${i}`
+
+  const move = (n: number) => setCursor(c => {
+    const next = Math.max(0, Math.min(filtered.length - 1, c + n))
+    sb.current?.scrollChildIntoView(rowId(next))
+    return next
+  })
+
+  // Notify on move
+  useEffect(() => {
+    const item = filtered[cursor]
+    if (item && props.onMove) props.onMove(item)
+  }, [cursor, filtered, props.onMove])
+
+  useKeyboard((key) => {
+    if (key.name === "up") return move(-1)
+    if (key.name === "down") return move(1)
+    if (key.name === "pageup") return move(-10)
+    if (key.name === "pagedown") return move(10)
+    if (key.name === "return") {
+      const item = filtered[cursor]
+      if (item) props.onSelect(item)
+      return
+    }
+    if (props.onKey?.(key)) return
+  })
+
+  // Build flat list with index tracking
+  let idx = 0
+  const entries = Array.from(groups.entries())
+
+  return (
+    <box flexDirection="column" width={60}>
+      <text fg={theme.text}>
+        <strong>{props.title}</strong>
+      </text>
+      <box height={1} />
+      <input
+        value={filter}
+        onInput={setFilter}
+        placeholder={props.placeholder ?? "Type to filter..."}
+        focused={true}
+        textColor={theme.text}
+        placeholderColor={theme.textMuted}
+        backgroundColor={theme.backgroundElement}
+        focusedBackgroundColor={theme.backgroundElement}
+      />
+      <box height={1} />
+      {/* ScrollBox root is flex-row ([wrapper, v-scrollbar]); column stacking
+          belongs on the content box, not here. */}
+      <scrollbox ref={sb} scrollY maxHeight={16}
+        contentOptions={{ flexDirection: "column" }} paddingRight={1}>
+        {filtered.length === 0 ? (
+          <text fg={theme.textMuted}>{"No results found"}</text>
+        ) : null}
+        {entries.map(([cat, items]) => {
+          const elements: React.ReactNode[] = []
+          if (cat) {
+            elements.push(
+              <text key={`cat-${cat}`} fg={theme.textMuted}>
+                <strong>{cat}</strong>
+              </text>
+            )
+          }
+          items.forEach(item => {
+            const i = idx++
+            const active = i === cursor
+            const current = item.value === props.current
+            elements.push(
+              <box
+                key={item.value}
+                id={rowId(i)}
+                flexDirection="row"
+                backgroundColor={active ? theme.backgroundElement : undefined}
+                onMouseMove={() => setCursor(i)}
+                onMouseDown={() => props.onSelect(item)}
+                paddingLeft={1}
+                paddingRight={1}
+              >
+                <box flexGrow={1} height={1} overflow="hidden">
+                  <text fg={active ? theme.text : theme.textMuted}>
+                    {current ? "● " : "  "}{item.title}{item.description ? ` — ${item.description}` : ""}
+                  </text>
+                </box>
+                {item.hint ? (
+                  <box flexShrink={0} height={1}>
+                    <text fg={theme.textMuted}>{item.hint}</text>
+                  </box>
+                ) : null}
+              </box>
+            )
+          })
+          return elements
+        }).flat()}
+      </scrollbox>
+      {props.footer != null ? <box paddingTop={1}>{props.footer}</box> : null}
+    </box>
+  )
+}

package/src/ui/dialog.tsx

@@ -0,0 +1,102 @@
+/**
+ * Dialog overlay system — modal stack with backdrop.
+ *
+ * Usage:
+ *   <DialogProvider><App /></DialogProvider>
+ *
+ *   const dialog = useDialog()
+ *   dialog.replace(<MyContent />, () => revert())
+ *   dialog.clear()
+ */
+
+import { createContext, useContext, useState, useCallback, useMemo } from "react"
+import type { ReactNode } from "react"
+import { useKeyboard, useTerminalDimensions } from "@opentui/react"
+import { RGBA } from "@opentui/core"
+import { useKeys } from "../keys"
+import { useTheme } from "../theme"
+
+type DialogEntry = {
+  readonly element: ReactNode
+  readonly onClose?: () => void
+}
+
+export type DialogContext = {
+  readonly replace: (element: ReactNode, onClose?: () => void) => void
+  readonly clear: () => void
+  readonly stack: ReadonlyArray<DialogEntry>
+}
+
+const Ctx = createContext<DialogContext | null>(null)
+
+const BACKDROP = RGBA.fromInts(0, 0, 0, 150)
+
+export const DialogProvider = ({ children }: { children: ReactNode }) => {
+  const [stack, setStack] = useState<DialogEntry[]>([])
+
+  const replace = useCallback((element: ReactNode, onClose?: () => void) => {
+    setStack([{ element, onClose }])
+  }, [])
+
+  const clear = useCallback(() => {
+    setStack(prev => {
+      const top = prev[prev.length - 1]
+      if (top?.onClose) top.onClose()
+      return []
+    })
+  }, [])
+
+  const keys = useKeys()
+  useKeyboard((key) => {
+    if (stack.length === 0) return
+    if (keys.match("dialog.cancel", key)) clear()
+  })
+
+  const value = useMemo<DialogContext>(() => ({ replace, clear, stack }), [replace, clear, stack])
+  const top = stack.length > 0 ? stack[stack.length - 1] : undefined
+
+  return (
+    <Ctx.Provider value={value}>
+      {children}
+      {top ? <Overlay entry={top} onClose={clear} /> : null}
+    </Ctx.Provider>
+  )
+}
+
+const Overlay = ({ entry, onClose }: { entry: DialogEntry; onClose: () => void }) => {
+  const dims = useTerminalDimensions()
+  const theme = useTheme().theme
+
+  return (
+    <box
+      position="absolute"
+      left={0}
+      top={0}
+      width={dims.width}
+      height={dims.height}
+      zIndex={100}
+      backgroundColor={BACKDROP}
+      justifyContent="center"
+      alignItems="center"
+      onMouseDown={onClose}
+    >
+      <box
+        backgroundColor={theme.backgroundPanel}
+        borderStyle="single"
+        border={true}
+        borderColor={theme.border}
+        padding={1}
+        flexDirection="column"
+        onMouseDown={(e) => { e.stopPropagation() }}
+      >
+        {entry.element}
+      </box>
+    </box>
+  )
+}
+
+export const useDialog = (): DialogContext => {
+  const ctx = useContext(Ctx)
+  if (!ctx) throw new Error("useDialog() must be inside <DialogProvider>")
+  return ctx
+}

package/src/ui/fmt.ts

@@ -0,0 +1,82 @@
+// Shared string formatters for tab panels.
+//
+// Timestamps in this codebase are unix seconds unless otherwise noted
+// (gateway RPCs and state.db both store seconds). `ago`/`when`/`span`
+// take seconds; `dur` takes an already-computed delta in seconds.
+//
+// `timeFormat` / `timeStyle` preferences are read via prefs.get() —
+// non-reactive, same as `animations`. tui.json is loaded once at
+// launch; a live toggle (herm-907.6) will re-render via usePref() at
+// the toggle site, and these stay plain functions.
+
+import * as prefs from "../utils/preferences"
+
+const h12 = () => prefs.get("timeFormat") === "12h"
+const abs = () => prefs.get("timeStyle") === "absolute"
+
+export const trunc = (s: string, max: number): string =>
+  s.length <= max ? s : s.slice(0, max - 1) + "…"
+
+// abbreviate large counts: 12.3k / 1.23M
+export const fmt = (n: number): string =>
+  n >= 1_000_000 ? `${(n / 1_000_000).toFixed(2)}M`
+  : n >= 1_000 ? `${(n / 1_000).toFixed(1)}k`
+  : String(n)
+
+export const cost = (c: number | null | undefined): string =>
+  c == null ? "—" : `$${c.toFixed(2)}`
+
+const clock = (d: Date) =>
+  d.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit", hour12: h12() })
+
+// Compact absolute stamp for list columns (≤8 chars at 24h, ≤7 at 12h):
+// today → HH:MM, otherwise → "May 1". Hoisted from Sessions.
+export const stamp = (ts: number): string => {
+  const d = new Date(ts * 1000)
+  return d.toDateString() === new Date().toDateString()
+    ? clock(d)
+    : d.toLocaleDateString(undefined, { month: "short", day: "numeric" })
+}
+
+const rel = (ts: number): string => {
+  const s = Math.floor(Date.now() / 1000 - ts)
+  if (s < 60) return "just now"
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`
+  return `${Math.floor(s / 86400)}d ago`
+}
+
+// `timeStyle` flips ago/until between relative deltas and compact
+// absolute stamps. Callers are list columns and inline "· 2h ago"
+// labels — both read fine as "· 14:32" / "· May 1".
+export const ago = (ts: number): string => abs() ? stamp(ts) : rel(ts)
+
+// Future counterpart to `ago`. Past → "due".
+export const until = (ts: number): string => {
+  if (abs()) return ts <= Date.now() / 1000 ? "due" : stamp(ts)
+  const s = Math.floor(ts - Date.now() / 1000)
+  if (s <= 0) return "due"
+  if (s < 60) return `in ${s}s`
+  if (s < 3600) return `in ${Math.floor(s / 60)}m`
+  if (s < 86400) return `in ${Math.floor(s / 3600)}h`
+  return `in ${Math.floor(s / 86400)}d`
+}
+
+export const when = (ts: number): string => {
+  const d = new Date(ts * 1000)
+  return `${d.toLocaleDateString()} ${clock(d)}`
+}
+
+export const span = (start: number, end: number): string => {
+  const s = Math.round(end - start)
+  if (s < 0) return "—"
+  if (s >= 3600) return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`
+  if (s >= 60) return `${Math.floor(s / 60)}m`
+  return `${s}s`
+}
+
+// compact duration for uptime columns (no spaces, always two units ≥1m)
+export const dur = (s: number): string =>
+  s >= 3600 ? `${Math.floor(s / 3600)}h${Math.floor((s % 3600) / 60)}m`
+  : s >= 60 ? `${Math.floor(s / 60)}m${Math.floor(s % 60)}s`
+  : `${Math.floor(s)}s`

package/src/ui/kv.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react"
+import type { RGBA } from "@opentui/core"
+import { useTheme } from "../theme"
+
+// Single key/value line for detail panels. Label is a fixed-width
+// muted column; value takes remaining width. Default hard-truncates
+// at one line (overflow=hidden on height=1) so a long value can't
+// push panel layout; `wrap` opts into multi-line word-wrap instead.
+export const KV = (props: { label: string; value: string; fg?: RGBA; wrap?: boolean }) => {
+  const theme = useTheme().theme
+  return (
+    <box minHeight={1} flexDirection="row">
+      <box width={13} flexShrink={0}><text fg={theme.textMuted}>{props.label}</text></box>
+      <box flexGrow={1} minWidth={0}
+           height={props.wrap ? undefined : 1}
+           overflow={props.wrap ? undefined : "hidden"}>
+        <text wrapMode={props.wrap ? "word" : undefined} fg={props.fg ?? theme.text}>{props.value}</text>
+      </box>
+    </box>
+  )
+}
+
+// Stack of KV lines. Rows with an undefined value are skipped so
+// callers can inline conditionals without ternary noise.
+export const KVBlock = (props: { rows: Array<[string, string | undefined, RGBA?]> }): ReactNode =>
+  props.rows.map(([k, v, fg]) =>
+    v === undefined ? null : <KV key={k} label={k} value={v} fg={fg} />,
+  )

package/src/ui/shell.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from "react"
+import { useTheme } from "../theme"
+
+// Bordered panel chrome shared by every tab: title + keybinding hint
+// on one header line, optional error line, a one-row gap, then the
+// body. Body is wrapped in a flexGrow column with minWidth=0 so
+// children can truncate instead of forcing the panel wider than the
+// terminal.
+//
+// `focus` switches the border to theme.primary — used when a tab
+// hosts multiple panels and wants to show which has keyboard focus.
+// `grow` lets side-by-side panels set their flex ratio directly;
+// flexBasis=0 makes the ratio authoritative regardless of content.
+
+export const TabShell = (props: {
+  title: string
+  hint: string
+  error?: string | null
+  focus?: boolean
+  grow?: number
+  children?: ReactNode
+}) => {
+  const theme = useTheme().theme
+  return (
+    <box flexDirection="column" flexGrow={props.grow ?? 1} flexBasis={0} minWidth={0}
+         border borderColor={props.focus ? theme.primary : theme.border}
+         backgroundColor={theme.backgroundPanel} padding={1}>
+      <box height={1} flexDirection="row" overflow="hidden">
+        <box flexShrink={0}>
+          <text fg={theme.primary}><strong>{props.title}</strong></text>
+        </box>
+        <box flexGrow={1} minWidth={0} height={1} overflow="hidden">
+          <text fg={theme.textMuted}>{`  ${props.hint}`}</text>
+        </box>
+      </box>
+      {props.error
+        ? <box height={1}><text fg={theme.error}>{`⚠ ${props.error}`}</text></box>
+        : null}
+      <box height={1} />
+      <box flexDirection="column" flexGrow={1} minWidth={0}>
+        {props.children}
+      </box>
+    </box>
+  )
+}

package/src/ui/spinner.tsx

@@ -0,0 +1,59 @@
+// Single shared braille spinner. oc uses a native <spinner> element
+// from opentui-spinner; Herm drives a setInterval so the only moving
+// state is one integer. All spinners on screen share the same tick
+// via a module-level clock — N spinners = 1 interval, not N.
+
+import { useState, useEffect, memo, type ReactNode } from "react"
+import type { RGBA } from "@opentui/core"
+import { useTheme } from "../theme"
+import * as prefs from "../utils/preferences"
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+const MS = 80
+
+type Sub = (n: number) => void
+const subs = new Set<Sub>()
+let tick = 0
+let timer: ReturnType<typeof setInterval> | null = null
+
+function sub(fn: Sub) {
+  subs.add(fn)
+  if (!timer) timer = setInterval(() => {
+    tick = (tick + 1) % FRAMES.length
+    for (const s of subs) s(tick)
+  }, MS)
+  return () => {
+    subs.delete(fn)
+    if (subs.size === 0 && timer) { clearInterval(timer); timer = null }
+  }
+}
+
+function useFrame(active: boolean): number {
+  const [n, set] = useState(tick)
+  useEffect(() => (active ? sub(set) : undefined), [active])
+  return n
+}
+
+export const Spinner = memo((props: { color?: RGBA; label?: ReactNode }) => {
+  const theme = useTheme().theme
+  const color = props.color ?? theme.textMuted
+  const on = prefs.get("animations") !== false
+  const n = useFrame(on)
+  return (
+    <text>
+      <span fg={color}>{on ? FRAMES[n] : "⋯"}</span>
+      {props.label ? <span fg={color}> {props.label}</span> : null}
+    </text>
+  )
+})
+
+/**
+ * Inline glyph only — for embedding inside an existing <text>. Pass
+ * `active=false` for rows that aren't spinning: the hook won't
+ * subscribe to the clock, so completed rows don't re-render 12×/s.
+ */
+export function useSpinnerGlyph(active = true): string {
+  const on = prefs.get("animations") !== false && active
+  const n = useFrame(on)
+  return on ? FRAMES[n] : "⋯"
+}