@timmo001/groundwork-tui 0.0.0-stage → 0.4.1

package/src/status-list.ts

@@ -0,0 +1,372 @@
+/**
+ * The status list: two-row items colored by their state, with optional
+ * section headings, that scroll by whole rows and keep a row's section in
+ * view when they can.
+ *
+ * @module
+ */
+import { BoxRenderable, TextRenderable, bold, fg, t } from "@opentui/core";
+import type { CliRenderer, KeyEvent } from "@opentui/core";
+import { ScrollSurface } from "./scroll-surface.ts";
+import { surfaceBackground } from "./styles.ts";
+import type { Theme } from "./theme.ts";
+
+export interface StatusListItem<T> {
+  readonly id: string;
+  readonly title: string;
+  readonly description: string;
+  /** The title's color, usually a state slot such as `theme.green`. */
+  readonly color: string;
+  /** Starts a new section heading when it differs from the row above. */
+  readonly section?: string;
+  readonly value: T;
+}
+
+export interface StatusListOptions<T> {
+  readonly id: string;
+  readonly theme: Theme;
+  readonly items?: readonly StatusListItem<T>[];
+  /** Called on Enter or a click. */
+  readonly onSelect: (item: StatusListItem<T>) => void;
+  /** Called when the highlighted row changes. */
+  readonly onSelectionChanged?: (item: StatusListItem<T>) => void;
+  /** Whether Enter selects, true by default. */
+  readonly selectOnEnter?: boolean;
+}
+
+interface StatusListRow<T> {
+  readonly container: BoxRenderable;
+  readonly marker: TextRenderable;
+  readonly title: TextRenderable;
+  readonly description: TextRenderable;
+  readonly item: StatusListItem<T>;
+  readonly sectionHeader: BoxRenderable | undefined;
+}
+
+/** A two-row list of items with a state color and section headings. */
+export class StatusList<T> extends ScrollSurface {
+  private readonly listRenderer: CliRenderer;
+  private readonly listTheme: Theme;
+  private readonly onSelectItem: (item: StatusListItem<T>) => void;
+  private readonly onItemSelectionChanged:
+    ((item: StatusListItem<T>) => void) | undefined;
+  private readonly selectOnEnter: boolean;
+  private rows: StatusListRow<T>[] = [];
+  private items: readonly StatusListItem<T>[] = [];
+  private selectedIndex = 0;
+  private active = false;
+
+  constructor(renderer: CliRenderer, options: StatusListOptions<T>) {
+    super(renderer, {
+      id: options.id,
+      theme: options.theme,
+      flexGrow: 1,
+      flexShrink: 1,
+      minHeight: 0,
+      scrollY: true,
+      scrollX: false,
+      focusable: true,
+      backgroundColor: surfaceBackground(options.theme),
+      contentOptions: { flexDirection: "column", width: "100%" },
+    });
+    this.listRenderer = renderer;
+    this.listTheme = options.theme;
+    this.onSelectItem = options.onSelect;
+    this.onItemSelectionChanged = options.onSelectionChanged;
+    this.selectOnEnter = options.selectOnEnter ?? true;
+    this.setItems(options.items ?? []);
+  }
+
+  /** Replaces the rows, keeping `preferredId` or the current row selected. */
+  setItems(
+    items: readonly StatusListItem<T>[],
+    preferredId?: string | null,
+  ): void {
+    const selectedId = preferredId ?? this.getSelectedItem()?.id;
+
+    for (const row of this.scrollBox.getChildren()) this.scrollBox.remove(row);
+
+    this.items = items;
+
+    this.selectedIndex = Math.max(
+      0,
+      selectedId ? items.findIndex((item) => item.id === selectedId) : 0,
+    );
+
+    this.rows = [];
+    let section: string | undefined;
+    let sectionHeader: BoxRenderable | undefined;
+
+    for (const [index, item] of items.entries()) {
+      if (item.section && item.section !== section) {
+        section = item.section;
+        sectionHeader = this.createSection(item.section, index);
+        this.addContent(sectionHeader);
+      }
+
+      const row = this.createRow(item, index, sectionHeader);
+      this.rows.push(row);
+      this.addContent(row.container);
+    }
+
+    this.refresh();
+    this.ensureSelectionVisible();
+    this.emitSelection();
+  }
+
+  getSelectedItem(): StatusListItem<T> | undefined {
+    return this.items[this.selectedIndex];
+  }
+
+  /** Marks the list as the focused pane, and focuses it unless told not to. */
+  setActive(active: boolean, options?: { readonly focus?: boolean }): void {
+    this.active = active;
+
+    if (active && (options?.focus ?? true)) this.focus();
+    else this.blur();
+
+    this.refresh();
+  }
+
+  selectNext(): void {
+    this.moveSelection(1);
+  }
+
+  selectPrevious(): void {
+    this.moveSelection(-1);
+  }
+
+  /** Scrolls the selected row back into view, such as after a resize. */
+  realign(): void {
+    this.ensureSelectionVisible();
+    this.syncMarker();
+  }
+
+  override focus(): void {
+    this.listRenderer.focusRenderable(this);
+  }
+
+  override blur(): void {
+    this.listRenderer.blurRenderable(this);
+  }
+
+  override handleKeyPress(key: KeyEvent): boolean {
+    if (key.name === "up" || key.name === "down") {
+      this.moveSelection(key.name === "up" ? -1 : 1);
+
+      return true;
+    }
+
+    if (key.name === "pageup" || key.name === "pagedown") {
+      const page = this.completeItemsPerPage();
+      this.moveSelection(key.name === "pageup" ? -page : page, false);
+
+      return true;
+    }
+
+    if (key.name === "return" && this.selectOnEnter) {
+      const item = this.getSelectedItem();
+
+      if (item) this.onSelectItem(item);
+
+      return true;
+    }
+
+    return this.scrollBox.handleKeyPress(key);
+  }
+
+  private moveSelection(delta: number, wrap = true): void {
+    if (!this.items.length) return;
+
+    const next = wrap
+      ? (this.selectedIndex + delta + this.items.length) % this.items.length
+      : Math.max(
+          0,
+          Math.min(this.items.length - 1, this.selectedIndex + delta),
+        );
+
+    if (next === this.selectedIndex) return;
+
+    this.selectedIndex = next;
+    this.refresh();
+    this.ensureSelectionVisible();
+    this.emitSelection();
+  }
+
+  private activate(index: number): void {
+    if (index !== this.selectedIndex) {
+      this.selectedIndex = index;
+      this.refresh();
+      this.ensureSelectionVisible();
+      this.emitSelection();
+    }
+
+    const item = this.items[index];
+
+    if (item) this.onSelectItem(item);
+  }
+
+  private createSection(label: string, index: number): BoxRenderable {
+    const header = new BoxRenderable(this.listRenderer, {
+      id: `${this.id}-section-${index}`,
+      width: "100%",
+      height: 1,
+      flexShrink: 0,
+      paddingLeft: 1,
+    });
+
+    header.add(
+      new TextRenderable(this.listRenderer, {
+        content: t`${bold(fg(this.listTheme.fgSubtle)(label))}`,
+        height: 1,
+        wrapMode: "none",
+        truncate: true,
+      }),
+    );
+
+    return header;
+  }
+
+  private createRow(
+    item: StatusListItem<T>,
+    index: number,
+    sectionHeader: BoxRenderable | undefined,
+  ): StatusListRow<T> {
+    const container = new BoxRenderable(this.listRenderer, {
+      id: `${this.id}-row-${index}`,
+      flexDirection: "row",
+      width: "100%",
+      height: 2,
+      flexShrink: 0,
+      overflow: "hidden",
+      onMouseDown: (event) => {
+        if (event.button !== 0) return;
+
+        event.stopPropagation();
+        this.activate(index);
+      },
+    });
+
+    const marker = new TextRenderable(this.listRenderer, {
+      width: 2,
+      height: 2,
+      flexShrink: 0,
+      content: "",
+    });
+
+    const content = new BoxRenderable(this.listRenderer, {
+      flexDirection: "column",
+      flexGrow: 1,
+      minWidth: 0,
+      height: 2,
+    });
+
+    const line = {
+      height: 1,
+      flexShrink: 0,
+      wrapMode: "none",
+      truncate: true,
+      overflow: "hidden",
+      content: "",
+    } as const;
+
+    const title = new TextRenderable(this.listRenderer, line);
+    const description = new TextRenderable(this.listRenderer, line);
+
+    content.add(title);
+    content.add(description);
+    container.add(marker);
+    container.add(content);
+
+    return { container, marker, title, description, item, sectionHeader };
+  }
+
+  private refresh(): void {
+    const theme = this.listTheme;
+
+    for (const [index, row] of this.rows.entries()) {
+      const selected = index === this.selectedIndex;
+      const { color, title, description } = row.item;
+
+      row.container.backgroundColor =
+        selected && this.active ? theme.bgSelected : surfaceBackground(theme);
+
+      row.marker.content = t`${fg(selected ? color : theme.fgGhost)(selected ? "▌\n▌" : "  \n  ")}`;
+      row.title.content = t`${selected ? bold(fg(color)(title)) : fg(color)(title)}`;
+      row.description.content = t`${fg(theme.fgMuted)(description)}`;
+    }
+  }
+
+  private ensureSelectionVisible(): void {
+    const row = this.rows[this.selectedIndex];
+
+    if (!row) return;
+
+    const viewport = this.scrollBox.viewport.height;
+    const rowStart = this.childStart(row.container);
+
+    const contextStart = row.sectionHeader
+      ? this.childStart(row.sectionHeader)
+      : rowStart;
+
+    const rowEnd = rowStart + row.container.height;
+
+    const targetStart =
+      rowEnd - contextStart <= viewport ? contextStart : rowStart;
+
+    const current = this.scrollBox.scrollTop;
+    let target = current;
+
+    if (targetStart < current) target = targetStart;
+    else if (rowEnd > current + viewport) target = rowEnd - viewport;
+
+    this.scrollBox.scrollTop = this.completeChildBoundary(target);
+    this.syncMarker();
+  }
+
+  private completeItemsPerPage(): number {
+    const viewport = this.scrollBox.viewport.height;
+
+    if (viewport <= 0) return 1;
+
+    return Math.max(1, Math.floor(viewport / 2));
+  }
+
+  /** Rounds an offset down to the start of a whole child. */
+  private completeChildBoundary(offset: number): number {
+    const extent = Math.max(
+      0,
+      this.scrollBox.scrollHeight - this.scrollBox.viewport.height,
+    );
+
+    const bounded = Math.max(0, Math.min(offset, extent));
+    const starts: number[] = [];
+    let start = 0;
+
+    for (const child of this.scrollBox.getChildren()) {
+      if (start <= bounded) starts.push(start);
+
+      start += child.height;
+    }
+
+    return Math.max(0, ...starts);
+  }
+
+  private childStart(target: BoxRenderable): number {
+    let start = 0;
+
+    for (const child of this.scrollBox.getChildren()) {
+      if (child === target) return start;
+
+      start += child.height;
+    }
+
+    return start;
+  }
+
+  private emitSelection(): void {
+    const item = this.getSelectedItem();
+
+    if (item) this.onItemSelectionChanged?.(item);
+  }
+}

package/src/styles.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared surface colors, so panes leave a transparent terminal see-through.
+ *
+ * @module
+ */
+import type { Theme } from "./theme.ts";
+
+/** A pane's background, or none when the theme keeps the terminal's own. */
+export const surfaceBackground = (theme: Theme): string =>
+  theme.transparent ? "transparent" : theme.bgElevated;

package/src/theme.ts

@@ -0,0 +1,100 @@
+/**
+ * Terminal colors from Groundwork's tokens: the roles of one theme and mode,
+ * placed into the slots the terminal components use, and picked with
+ * `GW_THEME` and `GW_MODE` (Base and dark by default).
+ *
+ * @module
+ */
+import { opentuiThemes } from "@timmo001/groundwork-tokens/opentui";
+import { Config, Effect } from "effect";
+
+/** Semantic color slots for the TUI */
+export interface Theme {
+  /** App background */
+  readonly bg: string;
+  /** Elevated surface (pane/card background) */
+  readonly bgElevated: string;
+  /** Selected row background */
+  readonly bgSelected: string;
+  /** Focused input background */
+  readonly bgInput: string;
+  /** Accent for selections, highlights, cursors and emphasis text */
+  readonly accent: string;
+  /** Text on the accent */
+  readonly accentFg: string;
+  /** Secondary surface (separators, secondary selection background) */
+  readonly surface: string;
+  /** Primary foreground text */
+  readonly fg: string;
+  /** Muted secondary text */
+  readonly fgMuted: string;
+  /** Dim text for subtle UI elements */
+  readonly fgSubtle: string;
+  /** Dimmest text for ghost-level elements */
+  readonly fgGhost: string;
+  /** Success state */
+  readonly green: string;
+  /** Error state */
+  readonly red: string;
+  /** Warning or in-progress state */
+  readonly yellow: string;
+  /** Whether panels skip painting backgrounds to let terminal transparency through */
+  readonly transparent: boolean;
+}
+
+type ThemeId = keyof typeof opentuiThemes;
+
+type Roles = (typeof opentuiThemes)["base"]["dark"];
+
+/** Places a theme's terminal roles into the TUI's slots. */
+const fromRoles = (roles: Roles): Theme => ({
+  bg: roles["surface-lower"],
+  bgElevated: roles["surface-default"],
+  bgSelected: roles["fill-neutral-selected"],
+  bgInput: roles["surface-raised"],
+  accent: roles.accent,
+  accentFg: roles["on-accent"],
+  surface: roles["border-normal"],
+  fg: roles["text-primary"],
+  fgMuted: roles["text-secondary"],
+  fgSubtle: roles["text-disabled"],
+  fgGhost: roles["border-loud"],
+  green: roles.success,
+  red: roles.danger,
+  yellow: roles.warning,
+  transparent: false,
+});
+
+const isTheme = (id: string): id is ThemeId => id in opentuiThemes;
+
+/** Base, dark: the default when nothing is picked. */
+export const DEFAULT_THEME: Theme = fromRoles(opentuiThemes.base.dark);
+
+/**
+ * A core theme's slots in one mode, or Base and dark when there's no such
+ * theme or mode.
+ */
+export const themeFor = (id: string, mode: string): Theme => {
+  if (!isTheme(id)) return DEFAULT_THEME;
+
+  const roles = Object.entries(opentuiThemes[id]).find(
+    ([name]) => name === mode,
+  )?.[1];
+
+  return roles === undefined ? DEFAULT_THEME : fromRoles(roles);
+};
+
+/**
+ * Loads the theme from `GW_THEME` (a core theme's id) and `GW_MODE` (`light`,
+ * `dark` or `darker`), falling back to Base and dark.
+ */
+export const loadTheme: Effect.Effect<Theme> = Effect.gen(function* () {
+  const id = yield* Config.String("GW_THEME").pipe(Config.withDefault("base"));
+
+  const mode = yield* Config.Literals(
+    ["light", "dark", "darker"],
+    "GW_MODE",
+  ).pipe(Config.withDefault("dark"));
+
+  return themeFor(id, mode);
+}).pipe(Effect.orElseSucceed(() => DEFAULT_THEME));

package/src/tile.ts

@@ -0,0 +1,126 @@
+/**
+ * The tile: a compact rounded card with a title, an optional icon, and a
+ * secondary line whose parts are joined with dots. Selection fills it.
+ *
+ * @module
+ */
+import {
+  BoxRenderable,
+  StyledText,
+  TextRenderable,
+  fg,
+  t,
+} from "@opentui/core";
+import type { CliRenderer, TextChunk } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+export interface TileOptions {
+  readonly id: string;
+  /** Primary text */
+  readonly primary: string;
+  /** Secondary text, or parts joined with ` • ` */
+  readonly secondary?: string | readonly string[] | undefined;
+  /** Nerd Font icon shown before the primary text */
+  readonly icon?: string | undefined;
+  /** 28 columns by default */
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/** A compact rounded card; add `box` to the parent. */
+export class Tile {
+  /** The tile's card */
+  readonly box: BoxRenderable;
+  private readonly theme: Theme;
+  private readonly primaryText: TextRenderable;
+  private readonly secondaryText: TextRenderable | undefined;
+  private readonly icon: string | undefined;
+  private primary: string;
+  private secondary: string | readonly string[] | undefined;
+  private selected = false;
+
+  constructor(renderer: CliRenderer, theme: Theme, options: TileOptions) {
+    this.theme = theme;
+    this.primary = options.primary;
+    this.secondary = options.secondary;
+    this.icon = options.icon;
+
+    this.box = new BoxRenderable(renderer, {
+      id: options.id,
+      flexDirection: "column",
+      flexShrink: 0,
+      width: options.width ?? 28,
+      paddingX: 1,
+      borderStyle: "rounded",
+      borderColor: theme.accent,
+      shouldFill: false,
+    });
+
+    if (options.height !== undefined) this.box.height = options.height;
+
+    this.primaryText = new TextRenderable(renderer, {
+      id: `${options.id}-primary`,
+      content: "",
+      flexGrow: 1,
+    });
+
+    if (options.secondary === undefined) {
+      this.primaryText.marginTop = 1;
+      this.primaryText.marginBottom = 1;
+    }
+
+    this.box.add(this.primaryText);
+
+    if (options.secondary !== undefined) {
+      this.secondaryText = new TextRenderable(renderer, {
+        id: `${options.id}-secondary`,
+        content: "",
+        marginTop: 1,
+      });
+
+      this.box.add(this.secondaryText);
+    }
+
+    this.paint();
+  }
+
+  setPrimary(primary: string): void {
+    this.primary = primary;
+    this.paint();
+  }
+
+  /** Changes the secondary line, when the tile was made with one. */
+  setSecondary(secondary: string | readonly string[]): void {
+    this.secondary = secondary;
+    this.paint();
+  }
+
+  setSelected(selected: boolean): void {
+    this.selected = selected;
+    this.box.shouldFill = selected;
+    this.box.backgroundColor = selected ? this.theme.bgSelected : "transparent";
+    this.paint();
+  }
+
+  private paint(): void {
+    const theme = this.theme;
+    const color = this.selected ? theme.accent : theme.fg;
+
+    this.primaryText.content = this.icon
+      ? t`${fg(color)(this.icon)} ${fg(color)(this.primary)}`
+      : t`${fg(color)(this.primary)}`;
+
+    if (this.secondaryText === undefined || this.secondary === undefined)
+      return;
+
+    const chunks: TextChunk[] = [this.secondary]
+      .flat()
+      .flatMap((part, index) =>
+        index === 0
+          ? [fg(theme.fgMuted)(part)]
+          : [fg(theme.fgSubtle)(" • "), fg(theme.fgMuted)(part)],
+      );
+
+    this.secondaryText.content = new StyledText(chunks);
+  }
+}

package/src/toast.ts

@@ -0,0 +1,102 @@
+/**
+ * The toast: one short message in the top-right corner that closes itself.
+ * Showing another with the same id replaces it in place, and a new id
+ * replaces the old toast, so toasts never stack. Use one only when nothing
+ * on screen can show the result, such as a command run in the background.
+ *
+ * @module
+ */
+import { BoxRenderable, TextRenderable, bold, fg, t } from "@opentui/core";
+import type { CliRenderer } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+export type ToastVariant = "info" | "success" | "error";
+
+const DISMISS_MS: Readonly<Record<ToastVariant, number>> = {
+  info: 5000,
+  success: 3000,
+  error: 8000,
+};
+
+const ICON: Readonly<Record<ToastVariant, string>> = {
+  info: "󰋼",
+  success: "󰄬",
+  error: "󰅚",
+};
+
+const variantColor = (theme: Theme, variant: ToastVariant): string => {
+  switch (variant) {
+    case "info":
+      return theme.accent;
+    case "success":
+      return theme.green;
+    case "error":
+      return theme.red;
+  }
+};
+
+/** A single-slot toast. */
+export class Toast {
+  private readonly theme: Theme;
+  private readonly root: BoxRenderable;
+  private readonly text: TextRenderable;
+  private currentId: string | undefined;
+  private timeout: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(renderer: CliRenderer, theme: Theme, id = "toast") {
+    this.theme = theme;
+
+    this.root = new BoxRenderable(renderer, {
+      id,
+      position: "absolute",
+      top: 1,
+      right: 2,
+      width: 50,
+      height: 3,
+      borderStyle: "rounded",
+      borderColor: theme.accent,
+      backgroundColor: theme.bgElevated,
+      paddingLeft: 1,
+      paddingRight: 1,
+      alignItems: "center",
+      zIndex: 200,
+      visible: false,
+    });
+
+    this.text = new TextRenderable(renderer, {
+      id: `${id}-text`,
+      content: "",
+      wrapMode: "none",
+      truncate: true,
+    });
+
+    this.root.add(this.text);
+    renderer.root.add(this.root);
+  }
+
+  /** The id of the toast showing, if any. */
+  get id(): string | undefined {
+    return this.currentId;
+  }
+
+  /** Shows a message, replacing whatever toast is showing. */
+  show(id: string, message: string, variant: ToastVariant): void {
+    clearTimeout(this.timeout);
+
+    const color = variantColor(this.theme, variant);
+
+    this.currentId = id;
+    this.root.borderColor = color;
+    this.text.content = t`${fg(color)(ICON[variant])}  ${bold(fg(this.theme.fg)(message))}`;
+    this.root.visible = true;
+    this.timeout = setTimeout(() => this.dismiss(), DISMISS_MS[variant]);
+  }
+
+  /** Hides the toast. */
+  dismiss(): void {
+    clearTimeout(this.timeout);
+    this.timeout = undefined;
+    this.currentId = undefined;
+    this.root.visible = false;
+  }
+}