free-coding-models 0.5.12 → 0.5.15

package/web/src/components/dashboard/ProviderDropdown.jsx

@@ -0,0 +1,156 @@
+/**
+ * @file web/src/components/dashboard/ProviderDropdown.jsx
+ * @description Custom dropdown for provider filtering with inline SVG logos + health indicator.
+ *
+ * @details
+ *   - Replaces the native `<select>` for providers with a custom dropdown that
+ *     renders each provider as [SVG icon + wordmark + health dot + model count].
+ *   - Uses the same `ProviderLogo` component as the model table so branding is
+ *     visually consistent across the dashboard.
+ *   - The health indicator dot shows:
+ *     🟢 Green (glow) — provider has at least one model with status 'up' (key works).
+ *     🟡 Yellow — provider has keys configured but no models are 'up' yet (pending).
+ *     🔴 Red — provider has keys but models are down / auth errors.
+ *     ⚪ Gray — provider has no API key configured at all.
+ *   - Theme-aware: colors adapt for both dark and light modes via CSS variables.
+ *   - Click-outside + Escape to close, keyboard-friendly, scrollable for long lists.
+ *
+ * @param {object} props
+ * @param {Array}   props.providers     — Array of { key, name, count, hasKey, anyUp }
+ * @param {string}  props.value         — Currently selected provider key ('all' for no filter).
+ * @param {function} props.onChange      — Callback with new provider key.
+ *
+ * @functions
+ *   → ProviderDropdown (default export)
+ *
+ * @see  web/src/components/dashboard/FilterBar.jsx (consumer)
+ * @see  web/src/components/atoms/ProviderLogo.jsx (logo renderer)
+ */
+import { useState, useEffect, useRef, useCallback } from 'react'
+import { IconChevronDown } from '@tabler/icons-react'
+import ProviderLogo from '../atoms/ProviderLogo.jsx'
+import styles from './ProviderDropdown.module.css'
+
+/**
+ * 📖 Derives the health indicator state from aggregated provider data.
+ * Returns one of: 'active' | 'pending' | 'down' | 'nokey'.
+ */
+function providerHealthState(provider) {
+  if (!provider.hasKey) return 'nokey'
+  if (provider.anyUp) return 'active'
+  return 'down'
+}
+
+function HealthIndicator({ state }) {
+  const cls = styles[`dot_${state}`] || styles.dot_nokey
+  const titles = {
+    active: 'API key works — at least one model is UP',
+    pending: 'API key set — waiting for health data',
+    down: 'API key set — models are DOWN or have auth errors',
+    nokey: 'No API key configured',
+  }
+  return <span className={`${styles.healthDot} ${cls}`} title={titles[state] || ''} />
+}
+
+export default function ProviderDropdown({ providers, value, onChange }) {
+  const [open, setOpen] = useState(false)
+  const ref = useRef(null)
+  const listRef = useRef(null)
+
+  const close = useCallback(() => setOpen(false), [])
+
+  // 📖 Close on outside click or Escape.
+  useEffect(() => {
+    if (!open) return
+    const handleClickOutside = (e) => {
+      if (ref.current && !ref.current.contains(e.target)) close()
+    }
+    const handleKey = (e) => { if (e.key === 'Escape') close() }
+    document.addEventListener('mousedown', handleClickOutside)
+    document.addEventListener('keydown', handleKey)
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside)
+      document.removeEventListener('keydown', handleKey)
+    }
+  }, [open, close])
+
+  // 📖 Scroll selected item into view when dropdown opens.
+  useEffect(() => {
+    if (!open || !listRef.current) return
+    const selected = listRef.current.querySelector(`[data-active="true"]`)
+    if (selected) selected.scrollIntoView({ block: 'nearest' })
+  }, [open])
+
+  const selectedProvider = providers.find(p => p.key === value)
+  const isFiltered = value !== 'all'
+
+  return (
+    <div className={styles.dropdown} ref={ref}>
+      <button
+        className={`${styles.trigger} ${isFiltered ? styles.triggerActive : ''} ${open ? styles.triggerOpen : ''}`}
+        onClick={() => setOpen(!open)}
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        title={isFiltered ? `Provider: ${selectedProvider?.name || value}` : 'All providers'}
+      >
+        <span className={styles.triggerContent}>
+          {isFiltered && selectedProvider ? (
+            <>
+              <span className={styles.triggerLogo}>
+                <ProviderLogo providerKey={selectedProvider.key} origin={selectedProvider.name} />
+              </span>
+              <span className={styles.triggerCount}>{selectedProvider.count}</span>
+            </>
+          ) : (
+            <span className={styles.triggerLabel}>All Providers</span>
+          )}
+        </span>
+        <IconChevronDown
+          size={12}
+          stroke={2}
+          className={`${styles.chevron} ${open ? styles.chevronOpen : ''}`}
+        />
+      </button>
+
+      {open && (
+        <div className={styles.menu} role="listbox" ref={listRef}>
+          {/* ── "All Providers" option ── */}
+          <button
+            role="option"
+            aria-selected={value === 'all'}
+            data-active={value === 'all'}
+            className={`${styles.option} ${value === 'all' ? styles.optionActive : ''}`}
+            onClick={() => { onChange('all'); close() }}
+          >
+            <span className={styles.optionLabel}>All Providers</span>
+            <span className={styles.optionCount}>{providers.reduce((s, p) => s + p.count, 0)}</span>
+          </button>
+
+          <div className={styles.separator} />
+
+          {/* ── Per-provider options ── */}
+          {providers.map((p) => {
+            const healthState = providerHealthState(p)
+            return (
+              <button
+                key={p.key}
+                role="option"
+                aria-selected={value === p.key}
+                data-active={value === p.key}
+                className={`${styles.option} ${value === p.key ? styles.optionActive : ''}`}
+                onClick={() => { onChange(p.key); close() }}
+                title={`${p.name} — ${p.count} model${p.count !== 1 ? 's' : ''}`}
+              >
+                <span className={styles.optionLogo}>
+                  <ProviderLogo providerKey={p.key} origin={p.name} />
+                </span>
+                <HealthIndicator state={healthState} />
+                <span className={styles.optionCount}>{p.count}</span>
+              </button>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

package/web/src/components/dashboard/ProviderDropdown.module.css

@@ -0,0 +1,248 @@
+/**
+ * @file web/src/components/dashboard/ProviderDropdown.module.css
+ * @description Styles for the custom provider dropdown — SVG logos + health dots.
+ *
+ * 📖 Theme-aware: uses CSS variables for all colors. Dark + light mode both
+ * 📖 fully supported. Health dot colors are defined per-theme with explicit
+ * 📖 overrides for light mode to maintain contrast.
+ */
+
+.dropdown {
+  position: relative;
+}
+
+/* ── Trigger button ── */
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 10px 4px 8px;
+  border: 1px solid var(--color-border);
+  border-radius: 5px;
+  background: var(--color-surface);
+  color: var(--color-text);
+  font-size: 11px;
+  font-family: var(--font-sans);
+  cursor: pointer;
+  transition: all 150ms;
+  min-width: 130px;
+  max-width: 240px;
+  user-select: none;
+  outline: none;
+}
+.trigger:hover {
+  background: var(--color-bg-hover);
+  border-color: var(--color-text-muted);
+}
+.trigger:focus {
+  border-color: var(--color-accent);
+}
+.triggerActive {
+  border-color: var(--color-accent);
+  color: var(--color-text);
+}
+.triggerOpen {
+  border-color: var(--color-accent);
+  border-bottom-left-radius: 0;
+  border-bottom-right-radius: 0;
+  z-index: 101;
+  background: var(--color-bg-hover);
+}
+
+.triggerContent {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.triggerLogo {
+  display: inline-flex;
+  align-items: center;
+  min-width: 0;
+  overflow: hidden;
+  /* 📖 Inherit max-height from ProviderLogo's row. */
+  --pl-max-h: 20px;
+  --pl-icon-h: 14px;
+  --pl-text-h: 10px;
+}
+/* 📖 Clamp ProviderLogo width inside trigger so long wordmarks don't overflow. */
+.triggerLogo > span {
+  max-width: 160px;
+}
+
+.triggerLabel {
+  font-size: 11px;
+  font-weight: 600;
+  color: var(--color-text-muted);
+  white-space: nowrap;
+}
+
+.triggerCount {
+  font-size: 10px;
+  font-weight: 700;
+  color: var(--color-text-muted);
+  font-family: var(--font-mono);
+  margin-left: auto;
+  flex-shrink: 0;
+}
+
+.chevron {
+  flex-shrink: 0;
+  opacity: 0.5;
+  transition: transform 200ms ease;
+}
+.chevronOpen {
+  transform: rotate(180deg);
+  opacity: 0.8;
+}
+
+/* ── Dropdown menu ── */
+.menu {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  z-index: 100;
+  min-width: 100%;
+  max-width: 300px;
+  max-height: 320px;
+  overflow-y: auto;
+  background: var(--color-surface);
+  border: 1px solid var(--color-accent);
+  border-top: none;
+  border-radius: 0 0 6px 6px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.3);
+  padding: 4px 0;
+}
+
+/* 📖 Custom scrollbar for the dropdown. */
+.menu::-webkit-scrollbar {
+  width: 5px;
+}
+.menu::-webkit-scrollbar-track {
+  background: transparent;
+}
+.menu::-webkit-scrollbar-thumb {
+  background: var(--color-border);
+  border-radius: 3px;
+}
+
+/* ── Menu options ── */
+.option {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 6px 10px;
+  border: none;
+  background: transparent;
+  color: var(--color-text-muted);
+  font-size: 11px;
+  font-family: var(--font-sans);
+  cursor: pointer;
+  transition: all 100ms;
+  text-align: left;
+  outline: none;
+}
+.option:hover {
+  background: var(--color-bg-hover);
+  color: var(--color-text);
+}
+.option:focus-visible {
+  background: var(--color-bg-hover);
+  color: var(--color-text);
+  box-shadow: inset 0 0 0 1px var(--color-accent);
+}
+
+.optionActive {
+  background: var(--color-accent-dim);
+  color: var(--color-text);
+  font-weight: 600;
+}
+.optionActive:hover {
+  background: var(--color-bg-hover);
+}
+
+.optionLabel {
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+.optionLogo {
+  display: inline-flex;
+  align-items: center;
+  min-width: 0;
+  flex: 1;
+  overflow: hidden;
+  /* 📖 Slightly larger than trigger for readability in the expanded menu. */
+  --pl-max-h: 20px;
+  --pl-icon-h: 15px;
+  --pl-text-h: 11px;
+}
+.optionLogo > span {
+  max-width: 180px;
+}
+
+.optionCount {
+  font-size: 10px;
+  font-weight: 700;
+  font-family: var(--font-mono);
+  color: var(--color-text-dim, #666);
+  flex-shrink: 0;
+  margin-left: auto;
+}
+
+/* ── Separator between "All" and per-provider options ── */
+.separator {
+  height: 1px;
+  background: var(--color-border);
+  margin: 4px 8px;
+}
+
+/* ── Health indicator dots ── */
+.healthDot {
+  display: inline-block;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  flex-shrink: 0;
+  transition: background 200ms ease, box-shadow 200ms ease;
+}
+
+/* 📖 Active: green glow — key works and models are UP. */
+.dot_active {
+  background: #00ff88;
+  box-shadow: 0 0 5px rgba(0, 255, 136, 0.5);
+}
+
+/* 📖 Pending: yellow — key set, health data not yet available. */
+.dot_pending {
+  background: #ffaa00;
+}
+
+/* 📖 Down: red — key set but models are down / auth errors. */
+.dot_down {
+  background: #ff4444;
+}
+
+/* 📖 No key: gray — no API key configured for this provider. */
+.dot_nokey {
+  background: #555570;
+}
+
+/* ── Light theme overrides — deeper colors for white background contrast ── */
+:global([data-theme="light"]) .dot_active {
+  background: #008f4d;
+  box-shadow: 0 0 4px rgba(0, 143, 77, 0.35);
+}
+:global([data-theme="light"]) .dot_pending {
+  background: #b38600;
+}
+:global([data-theme="light"]) .dot_down {
+  background: #c8143a;
+}
+:global([data-theme="light"]) .dot_nokey {
+  background: #aaa;
+}

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

@@ -118,6 +118,19 @@ const SECTIONS = [
       { key: 'Same engine', desc: 'All model parsing, ping, and benchmark code is shared with the TUI' },
     ],
   },
+  {
+    id: 'how-router-works',
+    title: '🌐 How the FCM Router works',
+    items: [
+      { key: 'Smart router', desc: 'Point any OpenAI client at http://localhost:19280/v1 with model: "fcm". The daemon picks the healthiest model in the active set and forwards the request with automatic failover.' },
+      { key: 'Pre-prompt', desc: 'A first-class system message is injected on every proxied request. The default introduces the assistant as the FCM routing agent. Edit from Settings.' },
+      { key: 'Probes', desc: 'Every 10s/30s/120s (eco/balanced/aggressive) the daemon sends a 1-token chat-completion ping to every model in the active set. The probe measures latency + status code, not just URL reachability — so a wrong API key is caught and the circuit opens.' },
+      { key: 'Circuit breaker', desc: 'Per-model state. Healthy (green) = last probe 2xx, route here. Down (red) = last 3 probes failed, skip until cooldown. Recovering (yellow) = cooldown expired, retrying. Auth error (orange) = 401/403, your key is wrong. Deprecated (gray) = removed from catalog, will be replaced by auto-heal.' },
+      { key: 'Failover order', desc: 'Models are tried in priority order. A model in Recovering/Down/Auth error is skipped — the request goes to the next healthy one. If ALL fail, you get 503 with the "models_tried" list in the error body.' },
+      { key: 'Auto-heal', desc: 'On daemon start, every Auth-error / Deprecated model in the active set is swapped for a working alternative (same provider first, then cross-provider). The first time you add/remove/reorder a model, auto-heal switches off.' },
+      { key: 'Rate limits', desc: 'Each provider has its own quota. Common free-tier limits: Groq 14 400 RPD, Mistral 1 RPS, NVIDIA ~40 RPM, OpenRouter 50 RPD. When a provider returns 429, the router fails over. When daily quota is exhausted, the model goes Auth error and auto-heal swaps it out next start.' },
+    ],
+  },
 ]
 
 export default function HelpView({ onClose }) {