@veluai/velu 0.2.13 → 0.2.15

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

@@ -1,254 +1,254 @@
-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' });
-
-// Positioning must happen before paint (no flash); fall back to useEffect on
-// the server so React doesn't warn about useLayoutEffect during SSR.
-const useIsoLayoutEffect =
-  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
-
-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, method } = 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}
-      >
-        {method ? (
-          <span
-            className={`velu-sidebar__method velu-method-badge--${String(method).toLowerCase()}`}
-          >
-            {method}
-          </span>
-        ) : (
-          <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]);
-
-  // The single gliding active indicator (crimson tint + flush-left bar). One
-  // element animates its position/height to the active item, so selection feels
-  // continuous rather than each item popping its own bar. It lives in the scroll
-  // content, so its offset is scroll-stable (no re-measure on scroll) and a
-  // pinned sticky heading's opaque background covers it when an item tucks under.
-  const [ind, setInd] = React.useState({ top: 0, h: 0, show: false });
-  const measure = React.useCallback(() => {
-    const nav = rootRef.current;
-    if (!nav) return;
-    const el = nav.querySelector('[aria-current="page"]');
-    if (!el) {
-      setInd((s) => (s.show ? { ...s, show: false } : s));
-      return;
-    }
-    const top = el.getBoundingClientRect().top - nav.getBoundingClientRect().top;
-    const h = el.offsetHeight;
-    // Bail when nothing moved → no needless re-render (and no animation jitter).
-    setInd((s) =>
-      s.show && Math.abs(s.top - top) < 0.5 && Math.abs(s.h - h) < 0.5
-        ? s
-        : { top, h, show: true },
-    );
-  }, []);
-  // Re-measure on selection / tab change…
-  useIsoLayoutEffect(() => {
-    measure();
-  }, [activeHref, sections, measure]);
-  // …and whenever the nav's layout changes (a group expands/collapses → the
-  // active item moves), plus on viewport resize.
-  React.useEffect(() => {
-    const nav = rootRef.current;
-    if (!nav || typeof ResizeObserver === 'undefined') return undefined;
-    const ro = new ResizeObserver(() => measure());
-    ro.observe(nav);
-    window.addEventListener('resize', measure);
-    return () => {
-      ro.disconnect();
-      window.removeEventListener('resize', measure);
-    };
-  }, [measure]);
-
-  return (
-    <SidebarCtx.Provider value={ctx}>
-      <Stack
-        ref={rootRef}
-        as="nav"
-        space="var(--s0)"
-        className={`velu-sidebar ${className}`.trim()}
-        aria-label="Documentation"
-        {...rest}
-      >
-        <span
-          className="velu-sidebar__indicator"
-          aria-hidden="true"
-          style={{
-            transform: `translateY(${ind.top}px)`,
-            height: `${ind.h}px`,
-            opacity: ind.show ? 1 : 0,
-          }}
-        />
-        {/* 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' });
+
+// Positioning must happen before paint (no flash); fall back to useEffect on
+// the server so React doesn't warn about useLayoutEffect during SSR.
+const useIsoLayoutEffect =
+  typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;
+
+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, method } = 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}
+      >
+        {method ? (
+          <span
+            className={`velu-sidebar__method velu-method-badge--${String(method).toLowerCase()}`}
+          >
+            {method}
+          </span>
+        ) : (
+          <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]);
+
+  // The single gliding active indicator (crimson tint + flush-left bar). One
+  // element animates its position/height to the active item, so selection feels
+  // continuous rather than each item popping its own bar. It lives in the scroll
+  // content, so its offset is scroll-stable (no re-measure on scroll) and a
+  // pinned sticky heading's opaque background covers it when an item tucks under.
+  const [ind, setInd] = React.useState({ top: 0, h: 0, show: false });
+  const measure = React.useCallback(() => {
+    const nav = rootRef.current;
+    if (!nav) return;
+    const el = nav.querySelector('[aria-current="page"]');
+    if (!el) {
+      setInd((s) => (s.show ? { ...s, show: false } : s));
+      return;
+    }
+    const top = el.getBoundingClientRect().top - nav.getBoundingClientRect().top;
+    const h = el.offsetHeight;
+    // Bail when nothing moved → no needless re-render (and no animation jitter).
+    setInd((s) =>
+      s.show && Math.abs(s.top - top) < 0.5 && Math.abs(s.h - h) < 0.5
+        ? s
+        : { top, h, show: true },
+    );
+  }, []);
+  // Re-measure on selection / tab change…
+  useIsoLayoutEffect(() => {
+    measure();
+  }, [activeHref, sections, measure]);
+  // …and whenever the nav's layout changes (a group expands/collapses → the
+  // active item moves), plus on viewport resize.
+  React.useEffect(() => {
+    const nav = rootRef.current;
+    if (!nav || typeof ResizeObserver === 'undefined') return undefined;
+    const ro = new ResizeObserver(() => measure());
+    ro.observe(nav);
+    window.addEventListener('resize', measure);
+    return () => {
+      ro.disconnect();
+      window.removeEventListener('resize', measure);
+    };
+  }, [measure]);
+
+  return (
+    <SidebarCtx.Provider value={ctx}>
+      <Stack
+        ref={rootRef}
+        as="nav"
+        space="var(--s0)"
+        className={`velu-sidebar ${className}`.trim()}
+        aria-label="Documentation"
+        {...rest}
+      >
+        <span
+          className="velu-sidebar__indicator"
+          aria-hidden="true"
+          style={{
+            transform: `translateY(${ind.top}px)`,
+            height: `${ind.h}px`,
+            opacity: ind.show ? 1 : 0,
+          }}
+        />
+        {/* 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>
+  );
+}