@veluai/velu 0.1.15 → 0.1.16

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

@@ -175,9 +175,11 @@
   color: var(--text-color);
 }
 .velu-try-it__cta {
+  position: relative;
+  overflow: hidden;
   display: inline-flex;
   align-items: center;
-  gap: var(--s-2);
+  justify-content: center;
   padding-block: var(--s-3);
   padding-inline: var(--s0);
   background: var(--method-cta, var(--accent-color));
@@ -194,6 +196,56 @@
 .velu-try-it__cta:hover {
   background: color-mix(in srgb, var(--method-cta, var(--accent-color)) 88%, #000);
 }
+.velu-try-it__cta:disabled {
+  cursor: default;
+}
+
+/* Label (text + chevron) and the loading spinner are two stacked layers
+   that swap with a vertical slide: when loading, the label slides DOWN and
+   out the bottom while the spinner slides IN from the top. overflow:hidden
+   on the button clips the off-screen states. The label stays in normal flow
+   so it fixes the button's width; the spinner overlays it. */
+.velu-try-it__cta-label {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  transition: transform 0.22s ease, opacity 0.18s ease;
+}
+.velu-try-it__cta-spinner {
+  position: absolute;
+  inset: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  transform: translateY(-110%);
+  opacity: 0;
+  transition: transform 0.22s ease, opacity 0.18s ease;
+}
+.velu-try-it__cta[data-loading='true'] .velu-try-it__cta-label {
+  transform: translateY(120%);
+  opacity: 0;
+}
+.velu-try-it__cta[data-loading='true'] .velu-try-it__cta-spinner {
+  transform: translateY(0);
+  opacity: 1;
+}
+.velu-try-it__cta-spinner svg {
+  animation: velu-cta-spin 0.7s linear infinite;
+}
+@keyframes velu-cta-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .velu-try-it__cta-label,
+  .velu-try-it__cta-spinner {
+    transition-duration: 0.01ms;
+  }
+  .velu-try-it__cta-spinner svg {
+    animation-duration: 1.4s;
+  }
+}
 .velu-try-it--get   { --method-cta: var(--get-cta-color); }
 .velu-try-it--post  { --method-cta: var(--post-cta-color); }
 .velu-try-it--put   { --method-cta: var(--put-cta-color); }
@@ -262,6 +314,7 @@
    AND natural height; the Cluster's align: flex-start keeps it from
    stretching to the taller TryItBar's height). */
 .velu-api-client__op {
+  position: relative;
   display: flex;
   align-items: center;
   gap: var(--s-2);
@@ -274,6 +327,20 @@
   line-height: var(--lh-h6);
   flex: none;
 }
+/* The clickable trigger when the operation is switchable — a bare button
+   that keeps the same layout as the static row. */
+.velu-api-client__op-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  margin: 0;
+  padding: 0;
+  background: transparent;
+  border: 0;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
 .velu-api-client__op-label {
   font-weight: var(--weight-medium);
 }
@@ -281,6 +348,55 @@
   display: inline-flex;
   align-items: center;
   color: var(--muted-color);
+  transition: transform 0.15s ease;
+}
+.velu-api-client__op-btn[aria-expanded='true'] .velu-api-client__op-chevron {
+  transform: rotate(180deg);
+}
+
+/* Operation switcher menu — lists every operation in the tab. */
+.velu-api-client__op-menu {
+  position: absolute;
+  inset-block-start: calc(100% + var(--s-3));
+  inset-inline-start: 0;
+  z-index: 5;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin: 0;
+  padding: var(--s-3);
+  list-style: none;
+  min-inline-size: 16rem;
+  max-block-size: 18rem;
+  overflow-y: auto;
+  background: var(--page-bg);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: 0 12px 32px -12px rgba(0, 0, 0, 0.4);
+}
+.velu-api-client__op-item {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  inline-size: 100%;
+  padding: var(--s-3) var(--s-2);
+  background: transparent;
+  border: 0;
+  border-radius: var(--radius-sm);
+  color: var(--text-color);
+  font: inherit;
+  font-size: var(--f-h6);
+  text-align: start;
+  cursor: pointer;
+}
+.velu-api-client__op-item:hover,
+.velu-api-client__op-item--active {
+  background: var(--surface-color);
+}
+.velu-api-client__op-item-label {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
 /* Inside ApiClient the outer frame already supplies the box — strip

package/runtime/velu-ui/index.js

@@ -26,6 +26,8 @@ export { default as TryItBar } from './components/TryItBar.jsx';
 export { default as ApiField } from './components/ApiField.jsx';
 export { default as ApiClient } from './components/ApiClient.jsx';
 export { default as ApiSidebar } from './components/ApiSidebar.jsx';
+export { default as ApiReferencePage } from './components/ApiReferencePage.jsx';
+export { default as ApiSamples } from './components/ApiSamples.jsx';
 export { default as AskBar } from './components/AskBar.jsx';
 export { default as Chatbot } from './components/Chatbot.jsx';
 export { default as PageFeedback } from './components/PageFeedback.jsx';

package/runtime/velu-ui/lib/api-send.js

@@ -0,0 +1,92 @@
+// Build and send a "Try It" request from the playground field values.
+//
+// By default the request goes through the dev server's proxy
+// (/@velu-api-proxy) so it isn't blocked by CORS — the proxy forwards it
+// server-side and returns { status, statusText, headers, body }. Set the
+// project's api.playground.proxy to false to send straight from the browser.
+
+const PROXY_URL = '/@velu-api-proxy';
+const BODY_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+// Compose the concrete request (url + headers + body) from the operation and
+// the user-entered values: { auth, path, query, header } maps + bodyText.
+function buildRequest({ operation, server, values, bodyText }) {
+  const v = values || {};
+  let path = operation.path.replace(/\{([^}]+)\}/g, (m, name) => {
+    const val = v.path?.[name];
+    return val ? encodeURIComponent(val) : m; // leave {name} if unfilled
+  });
+
+  const query = Object.entries(v.query || {}).filter(([, val]) => val !== '' && val != null);
+  const qs = query.map(([k, val]) => `${encodeURIComponent(k)}=${encodeURIComponent(val)}`).join('&');
+  const base = (server || '').replace(/\/+$/, '');
+  const url = `${base}${path}${qs ? `?${qs}` : ''}`;
+
+  const headers = {};
+  for (const a of operation.auth || []) {
+    const val = v.auth?.[a.name];
+    if (val) headers[a.name] = a.prefix ? `${a.prefix} ${val}` : val;
+  }
+  for (const [k, val] of Object.entries(v.header || {})) {
+    if (val !== '' && val != null) headers[k] = val;
+  }
+
+  let body = null;
+  if (operation.body && BODY_METHODS.has(operation.method)) {
+    body = bodyText || '';
+    if (body && !headers['Content-Type']) headers['Content-Type'] = operation.body.contentType || 'application/json';
+  }
+
+  return { method: operation.method, url, headers, body };
+}
+
+async function readBody(res) {
+  const text = await res.text();
+  const ct = res.headers.get('content-type') || '';
+  if (/json/i.test(ct)) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      /* fall through to raw text */
+    }
+  }
+  return text;
+}
+
+export async function sendApiRequest({ operation, server, proxy = true, values, bodyText }) {
+  const req = buildRequest({ operation, server, values, bodyText });
+
+  if (proxy) {
+    const res = await fetch(PROXY_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(req),
+    });
+    // The proxy returns the upstream result as JSON.
+    const payload = await res.json().catch(() => ({}));
+    if (payload && payload.error) return { error: payload.error };
+    return {
+      status: payload.status,
+      statusText: payload.statusText || '',
+      headers: payload.headers || {},
+      body: payload.body,
+    };
+  }
+
+  // Direct browser fetch (subject to CORS).
+  const res = await fetch(req.url, {
+    method: req.method,
+    headers: req.headers,
+    body: req.body || undefined,
+  });
+  const headers = {};
+  res.headers.forEach((val, key) => {
+    headers[key] = val;
+  });
+  return {
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+    body: await readBody(res),
+  };
+}

package/runtime/velu-ui/styles.css

@@ -30,6 +30,7 @@
 @import './components/steps.css';
 @import './components/tree.css';
 @import './components/api.css';
+@import './components/api-page.css';
 @import './components/ask-bar.css';
 @import './components/chatbot.css';
 @import './components/page-feedback.css';

package/schema/velu.schema.json

@@ -40,6 +40,43 @@
       "type": "string",
       "description": "Path to the favicon, relative to the project root."
     },
+    "api": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "API reference behaviour for OpenAPI-generated pages.",
+      "properties": {
+        "server": {
+          "type": "string",
+          "description": "Base URL override for the playground + code samples (otherwise the spec's first server is used)."
+        },
+        "playground": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "display": {
+              "type": "string",
+              "enum": ["interactive", "simple", "none"],
+              "description": "Playground mode. \"none\" disables the proxy / live send."
+            },
+            "proxy": {
+              "type": "boolean",
+              "description": "Send Try-It requests through the dev proxy to avoid CORS (default true)."
+            }
+          }
+        },
+        "examples": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "languages": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["curl", "javascript", "python", "ruby"] },
+              "description": "Which request-snippet languages to generate."
+            }
+          }
+        }
+      }
+    },
     "logo": {
       "description": "Site logo shown in the header, replacing the name wordmark. A single path used in both themes, or per-theme light/dark images with an optional click-through href. Paths are relative to the project root.",
       "oneOf": [
@@ -205,6 +242,7 @@
         "icon": { "type": "string", "description": "lucide icon id." },
         "expanded": { "type": "boolean", "description": "Start expanded." },
         "root": { "type": "string", "description": "Landing page path for the group." },
+        "openapi": { "$ref": "#/$defs/openapiRef" },
         "pages": { "$ref": "#/$defs/pages" }
       }
     },
@@ -216,11 +254,19 @@
         "tab": { "type": "string", "description": "Tab label (top nav)." },
         "icon": { "type": "string" },
         "href": { "type": "string", "description": "External/override link instead of in-site pages." },
+        "openapi": { "$ref": "#/$defs/openapiRef" },
         "anchors": { "type": "array", "items": { "$ref": "#/$defs/anchor" } },
         "groups": { "type": "array", "items": { "$ref": "#/$defs/group" } },
         "pages": { "$ref": "#/$defs/pages" }
       }
     },
+    "openapiRef": {
+      "description": "Path or URL to an OpenAPI spec (JSON/YAML), or an array of them. Auto-generates a page per operation, grouped by tag.",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
     "anchor": {
       "type": "object",
       "additionalProperties": false,

package/src/navigation.js

@@ -186,9 +186,13 @@ function normalizeGroup(g) {
   };
 }
 
-/** A `pages[]` entry is either a string (page path) or a nested group. */
+/** A `pages[]` entry is a string (page path), a generated OpenAPI page
+ *  ({ apiPage, label, method }), or a nested group. */
 function normalizePageEntry(entry) {
   if (typeof entry === 'string') return { kind: 'page', pagePath: entry };
+  if (entry && entry.apiPage) {
+    return { kind: 'page', pagePath: entry.apiPage, label: entry.label, method: entry.method, api: true };
+  }
   return normalizeGroup(entry);
 }
 
@@ -430,5 +434,10 @@ function itemsFor(nodes, pagesMap, ctx) {
 function itemFor(pageNode, pagesMap, ctx) {
   const href = urlInCtx(pageNode.pagePath, ctx);
   const fm = pagesMap[href]?.frontmatter;
-  return { label: fm?.title ?? titleCase(lastSeg(href)), href };
+  // Generated API pages carry their own label + HTTP method (for the sidebar
+  // method badge); normal pages source their label from frontmatter.
+  const label = pageNode.label ?? fm?.title ?? titleCase(lastSeg(href));
+  const item = { label, href };
+  if (pageNode.method) item.method = pageNode.method;
+  return item;
 }

package/src/runtime/App.jsx

@@ -47,6 +47,7 @@ import {
   ApiClient,
   ApiField,
   ApiSidebar,
+  ApiSamples,
   VeluMark,
 } from 'velu-ui';
 import { X, ChevronDown, ChevronUp } from 'lucide-react';
@@ -1057,6 +1058,7 @@ function DocsPage() {
       data-chat-open={chatOpen ? 'true' : 'false'}
       data-sidebar-open={sidebarOpen ? 'true' : 'false'}
       data-drawer-open={drawerOpen ? 'true' : 'false'}
+      data-api={entry?.api ? 'true' : 'false'}
     >
       {/* Scrim — visible at mobile while the drawer OR the chatbot
           sheet is open. Sits between the article (z-0) and the
@@ -1263,11 +1265,27 @@ function DocsPage() {
                 scrollPaddingBlockEnd: 'var(--s1)',
               }}
             >
-              <Sidebar
-                sections={nav?.sidebarSections ?? []}
-                activeHref={pathname}
-                linkComponent={RouterLink}
-              />
+              {entry?.api ? (
+                <ApiSidebar
+                  sections={(nav?.sidebarSections ?? []).map((s) => ({
+                    title: s.title,
+                    icon: s.icon,
+                    endpoints: (s.items ?? []).map((it) => ({
+                      method: it.method,
+                      label: it.label,
+                      href: it.href,
+                    })),
+                  }))}
+                  activeHref={pathname}
+                  linkComponent={RouterLink}
+                />
+              ) : (
+                <Sidebar
+                  sections={nav?.sidebarSections ?? []}
+                  activeHref={pathname}
+                  linkComponent={RouterLink}
+                />
+              )}
             </div>
             <button
               type="button"
@@ -1317,7 +1335,16 @@ function DocsPage() {
             scrollPaddingBlockEnd: `calc(${footerOverlap}px + 2rem)`,
           }}
         >
-          <Toc items={toc} activeId={activeId} onSelect={scrollTo} />
+          {/* API reference pages put their code samples in the right rail
+              (where the TOC sits for normal pages). */}
+          {entry?.api && entry.operation ? (
+            <ApiSamples
+              samples={entry.samples}
+              responses={entry.operation.responses}
+            />
+          ) : (
+            <Toc items={toc} activeId={activeId} onSelect={scrollTo} />
+          )}
         </aside>
       )}
 

package/templates/starter/api-reference/introduction.mdx

@@ -1,28 +1,43 @@
 ---
 title: Introduction
-description: How to read this API reference.
+description: How this API reference is generated.
 ---
 
-This section documents the example API. Endpoints are grouped in the
-sidebar; each page shows the request, parameters, and a sample
-response.
+The endpoints in this tab are generated automatically from an OpenAPI
+spec (`openapi.json`). Each operation becomes its own page — with
+parameters, request body, and responses — and an interactive **Try It**
+playground you can use to send real requests.
 
 <Callout type="note">
   This is a second tab ("API Reference"). Tabs let you keep guides and
-  reference docs in separate top-level sections of the same site.
+  reference docs in separate top-level sections of the same site. Point
+  the tab's `openapi` field at your own spec to replace this example.
 </Callout>
 
-## Base URL
+## How it works
 
-```
-https://api.example.com/v1
+Add an `openapi` field to a tab (or group) in `velu.json`:
+
+```json
+{
+  "tab": "API Reference",
+  "openapi": "/openapi.json"
+}
 ```
 
-## Authentication
+Velu reads the spec, groups the operations by their tag, and renders a
+page per endpoint. No hand-written endpoint pages required.
 
-Send your key as a bearer token:
+## The example API
 
-```bash
-curl https://api.example.com/v1/items \
-  -H "Authorization: Bearer YOUR_TOKEN"
-```
+This starter points at a live demo API — a small **product catalog**
+backed by [dummyjson.com](https://dummyjson.com). Open any endpoint in
+the sidebar, hit **Try It**, and send a real request:
+
+- **Get a product** — try `id` = `1`
+- **Search products** — try `q` = `phone`
+- **Add a product** — the body is pre-filled; Send returns a created product
+
+Requests are routed through the dev server's proxy so they aren't blocked
+by CORS. Set `api.playground.proxy` to `false` to send straight from the
+browser.

package/templates/starter/openapi.json

@@ -0,0 +1,160 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Product Catalog API",
+    "version": "1.0.0",
+    "description": "A friendly, fully-hosted example API — a product catalog backed by the live https://dummyjson.com service. Every operation hits the real API: list, search, fetch, create, update and delete products and see real responses."
+  },
+  "servers": [{ "url": "https://dummyjson.com" }],
+  "tags": [{ "name": "Products", "description": "Browse and manage the product catalog." }],
+  "paths": {
+    "/products": {
+      "get": {
+        "operationId": "listProducts",
+        "summary": "List products",
+        "description": "List products, with optional pagination.",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "How many products to return (0 returns all)." },
+          { "name": "skip", "in": "query", "schema": { "type": "integer" }, "description": "How many products to skip (for pagination)." }
+        ],
+        "responses": {
+          "200": {
+            "description": "A page of products.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } }
+          }
+        }
+      }
+    },
+    "/products/search": {
+      "get": {
+        "operationId": "searchProducts",
+        "summary": "Search products",
+        "description": "Search the catalog by a free-text query.",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The search query (try `phone`)." }
+        ],
+        "responses": {
+          "200": {
+            "description": "Matching products.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } }
+          }
+        }
+      }
+    },
+    "/products/{id}": {
+      "get": {
+        "operationId": "getProduct",
+        "summary": "Get a product",
+        "description": "Retrieve a single product by its id.",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The product id (try `1`)." }
+        ],
+        "responses": {
+          "200": {
+            "description": "The product.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }
+          }
+        }
+      },
+      "put": {
+        "operationId": "updateProduct",
+        "summary": "Update a product",
+        "description": "Update fields on an existing product. (Simulated by the upstream API — the response reflects the change but nothing is persisted.)",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The product id." }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } }
+        },
+        "responses": {
+          "200": {
+            "description": "The updated product.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "deleteProduct",
+        "summary": "Delete a product",
+        "description": "Delete a product by its id. (Simulated — the response includes `isDeleted` and `deletedOn`.)",
+        "tags": ["Products"],
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The product id." }
+        ],
+        "responses": {
+          "200": {
+            "description": "The deleted product.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }
+          }
+        }
+      }
+    },
+    "/products/add": {
+      "post": {
+        "operationId": "addProduct",
+        "summary": "Add a product",
+        "description": "Create a new product. (Simulated — the response echoes the body with a fresh `id`.)",
+        "tags": ["Products"],
+        "requestBody": {
+          "required": true,
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } }
+        },
+        "responses": {
+          "201": {
+            "description": "The created product.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Product": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer", "description": "Unique identifier." },
+          "title": { "type": "string", "description": "Product name." },
+          "description": { "type": "string", "description": "Product description." },
+          "category": { "type": "string", "description": "Category slug." },
+          "price": { "type": "number", "description": "Price in USD." },
+          "discountPercentage": { "type": "number", "description": "Discount, as a percentage." },
+          "rating": { "type": "number", "description": "Average customer rating (0–5)." },
+          "stock": { "type": "integer", "description": "Units in stock." },
+          "brand": { "type": "string", "description": "Brand name." },
+          "thumbnail": { "type": "string", "description": "Thumbnail image URL." }
+        }
+      },
+      "ProductList": {
+        "type": "object",
+        "properties": {
+          "products": { "type": "array", "description": "The products on this page.", "items": { "$ref": "#/components/schemas/Product" } },
+          "total": { "type": "integer", "description": "Total number of matching products." },
+          "skip": { "type": "integer", "description": "How many were skipped." },
+          "limit": { "type": "integer", "description": "How many were returned." }
+        }
+      },
+      "ProductInput": {
+        "type": "object",
+        "required": ["title"],
+        "properties": {
+          "title": { "type": "string", "description": "Product name." },
+          "description": { "type": "string", "description": "Product description." },
+          "category": { "type": "string", "description": "Category slug." },
+          "price": { "type": "number", "description": "Price in USD." }
+        },
+        "example": {
+          "title": "Velu Notebook",
+          "description": "A dotted-grid notebook for docs notes.",
+          "category": "stationery",
+          "price": 19.99
+        }
+      }
+    }
+  }
+}

package/templates/starter/velu.json

@@ -23,11 +23,15 @@
       {
         "tab": "API Reference",
         "icon": "terminal",
+        "openapi": "/openapi.json",
         "groups": [
-          { "group": "API Documentation", "pages": ["api-reference/introduction"] },
-          { "group": "Endpoint Examples", "pages": ["api-reference/endpoint/get", "api-reference/endpoint/create"] }
+          { "group": "API Documentation", "pages": ["api-reference/introduction"] }
         ]
       }
     ]
+  },
+  "api": {
+    "playground": { "proxy": true },
+    "examples": { "languages": ["curl", "javascript", "python", "ruby"] }
   }
 }