@veluai/velu 0.2.35 → 0.2.36

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

@@ -68,9 +68,13 @@ export function VeluMark() {
   );
 }
 
-function ActionButton({ action, Link }) {
-  const { label, icon, kind = 'outlined', href, onClick, external } = action;
+function ActionButton({ action, Link, id }) {
+  const { label, icon, kind = 'outlined', href, onClick, external, component } = action;
   const cls = `velu-header__action velu-header__action--${kind}`;
+  // Mintlify-compatible hooks: `#topbar-cta-button` on the first primary
+  // action, `[data-component="navbar-link"]` on every action (overridable per
+  // action, e.g. component: 'logout-link').
+  const hooks = { id, 'data-component': component ?? 'navbar-link' };
   const content = (
     <>
       {icon && (
@@ -87,13 +91,13 @@ function ActionButton({ action, Link }) {
       ? { target: '_blank', rel: 'noreferrer' }
       : {};
     return (
-      <Tag className={cls} href={href} {...extraProps}>
+      <Tag className={cls} href={href} {...hooks} {...extraProps}>
         {content}
       </Tag>
     );
   }
   return (
-    <button type="button" className={cls} onClick={onClick}>
+    <button type="button" className={cls} onClick={onClick} {...hooks}>
       {content}
     </button>
   );
@@ -111,6 +115,8 @@ function HeaderTab({ tab, isActive, Link }) {
       className={cls}
       href={href}
       aria-current={isActive ? 'page' : undefined}
+      data-active={isActive ? 'true' : undefined}
+      data-component="nav-tabs-item"
       {...extraProps}
     >
       {icon && (
@@ -243,6 +249,7 @@ export default function PageHeader({
   const Link = linkComponent;
   const brandLabel = brand?.label ?? 'Velu';
   const brandHref = brand?.href;
+  const firstPrimary = actions.findIndex((a) => a.kind === 'primary');
 
   // Track whether the page has been scrolled so the header can flip
   // from solid to translucent / frosted. Edge-triggered (only updates
@@ -288,7 +295,7 @@ export default function PageHeader({
           className="velu-header__col velu-header__col--brand"
         >
           {brandHref ? (
-            <Link href={brandHref} className="velu-header__brand-link">
+            <Link href={brandHref} className="velu-header__brand-link" data-component="nav-logo">
               {brandBlock}
             </Link>
           ) : (
@@ -306,6 +313,7 @@ export default function PageHeader({
 
         {(actions.length > 0 || trailing) && (
           <Cluster
+            as="topbar-right-container"
             space="var(--s-2)"
             align="center"
             className="velu-header__col velu-header__col--actions"
@@ -316,7 +324,12 @@ export default function PageHeader({
             {actions.length > 0 && (
               <div className="velu-header__actions-list">
                 {actions.map((a, i) => (
-                  <ActionButton key={i} action={a} Link={Link} />
+                  <ActionButton
+                    key={i}
+                    action={a}
+                    Link={Link}
+                    id={i === firstPrimary ? 'topbar-cta-button' : undefined}
+                  />
                 ))}
               </div>
             )}
@@ -341,6 +354,7 @@ export default function PageHeader({
         tabsTrailing ||
         onMenuClick) && (
         <Cluster
+          as="nav-tabs"
           space="var(--s0)"
           align="center"
           className="velu-header__tabs"
@@ -367,6 +381,7 @@ export default function PageHeader({
             <button
               type="button"
               className="velu-header__crumbs"
+              data-component="breadcrumb-list"
               onClick={onMenuClick}
               aria-label="Open navigation menu"
             >
@@ -381,13 +396,13 @@ export default function PageHeader({
                         focusable="false"
                       />
                     )}
-                    <span
-                      className={`velu-header__crumb${
+                    <breadcrumb-item
+                      class={`velu-header__crumb${
                         isLast ? ' velu-header__crumb--current' : ''
                       }`}
                     >
                       {c.label}
-                    </span>
+                    </breadcrumb-item>
                   </React.Fragment>
                 );
               })}

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

@@ -32,9 +32,10 @@ function NavCard({ page, dir, Link }) {
   return (
     <Link
       className={`velu-pagenav__card velu-pagenav__card--${dir}`}
+      data-component={`pagination-${dir}`}
       href={page.href ?? '#'}
     >
-      <span className="velu-pagenav__title">{page.label}</span>
+      <pagination-title class="velu-pagenav__title">{page.label}</pagination-title>
       <Cluster
         space="var(--s-4)"
         align="center"

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

@@ -69,7 +69,7 @@ export default function Prompt({
   }
 
   return (
-    <div className={`velu-prompt ${className}`.trim()} {...rest}>
+    <prompt className={`velu-prompt ${className}`.trim()} {...rest}>
       {title != null && (
         <div className="velu-prompt__title">{title}</div>
       )}
@@ -110,6 +110,6 @@ export default function Prompt({
           {copied ? 'Copied' : 'Copy Prompt'}
         </button>
       </Cluster>
-    </div>
+    </prompt>
   );
 }

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

@@ -287,6 +287,7 @@ function SearchPalette({ results, search, placeholder, onSelect, onClose }) {
           </span>
           <input
             ref={inputRef}
+            id="search-input"
             className="velu-search__input"
             placeholder={placeholder}
             value={query}

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

@@ -63,9 +63,9 @@ function hasActiveDescendant(item, activeHref) {
 function Icon({ icon }) {
   const node = resolveIcon(icon);
   return node ? (
-    <span className="velu-sidebar__icon" aria-hidden="true">
+    <sidebar-group-icon class="velu-sidebar__icon" aria-hidden="true">
       {node}
-    </span>
+    </sidebar-group-icon>
   ) : null;
 }
 
@@ -99,7 +99,7 @@ function Node({ item, depth }) {
     return (
       <li>
         <details open={hasActiveDescendant(item, activeHref) || undefined}>
-          <summary className={`${base} velu-sidebar__summary`}>
+          <summary className={`${base} velu-sidebar__summary`} data-component="sidebar-group-header">
             <Icon icon={icon} />
             <span className="velu-sidebar__label">{label}</span>
             <Chevron />
@@ -124,10 +124,11 @@ function Node({ item, depth }) {
     : { href };
 
   return (
-    <li>
+    <li data-active={active ? 'true' : undefined}>
       <LinkTag
         className={cls}
         aria-current={active ? 'page' : undefined}
+        data-active={active ? 'true' : undefined}
         {...linkProps}
       >
         <Icon icon={icon} />
@@ -228,8 +229,19 @@ export default function Sidebar({
             separates one section from the next — compact but still
             visibly grouped. */}
         {sections.map((section, i) => (
-          <Stack key={i} space="var(--s-4)">
-            <h5 className="velu-sidebar__section">
+          <Stack
+            key={i}
+            as="sidebar-group"
+            space="var(--s-4)"
+            data-active={
+              section.items.some(
+                (it) => isActive(it, activeHref) || hasActiveDescendant(it, activeHref),
+              )
+                ? 'true'
+                : undefined
+            }
+          >
+            <h5 className="velu-sidebar__section" data-component="sidebar-title">
               <Icon icon={section.icon} />
               {section.title}
             </h5>

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

@@ -33,7 +33,7 @@ export function Step({
   ...rest
 }) {
   return (
-    <div className={`velu-step ${className}`.trim()} {...rest}>
+    <step className={`velu-step ${className}`.trim()} {...rest}>
       <div className="velu-step__circle" aria-hidden="true">
         {index}
       </div>
@@ -44,7 +44,7 @@ export function Step({
       {children != null && children !== false && (
         <div className="velu-step__body">{children}</div>
       )}
-    </div>
+    </step>
   );
 }
 Step.displayName = 'Step';
@@ -58,8 +58,8 @@ export default function Steps({ children, className = '', ...rest }) {
     return cloneElement(child, { index: child.props.index ?? i });
   });
   return (
-    <div className={`velu-steps ${className}`.trim()} {...rest}>
+    <steps className={`velu-steps ${className}`.trim()} {...rest}>
       {numbered}
-    </div>
+    </steps>
   );
 }

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

@@ -32,6 +32,7 @@ export default function ThemeToggle({ className = '', ...rest }) {
       onClick={toggle}
       aria-label="Toggle color theme"
       title="Toggle color theme"
+      data-component-name="theme-toggle"
       className={`velu-theme-toggle ${className}`.trim()}
       {...rest}
     >

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

@@ -127,9 +127,11 @@ const Row = React.forwardRef(function Row(
   ref
 ) {
   return (
-    <div
+    <toc-item
       ref={ref}
       data-toc-active={active ? 'true' : undefined}
+      data-active={active ? 'true' : undefined}
+      data-active-deepest={active ? 'true' : undefined}
       onMouseEnter={() => onEnter(idx)}
       onClick={() => onClick(item.id)}
       style={{
@@ -166,7 +168,7 @@ const Row = React.forwardRef(function Row(
       >
         {item.label}
       </span>
-    </div>
+    </toc-item>
   );
 });
 
@@ -434,7 +436,7 @@ export default function Toc({
   }, [activeIdx]);
 
   return (
-    <div
+    <toc
       ref={rootRef}
       onMouseLeave={() => setHoverIdx(null)}
       style={{
@@ -532,6 +534,6 @@ export default function Toc({
           fontSize={fontSize}
         />
       ))}
-    </div>
+    </toc>
   );
 }

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

@@ -25,9 +25,9 @@ import resolveIcon from '../lib/resolveIcon.jsx';
 
 export default function Tree({ children, className = '', ...rest }) {
   return (
-    <div className={`velu-tree ${className}`.trim()} {...rest}>
+    <tree className={`velu-tree ${className}`.trim()} {...rest}>
       {children}
-    </div>
+    </tree>
   );
 }
 
@@ -54,6 +54,7 @@ export function Folder({
   // the <details> is not [open], so the rail collapses with them.
   return (
     <details
+      data-component="tree-folder"
       className={`velu-tree__group ${className}`.trim()}
       open={defaultOpen || undefined}
       {...rest}
@@ -76,12 +77,12 @@ export function File({
   ...rest
 }) {
   return (
-    <div
-      className={`velu-tree__item velu-tree__item--file ${className}`.trim()}
+    <tree-file
+      class={`velu-tree__item velu-tree__item--file ${className}`.trim()}
       {...rest}
     >
       <ItemIcon icon={icon} />
       <span className="velu-tree__label">{name}</span>
-    </div>
+    </tree-file>
   );
 }

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

@@ -78,6 +78,7 @@ export default function TryItBar({
       </div>
       <button
         type="button"
+        data-component="tryit-button"
         className="velu-try-it__cta"
         onClick={onTry}
         data-loading={loading ? 'true' : undefined}

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

@@ -55,7 +55,7 @@ export default function Update({
   const tagList = toTagList(tags);
 
   return (
-    <section
+    <update
       id={anchorId}
       data-update-label={updateLabel}
       data-update-tags={tagList.join('|')}
@@ -87,6 +87,6 @@ export default function Update({
         ) : null}
       </div>
       {children ? <div className="velu-update__content">{children}</div> : null}
-    </section>
+    </update>
   );
 }

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

@@ -0,0 +1,28 @@
+/* Callout — admonition box. Static styles live here (not inline) so a
+   project's custom CSS can override them with a plain `callout { ... }`
+   element selector, as on Mintlify. The per-variant colours arrive as inline
+   custom properties (--velu-callout-bg / --velu-callout-stroke) set by
+   Callout.jsx from the type / stroke / bg props. */
+.velu-callout {
+  display: flow-root; /* contains the floated icon, no clipping */
+  padding: var(--s0) var(--s3);
+  background: var(--velu-callout-bg);
+  border: var(--border-width) solid var(--velu-callout-stroke);
+  border-radius: var(--radius-sm);
+  color: var(--text-color);
+  font-size: var(--f-body);
+  line-height: var(--lh-body);
+}
+
+/* The icon is FLOATED into the text flow (not a fixed column): it sits on the
+   first line and the text wraps beside it, then flows back under it. One
+   line-box tall so it's centred on the first line. */
+.velu-callout__icon {
+  float: left;
+  display: inline-flex;
+  align-items: center;
+  block-size: calc(var(--f-body) * var(--lh-body));
+  margin-inline-end: var(--s-1);
+  color: var(--velu-callout-stroke);
+  font-size: var(--f-body);
+}

package/runtime/velu-ui/components/docs-layout.css

@@ -71,8 +71,13 @@
 }
 
 .velu-docs-layout__aside--left {
+  /* Shared surface token for the rail and its sticky descendants. Project
+     CSS can override this once on #sidebar; section headers and their fade
+     then remain visually continuous with the customized rail. */
+  --velu-sidebar-bg: var(--page-bg);
   inset-inline-start: 0;
   inline-size: var(--velu-sidebar-width);
+  background: var(--velu-sidebar-bg);
   /* Left gutter so the nav sits inset from the viewport edge rather
      than hugging it. (At mobile the @container block resets this to 0
      — the drawer manages its own padding.) */

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

@@ -58,15 +58,15 @@
      takes over (iOS-list style). It sticks within its section wrapper
      (Sidebar.jsx renders each section in its own Stack), which bounds
      the push-out. Full-width opaque background so scrolling items
-     don't show behind it; --page-bg matches the surroundings, so the
-     bar is invisible until it's actually covering scrolled content. */
+     don't show behind it; --velu-sidebar-bg is owned by the left rail and can
+     be customized there, so the bar remains continuous with its surroundings. */
   position: sticky;
   inset-block-start: 0;
   /* Above the items (z-index 1) so scrolled rows tuck UNDER the heading (its
      opaque bg + the ::after fade hide them), not over it; above the gliding
      indicator (z-index 0) too. */
   z-index: 2;
-  background: var(--page-bg);
+  background: var(--velu-sidebar-bg, var(--page-bg));
   display: flex;
   align-items: center;
   gap: var(--s-2);
@@ -95,8 +95,8 @@
   block-size: var(--s3);
   background: linear-gradient(
     to bottom,
-    var(--page-bg),
-    color-mix(in srgb, var(--page-bg) 55%, transparent),
+    var(--velu-sidebar-bg, var(--page-bg)),
+    color-mix(in srgb, var(--velu-sidebar-bg, var(--page-bg)) 55%, transparent),
     transparent
   );
   pointer-events: none;

package/runtime/velu-ui/element-selectors.css

@@ -0,0 +1,66 @@
+/* Element selectors (Mintlify-compatible).
+
+   Component roots that have no semantic HTML meaning are rendered as the same
+   custom tag names Mintlify uses (`<card>`, `<callout>`, `<code-block>`, …) so
+   a project's custom CSS can target them as `card { … }`, exactly like on
+   Mintlify. Each element keeps its `velu-*` class, so the component CSS is
+   unchanged; this file only gives the unknown tags the display the `div` /
+   `span` they replaced had, and exempts them from the `* { max-width }`
+   measure reset in base.css (which lists `div` and `span` but obviously not
+   these). Class rules (specificity 0,1,0) still beat these tag rules (0,0,1).
+
+   Roots that must stay native for behaviour or accessibility (`<a>`,
+   `<button>`, `<details>`, `<summary>`, `<ul>`, `<textarea>`, headings…)
+   carry `data-component="<mintlify-name>"` instead. */
+
+/* Block-level: replaced a <div> / <section>. */
+accordion-group,
+advanced-footer,
+api-section,
+callout,
+card,
+card-group,
+chat-assistant-floating-input,
+chat-assistant-sheet-content,
+chat-assistant-sheet-header,
+chat-assistant-disclaimer-text,
+code-block,
+code-group,
+columns,
+contextual-feedback-container,
+contextual-feedback-form,
+feedback-toolbar,
+field,
+mdx-content,
+nav-tabs,
+not-found-container,
+not-found-status-code,
+option-dropdown,
+prompt,
+sidebar-group,
+sidebar-nav-group-divider,
+step,
+steps,
+toc,
+toc-item,
+topbar-right-container,
+tree,
+tree-file,
+update {
+  display: block;
+  max-width: none;
+}
+
+/* Inline: replaced a <span>. */
+breadcrumb-item,
+code-block-icon,
+eyebrow,
+method-pill,
+nav-dropdown-item-icon,
+nav-dropdown-item-title,
+pagination-title,
+sidebar-group-icon,
+starter-question-text {
+  display: inline;
+  max-width: none;
+}

package/runtime/velu-ui/primitives/Cluster.jsx

@@ -22,11 +22,22 @@ import React from 'react';
  * @param {string} [props.justify='flex-start']
  * @param {string} [props.align='flex-start']
  */
+
+// React 18 sets props on custom elements (tag names with a hyphen, e.g. the
+// Mintlify-compatible `as="sidebar-group"`) as attributes verbatim, so
+// `className` would come out as a literal className="" attribute. Hand those
+// tags `class` instead. (React 19 maps className for custom elements itself,
+// and accepts `class` too.)
+const isCustomTag = (Tag) => typeof Tag === 'string' && Tag.includes('-');
+const classProp = (Tag, className) =>
+  className == null ? {} : { [isCustomTag(Tag) ? 'class' : 'className']: className };
+
 export default function Cluster({
   as: Tag = 'div',
   space = 'var(--s1)',
   justify = 'flex-start',
   align = 'flex-start',
+  className,
   style,
   children,
   ...rest
@@ -41,6 +52,7 @@ export default function Cluster({
         gap: space,
         ...style,
       }}
+      {...classProp(Tag, className)}
       {...rest}
     >
       {children}

package/runtime/velu-ui/primitives/Stack.jsx

@@ -20,11 +20,22 @@ import React from 'react';
  * @param {number|null} [props.splitAfter=null] 1-based child index; everything
  *        after it is pushed to the bottom (margin-block-end:auto on that child)
  */
+
+// React 18 sets props on custom elements (tag names with a hyphen, e.g. the
+// Mintlify-compatible `as="sidebar-group"`) as attributes verbatim, so
+// `className` would come out as a literal className="" attribute. Hand those
+// tags `class` instead. (React 19 maps className for custom elements itself,
+// and accepts `class` too.)
+const isCustomTag = (Tag) => typeof Tag === 'string' && Tag.includes('-');
+const classProp = (Tag, className) =>
+  className == null ? {} : { [isCustomTag(Tag) ? 'class' : 'className']: className };
+
 const Stack = React.forwardRef(function Stack(
   {
     as: Tag = 'div',
     space = 'var(--s1)',
     splitAfter = null,
+    className,
     style,
     children,
     ...rest
@@ -53,6 +64,7 @@ const Stack = React.forwardRef(function Stack(
         ...(splitAfter ? { blockSize: '100%' } : null),
         ...style,
       }}
+      {...classProp(Tag, className)}
       {...rest}
     >
       {kids}

package/runtime/velu-ui/primitives/Switcher.jsx

@@ -22,6 +22,16 @@ import React from 'react';
  * React-native + SSR-safe + tokenized (vs. the browser-only web component
  * which injects a runtime <style>). Needs its own CSS (styles `> *`).
  */
+
+// React 18 sets props on custom elements (tag names with a hyphen, e.g. the
+// Mintlify-compatible `as="sidebar-group"`) as attributes verbatim, so
+// `className` would come out as a literal className="" attribute. Hand those
+// tags `class` instead. (React 19 maps className for custom elements itself,
+// and accepts `class` too.)
+const isCustomTag = (Tag) => typeof Tag === 'string' && Tag.includes('-');
+const classProp = (Tag, className) =>
+  className == null ? {} : { [isCustomTag(Tag) ? 'class' : 'className']: className };
+
 export default function Switcher({
   as: Tag = 'div',
   space = 'var(--s1)',
@@ -42,7 +52,7 @@ export default function Switcher({
 
   return (
     <Tag
-      className={`velu-switcher ${className}`.trim()}
+      {...classProp(Tag, `velu-switcher ${className}`.trim())}
       data-limit-exceeded={exceeded ? '' : undefined}
       style={{
         '--switcher-space': space,