@veluai/velu 0.2.36 → 0.2.38

package/src/runtime/App.jsx

@@ -1,4 +1,5 @@
 import React from 'react';
+import VepaToc from './VepaToc.jsx';
 import { Routes, Route, useLocation, useNavigate, Link } from 'react-router-dom';
 import { MDXProvider } from '@mdx-js/react';
 // The project's pages + navigation, generated from velu.json by
@@ -6,6 +7,7 @@ import { MDXProvider } from '@mdx-js/react';
 // url → { Component, frontmatter, toc } (or { missing:true }).
 import { pages, navigation, site } from 'virtual:velu-site';
 import { resolve, normalizeUrl } from '../navigation.js';
+import { resolvePageMode, pageModeChrome } from './page-mode.js';
 import {
   Stack,
   Cluster,
@@ -53,6 +55,7 @@ import {
   ApiField,
   ApiSidebar,
   ApiSamples,
+  ApiReferencePage,
   NotFound,
   VeluMark,
 } from 'velu-ui';
@@ -691,7 +694,7 @@ const RouterLink = ({ href, ...rest }) => <Link to={href} {...rest} />;
 // place.
 function sectionById(id) {
   if (typeof document === 'undefined' || !id) return null;
-  const article = document.getElementById('content');
+  const article = document.querySelector('.velu-docs-layout__article');
   const esc = id.replace(/["\\]/g, '\\$&');
   return article?.querySelector(`[id="${esc}"]`) ?? document.getElementById(id);
 }
@@ -855,6 +858,10 @@ function DocsPage() {
   // No renderable page for this route → show the 404 page (a clean centered
   // takeover: header + footer stay, the docs sidebar/TOC are hidden).
   const isNotFound = !PageComponent;
+  // Mintlify-compatible page layout (`mode` in MDX frontmatter). Unknown
+  // values fall back to the standard sidebar + TOC + footer chrome.
+  const chrome = pageModeChrome(resolvePageMode(frontmatter));
+  const assistantUnavailable = chrome.assistant && !IS_DEV_PREVIEW && (!assistant || askAiHidden);
 
   // Switcher option sets (only render a switcher when an axis has >1
   // option). Anchors are pinned sidebar links shown in the context zone.
@@ -921,8 +928,9 @@ function DocsPage() {
   // against it like any other heading.
   const pageId = React.useMemo(() => {
     if (!frontmatter.title) return null;
+    if (site.theme === 'vepa') return 'page-title';
     return new GithubSlugger().slug(frontmatter.title);
-  }, [frontmatter.title]);
+  }, [frontmatter.title, site.theme]);
 
   // Combined TOC: the frontmatter title is the page's top-level entry,
   // and the MDX-derived headings (h2s) become its children. Without this,
@@ -1058,7 +1066,11 @@ function DocsPage() {
     const tocBarToggle = document.querySelector('.velu-toc-bar__toggle');
     if (tocBarToggle) ro.observe(tocBarToggle);
     return () => ro.disconnect();
-  }, []);
+    // Re-run when page mode changes: custom/assistant drop the tabs
+    // row and shrink the header. A mount-only observer can leave
+    // --velu-header-height at the two-row 7rem default, which leaves
+    // a gap above the full-page Ask AI canvas.
+  }, [chrome.mode]);
 
   // The asides (left sidebar + right TOC) scroll independently of the
   // page. On scroll/resize we set data-fade-top/-bottom on each scroll
@@ -1183,14 +1195,22 @@ function DocsPage() {
     });
   }
 
-  const footerRef = React.useRef(null);
+  // Callback ref so this rebinds when the footer mounts/unmounts.
+  // Custom and assistant unmount the footer; a mount-once listener
+  // would keep reading the detached node (getBoundingClientRect top
+  // is 0) and treat the footer as covering the full viewport, which
+  // crushes the fixed sidebar via --velu-aside-bottom.
+  const [footerEl, setFooterEl] = React.useState(null);
   const [footerOverlap, setFooterOverlap] = React.useState(0);
   React.useEffect(() => {
-    const node = footerRef.current;
-    if (!node) return;
+    if (!footerEl) {
+      setFooterOverlap(0);
+      return undefined;
+    }
     const update = () => {
-      const rect = node.getBoundingClientRect();
-      setFooterOverlap(Math.max(0, window.innerHeight - rect.top));
+      const rect = footerEl.getBoundingClientRect();
+      const visible = Math.max(0, window.innerHeight - rect.top);
+      setFooterOverlap(Math.min(visible, footerEl.offsetHeight));
     };
     update();
     window.addEventListener('scroll', update, { passive: true });
@@ -1199,15 +1219,17 @@ function DocsPage() {
       window.removeEventListener('scroll', update);
       window.removeEventListener('resize', update);
     };
-  }, []);
+  }, [footerEl]);
 
   // Sticky AskBar fades out once the user scrolls near the PageFeedback
   // widget — so it doesn't sit on top of the page-foot widgets.
-  const feedbackRef = React.useRef(null);
+  const [feedbackEl, setFeedbackEl] = React.useState(null);
   const [askBarHidden, setAskBarHidden] = React.useState(false);
   React.useEffect(() => {
-    const node = feedbackRef.current;
-    if (!node) return;
+    if (!feedbackEl) {
+      setAskBarHidden(false);
+      return undefined;
+    }
     const FADE_BUFFER = 64; // matches the rootMargin below
     const apply = (rect) => {
       // Hide whenever the feedback's top has reached the (effective)
@@ -1217,16 +1239,16 @@ function DocsPage() {
       // exactly at the same line in both scroll directions.
       setAskBarHidden(rect.top < window.innerHeight - FADE_BUFFER);
     };
-    apply(node.getBoundingClientRect());
+    apply(feedbackEl.getBoundingClientRect());
     const io = new IntersectionObserver(
       ([entry]) => apply(entry.boundingClientRect),
       // Trigger ~64px before the feedback enters the viewport, so the
       // AskBar fades just as the widget starts to peek up from below.
       { rootMargin: '0px 0px -64px 0px' },
     );
-    io.observe(node);
+    io.observe(feedbackEl);
     return () => io.disconnect();
-  }, []);
+  }, [feedbackEl]);
 
   const scrollTo = React.useCallback(
     (id) => {
@@ -1263,11 +1285,13 @@ function DocsPage() {
     <div
       id="body-content"
       className="velu-docs-layout"
-      data-chat-open={chatOpen ? 'true' : 'false'}
+      data-site-theme={site.theme ?? 'velu'}
+      data-chat-open={chatOpen && !chrome.assistant ? 'true' : 'false'}
       data-sidebar-open={sidebarOpen ? 'true' : 'false'}
       data-drawer-open={drawerOpen ? 'true' : 'false'}
       data-api={entry?.api ? 'true' : 'false'}
       data-not-found={isNotFound ? 'true' : undefined}
+      data-page-mode={isNotFound ? undefined : chrome.mode}
     >
       {/* Scrim — visible at mobile while the drawer OR the chatbot
           sheet is open. Sits between the article (z-0) and the
@@ -1284,6 +1308,7 @@ function DocsPage() {
       {/* Site header — brand, centered search, right-side actions,
           tabs row. Configurable: pass any number of actions / tabs. */}
       <PageHeader
+        preset={site.theme}
         id="navbar"
         linkComponent={RouterLink}
         brand={{
@@ -1296,7 +1321,6 @@ function DocsPage() {
             <span className="velu-hide-on-mobile">{versionSwitcher}</span>
           )
         }
-        tabsTrailing={languageSwitcher || undefined}
         center={
           <Cluster space="var(--s-6)" align="center">
             <Search
@@ -1309,7 +1333,7 @@ function DocsPage() {
             {/* Ask AI talks to the deployed site's AI backend — hidden in
                 the local dev preview where there's nothing to talk to, and
                 when the owner's plan/credits disable the assistant. */}
-            {!IS_DEV_PREVIEW && !askAiHidden && (
+            {!IS_DEV_PREVIEW && !askAiHidden && !chrome.assistant && (
               <button
                 type="button"
                 id="assistant-entry"
@@ -1325,11 +1349,24 @@ function DocsPage() {
           </Cluster>
         }
         actions={navActions}
-        trailing={<ThemeToggle />}
-        onMenuClick={() => setDrawerOpen((v) => !v)}
-        breadcrumb={nav?.breadcrumb ?? []}
+        trailing={<ThemeToggle variant={site.theme === 'vepa' ? 'menu' : undefined} />}
+        tabsTrailing={
+          chrome.mode === 'custom' || chrome.mode === 'assistant'
+            ? undefined
+            : languageSwitcher || undefined
+        }
+        onMenuClick={chrome.sidebar ? () => setDrawerOpen((v) => !v) : undefined}
+        breadcrumb={
+          chrome.mode === 'custom' || chrome.mode === 'assistant'
+            ? []
+            : (nav?.breadcrumb ?? [])
+        }
         activeTab={nav?.activeTab}
-        tabs={nav?.tabs ?? []}
+        tabs={
+          chrome.mode === 'custom' || chrome.mode === 'assistant'
+            ? []
+            : (nav?.tabs ?? [])
+        }
       />
 
       {/* Fixed left sidebar — pinned to viewport-left below the header.
@@ -1339,7 +1376,7 @@ function DocsPage() {
           honour `inset-block-start` for fixed positioning the same way
           as plain `top`). */}
       <aside
-        id="sidebar"
+        id={site.theme === 'vepa' ? 'sidebar-content' : 'sidebar'}
         className="velu-docs-layout__aside velu-docs-layout__aside--left"
         style={{
           /* Bottom edge stays a fixed gap above the viewport bottom,
@@ -1380,7 +1417,7 @@ function DocsPage() {
                 </>
               )}
             </RouterLink>
-            <ThemeToggle />
+            <ThemeToggle variant={site.theme === 'vepa' ? 'menu' : undefined} />
             <button
               type="button"
               className="velu-docs-layout__drawer-close"
@@ -1393,7 +1430,9 @@ function DocsPage() {
           {/* Nav dropdown — custom button + menu, fills drawer width.
               Items mirror the desktop tabs (Home / Docs / Blog).
               Click-outside + Escape close (see navOpen useEffect
-              above). Chevron rotates 180° on open. */}
+              above). Chevron rotates 180° on open. Shown only when
+              there is more than one tab to switch between. */}
+          {navItems.length > 1 && (
           <div
             ref={navRef}
             className="velu-docs-layout__drawer-docselect"
@@ -1437,6 +1476,7 @@ function DocsPage() {
               ))}
             </ul>
           </div>
+          )}
           {/* Context zone — product switcher + anchors at the top of
               the sidebar (all breakpoints), plus version/language
               switchers that only show on mobile (desktop has them in
@@ -1493,7 +1533,7 @@ function DocsPage() {
               nav fully to that end. */}
           <div className="velu-docs-nav-region">
             <div
-              id="sidebar-content"
+              id={site.theme === 'vepa' ? 'navigation-items' : 'sidebar-content'}
               ref={leftAsideRef}
               className="velu-docs-nav-scroll velu-hide-scrollbar"
               style={{
@@ -1561,8 +1601,9 @@ function DocsPage() {
           display:none snap. See docs-layout.css. */}
 
       {/* Fixed right TOC — pinned to viewport-right. Hidden while the
-          Ask-AI chatbot is open (the panel takes that edge). */}
-      {!chatOpen && (
+          Ask-AI chatbot is open (the panel takes that edge). Wide /
+          custom / frame / center / assistant hide this rail. */}
+      {!chatOpen && chrome.toc && (
         <aside
           id="table-of-contents"
           ref={rightAsideRef}
@@ -1578,11 +1619,20 @@ function DocsPage() {
               (where the TOC sits for normal pages). */}
           {entry?.api && entry.operation ? (
             <ApiSamples
+              preset={site.theme}
+              title={frontmatter.title}
               samples={entry.samples}
               responses={entry.operation.responses}
             />
-          ) : isChangelog && changelogTags.length ? (
+          ) : isChangelog && changelogTags.length && site.theme !== 'vepa' ? (
             <ChangelogFilters tags={changelogTags} />
+          ) : site.theme === 'vepa' ? (
+            <>
+              {isChangelog && changelogTags.length > 0 ? (
+                <ChangelogFilters tags={changelogTags} />
+              ) : null}
+              <VepaToc items={pageToc} activeId={activeId} onSelect={scrollTo} />
+            </>
           ) : (
             <Toc id="table-of-contents-content" items={toc} activeId={activeId} onSelect={scrollTo} />
           )}
@@ -1607,7 +1657,14 @@ function DocsPage() {
               onAskAI={IS_DEV_PREVIEW || askAiHidden ? undefined : () => askAI('')}
             />
           </main>
-        ) : (
+        ) : chrome.assistant && assistantUnavailable ? (
+          <main className="velu-assistant-disabled">
+            <Search
+              unavailable
+              unavailableMessage="Ask AI is not enabled on this site."
+            />
+          </main>
+        ) : chrome.assistant ? null : (
         <>
         {/* Narrow-layout TOC bar — always in DOM, only visible at
             < 1024px (toggled by @container in toc-bar.css). Shares
@@ -1616,8 +1673,11 @@ function DocsPage() {
             data; whichever one is visible at a given width responds
             to the same scroll-spy state. */}
         {/* Changelog tag filters are a wide-layout (right-rail) affordance only;
-            on tab/mobile we keep the normal TOC bar (no filters). */}
+            on tab/mobile we keep the normal TOC bar (no filters). Hidden
+            entirely when the page mode has no table of contents. */}
+        {chrome.toc && (
         <TocBar items={toc} activeId={activeId} onSelect={scrollTo} />
+        )}
       <main
         id="content-area"
         className="velu-docs-layout__main"
@@ -1641,6 +1701,7 @@ function DocsPage() {
             column, and therefore sits BELOW the TocBar rather than
             overlapping it. Chevron flips direction with the
             `data-sidebar-open` data attribute on the layout root. */}
+        {chrome.sidebar && (
         <button
           type="button"
           className="velu-docs-layout__sidebar-toggle"
@@ -1654,11 +1715,13 @@ function DocsPage() {
             })}
           </span>
         </button>
-        <div id="content" className="velu-docs-layout__article" data-pagefind-body="">
+        )}
+        <div id={site.theme === 'vepa' ? undefined : 'content'} data-contextual-actions={site.contextual?.options?.length ? 'true' : 'false'} className="velu-docs-layout__article" data-pagefind-body={chrome.assistant ? undefined : ""}>
           {/* Per-page agent/IDE action bar: the section eyebrow + a
               "Copy Page" split-button whose dropdown is driven by the
               Mintlify-compatible `contextual` config. Renders nothing
               when there's neither an eyebrow nor any enabled options. */}
+          {chrome.articleChrome && (
           <ContextMenu
             eyebrow={
               nav?.breadcrumb && nav.breadcrumb.length > 1
@@ -1675,13 +1738,15 @@ function DocsPage() {
             getMarkdown={entry?.getSource}
             rssHref={isChangelog ? `${BASE_PATH}/rss.xml` : undefined}
           />
+          )}
 
           {/* Page hero from MDX frontmatter. `.velu-hero` rules
               (in base.css) keep the title and description tightly
-              grouped and create a clear break before the prose body. */}
-          {(frontmatter.title || frontmatter.description) && (
+              grouped and create a clear break before the prose body.
+              Custom / frame / assistant are a blank canvas — no auto hero. */}
+          {chrome.hero && (frontmatter.title || frontmatter.description) && (
             <div className="velu-hero">
-              {frontmatter.title && <h1 id={pageId}>{frontmatter.title}</h1>}
+              {frontmatter.title && <h1 id={site.theme === 'vepa' ? 'page-title' : pageId}>{frontmatter.title}</h1>}
               {frontmatter.description && (
                 <p
                   style={{
@@ -1702,10 +1767,10 @@ function DocsPage() {
               level. Falls back to a not-found / missing-file notice
               when the route has no page (or its file is absent). */}
           <MDXProvider components={defaultMdxComponents}>
-            <mdx-content class="velu-prose">
+            <mdx-content key={site.theme === 'vepa' ? pathname : undefined} id={site.theme === 'vepa' && !entry?.api ? 'content' : undefined} class="velu-prose">
               {PageComponent ? (
                 <ErrorBoundary key={pathname} file={entry?.relPath}>
-                  <PageComponent />
+                  {entry?.mdxApi ? <ApiReferencePage {...entry.mdxApi} preset={site.theme}><PageComponent /></ApiReferencePage> : <PageComponent />}
                 </ErrorBoundary>
               ) : (
                 <p style={{ color: 'var(--muted-color)' }}>
@@ -1718,7 +1783,8 @@ function DocsPage() {
           </MDXProvider>
           {/* Page-foot feedback widget — ref'd so the sticky AskBar
               above can hide as the user scrolls near it. */}
-          <div ref={feedbackRef} style={{ marginTop: 'var(--s3)' }}>
+          {chrome.articleChrome && (
+          <div ref={setFeedbackEl} style={{ marginTop: 'var(--s3)' }}>
             {/* key resets the widget's vote state on page change. "Yes"
                 submits immediately; "No" submits once its form is sent.
                 Handlers are no-ops in the dev preview (pageFeedback null). */}
@@ -1732,9 +1798,10 @@ function DocsPage() {
               }
             />
           </div>
+          )}
           {/* Previous / next page navigation — derived from the
               sidebar reading order of the active section. */}
-          {(nav?.prev || nav?.next) && (
+          {chrome.articleChrome && !frontmatter.hidePagination && (nav?.prev || nav?.next) && (
             <PageNav
               id="pagination"
               style={{ marginTop: 'var(--s2)' }}
@@ -1750,7 +1817,7 @@ function DocsPage() {
               approaches (see IntersectionObserver above). */}
           {/* Ask-a-question bar — opens the AI chatbot, which runs on the
               deployed site. Hidden in the local dev preview. */}
-          {!IS_DEV_PREVIEW && !chatOpen && !askAiHidden && (
+          {!IS_DEV_PREVIEW && !chatOpen && !askAiHidden && chrome.articleChrome && (
             <AskBar
               onSubmit={askAI}
               style={{
@@ -1776,14 +1843,14 @@ function DocsPage() {
               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 />
+          {chrome.articleChrome && (footerHasLinks ? (
+            site.theme === 'vepa' ? null : <PoweredBy />
           ) : (
             <div className="velu-content-foot">
               <SocialLinks socials={footerSocials} />
               <PoweredBy />
             </div>
-          )}
+          ))}
         </div>
       </main>
         </>
@@ -1794,15 +1861,16 @@ function DocsPage() {
           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 && (
+      {footerHasLinks && chrome.footer && (
         <advanced-footer
-          id="footer"
-          ref={footerRef}
+          id={site.theme === 'vepa' ? undefined : 'footer'}
+          ref={setFooterEl}
           data-velu-footer
           style={{ position: 'relative', zIndex: 20 }}
         >
           <PageFooter
-            brand={{ href: site.logo?.href || '/' }}
+            preset={site.theme}
+            brand={{ label: site.name, logo: site.logo, href: site.logo?.href || '/' }}
             columns={site.footer.links}
             socials={footerSocials}
           />
@@ -1811,11 +1879,12 @@ function DocsPage() {
 
       {/* Ask-AI chatbot — slides in from the inline-end edge. Hidden when the
           docs owner's plan/credits disable Ask-AI. */}
-      {!askAiHidden && (
+      {!askAiHidden && (!chrome.assistant || !assistantUnavailable) && (
       <Chatbot
-        open={chatOpen}
+        open={chrome.assistant || chatOpen}
+        layout={chrome.assistant ? 'page' : 'panel'}
         seedQuestion={chatQuestion}
-        onClose={() => setChatOpen(false)}
+        onClose={chrome.assistant ? undefined : () => setChatOpen(false)}
         ask={assistant?.ask}
         onFeedback={assistant?.sendFeedback}
         listHistory={assistant?.listConversations}
@@ -1838,6 +1907,7 @@ function DocsPage() {
           // behind the sheet. Desktop keeps the panel open so multi-cite hops
           // stay convenient.
           if (
+            !chrome.assistant &&
             typeof window !== 'undefined' &&
             window.matchMedia('(max-width: 1024px)').matches
           ) {

package/src/runtime/VepaToc.jsx

@@ -0,0 +1,12 @@
+import React from 'react';
+
+export default function VepaToc({ items, activeId, onSelect }) {
+  const render = (entries) => <ul>{entries.map((item) => <li key={item.id}>
+    <a href={`#${item.id}`} aria-current={activeId === item.id ? 'location' : undefined} onClick={(e) => { e.preventDefault(); onSelect(item.id); }}>{item.label}</a>
+    {item.children?.length > 0 && render(item.children)}
+  </li>)}</ul>;
+  return <nav className="velu-vepa-toc" aria-label="On this page">
+    <button type="button" onClick={() => window.scrollTo({ top: 0, behavior: 'smooth' })}>On this page</button>
+    {render(items)}
+  </nav>;
+}

package/src/runtime/page-mode.js

@@ -0,0 +1,54 @@
+// Page layout modes — Mintlify-compatible `mode` frontmatter.
+// Unknown / missing values fall back to the standard docs chrome.
+
+export const PAGE_MODES = [
+  'default',
+  'wide',
+  'custom',
+  'frame',
+  'center',
+  'assistant',
+];
+
+/**
+ * @param {Record<string, unknown>} [frontmatter]
+ * @returns {'default' | 'wide' | 'custom' | 'frame' | 'center' | 'assistant'}
+ */
+export function resolvePageMode(frontmatter = {}) {
+  const raw = String(frontmatter.mode ?? 'default').trim().toLowerCase();
+  return PAGE_MODES.includes(raw) ? raw : 'default';
+}
+
+/**
+ * Which chrome pieces a mode shows. Used by the docs runtime; CSS also
+ * keys off `data-page-mode` for the corresponding layout (aside margins,
+ * article measure).
+ *
+ *   default   — sidebar + TOC + footer (standard docs page)
+ *   wide      — sidebar + footer; no TOC panel; keeps the right gutter
+ *   custom    — no sidebar/TOC/footer; centered landing canvas
+ *   frame     — custom canvas + sidebar (no TOC)
+ *   center    — no sidebar/TOC; centered reading (changelogs)
+ *   assistant — navbar + full-page Ask AI chat
+ *
+ * @param {string} mode
+ */
+export function pageModeChrome(mode) {
+  const m = PAGE_MODES.includes(mode) ? mode : 'default';
+  const sidebar = m === 'default' || m === 'wide' || m === 'frame';
+  const toc = m === 'default';
+  const footer = m === 'default' || m === 'wide' || m === 'frame' || m === 'center';
+  const hero = m === 'default' || m === 'wide' || m === 'center';
+  return {
+    mode: m,
+    sidebar,
+    toc,
+    footer,
+    hero,
+    // Context menu, feedback, prev/next, AskBar, powered-by — the
+    // docs-page chrome around the MDX body. Custom/frame are a canvas;
+    // assistant replaces the body with chat.
+    articleChrome: hero,
+    assistant: m === 'assistant',
+  };
+}

package/templates/starter/essentials/settings.mdx

@@ -28,3 +28,18 @@ applied as the body font.
   `favicon` is a path relative to your project root, e.g.
   `/favicon.svg`.
 </Callout>
+
+## Page layout
+
+Set `mode` in a page's frontmatter to change its chrome. `default` is a
+sidebar plus table of contents; `wide` drops the right panel; `custom` is
+navbar-only; `frame` keeps the sidebar on a custom canvas; `center` is for
+changelogs; `assistant` is a full-page Ask AI chat.
+
+```mdx
+---
+title: "Changelog"
+mode: "center"
+---
+```
+