@hoox-sh/hoox-tui 0.2.0

package/src/components/ui/dialog.tsx

@@ -0,0 +1,281 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * Thin wrappers around @opentui-ui/dialog/react with Hoox color tokens.
+ * Provides ConfirmDialog, ChoiceDialog, and LoadingDialog helpers.
+ *
+ * All dialogs render centered with a dimmed backdrop (backdropOpacity 0.35)
+ * and use Colors tokens from @hoox-sh/hoox-shared for consistent Hoox branding.
+ */
+import { useState } from "react";
+import {
+  type ChoiceContext,
+  type ConfirmContext,
+  type DialogId,
+  useDialogKeyboard,
+} from "@opentui-ui/dialog/react";
+import { Colors } from "@hoox-sh/hoox-shared";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** Options for confirm dialogs (Yes/No, Confirm/Cancel) */
+export interface ConfirmDialogOptions {
+  /** Dialog title (bold, accent-colored) */
+  title: string;
+  /** Explanatory message below the title */
+  message: string;
+  /** Label for the affirmative button (default: "Confirm") */
+  confirmLabel?: string;
+  /** Label for the dismiss button (default: "Cancel") */
+  cancelLabel?: string;
+  /** Whether clicking outside the dialog dismisses it (default: true) */
+  closeOnClickOutside?: boolean;
+}
+
+/** A single choice item in a choice dialog */
+export interface ChoiceOption<K extends string = string> {
+  key: K;
+  label: string;
+  description?: string;
+}
+
+/** Options for choice dialogs */
+export interface ChoiceDialogOptions<K extends string = string> {
+  /** Dialog title */
+  title: string;
+  /** Array of selectable options */
+  choices: ChoiceOption<K>[];
+  /** Value returned when dialog is dismissed via ESC/backdrop (default: undefined) */
+  fallback?: K;
+  /** Whether clicking outside dismisses (default: true) */
+  closeOnClickOutside?: boolean;
+}
+
+/** Dialog manager interface — subset of what useDialog() returns */
+export interface DialogHandle {
+  confirm(options: {
+    content: (ctx: ConfirmContext) => unknown;
+    closeOnClickOutside?: boolean;
+  }): Promise<boolean>;
+  choice<K extends string>(options: {
+    content: (ctx: ChoiceContext<K>) => unknown;
+    fallback?: K;
+    closeOnClickOutside?: boolean;
+  }): Promise<K | undefined>;
+  show(options: {
+    content: () => unknown;
+    id?: string | number;
+  }): string | number;
+  close(id?: string | number): void;
+}
+
+// ── Internal: keyboard-navigable choice list ──────────────────────────────
+
+/** Props for the keyboard-navigable choice list rendered inside a dialog */
+interface ChoiceListProps<K extends string = string> {
+  choices: ChoiceOption<K>[];
+  accentColor: string;
+  foregroundColor: string;
+  mutedColor: string;
+  highlightColor: string;
+  resolve: (value: K) => void;
+  dismiss: () => void;
+  dialogId: DialogId;
+}
+
+/**
+ * Internal component that renders a keyboard-navigable choice list.
+ * Uses useDialogKeyboard scoped to the dialog so only the topmost
+ * dialog receives keyboard events.
+ */
+function ChoiceList<K extends string = string>({
+  choices,
+  accentColor,
+  foregroundColor,
+  mutedColor,
+  highlightColor,
+  resolve,
+  dismiss,
+  dialogId,
+}: ChoiceListProps<K>) {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  useDialogKeyboard((key) => {
+    if (key.name === "down" || key.name === "j") {
+      setSelectedIndex((prev) => (prev < choices.length - 1 ? prev + 1 : 0));
+    }
+    if (key.name === "up" || key.name === "k") {
+      setSelectedIndex((prev) => (prev > 0 ? prev - 1 : choices.length - 1));
+    }
+    if (key.name === "return") {
+      const choice = choices[selectedIndex];
+      if (choice) resolve(choice.key);
+    }
+    if (key.name === "escape") {
+      dismiss();
+    }
+  }, dialogId);
+
+  return (
+    <box flexDirection="column" gap={0}>
+      {choices.map((choice, idx) => (
+        <box flexDirection="row" gap={2} paddingLeft={1} paddingRight={1}>
+          {/* Selection indicator */}
+          <text fg={idx === selectedIndex ? accentColor : mutedColor}>
+            {idx === selectedIndex ? "▶" : " "}
+          </text>
+          {/* Choice label */}
+          <text
+            fg={idx === selectedIndex ? foregroundColor : mutedColor}
+            bg={idx === selectedIndex ? highlightColor : undefined}
+            onMouseUp={() => resolve(choice.key)}
+          >
+            {choice.label}
+          </text>
+          {/* Optional description */}
+          {choice.description && (
+            <text dim fg={mutedColor}>
+              — {choice.description}
+            </text>
+          )}
+        </box>
+      ))}
+    </box>
+  );
+}
+
+// ── Dialog wrapper functions ───────────────────────────────────────────────
+
+/**
+ * Show a confirmation dialog styled with Hoox colors.
+ * Returns `true` if confirmed, `false` if canceled or dismissed.
+ *
+ * @example
+ * const confirmed = await showConfirm(dialog, {
+ *   title: "Delete Worker",
+ *   message: "This action cannot be undone.",
+ *   confirmLabel: "Delete",
+ *   cancelLabel: "Keep",
+ * })
+ */
+export async function showConfirm(
+  dialog: DialogHandle,
+  options: ConfirmDialogOptions
+): Promise<boolean> {
+  return dialog.confirm({
+    content: (ctx: ConfirmContext) => (
+      <box flexDirection="column" padding={1} gap={1}>
+        <text fg={Colors.accent}>
+          <b>{options.title}</b>
+        </text>
+        <text fg={Colors.muted}>{options.message}</text>
+        <box flexDirection="row" gap={2} justifyContent="flex-end">
+          <text fg={Colors.muted} onMouseUp={() => ctx.resolve(false)}>
+            {"  "}
+            {options.cancelLabel ?? "Cancel"}
+            {"  "}
+          </text>
+          <text
+            fg={Colors.accent}
+            bg={Colors.card}
+            onMouseUp={() => ctx.resolve(true)}
+          >
+            {"  "}
+            {options.confirmLabel ?? "Confirm"}
+            {"  "}
+          </text>
+        </box>
+      </box>
+    ),
+    closeOnClickOutside: options.closeOnClickOutside ?? true,
+  });
+}
+
+/**
+ * Show a multiple-choice dialog styled with Hoox colors.
+ * Returns the selected choice key, or `fallback` if dismissed.
+ *
+ * @example
+ * const action = await showChoice(dialog, {
+ *   title: "Select Action",
+ *   choices: [
+ *     { key: "restart", label: "Restart Worker", description: "Graceful restart" },
+ *     { key: "stop",    label: "Stop Worker",    description: "Immediate halt" },
+ *   ],
+ * })
+ */
+export async function showChoice<K extends string>(
+  dialog: DialogHandle,
+  options: ChoiceDialogOptions<K>
+): Promise<K | undefined> {
+  return dialog.choice<K>({
+    content: (ctx: ChoiceContext<K>) => (
+      <box flexDirection="column" padding={1} gap={1}>
+        {/* Header */}
+        <text fg={Colors.accent}>
+          <b>{options.title}</b>
+        </text>
+        <text dim fg={Colors.muted}>
+          Use ↑↓ to navigate, Enter to select, Esc to cancel
+        </text>
+
+        {/* Divider */}
+        <box height={1} />
+
+        {/* Keyboard-navigable choice list */}
+        <ChoiceList
+          choices={options.choices}
+          accentColor={Colors.accent}
+          foregroundColor={Colors.foreground}
+          mutedColor={Colors.muted}
+          highlightColor={Colors.card}
+          resolve={ctx.resolve}
+          dismiss={ctx.dismiss}
+          dialogId={ctx.dialogId}
+        />
+
+        {/* Footer actions */}
+        <box flexDirection="row" justifyContent="flex-end" paddingTop={1}>
+          <text fg={Colors.muted} onMouseUp={ctx.dismiss}>
+            {"  Cancel  "}
+          </text>
+        </box>
+      </box>
+    ),
+    fallback: options.fallback,
+    closeOnClickOutside: options.closeOnClickOutside ?? true,
+  });
+}
+
+/**
+ * Show a non-interactive loading dialog (centered, dimmed backdrop).
+ * Returns a `close` function to dismiss the dialog when loading completes.
+ *
+ * @example
+ * const close = showLoading(dialog, "Deploying workers...")
+ * await deployAll()
+ * close()
+ */
+export function showLoading(dialog: DialogHandle, message: string): () => void {
+  const id = dialog.show({
+    content: () => (
+      <box
+        flexDirection="column"
+        padding={2}
+        gap={1}
+        justifyContent="center"
+        alignItems="center"
+      >
+        <text fg={Colors.accent}>{message}</text>
+        <text dim fg={Colors.muted}>
+          Please wait...
+        </text>
+      </box>
+    ),
+  });
+  return () => dialog.close(id);
+}

package/src/components/ui/select.tsx

@@ -0,0 +1,197 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/** @jsxImportSource @opentui/react */
+/**
+ * SelectModal — a thin wrapper combining @opentui-ui/dialog modal behavior
+ * with keyboard-navigable option selection, styled with Hoox color tokens.
+ *
+ * Keyboard navigation:
+ *   - Up/Down (or j/k): move selection
+ *   - Enter: confirm selection
+ *   - Escape: dismiss
+ *
+ * All colors use Colors tokens from @hoox-sh/hoox-shared (no hardcoded hex).
+ */
+import { useState } from "react";
+import {
+  type DialogId,
+  type PromptContext,
+  useDialogKeyboard,
+} from "@opentui-ui/dialog/react";
+import { Colors } from "@hoox-sh/hoox-shared";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** A single selectable option */
+export interface SelectOption {
+  /** Unique key for the option */
+  key: string;
+  /** Display label shown in the list */
+  label: string;
+  /** Optional description rendered dimmed below or beside the label */
+  description?: string;
+}
+
+/** Options for the SelectModal */
+export interface SelectModalOptions {
+  /** Title displayed at the top of the modal (bold, accent-colored) */
+  title: string;
+  /** Array of selectable options */
+  options: SelectOption[];
+  /** Whether clicking outside the modal dismisses it (default: true) */
+  closeOnClickOutside?: boolean;
+}
+
+/** Dialog handle — the subset of useDialog() needed by SelectModal */
+export interface SelectDialogHandle {
+  prompt<T>(options: {
+    content: (ctx: PromptContext<T>) => unknown;
+    fallback?: T;
+    closeOnClickOutside?: boolean;
+  }): Promise<T | undefined>;
+}
+
+// ── Internal: keyboard-navigable option list ───────────────────────────────
+
+/** Props for the selectable option list rendered inside the dialog */
+interface SelectListProps {
+  options: SelectOption[];
+  accentColor: string;
+  foregroundColor: string;
+  mutedColor: string;
+  highlightColor: string;
+  resolve: (value: string) => void;
+  dismiss: () => void;
+  dialogId: DialogId;
+}
+
+/**
+ * Internal component that renders a keyboard-navigable option list.
+ * Uses useDialogKeyboard scoped to the dialog so that only the topmost
+ * dialog receives keyboard events.
+ */
+function SelectList({
+  options,
+  accentColor,
+  foregroundColor,
+  mutedColor,
+  highlightColor,
+  resolve,
+  dismiss,
+  dialogId,
+}: SelectListProps) {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  useDialogKeyboard((key) => {
+    if (key.name === "down" || key.name === "j") {
+      setSelectedIndex((prev) => (prev < options.length - 1 ? prev + 1 : 0));
+    }
+    if (key.name === "up" || key.name === "k") {
+      setSelectedIndex((prev) => (prev > 0 ? prev - 1 : options.length - 1));
+    }
+    if (key.name === "return") {
+      const selected = options[selectedIndex];
+      if (selected) resolve(selected.key);
+    }
+    if (key.name === "escape") {
+      dismiss();
+    }
+  }, dialogId);
+
+  return (
+    <box flexDirection="column" gap={0}>
+      {options.map((opt, idx) => (
+        <box flexDirection="row" gap={2} paddingLeft={1} paddingRight={1}>
+          {/* Selection indicator */}
+          <text fg={idx === selectedIndex ? accentColor : mutedColor}>
+            {idx === selectedIndex ? "▶" : " "}
+          </text>
+          {/* Option label */}
+          <text
+            fg={idx === selectedIndex ? foregroundColor : mutedColor}
+            bg={idx === selectedIndex ? highlightColor : undefined}
+            onMouseUp={() => resolve(opt.key)}
+          >
+            {opt.label}
+          </text>
+          {/* Optional description */}
+          {opt.description && (
+            <text dim fg={mutedColor}>
+              — {opt.description}
+            </text>
+          )}
+        </box>
+      ))}
+    </box>
+  );
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Show a modal select dialog with keyboard navigation.
+ *
+ * Returns the selected option's `key`, or `undefined` if dismissed
+ * (via Escape, clicking outside, or pressing Cancel).
+ *
+ * Keyboard controls:
+ *   - Up/Down or j/k: move selection highlight
+ *   - Enter: confirm current selection
+ *   - Escape: dismiss
+ *
+ * @example
+ * const chosen = await showSelectModal(dialog, {
+ *   title: "Select Worker",
+ *   options: [
+ *     { key: "worker-a", label: "Alpha Worker", description: "US-East" },
+ *     { key: "worker-b", label: "Beta Worker",  description: "EU-West" },
+ *   ],
+ * })
+ */
+export async function showSelectModal(
+  dialog: SelectDialogHandle,
+  opts: SelectModalOptions
+): Promise<string | undefined> {
+  const { title, options, closeOnClickOutside = true } = opts;
+
+  return dialog.prompt<string>({
+    content: (ctx: PromptContext<string>) => (
+      <box flexDirection="column" padding={1} gap={1}>
+        {/* Header */}
+        <text fg={Colors.accent}>
+          <b>{title}</b>
+        </text>
+        <text dim fg={Colors.muted}>
+          Use ↑↓ to navigate, Enter to select, Esc to cancel
+        </text>
+
+        {/* Divider */}
+        <box height={1} />
+
+        {/* Selectable list */}
+        <SelectList
+          options={options}
+          accentColor={Colors.accent}
+          foregroundColor={Colors.foreground}
+          mutedColor={Colors.muted}
+          highlightColor={Colors.card}
+          resolve={ctx.resolve}
+          dismiss={ctx.dismiss}
+          dialogId={ctx.dialogId}
+        />
+
+        {/* Footer actions */}
+        <box flexDirection="row" justifyContent="flex-end" paddingTop={1}>
+          <text fg={Colors.muted} onMouseUp={ctx.dismiss}>
+            {"  Cancel  "}
+          </text>
+        </box>
+      </box>
+    ),
+    fallback: undefined,
+    closeOnClickOutside,
+  });
+}

package/src/components/ui/toast.tsx

@@ -0,0 +1,185 @@
+/**
+ * Copyright (c) 2026 HOOX · HOOX · jango-blockchained (hoox-sh)
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Thin wrappers around @opentui-ui/toast with Hoox color token defaults.
+ * Provides toast helper functions (success, error, warning, info, loading)
+ * pre-configured with Hoox design system colors and durations.
+ *
+ * All helpers use the global toast singleton from @opentui-ui/toast.
+ * A ToasterRenderable must be initialized in the app root before calling
+ * these functions (see app.tsx).
+ */
+import { toast, TOAST_DURATION } from "@opentui-ui/toast";
+import { Colors } from "@hoox-sh/hoox-shared";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+/** Options that can be passed to any toast helper */
+export interface ToastOptions {
+  /** Additional description text below the message */
+  description?: string;
+  /** Auto-dismiss duration in ms (overrides the helper's default) */
+  duration?: number;
+  /** Whether the toast can be manually dismissed (default: true) */
+  dismissible?: boolean;
+  /** Action button with label and click handler */
+  action?: { label: string; onClick: () => void };
+  /** Show a close button on the toast (default: false) */
+  closeButton?: boolean;
+}
+
+/** Returned toast ID for programmatic control */
+export type ToastId = string | number;
+
+// ── Hoox-styled toast style overrides ──────────────────────────────────────
+
+/** Base style shared across all toast types */
+const baseStyle = {
+  backgroundColor: Colors.card,
+  foregroundColor: Colors.foreground,
+  borderColor: Colors.border,
+  paddingX: 1,
+  paddingY: 0,
+};
+
+/** Per-type border color overrides using Hoox design tokens */
+const hooxTypeStyles = {
+  success: { borderColor: Colors.success },
+  error: { borderColor: Colors.error },
+  warning: { borderColor: Colors.warning },
+  info: { borderColor: Colors.highlight },
+  loading: { borderColor: Colors.dim },
+};
+
+// ── Toast helper functions ─────────────────────────────────────────────────
+
+/**
+ * Show a success toast notification.
+ * Uses green border (Colors.success) and 3s auto-dismiss.
+ *
+ * @example
+ * toastSuccess("Worker deployed successfully")
+ */
+export function toastSuccess(message: string, options?: ToastOptions): ToastId {
+  return toast.success(message, {
+    ...options,
+    style: { ...baseStyle, ...hooxTypeStyles.success },
+    duration: options?.duration ?? TOAST_DURATION.SHORT,
+  });
+}
+
+/**
+ * Show an error toast notification.
+ * Uses red border (Colors.error) and 6s auto-dismiss.
+ *
+ * @example
+ * toastError("Failed to connect to API", { description: "Check your network" })
+ */
+export function toastError(message: string, options?: ToastOptions): ToastId {
+  return toast.error(message, {
+    ...options,
+    style: { ...baseStyle, ...hooxTypeStyles.error },
+    duration: options?.duration ?? TOAST_DURATION.LONG,
+  });
+}
+
+/**
+ * Show a warning toast notification.
+ * Uses amber border (Colors.warning) and 6s auto-dismiss.
+ *
+ * @example
+ * toastWarning("Rate limit approaching", { description: "Slow down requests" })
+ */
+export function toastWarning(message: string, options?: ToastOptions): ToastId {
+  return toast.warning(message, {
+    ...options,
+    style: { ...baseStyle, ...hooxTypeStyles.warning },
+    duration: options?.duration ?? TOAST_DURATION.LONG,
+  });
+}
+
+/**
+ * Show an info toast notification.
+ * Uses accent border (Colors.accent, orange) and 4s auto-dismiss.
+ *
+ * @example
+ * toastInfo("New version available", { action: { label: "Update", onClick: () => {} } })
+ */
+export function toastInfo(message: string, options?: ToastOptions): ToastId {
+  return toast.info(message, {
+    ...options,
+    style: { ...baseStyle, ...hooxTypeStyles.info },
+    duration: options?.duration ?? TOAST_DURATION.DEFAULT,
+  });
+}
+
+/**
+ * Show a persistent loading toast notification.
+ * Uses muted border (Colors.muted) and does NOT auto-dismiss.
+ * Returns the toast ID so it can be updated to success/error later.
+ *
+ * @example
+ * const id = toastLoading("Deploying worker...")
+ * try {
+ *   await deploy()
+ *   toastSuccess("Deployed!", { id })
+ * } catch {
+ *   toastError("Deploy failed", { id })
+ * }
+ */
+export function toastLoading(
+  message: string,
+  options?: Omit<ToastOptions, "duration">
+): ToastId {
+  return toast.loading(message, {
+    ...options,
+    style: { ...baseStyle, ...hooxTypeStyles.loading },
+    duration: TOAST_DURATION.PERSISTENT,
+  } as ToastOptions);
+}
+
+/**
+ * Dismiss a specific toast or all toasts.
+ * Thin wrapper around toast.dismiss().
+ *
+ * @example
+ * dismissToast(id)   // dismiss specific
+ * dismissToast()     // dismiss all
+ */
+export function dismissToast(id?: ToastId): void {
+  toast.dismiss(id as string | number | undefined);
+}
+
+// ── Clipboard copy feedback ────────────────────────────────────────────────
+
+const COPY_PREVIEW_MAX = 48;
+
+/** Pure message for “copied” toast (testable). */
+export function messageCopiedToClipboard(text: string): string {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  if (!oneLine) return "Copied to clipboard";
+  if (oneLine.length <= COPY_PREVIEW_MAX) {
+    return `Copied: “${oneLine}”`;
+  }
+  return `Copied: “${oneLine.slice(0, COPY_PREVIEW_MAX - 1)}…”`;
+}
+
+/** Toast after successful clipboard write (selection auto-copy, etc.). */
+export function toastCopiedToClipboard(text: string): ToastId {
+  const lines = text.split("\n").filter((l) => l.length > 0).length;
+  return toastSuccess(messageCopiedToClipboard(text), {
+    description: lines > 1 ? `${lines} lines` : undefined,
+    duration: 2500,
+  });
+}
+
+/** Toast when clipboard write fails. */
+export function toastCopyFailed(error: string): ToastId {
+  return toastError("Copy failed", {
+    description: error,
+    duration: 5000,
+  });
+}