@hoox-sh/hoox-tui 0.2.0

package/src/components/shared/spinner.tsx

@@ -0,0 +1,85 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+import { useState, useEffect } from "react";
+import { Colors } from "@hoox-sh/hoox-shared";
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface SpinnerProps {
+  label?: string;
+  color?: string;
+}
+
+export function Spinner({
+  label = "Loading...",
+  color = Colors.highlight,
+}: SpinnerProps) {
+  const [frame, setFrame] = useState(0);
+
+  useEffect(() => {
+    // Skip the animation loop in test environments. The OpenTUI test
+    // runner wraps renders in `act(...)`; an interval that fires every
+    // 80ms triggers state updates that aren't wrapped in `act`, which
+    // surfaces as noisy warnings and (in some configurations) causes
+    // related test assertions to fail. Tests are not validating
+    // animation timing, so a static spinner is correct here.
+    if (
+      (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean })
+        .IS_REACT_ACT_ENVIRONMENT === true
+    ) {
+      return;
+    }
+
+    const timer = setInterval(() => {
+      setFrame((f) => (f + 1) % SPINNER_FRAMES.length);
+    }, 80);
+    return () => clearInterval(timer);
+  }, []);
+
+  return (
+    <box flexDirection="row" gap={1} alignItems="center">
+      <text fg={color}>{SPINNER_FRAMES[frame]}</text>
+      <text fg={Colors.muted} dim>
+        {label}
+      </text>
+    </box>
+  );
+}
+
+export interface EmptyStateProps {
+  message: string;
+  suggestion?: string;
+  icon?: string;
+}
+
+export function EmptyState({
+  message,
+  suggestion,
+  icon = "∅",
+}: EmptyStateProps) {
+  return (
+    <box
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+      paddingY={2}
+      gap={1}
+    >
+      <text fg={Colors.muted} dim>
+        {icon}
+      </text>
+      <text fg={Colors.foreground} dim>
+        {message}
+      </text>
+      {suggestion && (
+        <text fg={Colors.muted} dim>
+          {suggestion}
+        </text>
+      )}
+    </box>
+  );
+}

package/src/components/shared/status-dot.tsx

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * StatusDot — a compact color-coded indicator for operational state.
+ *
+ * Renders a distinct terminal character per status:
+ *   - operational → "█" green  (WorkerStatusColor.operational)
+ *   - degraded    → "▌" amber  (WorkerStatusColor.degraded)
+ *   - down        → "░" red    (WorkerStatusColor.down), dimmed
+ *
+ * Optional `pulse` blinks the character for operational status
+ * (uses the Text `blink` attribute to pulse).
+ */
+import { WorkerStatusColor } from "@hoox-sh/hoox-shared";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type StatusDotStatus = "operational" | "degraded" | "down";
+
+export interface StatusDotProps {
+  /** The operational status to display */
+  status: StatusDotStatus;
+  /** Whether to pulse/blink the indicator (only visible on 'operational') */
+  pulse?: boolean;
+}
+
+// ── Character & color lookup ───────────────────────────────────────────────
+
+const DOT_CHAR: Record<StatusDotStatus, string> = {
+  operational: "█",
+  degraded: "▌",
+  down: "░",
+};
+
+const DOT_COLOR = WorkerStatusColor;
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+export function StatusDot({ status, pulse = false }: StatusDotProps) {
+  const char = DOT_CHAR[status];
+  const color = DOT_COLOR[status];
+  const isDown = status === "down";
+  const shouldBlink = pulse && status === "operational";
+
+  return (
+    <text fg={color} bold={!isDown} dim={isDown} blink={shouldBlink}>
+      {char}
+    </text>
+  );
+}

package/src/components/shared/view-header.tsx

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * ViewHeader — shared title row for high-traffic views.
+ *
+ * Cool-bracketed title on the left, optional right-side meta, dim rule under.
+ * OpenTUI: never nest <text> inside <text>.
+ */
+import { Colors } from "@hoox-sh/hoox-shared";
+import type { ReactNode } from "react";
+import { CoolBrackets } from "./cool-brackets";
+
+export interface ViewHeaderProps {
+  title: string;
+  /** Right-aligned meta (counts, status) — string or sibling text nodes */
+  meta?: ReactNode;
+  /** Dim horizontal rule under the title row (default true) */
+  showDivider?: boolean;
+}
+
+export function ViewHeader({
+  title,
+  meta,
+  showDivider = true,
+}: ViewHeaderProps) {
+  return (
+    <box
+      flexDirection="row"
+      gap={2}
+      paddingBottom={showDivider ? 1 : 0}
+      borderBottom={showDivider}
+      borderStyle={showDivider ? "single" : undefined}
+      borderColor={showDivider ? Colors.border : undefined}
+      justifyContent="space-between"
+      width="100%"
+    >
+      <CoolBrackets open="┌" close="┐" gap={1}>
+        <text fg={Colors.accent} bold>
+          {title}
+        </text>
+      </CoolBrackets>
+      {meta ? (
+        <box flexDirection="row" gap={1}>
+          {meta}
+        </box>
+      ) : null}
+    </box>
+  );
+}

package/src/components/ui/connection-toasts.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect } from "bun:test";
+import {
+  messageAuthMissing,
+  messageAuthRequired,
+  messageConnected,
+  messageConnectionLost,
+  messageOfflineStartup,
+  messageReconnected,
+} from "./connection-toasts";
+
+describe("connection-toasts messages", () => {
+  it("connected includes mode and host", () => {
+    expect(messageConnected("local", "localhost:8787")).toBe(
+      "Connected · LOCAL · localhost:8787"
+    );
+    expect(messageConnected("remote", "hoox.example.workers.dev")).toBe(
+      "Connected · REMOTE · hoox.example.workers.dev"
+    );
+  });
+
+  it("lost includes mode and host", () => {
+    expect(messageConnectionLost("remote", "gw.test")).toContain("REMOTE");
+    expect(messageConnectionLost("local", "localhost:8787")).toContain("LOCAL");
+  });
+
+  it("reconnected includes downtime", () => {
+    const msg = messageReconnected("remote", "gw.test", 1_000, 61_000);
+    expect(msg).toContain("Reconnected");
+    expect(msg).toContain("REMOTE");
+    expect(msg).toContain("gw.test");
+    expect(msg).toContain("downtime");
+  });
+
+  it("auth messages are explicit", () => {
+    expect(messageAuthRequired("remote", "gw")).toContain("Auth failed");
+    expect(messageAuthMissing("gw")).toContain("No API credentials");
+  });
+
+  it("offline startup distinguishes auth", () => {
+    expect(messageOfflineStartup("remote", "gw", "auth")).toContain("(auth)");
+    expect(
+      messageOfflineStartup("local", "localhost:8787", "network")
+    ).not.toContain("(auth)");
+  });
+});

package/src/components/ui/connection-toasts.ts

@@ -0,0 +1,215 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Connection toast notifications — mode-aware messages for LOCAL/REMOTE
+ * state changes (connected, lost, reconnected, auth, rate limit).
+ *
+ * Uses the Hoox-styled toast helpers from ./toast.tsx.
+ * Message builders are pure and exported for unit tests.
+ */
+import { toastSuccess, toastWarning, toastInfo, toastError } from "./toast";
+import { formatDuration } from "@hoox-sh/hoox-shared";
+import type { TuiMode } from "../../services/tui-connection";
+import { remoteAuthMissingHint } from "../../services/tui-connection";
+
+// ─── Pure message builders (testable without toast side effects) ─────────────
+
+export function messageConnected(mode: TuiMode, host: string): string {
+  const label = mode === "remote" ? "REMOTE" : "LOCAL";
+  return `Connected · ${label} · ${host}`;
+}
+
+export function messageConnectionLost(mode: TuiMode, host: string): string {
+  const label = mode === "remote" ? "REMOTE" : "LOCAL";
+  return `Connection lost · ${label} · ${host}`;
+}
+
+export function messageReconnected(
+  mode: TuiMode,
+  host: string,
+  disconnectedAt: number,
+  now: number = Date.now()
+): string {
+  const label = mode === "remote" ? "REMOTE" : "LOCAL";
+  const duration = formatDuration(Math.max(0, now - disconnectedAt));
+  return `Reconnected · ${label} · ${host} · ${duration} downtime`;
+}
+
+export function messageAuthRequired(mode: TuiMode, host: string): string {
+  const label = mode === "remote" ? "REMOTE" : "LOCAL";
+  return `Auth failed · ${label} · ${host}`;
+}
+
+export function messageAuthMissing(host: string): string {
+  return `No API credentials · REMOTE · ${host}`;
+}
+
+export function messageOfflineStartup(
+  mode: TuiMode,
+  host: string,
+  kind: "auth" | "network" | "rate-limit" | "unknown"
+): string {
+  const label = mode === "remote" ? "REMOTE" : "LOCAL";
+  if (kind === "auth") {
+    return `Could not connect · ${label} · ${host} (auth)`;
+  }
+  if (kind === "rate-limit") {
+    return `Could not connect · ${label} · ${host} (rate limited)`;
+  }
+  return `Could not connect · ${label} · ${host}`;
+}
+
+// ─── Toast factory functions ─────────────────────────────────────────────────
+
+/**
+ * Show a "Reconnected" toast with downtime duration.
+ * Called when the connection state transitions back to 'connected' after a
+ * disconnection period.
+ *
+ * @param disconnectedAt  Timestamp (ms) when the disconnection began
+ * @deprecated Prefer {@link toastReconnectedMode} for mode-aware copy
+ */
+export function toastReconnected(disconnectedAt: number): void {
+  const now = Date.now();
+  const downtime = now - disconnectedAt;
+  const duration = formatDuration(downtime);
+  toastSuccess(`Reconnected \u2022 ${duration} downtime`);
+}
+
+/** Mode-aware reconnect toast. */
+export function toastReconnectedMode(
+  mode: TuiMode,
+  host: string,
+  disconnectedAt: number
+): void {
+  toastSuccess(messageReconnected(mode, host, disconnectedAt), {
+    duration: 4000,
+  });
+}
+
+/**
+ * Show a rate limit warning toast.
+ * Called when the API returns HTTP 429.
+ */
+export function toastRateLimited(): void {
+  toastWarning("API rate limited \u2014 backing off", {
+    duration: 6000,
+  });
+}
+
+/**
+ * Show a config saved confirmation toast.
+ * Called after config-store persists to disk.
+ */
+export function toastConfigSaved(): void {
+  toastSuccess("Configuration saved", {
+    duration: 3000,
+  });
+}
+
+/**
+ * Show a deploy started toast (loading/persistent).
+ * Returns the toast ID so it can be updated to success/error when deploy completes.
+ *
+ * @param workerName  Name of the worker being deployed
+ * @returns           Toast ID for updating later
+ */
+export function toastDeployStarted(workerName: string): string | number {
+  return toastInfo(`Deploy started: ${workerName}`, {
+    duration: 0, // persistent until updated
+  });
+}
+
+/**
+ * Show a deploy completed toast.
+ * Updates or creates a success toast for the completed deployment.
+ *
+ * @param workerName  Name of the deployed worker
+ */
+export function toastDeployCompleted(workerName: string): void {
+  toastSuccess(`Deploy completed: ${workerName}`, {
+    duration: 4000,
+  });
+}
+
+/**
+ * Show a deploy failed toast.
+ *
+ * @param workerName  Name of the worker that failed to deploy
+ * @param error       Error message
+ */
+export function toastDeployFailed(workerName: string, error: string): void {
+  toastWarning(`Deploy failed: ${workerName} \u2014 ${error}`, {
+    duration: 8000,
+  });
+}
+
+/**
+ * Show a connection lost warning toast.
+ * Called when the connection transitions to 'offline'.
+ * @deprecated Prefer {@link toastConnectionLostMode}
+ */
+export function toastConnectionLost(): void {
+  toastWarning("Connection lost \u2014 retrying with backoff", {
+    duration: 0, // persistent until reconnected
+  });
+}
+
+/** Mode-aware connection lost toast. */
+export function toastConnectionLostMode(mode: TuiMode, host: string): void {
+  toastWarning(messageConnectionLost(mode, host), {
+    description:
+      mode === "remote"
+        ? "Check gateway URL, network, and HOOX_API_TOKEN"
+        : "Is `hoox dev` / wrangler running on this host?",
+    duration: 0,
+  });
+}
+
+/** First successful connect (startup or after offline). */
+export function toastConnectedMode(mode: TuiMode, host: string): void {
+  toastSuccess(messageConnected(mode, host), { duration: 3500 });
+}
+
+/** HTTP 401/403 while talking to the API. */
+export function toastAuthRequiredMode(mode: TuiMode, host: string): void {
+  toastError(messageAuthRequired(mode, host), {
+    description:
+      mode === "remote"
+        ? remoteAuthMissingHint()
+        : "Check HOOX_API_TOKEN if the local gateway enforces auth",
+    duration: 8000,
+  });
+}
+
+/**
+ * Remote launch without fail-closed auth (no Bearer and no Access pair).
+ * Prefer gating with `resolveTuiConnectionEnv().hasAuth` / `isRemoteAuthReady()`.
+ */
+export function toastAuthMissingRemote(host: string): void {
+  toastWarning(messageAuthMissing(host), {
+    description: remoteAuthMissingHint(),
+    duration: 7000,
+  });
+}
+
+/** Startup could not reach the API. */
+export function toastOfflineStartup(
+  mode: TuiMode,
+  host: string,
+  kind: "auth" | "network" | "rate-limit" | "unknown"
+): void {
+  const description =
+    kind === "auth"
+      ? remoteAuthMissingHint()
+      : mode === "remote"
+        ? "Remote gateway unreachable — CLI fallback is disabled in REMOTE mode"
+        : "Trying CLI fallback if available";
+  toastWarning(messageOfflineStartup(mode, host, kind), {
+    description,
+    duration: 6000,
+  });
+}