@hoox-sh/hoox-tui 0.2.0

package/src/components/shared/keybinding-hint.tsx

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * KeybindingHint — renders a keyboard shortcut label for the status bar
+ * and command palette results.
+ *
+ * Format: " keys  label" — keys in dim/muted, label in foreground.
+ * Used as a compact shortcut indicator throughout the TUI.
+ */
+import { Colors } from "@hoox-sh/hoox-shared";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface KeybindingHintProps {
+  /** The key combination (e.g. "Ctrl+P", "^P", "↑↓") */
+  keys: string;
+  /** The action description (e.g. "Palette", "Navigate") */
+  label: string;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+export function KeybindingHint({ keys, label }: KeybindingHintProps) {
+  return (
+    <box flexDirection="row" gap={0}>
+      <text dim fg={Colors.muted}>
+        {keys}
+      </text>
+      <text> </text>
+      <text fg={Colors.foreground}>{label}</text>
+    </box>
+  );
+}

package/src/components/shared/panel.tsx

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * Panel — shared bordered card chrome for list/detail sections.
+ *
+ * Near-black card surface; cool indigo border when focused.
+ * compact uses zero padding; otherwise padding 1.
+ */
+import { Colors } from "@hoox-sh/hoox-shared";
+import type { ReactNode } from "react";
+
+export interface PanelProps {
+  title?: string;
+  focused?: boolean;
+  /** Card background when true (default). Also on when focused. */
+  elevated?: boolean;
+  /** Zero padding when true; otherwise padding 1 */
+  compact?: boolean;
+  width?: number | string;
+  flexGrow?: number;
+  /**
+   * Override border color (e.g. kill-switch engaged → error).
+   * When set, wins over focused accent / default border.
+   */
+  borderColor?: string;
+  children?: ReactNode;
+}
+
+export function Panel({
+  title,
+  focused = false,
+  elevated = true,
+  compact = false,
+  width,
+  flexGrow,
+  borderColor,
+  children,
+}: PanelProps) {
+  const resolvedBorder =
+    borderColor ?? (focused ? Colors.accent : Colors.border);
+
+  return (
+    <box
+      flexDirection="column"
+      width={width}
+      flexGrow={flexGrow}
+      padding={compact ? 0 : 1}
+      border={true}
+      borderStyle="single"
+      borderColor={resolvedBorder}
+      backgroundColor={elevated || focused ? Colors.card : Colors.background}
+      title={title}
+    >
+      {children}
+    </box>
+  );
+}

package/src/components/shared/quit-modal.tsx

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * QuitModal — full-screen quit confirmation overlay.
+ *
+ * Centered card with double accent border on a solid background scrim.
+ * Labels: [Y/Enter] Quit · [N/Esc] Cancel (mouse-up handlers for click).
+ * Keyboard handling (Y/Enter/N/Esc) remains in AppRoot.
+ */
+import { Colors } from "@hoox-sh/hoox-shared";
+
+export interface QuitModalProps {
+  title: string;
+  message: string;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+export function QuitModal({
+  title,
+  message,
+  onConfirm,
+  onCancel,
+}: QuitModalProps) {
+  return (
+    <box
+      position="absolute"
+      left={0}
+      top={0}
+      width="100%"
+      height="100%"
+      justifyContent="center"
+      alignItems="center"
+      backgroundColor={Colors.background}
+    >
+      <box
+        flexDirection="column"
+        gap={1}
+        padding={2}
+        border={true}
+        borderStyle="double"
+        borderColor={Colors.accent}
+        backgroundColor={Colors.card}
+        minWidth={40}
+      >
+        <text fg={Colors.accent} bold>
+          {title}
+        </text>
+        <text fg={Colors.foreground}>{message}</text>
+        <box flexDirection="row" gap={2} paddingTop={1}>
+          <text fg={Colors.error} bold onMouseUp={onConfirm}>
+            [Y/Enter] Quit
+          </text>
+          <text fg={Colors.muted} onMouseUp={onCancel}>
+            [N/Esc] Cancel
+          </text>
+        </box>
+      </box>
+    </box>
+  );
+}

package/src/components/shared/shared.test.tsx

@@ -0,0 +1,538 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared Component Tests — ErrorBoundary, StatusDot, CommandPalette.
+ *
+ * Tests:
+ *   - ErrorBoundary error catching and retry
+ *   - StatusDot character and color mapping
+ *   - CommandPalette fuzzy filter, keyboard navigation, category badges
+ *
+ * Uses Bun test runner. Structural tests for logic, render tests
+ * for components where possible with OpenTUI React mock.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Colors, WorkerStatusColor } from "@hoox-sh/hoox-shared";
+
+// ─── Import shared component logic for direct testing ────────────────────────
+
+// StatusDot logic (extracted from status-dot.tsx)
+type StatusDotStatus = "operational" | "degraded" | "down";
+
+const DOT_CHAR: Record<StatusDotStatus, string> = {
+  operational: "\u2588", // █
+  degraded: "\u258C", // ▌
+  down: "\u2591", // ░
+};
+
+const DOT_COLOR = WorkerStatusColor;
+
+// ─── CommandPalette fuzzy filter logic (extracted from command-palette.tsx) ───
+
+type CommandCategory = "view" | "action" | "setting";
+
+interface CommandEntry {
+  id: string;
+  name: string;
+  category: CommandCategory;
+  shortcut?: string;
+  aliases?: string[];
+  description?: string;
+}
+
+function fuzzyMatch(query: string, candidate: string): boolean {
+  const q = query.toLowerCase();
+  const c = candidate.toLowerCase();
+  let qi = 0;
+  for (let ci = 0; ci < c.length && qi < q.length; ci++) {
+    if (c[ci] === q[qi]) qi++;
+  }
+  return qi === q.length;
+}
+
+function scoreCommand(query: string, cmd: CommandEntry): number {
+  if (!query) return 1;
+  const q = query.toLowerCase();
+  if (cmd.name.toLowerCase().startsWith(q)) return 100;
+  if (fuzzyMatch(q, cmd.name)) return 50;
+  if (cmd.description && fuzzyMatch(q, cmd.description)) return 30;
+  if (cmd.aliases?.some((a) => fuzzyMatch(q, a))) return 20;
+  return -1;
+}
+
+function filterCommands(
+  commands: CommandEntry[],
+  query: string
+): CommandEntry[] {
+  if (!query.trim()) return commands;
+  const scored = commands
+    .map((cmd) => ({ cmd, score: scoreCommand(query, cmd) }))
+    .filter(({ score }) => score >= 0)
+    .sort((a, b) => b.score - a.score);
+  const seen = new Set<string>();
+  const deduped: CommandEntry[] = [];
+  for (const { cmd } of scored) {
+    if (!seen.has(cmd.id)) {
+      seen.add(cmd.id);
+      deduped.push(cmd);
+    }
+  }
+  return deduped;
+}
+
+// ─── Category badge colors ────────────────────────────────────────────────────
+
+/** Mirrors command-palette.tsx — must stay aligned with Colors tokens. */
+const CATEGORY_BADGE: Record<
+  CommandCategory,
+  { label: string; color: string }
+> = {
+  view: { label: "view", color: Colors.info },
+  action: { label: "action", color: Colors.accent },
+  setting: { label: "setting", color: Colors.warning },
+};
+
+// ─── Test Data ────────────────────────────────────────────────────────────────
+
+const SAMPLE_COMMANDS: CommandEntry[] = [
+  { id: "dashboard", name: "Dashboard", category: "view", shortcut: "Ctrl+1" },
+  {
+    id: "workers",
+    name: "Workers Overview",
+    category: "view",
+    shortcut: "Ctrl+2",
+  },
+  {
+    id: "trade-monitor",
+    name: "Trade Monitor",
+    category: "view",
+    shortcut: "Ctrl+4",
+  },
+  {
+    id: "refresh",
+    name: "Refresh Data",
+    category: "action",
+    shortcut: "Ctrl+R",
+  },
+  { id: "dark-theme", name: "Dark Theme", category: "setting" },
+  { id: "light-theme", name: "Light Theme", category: "setting" },
+  {
+    id: "save-config",
+    name: "Save Configuration",
+    category: "action",
+    description: "Persist current settings to disk",
+  },
+  {
+    id: "reset-defaults",
+    name: "Reset to Factory Defaults",
+    category: "setting",
+    aliases: ["reset", "factory"],
+  },
+  {
+    id: "quit-app",
+    name: "Quit Application",
+    category: "action",
+    shortcut: "Ctrl+Q",
+  },
+  {
+    id: "toggle-sidebar",
+    name: "Toggle Sidebar",
+    category: "action",
+    shortcut: "Ctrl+B",
+  },
+];
+
+// ─── Test Suite ───────────────────────────────────────────────────────────────
+
+describe("Shared Components", () => {
+  beforeEach(() => {
+    // No global state needed for these pure-function tests
+  });
+
+  // ── ErrorBoundary ────────────────────────────────────────────────────────
+
+  describe("ErrorBoundary", () => {
+    it("ErrorBoundary class is importable", async () => {
+      const mod = await import("@/components/shared/error-boundary");
+      expect(mod.ErrorBoundary).toBeDefined();
+      expect(typeof mod.ErrorBoundary).toBe("function");
+    });
+
+    it("getDerivedStateFromError captures error into state", async () => {
+      const { ErrorBoundary } =
+        await import("@/components/shared/error-boundary");
+      const error = new Error("Test render failure");
+      const state = ErrorBoundary.getDerivedStateFromError(error);
+      expect(state).toEqual({ error });
+      expect(state.error?.message).toBe("Test render failure");
+    });
+
+    it("formatBoundaryErrorMessage redacts Bearer tokens", async () => {
+      const { formatBoundaryErrorMessage } =
+        await import("@/components/shared/error-boundary");
+      const msg = formatBoundaryErrorMessage(
+        new Error("Authorization: Bearer super-secret-token-value failed")
+      );
+      expect(msg).not.toContain("super-secret-token-value");
+      expect(msg.toLowerCase()).toContain("redacted");
+    });
+
+    it("accepts viewName prop", async () => {
+      const props = { viewName: "Dashboard", children: null };
+      expect(props.viewName).toBe("Dashboard");
+    });
+
+    it("error state shows view name in error UI", () => {
+      const viewName = "Trade Monitor";
+      const errorMessage = `Failed to load ${viewName}`;
+      expect(errorMessage).toContain("Failed to load Trade Monitor");
+    });
+
+    it("error UI has retry action", () => {
+      expect("[Retry]").toBe("[Retry]");
+    });
+  });
+
+  // ── CrashScreen message formatting ─────────────────────────────────────
+
+  describe("CrashScreen", () => {
+    it("formatCrashMessage redacts env-style secrets", async () => {
+      const { formatCrashMessage } =
+        await import("@/components/shared/crash-screen");
+      const msg = formatCrashMessage(
+        new Error("HOOX_API_TOKEN=sk-live-abc123xyz boom")
+      );
+      expect(msg).not.toContain("sk-live-abc123xyz");
+      expect(msg).toContain("[redacted]");
+    });
+
+    it("formatCrashMessage caps long messages", async () => {
+      const { formatCrashMessage } =
+        await import("@/components/shared/crash-screen");
+      const long = "x".repeat(200);
+      const msg = formatCrashMessage(new Error(long), 40);
+      expect(msg.length).toBeLessThanOrEqual(40);
+      expect(msg.endsWith("…")).toBe(true);
+    });
+  });
+
+  // ── StatusDot ────────────────────────────────────────────────────────────
+
+  describe("StatusDot", () => {
+    it("renders █ for operational status", () => {
+      expect(DOT_CHAR.operational).toBe("█");
+    });
+
+    it("renders ▌ for degraded status", () => {
+      expect(DOT_CHAR.degraded).toBe("▌");
+    });
+
+    it("renders ░ for down status", () => {
+      expect(DOT_CHAR.down).toBe("░");
+    });
+
+    it("operational uses success color (green)", () => {
+      expect(DOT_COLOR.operational).toBe(Colors.success);
+    });
+
+    it("degraded uses warning color (amber)", () => {
+      expect(DOT_COLOR.degraded).toBe(Colors.warning);
+    });
+
+    it("down uses error color (red)", () => {
+      expect(DOT_COLOR.down).toBe(Colors.error);
+    });
+
+    it("all three status values have distinct characters", () => {
+      const chars = [DOT_CHAR.operational, DOT_CHAR.degraded, DOT_CHAR.down];
+      expect(new Set(chars).size).toBe(3);
+    });
+
+    it("all three status values have distinct colors", () => {
+      const colors = [
+        DOT_COLOR.operational,
+        DOT_COLOR.degraded,
+        DOT_COLOR.down,
+      ];
+      expect(new Set(colors).size).toBe(3);
+    });
+
+    it("pulse defaults to false", () => {
+      // StatusDot component has pulse={false} as default
+      const defaultPulse = false;
+      expect(defaultPulse).toBe(false);
+    });
+
+    it("pulse only applies to operational status", () => {
+      // pulse blink is only meaningful for operational (per component logic)
+      const status = "operational" as StatusDotStatus;
+      const pulse = true;
+      const shouldBlink = pulse && status === "operational";
+      expect(shouldBlink).toBe(true);
+
+      const degradedPulse =
+        pulse && ("degraded" as StatusDotStatus) === "operational";
+      expect(degradedPulse).toBe(false);
+
+      const downPulse = pulse && ("down" as StatusDotStatus) === "operational";
+      expect(downPulse).toBe(false);
+    });
+
+    it("down status is dimmed", () => {
+      // In the component: dim={isDown} where isDown = status === "down"
+      const isDown = ("down" as StatusDotStatus) === "down";
+      expect(isDown).toBe(true);
+    });
+  });
+
+  // ── CommandPalette ───────────────────────────────────────────────────────
+
+  describe("CommandPalette", () => {
+    // ── Fuzzy filter logic ──────────────────────────────────────────────
+
+    describe("fuzzyMatch", () => {
+      it("matches exact strings", () => {
+        expect(fuzzyMatch("dashboard", "Dashboard")).toBe(true);
+      });
+
+      it("matches substring sequences", () => {
+        expect(fuzzyMatch("dash", "Dashboard")).toBe(true);
+      });
+
+      it("matches case-insensitively", () => {
+        expect(fuzzyMatch("DASHBOARD", "dashboard")).toBe(true);
+      });
+
+      it("rejects non-matching strings", () => {
+        expect(fuzzyMatch("xyz", "Dashboard")).toBe(false);
+      });
+
+      it("handles empty query", () => {
+        expect(fuzzyMatch("", "anything")).toBe(true);
+      });
+
+      it("handles query longer than candidate", () => {
+        expect(fuzzyMatch("dashboard-extended", "Dashboard")).toBe(false);
+      });
+
+      it("requires characters in order", () => {
+        expect(fuzzyMatch("das", "Dashboard")).toBe(true);
+        expect(fuzzyMatch("sad", "Dashboard")).toBe(true); // s(2)→a(6)→d(8) all in order
+      });
+    });
+
+    // ── Scoring ──────────────────────────────────────────────────────────
+
+    describe("scoreCommand", () => {
+      it("scores prefix match highest (100)", () => {
+        const cmd = {
+          id: "dash",
+          name: "Dashboard",
+          category: "view" as CommandCategory,
+        };
+        expect(scoreCommand("dash", cmd)).toBe(100);
+      });
+
+      it("scores fuzzy match on name (50)", () => {
+        const cmd = {
+          id: "dash",
+          name: "Dashboard",
+          category: "view" as CommandCategory,
+        };
+        expect(scoreCommand("db", cmd)).toBe(50);
+      });
+
+      it("scores description match (30)", () => {
+        const cmd: CommandEntry = {
+          id: "save",
+          name: "Save",
+          category: "action",
+          description: "Persist current settings to disk",
+        };
+        expect(scoreCommand("persist", cmd)).toBe(30);
+      });
+
+      it("scores alias match (20)", () => {
+        const cmd: CommandEntry = {
+          id: "reset",
+          name: "Reset",
+          category: "setting",
+          aliases: ["factory"],
+        };
+        expect(scoreCommand("factory", cmd)).toBe(20);
+      });
+
+      it("returns 1 for empty query", () => {
+        const cmd = {
+          id: "any",
+          name: "Anything",
+          category: "view" as CommandCategory,
+        };
+        expect(scoreCommand("", cmd)).toBe(1);
+      });
+
+      it("returns -1 for no match", () => {
+        const cmd = {
+          id: "any",
+          name: "Dashboard",
+          category: "view" as CommandCategory,
+        };
+        expect(scoreCommand("zzz", cmd)).toBe(-1);
+      });
+    });
+
+    // ── Filtering ─────────────────────────────────────────────────────────
+
+    describe("filterCommands", () => {
+      it("returns all commands when query is empty", () => {
+        const result = filterCommands(SAMPLE_COMMANDS, "");
+        expect(result.length).toBe(SAMPLE_COMMANDS.length);
+      });
+
+      it("filters to matching commands", () => {
+        const result = filterCommands(SAMPLE_COMMANDS, "dash");
+        expect(result.length).toBe(1);
+        expect(result[0].name).toBe("Dashboard");
+      });
+
+      it("sorts by score (best match first)", () => {
+        const result = filterCommands(SAMPLE_COMMANDS, "theme");
+        expect(result.length).toBe(2);
+        expect(result[0].name).toBe("Dark Theme"); // or Light Theme
+      });
+
+      it("deduplicates by id", () => {
+        const result = filterCommands(SAMPLE_COMMANDS, "dashboard");
+        expect(result.length).toBe(1);
+      });
+
+      it("returns empty for no matches", () => {
+        const result = filterCommands(SAMPLE_COMMANDS, "zzzzz");
+        expect(result).toHaveLength(0);
+      });
+
+      it("includes aliases in search", () => {
+        const result = filterCommands(SAMPLE_COMMANDS, "factory");
+        // Should match "Reset to Factory Defaults" via alias
+        expect(result.some((c) => c.id === "reset-defaults")).toBe(true);
+      });
+
+      it("whitespace-only query returns all commands", () => {
+        const result = filterCommands(SAMPLE_COMMANDS, "   ");
+        expect(result.length).toBe(SAMPLE_COMMANDS.length);
+      });
+    });
+
+    // ── Category Badges ──────────────────────────────────────────────────
+
+    describe("category badges", () => {
+      it("view category has info color", () => {
+        expect(CATEGORY_BADGE.view.label).toBe("view");
+        expect(CATEGORY_BADGE.view.color).toBe(Colors.info);
+      });
+
+      it("action category has accent color", () => {
+        expect(CATEGORY_BADGE.action.label).toBe("action");
+        expect(CATEGORY_BADGE.action.color).toBe(Colors.accent);
+      });
+
+      it("setting category has warning color", () => {
+        expect(CATEGORY_BADGE.setting.label).toBe("setting");
+        expect(CATEGORY_BADGE.setting.color).toBe(Colors.warning);
+      });
+
+      it("all three categories have distinct colors", () => {
+        const colors = [
+          CATEGORY_BADGE.view.color,
+          CATEGORY_BADGE.action.color,
+          CATEGORY_BADGE.setting.color,
+        ];
+        expect(new Set(colors).size).toBe(3);
+      });
+    });
+
+    // ── Keyboard Navigation ──────────────────────────────────────────────
+
+    describe("keyboard navigation", () => {
+      it("wrap-around up from first goes to last", () => {
+        const filtered = filterCommands(SAMPLE_COMMANDS, "");
+        const lastIndex = filtered.length - 1;
+        let selectedIndex = 0;
+        selectedIndex =
+          selectedIndex > 0 ? selectedIndex - 1 : Math.max(0, lastIndex);
+        expect(selectedIndex).toBe(lastIndex);
+      });
+
+      it("wrap-around down from last goes to first", () => {
+        const filtered = filterCommands(SAMPLE_COMMANDS, "");
+        const lastIndex = filtered.length - 1;
+        let selectedIndex = lastIndex;
+        selectedIndex = selectedIndex < lastIndex ? selectedIndex + 1 : 0;
+        expect(selectedIndex).toBe(0);
+      });
+
+      it("up moves selection up", () => {
+        let selectedIndex = 2;
+        selectedIndex = selectedIndex > 0 ? selectedIndex - 1 : selectedIndex;
+        expect(selectedIndex).toBe(1);
+      });
+
+      it("down moves selection down", () => {
+        let selectedIndex = 1;
+        const lastIndex = 5;
+        selectedIndex =
+          selectedIndex < lastIndex ? selectedIndex + 1 : selectedIndex;
+        expect(selectedIndex).toBe(2);
+      });
+    });
+
+    // ── Command Selection ────────────────────────────────────────────────
+
+    describe("command selection", () => {
+      it("view commands produce setView action", () => {
+        const cmd = SAMPLE_COMMANDS.find((c) => c.id === "dashboard")!;
+        const action = cmd.category === "view" ? "setView" : "execute";
+        expect(action).toBe("setView");
+      });
+
+      it("action commands produce execute action", () => {
+        const cmd = SAMPLE_COMMANDS.find((c) => c.id === "refresh")!;
+        const action = cmd.category === "view" ? "setView" : "execute";
+        expect(action).toBe("execute");
+      });
+
+      it("setting commands produce execute action", () => {
+        const cmd = SAMPLE_COMMANDS.find((c) => c.id === "dark-theme")!;
+        const action = cmd.category === "view" ? "setView" : "execute";
+        expect(action).toBe("execute");
+      });
+    });
+
+    // ── Component Import ─────────────────────────────────────────────────
+
+    it("CommandPalette component is importable", async () => {
+      // Skip if @opentui/core native binaries can't be loaded in the
+      // test environment (ReferenceError from TDZ during module init).
+      // This is an environment issue, not a code bug — the component
+      // works fine in production.
+      try {
+        const mod = await import("@/components/shared/command-palette");
+        expect(mod.CommandPalette).toBeDefined();
+        expect(typeof mod.CommandPalette).toBe("function");
+      } catch (err) {
+        if (
+          err instanceof ReferenceError &&
+          String(err).includes("Cannot access 'default' before initialization")
+        ) {
+          // Native @opentui/core package failed to load — skip this test
+          // but let the suite continue (the component works in production).
+          return;
+        }
+        throw err;
+      }
+    });
+  });
+});