free-coding-models 0.5.4 → 0.5.6

package/web/src/components/help/HelpView.jsx

@@ -0,0 +1,188 @@
+/**
+ * @file web/src/components/help/HelpView.jsx
+ * @description Help modal — M2 parity with the TUI's `K` / `I` help overlay.
+ * 📖 Renders the same content the TUI help overlay does, as JSX, with a live
+ * 📖 search bar at the top. The TUI source-of-truth is `src/tui/cli-help.js`
+ * 📖 (CLI flags) and `src/tui/overlays.js` `renderHelp` (key bindings) — we
+ * 📖 re-render those lists statically here to avoid a TUI-engine import that
+ * 📖 would pull chalk into the Web bundle.
+ *
+ * 📖 The header's overflow menu and the ⌘K palette expose "Help" as a page;
+ * 📖 this component is rendered as a full-screen modal inside the Web.
+ *
+ * @functions
+ *   → HelpView → main modal component
+ */
+import { useState, useMemo } from 'react'
+import { IconSearch, IconX } from '@tabler/icons-react'
+import styles from './HelpView.module.css'
+
+const SECTIONS = [
+  {
+    id: 'navigation',
+    title: '🧭 Navigation',
+    items: [
+      { key: '↑ / ↓', desc: 'Navigate rows in the main table (planned — currently mouse-only)' },
+      { key: 'Enter', desc: 'Open the detail panel for the focused row' },
+      { key: 'Esc', desc: 'Close any open modal or detail panel' },
+    ],
+  },
+  {
+    id: 'filters',
+    title: '🔍 Filters',
+    items: [
+      { key: 'Tier chip', desc: 'Click to cycle: All → S+ → S → A+ → A → A- → B+ → B → C → All' },
+      { key: 'Status chip', desc: 'Click to cycle: All → Up → Down → Pending' },
+      { key: 'Verdict chip', desc: 'Click to cycle: All → Perfect → Normal → Spiky → Slow → Overloaded → Down → Unstable → Pending' },
+      { key: 'Health chip', desc: 'Click to cycle: All → Up → Timeout → Down → Pending → No key → Auth err' },
+      { key: 'Visibility', desc: 'Normal (all) / Configured only (hide no-key) / Usable only (UP + good verdict)' },
+      { key: 'Provider dropdown', desc: 'Filter by provider' },
+      { key: 'Custom text filter', desc: 'Apply via ⌘K palette or `Apply text filter` — clear with the X chip' },
+      { key: 'Reset button', desc: 'Clears every active filter + sort back to defaults' },
+    ],
+  },
+  {
+    id: 'sort',
+    title: '📶 Sort',
+    items: [
+      { key: 'Click any column header', desc: 'Sort asc → desc → reset (no sort, default order)' },
+      { key: 'Resizable columns', desc: 'Drag the right edge of any header to resize. Double-click resets one column.' },
+    ],
+  },
+  {
+    id: 'favorites',
+    title: '⭐ Favorites',
+    items: [
+      { key: 'Star button (per row)', desc: 'Click to favorite / unfavorite the model (TUI: F key)' },
+      { key: 'Detail panel', desc: 'Favorite + Up/Down reorder + current priority rank (TUI: Shift+↑/↓)' },
+      { key: 'Pinned mode', desc: 'In the Settings view, toggle "Pinned + always visible" (TUI: Y key)' },
+      { key: 'Shared with TUI', desc: 'Favorites are persisted in the same ~/.free-coding-models.json the TUI uses' },
+    ],
+  },
+  {
+    id: 'benchmark',
+    title: '🤖 AI Speed Test (benchmark)',
+    items: [
+      { key: 'Header button', desc: 'Run a global AI Speed Test on every visible model' },
+      { key: 'AI Lat. cell', desc: 'Click any AI Lat. cell to benchmark just that model (TUI: Ctrl+A)' },
+      { key: 'Detail panel', desc: 'Dedicated "AI Speed Test" button (TUI: Ctrl+A)' },
+      { key: 'TPS column', desc: 'Tokens per second for the model — appears after a benchmark run' },
+      { key: 'Latency column', desc: 'Real completion latency (not just ping) for the model' },
+    ],
+  },
+  {
+    id: 'tools',
+    title: '🧰 Tool mode (M3)',
+    items: [
+      { key: 'Coming in M3', desc: 'Tool mode picker, per-row Launch button, missing-tool install prompt, incompatible-fallback modal' },
+    ],
+  },
+  {
+    id: 'palette',
+    title: '⚡ Command palette',
+    items: [
+      { key: '⌘K / Ctrl+P', desc: 'The Web\'s only global keyboard shortcut — toggles the command palette' },
+      { key: 'Type to search', desc: 'Fuzzy match across all filters, sorts, tools, pages, and theme / ping / reset actions' },
+      { key: '↑ / ↓ + Enter', desc: 'Navigate the results and execute the highlighted command' },
+      { key: 'Esc', desc: 'Close the palette without running anything' },
+    ],
+  },
+  {
+    id: 'theme',
+    title: '🌗 Theme',
+    items: [
+      { key: 'Theme button (header)', desc: 'Click to cycle: auto → dark → light (TUI: G key)' },
+      { key: 'Auto mode', desc: 'Follows the OS prefers-color-scheme preference and updates live' },
+    ],
+  },
+  {
+    id: 'ping',
+    title: '⚡ Ping mode',
+    items: [
+      { key: 'Speed / Normal / Slow / Forced', desc: 'Ping cadence (2s / 10s / 30s / 4s) — TUI: W key' },
+      { key: 'next ping in Xs', desc: 'Live countdown shown in the FilterBar (TUI footer style)' },
+    ],
+  },
+  {
+    id: 'url',
+    title: '🔗 URL deep-linking',
+    items: [
+      { key: '?tier=S+&sort=verdict&origin=groq&view=dashboard', desc: 'Every filter / sort / view is reflected in the URL — share pre-filtered links' },
+    ],
+  },
+  {
+    id: 'cli',
+    title: '⌨️ CLI parity',
+    items: [
+      { key: 'Same storage', desc: 'The Web reads + writes the same ~/.free-coding-models.json as the TUI' },
+      { key: 'Same engine', desc: 'All model parsing, ping, and benchmark code is shared with the TUI' },
+    ],
+  },
+]
+
+export default function HelpView({ onClose }) {
+  const [query, setQuery] = useState('')
+
+  // 📖 Filter every section's items by the live query. Case-insensitive
+  // 📖 substring match on the key or description. Empty results hide the
+  // 📖 section entirely.
+  const filteredSections = useMemo(() => {
+    const q = query.trim().toLowerCase()
+    if (!q) return SECTIONS
+    return SECTIONS.map((section) => ({
+      ...section,
+      items: section.items.filter(
+        (item) => item.key.toLowerCase().includes(q) || item.desc.toLowerCase().includes(q),
+      ),
+    })).filter((section) => section.items.length > 0)
+  }, [query])
+
+  return (
+    <div className={styles.backdrop} onClick={onClose}>
+      <div className={styles.modal} onClick={(e) => e.stopPropagation()}>
+        <div className={styles.header}>
+          <div className={styles.titleRow}>
+            <h2 className={styles.title}>❓ Help & Keyboard Shortcuts</h2>
+            <button className={styles.closeBtn} onClick={onClose} aria-label="Close help">
+              <IconX size={18} stroke={1.5} />
+            </button>
+          </div>
+          <div className={styles.searchBar}>
+            <IconSearch size={14} stroke={1.5} className={styles.searchIcon} />
+            <input
+              className={styles.searchInput}
+              placeholder="Search help (filters, hotkeys, TUI parity)…"
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              autoFocus
+            />
+          </div>
+          <p className={styles.note}>
+            The Web Dashboard is mouse-first. The only global keyboard shortcut is{' '}
+            <kbd>⌘K</kbd> / <kbd>Ctrl+P</kbd> for the command palette — everything else
+            lives here, in the header menu, or in modals.
+          </p>
+        </div>
+        <div className={styles.body}>
+          {filteredSections.length === 0 ? (
+            <div className={styles.empty}>No help matches "{query}".</div>
+          ) : (
+            filteredSections.map((section) => (
+              <section key={section.id} className={styles.section}>
+                <h3 className={styles.sectionTitle}>{section.title}</h3>
+                <ul className={styles.itemList}>
+                  {section.items.map((item) => (
+                    <li key={item.key + item.desc} className={styles.item}>
+                      <span className={styles.itemKey}>{item.key}</span>
+                      <span className={styles.itemDesc}>{item.desc}</span>
+                    </li>
+                  ))}
+                </ul>
+              </section>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

package/web/src/components/help/HelpView.module.css

@@ -0,0 +1,157 @@
+/**
+ * @file web/src/components/help/HelpView.module.css
+ * @description Full-screen help modal styles — TUI parity.
+ */
+
+.backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.55);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+  z-index: 500;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 5vh 4vw;
+}
+
+.modal {
+  width: min(820px, 95vw);
+  max-height: 90vh;
+  background: var(--color-bg-elevated);
+  border: 1px solid var(--color-border-hover);
+  border-radius: 14px;
+  box-shadow: 0 24px 64px rgba(0, 0, 0, 0.5);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.header {
+  padding: 20px 24px 16px;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.titleRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.title {
+  font-size: 17px;
+  font-weight: 700;
+  margin: 0;
+  color: var(--color-text);
+}
+
+.closeBtn {
+  background: transparent;
+  border: none;
+  color: var(--color-text-muted);
+  cursor: pointer;
+  padding: 4px;
+  border-radius: 4px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+.closeBtn:hover { color: var(--color-text); background: var(--color-bg-hover); }
+
+.searchBar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-top: 12px;
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 8px;
+  padding: 0 12px;
+  height: 34px;
+}
+.searchBar:focus-within {
+  border-color: var(--color-accent);
+  box-shadow: 0 0 0 3px var(--color-accent-glow);
+}
+.searchIcon { color: var(--color-text-dim); }
+.searchInput {
+  flex: 1;
+  background: none;
+  border: none;
+  outline: none;
+  color: var(--color-text);
+  font-size: 13px;
+  font-family: var(--font-sans);
+}
+.searchInput::placeholder { color: var(--color-text-dim); }
+
+.note {
+  margin: 10px 0 0;
+  font-size: 11px;
+  color: var(--color-text-muted);
+  line-height: 1.5;
+}
+.note kbd {
+  display: inline-block;
+  font-family: var(--font-mono);
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-size: 10px;
+}
+
+.body {
+  padding: 18px 24px 24px;
+  overflow-y: auto;
+  flex: 1;
+}
+
+.section { margin-bottom: 18px; }
+.sectionTitle {
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.6px;
+  color: var(--color-text-muted);
+  margin: 0 0 8px;
+}
+
+.itemList {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+.item {
+  display: grid;
+  grid-template-columns: minmax(160px, 0.4fr) 1fr;
+  gap: 12px;
+  align-items: baseline;
+  padding: 6px 10px;
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  font-size: 12px;
+}
+.itemKey {
+  font-weight: 600;
+  color: var(--color-text);
+  font-family: var(--font-mono);
+  font-size: 11px;
+}
+.itemDesc {
+  color: var(--color-text-muted);
+  line-height: 1.5;
+}
+
+.empty {
+  text-align: center;
+  padding: 40px 20px;
+  color: var(--color-text-dim);
+  font-size: 13px;
+}

package/web/src/components/layout/Header.jsx

@@ -28,10 +28,11 @@ const NAV_ITEMS = [
   { id: 'router',      label: 'Router',      icon: IconRoute,      comingIn: 'M4' },
 ]
 
-// 📖 Overflow menu items — Help, Changelog, Install Endpoints, Installed Models.
+// 📖 Overflow menu items — Help + Changelog shipped in M2; Install Endpoints
+// 📖 and Installed Models are still M4.
 const MENU_ITEMS = [
-  { id: 'help',              label: 'Help',               icon: IconQuestionMark, comingIn: 'M2' },
-  { id: 'changelog',         label: 'Changelog',          icon: IconHistory,      comingIn: 'M2' },
+  { id: 'help',              label: 'Help',               icon: IconQuestionMark },
+  { id: 'changelog',         label: 'Changelog',          icon: IconHistory },
   { id: 'install-endpoints', label: 'Install Endpoints',  icon: IconPlug,         comingIn: 'M4' },
   { id: 'installed-models',  label: 'Installed Models',   icon: IconFolders,      comingIn: 'M4' },
 ]
@@ -42,6 +43,7 @@ export default function Header({
   onToggleTheme, onOpenExport, onOpenCommandPalette,
   onBenchmark, benchmarkRunning, benchmarkTotal, benchmarkCompleted,
   modelsCount, theme, onToast,
+  updateSlot = null,
 }) {
   const [menuOpen, setMenuOpen] = useState(false)
   const menuRef = useRef(null)
@@ -188,6 +190,9 @@ export default function Header({
           )}
         </button>
 
+        {/* 📖 M2: update chip slot. Hidden when no update is available. */}
+        {updateSlot}
+
         <button className={styles.iconBtn} onClick={onToggleTheme} title={`Theme: ${theme} (click to cycle auto / dark / light)`}>
           {theme === 'light' ? <IconMoon size={16} stroke={1.5} /> : <IconSun size={16} stroke={1.5} />}
         </button>