@veluai/velu 0.1.15 → 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/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>

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

@@ -21,6 +21,7 @@ export default function TryItBar({
   path = '',
   cta = 'Try It',
   onTry,
+  loading = false,
   className = '',
   ...rest
 }) {
@@ -79,10 +80,21 @@ export default function TryItBar({
         type="button"
         className="velu-try-it__cta"
         onClick={onTry}
+        data-loading={loading ? 'true' : undefined}
+        disabled={loading || undefined}
+        aria-busy={loading || undefined}
       >
-        {cta}
-        <span className="velu-try-it__cta-icon" aria-hidden="true">
-          {resolveIcon('chevron-right', { size: '1em' })}
+        {/* Two stacked layers swap with a vertical slide: the label slides
+            down and out the bottom while the spinner slides in from the top.
+            overflow:hidden on the button clips both off-screen states. */}
+        <span className="velu-try-it__cta-label">
+          {cta}
+          <span className="velu-try-it__cta-icon" aria-hidden="true">
+            {resolveIcon('chevron-right', { size: '1em' })}
+          </span>
+        </span>
+        <span className="velu-try-it__cta-spinner" aria-hidden="true">
+          {resolveIcon('loader-circle', { size: '1em' })}
         </span>
       </button>
     </Cluster>

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

@@ -0,0 +1,215 @@
+/* Auto-generated OpenAPI reference page. Composes existing API components; this
+   only adds the page-level rhythm, the response tabs, and the playground's
+   live-response panel + body input. All tokens — light/dark via [data-theme]. */
+
+.velu-api-page__title {
+  font-size: var(--f-h1);
+  font-weight: var(--weight-bold);
+  line-height: 1.1;
+  letter-spacing: -0.02em;
+  margin: 0 0 var(--s1);
+}
+.velu-api-page__lede {
+  color: var(--muted-color);
+  margin: 0 0 var(--s2);
+}
+.velu-api-page__tryit {
+  margin-block: var(--s2);
+}
+.velu-api-page__section {
+  margin-block-start: var(--s3);
+}
+.velu-api-page__section > h2 {
+  font-size: var(--f-h3);
+  font-weight: var(--weight-semibold);
+  margin: 0 0 var(--s1);
+}
+.velu-api-page__enum {
+  margin-block-start: var(--s-3);
+  color: var(--muted-color);
+  font-size: var(--f-h6);
+}
+.velu-api-page__enum code {
+  margin-inline-end: var(--s-4);
+}
+
+/* ── Response sections (doc body) ──────────────────────────────────────── */
+/* One default-open accordion per status; the summary shows a status pill +
+   the content-type. */
+.velu-api-resp__head {
+  display: inline-flex;
+  align-items: baseline;
+  gap: var(--s0);
+}
+/* Plain status code — no pill chrome, no per-status color, regular weight. */
+.velu-api-resp__status {
+  font-family: var(--font-mono);
+}
+.velu-api-resp__ctype {
+  color: var(--muted-color);
+  font-family: var(--font-mono);
+  font-size: var(--f-h6);
+}
+.velu-api-resp__desc {
+  color: var(--muted-color);
+  margin: 0 0 var(--s1);
+}
+
+/* ── Playground live-response panel (ApiClient aside) ──────────────────── */
+/* A Body / Header tabbed card reusing the CodeGroup tab chrome
+   (.velu-code-block__*): Body shows a status-colored callout + the response
+   body; Header shows the response headers as a fixed-height scrollable table. */
+.velu-api-resp-panel__content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s1);
+  padding: var(--s1);
+  background: var(--page-bg);
+}
+.velu-api-resp-panel__status {
+  /* The Callout owns its color; keep the weight regular. */
+  font-size: var(--f-h6);
+}
+
+/* Body + Header tabs — fixed height, vertically scrollable, so a long
+   response never makes the panel grow unbounded. */
+.velu-api-resp-headers__scroll,
+.velu-api-resp-body__scroll {
+  max-block-size: 15rem;
+  overflow-y: auto;
+}
+/* The CodeBlock owns its own border/radius; let it fill the scroll box. */
+.velu-api-resp-body__scroll > .velu-code-block {
+  border: 0;
+  border-radius: 0;
+}
+
+/* Response headers table — flush rows with hairline dividers. */
+.velu-api-resp-headers {
+  inline-size: 100%;
+  border-collapse: collapse;
+  font-size: var(--f-h6);
+}
+.velu-api-resp-headers tr + tr td {
+  border-block-start: var(--border-width) solid var(--border-color);
+}
+.velu-api-resp-headers td {
+  padding: var(--s-2) var(--s-1);
+  vertical-align: top;
+  word-break: break-word;
+}
+.velu-api-resp-headers__key {
+  color: var(--muted-color);
+  font-family: var(--font-mono);
+  white-space: nowrap;
+  padding-inline-end: var(--s1) !important;
+}
+.velu-api-resp-headers__val {
+  font-family: var(--font-mono);
+  inline-size: 100%;
+}
+
+/* Editable JSON body in the playground. */
+.velu-api-body-input {
+  inline-size: 100%;
+  resize: vertical;
+  padding: var(--s0);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+  background: var(--page-bg);
+  color: var(--text-color);
+  font-family: var(--font-mono);
+  font-size: var(--f-h6);
+  line-height: 1.5;
+}
+
+/* ── Right-rail samples ────────────────────────────────────────────────── */
+/* A TOC needs only ~280px, but the request/response code samples were being
+   cropped in that width. On API pages widen the right rail — both the aside
+   width AND the centre column's right margin read this one var, so they stay
+   in sync. (At < 1024px the @container query hides the rail + zeroes the
+   margin, so this wider value never affects narrow layouts.) */
+.velu-docs-layout[data-api='true'] {
+  --velu-aside-right-width: 28rem; /* 448px */
+}
+
+.velu-api-samples {
+  display: flex;
+  flex-direction: column;
+  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 > * {
+  margin: 0;
+}
+.velu-api-samples :is(pre, code) {
+  font-size: var(--f-h6);
+  line-height: 1.6;
+}
+
+/* ── Try-It playground modal ───────────────────────────────────────────── */
+/* The playground renders above the page on a dimmed, blurred backdrop
+   rather than inline. */
+.velu-api-modal {
+  position: fixed;
+  inset: 0;
+  z-index: 80;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: clamp(var(--s1), 6vh, var(--s5)) var(--s2);
+  overflow-y: auto;
+  background: color-mix(in srgb, var(--page-bg) 35%, rgba(0, 0, 0, 0.55));
+  backdrop-filter: blur(6px) saturate(1.1);
+  -webkit-backdrop-filter: blur(6px) saturate(1.1);
+  animation: velu-api-modal-in 140ms ease-out;
+}
+.velu-api-modal__panel {
+  inline-size: 100%;
+  max-inline-size: 64rem;
+  border-radius: var(--radius-md);
+  box-shadow:
+    0 24px 64px -16px rgba(0, 0, 0, 0.45),
+    0 8px 24px -12px rgba(0, 0, 0, 0.35);
+  animation: velu-api-modal-rise 160ms cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+@keyframes velu-api-modal-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@keyframes velu-api-modal-rise {
+  from { opacity: 0; transform: translateY(8px) scale(0.99); }
+  to { opacity: 1; transform: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .velu-api-modal,
+  .velu-api-modal__panel {
+    animation: none;
+  }
+}
+
+/* Compact method pill in the sidebar (replaces the icon for API endpoints). */
+.velu-sidebar__method {
+  flex: none;
+  font-family: var(--font-mono);
+  font-size: 0.6rem;
+  font-weight: var(--weight-bold);
+  letter-spacing: 0.03em;
+  padding: 0.18em 0.36em;
+  border-radius: var(--radius-xs, 4px);
+  text-transform: uppercase;
+}
+.velu-sidebar__method.velu-method-badge--get { color: var(--get-pill-color); background: color-mix(in srgb, var(--get-pill-color) 14%, transparent); }
+.velu-sidebar__method.velu-method-badge--post { color: var(--post-pill-color); background: color-mix(in srgb, var(--post-pill-color) 14%, transparent); }
+.velu-sidebar__method.velu-method-badge--put { color: var(--put-pill-color); background: color-mix(in srgb, var(--put-pill-color) 14%, transparent); }
+.velu-sidebar__method.velu-method-badge--patch { color: var(--patch-pill-color); background: color-mix(in srgb, var(--patch-pill-color) 14%, transparent); }
+.velu-sidebar__method.velu-method-badge--delete { color: var(--delete-pill-color); background: color-mix(in srgb, var(--delete-pill-color) 14%, transparent); }