@veluai/velu 0.2.35 → 0.2.36

package/runtime/velu-ui/styles.css

@@ -1,9 +1,18 @@
 /* Aggregate stylesheet for velu-ui. Consumers import this once.
 
-   Tailwind v4 first (theme/preflight/utilities — all in @layer).
-   base.css is intentionally UNLAYERED, so it wins over Tailwind's
-   preflight `base` layer — our fluid type/measure beat Tailwind's reset
-   by cascade-layer precedence (unlayered > layered). */
+   Cascade layers, lowest to highest precedence:
+     Tailwind's theme / base (preflight) / components / utilities
+     velu   - everything in this package (base.css + every component sheet)
+     (unlayered) - the PROJECT's own custom CSS (any .css file in a docs
+                   project is linked after this sheet, unlayered)
+   Unlayered styles beat every layer regardless of specificity, so a project
+   can restyle components with Mintlify-style element selectors - a plain
+   `card { border-radius: 0 }` (specificity 0,0,1) overrides `.velu-card`
+   (0,1,0) because velu-ui lives in a layer and the project sheet does not.
+   The `velu` layer is declared after Tailwind's, so our fluid type/measure
+   still beat Tailwind's preflight, as before. */
+@layer theme, base, components, utilities, velu;
+
 @import 'tailwindcss';
 
 /* Map Tailwind's `dark:` variant onto our [data-theme="dark"] attribute
@@ -14,36 +23,43 @@
    and ignores node_modules — velu-ui is reached via a workspace symlink
    there, so its component classes would NOT be scanned. This @source is
    relative to THIS file (packages/velu-ui/src/styles.css); "." == the
-   velu-ui src tree, so Tailwind also scans velu-ui components. */
+   velu-ui src tree, so Tailwind also scans velu-ui components.
+
+   Project MDX/JSX (the docs author's content) is registered as an extra
+   `@source` at `velu dev` / `velu build` time by
+   `veluTailwindProjectSource` in velu-cli — so utilities used in content
+   (`w-full`, `rounded-xl`, `dark:…`, …) are generated too. */
 @source ".";
 
-@import './base.css';
-@import './primitives/switcher.css';
-@import './components/sidebar.css';
-@import './components/nav-select.css';
-@import './components/context-menu.css';
-@import './components/accordion.css';
-@import './components/card.css';
-@import './components/icon.css';
-@import './components/image.css';
-@import './components/code-block.css';
-@import './components/field.css';
-@import './components/prompt.css';
-@import './components/steps.css';
-@import './components/tree.css';
-@import './components/update.css';
-@import './components/changelog-filters.css';
-@import './components/api.css';
-@import './components/api-page.css';
-@import './components/not-found.css';
-@import './components/ask-bar.css';
-@import './components/chatbot.css';
-@import './components/page-feedback.css';
-@import './components/page-nav.css';
-@import './components/page-footer.css';
-@import './components/powered-by.css';
-@import './components/page-header.css';
-@import './components/theme-toggle.css';
-@import './components/docs-layout.css';
-@import './components/toc-bar.css';
-@import './components/search.css';
+@import './base.css' layer(velu);
+@import './element-selectors.css' layer(velu);
+@import './primitives/switcher.css' layer(velu);
+@import './components/sidebar.css' layer(velu);
+@import './components/nav-select.css' layer(velu);
+@import './components/context-menu.css' layer(velu);
+@import './components/accordion.css' layer(velu);
+@import './components/callout.css' layer(velu);
+@import './components/card.css' layer(velu);
+@import './components/icon.css' layer(velu);
+@import './components/image.css' layer(velu);
+@import './components/code-block.css' layer(velu);
+@import './components/field.css' layer(velu);
+@import './components/prompt.css' layer(velu);
+@import './components/steps.css' layer(velu);
+@import './components/tree.css' layer(velu);
+@import './components/update.css' layer(velu);
+@import './components/changelog-filters.css' layer(velu);
+@import './components/api.css' layer(velu);
+@import './components/api-page.css' layer(velu);
+@import './components/not-found.css' layer(velu);
+@import './components/ask-bar.css' layer(velu);
+@import './components/chatbot.css' layer(velu);
+@import './components/page-feedback.css' layer(velu);
+@import './components/page-nav.css' layer(velu);
+@import './components/page-footer.css' layer(velu);
+@import './components/powered-by.css' layer(velu);
+@import './components/page-header.css' layer(velu);
+@import './components/theme-toggle.css' layer(velu);
+@import './components/docs-layout.css' layer(velu);
+@import './components/toc-bar.css' layer(velu);
+@import './components/search.css' layer(velu);

package/src/runtime/App.jsx

@@ -683,6 +683,19 @@ function ImageDemo() {
 
 const RouterLink = ({ href, ...rest }) => <Link to={href} {...rest} />;
 
+// Look up a heading by its slug id. Prefers a match INSIDE the article: the
+// layout chrome carries stable, Mintlify-compatible ids for custom CSS
+// (#sidebar, #content, #footer, …), and a heading titled "Sidebar" or "Footer"
+// would slug to the same id — document.getElementById would then return the
+// chrome element (earlier in DOM order) and the TOC would scroll to the wrong
+// place.
+function sectionById(id) {
+  if (typeof document === 'undefined' || !id) return null;
+  const article = document.getElementById('content');
+  const esc = id.replace(/["\\]/g, '\\$&');
+  return article?.querySelector(`[id="${esc}"]`) ?? document.getElementById(id);
+}
+
 // Flatten a nested TOC tree to {id, label, depth} for scroll-spy.
 function flat(nodes, depth = 0, out = []) {
   for (const n of nodes) {
@@ -730,7 +743,7 @@ function useScrollSpy(ids) {
       let best = ids[0];
       let bestDist = Infinity;
       for (const id of ids) {
-        const node = document.getElementById(id);
+        const node = sectionById(id);
         if (!node) continue;
         const top = node.getBoundingClientRect().top;
         if (top >= vh) continue;
@@ -867,6 +880,7 @@ function DocsPage() {
       options={languageOptions}
       linkComponent={RouterLink}
       ariaLabel="Language"
+      idPrefix="localization-select"
     />
   );
   const productSwitcher = productOptions.length > 1 && (
@@ -875,6 +889,7 @@ function DocsPage() {
       options={productOptions}
       linkComponent={RouterLink}
       ariaLabel="Product"
+      component="nav-dropdown-products-selector"
     />
   );
 
@@ -897,6 +912,9 @@ function DocsPage() {
     }
     descTag.setAttribute('content', frontmatter.description || '');
     document.documentElement.lang = nav?.activeLanguageCode || 'en';
+    // Mirrors the SSR'd attribute so custom CSS scoped with
+    // html[data-current-path="/x"] follows client-side navigation too.
+    document.documentElement.dataset.currentPath = pathname;
   }, [pathname, isNotFound, frontmatter.title, frontmatter.description, nav?.activeLanguageCode]);
 
   // Frontmatter title needs an id so scroll-spy + click-to-scroll work
@@ -1161,6 +1179,7 @@ function DocsPage() {
       label: 'Log out',
       onClick: logoutPrivateAccess,
       kind: 'outlined',
+      component: 'logout-link',
     });
   }
 
@@ -1211,7 +1230,7 @@ function DocsPage() {
 
   const scrollTo = React.useCallback(
     (id) => {
-      const node = document.getElementById(id);
+      const node = sectionById(id);
       if (!node) return;
       // 1) Set + lock the active id IMMEDIATELY so the spy doesn't
       //    overwrite it during the smooth-scroll animation.
@@ -1242,6 +1261,7 @@ function DocsPage() {
 
   return (
     <div
+      id="body-content"
       className="velu-docs-layout"
       data-chat-open={chatOpen ? 'true' : 'false'}
       data-sidebar-open={sidebarOpen ? 'true' : 'false'}
@@ -1264,6 +1284,7 @@ function DocsPage() {
       {/* Site header — brand, centered search, right-side actions,
           tabs row. Configurable: pass any number of actions / tabs. */}
       <PageHeader
+        id="navbar"
         linkComponent={RouterLink}
         brand={{
           label: site.name,
@@ -1279,6 +1300,7 @@ function DocsPage() {
         center={
           <Cluster space="var(--s-6)" align="center">
             <Search
+              id="search-bar-entry"
               style={{ inlineSize: '30ch' }}
               unavailable={IS_DEV_PREVIEW}
               search={IS_DEV_PREVIEW ? undefined : searchDocs}
@@ -1290,6 +1312,7 @@ function DocsPage() {
             {!IS_DEV_PREVIEW && !askAiHidden && (
               <button
                 type="button"
+                id="assistant-entry"
                 className="velu-header__action velu-header__action--outlined"
                 onClick={() => askAI('')}
               >
@@ -1316,6 +1339,7 @@ function DocsPage() {
           honour `inset-block-start` for fixed positioning the same way
           as plain `top`). */}
       <aside
+        id="sidebar"
         className="velu-docs-layout__aside velu-docs-layout__aside--left"
         style={{
           /* Bottom edge stays a fixed gap above the viewport bottom,
@@ -1400,6 +1424,8 @@ function DocsPage() {
                 <li key={it.href} role="none">
                   <a
                     role="menuitem"
+                    data-component="mobile-nav-tabs-item"
+                    data-active={it.href === nav?.activeTab ? 'true' : undefined}
                     className="velu-docs-layout__drawer-docselect-item"
                     href={it.href}
                     tabIndex={navOpen ? 0 : -1}
@@ -1429,10 +1455,11 @@ function DocsPage() {
                 <span className="velu-show-on-mobile">{languageSwitcher}</span>
               )}
               {anchors.length > 0 && (
-                <ul className="velu-docs-anchors">
+                <ul className="velu-docs-anchors" data-component="nav-anchors">
                   {anchors.map((a, i) => (
                     <li key={i}>
                       <a
+                        data-component="nav-anchor"
                         className="velu-docs-anchors__link"
                         href={a.href}
                         target="_blank"
@@ -1457,7 +1484,7 @@ function DocsPage() {
           {/* Hairline separating the top anchor links from the nav sections
               (faithful to the sidebar design's anchor↔sidebar divider). */}
           {anchors.length > 0 && (
-            <div className="velu-docs-context-divider" aria-hidden="true" />
+            <sidebar-nav-group-divider class="velu-docs-context-divider" aria-hidden="true" />
           )}
           {/* Only this region scrolls — the context zone above stays
               pinned. The up/down arrows overlay its top/bottom edges and
@@ -1466,6 +1493,7 @@ function DocsPage() {
               nav fully to that end. */}
           <div className="velu-docs-nav-region">
             <div
+              id="sidebar-content"
               ref={leftAsideRef}
               className="velu-docs-nav-scroll velu-hide-scrollbar"
               style={{
@@ -1536,6 +1564,7 @@ function DocsPage() {
           Ask-AI chatbot is open (the panel takes that edge). */}
       {!chatOpen && (
         <aside
+          id="table-of-contents"
           ref={rightAsideRef}
           className="velu-docs-layout__aside velu-docs-layout__aside--right velu-hide-scrollbar"
           style={{
@@ -1555,7 +1584,7 @@ function DocsPage() {
           ) : isChangelog && changelogTags.length ? (
             <ChangelogFilters tags={changelogTags} />
           ) : (
-            <Toc items={toc} activeId={activeId} onSelect={scrollTo} />
+            <Toc id="table-of-contents-content" items={toc} activeId={activeId} onSelect={scrollTo} />
           )}
         </aside>
       )}
@@ -1590,6 +1619,7 @@ function DocsPage() {
             on tab/mobile we keep the normal TOC bar (no filters). */}
         <TocBar items={toc} activeId={activeId} onSelect={scrollTo} />
       <main
+        id="content-area"
         className="velu-docs-layout__main"
         style={{
           /* No padding-block-end — the article's last child (PoweredBy)
@@ -1624,7 +1654,7 @@ function DocsPage() {
             })}
           </span>
         </button>
-        <div className="velu-docs-layout__article" data-pagefind-body="">
+        <div id="content" className="velu-docs-layout__article" data-pagefind-body="">
           {/* 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
@@ -1672,7 +1702,7 @@ 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}>
-            <div className="velu-prose">
+            <mdx-content class="velu-prose">
               {PageComponent ? (
                 <ErrorBoundary key={pathname} file={entry?.relPath}>
                   <PageComponent />
@@ -1684,7 +1714,7 @@ function DocsPage() {
                     : 'Page not found.'}
                 </p>
               )}
-            </div>
+            </mdx-content>
           </MDXProvider>
           {/* Page-foot feedback widget — ref'd so the sticky AskBar
               above can hide as the user scrolls near it. */}
@@ -1706,6 +1736,7 @@ function DocsPage() {
               sidebar reading order of the active section. */}
           {(nav?.prev || nav?.next) && (
             <PageNav
+              id="pagination"
               style={{ marginTop: 'var(--s2)' }}
               prev={nav?.prev}
               next={nav?.next}
@@ -1764,7 +1795,8 @@ function DocsPage() {
           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
+        <advanced-footer
+          id="footer"
           ref={footerRef}
           data-velu-footer
           style={{ position: 'relative', zIndex: 20 }}
@@ -1774,7 +1806,7 @@ function DocsPage() {
             columns={site.footer.links}
             socials={footerSocials}
           />
-        </div>
+        </advanced-footer>
       )}
 
       {/* Ask-AI chatbot — slides in from the inline-end edge. Hidden when the
@@ -1817,7 +1849,7 @@ function DocsPage() {
           let tries = 0;
           const go = () => {
             if (hash) {
-              if (document.getElementById(hash)) { scrollTo(hash); return; }
+              if (sectionById(hash)) { scrollTo(hash); return; }
               if (tries++ < 10) { setTimeout(go, 60); return; }
             }
             window.scrollTo({ top: 0, behavior: 'smooth' });

package/src/runtime/client-entry.jsx

@@ -1,7 +1,9 @@
+import './dev-warnings.js';
 import React from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router-dom';
 import 'velu-ui/styles.css';
+import { site } from 'virtual:velu-site';
 import App from './App.jsx';
 
 // Subpath hosting: Vite sets BASE_URL from the build's `base` (e.g. "/docs/").
@@ -9,10 +11,31 @@ import App from './App.jsx';
 // case ("/") becomes undefined so the router behaves as if mounted at origin.
 const basename = (import.meta.env.BASE_URL || '/').replace(/\/$/, '') || undefined;
 
+// Custom JavaScript (Mintlify-compatible): every `.js` file in the project is
+// run on every page. Loaded from an effect so it runs AFTER hydration commits —
+// the page is interactive and a script that mutates the DOM can't cause a
+// hydration mismatch. Classic (non-module) scripts, appended in the discovered
+// order; `async = false` keeps that order for dynamically inserted scripts.
+// Runs once per full page load, not per client-side navigation — same as a
+// <script> tag in the HTML would.
+function CustomScripts() {
+  React.useEffect(() => {
+    for (const url of site.customScripts ?? []) {
+      const el = document.createElement('script');
+      el.src = (basename || '') + url;
+      el.async = false;
+      el.dataset.veluCustom = '';
+      document.body.appendChild(el);
+    }
+  }, []);
+  return null;
+}
+
 hydrateRoot(
   document.getElementById('root'),
   <BrowserRouter basename={basename}>
     <App />
+    <CustomScripts />
   </BrowserRouter>
 );
 

package/src/runtime/dev-warnings.js

@@ -0,0 +1,16 @@
+// velu-ui renders component roots as Mintlify-compatible custom tags
+// (`<card>`, `<callout>`, `<code-block>`, …) so project CSS can use element
+// selectors. Browsers handle unknown elements fine (HTMLUnknownElement), and
+// React renders them fine too, but React's DEVELOPMENT build logs
+//   "Warning: The tag <card> is unrecognized in this browser. …"
+// once per tag name for the ones without a hyphen. Production builds never
+// emit it. This drops exactly that message in dev (server + browser) so
+// `velu dev` output stays readable; every other console.error passes through.
+if (import.meta.env.DEV && typeof console !== 'undefined') {
+  const original = console.error;
+  console.error = function veluFilteredError(...args) {
+    const first = args[0];
+    if (typeof first === 'string' && first.includes('is unrecognized in this browser')) return;
+    original.apply(this, args);
+  };
+}

package/src/runtime/server-entry.jsx

@@ -1,3 +1,4 @@
+import './dev-warnings.js';
 import React from 'react';
 import { renderToString } from 'react-dom/server';
 import { StaticRouter } from 'react-router-dom/server';