@timmo001/groundwork-tui 0.0.0-stage → 0.0.0

package/src/radio-group.ts

@@ -0,0 +1,146 @@
+/**
+ * The radio group: a focusable list of two-line choices, the label and a
+ * description, where one is always picked. Arrow keys move the pick, Enter or
+ * Space activates it, and a click picks a choice.
+ *
+ * @module
+ */
+import { BoxRenderable, TextRenderable, bold, fg, t } from "@opentui/core";
+import type { CliRenderer, KeyEvent } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+export interface RadioChoice<Value extends string> {
+  readonly value: Value;
+  readonly label: string;
+  readonly description?: string | undefined;
+  /** The picked label's color; the accent by default */
+  readonly color?: string | undefined;
+}
+
+export interface RadioGroupOptions<Value extends string> {
+  readonly id: string;
+  readonly theme: Theme;
+  /** At least one */
+  readonly choices: readonly [RadioChoice<Value>, ...RadioChoice<Value>[]];
+  readonly value: Value;
+  /** Called when the pick moves */
+  readonly onValueChange?: ((value: Value) => void) | undefined;
+  /** Called on Enter or Space */
+  readonly onActivate?: ((value: Value) => void) | undefined;
+}
+
+/** A focusable group of choices with one always picked. */
+export class RadioGroup<Value extends string> extends BoxRenderable {
+  private readonly theme: Theme;
+  private readonly choices: readonly [
+    RadioChoice<Value>,
+    ...RadioChoice<Value>[],
+  ];
+  private readonly rows: readonly TextRenderable[];
+  private readonly onValueChange: ((value: Value) => void) | undefined;
+  private readonly onActivate: ((value: Value) => void) | undefined;
+  private selectedIndex: number;
+
+  constructor(renderer: CliRenderer, options: RadioGroupOptions<Value>) {
+    super(renderer, {
+      id: options.id,
+      flexDirection: "column",
+      width: "100%",
+      height: options.choices.length * 2,
+      flexShrink: 0,
+      focusable: true,
+    });
+
+    this.theme = options.theme;
+    this.choices = options.choices;
+    this.onValueChange = options.onValueChange;
+    this.onActivate = options.onActivate;
+
+    this.selectedIndex = Math.max(
+      0,
+      options.choices.findIndex((choice) => choice.value === options.value),
+    );
+
+    this.rows = options.choices.map((choice, index) => {
+      const row = new TextRenderable(renderer, {
+        id: `${options.id}-${choice.value}`,
+        content: "",
+        height: 2,
+        flexShrink: 0,
+        wrapMode: "none",
+        truncate: true,
+        onMouseDown: (event) => {
+          if (event.button !== 0) return;
+
+          this.focus();
+          this.select(index);
+        },
+      });
+
+      this.add(row);
+
+      return row;
+    });
+
+    this.refresh();
+  }
+
+  /** The picked choice's value. */
+  get value(): Value {
+    return (this.choices[this.selectedIndex] ?? this.choices[0]).value;
+  }
+
+  /** Picks a choice without calling `onValueChange`. */
+  set value(value: Value) {
+    const index = this.choices.findIndex((choice) => choice.value === value);
+
+    if (index >= 0) this.select(index, false);
+  }
+
+  override handleKeyPress(key: KeyEvent): boolean {
+    const count = this.choices.length;
+
+    switch (key.name) {
+      case "up":
+      case "left":
+        this.select((this.selectedIndex - 1 + count) % count);
+
+        return true;
+      case "down":
+      case "right":
+        this.select((this.selectedIndex + 1) % count);
+
+        return true;
+      case "return":
+      case "space":
+        this.onActivate?.(this.value);
+
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  private select(index: number, emit = true): void {
+    this.selectedIndex = index;
+    this.refresh();
+
+    if (emit) this.onValueChange?.(this.value);
+  }
+
+  private refresh(): void {
+    for (const [index, row] of this.rows.entries()) {
+      const choice = this.choices[index] ?? this.choices[0];
+      const picked = index === this.selectedIndex;
+
+      const color = picked
+        ? (choice.color ?? this.theme.accent)
+        : this.theme.fgMuted;
+
+      const label = `${picked ? "●" : "○"} ${choice.label}`;
+      const description = `  ${choice.description ?? ""}`;
+
+      row.content = t`${picked ? bold(fg(color)(label)) : fg(color)(label)}\n${fg(this.theme.fgSubtle)(description)}`;
+    }
+  }
+}

package/src/scroll-surface.ts

@@ -0,0 +1,146 @@
+/**
+ * The scroll surface: a scroll box with a one-column position marker in place
+ * of the native scrollbar, so the gutter never changes the content's width.
+ *
+ * @module
+ */
+import {
+  BoxRenderable,
+  ScrollBoxRenderable,
+  TextRenderable,
+  fg,
+  t,
+} from "@opentui/core";
+import type { CliRenderer, ScrollBoxOptions } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+export interface ScrollSurfaceOptions extends ScrollBoxOptions {
+  readonly theme: Theme;
+}
+
+/** Draws the marker column: a thumb of `┃` on a track of `│`. */
+const renderMarker = (
+  viewport: number,
+  extent: number,
+  offset: number,
+): string => {
+  if (viewport <= 0) return "";
+
+  if (extent === 0)
+    return Array.from({ length: viewport }, () => " ").join("\n");
+
+  const thumb = Math.max(
+    1,
+    Math.floor((viewport * viewport) / (viewport + extent)),
+  );
+
+  const start = Math.round((offset / extent) * Math.max(0, viewport - thumb));
+
+  return Array.from({ length: viewport }, (_, row) =>
+    row >= start && row < start + thumb ? "┃" : "│",
+  ).join("\n");
+};
+
+/** A scroll box with a fixed marker column and no native scrollbar. */
+export class ScrollSurface extends BoxRenderable {
+  readonly scrollBox: ScrollBoxRenderable;
+  private readonly marker: TextRenderable;
+  private readonly surfaceTheme: Theme;
+  private markerText = "";
+  private markerMetrics = "";
+
+  constructor(
+    renderer: CliRenderer,
+    { theme, width, ...options }: ScrollSurfaceOptions,
+  ) {
+    const outer = {
+      id: options.id,
+      height: options.height,
+      flexGrow: options.flexGrow,
+      flexShrink: options.flexShrink,
+      minHeight: options.minHeight,
+      backgroundColor: options.backgroundColor,
+      focusable: options.focusable,
+    };
+
+    super(renderer, {
+      ...Object.fromEntries(
+        Object.entries(outer).filter(([, value]) => value !== undefined),
+      ),
+      flexDirection: "row",
+      width: width ?? "100%",
+    });
+    this.surfaceTheme = theme;
+
+    this.scrollBox = new ScrollBoxRenderable(renderer, {
+      ...options,
+      id: `${options.id}-scrollbox`,
+      flexGrow: 1,
+      minWidth: 0,
+    });
+
+    this.scrollBox.renderAfter = () => this.syncMarker();
+    this.scrollBox.verticalScrollBar.visible = false;
+
+    this.marker = new TextRenderable(renderer, {
+      id: `${options.id}-marker`,
+      width: 1,
+      height: "100%",
+      flexShrink: 0,
+      content: "",
+      wrapMode: "none",
+    });
+
+    this.add(this.scrollBox);
+    this.add(this.marker);
+  }
+
+  /** Adds a child to the scrolled content. */
+  addContent(renderable: Parameters<ScrollBoxRenderable["add"]>[0]): number {
+    return this.scrollBox.add(renderable);
+  }
+
+  override focus(): void {
+    this.scrollBox.focus();
+  }
+
+  override blur(): void {
+    this.scrollBox.blur();
+  }
+
+  override handleKeyPress(
+    key: Parameters<ScrollBoxRenderable["handleKeyPress"]>[0],
+  ): boolean {
+    const handled = this.scrollBox.handleKeyPress(key);
+    this.syncMarker();
+
+    return handled;
+  }
+
+  /** Redraws the marker when the viewport, content or offset changed. */
+  syncMarker(): void {
+    const viewport = this.scrollBox.viewport.height;
+
+    if (viewport <= 0) return;
+
+    const extent = Math.max(0, this.scrollBox.scrollHeight - viewport);
+    const offset = Math.max(0, Math.min(this.scrollBox.scrollTop, extent));
+    const metrics = `${viewport}:${extent}:${offset}`;
+
+    if (metrics === this.markerMetrics) return;
+
+    this.markerMetrics = metrics;
+    const marker = renderMarker(viewport, extent, offset);
+
+    if (marker === this.markerText) return;
+
+    this.markerText = marker;
+    this.marker.content = t`${fg(this.surfaceTheme.fgSubtle)(marker)}`;
+  }
+
+  protected override onUpdate(deltaTime: number): void {
+    super.onUpdate(deltaTime);
+
+    if (this.markerMetrics) this.syncMarker();
+  }
+}

package/src/section-heading.ts

@@ -0,0 +1,83 @@
+/**
+ * The section heading: a full-width row with a dimmed bold title and an
+ * optional icon, which starts a new row in a wrapping tile grid.
+ *
+ * @module
+ */
+import { BoxRenderable, TextRenderable, bold, fg, t } from "@opentui/core";
+import type { CliRenderer } from "@opentui/core";
+import type { Theme } from "./theme.ts";
+
+/** Width of the optional left icon column in characters */
+const ICON_COLUMN_WIDTH = 4;
+
+export interface SectionHeadingOptions {
+  readonly id: string;
+  readonly title: string;
+  /** Nerd Font icon shown before the title */
+  readonly icon?: string | undefined;
+  readonly marginTop?: number;
+  /** 1 by default */
+  readonly marginBottom?: number;
+}
+
+/** A full-width heading row; add `box` to the parent. */
+export class SectionHeading {
+  /** The heading's row */
+  readonly box: BoxRenderable;
+  private readonly theme: Theme;
+  private readonly titleText: TextRenderable;
+
+  constructor(
+    renderer: CliRenderer,
+    theme: Theme,
+    options: SectionHeadingOptions,
+  ) {
+    this.theme = theme;
+
+    this.box = new BoxRenderable(renderer, {
+      id: options.id,
+      flexDirection: "row",
+      width: "100%",
+      flexShrink: 0,
+      alignItems: "center",
+      shouldFill: false,
+      marginTop: options.marginTop ?? 0,
+      marginBottom: options.marginBottom ?? 1,
+    });
+
+    if (options.icon) {
+      const iconCol = new BoxRenderable(renderer, {
+        id: `${options.id}-icol`,
+        width: ICON_COLUMN_WIDTH,
+        paddingLeft: 1,
+        alignItems: "center",
+      });
+
+      iconCol.add(
+        new TextRenderable(renderer, {
+          id: `${options.id}-icon`,
+          content: t`${fg(theme.fgSubtle)(options.icon)}`,
+        }),
+      );
+
+      this.box.add(iconCol);
+    }
+
+    this.titleText = new TextRenderable(renderer, {
+      id: `${options.id}-title`,
+      content: "",
+    });
+
+    this.box.add(this.titleText);
+    this.setTitle(options.title);
+  }
+
+  setTitle(title: string): void {
+    this.titleText.content = t`${bold(fg(this.theme.fgSubtle)(title))}`;
+  }
+
+  setVisible(visible: boolean): void {
+    this.box.visible = visible;
+  }
+}