@timmo001/groundwork-tui 0.0.0-stage → 0.0.0

package/src/collapsible.ts

@@ -0,0 +1,119 @@
+/**
+ * The collapsible: a one-row trigger with a ▸ or ▾ marker over a panel that
+ * shows only while open. Enter, Space or a click on the trigger toggles it.
+ *
+ * @module
+ */
+import { BoxRenderable, TextRenderable, fg, t } from "@opentui/core";
+import type { CliRenderer, KeyEvent } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+export interface CollapsibleOptions {
+  readonly id: string;
+  readonly theme: Theme;
+  readonly label: string;
+  readonly open: boolean;
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+}
+
+/** A focusable trigger over a panel; add the panel's content to `panel`. */
+export class Collapsible extends BoxRenderable {
+  /** Holds the content shown while open */
+  readonly panel: BoxRenderable;
+  private readonly theme: Theme;
+  private readonly trigger: TextRenderable;
+  private readonly onOpenChange: ((open: boolean) => void) | undefined;
+  private label: string;
+  private isOpen: boolean;
+
+  constructor(renderer: CliRenderer, options: CollapsibleOptions) {
+    super(renderer, {
+      id: options.id,
+      flexDirection: "column",
+      width: "100%",
+      flexShrink: 0,
+      focusable: true,
+    });
+
+    this.theme = options.theme;
+    this.onOpenChange = options.onOpenChange;
+    this.label = options.label;
+    this.isOpen = options.open;
+
+    this.trigger = new TextRenderable(renderer, {
+      id: `${options.id}-trigger`,
+      content: "",
+      height: 1,
+      flexShrink: 0,
+      wrapMode: "none",
+      truncate: true,
+      onMouseDown: (event) => {
+        if (event.button !== 0) return;
+
+        this.focus();
+        this.toggle();
+      },
+    });
+
+    this.panel = new BoxRenderable(renderer, {
+      id: `${options.id}-panel`,
+      flexDirection: "column",
+      width: "100%",
+      flexShrink: 0,
+      paddingLeft: 2,
+    });
+
+    this.add(this.trigger);
+    this.add(this.panel);
+    this.refresh();
+  }
+
+  /** Whether the panel shows. */
+  get open(): boolean {
+    return this.isOpen;
+  }
+
+  /** Opens or closes the panel without calling `onOpenChange`. */
+  set open(open: boolean) {
+    this.isOpen = open;
+    this.refresh();
+  }
+
+  /** Changes the trigger's label. */
+  setLabel(label: string): void {
+    this.label = label;
+    this.refresh();
+  }
+
+  override focus(): void {
+    super.focus();
+    this.refresh();
+  }
+
+  override blur(): void {
+    super.blur();
+    this.refresh();
+  }
+
+  override handleKeyPress(key: KeyEvent): boolean {
+    if (key.name !== "return" && key.name !== "space") return false;
+
+    this.toggle();
+
+    return true;
+  }
+
+  private toggle(): void {
+    this.open = !this.isOpen;
+    this.onOpenChange?.(this.isOpen);
+  }
+
+  private refresh(): void {
+    if (this.isDestroyed || this.trigger.isDestroyed) return;
+
+    const color = this.focused ? this.theme.accent : this.theme.fgMuted;
+
+    this.trigger.content = t`${fg(color)(`${this.isOpen ? "▾" : "▸"} ${this.label}`)}`;
+    this.panel.visible = this.isOpen;
+  }
+}

package/src/confirm-dialog.ts

@@ -0,0 +1,121 @@
+/**
+ * The confirm dialog: a question with Cancel and Confirm buttons. Y or the
+ * Confirm button confirms; Escape, a click outside or Cancel closes it.
+ *
+ * @module
+ */
+import { BoxRenderable, TextRenderable, fg, t } from "@opentui/core";
+import type { CliRenderer, KeyEvent } from "@opentui/core";
+import { Button } from "./button.ts";
+import { Dialog } from "./dialog.ts";
+import type { Theme } from "./theme.ts";
+
+export interface ConfirmDialogOptions {
+  readonly id: string;
+  readonly theme: Theme;
+  /** For a destructive action: the red border and Confirm button */
+  readonly destructive?: boolean | undefined;
+  /** "Confirm" by default */
+  readonly confirmLabel?: string | undefined;
+  readonly onConfirm: () => void;
+  /** Runs when it closes without confirming */
+  readonly onCancel?: (() => void) | undefined;
+}
+
+/** A yes or no question in a dialog. */
+export class ConfirmDialog {
+  private readonly renderer: CliRenderer;
+  private readonly dialog: Dialog;
+  private readonly theme: Theme;
+  private readonly message: TextRenderable;
+  private readonly onConfirm: () => void;
+
+  constructor(renderer: CliRenderer, options: ConfirmDialogOptions) {
+    this.renderer = renderer;
+    this.theme = options.theme;
+    this.onConfirm = options.onConfirm;
+
+    this.dialog = new Dialog(renderer, {
+      id: options.id,
+      theme: options.theme,
+      title: "",
+      color: options.destructive === true ? options.theme.red : undefined,
+      height: 8,
+      help: [
+        { key: "y", action: "confirm" },
+        { key: "Tab", action: "move" },
+        { key: "Esc", action: "cancel" },
+      ],
+      onClose: options.onCancel,
+    });
+
+    this.message = new TextRenderable(renderer, {
+      id: `${options.id}-message`,
+      content: "",
+      flexGrow: 1,
+    });
+
+    const buttons = new BoxRenderable(renderer, {
+      id: `${options.id}-buttons`,
+      flexDirection: "row",
+      justifyContent: "flex-end",
+      gap: 2,
+      flexShrink: 0,
+    });
+
+    const cancel = new Button(renderer, {
+      id: `${options.id}-cancel`,
+      theme: options.theme,
+      label: "Cancel",
+      onPress: () => this.dialog.close(),
+    });
+
+    const confirm = new Button(renderer, {
+      id: `${options.id}-confirm`,
+      theme: options.theme,
+      label: options.confirmLabel ?? "Confirm",
+      variant: options.destructive === true ? "destructive" : "primary",
+      onPress: () => this.confirm(),
+    });
+
+    buttons.add(cancel);
+    buttons.add(confirm);
+    this.dialog.body.add(this.message);
+    this.dialog.body.add(buttons);
+    this.dialog.setFocusables([cancel, confirm]);
+
+    renderer.keyInput.prependListener("keypress", this.onKey);
+  }
+
+  /** Whether it's open. */
+  get visible(): boolean {
+    return this.dialog.visible;
+  }
+
+  /** Asks the question; Cancel has focus, so Enter alone never confirms. */
+  show(title: string, message: string): void {
+    this.dialog.setTitle(title);
+    this.message.content = t`${fg(this.theme.fg)(message)}`;
+    this.dialog.show();
+  }
+
+  /** Removes the dialog. */
+  destroy(): void {
+    this.renderer.keyInput.off("keypress", this.onKey);
+    this.dialog.destroy();
+  }
+
+  private confirm(): void {
+    this.dialog.hide();
+    this.onConfirm();
+  }
+
+  private readonly onKey = (key: KeyEvent): void => {
+    if (!this.dialog.visible || key.name !== "y" || key.ctrl || key.meta)
+      return;
+
+    key.preventDefault();
+    key.stopPropagation();
+    this.confirm();
+  };
+}

package/src/dialog.ts

@@ -0,0 +1,251 @@
+/**
+ * The dialog: a centered, bordered panel over the current view, with a
+ * title, an optional description, a body and a key hint line. Only one is
+ * open at a time: opening another closes the first. Escape or a click outside
+ * closes it, and `onClose` runs once per close.
+ *
+ * @module
+ */
+import { BoxRenderable, TextRenderable, bold, fg, t } from "@opentui/core";
+import type { CliRenderer, KeyEvent, Renderable } from "@opentui/core";
+import { formatHelpBar } from "./help-bar.ts";
+import type { HelpEntry } from "./help-bar.ts";
+import type { Theme } from "./theme.ts";
+
+export interface DialogOptions {
+  readonly id: string;
+  readonly theme: Theme;
+  readonly title: string;
+  readonly description?: string | undefined;
+  /** The border and title color; the accent by default */
+  readonly color?: string | undefined;
+  /** 58 by default, and never wider than the terminal */
+  readonly width?: number | undefined;
+  /** 14 by default, and never taller than the terminal */
+  readonly height?: number | undefined;
+  /** The key hints along the bottom; Escape to close by default */
+  readonly help?: readonly HelpEntry[] | undefined;
+  /** Runs once each time the dialog closes, however it closed */
+  readonly onClose?: (() => void) | undefined;
+}
+
+const CLOSE_HELP: readonly HelpEntry[] = [{ key: "Esc", action: "close" }];
+
+/** One dialog at a time; add its content to `body`. */
+export class Dialog {
+  private static open: Dialog | undefined;
+  /** Holds the dialog's content */
+  readonly body: BoxRenderable;
+  private readonly renderer: CliRenderer;
+  private readonly options: DialogOptions;
+  private readonly overlay: BoxRenderable;
+  private readonly panel: BoxRenderable;
+  private readonly titleText: TextRenderable;
+  private readonly helpText: TextRenderable;
+  private focusables: readonly Renderable[] = [];
+  private previousFocus: Renderable | undefined;
+  private height: number;
+
+  constructor(renderer: CliRenderer, options: DialogOptions) {
+    this.renderer = renderer;
+    this.options = options;
+    this.height = options.height ?? 14;
+
+    const color = options.color ?? options.theme.accent;
+
+    this.overlay = new BoxRenderable(renderer, {
+      id: options.id,
+      position: "absolute",
+      width: "100%",
+      height: "100%",
+      zIndex: 160,
+      visible: false,
+      onMouseDown: (event) => {
+        if (event.target === this.overlay) this.close();
+      },
+    });
+
+    this.panel = new BoxRenderable(renderer, {
+      id: `${options.id}-panel`,
+      position: "absolute",
+      flexDirection: "column",
+      borderStyle: "rounded",
+      borderColor: color,
+      backgroundColor: options.theme.bgElevated,
+      paddingLeft: 1,
+      paddingRight: 1,
+    });
+
+    this.titleText = new TextRenderable(renderer, {
+      id: `${options.id}-title`,
+      content: t`${bold(fg(color)(options.title))}`,
+      height: 1,
+      flexShrink: 0,
+      wrapMode: "none",
+      truncate: true,
+    });
+
+    this.panel.add(this.titleText);
+
+    if (options.description !== undefined) {
+      this.panel.add(
+        new TextRenderable(renderer, {
+          id: `${options.id}-description`,
+          content: t`${fg(options.theme.fgMuted)(options.description)}`,
+          flexShrink: 0,
+        }),
+      );
+    }
+
+    this.body = new BoxRenderable(renderer, {
+      id: `${options.id}-body`,
+      flexDirection: "column",
+      width: "100%",
+      flexGrow: 1,
+      minHeight: 0,
+      marginTop: 1,
+    });
+
+    this.helpText = new TextRenderable(renderer, {
+      id: `${options.id}-help`,
+      content: formatHelpBar(options.theme, options.help ?? CLOSE_HELP),
+      height: 1,
+      flexShrink: 0,
+      wrapMode: "none",
+      truncate: true,
+    });
+
+    this.panel.add(this.body);
+    this.panel.add(this.helpText);
+    this.overlay.add(this.panel);
+    renderer.root.add(this.overlay);
+
+    renderer.keyInput.prependListener("keypress", this.onKey);
+    renderer.on("resize", this.onResize);
+  }
+
+  /** Whether this dialog is open. */
+  get visible(): boolean {
+    return this.overlay.visible;
+  }
+
+  /** Changes the title. */
+  setTitle(title: string): void {
+    const color = this.options.color ?? this.options.theme.accent;
+
+    this.titleText.content = t`${bold(fg(color)(title))}`;
+  }
+
+  /** Changes the height, such as to fit a new list. */
+  setHeight(height: number): void {
+    this.height = height;
+
+    if (this.visible) this.measure();
+  }
+
+  /**
+   * Sets what Tab and Shift+Tab move between, in order. The first gets focus
+   * when the dialog opens.
+   */
+  setFocusables(focusables: readonly Renderable[]): void {
+    this.focusables = focusables;
+
+    if (this.visible) this.focusables[0]?.focus();
+  }
+
+  /** Opens the dialog, closing any other that's open. */
+  show(): void {
+    if (this.visible) return;
+
+    Dialog.open?.close();
+    Dialog.open = this;
+
+    this.previousFocus = this.renderer.currentFocusedRenderable ?? undefined;
+    this.previousFocus?.blur();
+    this.measure();
+    this.overlay.visible = true;
+    this.focusables[0]?.focus();
+  }
+
+  /** Closes the dialog, gives focus back and runs `onClose`. */
+  close(): void {
+    if (!this.visible) return;
+
+    this.hide();
+    this.options.onClose?.();
+  }
+
+  /** Closes the dialog without running `onClose`, such as after a choice. */
+  hide(): void {
+    if (!this.visible) return;
+
+    this.overlay.visible = false;
+
+    for (const focusable of this.focusables) focusable.blur();
+
+    if (Dialog.open === this) Dialog.open = undefined;
+
+    this.previousFocus?.focus();
+    this.previousFocus = undefined;
+  }
+
+  /** Removes the dialog and stops listening for keys. */
+  destroy(): void {
+    this.hide();
+    this.renderer.keyInput.off("keypress", this.onKey);
+    this.renderer.off("resize", this.onResize);
+    this.renderer.root.remove(this.overlay);
+  }
+
+  private readonly onKey = (key: KeyEvent): void => {
+    if (!this.visible) return;
+
+    if (key.name === "escape") {
+      key.preventDefault();
+      key.stopPropagation();
+      this.close();
+
+      return;
+    }
+
+    if (key.name !== "tab" || this.focusables.length === 0) return;
+
+    key.preventDefault();
+    key.stopPropagation();
+
+    const count = this.focusables.length;
+    const current = this.renderer.currentFocusedRenderable;
+
+    const index = Math.max(
+      0,
+      this.focusables.findIndex((focusable) => focusable === current),
+    );
+
+    this.focusables[index]?.blur();
+    this.focusables[(index + (key.shift ? count - 1 : 1)) % count]?.focus();
+  };
+
+  private readonly onResize = (): void => {
+    if (this.visible) this.measure();
+  };
+
+  private measure(): void {
+    const width = Math.max(
+      1,
+      Math.min(this.options.width ?? 58, this.renderer.width - 4),
+    );
+
+    const height = Math.max(1, Math.min(this.height, this.renderer.height - 2));
+
+    this.panel.width = width;
+    this.panel.height = height;
+    this.panel.left = Math.max(
+      0,
+      Math.floor((this.renderer.width - width) / 2),
+    );
+    this.panel.top = Math.max(
+      0,
+      Math.floor((this.renderer.height - height) / 2),
+    );
+  }
+}

package/src/filter-bar.ts

@@ -0,0 +1,15 @@
+/**
+ * The filter bar: a dimmed `/` when there's no filter, or an accented `/`
+ * and the filter text while filtering.
+ *
+ * @module
+ */
+import { fg, t } from "@opentui/core";
+import type { StyledText } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+/** Formats the filter bar for the current filter text. */
+export const formatFilterBar = (theme: Theme, filter: string): StyledText =>
+  filter.length === 0
+    ? t`${fg(theme.fgSubtle)("/")}`
+    : t`${fg(theme.accent)("/")} ${fg(theme.fg)(filter)}`;

package/src/header-bar.ts

@@ -0,0 +1,93 @@
+/**
+ * The header bar: one line with the breadcrumb title, a status dot and label,
+ * and details on the right that drop off when the terminal is too narrow.
+ *
+ * @module
+ */
+import { StyledText, bold, fg } from "@opentui/core";
+import type { TextChunk } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+/** How the status reads: working, waiting, failed or off. */
+export type HeaderTone = "ok" | "pending" | "error" | "off";
+
+/** What the header bar shows after the title. */
+export interface HeaderStatus {
+  readonly tone: HeaderTone;
+  /** Such as "Connected" or "Syncing" */
+  readonly label: string;
+  /**
+   * Shown dimmed after the label, in order, until the line runs out of
+   * room, such as the host or the signed-in user.
+   */
+  readonly details?: readonly string[] | undefined;
+}
+
+const SEPARATOR = " › ";
+
+const GAP = "   ";
+
+const STATUS_DOT: Readonly<Record<HeaderTone, string>> = {
+  ok: "●",
+  pending: "◌",
+  error: "✗",
+  off: "○",
+};
+
+const toneColor = (theme: Theme, tone: HeaderTone): string => {
+  switch (tone) {
+    case "ok":
+      return theme.green;
+    case "pending":
+      return theme.yellow;
+    case "error":
+      return theme.red;
+    case "off":
+      return theme.fgSubtle;
+  }
+};
+
+/**
+ * Formats the header bar to fit `width` columns: the title parts as a
+ * breadcrumb (earlier parts dimmed, the last bold in the accent), the status,
+ * then as many details as fit.
+ */
+export const formatHeaderBar = (
+  theme: Theme,
+  titleParts: readonly string[],
+  status: HeaderStatus,
+  width: number,
+): StyledText => {
+  const last = titleParts.at(-1) ?? "";
+  const prefix = titleParts.slice(0, -1).join(SEPARATOR);
+
+  const title: TextChunk[] =
+    prefix.length === 0
+      ? [bold(fg(theme.accent)(last))]
+      : [
+          fg(theme.fgMuted)(prefix),
+          fg(theme.fgSubtle)(SEPARATOR),
+          bold(fg(theme.accent)(last)),
+        ];
+
+  const color = toneColor(theme, status.tone);
+  const dot = STATUS_DOT[status.tone];
+
+  const chunks: TextChunk[] = [
+    ...title,
+    fg(theme.fgSubtle)(GAP),
+    fg(color)(`${dot} ${status.label}`),
+  ];
+
+  let used = chunks.reduce((total, chunk) => total + chunk.text.length, 0);
+
+  for (const detail of status.details ?? []) {
+    used += GAP.length + detail.length;
+
+    if (used > width - 1) break;
+
+    chunks.push(fg(theme.fgSubtle)(GAP), fg(theme.fgMuted)(detail));
+  }
+
+  return new StyledText(chunks);
+};