@veluai/velu 0.1.16 → 0.2.0

package/runtime/velu-ui/components/ContextMenu.jsx

@@ -0,0 +1,272 @@
+import React from 'react';
+import {
+  Copy,
+  Check,
+  ChevronDown,
+  ArrowUpRight,
+  Sparkles,
+  Terminal,
+  Download,
+  Bot,
+  Wind,
+} from 'lucide-react';
+import Cluster from '../primitives/Cluster.jsx';
+import {
+  MarkdownIcon,
+  OpenAIIcon,
+  ClaudeIcon,
+  PerplexityIcon,
+  CursorIcon,
+  VscodeIcon,
+} from '../lib/brand-icons.jsx';
+
+/**
+ * ContextMenu — the per-page agent/IDE action bar shown at the top of every
+ * page: the section eyebrow on the left, and a "Copy Page" split-button with a
+ * dropdown on the right. The dropdown items are driven by the Mintlify-
+ * compatible `contextual.options` config.
+ *
+ * The primary button copies the page's Markdown (the `.md` twin). Items either
+ * copy, open the Markdown, download the spec, or open the page in an AI tool /
+ * IDE. All side effects happen in click handlers (SSR-safe — no window at
+ * render).
+ *
+ * @param {{
+ *   eyebrow?: string,                 // section/group label
+ *   pageUrl: string,                  // page path, e.g. "/quickstart"
+ *   title?: string,                   // page title (for AI prompts / filenames)
+ *   isApi?: boolean,                  // API page → enable download-spec
+ *   siteName?: string,                // for MCP deep-link labels
+ *   options?: Array<string|{title,description,href,icon}>,
+ *   onAssistant?: () => void,         // 'assistant' option → in-site Ask AI
+ * }} props
+ */
+
+// The Markdown URL for a page path (`/` → `/index.md`).
+const mdUrlForPage = (url) => (url === '/' ? '/index.md' : `${url}.md`);
+
+// key → { icon, label, desc, external?, apiOnly?, kind, url? }
+const REGISTRY = {
+  copy: { icon: Copy, label: 'Copy page', desc: 'Copy page as Markdown for LLMs', kind: 'copy' },
+  view: { icon: MarkdownIcon, label: 'View as Markdown', desc: 'Open the raw Markdown', kind: 'view', external: true },
+  'download-spec': { icon: Download, label: 'Download OpenAPI spec', desc: 'Save this endpoint as YAML', kind: 'spec', apiOnly: true },
+  assistant: { icon: Sparkles, label: 'Ask AI', desc: 'Ask the docs assistant about this page', kind: 'assistant' },
+  chatgpt: { icon: OpenAIIcon, label: 'Open in ChatGPT', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://chatgpt.com/?hints=search&q=${q}` },
+  claude: { icon: ClaudeIcon, label: 'Open in Claude', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://claude.ai/new?q=${q}` },
+  perplexity: { icon: PerplexityIcon, label: 'Open in Perplexity', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://www.perplexity.ai/search?q=${q}` },
+  grok: { icon: Bot, label: 'Open in Grok', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://grok.com/?q=${q}` },
+  aistudio: { icon: Sparkles, label: 'Open in AI Studio', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://aistudio.google.com/app/prompts/new_chat?prompt=${q}` },
+  devin: { icon: Bot, label: 'Open in Devin', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://app.devin.ai/?prompt=${q}` },
+  windsurf: { icon: Wind, label: 'Open in Windsurf', desc: 'Ask questions about this page', kind: 'ai', external: true, url: (q) => `https://windsurf.com/?q=${q}` },
+  mcp: { icon: Terminal, label: 'Copy MCP install command', desc: 'Copy npx command to install MCP server', kind: 'mcp' },
+  'add-mcp': { icon: Terminal, label: 'Add MCP server', desc: 'Copy command to add the MCP server', kind: 'mcp' },
+  cursor: { icon: CursorIcon, label: 'Connect to Cursor', desc: 'Install MCP Server on Cursor', kind: 'cursor', external: true },
+  vscode: { icon: VscodeIcon, label: 'Connect to VS Code', desc: 'Install MCP Server on VS Code', kind: 'vscode', external: true },
+  'devin-mcp': { icon: Terminal, label: 'Connect to Devin', desc: 'Install MCP Server on Devin', kind: 'cursor', external: true },
+};
+
+export default function ContextMenu({
+  eyebrow,
+  pageUrl,
+  title = '',
+  isApi = false,
+  siteName = 'docs',
+  options = [],
+  onAssistant,
+}) {
+  const [open, setOpen] = React.useState(false);
+  const [copied, setCopied] = React.useState(false);
+  const rootRef = React.useRef(null);
+  const copiedTimer = React.useRef(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    const onDoc = (e) => {
+      if (!rootRef.current?.contains(e.target)) setOpen(false);
+    };
+    const onKey = (e) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('mousedown', onDoc);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('mousedown', onDoc);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  React.useEffect(() => () => clearTimeout(copiedTimer.current), []);
+
+  const flashCopied = () => {
+    setCopied(true);
+    clearTimeout(copiedTimer.current);
+    copiedTimer.current = setTimeout(() => setCopied(false), 1600);
+  };
+
+  const mdUrl = mdUrlForPage(pageUrl);
+
+  // Build the descriptor list from the configured options (skip API-only items
+  // off API pages, and any unsupported keys).
+  const items = [];
+  for (const o of options) {
+    if (typeof o === 'object' && o) {
+      items.push({ icon: ArrowUpRight, label: o.title, desc: o.description, external: true, kind: 'custom', href: o.href });
+      continue;
+    }
+    const def = REGISTRY[o];
+    if (!def) continue; // e.g. download-pdf — no static pipeline
+    if (def.apiOnly && !isApi) continue;
+    items.push({ ...def, key: o });
+  }
+
+  const copyText = async (text) => {
+    try {
+      await navigator.clipboard.writeText(text);
+      flashCopied();
+    } catch {
+      /* clipboard blocked — no-op */
+    }
+  };
+
+  const copyPage = async () => {
+    try {
+      const md = await fetch(mdUrl).then((r) => r.text());
+      await copyText(md);
+    } catch {
+      /* fetch failed — no-op */
+    }
+  };
+
+  const run = async (it) => {
+    setOpen(false);
+    const origin = window.location.origin;
+    const absMd = origin + mdUrl;
+    switch (it.kind) {
+      case 'copy':
+        return copyPage();
+      case 'view':
+        return void window.open(mdUrl, '_blank', 'noopener');
+      case 'spec': {
+        try {
+          const text = await fetch(mdUrl).then((r) => r.text());
+          const blob = new Blob([text], { type: 'text/yaml' });
+          const a = document.createElement('a');
+          a.href = URL.createObjectURL(blob);
+          a.download = `${(title || 'openapi').replace(/[^a-z0-9]+/gi, '-').toLowerCase()}.yaml`;
+          a.click();
+          URL.revokeObjectURL(a.href);
+        } catch {
+          /* no-op */
+        }
+        return;
+      }
+      case 'assistant':
+        return onAssistant?.();
+      case 'ai': {
+        const q = encodeURIComponent(`Read ${absMd} and answer my questions about this page.`);
+        return void window.open(it.url(q), '_blank', 'noopener');
+      }
+      case 'mcp':
+        // Stubbed: the Velu MCP server isn't hosted yet — this is the intended
+        // command, wired to <origin>/mcp once it exists.
+        return copyText(`npx -y @veluai/mcp@latest ${origin}/mcp`);
+      case 'cursor': {
+        const cfg =
+          typeof btoa === 'function' ? btoa(JSON.stringify({ url: `${origin}/mcp` })) : '';
+        return void window.open(
+          `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(siteName)}&config=${cfg}`,
+          '_blank',
+          'noopener',
+        );
+      }
+      case 'vscode': {
+        const cfg = encodeURIComponent(JSON.stringify({ name: siteName, url: `${origin}/mcp` }));
+        return void window.open(
+          `https://insiders.vscode.dev/redirect/mcp/install?${cfg}`,
+          '_blank',
+          'noopener',
+        );
+      }
+      case 'custom':
+        return void window.open(it.href, '_blank', 'noopener');
+      default:
+        return undefined;
+    }
+  };
+
+  // Nothing to show → render nothing (keeps the page top clean).
+  if (!eyebrow && !items.length) return null;
+
+  return (
+    <Cluster
+      space="var(--s-2)"
+      justify="space-between"
+      align="flex-end"
+      className="velu-context-bar"
+    >
+      {eyebrow ? <span className="velu-context-bar__eyebrow">{eyebrow}</span> : <span />}
+
+      {items.length > 0 && (
+        <div ref={rootRef} className="velu-context-menu" data-open={open ? 'true' : 'false'}>
+          <div className="velu-context-menu__split">
+            <button
+              type="button"
+              className="velu-context-menu__copy"
+              onClick={copyPage}
+              aria-label="Copy page as Markdown"
+            >
+              <span className="velu-context-menu__copy-icon" aria-hidden="true">
+                {copied ? <Check size="1em" /> : <Copy size="1em" />}
+              </span>
+              <span>{copied ? 'Copied' : 'Copy Page'}</span>
+            </button>
+            <button
+              type="button"
+              className="velu-context-menu__toggle"
+              aria-haspopup="menu"
+              aria-expanded={open}
+              aria-label="More actions"
+              onClick={() => setOpen((v) => !v)}
+            >
+              <ChevronDown size="1em" aria-hidden="true" focusable="false" />
+            </button>
+          </div>
+
+          <ul className="velu-context-menu__menu" role="menu" aria-hidden={!open}>
+            {items.map((it, i) => {
+              const Icon = it.icon;
+              return (
+                <li key={it.key ?? it.href ?? i} role="none">
+                  <button
+                    type="button"
+                    role="menuitem"
+                    className="velu-context-menu__item"
+                    tabIndex={open ? 0 : -1}
+                    onClick={() => run(it)}
+                  >
+                    <span className="velu-context-menu__item-icon" aria-hidden="true">
+                      <Icon size="1.1em" />
+                    </span>
+                    <span className="velu-context-menu__item-text">
+                      <span className="velu-context-menu__item-title">
+                        {it.label}
+                        {it.external && (
+                          <ArrowUpRight
+                            className="velu-context-menu__item-ext"
+                            size="0.85em"
+                            aria-hidden="true"
+                          />
+                        )}
+                      </span>
+                      {it.desc && <span className="velu-context-menu__item-desc">{it.desc}</span>}
+                    </span>
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        </div>
+      )}
+    </Cluster>
+  );
+}

package/runtime/velu-ui/components/NotFound.jsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * NotFound — the 404 page ("Direction 1 · Classic" from the design):
+ * a big accent-colored numeral, a short message, and a three-action row
+ * (Back to Home / Search the docs / Ask AI). Centered; the host layout
+ * supplies the header + footer. Pure tokens, so light/dark follow
+ * [data-theme] automatically.
+ *
+ * @param {{
+ *   homeHref?: string,
+ *   linkComponent?: React.ElementType,
+ *   onSearch?: () => void,
+ *   onAskAI?: () => void,
+ *   eyebrow?: string, title?: string, body?: string,
+ * }} props
+ */
+export default function NotFound({
+  homeHref = '/',
+  linkComponent = 'a',
+  onSearch,
+  onAskAI,
+  eyebrow = 'Error 404',
+  title = 'This page wandered off',
+  body = 'The page you’re looking for doesn’t exist or may have moved. Pick up the trail below.',
+}) {
+  const Link = linkComponent;
+  return (
+    <section className="velu-404">
+      <p className="velu-404__eyebrow">{eyebrow}</p>
+      <div className="velu-404__num" aria-hidden="true">
+        404
+      </div>
+      <h1 className="velu-404__title">{title}</h1>
+      <p className="velu-404__body">{body}</p>
+      <div className="velu-404__actions">
+        <Link className="velu-404__btn velu-404__btn--primary" href={homeHref}>
+          <span className="velu-404__btn-ic" aria-hidden="true">
+            {resolveIcon('house', { size: '1em' })}
+          </span>
+          Back to Home
+        </Link>
+        {onSearch && (
+          <button type="button" className="velu-404__btn" onClick={onSearch}>
+            <span className="velu-404__btn-ic" aria-hidden="true">
+              {resolveIcon('search', { size: '1em' })}
+            </span>
+            Search the docs
+          </button>
+        )}
+        {onAskAI && (
+          <button type="button" className="velu-404__btn" onClick={onAskAI}>
+            <span className="velu-404__btn-ic" aria-hidden="true">
+              {resolveIcon('sparkles', { size: '1em' })}
+            </span>
+            Ask AI
+          </button>
+        )}
+      </div>
+    </section>
+  );
+}

package/runtime/velu-ui/components/api-page.css

@@ -139,13 +139,6 @@
   gap: var(--s2);
 }
 
-/* Playground right column: live response (when present) stacked above the
-   same request/response code samples shown in the page's right rail. */
-.velu-api-pg-aside {
-  display: flex;
-  flex-direction: column;
-  gap: var(--s2);
-}
 /* Breathing room inside each sample group — the code panels were reading
    as cramped against the rail edge. */
 .velu-api-samples > * {

package/runtime/velu-ui/components/api.css

@@ -265,6 +265,9 @@
   overflow: hidden;
   max-inline-size: 100%;
   min-inline-size: 0;
+  /* Own query container so the body grid reflows to the client's width
+     (it lives in a modal, outside the docs layout container). */
+  container: api-client / inline-size;
 }
 
 /* Modal close button — sits in its own row at the top of the client,
@@ -413,25 +416,62 @@
   background: transparent;
 }
 
-/* Two-column body. Falls back to single column on narrow widths via
-   a Switcher-style flex-wrap trick: flex-basis with a calc() that
-   flips when the container drops below the threshold. */
+/* Body grid with named areas so the three slots — form / live response /
+   code samples — can be placed AND reordered independently.
+   Wide (the client is its own query container, set on .velu-api-client):
+     form fills the left column; response sits top-right with the samples
+     below it. When there's no response yet, the samples take the whole right
+     column.
+   Narrow (single column): the live response moves ABOVE the form so a Send
+   result is visible without scrolling past the inputs; form then samples
+   follow. */
 .velu-api-client__body {
-  display: flex;
-  flex-wrap: wrap;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  grid-template-areas: 'form aside';
+  align-items: start;
   gap: var(--s2);
   padding: var(--s2);
 }
-.velu-api-client__left,
+.velu-api-client__body[data-has-response='true'] {
+  grid-template-areas:
+    'form response'
+    'form aside';
+}
+.velu-api-client__left {
+  grid-area: form;
+}
+.velu-api-client__response {
+  grid-area: response;
+}
 .velu-api-client__right {
-  flex-grow: 1;
-  flex-basis: calc((40rem - 100%) * 999);
+  grid-area: aside;
+}
+.velu-api-client__left,
+.velu-api-client__right,
+.velu-api-client__response {
   display: flex;
   flex-direction: column;
   gap: var(--s1);
   min-inline-size: 0;
 }
 
+@container api-client (max-width: 40rem) {
+  .velu-api-client__body,
+  .velu-api-client__body[data-has-response='true'] {
+    grid-template-columns: 1fr;
+    grid-template-areas:
+      'form'
+      'aside';
+  }
+  .velu-api-client__body[data-has-response='true'] {
+    grid-template-areas:
+      'response'
+      'form'
+      'aside';
+  }
+}
+
 .velu-api-client__title {
   margin: 0;
   font-size: var(--f-h3);

package/runtime/velu-ui/components/context-menu.css

@@ -0,0 +1,170 @@
+/* ContextMenu — the per-page agent/IDE action bar (eyebrow + Copy Page
+   split-button + dropdown). Mirrors NavSelect's dropdown recipe; all values are
+   tokens, light/dark via [data-theme]. */
+
+.velu-context-bar {
+  margin-block-end: var(--s0);
+}
+
+/* Section/group label, top-left — small, uppercase, accent (matches the
+   crimson eyebrow in the reference). */
+.velu-context-bar__eyebrow {
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: var(--f-h6);
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--accent-color);
+}
+
+.velu-context-menu {
+  position: relative;
+  flex: none;
+}
+
+/* The split button: "Copy Page" + a divider + a chevron toggle, joined as one
+   segmented control. */
+.velu-context-menu__split {
+  display: inline-flex;
+  align-items: stretch;
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+  background: var(--page-bg);
+  overflow: hidden;
+  transition: border-color 0.12s ease;
+}
+.velu-context-menu__split:hover {
+  border-color: var(--accent-color);
+}
+
+.velu-context-menu__copy,
+.velu-context-menu__toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-3);
+  background: transparent;
+  border: 0;
+  font: inherit;
+  font-size: var(--f-h6);
+  color: var(--text-color);
+  cursor: pointer;
+  transition: background 0.12s ease, color 0.12s ease;
+}
+.velu-context-menu__copy {
+  padding-block: var(--s-3);
+  padding-inline: var(--s-1);
+  font-weight: 500;
+}
+.velu-context-menu__toggle {
+  padding-inline: var(--s-3);
+  border-inline-start: var(--border-width) solid var(--border-color);
+}
+.velu-context-menu__copy:hover,
+.velu-context-menu__toggle:hover {
+  background: var(--surface-color);
+  color: var(--accent-color);
+}
+.velu-context-menu__copy-icon {
+  display: inline-flex;
+  flex: none;
+}
+.velu-context-menu__toggle svg {
+  transition: transform 0.18s ease;
+}
+.velu-context-menu[data-open='true'] .velu-context-menu__toggle svg {
+  transform: rotate(180deg);
+}
+
+/* Menu — anchored to the trailing edge below the button; fades + slides in.
+   Always in DOM so the transition runs both ways; visibility delayed so the
+   closed menu isn't focusable. */
+.velu-context-menu__menu {
+  position: absolute;
+  inset-block-start: calc(100% + var(--s-3));
+  inset-inline-end: 0;
+  min-inline-size: 17rem;
+  margin: 0;
+  padding-block: var(--s-3);
+  padding-inline: 0.5rem; /* 8px */
+  list-style: none;
+  background: var(--page-bg);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: 0.75rem; /* 12px */
+  box-shadow: 0 var(--s-1) var(--s2) color-mix(in srgb, #000 14%, transparent);
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(-0.25rem);
+  pointer-events: none;
+  transition:
+    opacity 0.15s ease,
+    transform 0.15s ease,
+    visibility 0s linear 0.15s;
+  z-index: 40;
+}
+.velu-context-menu[data-open='true'] .velu-context-menu__menu {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+  pointer-events: auto;
+  transition:
+    opacity 0.15s ease,
+    transform 0.15s ease,
+    visibility 0s;
+}
+
+.velu-context-menu__item {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--s-2);
+  inline-size: 100%;
+  padding-block: var(--s-3);
+  padding-inline: var(--s-3);
+  border-radius: var(--radius-sm);
+  background: transparent;
+  border: 0;
+  font: inherit;
+  text-align: start;
+  color: var(--text-color);
+  cursor: pointer;
+  transition: background 0.12s ease;
+}
+.velu-context-menu__item:hover {
+  background: var(--surface-color);
+}
+
+.velu-context-menu__item-icon {
+  display: inline-flex;
+  flex: none;
+  margin-block-start: 0.1em;
+  color: var(--muted-color);
+}
+.velu-context-menu__item:hover .velu-context-menu__item-icon {
+  color: var(--accent-color);
+}
+
+.velu-context-menu__item-text {
+  display: flex;
+  flex-direction: column;
+  gap: 0.1em;
+  min-inline-size: 0;
+}
+.velu-context-menu__item-title {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-4);
+  font-size: var(--f-h6);
+  font-weight: 500;
+  color: var(--text-color);
+}
+.velu-context-menu__item-ext {
+  flex: none;
+  color: var(--muted-color);
+}
+.velu-context-menu__item-desc {
+  font-size: var(--f-h6);
+  line-height: var(--lh-tight, 1.3);
+  color: var(--muted-color);
+}

package/runtime/velu-ui/components/docs-layout.css

@@ -782,3 +782,21 @@
     display: block;
   }
 }
+
+/* ── 404 takeover ─────────────────────────────────────────────────────── */
+/* On a not-found route the docs chrome (both fixed asides) is hidden and the
+   centre column spans full width to center the <NotFound> content. The header
+   and (configured) footer stay. */
+.velu-docs-layout[data-not-found='true'] .velu-docs-layout__aside {
+  display: none;
+}
+.velu-docs-layout[data-not-found='true'] .velu-docs-layout__center {
+  margin-inline: 0;
+}
+.velu-404-main {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-block-size: 70vh;
+  padding: var(--s4) var(--s2);
+}