@xp266/dshtui 0.1.0

package/src/ui/dialog/dialog.tsx

@@ -0,0 +1,386 @@
+import { Box, Text, useStdout } from 'ink'
+import { createContext, useContext } from 'react'
+import { useCaret } from '../hooks/use-caret.ts'
+import type { ReactNode, Ref } from 'react'
+import { useEffect, useImperativeHandle, useRef, useState } from 'react'
+import { COLORS } from '../../theme.ts'
+import { writeCursorShape } from '../../terminal/cursor-shape.ts'
+import { textWidth, colToCharIndex, caretScrollStart, truncate } from '../../core/text.ts'
+import { SelectableText } from '../selection.tsx'
+import { Region } from '../region.tsx'
+import { renderRow } from './dialog-item.tsx'
+import { adjustScroll, hitRowIndex, rowHeight, rowTopOffset, wrapFooter, wrapStatusLines } from './geometry.ts'
+import type { DialogFooterLine } from './geometry.ts'
+import { ERROR_MAX_ROWS } from './sizes.ts'
+import { asTextItem, clampFocus, filterRowsWithHeaders, focusedItem, isSelectableRow, selectableSpan, snapRow } from './items.ts'
+import type { DialogFocus, DialogItem, DialogRow } from './items.ts'
+import { applyNavigation, useDialogInput } from './use-dialog-input.ts'
+import type { DialogLiveState } from './use-dialog-input.ts'
+import { widgetOf } from '../widgets/registry.ts'
+import type { ClickActions, ClickHit } from '../widgets/types.ts'
+import type { WindowHandle } from '../../contract/index.ts'
+
+export * from './items.ts'
+export * from './geometry.ts'
+
+export interface DialogProps {
+  width: number
+  maxHeight: number
+  title?: string
+  rows: DialogRow[]
+  footer?: DialogFooterLine[]
+  errors?: DialogFooterLine[]
+  onClose: () => void
+  search?: boolean
+  searchRight?: boolean
+  centerScroll?: boolean
+  onCtrlA?(focused: DialogItem | undefined): boolean
+  onCtrlD?(focused: DialogItem | undefined): boolean
+  onCtrlE?(focused: DialogItem | undefined): boolean
+  onActivity?(): void
+  ref?: Ref<DialogHandle>
+}
+
+export type DialogHandle = WindowHandle
+
+export const CloseGuardContext = createContext(false)
+
+export function Dialog({
+  width,
+  maxHeight,
+  title,
+  rows,
+  footer,
+  errors,
+  onClose,
+  search = false,
+  searchRight = false,
+  centerScroll = false,
+  onCtrlA,
+  onCtrlD,
+  onCtrlE,
+  onActivity,
+  ref,
+}: DialogProps) {
+  const { stdout } = useStdout()
+  const { setCursorPosition } = useCaret()
+  const closeGuarded = useContext(CloseGuardContext)
+  const columns = stdout?.columns ?? 80
+  const totalRows = stdout?.rows ?? 24
+  const [scrollTop, setScrollTop] = useState(0)
+  const [cursor, setCursor] = useState(0)
+  const cursorSyncRef = useRef<{ row: number; col: number; type: string | undefined }>({ row: -1, col: -1, type: undefined })
+  const [searchValue, setSearchValue] = useState('')
+  const [carouselPress, setCarouselPress] = useState<{ row: number; side: 'left' | 'right' } | null>(null)
+  const carouselPressTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const [errorScrollTop, setErrorScrollTop] = useState(0)
+  const handleSearch = (value: string) => {
+    setSearchValue(value)
+    setScrollTop(0)
+  }
+  const searchRow: DialogRow = { items: [{ type: 'search', value: searchValue, onChange: handleSearch }] }
+  const filteredRows = search ? filterRowsWithHeaders(rows, searchValue, searchRight) : rows
+  const displayRows = search ? [searchRow, ...filteredRows] : rows
+  const contentRows = search ? filteredRows : rows
+  const [focus, setFocus] = useState<DialogFocus>(() => ({ row: snapRow(search ? [searchRow, ...rows] : rows, search ? 1 : 0), col: 0 }))
+  const widthCells = width <= 1 ? Math.floor(columns * width) : width
+  const windowWidth = Math.min(Math.max(1, widthCells), columns)
+  const contentWidth = Math.max(1, windowWidth - 4)
+  const fixedHeight = search ? rowHeight(searchRow, contentWidth) : 0
+  const focusMinRow = search ? 1 : 0
+  const focusMaxRow = Math.max(0, displayRows.length - 1)
+  useEffect(() => {
+    setFocus(current => {
+      const next = clampFocus(displayRows, current, focusMinRow, focusMaxRow)
+      return next.row === current.row && next.col === current.col ? current : next
+    })
+  }, [displayRows, focusMinRow, focusMaxRow])
+  const errorKey = (errors ?? []).map(line => line.text).join('\n')
+  useEffect(() => {
+    setErrorScrollTop(0)
+  }, [errorKey])
+  const titleLines = title === undefined ? 0 : 2
+  const footerRows = wrapFooter(footer, contentWidth)
+  const extraHeight = footerRows.length > 0 ? 1 + footerRows.length : 0
+  const desired = displayRows.reduce((sum, row) => sum + rowHeight(row, contentWidth), 0) + titleLines + extraHeight + 2
+  const maxRows = Math.max(1, maxHeight <= 1 ? Math.floor(totalRows * maxHeight) : maxHeight)
+  const windowHeight = Math.min(desired, maxRows, totalRows)
+  const contentHeight = Math.max(1, windowHeight - 2 - titleLines - extraHeight)
+  const viewportHeight = Math.max(1, contentHeight - fixedHeight)
+  const top = Math.max(0, Math.floor((totalRows - windowHeight) / 2))
+  const left = Math.max(0, Math.floor((columns - windowWidth) / 2))
+  const frameLeft = 2
+  const errorRows = wrapStatusLines(errors, contentWidth)
+  const availableBelow = Math.max(0, totalRows - (top + windowHeight))
+  const errorVisible = Math.max(0, Math.min(ERROR_MAX_ROWS, errorRows.length, availableBelow - 1))
+  const maxErrorScroll = Math.max(0, errorRows.length - errorVisible)
+  const errorScroll = Math.min(errorScrollTop, maxErrorScroll)
+  const headerBottom = 1 + titleLines
+  const contentTop = headerBottom + fixedHeight
+  const safeFocus: DialogFocus = {
+    row: Math.min(Math.max(focus.row, 0), focusMaxRow),
+    col: Math.min(Math.max(focus.col, 0), selectableSpan(displayRows[focus.row])),
+  }
+  const contentRowsHeight = contentRows.reduce((sum, row) => sum + rowHeight(row, contentWidth), 0)
+  const maxScroll = Math.max(0, contentRowsHeight - viewportHeight)
+  const scroll = adjustScroll(contentRows, { row: Math.max(0, safeFocus.row - (search ? 1 : 0)), col: 0 }, Math.min(scrollTop, maxScroll), viewportHeight, contentWidth)
+  const live = useRef<DialogLiveState>({
+    rows: displayRows,
+    contentRows,
+    focus,
+    scrollTop: scroll,
+    cursor,
+    value: '',
+    searchValue,
+    viewportHeight,
+    focusMinRow,
+    focusMaxRow,
+    contentWidth,
+    top,
+    windowHeight,
+  })
+  live.current.rows = displayRows
+  live.current.contentRows = contentRows
+  live.current.focus = focus
+  live.current.scrollTop = scroll
+  live.current.searchValue = searchValue
+  live.current.viewportHeight = viewportHeight
+  live.current.focusMinRow = focusMinRow
+  live.current.focusMaxRow = focusMaxRow
+  live.current.contentWidth = contentWidth
+  live.current.top = top
+  live.current.windowHeight = windowHeight
+  const errorLive = useRef({ top: 0, height: 0, maxScroll: 0 })
+  errorLive.current = { top: top + windowHeight, height: errorVisible + 1, maxScroll: maxErrorScroll }
+  const current = focusedItem(displayRows[safeFocus.row], safeFocus.col)
+  const currentText = current === undefined ? null : asTextItem(current)
+  live.current.value = currentText?.value ?? ''
+  const cursorSynced = cursorSyncRef.current.row === safeFocus.row
+    && cursorSyncRef.current.col === safeFocus.col
+    && cursorSyncRef.current.type === current?.type
+  const effectiveCursor = cursorSynced || currentText === null || currentText.type === 'search'
+    ? cursor
+    : currentText.value.length
+  live.current.cursor = effectiveCursor
+  useEffect(() => {
+    cursorSyncRef.current = { row: safeFocus.row, col: safeFocus.col, type: current?.type }
+    if (currentText !== null && currentText.type !== 'search') {
+      setCursor(currentText.value.length)
+    }
+  }, [current?.type, safeFocus.row, safeFocus.col, displayRows.length])
+  const editingFormInput = current !== undefined && current.type !== 'search' && asTextItem(current) !== null
+  if (search && !editingFormInput) {
+    const caret = Math.min(Math.max(0, cursor), searchValue.length)
+    const start = caretScrollStart(searchValue, caret, contentWidth)
+    setCursorPosition({
+      x: left + frameLeft + textWidth(searchValue.slice(start, caret)),
+      y: top + headerBottom,
+    })
+  } else {
+    const caretOffset = current === undefined ? undefined : widgetOf(current.type).caret?.(current, effectiveCursor, contentWidth)
+    if (caretOffset === undefined) {
+      setCursorPosition(undefined)
+    } else {
+      const contentIndex = Math.max(0, safeFocus.row - (search ? 1 : 0))
+      const rowOffset = rowTopOffset(contentRows, contentIndex, contentWidth)
+      setCursorPosition({
+        x: left + frameLeft + caretOffset.dx,
+        y: top + contentTop + rowOffset + caretOffset.dy - scroll,
+      })
+    }
+  }
+  useEffect(() => {
+    if (search && !editingFormInput) {
+      writeCursorShape('beam')
+      return
+    }
+    const beam = current !== undefined && widgetOf(current.type).caret !== undefined
+    writeCursorShape(beam ? 'beam' : 'block')
+  }, [current?.type, safeFocus.row, safeFocus.col])
+  useEffect(() => {
+    return () => {
+      writeCursorShape('reset')
+      clearTimeout(carouselPressTimer.current)
+    }
+  }, [])
+  useDialogInput({
+    live,
+    search,
+    closeGuarded,
+    centerScroll,
+    onClose,
+    onCtrlA,
+    onCtrlD,
+    onCtrlE,
+    onActivity,
+    requestSearch: handleSearch,
+    setFocus,
+    setScrollTop,
+    setCursor,
+  })
+  const flashCarousel = (row: number, side: 'left' | 'right') => {
+    setCarouselPress({ row, side })
+    clearTimeout(carouselPressTimer.current)
+    carouselPressTimer.current = setTimeout(() => setCarouselPress(null), 120)
+  }
+  useImperativeHandle(ref, () => ({
+    wheelAt(y, dir) {
+      onActivity?.()
+      if (y < live.current.top || y >= live.current.top + live.current.windowHeight) {
+        const error = errorLive.current
+        if (error.height > 1 && y >= error.top && y < error.top + error.height) {
+          setErrorScrollTop(current => Math.max(0, Math.min(current + dir, error.maxScroll)))
+          return true
+        }
+        return false
+      }
+      applyNavigation(live.current, dir === -1 ? 'up' : 'down', search, { setFocus, setScrollTop }, centerScroll)
+      return true
+    },
+    clickAt(y, x) {
+      onActivity?.()
+      if (y < top || y >= top + windowHeight || x < left || x >= left + windowWidth) return
+      if (search) {
+        const searchTop = top + headerBottom
+        if (y >= searchTop && y < searchTop + fixedHeight) {
+          const clickCaret = safeFocus.row === 0 ? Math.min(cursor, searchValue.length) : searchValue.length
+          const start = caretScrollStart(searchValue, clickCaret, contentWidth)
+          const visible = truncate(searchValue.slice(start), contentWidth)
+          const col = Math.max(0, Math.min(x - (left + frameLeft), textWidth(visible)))
+          setFocus({ row: 0, col: 0 })
+          setCursor(Math.min(searchValue.length, start + colToCharIndex(visible, col)))
+          return
+        }
+      }
+      const rowIndex = hitRowIndex(y, top + fixedHeight, titleLines, contentRows, scroll, contentWidth)
+      if (rowIndex === null) return
+      const rowSpec = contentRows[rowIndex]
+      if (!isSelectableRow(rowSpec)) return
+      const displayRow = Math.min(Math.max(rowIndex + (search ? 1 : 0), focusMinRow), focusMaxRow)
+      const rowOffset = rowTopOffset(contentRows, rowIndex, contentWidth)
+      const hit: ClickHit = {
+        localX: x - (left + frameLeft),
+        localY: y - (top + contentTop + rowOffset - scroll),
+        width: contentWidth,
+      }
+      const clickActions: ClickActions = {
+        focus: col => setFocus({ row: displayRow, col }),
+        flash: side => flashCarousel(rowIndex, side),
+      }
+      for (const item of rowSpec?.items ?? []) {
+        if (widgetOf(item.type).onClick?.(item, hit, clickActions) === true) return
+      }
+      if (safeFocus.row === displayRow && rowSpec !== undefined) {
+        const first = rowSpec.items[0]
+        if (first !== undefined) {
+          const activate = widgetOf(first.type).activate
+          if (activate !== undefined) {
+            activate(first)
+            return
+          }
+        }
+      }
+      setFocus({ row: displayRow, col: 0 })
+      const contentRow = Math.max(0, Math.min(rowIndex, contentRows.length - 1))
+      setScrollTop(adjustScroll(contentRows, { row: contentRow, col: 0 }, scroll, viewportHeight, contentWidth))
+    },
+  }))
+  const visibleRows: ReactNode[] = []
+  let offset = 0
+  for (let i = 0; i < contentRows.length; i++) {
+    const height = rowHeight(contentRows[i]!, contentWidth)
+    if (offset + height <= scroll) {
+      offset += height
+      continue
+    }
+    if (offset >= scroll + viewportHeight) break
+    const clip = Math.max(0, scroll - offset)
+    const rel = Math.max(0, offset - scroll)
+    const baseY = contentTop + rel
+    const focused = safeFocus.row === i + (search ? 1 : 0)
+    visibleRows.push(
+      <Box key={`row-${i}`} position="absolute" top={rel} left={0} width={contentWidth}>
+        {renderRow(contentRows[i], focused, contentWidth, baseY, frameLeft, carouselPress?.row === i ? carouselPress.side : null, focused ? safeFocus.col : 0, clip, focused ? effectiveCursor : undefined)}
+      </Box>,
+    )
+    offset += height
+  }
+  return (
+    <Region x={left} y={top}>
+      <Box
+        position="absolute"
+        top={top}
+        left={left}
+        width={windowWidth}
+        height={windowHeight}
+        flexDirection="column"
+        backgroundColor={COLORS.dialogBackground}
+        paddingLeft={2}
+        paddingRight={2}
+        paddingTop={1}
+        paddingBottom={1}
+      >
+        {title !== undefined && (
+          <>
+            <Box justifyContent="center">
+              <SelectableText y={1} col={frameLeft + Math.max(0, Math.floor((contentWidth - textWidth(title)) / 2))} text={title} />
+            </Box>
+            <Box height={1}>
+              <Text> </Text>
+            </Box>
+          </>
+        )}
+        <Box flexDirection="column">
+          {search && (
+            <Box flexDirection="column">
+              {renderRow(searchRow, safeFocus.row === 0, contentWidth, headerBottom, frameLeft, null, 0, 0, cursor)}
+            </Box>
+          )}
+          <Box flexDirection="column" height={viewportHeight} overflow="hidden">
+            {visibleRows}
+          </Box>
+        </Box>
+        {footerRows.length > 0 && (
+          <>
+            <Box height={1}>
+              <Text> </Text>
+            </Box>
+            {footerRows.map((line, index) => (
+              <SelectableText
+                key={index}
+                y={windowHeight - footerRows.length + index - 1}
+                col={frameLeft}
+                text={line.text}
+                color={line.color}
+              />
+            ))}
+          </>
+        )}
+      </Box>
+      {errorVisible > 0 && (
+        <Box
+          position="absolute"
+          top={top + windowHeight}
+          left={left}
+          width={windowWidth}
+          height={errorVisible + 1}
+          flexDirection="column"
+          backgroundColor={COLORS.dialogBackground}
+          paddingLeft={2}
+          paddingRight={2}
+          paddingBottom={1}
+        >
+          {errorRows.slice(errorScroll, errorScroll + errorVisible).map((line, index) => (
+            <SelectableText
+              key={errorScroll + index}
+              y={windowHeight + index}
+              col={frameLeft}
+              text={line.text}
+              color={line.color}
+            />
+          ))}
+        </Box>
+      )}
+    </Region>
+  )
+}

package/src/ui/dialog/effort-dialog.tsx

@@ -0,0 +1,45 @@
+import type { Ref } from 'react'
+import { errorLine } from './status-lines.ts'
+import type { EffortSummary } from '../../chat/efforts.ts'
+import { useAsyncAction } from '../hooks/use-async-action.ts'
+import { ListDialog } from './list-dialog.tsx'
+import { DIALOG_WIDTH_MEDIUM, DIALOG_MAX_HEIGHT } from './sizes.ts'
+import type { DialogHandle, DialogFooterLine } from './dialog.tsx'
+
+export interface EffortsApi {
+  listEfforts(): Promise<EffortSummary[]>
+  currentEffort(): string | undefined
+  selectEffort(id: string): Promise<void>
+}
+
+export interface EffortDialogProps {
+  api: EffortsApi
+  onClose: () => void
+  ref?: Ref<DialogHandle>
+}
+
+
+export function EffortDialog({ api, onClose, ref }: EffortDialogProps) {
+  const { error, run } = useAsyncAction()
+  const current = api.currentEffort()
+  const selectEffort = async (id: string) => {
+    const result = await run(() => api.selectEffort(id))
+    if (!result.ok) return
+    onClose()
+  }
+  const footerLines: DialogFooterLine[] = error === null ? [] : [errorLine(error)]
+  return (
+    <ListDialog
+      ref={ref}
+      title="reasoning effort"
+      width={DIALOG_WIDTH_MEDIUM}
+      maxHeight={DIALOG_MAX_HEIGHT}
+      load={api.listEfforts}
+      labelOf={effort => effort.name}
+      rightOf={effort => (effort.id === current ? 'current' : undefined)}
+      onSelect={effort => void selectEffort(effort.id)}
+      onClose={onClose}
+      errors={footerLines}
+    />
+  )
+}

package/src/ui/dialog/geometry.ts

@@ -0,0 +1,131 @@
+import { textWidth, truncate, wrapLines } from '../../core/text.ts'
+import { glyphs } from '../../terminal/glyphs.ts'
+import type { DialogFocus, DialogRow } from './items.ts'
+import { isSelectableRow } from './items.ts'
+import { widgetOf } from '../widgets/registry.ts'
+
+export const CAROUSEL_BUTTON_WIDTH = 3
+
+const SELECT_BLOCK_WIDTH_RATIO = 0.6
+const ACTION_EDGE_RATIO = 0.2
+
+export interface DialogFooterLine {
+  text: string
+  color?: string
+}
+
+interface FooterRenderLine {
+  text: string
+  color?: string
+}
+
+const FOOTER_MAX_LINES_PER_ENTRY = 2
+
+function wrapFooter(footer: DialogFooterLine[] | undefined, width: number): FooterRenderLine[] {
+  if (footer === undefined) return []
+  const rows: FooterRenderLine[] = []
+  for (const line of footer) {
+    if (line.text === '') continue
+    const wrapped = wrapLines(line.text, width)
+    const capped = wrapped.slice(0, FOOTER_MAX_LINES_PER_ENTRY)
+    if (wrapped.length > FOOTER_MAX_LINES_PER_ENTRY) {
+      capped[1] = truncate(capped[1] ?? '', Math.max(1, width - glyphs.ellipsis.length)) + glyphs.ellipsis
+    }
+    for (const text of capped) rows.push({ text, color: line.color })
+  }
+  return rows
+}
+
+export { wrapFooter }
+
+export function wrapStatusLines(lines: DialogFooterLine[] | undefined, width: number): FooterRenderLine[] {
+  if (lines === undefined) return []
+  const rows: FooterRenderLine[] = []
+  for (const line of lines) {
+    if (line.text === '') continue
+    for (const text of wrapLines(line.text, width)) rows.push({ text, color: line.color })
+  }
+  return rows
+}
+
+export function rowHeight(row: DialogRow, width: number): number {
+  let height = 1
+  for (const item of row.items) {
+    const itemHeight = widgetOf(item.type).height(item, width)
+    if (itemHeight > height) height = itemHeight
+  }
+  return height
+}
+
+export function rowTopOffset(rows: DialogRow[], rowIndex: number, width: number): number {
+  let offset = 0
+  for (let i = 0; i < rowIndex; i++) offset += rowHeight(rows[i]!, width)
+  return offset
+}
+
+export function rowBlockSpan(rows: DialogRow[], rowIndex: number, width: number): { top: number; bottom: number } {
+  const top = rowTopOffset(rows, rowIndex, width)
+  let blockTop = top
+  let bottom = top + rowHeight(rows[rowIndex] ?? { items: [] }, width) - 1
+  for (let i = rowIndex - 1; i >= 0 && !isSelectableRow(rows[i]); i--) blockTop -= rowHeight(rows[i]!, width)
+  for (let i = rowIndex + 1; i < rows.length && !isSelectableRow(rows[i]); i++) bottom += rowHeight(rows[i]!, width)
+  return { top: blockTop, bottom }
+}
+
+export function adjustScroll(rows: DialogRow[], focus: DialogFocus, scrollTop: number, contentHeight: number, width: number): number {
+  const { top, bottom } = rowBlockSpan(rows, focus.row, width)
+  if (top < scrollTop) return top
+  if (bottom >= scrollTop + contentHeight) return Math.max(0, bottom - contentHeight + 1)
+  return scrollTop
+}
+
+export function listCenterScroll(rows: DialogRow[], focusRow: number, viewportHeight: number, width: number, direction: 'up' | 'down'): number {
+  const total = rows.reduce((sum, row) => sum + rowHeight(row, width), 0)
+  const maxScroll = Math.max(0, total - viewportHeight)
+  const anchor = direction === 'down' ? Math.floor(viewportHeight / 2) : Math.floor((viewportHeight - 1) / 2)
+  const top = rowTopOffset(rows, focusRow, width)
+  return Math.max(0, Math.min(top - anchor, maxScroll))
+}
+
+export function hitRowIndex(y: number, top: number, titleLines: number, rows: DialogRow[], scrollTop = 0, width = Number.POSITIVE_INFINITY): number | null {
+  const localY = y - top - 1 - titleLines + scrollTop
+  let offset = 0
+  for (let i = 0; i < rows.length; i++) {
+    const height = rowHeight(rows[i]!, width)
+    if (localY >= offset && localY < offset + height) return i
+    offset += height
+  }
+  return null
+}
+
+export interface SelectBlock {
+  blockWidth: number
+  blockStart: number
+  text: string
+  leftPad: number
+  fullLeftPad: number
+  cursorX: number
+}
+
+export function selectBlock(contentWidth: number, value: string): SelectBlock {
+  const blockWidth = Math.max(3, Math.floor(contentWidth * SELECT_BLOCK_WIDTH_RATIO))
+  const innerWidth = Math.max(1, blockWidth - CAROUSEL_BUTTON_WIDTH * 2)
+  const text = truncate(value || '(none)', innerWidth)
+  const padding = innerWidth - textWidth(text)
+  const fullPadding = blockWidth - textWidth(text)
+  return {
+    blockWidth,
+    blockStart: contentWidth - blockWidth,
+    text,
+    leftPad: Math.floor(padding / 2),
+    fullLeftPad: Math.floor(fullPadding / 2),
+    cursorX: CAROUSEL_BUTTON_WIDTH + Math.floor(padding / 2) + textWidth(text),
+  }
+}
+
+export function actionPositions(contentWidth: number, confirmLabel: string, cancelLabel: string): { confirmX: number; cancelX: number } {
+  const edge = Math.floor(contentWidth * ACTION_EDGE_RATIO)
+  const confirmX = Math.min(edge, Math.max(0, contentWidth - textWidth(confirmLabel)))
+  const cancelX = Math.max(confirmX + textWidth(confirmLabel), contentWidth - edge - textWidth(cancelLabel))
+  return { confirmX, cancelX }
+}

package/src/ui/dialog/items.ts

@@ -0,0 +1,124 @@
+import { widgetOf } from '../widgets/registry.ts'
+import type { DialogItemKinds } from '../../contract/index.ts'
+
+export interface DialogRow {
+  items: DialogItem[]
+}
+
+type PluginDialogItem = DialogItemKinds[keyof DialogItemKinds]
+
+export type DialogItem =
+  | { type: 'input'; label: string; value: string; onChange: (value: string) => void; onEnter?: () => void }
+  | { type: 'select'; label: string; value: string; options: string[]; onChange: (value: string) => void; onEnter?: () => void; spaced?: boolean }
+  | { type: 'search'; value: string; onChange: (value: string) => void }
+  | { type: 'button'; label: string; right?: string; rightColor?: string; onPress: () => void }
+  | { type: 'checkbox'; label: string; checked: boolean; onToggle: () => void; onConfirm: () => void }
+  | { type: 'header'; label: string; leadingBlank?: boolean }
+  | { type: 'static'; label: string }
+  | { type: 'actions'; confirmLabel: string; cancelLabel: string; onConfirm: () => void; onCancel: () => void }
+  | { type: string; data?: unknown }
+  | PluginDialogItem
+
+export interface DialogFocus {
+  row: number
+  col: number
+}
+
+export function isSelectableRow(row: DialogRow | undefined): boolean {
+  if (row === undefined) return false
+  return row.items.some(item => widgetOf(item.type).selectable === true)
+}
+
+export function selectableSpan(row: DialogRow | undefined): number {
+  if (row === undefined) return 0
+  let stops = 0
+  for (const item of row.items) {
+    stops += widgetOf(item.type).stops?.(item) ?? 1
+  }
+  return Math.max(0, stops - 1)
+}
+
+export function snapRow(rows: DialogRow[], row: number): number {
+  const count = rows.length
+  if (count === 0) return 0
+  const index = Math.min(Math.max(row, 0), count - 1)
+  if (isSelectableRow(rows[index])) return index
+  for (let down = index + 1; down < count; down++) {
+    if (isSelectableRow(rows[down])) return down
+  }
+  for (let up = index - 1; up >= 0; up--) {
+    if (isSelectableRow(rows[up])) return up
+  }
+  return index
+}
+
+function stepRow(rows: DialogRow[], from: number, delta: -1 | 1): number {
+  let row = from + delta
+  while (row >= 0 && row < rows.length && !isSelectableRow(rows[row])) row += delta
+  return row >= 0 && row < rows.length ? row : from
+}
+
+function focusedItem(row: DialogRow | undefined, col: number): DialogItem | undefined {
+  if (row === undefined) return undefined
+  const only = row.items.length === 1 ? row.items[0] : undefined
+  if (only !== undefined && widgetOf(only.type).fullRowFocus === true) return only
+  return row.items[col]
+}
+
+export { focusedItem }
+
+export function moveFocus(rows: DialogRow[], focus: DialogFocus, key: 'up' | 'down' | 'left' | 'right'): DialogFocus {
+  switch (key) {
+    case 'up':
+      return { row: stepRow(rows, focus.row, -1), col: 0 }
+    case 'down':
+      return { row: stepRow(rows, focus.row, 1), col: 0 }
+    case 'left':
+      return { row: focus.row, col: Math.max(0, focus.col - 1) }
+    case 'right': {
+      const max = selectableSpan(rows[focus.row])
+      return { row: focus.row, col: Math.max(0, Math.min(max, focus.col + 1)) }
+    }
+  }
+}
+
+export function clampFocus(rows: DialogRow[], focus: DialogFocus, minRow: number, maxRow: number): DialogFocus {
+  const row = snapRow(rows, Math.min(Math.max(focus.row, minRow), maxRow))
+  return { row, col: Math.min(focus.col, selectableSpan(rows[row])) }
+}
+
+export type TextItem = Extract<DialogItem, { type: 'input' }> | Extract<DialogItem, { type: 'search' }>
+
+export function asTextItem(item: DialogItem): TextItem | null {
+  return widgetOf(item.type).editable === true ? item as TextItem : null
+}
+
+export function filterRowsWithHeaders(rows: DialogRow[], query: string, searchRight: boolean): DialogRow[] {
+  const q = query.trim().toLowerCase()
+  if (q === '') return rows
+  const matches = (item: DialogItem): boolean => {
+    const texts = widgetOf(item.type).searchTexts?.(item, searchRight)
+    if (texts === undefined) return false
+    return texts.some(text => text.toLowerCase().includes(q))
+  }
+  const out: DialogRow[] = []
+  let pendingHeader: DialogRow | undefined
+  for (const row of rows) {
+    if (!isSelectableRow(row)) {
+      pendingHeader = row
+      continue
+    }
+    if (!row.items.some(matches)) continue
+    if (pendingHeader !== undefined) {
+      out.push(pendingHeader)
+      pendingHeader = undefined
+    }
+    out.push(row)
+  }
+  const first = out[0]
+  if (first !== undefined && first.items.length === 1 && first.items[0]?.type === 'header') {
+    const header = first.items[0] as { type: 'header'; label: string; leadingBlank?: boolean }
+    out[0] = { items: [{ ...header, leadingBlank: false }] }
+  }
+  return out
+}