@nexusbloom/cli 0.2.12 → 0.3.0

package/src/ui.js

@@ -0,0 +1,371 @@
+/**
+ * ui.js — Terminal UI helpers for the nxb CLI.
+ *
+ * Everything rendering / prompting related lives here so command modules
+ * stay lean and the look-and-feel is consistent across `list`, `abbr`, `run`, etc.
+ *
+ * Exports:
+ *   - Visual primitives  : renderHeader, renderBox, renderBadge, divider
+ *   - Table printer       : renderTable
+ *   - Pagination engine   : paginate (pure) + paginateInteractive (live nav)
+ *   - Prompt wrappers     : promptSelect, promptInput, promptConfirm,
+ *                           promptNumber, promptCheckbox, promptMultiSelect
+ */
+
+import chalk from "chalk";
+import {
+  select,
+  input,
+  confirm,
+  number,
+  checkbox,
+  Separator,
+} from "@inquirer/prompts";
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+export const PAGE_SIZE = 10;
+
+// Box-drawing palette
+const BOX = {
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  h: "─",
+  v: "│",
+};
+
+// Badge style map per tool type / category
+const BADGE_STYLES = {
+  local: { label: chalk.bgBlueBright.white(" local   "), border: "blueBright" },
+  builtin: { label: chalk.bgGreen.white(" builtin "), border: "green" },
+  community: { label: chalk.bgMagenta.white("community"), border: "magenta" },
+  uncategorized: { label: chalk.bgGray.white("  uncat  "), border: "gray" },
+};
+
+// ─── Simple helpers ──────────────────────────────────────────────────────────
+
+/** Print a thin horizontal rule across the terminal. */
+export function divider(width = 60) {
+  return console.log(chalk.gray("─".repeat(width)));
+}
+
+/**
+ * Render a centered header with a title and optional subtitle.
+ * Clears any previous inquirer prompt state.
+ */
+export function renderHeader(title, { subtitle, color = "cyanBright" } = {}) {
+  const bar = "═".repeat(Math.max(title.length + 4, 30));
+  const line1 = chalk[color].bold(`  ${bar}`);
+  const line2 = chalk[color].bold(`  ║  ${title.padEnd(title.length)}  ║`);
+  const line3 = chalk[color].bold(`  ${bar}`);
+  console.log("\n" + line1);
+  console.log(line2);
+  console.log(line3);
+  if (subtitle) {
+    console.log(chalk.dim(`  ${subtitle}\n`));
+  } else {
+    console.log();
+  }
+}
+
+/**
+ * Render a bordered box around arbitrary content lines.
+ *
+ *   renderBox("Results", ["line one", "line two"], { footer: "done." })
+ */
+export function renderBox(title, lines = [], { footer, width, borderColor = "gray" } = {}) {
+  const border = chalk[borderColor];
+  const innerWidth = (width || Math.min(72, Math.max(40, Math.max(...(lines || []).map(l => (l || "").length), title.length)))) - 4;
+  const top = border(`${BOX.topLeft}${BOX.h.repeat(innerWidth + 2)}${BOX.topRight}`);
+
+  const titleLine = border(BOX.v) + " " + chalk.bold(title) + " " + border(BOX.v);
+
+  const body = (lines || []).map((line) => {
+    const cleaned = typeof line === "string" ? line : String(line);
+    return border(BOX.v) + " " + cleaned.padEnd(innerWidth) + " " + border(BOX.v);
+  });
+
+  const bottom = border(`${BOX.bottomLeft}${BOX.h.repeat(innerWidth + 2)}${BOX.bottomRight}`);
+
+  console.log("\n" + top);
+  console.log(titleLine);
+  if (body.length) console.log(body.join("\n"));
+  if (footer) console.log(" " + chalk.dim(footer));
+  console.log(bottom + "\n");
+}
+
+/**
+ * Render a small colored badge.
+ *
+ *   renderBadge("local")          → blue background
+ *   renderBadge("image")          → category badge
+ *   renderBadge("custom", "info") → generic info badge
+ */
+export function renderBadge(text, type = "info") {
+  if (type === "tool") {
+    const style = BADGE_STYLES[text] || BADGE_STYLES.uncategorized;
+    return style.label;
+  }
+  // Generic info badge
+  return chalk.gray(`[${text}]`);
+}
+
+/** Pre-built type badge for tool objects. */
+export function typeBadge(tool) {
+  const t = tool?.type || "builtin";
+  return renderBadge(t, "tool");
+}
+
+/** Pre-built category badge — shows the category name in a muted block. */
+export function categoryBadge(cat) {
+  const c = (cat || "uncategorized").toLowerCase();
+  // Known categories get a coloured block
+  const known = {
+    text: chalk.bgWhite.black(" text  "),
+    image: chalk.bgCyan.black(" image "),
+    data: chalk.bgYellow.black(" data  "),
+    network: chalk.bgBlue.white("network"),
+    security: chalk.bgRed.white("secure"),
+    development: chalk.bgGreen.white("  dev  "),
+    utility: chalk.bgGray.white("utils "),
+    math: chalk.bgGray.white(" math  "),
+    business: chalk.bgGray.white("biz   "),
+    education: chalk.bgGray.white(" learn "),
+  };
+  if (known[c]) return known[c];
+  // Show first 6 chars for unknown categories
+  const label = c === "uncategorized" ? " any   " : c.slice(0, 6).padEnd(6);
+  return chalk.bgGray.white(` ${label} `);
+}
+
+// ─── Table printer ───────────────────────────────────────────────────────────
+
+/**
+ * Render an aligned text table.
+ *
+ *   cols: [{ key, header, width?, align?, color? }]
+ *   rows: array of objects keyed by `key`
+ */
+export function renderTable(cols, rows, { indent = "  ", headColor = "bold" } = {}) {
+  const computed = cols.map((c) => ({
+    ...c,
+    width: c.width || Math.max(c.header.length, ...rows.map((r) => stringWidth(r[c.key]))),
+  }));
+
+  const fmt = (val, col) => {
+    const str = val == null ? "" : String(val);
+    const trimmed = str.length > col.width ? str.slice(0, col.width - 1) + "…" : str;
+    let cell = trimmed.padEnd(col.width);
+    if (col.align === "right") cell = trimmed.padStart(col.width);
+    if (col.color) return col.color(cell);
+    return cell;
+  };
+
+  // Header
+  const headLine = indent + computed.map((c) => chalk[headColor](c.header.padEnd(c.width))).join("  ");
+  const sepLine = indent + computed.map((c) => chalk.gray("─".repeat(c.width))).join("  ");
+
+  console.log(headLine);
+  console.log(sepLine);
+  for (const row of rows) {
+    console.log(indent + computed.map((c) => fmt(row[c.key], c)).join("  "));
+  }
+}
+
+/** Byte-safe string width (strips ANSI, handles emoji roughly). */
+function stringWidth(str) {
+  return (str || "").replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+// ─── Pagination engine ───────────────────────────────────────────────────────
+
+/**
+ * Pure pagination.  Given a flat list, return a slice plus navigation metadata.
+ *
+ *   const page = paginate(items, 10, 2);
+ *   // { items, page, totalPages, total, pageSize, startIndex, endIndex,
+ *       hasPrev, hasNext }
+ */
+export function paginate(items, pageSize = PAGE_SIZE, currentPage = 1) {
+  const list = items || [];
+  const total = list.length;
+  const totalPages = Math.max(1, Math.ceil(total / pageSize));
+  const page = Math.max(1, Math.min(currentPage, totalPages));
+  const startIndex = (page - 1) * pageSize;
+  const endIndex = Math.min(startIndex + pageSize, total);
+  return {
+    items: list.slice(startIndex, endIndex),
+    page,
+    totalPages,
+    total,
+    pageSize,
+    startIndex,
+    endIndex,
+    hasPrev: page > 1,
+    hasNext: page < totalPages,
+  };
+}
+
+/**
+ * Interactive paginator: renders the current page via `renderPage`, then offers
+ * prev / next / cancel navigation until the user settles.
+ *
+ *   renderPage(pageResult)  → returns a value or Promise; its return is used as
+ *                             the final resolved value when the user picks "Done".
+ *
+ * Returns the last rendered page object (with `selected` set when applicable)
+ * or `null` on cancel.
+ */
+export async function paginateInteractive(items, pageSize, renderPage, options = {}) {
+  const all = items || [];
+  if (all.length === 0) {
+    renderPage(paginate([], pageSize, 1));
+    return null;
+  }
+
+  let page = 1;
+  let result = paginate(all, pageSize, page);
+
+  while (true) {
+    // Clear and re-render the page
+    if (process.stdout.isTTY) process.stdout.write("\x1b[?25l"); // hide cursor
+    renderPage(result);
+
+    if (result.totalPages === 1) {
+      if (process.stdout.isTTY) process.stdout.write("\x1b[?25h");
+      return result;
+    }
+
+    // Build navigator choices
+    const footer = [];
+    if (result.hasPrev) footer.push({ name: `${chalk.cyan("◀  Prev page")}`, value: "prev", description: "Show previous page" });
+    footer.push({ name: `${chalk.cyan("→  Done")}`, value: "done", description: "Keep current view" });
+    if (result.hasNext) footer.push({ name: `${chalk.cyan("▶  Next page")}`, value: "next", description: "Show next page" });
+    footer.push({ name: `${chalk.red("✕  Cancel")}`, value: "cancel", description: "Abort" });
+
+    const choices = [
+      new Separator(),
+      ...footer,
+    ];
+
+    const action = await select({
+      message: chalk.gray(`Page ${result.page} of ${result.totalPages} · ${result.total} items`),
+      choices,
+      pageSize: options.pageSize || 8,
+    });
+
+    if (process.stdout.isTTY) process.stdout.write("\x1b[?25l"); // hide again before re-render
+    if (options.beforeRender) await options.beforeRender();
+    if (action === "cancel") {
+      if (process.stdout.isTTY) process.stdout.write("\x1b[?25h");
+      return null;
+    }
+    if (action === "done") {
+      if (process.stdout.isTTY) process.stdout.write("\x1b[?25h");
+      return result;
+    }
+    if (action === "prev") page = Math.max(1, page - 1);
+    if (action === "next") page = Math.min(result.totalPages, page + 1);
+    result = paginate(all, pageSize, page);
+  }
+}
+
+/** Pagination footer: `Page 1 of 5 · 42 items` in a subtle style. */
+export function renderPageInfo(result) {
+  console.log(
+    chalk.dim(
+      `  Page ${chalk.cyan(result.page)} of ${chalk.cyan(result.totalPages)} ` +
+      chalk.gray(`· ${result.total} items`)
+    )
+  );
+}
+
+// ─── Prompt wrappers (consistent styling + sensible defaults) ─────────────────
+
+/**
+ * Present a list of choices and return the selected value.
+ *
+ * choices: [{ name, value, description? }] or plain strings
+ *          Use a Separator anywhere in the array.
+ */
+export async function promptSelect(message, choices, opts = {}) {
+  return select({
+    message: chalk.cyan(message),
+    choices,
+    pageSize: opts.pageSize || 10,
+    ...opts,
+  });
+}
+
+/** Single-line text input. */
+export async function promptInput(message, { defaultValue, validate, ...opts } = {}) {
+  return input({
+    message: chalk.cyan(message),
+    default: defaultValue,
+    ...(validate ? { validate } : {}),
+    ...opts,
+  });
+}
+
+/** Yes/no confirmation. */
+export async function promptConfirm(message, { default: def = true } = {}) {
+  return confirm({
+    message: chalk.cyan(message),
+    default: def,
+  });
+}
+
+/** Numeric input. */
+export async function promptNumber(message, { min, max, ...opts } = {}) {
+  return number({
+    message: chalk.cyan(message),
+    ...(min != null ? { min } : {}),
+    ...(max != null ? { max } : {}),
+    ...opts,
+  });
+}
+
+/**
+ * Multi-select (checkbox) — returns array of selected values.
+ * Pass `isCheckedAll` to offer a "toggle all" separator-less convenience.
+ */
+export async function promptCheckbox(message, choices, opts = {}) {
+  return checkbox({
+    message: chalk.cyan(message),
+    choices,
+    pageSize: opts.pageSize || 10,
+    ...opts,
+  });
+}
+
+/** Convenience: separator for checkbox/choice lists. */
+export function sep(label = "") {
+  return new Separator(label ? ` — ${label} — ` : "");
+}
+
+// ─── Tool-specific renderers ─────────────────────────────────────────────────
+
+/** Render a single tool row for `nxb list` / `nxb search`. */
+export function renderToolCard(tool, { compact = false } = {}) {
+  const icon = tool.icon || "🔧";
+  const name = chalk.bold.cyan(tool.name || tool.slug);
+  const slug = chalk.dim(tool.slug);
+  const badge = typeBadge(tool);
+  const desc = chalk.dim(tool.short_description || tool.description || "");
+
+  if (compact) {
+    console.log(
+      `  ${icon} ${chalk.cyan(tool.slug.padEnd(28))} ${desc.slice(0, 55)}${badge ? " " + badge : ""}`
+    );
+    return;
+  }
+
+  console.log(`  ${icon}  ${name}  ${badge}`);
+  console.log(`     ${slug}`);
+  if (desc) console.log(`     ${desc}`);
+  const tags = tool.tags && tool.tags.length ? chalk.gray(tool.tags.map((t) => `#${t}`).join(" ")) : "";
+  if (tags) console.log(`     ${tags}`);
+  console.log();
+}