@veluai/velu 0.1.14 → 0.1.16

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

@@ -0,0 +1,388 @@
+import React, { useState, useCallback, useEffect } from 'react';
+import { createPortal } from 'react-dom';
+import MethodBadge from './MethodBadge.jsx';
+import ApiPath from './ApiPath.jsx';
+import TryItBar from './TryItBar.jsx';
+import ApiClient from './ApiClient.jsx';
+import ApiField from './ApiField.jsx';
+import Field from './Field.jsx';
+import Accordion, { AccordionGroup } from './Accordion.jsx';
+import CodeBlock, { CodeGroup } from './CodeBlock.jsx';
+import ApiSamples from './ApiSamples.jsx';
+import Callout from './Callout.jsx';
+import { sendApiRequest } from '../lib/api-send.js';
+
+/**
+ * ApiReferencePage — the full, auto-generated reference page for one OpenAPI
+ * operation. Driven entirely by the normalized `operation` model (see the
+ * CLI's src/openapi/parse.js). Renders the doc body (auth, params, body,
+ * responses) and an interactive "Try It" playground that builds + sends the
+ * request (through the dev proxy by default — see lib/api-send.js).
+ *
+ * The right-rail code samples live in the page's right aside (the runtime
+ * renders <ApiSamples> there for API pages) — this component owns the main
+ * column + the playground only.
+ *
+ * @param {{ operation: object, api?: { proxy?: boolean, server?: string } }} props
+ */
+const LOCATION_LABEL = { path: 'Path Parameters', query: 'Query Parameters', header: 'Header Parameters' };
+
+export default function ApiReferencePage({ operation, samples = [], apiOperations = [], api = {} }) {
+  const [open, setOpen] = useState(false);
+  // Which operation the playground is currently showing. Defaults to this
+  // page's own operation; the dropdown can switch it to any sibling.
+  const [activeId, setActiveId] = useState(operation.id);
+
+  // The switchable list — fall back to just this page's operation.
+  const ops =
+    apiOperations.length > 0
+      ? apiOperations
+      : [{ id: operation.id, method: operation.method, title: operation.title, operation, samples }];
+  const current = ops.find((o) => o.id === activeId) || { operation, samples };
+  const server = api.server || current.operation.servers?.[0] || '';
+
+  // While the playground modal is open, close on Escape and lock the
+  // page scroll so the dimmed backdrop reads as a true overlay.
+  useEffect(() => {
+    if (!open || typeof document === 'undefined') return undefined;
+    const onKey = (e) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('keydown', onKey);
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    return () => {
+      document.removeEventListener('keydown', onKey);
+      document.body.style.overflow = prev;
+    };
+  }, [open]);
+
+  if (!operation) return null;
+
+  return (
+    <div className="velu-api-page">
+      {/* The page title + description come from the page frontmatter heading
+          (rendered by the runtime), so this component starts at the Try-It bar
+          to avoid a duplicate title. */}
+      <TryItBar
+        method={operation.method}
+        path={operation.path}
+        cta="Try It"
+        onTry={() => {
+          setActiveId(operation.id);
+          setOpen(true);
+        }}
+        className="velu-api-page__tryit"
+      />
+
+      {/* Authorizations */}
+      {operation.auth?.length > 0 && (
+        <section className="velu-api-page__section">
+          <h2>Authorizations</h2>
+          {operation.auth.map((a, i) => (
+            <Field key={i} name={a.name} pre={a.prefix} type={a.type} required={a.required} post={a.in}>
+              {a.description}
+            </Field>
+          ))}
+        </section>
+      )}
+
+      {/* Parameters, by location */}
+      {['path', 'query', 'header'].map((loc) => {
+        const rows = operation.parameters?.[loc] || [];
+        if (!rows.length) return null;
+        return (
+          <section key={loc} className="velu-api-page__section">
+            <h2>{LOCATION_LABEL[loc]}</h2>
+            {rows.map((p, i) => (
+              <Field key={i} name={p.name} type={p.type} required={p.required}>
+                {p.description}
+                {p.enum && <EnumHint values={p.enum} />}
+              </Field>
+            ))}
+          </section>
+        );
+      })}
+
+      {/* Request body */}
+      {operation.body?.fields?.length > 0 && (
+        <section className="velu-api-page__section">
+          <h2>Body</h2>
+          {operation.body.fields.map((f, i) => (
+            <Field key={i} name={f.name} type={f.type} required={f.required}>
+              {f.description}
+              {f.enum && <EnumHint values={f.enum} />}
+            </Field>
+          ))}
+        </section>
+      )}
+
+      {/* Responses */}
+      {operation.responses?.length > 0 && (
+        <section className="velu-api-page__section">
+          <h2>Response</h2>
+          <ResponseSections responses={operation.responses} />
+        </section>
+      )}
+
+      {/* Try-It playground — rendered as an overlay above the page, with a
+          blurred backdrop, rather than inline. Portaled to <body> so the
+          docs layout's @container containment can't clip the fixed overlay. */}
+      {open && typeof document !== 'undefined' &&
+        createPortal(
+          <div
+            className="velu-api-modal"
+            role="presentation"
+            onClick={() => setOpen(false)}
+          >
+            <div
+              className="velu-api-modal__panel"
+              role="dialog"
+              aria-modal="true"
+              aria-label={`${operation.title} playground`}
+              onClick={(e) => e.stopPropagation()}
+            >
+              <Playground
+                key={current.operation.id}
+                operation={current.operation}
+                samples={current.samples}
+                operations={ops}
+                activeId={activeId}
+                onSelectOperation={setActiveId}
+                server={server}
+                proxy={api.proxy !== false}
+                onClose={() => setOpen(false)}
+              />
+            </div>
+          </div>,
+          document.body,
+        )}
+    </div>
+  );
+}
+
+function EnumHint({ values }) {
+  return (
+    <p className="velu-api-page__enum">
+      Allowed values:{' '}
+      {values.map((v, i) => (
+        <code key={i}>{String(v)}</code>
+      ))}
+    </p>
+  );
+}
+
+function ResponseSections({ responses }) {
+  return (
+    <AccordionGroup className="velu-api-resp">
+      {responses.map((r, i) => {
+        return (
+          <Accordion
+            key={i}
+            defaultOpen
+            title={
+              <span className="velu-api-resp__head">
+                <span className="velu-api-resp__status">{r.status}</span>
+                {r.contentType && (
+                  <span className="velu-api-resp__ctype">{r.contentType}</span>
+                )}
+              </span>
+            }
+          >
+            {r.description && <p className="velu-api-resp__desc">{r.description}</p>}
+            {r.fields?.map((f, j) => (
+              <Field key={j} name={f.name} type={f.type} required={f.required}>
+                {f.description}
+              </Field>
+            ))}
+          </Accordion>
+        );
+      })}
+    </AccordionGroup>
+  );
+}
+
+// ── The interactive playground ──────────────────────────────────────────────
+
+function Playground({
+  operation,
+  samples = [],
+  operations = [],
+  activeId,
+  onSelectOperation,
+  server,
+  proxy,
+  onClose,
+}) {
+  const [values, setValues] = useState({});
+  const [bodyText, setBodyText] = useState(
+    operation.body ? JSON.stringify(operation.body.example ?? {}, null, 2) : '',
+  );
+  const [busy, setBusy] = useState(false);
+  const [resp, setResp] = useState(null);
+
+  const set = (loc, name, v) =>
+    setValues((prev) => ({ ...prev, [loc]: { ...(prev[loc] || {}), [name]: v } }));
+
+  const onSend = useCallback(async () => {
+    setBusy(true);
+    setResp(null);
+    try {
+      const result = await sendApiRequest({ operation, server, proxy, values, bodyText });
+      setResp(result);
+    } catch (err) {
+      setResp({ error: String(err?.message || err) });
+    } finally {
+      setBusy(false);
+    }
+  }, [operation, server, proxy, values, bodyText]);
+
+  const sections = [];
+  if (operation.auth?.length) sections.push(['auth', 'Authorization', operation.auth]);
+  for (const loc of ['path', 'query', 'header']) {
+    const rows = operation.parameters?.[loc] || [];
+    if (rows.length) sections.push([loc, LOCATION_LABEL[loc].replace(' Parameters', ''), rows]);
+  }
+
+  return (
+    <ApiClient
+      method={operation.method}
+      label={operation.title}
+      path={operation.path}
+      description={operation.description}
+      operations={operations}
+      activeId={activeId}
+      onSelectOperation={onSelectOperation}
+      onSend={onSend}
+      sending={busy}
+      onClose={onClose}
+      aside={
+        <div className="velu-api-pg-aside">
+          {/* The live response is prepended above the static request /
+              response samples as it comes in. Progress is shown by the Send
+              button's spinner — no "Sending…" placeholder here. */}
+          {resp && <ResponsePanel resp={resp} />}
+          <ApiSamples samples={samples} responses={operation.responses} />
+        </div>
+      }
+    >
+      <AccordionGroup>
+        {sections.map(([loc, title, rows]) => (
+          <Accordion key={loc} title={title} defaultOpen>
+            {rows.map((f, i) => (
+              <ApiField
+                key={i}
+                name={f.name}
+                type={f.type}
+                required={f.required}
+                prefix={f.prefix}
+                value={values[loc]?.[f.name] ?? ''}
+                onChange={(e) => set(loc, f.name, e.target.value)}
+              >
+                {f.description}
+              </ApiField>
+            ))}
+          </Accordion>
+        ))}
+        {operation.body && (
+          <Accordion title="Body" defaultOpen>
+            <textarea
+              className="velu-api-body-input"
+              spellCheck={false}
+              rows={Math.min(14, bodyText.split('\n').length + 1)}
+              value={bodyText}
+              onChange={(e) => setBodyText(e.target.value)}
+            />
+          </Accordion>
+        )}
+      </AccordionGroup>
+    </ApiClient>
+  );
+}
+
+/**
+ * ResponsePanel — the live-response viewer: a Body / Header tabbed card.
+ *  - Body:   a status-colored Callout (green for 2xx, red otherwise) plus the
+ *            response body.
+ *  - Header: the response headers as a key/value table.
+ */
+function ResponsePanel({ resp }) {
+  const [tab, setTab] = useState('body');
+  if (!resp) return null;
+
+  const isError = resp.error != null;
+  const ok = !isError && resp.status >= 200 && resp.status < 300;
+  const statusLabel = isError
+    ? 'Request failed'
+    : `${resp.status}${resp.statusText ? ` - ${resp.statusText}` : ''}`;
+  const bodyStr = isError
+    ? resp.error
+    : typeof resp.body === 'string'
+      ? resp.body
+      : JSON.stringify(resp.body, null, 2);
+  const headerRows = Object.entries(resp.headers || {});
+
+  // Reuse the CodeGroup's tab chrome (velu-code-block__*) so the Body/Header
+  // switcher looks identical to the code-sample tabs.
+  const tabCls = (name) =>
+    `velu-code-block__tab${tab === name ? ' velu-code-block__tab--active' : ''}`;
+
+  return (
+    <div className="velu-code-block velu-api-resp-panel">
+      <div className="velu-code-block__header">
+        <div className="velu-code-block__tabs" role="tablist">
+          <button
+            type="button"
+            role="tab"
+            aria-selected={tab === 'body'}
+            className={tabCls('body')}
+            onClick={() => setTab('body')}
+          >
+            <span className="velu-code-block__tab-label">Body</span>
+          </button>
+          <button
+            type="button"
+            role="tab"
+            aria-selected={tab === 'header'}
+            className={tabCls('header')}
+            onClick={() => setTab('header')}
+            disabled={!headerRows.length || undefined}
+          >
+            <span className="velu-code-block__tab-label">Header</span>
+          </button>
+        </div>
+      </div>
+
+      <div className="velu-api-resp-panel__content">
+        {tab === 'body' ? (
+          <>
+            <Callout
+              type={ok ? 'check' : 'danger'}
+              className="velu-api-resp-panel__status"
+            >
+              {statusLabel}
+            </Callout>
+            {!isError && (
+              <div className="velu-api-resp-body__scroll velu-hide-scrollbar">
+                <CodeBlock language="json">{bodyStr || '(empty)'}</CodeBlock>
+              </div>
+            )}
+          </>
+        ) : (
+          <div className="velu-api-resp-headers__scroll velu-hide-scrollbar">
+            <table className="velu-api-resp-headers">
+              <tbody>
+                {headerRows.map(([k, val]) => (
+                  <tr key={k}>
+                    <td className="velu-api-resp-headers__key">{k}</td>
+                    <td className="velu-api-resp-headers__val">{val}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,36 @@
+import React from 'react';
+import CodeBlock, { CodeGroup } from './CodeBlock.jsx';
+
+/**
+ * ApiSamples — the right-rail of an API reference page: the request code
+ * snippets (curl / JS / Python / Ruby tabs) and the example responses
+ * (one tab per status). The runtime renders this in the page's right aside
+ * (where the TOC sits for normal pages).
+ *
+ * @param {{ samples: {key,label,language,code}[], responses: object[] }} props
+ */
+export default function ApiSamples({ samples = [], responses = [] }) {
+  const withExample = responses.filter((r) => r.example != null);
+  return (
+    <div className="velu-api-samples">
+      {samples.length > 0 && (
+        <CodeGroup className="velu-api-samples__req">
+          {samples.map((s) => (
+            <CodeBlock key={s.key} title={s.label} language={s.language}>
+              {s.code}
+            </CodeBlock>
+          ))}
+        </CodeGroup>
+      )}
+      {withExample.length > 0 && (
+        <CodeGroup className="velu-api-samples__res">
+          {withExample.map((r) => (
+            <CodeBlock key={r.status} title={r.status} language="json">
+              {JSON.stringify(r.example, null, 2)}
+            </CodeBlock>
+          ))}
+        </CodeGroup>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+import React from 'react';
+
+/**
+ * Logo — the configured site logo image(s), shown in the header (and mobile
+ * drawer) in place of the name wordmark.
+ *
+ * `logo` is `{ light, dark, mono }` where light/dark are URLs the dev server
+ * serves from the project's logo files. When `mono`, a single image covers
+ * both themes; otherwise both render and CSS shows the right one per
+ * `[data-theme]` (see page-header.css `.velu-logo--light/--dark`).
+ *
+ * SSR-safe: identical markup on server + client (the theme picks the visible
+ * image via CSS, not JS), so there's no hydration mismatch or flash.
+ */
+export default function Logo({ logo, alt = '' }) {
+  if (!logo) return null;
+  if (logo.mono) {
+    return <img className="velu-logo" src={logo.light} alt={alt} />;
+  }
+  return (
+    <>
+      <img className="velu-logo velu-logo--light" src={logo.light} alt={alt} />
+      <img
+        className="velu-logo velu-logo--dark"
+        src={logo.dark}
+        alt={alt}
+        aria-hidden="true"
+      />
+    </>
+  );
+}

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

@@ -1,6 +1,7 @@
 import React from 'react';
 import Stack from '../primitives/Stack.jsx';
 import Cluster from '../primitives/Cluster.jsx';
+import SocialLinks from './SocialLinks.jsx';
 
 /**
  * PageFooter — the docs site's footer.
@@ -65,54 +66,6 @@ function VeluMark() {
   );
 }
 
-/* ── Social glyphs — inline SVGs with fill: currentColor so they
-   inherit color (themed) and flip with light/dark. ─────────────────── */
-function GithubIcon() {
-  return (
-    <svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M8 0C3.58 0 0 3.58 0 8C0 11.54 2.29 14.53 5.47 15.59C5.87 15.66 6.02 15.42 6.02 15.21C6.02 15.02 6.01 14.39 6.01 13.72C4 14.09 3.48 13.23 3.32 12.78C3.23 12.55 2.84 11.84 2.5 11.65C2.22 11.5 1.82 11.13 2.49 11.12C3.12 11.11 3.57 11.7 3.72 11.94C4.44 13.15 5.59 12.81 6.05 12.6C6.12 12.08 6.33 11.73 6.56 11.53C4.78 11.33 2.92 10.64 2.92 7.58C2.92 6.71 3.23 5.99 3.74 5.43C3.66 5.23 3.38 4.41 3.82 3.31C3.82 3.31 4.49 3.1 6.02 4.13C6.66 3.95 7.34 3.86 8.02 3.86C8.7 3.86 9.38 3.95 10.02 4.13C11.55 3.09 12.22 3.31 12.22 3.31C12.66 4.41 12.38 5.23 12.3 5.43C12.81 5.99 13.12 6.7 13.12 7.58C13.12 10.65 11.25 11.33 9.47 11.53C9.76 11.78 10.01 12.26 10.01 13.01C10.01 14.08 10 14.94 10 15.21C10 15.42 10.15 15.67 10.55 15.59C13.71 14.53 16 11.53 16 8C16 3.58 12.42 0 8 0Z"
-      />
-    </svg>
-  );
-}
-function XIcon() {
-  return (
-    <svg viewBox="0 0 1200 1227" fill="currentColor" aria-hidden="true">
-      <path d="M714.163 519.284 1160.89 0h-105.86L667.137 450.887 357.328 0H0l468.492 681.821L0 1226.37h105.866l409.625-476.152 327.181 476.152H1200L714.137 519.284h.026ZM569.165 687.828l-47.468-67.894-377.686-540.24h162.604l304.797 435.991 47.468 67.894 396.2 566.721H892.476L569.165 687.854v-.026Z" />
-    </svg>
-  );
-}
-function YoutubeIcon() {
-  return (
-    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
-      <path d="M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 0 0 .502 6.186C0 8.07 0 12 0 12s0 3.93.502 5.814a3.016 3.016 0 0 0 2.122 2.136c1.871.505 9.376.505 9.376.505s7.505 0 9.377-.505a3.015 3.015 0 0 0 2.122-2.136C24 15.93 24 12 24 12s0-3.93-.502-5.814zM9.545 15.568V8.432L15.818 12l-6.273 3.568z" />
-    </svg>
-  );
-}
-function LinkedinIcon() {
-  return (
-    <svg viewBox="0 0 256 256" fill="currentColor" aria-hidden="true">
-      <path d="M218.123 218.127h-37.931v-59.403c0-14.165-.253-32.4-19.728-32.4-19.756 0-22.779 15.434-22.779 31.369v60.43h-37.93V95.967h36.413v16.694h.51a39.907 39.907 0 0 1 35.928-19.733c38.445 0 45.533 25.288 45.533 58.186l-.016 67.013ZM56.955 79.27c-12.157.002-22.014-9.852-22.016-22.009-.002-12.157 9.851-22.014 22.008-22.016 12.157-.003 22.014 9.851 22.016 22.008A22.013 22.013 0 0 1 56.955 79.27m18.966 138.858H37.95V95.967h37.97v122.16ZM237.033.018H18.89C8.58-.098.125 8.161-.001 18.471v219.053c.122 10.315 8.576 18.582 18.89 18.474h218.144c10.336.128 18.823-8.139 18.966-18.474V18.454c-.147-10.33-8.635-18.588-18.966-18.453" />
-    </svg>
-  );
-}
-
-const SOCIAL_ICONS = {
-  github: GithubIcon,
-  x: XIcon,
-  youtube: YoutubeIcon,
-  linkedin: LinkedinIcon,
-};
-const SOCIAL_LABELS = {
-  github: 'GitHub',
-  x: 'X',
-  youtube: 'YouTube',
-  linkedin: 'LinkedIn',
-};
-
 export default function PageFooter({
   brand,
   columns = [],
@@ -182,32 +135,11 @@ export default function PageFooter({
       </Stack>
 
       {/* Socials sit OUTSIDE the container, at the bottom of the footer. */}
-      {socials.length > 0 && (
-        <Cluster
-          space="var(--s-2)"
-          justify="center"
-          align="center"
-          className="velu-footer__socials"
-        >
-          {socials.map((s, i) => {
-            const Icon = SOCIAL_ICONS[s.kind];
-            if (!Icon) return null;
-            return (
-              <a
-                key={i}
-                href={s.href}
-                target="_blank"
-                rel="noreferrer"
-                aria-label={SOCIAL_LABELS[s.kind] ?? s.kind}
-                className="velu-footer__social"
-                data-kind={s.kind}
-              >
-                <Icon />
-              </a>
-            );
-          })}
-        </Cluster>
-      )}
+      <SocialLinks
+        socials={socials}
+        justify="center"
+        className="velu-footer__socials"
+      />
     </Stack>
   );
 }

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

@@ -3,6 +3,7 @@ import { MoreVertical, Menu, ChevronRight } from 'lucide-react';
 import resolveIcon from '../lib/resolveIcon.jsx';
 import Stack from '../primitives/Stack.jsx';
 import Cluster from '../primitives/Cluster.jsx';
+import Logo from './Logo.jsx';
 
 /**
  * PageHeader — top of the docs site.
@@ -258,10 +259,17 @@ export default function PageHeader({
     return () => window.removeEventListener('scroll', onScroll);
   }, []);
 
+  // A configured logo replaces the mark + wordmark entirely (Mintlify-style).
   const brandBlock = (
     <Cluster space="var(--s-3)" align="center" className="velu-header__brand">
-      <VeluMark />
-      <span className="velu-header__wordmark">{brandLabel}</span>
+      {brand?.logo ? (
+        <Logo logo={brand.logo} alt={brandLabel} />
+      ) : (
+        <>
+          <VeluMark />
+          <span className="velu-header__wordmark">{brandLabel}</span>
+        </>
+      )}
     </Cluster>
   );
 

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

@@ -87,7 +87,7 @@ function ExternalIcon() {
 /** Recursive node. depth 0 = top-level; depth >= 1 = nested (subitem style). */
 function Node({ item, depth }) {
   const { activeHref, Link } = React.useContext(SidebarCtx);
-  const { label, href = '#', icon, external, items } = item;
+  const { label, href = '#', icon, external, items, method } = item;
   const base = depth === 0 ? 'velu-sidebar__item' : 'velu-sidebar__subitem';
 
   if (items && items.length) {
@@ -125,7 +125,15 @@ function Node({ item, depth }) {
         aria-current={active ? 'page' : undefined}
         {...linkProps}
       >
-        <Icon icon={icon} />
+        {method ? (
+          <span
+            className={`velu-sidebar__method velu-method-badge--${String(method).toLowerCase()}`}
+          >
+            {method}
+          </span>
+        ) : (
+          <Icon icon={icon} />
+        )}
         <span className="velu-sidebar__label">{label}</span>
         {external ? <ExternalIcon /> : null}
       </LinkTag>