@veluai/velu 0.1.14 → 0.1.16

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,157 @@
       "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": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "description": "Logo path used in both light and dark mode."
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["light", "dark"],
+          "properties": {
+            "light": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Logo shown in light mode."
+            },
+            "dark": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Logo shown in dark mode."
+            },
+            "href": {
+              "type": "string",
+              "description": "Where clicking the logo links. Defaults to the site root."
+            }
+          }
+        }
+      ]
+    },
+    "navbar": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The header's top-right area: secondary links plus a primary CTA button.",
+      "properties": {
+        "links": {
+          "type": "array",
+          "description": "Secondary header links (to the left of the primary CTA).",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["href"],
+            "properties": {
+              "label": { "type": "string", "description": "Link text." },
+              "href": { "type": "string", "description": "Link URL." },
+              "icon": { "type": "string", "description": "lucide icon id." }
+            }
+          }
+        },
+        "primary": {
+          "description": "The prominent CTA button at the far right.",
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["type", "label", "href"],
+              "properties": {
+                "type": { "const": "button" },
+                "label": { "type": "string", "description": "Button text." },
+                "href": { "type": "string", "description": "Button URL." }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["type", "href"],
+              "properties": {
+                "type": { "const": "github" },
+                "href": { "type": "string", "description": "GitHub repository URL." },
+                "label": { "type": "string", "description": "Button text (default \"GitHub\")." }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "footer": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Site footer. With `links`, a full footer section renders; with only `socials`, the icons sit next to the \"Powered by\" line instead.",
+      "properties": {
+        "socials": {
+          "type": "object",
+          "description": "Social links as platform → URL. Recognized icons: github, x (or twitter), youtube, linkedin.",
+          "additionalProperties": { "type": "string" }
+        },
+        "links": {
+          "type": "array",
+          "description": "Footer link columns (max 4).",
+          "maxItems": 4,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["header", "items"],
+            "properties": {
+              "header": { "type": "string", "description": "Column heading." },
+              "items": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["label", "href"],
+                  "properties": {
+                    "label": { "type": "string", "description": "Link text." },
+                    "href": { "type": "string", "description": "Link URL." }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "font": {
       "type": "object",
       "description": "Typography. Maps onto the --font-sans token in base.css.",
@@ -91,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" }
       }
     },
@@ -102,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

@@ -4,7 +4,7 @@ import { MDXProvider } from '@mdx-js/react';
 // The project's pages + navigation, generated from velu.json by
 // vite-plugin-velu-site (see src/vite-plugin-velu-site.js). `pages` is
 // url → { Component, frontmatter, toc } (or { missing:true }).
-import { pages, navigation } from 'virtual:velu-site';
+import { pages, navigation, site } from 'virtual:velu-site';
 import { resolve, normalizeUrl } from '../navigation.js';
 import {
   Stack,
@@ -38,6 +38,8 @@ import {
   defaultMdxComponents,
   resolveIcon,
   Search,
+  Logo,
+  SocialLinks,
   Tree,
   Folder,
   File,
@@ -45,6 +47,7 @@ import {
   ApiClient,
   ApiField,
   ApiSidebar,
+  ApiSamples,
   VeluMark,
 } from 'velu-ui';
 import { X, ChevronDown, ChevronUp } from 'lucide-react';
@@ -944,6 +947,35 @@ function DocsPage() {
     return () => scroller.removeEventListener('scroll', update);
   }, [pathname, chatOpen]);
 
+  // Footer config (from velu.json via virtual:velu-site). Link columns →
+  // full footer section; socials with no columns → inline next to PoweredBy.
+  const footerSocials = site.footer?.socials ?? [];
+  const footerHasLinks = (site.footer?.links?.length ?? 0) > 0;
+
+  // Header top-right actions, built from velu.json's `navbar`: secondary
+  // `links` (plain text links) then the `primary` CTA (a filled button, or an
+  // outlined GitHub button). Empty when unconfigured — no placeholder buttons.
+  const navActions = [];
+  for (const l of site.navbar?.links ?? []) {
+    navActions.push({
+      label: l.label,
+      href: l.href,
+      icon: l.icon || undefined,
+      kind: 'link',
+      external: l.external,
+    });
+  }
+  if (site.navbar?.primary) {
+    const p = site.navbar.primary;
+    navActions.push({
+      label: p.label,
+      href: p.href,
+      kind: p.kind === 'github' ? 'outlined' : 'primary',
+      icon: p.kind === 'github' ? 'github' : undefined,
+      external: p.external,
+    });
+  }
+
   const footerRef = React.useRef(null);
   const [footerOverlap, setFooterOverlap] = React.useState(0);
   React.useEffect(() => {
@@ -1026,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
@@ -1043,7 +1076,11 @@ function DocsPage() {
           tabs row. Configurable: pass any number of actions / tabs. */}
       <PageHeader
         linkComponent={RouterLink}
-        brand={{ label: 'Velu', href: '/' }}
+        brand={{
+          label: site.name,
+          href: site.logo?.href || '/',
+          logo: site.logo,
+        }}
         brandTrailing={
           versionSwitcher && (
             <span className="velu-hide-on-mobile">{versionSwitcher}</span>
@@ -1069,13 +1106,7 @@ function DocsPage() {
             )}
           </Cluster>
         }
-        actions={[
-          {
-            label: 'Book Demo',
-            kind: 'primary',
-            href: '#',
-          },
-        ]}
+        actions={navActions}
         trailing={<ThemeToggle />}
         onMenuClick={() => setDrawerOpen((v) => !v)}
         breadcrumb={nav?.breadcrumb ?? []}
@@ -1111,8 +1142,14 @@ function DocsPage() {
               href="/"
               className="velu-docs-layout__drawer-brand"
             >
-              <VeluMark />
-              <span className="velu-header__wordmark">Velu</span>
+              {site.logo ? (
+                <Logo logo={site.logo} alt={site.name} />
+              ) : (
+                <>
+                  <VeluMark />
+                  <span className="velu-header__wordmark">{site.name}</span>
+                </>
+              )}
             </RouterLink>
             <ThemeToggle />
             <button
@@ -1228,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"
@@ -1282,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>
       )}
 
@@ -1417,59 +1479,40 @@ function DocsPage() {
               }}
             />
           )}
-          {/* "Powered by Velu" attribution — bottom-right of the
-              article column, just under the AskBar. Muted so it reads
-              as a footer-of-content note, not a brand statement. */}
-          <PoweredBy />
+          {/* Content foot — "Powered by Velu" at the bottom-right of the
+              article column. When the footer has no link columns, the
+              configured social icons sit on the LEFT of this same row (no
+              full footer section); with link columns they live in the full
+              footer below instead. */}
+          {footerHasLinks ? (
+            <PoweredBy />
+          ) : (
+            <div className="velu-content-foot">
+              <SocialLinks socials={footerSocials} />
+              <PoweredBy />
+            </div>
+          )}
         </div>
       </main>
       </div>
 
-      {/* Site footer — spans full width below the article. Its raised
-          z-index ensures it visually eclipses the bottoms of the fixed
-          left sidebar and right TOC as the page scrolls into it. The
-          ref is watched so the asides can pad their bottom by the same
-          overlap amount, keeping every item scrollable into view. */}
-      <div
-        ref={footerRef}
-        data-velu-footer
-        style={{ position: 'relative', zIndex: 20 }}
-      >
-      <PageFooter
-        brand={{ href: '#' }}
-        columns={[
-          {
-            title: 'Resources',
-            items: [
-              { label: 'Showcase', href: '#' },
-              { label: 'Enterprise', href: '#' },
-              { label: 'Status', href: '#' },
-            ],
-          },
-          {
-            title: 'Company',
-            items: [
-              { label: 'Careers', href: '#' },
-              { label: 'Blog', href: '#' },
-              { label: 'Community', href: '#' },
-            ],
-          },
-          {
-            title: 'Policies',
-            items: [
-              { label: 'Subprocessors', href: '#' },
-              { label: 'Terms of Service', href: '#' },
-            ],
-          },
-        ]}
-        socials={[
-          { kind: 'github', href: 'https://github.com/aravindc26/velu-cli' },
-          { kind: 'x', href: 'https://x.com/' },
-          { kind: 'youtube', href: 'https://youtube.com/' },
-          { kind: 'linkedin', href: 'https://linkedin.com/' },
-        ]}
-      />
-      </div>
+      {/* Full site footer — only when the config provides link columns. Spans
+          full width below the article; its raised z-index eclipses the bottoms
+          of the fixed sidebar and TOC as the page scrolls into it, and the ref
+          is watched so the asides can pad their bottom by the overlap. */}
+      {footerHasLinks && (
+        <div
+          ref={footerRef}
+          data-velu-footer
+          style={{ position: 'relative', zIndex: 20 }}
+        >
+          <PageFooter
+            brand={{ href: site.logo?.href || '/' }}
+            columns={site.footer.links}
+            socials={footerSocials}
+          />
+        </div>
+      )}
 
       {/* Ask-AI chatbot — slides in from the inline-end edge. */}
       <Chatbot

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.