@timmo001/groundwork-tui 0.0.0-stage → 0.4.1

package/src/header-block.ts

@@ -0,0 +1,120 @@
+/**
+ * The header block: the app's name as large ASCII art when the terminal has
+ * room, then the header bar. Shared by every view, so the top of the app
+ * stays put as views change.
+ *
+ * @module
+ */
+import { ASCIIFontRenderable, TextRenderable } from "@opentui/core";
+import type { BoxRenderable, CliRenderer } from "@opentui/core";
+import { formatHeaderBar } from "./header-bar.ts";
+import type { HeaderStatus } from "./header-bar.ts";
+import type { Theme } from "./theme.ts";
+
+/** The narrowest terminal that gets the large block font. */
+const MIN_WIDTH_FOR_BLOCK = 160;
+
+/** The shortest terminal that shows the ASCII art at all. */
+const MIN_HEIGHT_FOR_ART = 24;
+
+export interface HeaderBlockOptions {
+  /** Prefix for the renderables' ids */
+  readonly id: string;
+  /** The app's name, drawn as ASCII art */
+  readonly name: string;
+  /** The breadcrumb, such as `["Settings", "Theme"]` */
+  readonly titleParts: readonly string[];
+  readonly status: HeaderStatus;
+}
+
+/**
+ * The ASCII art name and the header bar. Both are added straight to `parent`,
+ * with no wrapper box, so the ASCII art takes part in its flex layout.
+ */
+export class HeaderBlock {
+  private readonly renderer: CliRenderer;
+  private readonly theme: Theme;
+  private readonly art: ASCIIFontRenderable;
+  private readonly bar: TextRenderable;
+  private titleParts: readonly string[];
+  private status: HeaderStatus;
+
+  constructor(
+    renderer: CliRenderer,
+    theme: Theme,
+    parent: BoxRenderable,
+    options: HeaderBlockOptions,
+  ) {
+    this.renderer = renderer;
+    this.theme = theme;
+    this.titleParts = options.titleParts;
+    this.status = options.status;
+
+    this.art = new ASCIIFontRenderable(renderer, {
+      id: `${options.id}-art`,
+      text: options.name,
+      font: this.pickFont(),
+      color: theme.accent,
+      alignSelf: "center",
+    });
+    this.art.visible = this.hasRoom();
+    parent.add(this.art);
+
+    this.bar = new TextRenderable(renderer, {
+      id: `${options.id}-bar`,
+      content: "",
+      wrapMode: "none",
+      truncate: true,
+      flexShrink: 0,
+      marginTop: 1,
+      marginBottom: 1,
+    });
+    parent.add(this.bar);
+    this.render();
+
+    renderer.on("resize", this.onResize);
+  }
+
+  /** Changes the status, and the breadcrumb when given. */
+  update(status: HeaderStatus, titleParts?: readonly string[]): void {
+    this.status = status;
+
+    if (titleParts !== undefined) this.titleParts = titleParts;
+
+    this.render();
+  }
+
+  /** Changes the breadcrumb. */
+  setTitleParts(titleParts: readonly string[]): void {
+    this.titleParts = titleParts;
+    this.render();
+  }
+
+  /** Stops following terminal resizes. */
+  destroy(): void {
+    this.renderer.off("resize", this.onResize);
+  }
+
+  private readonly onResize = (): void => {
+    this.art.visible = this.hasRoom();
+    this.art.font = this.pickFont();
+    this.render();
+  };
+
+  private render(): void {
+    this.bar.content = formatHeaderBar(
+      this.theme,
+      this.titleParts,
+      this.status,
+      this.renderer.width,
+    );
+  }
+
+  private hasRoom(): boolean {
+    return this.renderer.height >= MIN_HEIGHT_FOR_ART;
+  }
+
+  private pickFont(): "block" | "tiny" {
+    return this.renderer.width >= MIN_WIDTH_FOR_BLOCK ? "block" : "tiny";
+  }
+}

package/src/help-bar.ts

@@ -0,0 +1,90 @@
+/**
+ * The help bar along the bottom of each view: key and action pairs, wrapped
+ * to the terminal's width.
+ *
+ * @module
+ */
+import { StyledText, fg } from "@opentui/core";
+import type { TextChunk } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+/** A key-action pair displayed in a help bar */
+export interface HelpEntry {
+  /** Key or key combination (e.g. "↑↓", "Enter", "Esc/Backspace") */
+  readonly key: string;
+  /** Action description (e.g. "navigate", "quit") */
+  readonly action: string;
+}
+
+/** Global help entries appended to every view's help bar */
+export const GLOBAL_HELP: readonly HelpEntry[] = [
+  { key: "Ctrl+c", action: "quit" },
+];
+
+/** Separator between key-action pairs (visible width) */
+const SEPARATOR = "   ";
+
+/**
+ * Format help bar entries into styled text with automatic row wrapping.
+ *
+ * Keys are rendered in muted text and actions in subtle text so keyboard
+ * shortcuts stand out. When the total width exceeds terminal columns,
+ * entries wrap onto multiple rows.
+ *
+ * @param theme - Active color theme
+ * @param entries - Key-action pairs to display
+ * @param suffix - Optional styled suffix appended after the last row (e.g. model ID badge)
+ * @param columns - Width to wrap at, the terminal's by default
+ */
+export function formatHelpBar(
+  theme: Theme,
+  entries: readonly HelpEntry[],
+  suffix?: TextChunk,
+  columns: number = process.stdout.columns || 80,
+): StyledText {
+  // Wrap into rows that fit within terminal width using plain-text widths
+  const rows: HelpEntry[][] = [];
+  let currentWidth = 0;
+  let currentRow: HelpEntry[] = [];
+
+  for (const entry of entries) {
+    const partWidth = `${entry.key} ${entry.action}`.length;
+
+    const candidateWidth =
+      currentRow.length > 0
+        ? currentWidth + SEPARATOR.length + partWidth
+        : partWidth;
+
+    if (currentRow.length > 0 && candidateWidth > columns) {
+      rows.push(currentRow);
+      currentRow = [entry];
+      currentWidth = partWidth;
+    } else {
+      currentRow.push(entry);
+      currentWidth = candidateWidth;
+    }
+  }
+
+  if (currentRow.length > 0) rows.push(currentRow);
+
+  // Build styled chunks with color-coded keys and actions
+  const chunks: TextChunk[] = [];
+
+  for (const [r, row] of rows.entries()) {
+    if (r > 0) chunks.push(fg(theme.fgSubtle)("\n"));
+
+    for (const [j, entry] of row.entries()) {
+      if (j > 0) chunks.push(fg(theme.fgSubtle)(SEPARATOR));
+
+      chunks.push(fg(theme.fgMuted)(entry.key));
+      chunks.push(fg(theme.fgSubtle)(` ${entry.action}`));
+    }
+  }
+
+  if (suffix) {
+    chunks.push(fg(theme.fgSubtle)("  "));
+    chunks.push(suffix);
+  }
+
+  return new StyledText(chunks);
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Groundwork's terminal components: OpenTUI renderables and formatters on
+ * the terminal tokens, so every Groundwork TUI looks and behaves the same.
+ * Docs: https://groundwork.timmo.dev/terminal
+ *
+ * @packageDocumentation
+ */
+export { AppHeader, type AppHeaderOptions } from "./app-header.ts";
+
+export { formatBreadcrumb } from "./breadcrumb.ts";
+
+export { Button, type ButtonOptions, type ButtonVariant } from "./button.ts";
+
+export {
+  ChoiceDialog,
+  type Choice,
+  type ChoiceDialogOptions,
+} from "./choice-dialog.ts";
+
+export { Collapsible, type CollapsibleOptions } from "./collapsible.ts";
+
+export { ConfirmDialog, type ConfirmDialogOptions } from "./confirm-dialog.ts";
+
+export { Dialog, type DialogOptions } from "./dialog.ts";
+
+export { formatFilterBar } from "./filter-bar.ts";
+
+export {
+  formatHeaderBar,
+  type HeaderStatus,
+  type HeaderTone,
+} from "./header-bar.ts";
+
+export { HeaderBlock, type HeaderBlockOptions } from "./header-block.ts";
+
+export { formatHelpBar, GLOBAL_HELP, type HelpEntry } from "./help-bar.ts";
+
+export { Input, type InputOptions } from "./input.ts";
+
+export {
+  MenuGrid,
+  type MenuGridItem,
+  type MenuGridOptions,
+  type MenuGridSection,
+} from "./menu-grid.ts";
+
+export {
+  MenuList,
+  type MenuListItem,
+  type MenuListOptions,
+} from "./menu-list.ts";
+
+export { PaneHeader } from "./pane-header.ts";
+
+export {
+  RadioGroup,
+  type RadioChoice,
+  type RadioGroupOptions,
+} from "./radio-group.ts";
+
+export { ScrollSurface, type ScrollSurfaceOptions } from "./scroll-surface.ts";
+
+export {
+  SectionHeading,
+  type SectionHeadingOptions,
+} from "./section-heading.ts";
+
+export {
+  StatusList,
+  type StatusListItem,
+  type StatusListOptions,
+} from "./status-list.ts";
+
+export { surfaceBackground } from "./styles.ts";
+
+export { DEFAULT_THEME, loadTheme, themeFor, type Theme } from "./theme.ts";
+
+export { Tile, type TileOptions } from "./tile.ts";
+
+export { Toast, type ToastVariant } from "./toast.ts";

package/src/input.ts

@@ -0,0 +1,30 @@
+/**
+ * The text input: OpenTUI's one-line input in the theme's input colors, with
+ * the accent cursor and a lighter background while focused.
+ *
+ * @module
+ */
+import { InputRenderable } from "@opentui/core";
+import type { CliRenderer, InputRenderableOptions } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+export interface InputOptions extends InputRenderableOptions {
+  readonly id: string;
+  readonly theme: Theme;
+}
+
+/** A one-line text input in the theme's colors; full width by default. */
+export class Input extends InputRenderable {
+  constructor(renderer: CliRenderer, { theme, ...options }: InputOptions) {
+    super(renderer, {
+      width: "100%",
+      backgroundColor: theme.bgInput,
+      focusedBackgroundColor: theme.bgSelected,
+      textColor: theme.fg,
+      focusedTextColor: theme.fg,
+      placeholderColor: theme.fgSubtle,
+      cursorColor: theme.accent,
+      ...options,
+    });
+  }
+}

package/src/menu-grid.ts

@@ -0,0 +1,279 @@
+/**
+ * The menu grid: sections of wrapping tiles, each under a section heading,
+ * in a scroll box the app owns. The arrow keys move to the nearest tile in
+ * that direction, across sections too.
+ *
+ * @module
+ */
+import type { CliRenderer, KeyEvent, ScrollBoxRenderable } from "@opentui/core";
+import { SectionHeading } from "./section-heading.ts";
+import type { Theme } from "./theme.ts";
+import { Tile } from "./tile.ts";
+
+export interface MenuGridItem {
+  readonly id: string;
+  readonly primary: string;
+  readonly secondary?: string | readonly string[];
+  readonly icon?: string;
+}
+
+export interface MenuGridSection {
+  readonly id: string;
+  /** No heading row when empty */
+  readonly title: string;
+  readonly icon?: string;
+  readonly items: readonly MenuGridItem[];
+}
+
+export interface MenuGridOptions {
+  /**
+   * The view's scroll box, which should wrap its content in rows
+   * (`contentOptions: { flexDirection: "row", flexWrap: "wrap" }`)
+   */
+  readonly scroll: ScrollBoxRenderable;
+  /** 28 columns by default */
+  readonly tileWidth?: number;
+}
+
+interface GridSection {
+  readonly items: readonly MenuGridItem[];
+  readonly heading: SectionHeading | undefined;
+}
+
+interface TilePosition {
+  readonly id: string;
+  readonly section: number;
+  readonly index: number;
+  readonly x: number;
+  readonly y: number;
+}
+
+type Direction = "left" | "right" | "up" | "down";
+
+const DIRECTION_KEYS = new Map<string, Direction>([
+  ["left", "left"],
+  ["right", "right"],
+  ["up", "up"],
+  ["down", "down"],
+]);
+
+/** Tiles in sections, filling a scroll box the app owns. */
+export class MenuGrid {
+  private readonly renderer: CliRenderer;
+  private readonly theme: Theme;
+  private readonly scroll: ScrollBoxRenderable;
+  private readonly tileWidth: number;
+  private sections: GridSection[] = [];
+  private readonly tiles = new Map<string, Tile>();
+  private sectionIndex = 0;
+  private tileIndex = 0;
+  private focused = false;
+
+  constructor(renderer: CliRenderer, theme: Theme, options: MenuGridOptions) {
+    this.renderer = renderer;
+    this.theme = theme;
+    this.scroll = options.scroll;
+    this.tileWidth = options.tileWidth ?? 28;
+
+    renderer.on("resize", () => {
+      if (this.focused) this.applySelection();
+    });
+  }
+
+  /** Whether there are any tiles */
+  get hasEntries(): boolean {
+    return this.tiles.size > 0;
+  }
+
+  /** Whether a tile is highlighted */
+  get isFocused(): boolean {
+    return this.focused;
+  }
+
+  /** The highlighted tile's id */
+  getSelectedId(): string | undefined {
+    return this.sections[this.sectionIndex]?.items[this.tileIndex]?.id;
+  }
+
+  /** Replaces the tiles; sections without items are skipped. */
+  setSections(sections: readonly MenuGridSection[]): void {
+    this.clearContent();
+    this.sectionIndex = 0;
+    this.tileIndex = 0;
+
+    for (const section of sections) {
+      if (section.items.length === 0) continue;
+
+      const heading =
+        section.title.length > 0
+          ? new SectionHeading(this.renderer, this.theme, {
+              id: `${this.scroll.id}-heading-${section.id}`,
+              title: section.title,
+              icon: section.icon,
+              marginTop: this.sections.length === 0 ? 0 : 1,
+            })
+          : undefined;
+
+      if (heading) this.scroll.add(heading.box);
+
+      this.sections.push({ items: section.items, heading });
+
+      for (const item of section.items) {
+        const tile = new Tile(this.renderer, this.theme, {
+          id: `${this.scroll.id}-tile-${item.id}`,
+          primary: item.primary,
+          secondary: item.secondary,
+          icon: item.icon,
+          width: this.tileWidth,
+        });
+
+        this.tiles.set(item.id, tile);
+        this.scroll.add(tile.box);
+      }
+    }
+
+    if (this.focused) this.applySelection();
+  }
+
+  /** One section without a heading. */
+  setItems(items: readonly MenuGridItem[]): void {
+    this.setSections([{ id: "default", title: "", items }]);
+  }
+
+  /** Changes one tile's text in place. */
+  updateItem(
+    id: string,
+    patch: {
+      readonly primary?: string;
+      readonly secondary?: string | readonly string[];
+    },
+  ): void {
+    const tile = this.tiles.get(id);
+
+    if (patch.primary !== undefined) tile?.setPrimary(patch.primary);
+
+    if (patch.secondary !== undefined) tile?.setSecondary(patch.secondary);
+  }
+
+  /** Removes every tile and heading. */
+  clear(): void {
+    this.clearContent();
+    this.sectionIndex = 0;
+    this.tileIndex = 0;
+    this.focused = false;
+  }
+
+  /** Highlights the selected tile. */
+  focus(): void {
+    if (this.tiles.size === 0) return;
+
+    this.focused = true;
+    this.applySelection();
+  }
+
+  /** Clears the highlight, keeping the selection. */
+  blur(): void {
+    this.focused = false;
+
+    for (const tile of this.tiles.values()) tile.setSelected(false);
+  }
+
+  /** Selects the first tile and scrolls to the top. */
+  resetSelection(): void {
+    this.sectionIndex = 0;
+    this.tileIndex = 0;
+    this.scroll.scrollTop = 0;
+    this.applySelection();
+  }
+
+  /** Handles the arrow keys; returns whether it used the key. */
+  handleKeyPress(key: KeyEvent): boolean {
+    const direction = DIRECTION_KEYS.get(key.name);
+
+    if (this.tiles.size === 0 || direction === undefined) return false;
+
+    if (!this.focused) this.focus();
+
+    this.move(direction);
+
+    return true;
+  }
+
+  private clearContent(): void {
+    for (const tile of this.tiles.values()) this.scroll.remove(tile.box);
+
+    for (const { heading } of this.sections)
+      if (heading) this.scroll.remove(heading.box);
+
+    this.tiles.clear();
+    this.sections = [];
+  }
+
+  /** Moves to the nearest tile in that direction, preferring the same line. */
+  private move(direction: Direction): void {
+    const positions = this.positions();
+    const current = positions.find(({ id }) => id === this.getSelectedId());
+
+    if (current === undefined) return;
+
+    let best: TilePosition | undefined;
+    let bestScore = Number.POSITIVE_INFINITY;
+
+    for (const candidate of positions) {
+      const dx = candidate.x - current.x;
+      const dy = candidate.y - current.y;
+      const horizontal = direction === "left" || direction === "right";
+      const ahead = horizontal ? dx : dy;
+      const across = horizontal ? dy : dx;
+      const forward = direction === "right" || direction === "down";
+      const distance = forward ? ahead : -ahead;
+
+      if (distance <= 0) continue;
+
+      const score = Math.abs(across) * 1000 + distance;
+
+      if (score >= bestScore) continue;
+
+      bestScore = score;
+      best = candidate;
+    }
+
+    if (best === undefined) return;
+
+    this.sectionIndex = best.section;
+    this.tileIndex = best.index;
+    this.applySelection();
+  }
+
+  private positions(): TilePosition[] {
+    return this.sections.flatMap(({ items }, section) =>
+      items.flatMap(({ id }, index) => {
+        const box = this.tiles.get(id)?.box;
+
+        return box === undefined
+          ? []
+          : [
+              {
+                id,
+                section,
+                index,
+                x: box.x + box.width / 2,
+                y: box.y + box.height / 2,
+              },
+            ];
+      }),
+    );
+  }
+
+  private applySelection(): void {
+    for (const tile of this.tiles.values()) tile.setSelected(false);
+
+    const id = this.getSelectedId();
+    const tile = id === undefined ? undefined : this.tiles.get(id);
+
+    if (!this.focused || tile === undefined) return;
+
+    tile.setSelected(true);
+    this.scroll.scrollChildIntoView(tile.box.id);
+  }
+}