quoxcli 0.0.0-stage → 0.3.1

package/lib/tui/components/DataTable.jsx

@@ -0,0 +1,270 @@
+/**
+ * DataTable — Paginated, selectable data table for list views
+ *
+ * Designed for the left panel of dual-panel layouts.
+ * Supports vim-style navigation, pagination, and keyboard selection.
+ *
+ * Props:
+ *   columns          - array of { key, label, width? } — a column with no
+ *                       `width` (or explicit `flex: true`) absorbs a share
+ *                       of the remaining terminal width alongside other
+ *                       flex columns. Columns with a numeric `width` are
+ *                       fixed and unaffected by flex distribution.
+ *   rows             - array of data objects
+ *   selected         - controlled selected row index
+ *   onSelect         - callback on Enter (receives row object)
+ *   onSelectionChange- callback on cursor move (receives index)
+ *   pageSize         - rows per page (default: derived from terminal rows)
+ *   loading          - show spinner overlay
+ *   emptyMessage     - text when rows is empty
+ *   active           - accept keyboard input (default: true)
+ */
+
+import React, { useState, useMemo, useEffect } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { Spinner } from '@inkjs/ui';
+import { matchKey } from '../keys.js';
+import { colors } from '../theme.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+
+// Minimum rows per page when deriving from a short terminal.
+const MIN_PAGE_SIZE = 5;
+// Rows reserved for header/footer/borders/etc. when deriving page size.
+const CHROME_ROWS = 8;
+// Width reserved for the selection marker ("▶ " / "  ") before columns start.
+const MARKER_WIDTH = 2;
+// Floor width for a flex column so it never collapses to unreadable size.
+const MIN_FLEX_WIDTH = 6;
+
+export function DataTable({
+  columns,
+  rows = [],
+  selected: controlledSelected,
+  onSelect,
+  onSelectionChange,
+  pageSize: pageSizeProp,
+  loading = false,
+  emptyMessage = 'No items',
+  active = true,
+}) {
+  // ── Responsive page size (only when caller doesn't pass one) ────────
+  const { rows: termRows, columns: termColumns } = useTerminalSize();
+  const pageSize = pageSizeProp != null
+    ? pageSizeProp
+    : Math.max(MIN_PAGE_SIZE, termRows - CHROME_ROWS);
+
+  // ── Internal cursor state ───────────────────────────────────────────
+  const [internalSelected, setInternalSelected] = useState(0);
+
+  // Use controlled selection if provided, otherwise internal
+  const isControlled = controlledSelected !== undefined;
+  const selected = isControlled ? controlledSelected : internalSelected;
+
+  const setSelected = (valOrFn) => {
+    const nextVal = typeof valOrFn === 'function' ? valOrFn(selected) : valOrFn;
+    if (!isControlled) {
+      setInternalSelected(nextVal);
+    }
+    if (onSelectionChange) {
+      onSelectionChange(nextVal);
+    }
+  };
+
+  // ── Pagination ──────────────────────────────────────────────────────
+  const totalPages = Math.max(1, Math.ceil(rows.length / pageSize));
+
+  const currentPage = useMemo(() => {
+    return Math.floor(selected / pageSize);
+  }, [selected, pageSize]);
+
+  const pageRows = useMemo(() => {
+    const start = currentPage * pageSize;
+    return rows.slice(start, start + pageSize);
+  }, [rows, currentPage, pageSize]);
+
+  const pageOffset = currentPage * pageSize;
+
+  // ── Reset selection when rows change ────────────────────────────────
+  useEffect(() => {
+    if (rows.length > 0 && selected >= rows.length) {
+      setSelected(Math.max(0, rows.length - 1));
+    }
+  }, [rows.length]);
+
+  // ── Keyboard handling ───────────────────────────────────────────────
+  useInput((input, key) => {
+    if (!active || rows.length === 0) return;
+
+    // Cursor movement: j/down, k/up
+    if (matchKey('down', input, key)) {
+      setSelected((s) => (s < rows.length - 1 ? s + 1 : 0));
+      return;
+    }
+    if (matchKey('up', input, key)) {
+      setSelected((s) => (s > 0 ? s - 1 : rows.length - 1));
+      return;
+    }
+
+    // Page navigation: n = next page, p = prev page
+    if (matchKey('nextPage', input, key)) {
+      const nextPageStart = Math.min((currentPage + 1) * pageSize, rows.length - 1);
+      if (currentPage < totalPages - 1) {
+        setSelected(nextPageStart);
+      }
+      return;
+    }
+    if (matchKey('prevPage', input, key)) {
+      const prevPageStart = Math.max((currentPage - 1) * pageSize, 0);
+      if (currentPage > 0) {
+        setSelected(prevPageStart);
+      }
+      return;
+    }
+
+    // Select with Enter
+    if (matchKey('select', input, key)) {
+      if (onSelect && rows[selected]) {
+        onSelect(rows[selected]);
+      }
+      return;
+    }
+  });
+
+  // ── Column widths ───────────────────────────────────────────────────
+  // A column with an explicit numeric `width` is fixed (unchanged from
+  // legacy behavior). A column with `flex: true` or no `width` at all is a
+  // flex column: it absorbs an equal share of whatever terminal width is
+  // left over after fixed columns and the selection marker are accounted
+  // for, so long values (titles, URLs) expand on wide terminals instead of
+  // always being clipped at the old hard-coded 40-char cap.
+  const colWidths = useMemo(() => {
+    if (columns.length === 0) return [];
+
+    const isFlex = (col) => col.flex === true || col.width == null;
+
+    // Content-based width (legacy auto-calc): used as the fallback when no
+    // usable terminal width is available.
+    const contentWidth = (col) => {
+      const headerLen = col.label.length;
+      const maxDataLen = rows.reduce((max, row) => {
+        const val = String(row[col.key] ?? '');
+        return Math.max(max, val.length);
+      }, 0);
+      return Math.min(Math.max(headerLen, maxDataLen) + 2, 40);
+    };
+
+    const flexIndices = columns
+      .map((col, i) => (isFlex(col) ? i : -1))
+      .filter((i) => i !== -1);
+
+    // No flex columns — every width is explicit, behavior is unchanged.
+    if (flexIndices.length === 0) {
+      return columns.map((col) => col.width);
+    }
+
+    const fixedTotal = columns.reduce(
+      (sum, col) => sum + (isFlex(col) ? 0 : col.width),
+      0
+    );
+
+    // No terminal width info at all — fall back to legacy content-based sizing.
+    if (!termColumns) {
+      return columns.map((col) => (isFlex(col) ? contentWidth(col) : col.width));
+    }
+
+    const available = termColumns - MARKER_WIDTH - fixedTotal;
+    const perFlex = Math.floor(available / flexIndices.length);
+    const flexWidth = Math.max(MIN_FLEX_WIDTH, perFlex);
+
+    return columns.map((col) => (isFlex(col) ? flexWidth : col.width));
+  }, [columns, rows, termColumns]);
+
+  // ── Render: Loading state ───────────────────────────────────────────
+  if (loading) {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Spinner label="Loading..." />
+      </Box>
+    );
+  }
+
+  // ── Render: Empty state ─────────────────────────────────────────────
+  if (rows.length === 0) {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Text color={colors.dim}>{emptyMessage}</Text>
+      </Box>
+    );
+  }
+
+  // ── Render: Table ───────────────────────────────────────────────────
+  return (
+    <Box flexDirection="column">
+      {/* Column headers */}
+      <Box>
+        <Text color={colors.dim}>  </Text>
+        {columns.map((col, ci) => (
+          <Box key={col.key} width={colWidths[ci]}>
+            <Text bold dimColor>
+              {col.label}
+            </Text>
+          </Box>
+        ))}
+      </Box>
+
+      {/* Header separator */}
+      <Box>
+        <Text color={colors.subtle}>
+          {'  '}{columns.map((_, ci) => '\u2500'.repeat(Math.max(1, colWidths[ci] - 1))).join(' ')}
+        </Text>
+      </Box>
+
+      {/* Data rows */}
+      {pageRows.map((row, ri) => {
+        const absoluteIndex = pageOffset + ri;
+        const isSelected = absoluteIndex === selected;
+        return (
+          <Box key={absoluteIndex}>
+            {/* Selection marker */}
+            <Text color={isSelected ? colors.cyberBlue : colors.subtle}>
+              {isSelected ? '\u25B6 ' : '  '}
+            </Text>
+
+            {/* Cell values */}
+            {columns.map((col, ci) => {
+              const rawVal = row[col.key];
+              const val = rawVal === null || rawVal === undefined ? '' : String(rawVal);
+              return (
+                <Box key={col.key} width={colWidths[ci]}>
+                  <Text
+                    color={isSelected ? colors.text : colors.textMuted}
+                    bold={isSelected}
+                  >
+                    {val.length > colWidths[ci] - 1
+                      ? val.slice(0, colWidths[ci] - 2) + '\u2026'
+                      : val}
+                  </Text>
+                </Box>
+              );
+            })}
+          </Box>
+        );
+      })}
+
+      {/* Page indicator */}
+      {totalPages > 1 && (
+        <Box marginTop={1}>
+          <Text color={colors.dim}>
+            Page {currentPage + 1} of {totalPages}
+            {'  '}({rows.length} items)
+            {'  '}
+          </Text>
+          <Text color={colors.cyberBlue}>n</Text>
+          <Text color={colors.dim}>/</Text>
+          <Text color={colors.cyberBlue}>p</Text>
+          <Text color={colors.dim}> next/prev</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}

package/lib/tui/components/DetailPanel.jsx

@@ -0,0 +1,241 @@
+/**
+ * DetailPanel — Scrollable key-value display for the right panel
+ *
+ * Shows properties of a selected item as labeled key-value pairs.
+ * Handles nested objects (JSON.stringify) and arrays (join with ', ').
+ *
+ * When content exceeds the available vertical space (derived from
+ * useTerminalSize().rows, or the `maxHeight` prop), the panel renders a
+ * windowed slice of its content lines instead of silently overflowing, and
+ * shows a scroll indicator (`▲ N more` / `▼ N more`) for whatever is
+ * hidden off-screen.
+ *
+ * Props:
+ *   data      - object to display (keys become labels, values become text)
+ *   title     - optional heading string
+ *   loading   - show spinner when true
+ *   focused   - when true, the panel handles Up/Down/k/j/PgUp/PgDn itself
+ *               to move the scroll offset (default: false — content is
+ *               top-anchored, clamped, with an overflow hint if needed)
+ *   maxHeight - override the auto-derived (terminal-size-based) viewport
+ *               height used for windowing
+ */
+
+import React, { useState, useEffect, useMemo } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { Spinner } from '@inkjs/ui';
+import { matchKey } from '../keys.js';
+import { colors } from '../theme.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+
+// Rows reserved for title/borders/scroll-indicator when deriving viewport height.
+const CHROME_ROWS = 6;
+// Minimum viewport height when deriving from a short terminal.
+const MIN_HEIGHT = 5;
+
+/**
+ * Format a key string into a readable label.
+ * Converts camelCase and snake_case to Title Case.
+ */
+function formatLabel(key) {
+  return key
+    .replace(/_/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/**
+ * Format a value for display.
+ * - null/undefined => dim dash
+ * - arrays => comma-separated
+ * - objects => JSON string
+ * - booleans => Yes/No with color
+ * - everything else => string
+ */
+function formatValue(value) {
+  if (value === null || value === undefined) {
+    return { text: '—', color: colors.dim };
+  }
+
+  if (typeof value === 'boolean') {
+    return {
+      text: value ? 'Yes' : 'No',
+      color: value ? colors.success : colors.dim,
+    };
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return { text: '(empty)', color: colors.dim };
+    return { text: value.join(', '), color: colors.text };
+  }
+
+  if (typeof value === 'object') {
+    try {
+      return { text: JSON.stringify(value, null, 2), color: colors.textMuted };
+    } catch {
+      return { text: String(value), color: colors.textMuted };
+    }
+  }
+
+  return { text: String(value), color: colors.text };
+}
+
+/**
+ * Flatten data entries into a linear list of renderable "lines" so the
+ * panel can window/scroll through them regardless of whether an entry is a
+ * single inline row or a multi-line JSON block.
+ */
+function buildLines(entries) {
+  const lines = [];
+
+  for (const [key, value] of entries) {
+    const { text, color } = formatValue(value);
+    const label = formatLabel(key);
+    const isBlock = typeof value === 'object' && value !== null && !Array.isArray(value);
+
+    if (isBlock) {
+      lines.push({ id: `${key}:label`, kind: 'label', label: `${label}:` });
+      text.split('\n').forEach((jsonLine, i) => {
+        lines.push({ id: `${key}:${i}`, kind: 'block', text: jsonLine, color });
+      });
+    } else {
+      lines.push({ id: key, kind: 'inline', label: `${label}: `, text, color });
+    }
+  }
+
+  return lines;
+}
+
+export function DetailPanel({ data, title, loading = false, focused = false, maxHeight }) {
+  const { rows: termRows } = useTerminalSize();
+  const viewportHeight = maxHeight != null
+    ? maxHeight
+    : Math.max(MIN_HEIGHT, termRows - CHROME_ROWS);
+
+  const entries = useMemo(() => (data ? Object.entries(data) : []), [data]);
+  const lines = useMemo(() => buildLines(entries), [entries]);
+
+  const total = lines.length;
+  const needsScroll = total > viewportHeight;
+  const maxOffset = needsScroll ? total - viewportHeight : 0;
+
+  const [offset, setOffset] = useState(0);
+
+  // Reset scroll position whenever the underlying data changes.
+  useEffect(() => {
+    setOffset(0);
+  }, [data]);
+
+  // Clamp if the viewport grew (e.g. terminal resize) past the current offset.
+  useEffect(() => {
+    setOffset((o) => Math.min(o, maxOffset));
+  }, [maxOffset]);
+
+  useInput((input, key) => {
+    if (!focused || !needsScroll) return;
+
+    if (matchKey('down', input, key)) {
+      setOffset((o) => Math.min(maxOffset, o + 1));
+      return;
+    }
+    if (matchKey('up', input, key)) {
+      setOffset((o) => Math.max(0, o - 1));
+      return;
+    }
+    if (key.pageDown) {
+      setOffset((o) => Math.min(maxOffset, o + viewportHeight));
+      return;
+    }
+    if (key.pageUp) {
+      setOffset((o) => Math.max(0, o - viewportHeight));
+      return;
+    }
+  });
+
+  // ── Loading state ───────────────────────────────────────────────────
+  if (loading) {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Spinner label="Loading details..." />
+      </Box>
+    );
+  }
+
+  // ── Empty state ─────────────────────────────────────────────────────
+  if (!data) {
+    return (
+      <Box flexDirection="column" paddingY={1}>
+        <Text color={colors.dim}>No item selected</Text>
+      </Box>
+    );
+  }
+
+  const visibleLines = needsScroll ? lines.slice(offset, offset + viewportHeight) : lines;
+  // Gate on needsScroll, not just offset>0: `offset` state can be briefly
+  // stale for one render after `data` changes (before the reset effect
+  // runs), and without this guard that stale offset would flash a false
+  // "more above" hint even though the new content fits without scrolling.
+  const hiddenAbove = needsScroll ? offset : 0;
+  const hiddenBelow = needsScroll ? total - (offset + visibleLines.length) : 0;
+
+  // ── Render ──────────────────────────────────────────────────────────
+  return (
+    <Box flexDirection="column">
+      {/* Title */}
+      {title && (
+        <Box marginBottom={1}>
+          <Text color={colors.accent} bold>
+            {title}
+          </Text>
+        </Box>
+      )}
+
+      {/* Scroll-up indicator */}
+      {hiddenAbove > 0 && (
+        <Box>
+          <Text color={colors.dim}>{'▲'} {hiddenAbove} more</Text>
+        </Box>
+      )}
+
+      {/* Windowed key-value lines */}
+      {visibleLines.map((line, _i) => {
+        if (line.kind === 'label') {
+          return (
+            <Box key={`${line.id}-${_i}`}>
+              <Text color={colors.textMuted} bold>
+                {line.label}
+              </Text>
+            </Box>
+          );
+        }
+        if (line.kind === 'block') {
+          return (
+            <Box key={`${line.id}-${_i}`} marginLeft={2}>
+              <Text color={line.color}>{line.text}</Text>
+            </Box>
+          );
+        }
+        return (
+          <Box key={`${line.id}-${_i}`}>
+            <Text color={colors.textMuted} bold>
+              {line.label}
+            </Text>
+            <Text color={line.color}>{line.text}</Text>
+          </Box>
+        );
+      })}
+
+      {/* Scroll-down indicator */}
+      {hiddenBelow > 0 && (
+        <Box>
+          <Text color={colors.dim}>{'▼'} {hiddenBelow} more</Text>
+        </Box>
+      )}
+
+      {/* Empty data object */}
+      {entries.length === 0 && (
+        <Text color={colors.dim}>No properties to display</Text>
+      )}
+    </Box>
+  );
+}

package/lib/tui/components/HelpOverlay.jsx

@@ -0,0 +1,67 @@
+/**
+ * HelpOverlay — Keybinding reference overlay
+ *
+ * Renders on top of the current view when `?` is pressed.
+ * Shows all keybindings organized in a clean layout.
+ * Press `?` or `Esc` to dismiss.
+ *
+ * Props:
+ *   visible  - whether the overlay is shown
+ *   onClose  - called when user dismisses (? or Esc)
+ */
+
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+import { KEY_HELP } from '../keys.js';
+import { colors } from '../theme.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+
+// Preferred overlay width; clamped down on narrow terminals.
+const PREFERRED_WIDTH = 44;
+const MIN_WIDTH = 20;
+
+export function HelpOverlay({ visible = false, onClose }) {
+  const { columns } = useTerminalSize();
+
+  useInput((input, key) => {
+    if (!visible) return;
+    if (input === '?' || key.escape) {
+      onClose?.();
+    }
+  }, { isActive: visible });
+
+  if (!visible) return null;
+
+  const width = Math.max(MIN_WIDTH, Math.min(PREFERRED_WIDTH, columns - 4));
+
+  return (
+    <Box
+      flexDirection="column"
+      borderStyle="round"
+      borderColor={colors.primary}
+      paddingX={2}
+      paddingY={1}
+      width={width}
+    >
+      {/* Header */}
+      <Box justifyContent="center" marginBottom={1}>
+        <Text color={colors.primary} bold>Keyboard Shortcuts</Text>
+      </Box>
+
+      {/* Key entries */}
+      {KEY_HELP.map((entry, i) => (
+        <Box key={i} marginBottom={0}>
+          <Box width={14}>
+            <Text color={colors.cyberBlue} bold>{entry.keys}</Text>
+          </Box>
+          <Text color={colors.textMuted}>{entry.desc}</Text>
+        </Box>
+      ))}
+
+      {/* Dismiss hint */}
+      <Box marginTop={1} justifyContent="center">
+        <Text color={colors.dim}>Press ? or Esc to close</Text>
+      </Box>
+    </Box>
+  );
+}