@hoox-sh/hoox-tui 0.2.0

package/src/components/shared/command-palette.tsx

@@ -0,0 +1,361 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * CommandPalette — an overlay modal with fuzzy-searchable command registry.
+ *
+ * Features:
+ *   - Dimmed backdrop overlay (backdropOpacity).
+ *   - Fuzzy-search input at top with caret indicator.
+ *   - Results list: command name (bold), category badge (view/action/setting),
+ *     shortcut hint on the right.
+ *   - ↑↓ navigate results, Enter to select, Esc to dismiss.
+ *   - Commands are provided via a registry prop so consumers can
+ *     populate from views, actions, and settings.
+ *
+ * Colors use Hoox design tokens — no hardcoded hex.
+ * Keyboard handling via @opentui/react useKeyboard hook.
+ */
+import { useState, useMemo, useEffect } from "react";
+import { useKeyboard } from "@opentui/react";
+import { Colors } from "@hoox-sh/hoox-shared";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** Category tag for grouping commands in the palette */
+export type CommandCategory = "view" | "action" | "setting";
+
+/** A single command entry in the registry */
+export interface CommandEntry {
+  /** Unique command identifier */
+  id: string;
+  /** Display name shown in results (bold) */
+  name: string;
+  /** Category used for the badge */
+  category: CommandCategory;
+  /** Optional keyboard shortcut shown on the right */
+  shortcut?: string;
+  /** Optional search aliases to improve fuzzy matching */
+  aliases?: string[];
+  /** Extra description shown dimmed below the name */
+  description?: string;
+}
+
+/** Result of selecting a command */
+export interface CommandSelection {
+  command: CommandEntry;
+  /** Type of action to perform */
+  action: "setView" | "execute";
+}
+
+export interface CommandPaletteProps {
+  /** Whether the palette overlay is visible */
+  visible: boolean;
+  /** Registry of all available commands */
+  commands: CommandEntry[];
+  /** Called when user selects a command (Enter) or dismisses with Escape */
+  onSelect: (selection: CommandSelection) => void;
+  /** Called when user dismisses the palette (Escape) */
+  onDismiss: () => void;
+}
+
+// ── Category badge colors ──────────────────────────────────────────────────
+
+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 },
+};
+
+// ── Fuzzy filter ───────────────────────────────────────────────────────────
+
+/**
+ * Simple fuzzy match — checks if all characters in `query` appear
+ * in order within the candidate string (case-insensitive).
+ */
+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;
+}
+
+/** Score a command entry against a query (higher = better match) */
+function scoreCommand(query: string, cmd: CommandEntry): number {
+  if (!query) return 1; // no query, keep natural order
+  const q = query.toLowerCase();
+
+  // Exact prefix match on name is strongest
+  if (cmd.name.toLowerCase().startsWith(q)) return 100;
+
+  // Fuzzy match on name
+  if (fuzzyMatch(q, cmd.name)) return 50;
+
+  // Match in description
+  if (cmd.description && fuzzyMatch(q, cmd.description)) return 30;
+
+  // Match in aliases
+  if (cmd.aliases?.some((a) => fuzzyMatch(q, a))) return 20;
+
+  return -1; // no match
+}
+
+/** Filter and sort commands by fuzzy relevance */
+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);
+
+  // Deduplicate by id (keep highest 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;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+export function CommandPalette({
+  visible,
+  commands,
+  onSelect,
+  onDismiss,
+}: CommandPaletteProps) {
+  const [query, setQuery] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  // Filtered & scored results
+  const filtered = useMemo(
+    () => filterCommands(commands, query),
+    [commands, query]
+  );
+
+  // Clamp selection when the filtered list shrinks (e.g. tighter query)
+  const safeIndex =
+    filtered.length === 0 ? 0 : Math.min(selectedIndex, filtered.length - 1);
+
+  // Reset local state when the palette is dismissed so next open is clean
+  useEffect(() => {
+    if (!visible) {
+      setQuery("");
+      setSelectedIndex(0);
+    }
+  }, [visible]);
+
+  // Keep selectedIndex in range after filter changes
+  useEffect(() => {
+    if (selectedIndex !== safeIndex) {
+      setSelectedIndex(safeIndex);
+    }
+  }, [safeIndex, selectedIndex]);
+
+  // ── Keyboard handling (active only when visible) ─────────────────────
+
+  useKeyboard((key) => {
+    if (!visible) return;
+
+    // Dismiss
+    if (key.name === "escape") {
+      setQuery("");
+      setSelectedIndex(0);
+      onDismiss();
+      return;
+    }
+
+    // Navigate
+    if (key.name === "up") {
+      setSelectedIndex((i) => {
+        const last = Math.max(0, filtered.length - 1);
+        const cur = Math.min(i, last);
+        return cur > 0 ? cur - 1 : last;
+      });
+      return;
+    }
+    if (key.name === "down") {
+      setSelectedIndex((i) => {
+        const last = Math.max(0, filtered.length - 1);
+        const cur = Math.min(i, last);
+        return cur < last ? cur + 1 : 0;
+      });
+      return;
+    }
+
+    // Select (return / enter)
+    if (key.name === "return" || key.name === "enter") {
+      const selected = filtered[safeIndex];
+      if (selected) {
+        setQuery("");
+        setSelectedIndex(0);
+        onSelect({
+          command: selected,
+          action: selected.category === "view" ? "setView" : "execute",
+        });
+      }
+      return;
+    }
+
+    // Delete
+    if (key.name === "backspace" || key.name === "delete") {
+      setQuery((q) => q.slice(0, -1));
+      setSelectedIndex(0);
+      return;
+    }
+
+    // Character input (printable keys only — no modifiers)
+    if (
+      key.sequence &&
+      !key.ctrl &&
+      !key.alt &&
+      !key.meta &&
+      key.sequence.length === 1 &&
+      key.name !== "space" // space handled separately
+    ) {
+      const char = key.sequence;
+      // Only accept printable ASCII
+      if (char >= " " && char <= "~") {
+        setQuery((q) => q + char);
+        setSelectedIndex(0);
+        return;
+      }
+    }
+
+    // Space
+    if (key.name === "space") {
+      setQuery((q) => q + " ");
+      setSelectedIndex(0);
+    }
+  });
+
+  // ── Render (hidden when not visible) ────────────────────────────────
+
+  if (!visible) return null;
+
+  return (
+    <box
+      position="absolute"
+      left={0}
+      top={0}
+      width="100%"
+      height="100%"
+      flexDirection="column"
+      justifyContent="center"
+      alignItems="center"
+    >
+      {/* Modal container */}
+      <box
+        flexDirection="column"
+        width={50}
+        padding={1}
+        gap={0}
+        border={true}
+        borderStyle="double"
+        borderColor={Colors.accent}
+        backgroundColor={Colors.background}
+      >
+        {/* ── Search input row ──────────────────────────────────────── */}
+        <box flexDirection="row" gap={1} paddingLeft={1} paddingRight={1}>
+          <text fg={Colors.accent}>▸</text>
+          <text fg={Colors.foreground}>{query}</text>
+          {/* Blinking caret */}
+          <text fg={Colors.accent} blink>
+            █
+          </text>
+        </box>
+
+        {/* ── Divider ────────────────────────────────────────────────── */}
+        <box
+          height={1}
+          border={true}
+          borderStyle="single"
+          borderColor={Colors.border}
+        />
+
+        {/* ── Results list ───────────────────────────────────────────── */}
+        <box flexDirection="column" gap={0} paddingTop={0}>
+          {filtered.length === 0 && query.length > 0 ? (
+            /* No results state */
+            <box paddingLeft={2} paddingTop={1} paddingBottom={1}>
+              <text dim fg={Colors.muted}>
+                No matching commands
+              </text>
+            </box>
+          ) : (
+            filtered.map((cmd, idx) => (
+              <box
+                key={cmd.id}
+                flexDirection="row"
+                justifyContent="space-between"
+                paddingLeft={idx === safeIndex ? 1 : 2}
+                paddingRight={1}
+                bg={idx === safeIndex ? Colors.card : undefined}
+              >
+                {/* Left side: selection arrow + name + category badge */}
+                <box flexDirection="row" gap={1}>
+                  {idx === safeIndex ? (
+                    <text fg={Colors.accent}>▶</text>
+                  ) : (
+                    <text> </text>
+                  )}
+                  <text
+                    fg={idx === safeIndex ? Colors.foreground : Colors.muted}
+                    bold
+                  >
+                    {cmd.name}
+                  </text>
+                  {/* Category badge */}
+                  <text
+                    fg={CATEGORY_BADGE[cmd.category].color}
+                    dim={idx !== safeIndex}
+                  >
+                    {CATEGORY_BADGE[cmd.category].label}
+                  </text>
+                </box>
+
+                {/* Right side: shortcut hint */}
+                <box flexDirection="row" gap={0}>
+                  {cmd.shortcut && (
+                    <text dim fg={Colors.muted}>
+                      {cmd.shortcut}
+                    </text>
+                  )}
+                </box>
+              </box>
+            ))
+          )}
+        </box>
+
+        {/* ── Footer hint ────────────────────────────────────────────── */}
+        <box
+          flexDirection="row"
+          justifyContent="flex-end"
+          paddingTop={0}
+          paddingRight={1}
+        >
+          <text dim fg={Colors.muted}>
+            Esc to close
+          </text>
+        </box>
+      </box>
+    </box>
+  );
+}

package/src/components/shared/cool-brackets.tsx

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * CoolBrackets — static corner/pair brackets in brand accent colors.
+ * No animation (no rainbow / spectrum cycling).
+ */
+import type { ReactNode } from "react";
+import { Colors } from "@hoox-sh/hoox-shared";
+
+/**
+ * Focus / accent color helper (static — kept for call-site compatibility).
+ */
+export function useCoolHue(
+  _intervalMs = 120,
+  enabled = true
+): { color: string; index: number } {
+  return {
+    index: 0,
+    color: enabled ? Colors.accent : Colors.border,
+  };
+}
+
+export interface CoolBracketsProps {
+  /** Content between the brackets */
+  children?: ReactNode;
+  /** Left glyph (default ┌) */
+  open?: string;
+  /** Right glyph (default ┐) */
+  close?: string;
+  /** @deprecated Ignored — animation removed */
+  intervalMs?: number;
+  /** @deprecated Always static now */
+  static?: boolean;
+  /** @deprecated Ignored — animation removed */
+  phase?: number;
+  /** Gap between open, children, close */
+  gap?: number;
+}
+
+/**
+ * Renders open + optional children + close with fixed accent colors.
+ */
+export function CoolBrackets({
+  children,
+  open = "┌",
+  close = "┐",
+  gap = 1,
+}: CoolBracketsProps) {
+  return (
+    <box flexDirection="row" gap={gap} alignItems="center">
+      <text fg={Colors.accent}>{open}</text>
+      {children ?? null}
+      <text fg={Colors.accent}>{close}</text>
+    </box>
+  );
+}
+
+/**
+ * Inline single glyph in accent color (for ▸ markers, pipes, etc.).
+ */
+export function CoolGlyph({
+  char,
+}: {
+  char: string;
+  /** @deprecated Ignored — animation removed */
+  intervalMs?: number;
+  /** @deprecated Ignored — animation removed */
+  phase?: number;
+}) {
+  return <text fg={Colors.accent}>{char}</text>;
+}

package/src/components/shared/crash-screen.tsx

@@ -0,0 +1,167 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * Crash Screen — rendered when an unhandled error escapes all error boundaries.
+ *
+ * Displays:
+ *   - "Something went wrong" banner
+ *   - Error message (first line)
+ *   - Three action buttons: [Restart] [Safe Mode] [Report Bug]
+ *
+ * This component is a plain function (not a class) because it's meant to be
+ * rendered in a degraded state — no hooks, no stores, no external state.
+ * Colors use Hoox design tokens via @hoox-sh/hoox-shared.
+ */
+import { Colors } from "@hoox-sh/hoox-shared";
+import { redactSecretsInText } from "../../services/dev-log";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type CrashAction = "restart" | "safe-mode" | "report-bug";
+
+export interface CrashScreenProps {
+  /** The error that caused the crash */
+  error: Error;
+  /** Callback for crash action buttons */
+  onAction: (action: CrashAction) => void;
+  /** Whether we're in safe mode (affects display) */
+  safeMode?: boolean;
+}
+
+/** Safe, single-line display text for crash UI (secrets scrubbed, length capped). */
+export function formatCrashMessage(error: Error, maxLen = 120): string {
+  const first = (error.message || "Unknown error").split("\n")[0] ?? "";
+  const scrubbed = redactSecretsInText(first).trim() || "Unknown error";
+  return scrubbed.length > maxLen
+    ? `${scrubbed.slice(0, maxLen - 1)}…`
+    : scrubbed;
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+export function CrashScreen({
+  error,
+  onAction,
+  safeMode = false,
+}: CrashScreenProps) {
+  const messageLine = formatCrashMessage(error);
+  const secondRaw = error.message.includes("\n")
+    ? error.message.split("\n")[1]
+    : undefined;
+  const secondLine = secondRaw
+    ? redactSecretsInText(secondRaw).slice(0, 80)
+    : undefined;
+
+  return (
+    <box
+      flexDirection="column"
+      width="100%"
+      height="100%"
+      justifyContent="center"
+      alignItems="center"
+      padding={2}
+      gap={2}
+      backgroundColor={Colors.background}
+    >
+      {/* ── Banner ───────────────────────────────────────────────────────── */}
+      <box
+        flexDirection="column"
+        alignItems="center"
+        border={true}
+        borderStyle="double"
+        borderColor={Colors.error}
+        padding={2}
+        gap={1}
+        backgroundColor={Colors.card}
+      >
+        {/* Title */}
+        <text fg={Colors.error} bold>
+          ╔══════════════════════════════════════╗
+        </text>
+        <text fg={Colors.error} bold>
+          ║ Something went wrong ║
+        </text>
+        <text fg={Colors.error} bold>
+          ╚══════════════════════════════════════╝
+        </text>
+
+        {/* Safe mode indicator */}
+        {safeMode && (
+          <text fg={Colors.warning} bold>
+            (Safe Mode — UI only, no API / CLI / SSE)
+          </text>
+        )}
+
+        {/* Error message (redacted — never show tokens) */}
+        <box paddingTop={1} flexDirection="column" alignItems="center">
+          <text fg={Colors.muted}>{messageLine}</text>
+          {secondLine ? (
+            <text fg={Colors.dim} dim>
+              {secondLine}
+            </text>
+          ) : null}
+        </box>
+      </box>
+
+      {/* ── Action Buttons ───────────────────────────────────────────────── */}
+      <box flexDirection="row" gap={2} paddingTop={1}>
+        {/* [Restart] — re-initialize the renderer */}
+        <box
+          border={true}
+          borderStyle="single"
+          borderColor={Colors.accent}
+          paddingLeft={2}
+          paddingRight={2}
+        >
+          <text
+            fg={Colors.accent}
+            bg={Colors.card}
+            onMouseUp={() => onAction("restart")}
+          >
+            {"  [Restart]  "}
+          </text>
+        </box>
+
+        {/* [Safe Mode] — start with minimal config */}
+        {!safeMode && (
+          <box
+            border={true}
+            borderStyle="single"
+            borderColor={Colors.warning}
+            paddingLeft={2}
+            paddingRight={2}
+          >
+            <text
+              fg={Colors.warning}
+              bg={Colors.card}
+              onMouseUp={() => onAction("safe-mode")}
+            >
+              {"  [Safe Mode]  "}
+            </text>
+          </box>
+        )}
+
+        {/* [Report Bug] — write error to file / console */}
+        <box
+          border={true}
+          borderStyle="single"
+          borderColor={Colors.muted}
+          paddingLeft={2}
+          paddingRight={2}
+        >
+          <text
+            fg={Colors.muted}
+            bg={Colors.card}
+            onMouseUp={() => onAction("report-bug")}
+          >
+            {"  [Report Bug]  "}
+          </text>
+        </box>
+      </box>
+    </box>
+  );
+}

package/src/components/shared/error-boundary.tsx

@@ -0,0 +1,99 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * React-style error boundary for the TUI.
+ * Catches render errors in child views and displays a styled recovery panel
+ * with the view name, error message, and a [Retry] button.
+ *
+ * Colors use Hoox design tokens — no hardcoded hex.
+ */
+import { Component, type ReactNode } from "react";
+import { Colors } from "@hoox-sh/hoox-shared";
+import { redactSecretsInText } from "../../services/dev-log";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface ErrorBoundaryProps {
+  /** Name of the view being wrapped (shown in error UI) */
+  viewName: string;
+  /** Child content to protect */
+  children: ReactNode;
+}
+
+interface ErrorBoundaryState {
+  error: Error | null;
+}
+
+/** First line of error message, secrets scrubbed, length-capped for chrome. */
+export function formatBoundaryErrorMessage(error: Error, maxLen = 160): string {
+  const first = (error.message || "Unknown error").split("\n")[0] ?? "";
+  const scrubbed = redactSecretsInText(first).trim() || "Unknown error";
+  return scrubbed.length > maxLen
+    ? `${scrubbed.slice(0, maxLen - 1)}…`
+    : scrubbed;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  state: ErrorBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { error };
+  }
+
+  /** Reset error state to retry rendering children */
+  private handleRetry = () => {
+    this.setState({ error: null });
+  };
+
+  render(): ReactNode {
+    if (this.state.error) {
+      const message = formatBoundaryErrorMessage(this.state.error);
+      return (
+        <box
+          flexDirection="column"
+          padding={2}
+          gap={1}
+          border={true}
+          borderStyle="single"
+          borderColor={Colors.border}
+          backgroundColor={Colors.card}
+        >
+          {/* Header: view name + error indicator */}
+          <box flexDirection="row" gap={1}>
+            <text fg={Colors.error} bold>
+              ⚠
+            </text>
+            <text fg={Colors.error} bold>
+              Failed to load {this.props.viewName}
+            </text>
+          </box>
+
+          {/* Error message (redacted, first line only) */}
+          <text fg={Colors.muted}>{message}</text>
+
+          {/* Retry action */}
+          <box paddingTop={1}>
+            <text
+              fg={Colors.accent}
+              bg={Colors.card}
+              onMouseUp={this.handleRetry}
+            >
+              {"  [Retry]  "}
+            </text>
+          </box>
+        </box>
+      );
+    }
+
+    return this.props.children;
+  }
+}