@profullstack/hqtui-demo 0.1.0

package/src/main.ts

@@ -0,0 +1,320 @@
+// Run directly with `bun src/main.ts`, or via the compiled bin on Node.
+/**
+ * The HQTUI reference dashboard.
+ *
+ *   bunx @profullstack/hqtui-demo            # real system metrics
+ *   bunx @profullstack/hqtui-demo --sim      # deterministic simulation
+ *
+ * Also runs under Node 22.6+ (`npx @profullstack/hqtui-demo`).
+ */
+import { createApp, themeList, themes, type KeyEvent } from "@profullstack/hqtui";
+import { createCollector } from "./system/index.ts";
+import { createState, SCREENS, type ScreenName } from "./state.ts";
+import {
+  componentsScreen, dashboardScreen, graphicsScreen, inputScreen, stressScreen, themesScreen, visibleProcesses,
+} from "./screens/index.ts";
+import { clock, num } from "./format.ts";
+
+interface Options {
+  real: boolean;
+  seed: number;
+  fps: number;
+  theme: string;
+  screen: ScreenName;
+  interval: number;
+}
+
+function parseArgs(argv: string[]): Options {
+  const options: Options = {
+    real: true,
+    seed: 1337,
+    fps: 30,
+    theme: "dark",
+    screen: "dashboard",
+    interval: 1000,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    switch (arg) {
+      case "--sim":
+      case "--fake":
+      case "--simulate": options.real = false; break;
+      case "--real": options.real = true; break;
+      case "--seed": options.seed = Number(value) || 1337; i++; break;
+      case "--fps": options.fps = Number(value) || 30; i++; break;
+      case "--theme": options.theme = value ?? "dark"; i++; break;
+      case "--screen": options.screen = (value as ScreenName) ?? "dashboard"; i++; break;
+      case "--interval": options.interval = Number(value) || 1000; i++; break;
+      case "-h":
+      case "--help": printHelp(); process.exit(0);
+      case "-v":
+      case "--version": console.log("hqtui-demo 0.1.0"); process.exit(0);
+    }
+  }
+  return options;
+}
+
+function printHelp(): void {
+  console.log(`hqtui-demo — the HQTUI reference dashboard
+
+Usage:
+  hqtui-demo [options]
+
+Options:
+  --sim              Use the deterministic simulation instead of real metrics
+  --real             Read real system metrics (default)
+  --seed <n>         Simulation seed (default 1337)
+  --fps <n>          Frame cap (default 30, 15 over SSH)
+  --theme <name>     dark, dracula, nord, tokyoNight, gruvbox, matrix, monochrome, highContrast, light
+  --screen <name>    dashboard, components, graphics, themes, input, stress
+  --interval <ms>    Metric refresh interval (default 1000)
+  -h, --help         Show this help
+  -v, --version      Show the version
+
+Keys:
+  1-6 / Tab screens   F2 theme   F3 filter   F6 sort   Ctrl+K palette
+  ↑/↓ select          Space pause            F1 help   q quit
+`);
+}
+
+const PALETTE_COMMANDS: { label: string; hint: string; run: (state: ReturnType<typeof createState>) => void }[] = [
+  { label: "Go to Dashboard", hint: "1", run: (s) => { s.screen = "dashboard"; } },
+  { label: "Go to Components", hint: "2", run: (s) => { s.screen = "components"; } },
+  { label: "Go to Graphics", hint: "3", run: (s) => { s.screen = "graphics"; } },
+  { label: "Go to Themes", hint: "4", run: (s) => { s.screen = "themes"; } },
+  { label: "Go to Input", hint: "5", run: (s) => { s.screen = "input"; } },
+  { label: "Go to Stress Test", hint: "6", run: (s) => { s.screen = "stress"; } },
+  { label: "Sort by CPU", hint: "F6", run: (s) => { s.sort = "cpu"; } },
+  { label: "Sort by Memory", hint: "F6", run: (s) => { s.sort = "mem"; } },
+  { label: "Pause updates", hint: "Space", run: (s) => { s.paused = !s.paused; } },
+];
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  const collector = await createCollector({ real: options.real, seed: options.seed });
+  await collector.refresh(options.interval / 1000);
+
+  const state = createState(collector.current(), collector.source, collector.unavailable);
+  state.screen = SCREENS.includes(options.screen) ? options.screen : "dashboard";
+  state.themeIndex = Math.max(0, themeList.findIndex((t) => t.name === options.theme || t === (themes as never)[options.theme]));
+
+  const app = await createApp({
+    theme: themeList[state.themeIndex] ?? themes.dark,
+    fps: options.fps,
+    title: "hqtui demo",
+    quitKeys: ["ctrl+c"],
+  });
+
+  // Metrics refresh on their own clock; rendering runs at the frame rate.
+  const dt = options.interval / 1000;
+  const poll = setInterval(() => {
+    if (state.paused) return;
+    void collector.refresh(dt).then(() => {
+      state.sample = collector.current();
+      app.invalidate();
+    });
+  }, options.interval);
+  poll.unref?.();
+
+  // The simulation is cheap enough to advance every frame, which is what makes
+  // the demo look alive rather than stepping once a second.
+  const animate = setInterval(() => {
+    if (state.paused || options.real) return;
+    void collector.refresh(0.1);
+    state.sample = collector.current();
+    app.invalidate();
+  }, 100);
+  animate.unref?.();
+
+  app.on("frame", (stats) => {
+    state.fps = stats.fps;
+    state.renderMs = stats.renderMs;
+    state.changedCells = stats.changedCells;
+    state.bytes = stats.bytes;
+  });
+
+  app.on("mouse", (event) => {
+    state.lastMouse = `${event.action} ${event.button} @ ${event.x},${event.y}${event.scroll ? ` scroll ${event.scroll}` : ""}`;
+    if (event.action === "scroll") {
+      state.offset = Math.max(0, state.offset + event.scroll * 3);
+    }
+  });
+
+  app.on("key", (event: KeyEvent) => {
+    state.lastKey = event.key;
+    state.keyLog.push(`${clock()}  ${event.key}${event.char ? `  "${event.char}"` : ""}`);
+    if (state.keyLog.length > 100) state.keyLog.shift();
+
+    // Overlays capture input first.
+    if (state.showPalette) {
+      const matches = PALETTE_COMMANDS.filter((c) => c.label.toLowerCase().includes(state.paletteQuery.toLowerCase()));
+      if (event.name === "escape") state.showPalette = false;
+      else if (event.name === "enter") {
+        matches[state.paletteIndex]?.run(state);
+        state.showPalette = false;
+      } else if (event.name === "up") state.paletteIndex = Math.max(0, state.paletteIndex - 1);
+      else if (event.name === "down") state.paletteIndex = Math.min(matches.length - 1, state.paletteIndex + 1);
+      else if (event.name === "backspace") state.paletteQuery = state.paletteQuery.slice(0, -1);
+      else if (event.char) state.paletteQuery += event.char;
+      return;
+    }
+    if (state.showModal) {
+      if (event.name === "escape" || event.name === "enter" || event.name === "n" || event.name === "y") {
+        state.showModal = false;
+      }
+      return;
+    }
+    if (state.showHelp) {
+      state.showHelp = false;
+      return;
+    }
+    if (state.filtering) {
+      if (event.name === "escape") { state.filtering = false; state.filter = ""; }
+      else if (event.name === "enter") state.filtering = false;
+      else if (event.name === "backspace") state.filter = state.filter.slice(0, -1);
+      else if (event.char) state.filter += event.char;
+      return;
+    }
+
+    switch (event.key) {
+      case "q": app.quit(); return;
+      case "f1": state.showHelp = true; return;
+      case "f2":
+        state.themeIndex = (state.themeIndex + 1) % themeList.length;
+        app.setTheme(themeList[state.themeIndex]);
+        return;
+      case "f3": state.filtering = true; return;
+      case "f6": {
+        const order = ["cpu", "mem", "pid", "name"] as const;
+        state.sort = order[(order.indexOf(state.sort) + 1) % order.length];
+        return;
+      }
+      case "f10": app.quit(); return;
+      case "ctrl+k":
+        state.showPalette = true;
+        state.paletteQuery = "";
+        state.paletteIndex = 0;
+        return;
+      case "space": state.paused = !state.paused; return;
+      case "up": state.selected = Math.max(0, state.selected - 1); break;
+      case "down": state.selected = Math.min(visibleProcesses(state).length - 1, state.selected + 1); break;
+      case "pageup": state.selected = Math.max(0, state.selected - 10); break;
+      case "pagedown": state.selected = Math.min(visibleProcesses(state).length - 1, state.selected + 10); break;
+      case "home": state.selected = 0; break;
+      case "end": state.selected = Math.max(0, visibleProcesses(state).length - 1); break;
+      case "enter": state.showModal = true; return;
+      case "left":
+        if (state.screen === "themes") {
+          state.themeIndex = (state.themeIndex - 1 + themeList.length) % themeList.length;
+          app.setTheme(themeList[state.themeIndex]);
+        }
+        return;
+      case "right":
+        if (state.screen === "themes") {
+          state.themeIndex = (state.themeIndex + 1) % themeList.length;
+          app.setTheme(themeList[state.themeIndex]);
+        }
+        return;
+      case "tab": state.screen = SCREENS[(SCREENS.indexOf(state.screen) + 1) % SCREENS.length]; return;
+    }
+
+    const digit = Number(event.name);
+    if (Number.isInteger(digit) && digit >= 1 && digit <= SCREENS.length) {
+      state.screen = SCREENS[digit - 1];
+    }
+
+    // Keep the selected row inside the visible window.
+    if (state.selected < state.offset) state.offset = state.selected;
+  });
+
+  app.render(({ ui, theme, height }) => {
+    ui.row({ size: 1 }, (header) => {
+      header.text(" hqtui.com", { fg: theme.title, bold: true, size: 12 });
+      header.tabs({
+        tabs: SCREENS.map((s, i) => `${i + 1} ${s}`),
+        active: SCREENS.indexOf(state.screen),
+        onSelect: (index) => { state.screen = SCREENS[index]; },
+      });
+      header.text(
+        `${state.paused ? "paused" : "live"}  ${state.source}  ${num(state.fps, 0)}fps  ${clock()} `,
+        { fg: state.paused ? theme.warning : theme.success, align: "right" },
+      );
+    });
+    ui.spacer(1);
+
+    ui.column({ size: height - 4 }, (body) => {
+      switch (state.screen) {
+        case "components": componentsScreen(body, state, theme); break;
+        case "graphics": graphicsScreen(body, state, theme); break;
+        case "themes": themesScreen(body, state, theme); break;
+        case "input": inputScreen(body, state, theme); break;
+        case "stress": stressScreen(body, state, theme); break;
+        default: dashboardScreen(body, state, theme); break;
+      }
+    });
+
+    ui.spacer(1);
+    ui.statusBar({
+      items: [
+        { key: "F1", label: "Help" },
+        { key: "F2", label: `Theme (${theme.name})` },
+        { key: "F3", label: state.filtering ? `Filter: ${state.filter}_` : "Filter", active: state.filtering },
+        { key: "F6", label: `Sort: ${state.sort}` },
+        { key: "^K", label: "Palette" },
+        { key: "Tab", label: "Screen" },
+        { key: "q", label: "Quit" },
+      ],
+      right: [{ label: `${num(state.renderMs, 2)}ms  ${state.changedCells} cells  ${state.bytes}B` }],
+    });
+
+    if (state.showHelp) {
+      ui.modal({
+        title: "HQTUI Demo — Help",
+        width: 62,
+        height: 18,
+        message:
+          "1-6 or Tab switch screens.\n" +
+          "F2 cycles themes, F3 filters processes, F6 changes sort.\n" +
+          "Ctrl+K opens the command palette, Space pauses updates.\n" +
+          "Arrows, PageUp/PageDown, Home/End move the selection.\n" +
+          "Mouse: click tabs and buttons, scroll the process list.\n\n" +
+          (state.unavailable.length
+            ? `Unavailable on this platform: ${state.unavailable.join(", ")}.\nRun with --sim to see every widget populated.`
+            : "All metrics available on this platform.") +
+          "\n\nPress any key to close.",
+        buttons: [{ label: "Close", focused: true }],
+      });
+    }
+    if (state.showModal) {
+      ui.modal({
+        title: "Confirm Action",
+        message: `Are you sure you want to terminate process ${visibleProcesses(state)[state.selected]?.pid ?? "—"} (${visibleProcesses(state)[state.selected]?.name ?? "—"})?`,
+        buttons: [
+          { label: "Yes", variant: "success", focused: true },
+          { label: "No", variant: "ghost" },
+        ],
+      });
+    }
+    if (state.showPalette) {
+      const matches = PALETTE_COMMANDS.filter((c) => c.label.toLowerCase().includes(state.paletteQuery.toLowerCase()));
+      ui.commandPalette({
+        query: state.paletteQuery,
+        items: matches.map((c) => ({ label: c.label, hint: c.hint })),
+        selected: state.paletteIndex,
+      });
+    }
+  });
+
+  app.on("exit", () => {
+    clearInterval(poll);
+    clearInterval(animate);
+  });
+
+  await app.start();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/screens/components.ts

@@ -0,0 +1,153 @@
+import type { Container, Theme } from "@profullstack/hqtui";
+import type { DemoState } from "../state.ts";
+import { bytes, percent } from "../format.ts";
+
+const FILES = [
+  { name: "src", size: "4.2 KB", type: "dir", modified: "2m ago" },
+  { name: "test", size: "1.1 KB", type: "dir", modified: "5m ago" },
+  { name: "package.json", size: "1.2 KB", type: "file", modified: "10m ago" },
+  { name: "README.md", size: "3.4 KB", type: "file", modified: "1h ago" },
+  { name: "bun.lockb", size: "12 KB", type: "file", modified: "1h ago" },
+];
+
+const TREE = [
+  {
+    label: "systemd",
+    expanded: true,
+    values: [{ text: "1.3", width: 6 }, { text: "0.1", width: 6 }],
+    children: [
+      { label: "bash", values: [{ text: "0.1", width: 6 }, { text: "0.2", width: 6 }] },
+      {
+        label: "bun",
+        expanded: true,
+        values: [{ text: "32.8", width: 6 }, { text: "4.2", width: 6 }],
+        children: [
+          { label: "bun:worker", values: [{ text: "12.4", width: 6 }, { text: "1.8", width: 6 }] },
+          { label: "bun:worker", values: [{ text: "8.7", width: 6 }, { text: "1.3", width: 6 }] },
+        ],
+      },
+      {
+        label: "node",
+        expanded: true,
+        values: [{ text: "18.1", width: 6 }, { text: "2.1", width: 6 }],
+        children: [{ label: "node:worker", values: [{ text: "6.1", width: 6 }, { text: "0.8", width: 6 }] }],
+      },
+      { label: "postgres", values: [{ text: "6.7", width: 6 }, { text: "1.8", width: 6 }] },
+    ],
+  },
+];
+
+/** Every widget in the library, in one screen. Also the interaction sandbox. */
+export function componentsScreen(ui: Container, state: DemoState, theme: Theme): void {
+  ui.row({ size: "1fr", gap: 1 }, (row) => {
+    row.column({ gap: 1 }, (left) => {
+      left.panel({ title: "Buttons & Inputs", size: 13 }, (p) => {
+        p.row({ size: 1, gap: 1 }, (r) => {
+          r.button({ label: "Primary", width: 11, size: 11, onPress: () => { state.showModal = true; } });
+          r.button({ label: "Success", width: 11, size: 11, variant: "success" });
+          r.button({ label: "Warning", width: 11, size: 11, variant: "warning" });
+          r.button({ label: "Danger", width: 10, size: 10, variant: "danger" });
+          r.spacer("fill");
+        });
+        p.spacer(1);
+        p.row({ size: 1, gap: 2 }, (r) => {
+          r.select({
+            value: ["Dark", "Dracula", "Nord", "Tokyo Night"][state.selectIndex] ?? "Dark",
+            width: 20,
+            size: 20,
+            open: state.selectOpen,
+            options: ["Dark", "Dracula", "Nord", "Tokyo Night"],
+            selectedIndex: state.selectIndex,
+            onOpen: () => { state.selectOpen = !state.selectOpen; },
+          });
+          r.checkbox({
+            label: "Toggle",
+            checked: state.toggle,
+            variant: "toggle",
+            size: 12,
+            onToggle: () => { state.toggle = !state.toggle; },
+          });
+          r.checkbox({
+            label: "Checkbox",
+            checked: state.checkbox,
+            size: 14,
+            onToggle: () => { state.checkbox = !state.checkbox; },
+          });
+          r.spacer("fill");
+        });
+        p.spacer(1);
+        p.textInput({ label: "Search", value: state.inputValue, placeholder: "type to filter…", size: 1 });
+        p.spacer(1);
+        p.meter({ label: "Slider", value: state.slider, style: "smooth", heat: false, color: theme.primary });
+        p.progress({ label: "Progress", value: 37, max: 120, showCount: true });
+      });
+
+      left.panel({ title: "Table Widget", size: "1fr" }, (p) => {
+        p.table({
+          rows: FILES,
+          selected: state.selected % FILES.length,
+          zebra: true,
+          columns: [
+            { key: "name", title: "Name", min: 10, color: theme.primary },
+            { key: "size", title: "Size", width: 9, align: "right" },
+            { key: "type", title: "Type", width: 6 },
+            { key: "modified", title: "Modified", width: 10, align: "right", color: theme.muted },
+          ],
+        });
+      });
+
+      left.panel({ title: "Log Viewer", size: 11 }, (p) => {
+        p.log({
+          entries: state.sample.logs.map((l) => ({ time: l.time, level: l.level, message: l.message, meta: `{${l.meta}}` })),
+        });
+      });
+    });
+
+    row.column({ gap: 1 }, (right) => {
+      right.panel({ title: "Process Tree", size: 13 }, (p) => {
+        p.row({ size: 1 }, (r) => {
+          r.text("Name", { fg: theme.muted, bold: true });
+          r.text("CPU%   MEM%", { fg: theme.muted, bold: true, align: "right" });
+        });
+        p.tree({ nodes: TREE, selected: state.selected % 8 });
+      });
+
+      right.panel({ title: "Sparklines & Gauges", size: 12 }, (p) => {
+        p.sparkline({ label: "CPU ", values: state.sample.cpu.history, text: percent(state.sample.cpu.total), color: theme.success });
+        p.sparkline({ label: "Mem ", values: state.sample.memory.history, text: percent(state.sample.memory.used / state.sample.memory.total), color: theme.warning });
+        p.sparkline({ label: "Net ", values: state.sample.network.downHistory, text: bytes(state.sample.network.downRate) + "/s", color: theme.primary });
+        p.spacer(1);
+        p.row({ size: "1fr", gap: 2 }, (r) => {
+          r.gauge({ value: state.sample.cpu.total, label: percent(state.sample.cpu.total) });
+          r.donut({
+            segments: [
+              { value: state.sample.memory.used, color: theme.primary, label: "Used" },
+              { value: state.sample.memory.available, color: theme.warning, label: "Free" },
+            ],
+          });
+        });
+      });
+
+      right.panel({ title: "Lists & Badges", size: "1fr" }, (p) => {
+        p.row({ size: 1, gap: 1 }, (r) => {
+          r.badge({ text: "active", color: theme.success, size: 10 });
+          r.badge({ text: "idle", color: theme.warning, variant: "subtle", size: 8 });
+          r.badge({ text: "failed", color: theme.danger, variant: "outline", size: 10 });
+          r.spacer("fill");
+        });
+        p.spacer(1);
+        p.list({
+          items: [
+            { label: "apps/demo", color: theme.primary },
+            { label: "packages/hqtui" },
+            { label: "apps/web" },
+            { label: "docs" },
+          ],
+          selected: state.selected % 4,
+          bullet: "▸",
+          scrollbar: true,
+        });
+      });
+    });
+  });
+}