@veluai/velu 0.1.13 → 0.1.14

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

@@ -1,191 +1,191 @@
-import React from 'react';
-import { ChevronRight, ExternalLink } from 'lucide-react';
-import Stack from '../primitives/Stack.jsx';
-import resolveIcon from '../lib/resolveIcon.jsx';
-import scrollIntoNearestView from '../lib/scrollIntoNearestView.js';
-
-/**
- * Sidebar — docs navigation. Data-driven, recursive (arbitrary depth),
- * tokenized, SSR-safe.
- *
- * Composition: ALL vertical rhythm is the Stack primitive (DRY) — faithful to
- * the source design's flat structure:
- *   <Stack as="nav" space=--s1>            ← headings + lists alternate here
- *     <h5 section/>                         (uniform --s1 between every child)
- *     <Stack as="ul" space=--s0> items </Stack>
- *   nested groups: <Stack as="ul" space="0"> (spacing via item padding)
- * sidebar.css holds only what Stack cannot: rails, active state, item rows,
- * chevron, summary, icon sizing.
- *
- * Icons (`section.icon` / `item.icon`) are **lucide icon id strings**
- * (kebab-case), resolved by the shared resolveIcon util (a React node is
- * also accepted). Size + stroke come from .velu-sidebar__icon CSS.
- *
- * Selection is ROUTE-DRIVEN (SSR-correct, reload-safe, URL-shareable): an
- * item is active when its href === activeHref (or active:true). Ancestor
- * groups of the active item auto-open. Router-agnostic via `linkComponent`
- * (defaults to <a>); external items always render a real <a target=_blank>.
- *
- * @typedef {Object} SidebarItem
- * @property {string} label
- * @property {string} [href]
- * @property {string|React.ReactNode} [icon]   // lucide id or node
- * @property {boolean} [active]
- * @property {boolean} [external]
- * @property {SidebarItem[]} [items]
- *
- * @param {{ sections: { title: string, icon?: string|React.ReactNode,
- *           items: SidebarItem[] }[], activeHref?: string,
- *           linkComponent?: React.ElementType, className?: string }} props
- */
-
-const SidebarCtx = React.createContext({ activeHref: undefined, Link: 'a' });
-
-function isActive(item, activeHref) {
-  return Boolean(
-    item.active || (item.href != null && item.href === activeHref)
-  );
-}
-
-function hasActiveDescendant(item, activeHref) {
-  if (isActive(item, activeHref)) return true;
-  return (
-    Array.isArray(item.items) &&
-    item.items.some((c) => hasActiveDescendant(c, activeHref))
-  );
-}
-
-function Icon({ icon }) {
-  const node = resolveIcon(icon);
-  return node ? (
-    <span className="velu-sidebar__icon" aria-hidden="true">
-      {node}
-    </span>
-  ) : null;
-}
-
-function Chevron() {
-  return (
-    <ChevronRight
-      className="velu-sidebar__chevron"
-      aria-hidden="true"
-      focusable="false"
-    />
-  );
-}
-
-function ExternalIcon() {
-  return (
-    <ExternalLink
-      className="velu-sidebar__icon"
-      aria-hidden="true"
-      focusable="false"
-    />
-  );
-}
-
-/** Recursive node. depth 0 = top-level; depth >= 1 = nested (subitem style). */
-function Node({ item, depth }) {
-  const { activeHref, Link } = React.useContext(SidebarCtx);
-  const { label, href = '#', icon, external, items } = item;
-  const base = depth === 0 ? 'velu-sidebar__item' : 'velu-sidebar__subitem';
-
-  if (items && items.length) {
-    return (
-      <li>
-        <details open={hasActiveDescendant(item, activeHref) || undefined}>
-          <summary className={`${base} velu-sidebar__summary`}>
-            <Icon icon={icon} />
-            <span className="velu-sidebar__label">{label}</span>
-            <Chevron />
-          </summary>
-          {/* nested list: Stack with no gap (spacing = item padding-block),
-              matching the source's stack-s */}
-          <Stack as="ul" space="0" className="velu-sidebar__sublist">
-            {items.map((child, i) => (
-              <Node key={i} item={child} depth={depth + 1} />
-            ))}
-          </Stack>
-        </details>
-      </li>
-    );
-  }
-
-  const active = isActive(item, activeHref);
-  const cls = base + (active ? ' velu-sidebar__item--active' : '');
-  const LinkTag = external ? 'a' : Link;
-  const linkProps = external
-    ? { href, target: '_blank', rel: 'noreferrer' }
-    : { href };
-
-  return (
-    <li>
-      <LinkTag
-        className={cls}
-        aria-current={active ? 'page' : undefined}
-        {...linkProps}
-      >
-        <Icon icon={icon} />
-        <span className="velu-sidebar__label">{label}</span>
-        {external ? <ExternalIcon /> : null}
-      </LinkTag>
-    </li>
-  );
-}
-
-export default function Sidebar({
-  sections = [],
-  activeHref,
-  linkComponent = 'a',
-  className = '',
-  ...rest
-}) {
-  const ctx = React.useMemo(
-    () => ({ activeHref, Link: linkComponent }),
-    [activeHref, linkComponent]
-  );
-
-  // Bring the active item into view inside the parent scroll container
-  // whenever the active route changes — e.g. after navigation, the
-  // selected page is already visible without the user scrolling the
-  // sidebar manually. Uses the shared util (instead of native
-  // scrollIntoView) so `scroll-padding-*` on the parent — which the
-  // docs layout uses to mark the footer-eclipsed band as off-limits —
-  // is reliably honoured.
-  const rootRef = React.useRef(null);
-  React.useEffect(() => {
-    const el = rootRef.current?.querySelector('[aria-current="page"]');
-    scrollIntoNearestView(el);
-  }, [activeHref]);
-
-  return (
-    <SidebarCtx.Provider value={ctx}>
-      <Stack
-        ref={rootRef}
-        as="nav"
-        space="var(--s0)"
-        className={`velu-sidebar ${className}`.trim()}
-        aria-label="Documentation"
-        {...rest}
-      >
-        {/* Each section is its own Stack so the heading sits TIGHT to
-            its list (small inner gap), while the nav's larger gap
-            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">
-              <Icon icon={section.icon} />
-              {section.title}
-            </h5>
-            <Stack as="ul" space="var(--s-4)" className="velu-sidebar__list">
-              {section.items.map((it, j) => (
-                <Node key={j} item={it} depth={0} />
-              ))}
-            </Stack>
-          </Stack>
-        ))}
-      </Stack>
-    </SidebarCtx.Provider>
-  );
-}
+import React from 'react';
+import { ChevronRight, ExternalLink } from 'lucide-react';
+import Stack from '../primitives/Stack.jsx';
+import resolveIcon from '../lib/resolveIcon.jsx';
+import scrollIntoNearestView from '../lib/scrollIntoNearestView.js';
+
+/**
+ * Sidebar — docs navigation. Data-driven, recursive (arbitrary depth),
+ * tokenized, SSR-safe.
+ *
+ * Composition: ALL vertical rhythm is the Stack primitive (DRY) — faithful to
+ * the source design's flat structure:
+ *   <Stack as="nav" space=--s1>            ← headings + lists alternate here
+ *     <h5 section/>                         (uniform --s1 between every child)
+ *     <Stack as="ul" space=--s0> items </Stack>
+ *   nested groups: <Stack as="ul" space="0"> (spacing via item padding)
+ * sidebar.css holds only what Stack cannot: rails, active state, item rows,
+ * chevron, summary, icon sizing.
+ *
+ * Icons (`section.icon` / `item.icon`) are **lucide icon id strings**
+ * (kebab-case), resolved by the shared resolveIcon util (a React node is
+ * also accepted). Size + stroke come from .velu-sidebar__icon CSS.
+ *
+ * Selection is ROUTE-DRIVEN (SSR-correct, reload-safe, URL-shareable): an
+ * item is active when its href === activeHref (or active:true). Ancestor
+ * groups of the active item auto-open. Router-agnostic via `linkComponent`
+ * (defaults to <a>); external items always render a real <a target=_blank>.
+ *
+ * @typedef {Object} SidebarItem
+ * @property {string} label
+ * @property {string} [href]
+ * @property {string|React.ReactNode} [icon]   // lucide id or node
+ * @property {boolean} [active]
+ * @property {boolean} [external]
+ * @property {SidebarItem[]} [items]
+ *
+ * @param {{ sections: { title: string, icon?: string|React.ReactNode,
+ *           items: SidebarItem[] }[], activeHref?: string,
+ *           linkComponent?: React.ElementType, className?: string }} props
+ */
+
+const SidebarCtx = React.createContext({ activeHref: undefined, Link: 'a' });
+
+function isActive(item, activeHref) {
+  return Boolean(
+    item.active || (item.href != null && item.href === activeHref)
+  );
+}
+
+function hasActiveDescendant(item, activeHref) {
+  if (isActive(item, activeHref)) return true;
+  return (
+    Array.isArray(item.items) &&
+    item.items.some((c) => hasActiveDescendant(c, activeHref))
+  );
+}
+
+function Icon({ icon }) {
+  const node = resolveIcon(icon);
+  return node ? (
+    <span className="velu-sidebar__icon" aria-hidden="true">
+      {node}
+    </span>
+  ) : null;
+}
+
+function Chevron() {
+  return (
+    <ChevronRight
+      className="velu-sidebar__chevron"
+      aria-hidden="true"
+      focusable="false"
+    />
+  );
+}
+
+function ExternalIcon() {
+  return (
+    <ExternalLink
+      className="velu-sidebar__icon"
+      aria-hidden="true"
+      focusable="false"
+    />
+  );
+}
+
+/** Recursive node. depth 0 = top-level; depth >= 1 = nested (subitem style). */
+function Node({ item, depth }) {
+  const { activeHref, Link } = React.useContext(SidebarCtx);
+  const { label, href = '#', icon, external, items } = item;
+  const base = depth === 0 ? 'velu-sidebar__item' : 'velu-sidebar__subitem';
+
+  if (items && items.length) {
+    return (
+      <li>
+        <details open={hasActiveDescendant(item, activeHref) || undefined}>
+          <summary className={`${base} velu-sidebar__summary`}>
+            <Icon icon={icon} />
+            <span className="velu-sidebar__label">{label}</span>
+            <Chevron />
+          </summary>
+          {/* nested list: Stack with no gap (spacing = item padding-block),
+              matching the source's stack-s */}
+          <Stack as="ul" space="0" className="velu-sidebar__sublist">
+            {items.map((child, i) => (
+              <Node key={i} item={child} depth={depth + 1} />
+            ))}
+          </Stack>
+        </details>
+      </li>
+    );
+  }
+
+  const active = isActive(item, activeHref);
+  const cls = base + (active ? ' velu-sidebar__item--active' : '');
+  const LinkTag = external ? 'a' : Link;
+  const linkProps = external
+    ? { href, target: '_blank', rel: 'noreferrer' }
+    : { href };
+
+  return (
+    <li>
+      <LinkTag
+        className={cls}
+        aria-current={active ? 'page' : undefined}
+        {...linkProps}
+      >
+        <Icon icon={icon} />
+        <span className="velu-sidebar__label">{label}</span>
+        {external ? <ExternalIcon /> : null}
+      </LinkTag>
+    </li>
+  );
+}
+
+export default function Sidebar({
+  sections = [],
+  activeHref,
+  linkComponent = 'a',
+  className = '',
+  ...rest
+}) {
+  const ctx = React.useMemo(
+    () => ({ activeHref, Link: linkComponent }),
+    [activeHref, linkComponent]
+  );
+
+  // Bring the active item into view inside the parent scroll container
+  // whenever the active route changes — e.g. after navigation, the
+  // selected page is already visible without the user scrolling the
+  // sidebar manually. Uses the shared util (instead of native
+  // scrollIntoView) so `scroll-padding-*` on the parent — which the
+  // docs layout uses to mark the footer-eclipsed band as off-limits —
+  // is reliably honoured.
+  const rootRef = React.useRef(null);
+  React.useEffect(() => {
+    const el = rootRef.current?.querySelector('[aria-current="page"]');
+    scrollIntoNearestView(el);
+  }, [activeHref]);
+
+  return (
+    <SidebarCtx.Provider value={ctx}>
+      <Stack
+        ref={rootRef}
+        as="nav"
+        space="var(--s0)"
+        className={`velu-sidebar ${className}`.trim()}
+        aria-label="Documentation"
+        {...rest}
+      >
+        {/* Each section is its own Stack so the heading sits TIGHT to
+            its list (small inner gap), while the nav's larger gap
+            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">
+              <Icon icon={section.icon} />
+              {section.title}
+            </h5>
+            <Stack as="ul" space="var(--s-4)" className="velu-sidebar__list">
+              {section.items.map((it, j) => (
+                <Node key={j} item={it} depth={0} />
+              ))}
+            </Stack>
+          </Stack>
+        ))}
+      </Stack>
+    </SidebarCtx.Provider>
+  );
+}

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

@@ -1,65 +1,65 @@
-import React, { Children, cloneElement, isValidElement } from 'react';
-
-/**
- * Steps + Step — numbered procedural steps with a continuous accent rail
- * down the left edge.
- *
- *   <Steps>
- *     <Step title="First Step">These are instructions…</Step>
- *     <Step title="Second Step">…</Step>
- *     <Step title="Third Step">…</Step>
- *   </Steps>
- *
- * Steps assigns 1-based `index` to each <Step> child via cloneElement —
- * callers don't have to number them by hand. A <Step> rendered outside
- * <Steps> falls back to whatever `index` it was given (or 1).
- *
- * Each Step is a 2-column grid:
- *
- *   [circle + line]   title
- *                     body
- *
- * The marker column spans both rows. The vertical rail (line below the
- * circle) is `flex: 1`, so it stretches to fill the Step's full height —
- * meaning adjacent steps' rails meet end-to-end with no manual height
- * math. The last step keeps its rail too (matches the design).
- */
-
-export function Step({
-  title,
-  index = 1,
-  children,
-  className = '',
-  ...rest
-}) {
-  return (
-    <div className={`velu-step ${className}`.trim()} {...rest}>
-      <div className="velu-step__circle" aria-hidden="true">
-        {index}
-      </div>
-      <div className="velu-step__line" aria-hidden="true" />
-      {title != null && (
-        <div className="velu-step__title">{title}</div>
-      )}
-      {children != null && children !== false && (
-        <div className="velu-step__body">{children}</div>
-      )}
-    </div>
-  );
-}
-Step.displayName = 'Step';
-
-export default function Steps({ children, className = '', ...rest }) {
-  let i = 0;
-  const numbered = Children.map(children, (child) => {
-    if (!isValidElement(child)) return child;
-    if (child.type !== Step && child.type?.displayName !== 'Step') return child;
-    i += 1;
-    return cloneElement(child, { index: child.props.index ?? i });
-  });
-  return (
-    <div className={`velu-steps ${className}`.trim()} {...rest}>
-      {numbered}
-    </div>
-  );
-}
+import React, { Children, cloneElement, isValidElement } from 'react';
+
+/**
+ * Steps + Step — numbered procedural steps with a continuous accent rail
+ * down the left edge.
+ *
+ *   <Steps>
+ *     <Step title="First Step">These are instructions…</Step>
+ *     <Step title="Second Step">…</Step>
+ *     <Step title="Third Step">…</Step>
+ *   </Steps>
+ *
+ * Steps assigns 1-based `index` to each <Step> child via cloneElement —
+ * callers don't have to number them by hand. A <Step> rendered outside
+ * <Steps> falls back to whatever `index` it was given (or 1).
+ *
+ * Each Step is a 2-column grid:
+ *
+ *   [circle + line]   title
+ *                     body
+ *
+ * The marker column spans both rows. The vertical rail (line below the
+ * circle) is `flex: 1`, so it stretches to fill the Step's full height —
+ * meaning adjacent steps' rails meet end-to-end with no manual height
+ * math. The last step keeps its rail too (matches the design).
+ */
+
+export function Step({
+  title,
+  index = 1,
+  children,
+  className = '',
+  ...rest
+}) {
+  return (
+    <div className={`velu-step ${className}`.trim()} {...rest}>
+      <div className="velu-step__circle" aria-hidden="true">
+        {index}
+      </div>
+      <div className="velu-step__line" aria-hidden="true" />
+      {title != null && (
+        <div className="velu-step__title">{title}</div>
+      )}
+      {children != null && children !== false && (
+        <div className="velu-step__body">{children}</div>
+      )}
+    </div>
+  );
+}
+Step.displayName = 'Step';
+
+export default function Steps({ children, className = '', ...rest }) {
+  let i = 0;
+  const numbered = Children.map(children, (child) => {
+    if (!isValidElement(child)) return child;
+    if (child.type !== Step && child.type?.displayName !== 'Step') return child;
+    i += 1;
+    return cloneElement(child, { index: child.props.index ?? i });
+  });
+  return (
+    <div className={`velu-steps ${className}`.trim()} {...rest}>
+      {numbered}
+    </div>
+  );
+}

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

@@ -1,48 +1,48 @@
-import React from 'react';
-import { Sun, Moon } from 'lucide-react';
-
-/**
- * ThemeToggle — pill-shaped two-state light/dark switch. The thumb
- * sits at the inline-start in light mode and slides to the inline-end
- * in dark mode. A sun glyph rides the thumb in light, a moon in dark.
- *
- * SSR-safe by design: markup is identical regardless of theme (the
- * server doesn't know it), and the thumb position + which glyph shows
- * are decided purely by CSS via the `[data-theme]` attribute — NOT by
- * React state. So there is no hydration mismatch and no icon flash. JS
- * only handles the click: it flips `data-theme` and persists the
- * explicit choice (which then overrides the OS preference on future
- * visits, per the anti-flash script in the template).
- */
-export default function ThemeToggle({ className = '', ...rest }) {
-  function toggle() {
-    const root = document.documentElement;
-    const next = root.dataset.theme === 'dark' ? 'light' : 'dark';
-    root.dataset.theme = next;
-    try {
-      localStorage.setItem('velu-theme', next);
-    } catch {
-      /* private mode / storage disabled — toggle still works for the session */
-    }
-  }
-
-  return (
-    <button
-      type="button"
-      onClick={toggle}
-      aria-label="Toggle color theme"
-      title="Toggle color theme"
-      className={`velu-theme-toggle ${className}`.trim()}
-      {...rest}
-    >
-      <Sun
-        className="velu-theme-toggle__icon velu-theme-toggle__icon--sun"
-        aria-hidden="true"
-      />
-      <Moon
-        className="velu-theme-toggle__icon velu-theme-toggle__icon--moon"
-        aria-hidden="true"
-      />
-    </button>
-  );
-}
+import React from 'react';
+import { Sun, Moon } from 'lucide-react';
+
+/**
+ * ThemeToggle — pill-shaped two-state light/dark switch. The thumb
+ * sits at the inline-start in light mode and slides to the inline-end
+ * in dark mode. A sun glyph rides the thumb in light, a moon in dark.
+ *
+ * SSR-safe by design: markup is identical regardless of theme (the
+ * server doesn't know it), and the thumb position + which glyph shows
+ * are decided purely by CSS via the `[data-theme]` attribute — NOT by
+ * React state. So there is no hydration mismatch and no icon flash. JS
+ * only handles the click: it flips `data-theme` and persists the
+ * explicit choice (which then overrides the OS preference on future
+ * visits, per the anti-flash script in the template).
+ */
+export default function ThemeToggle({ className = '', ...rest }) {
+  function toggle() {
+    const root = document.documentElement;
+    const next = root.dataset.theme === 'dark' ? 'light' : 'dark';
+    root.dataset.theme = next;
+    try {
+      localStorage.setItem('velu-theme', next);
+    } catch {
+      /* private mode / storage disabled — toggle still works for the session */
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={toggle}
+      aria-label="Toggle color theme"
+      title="Toggle color theme"
+      className={`velu-theme-toggle ${className}`.trim()}
+      {...rest}
+    >
+      <Sun
+        className="velu-theme-toggle__icon velu-theme-toggle__icon--sun"
+        aria-hidden="true"
+      />
+      <Moon
+        className="velu-theme-toggle__icon velu-theme-toggle__icon--moon"
+        aria-hidden="true"
+      />
+    </button>
+  );
+}