@veluai/velu 0.2.25 → 0.2.28

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

@@ -1,195 +1,195 @@
-import React from 'react';
-import { ChevronDown } from 'lucide-react';
-import scrollIntoNearestView from '../lib/scrollIntoNearestView.js';
-
-/**
- * TocBar — narrow-layout counterpart to <Toc>.
- *
- * Same data contract as <Toc> (`items`, `activeId`, `onSelect`), but
- * renders as a single sticky bar above the article that expands into a
- * vertical list on click. Used in the tablet layout where the right
- * rail is hidden by a container query — the bar is the only TOC at
- * narrow widths.
- *
- * The component is always rendered; visibility is controlled by CSS
- * (`@container docs (max-width: 1024px)` in toc-bar.css). That way
- * the page hierarchy/state is identical at every viewport size — no
- * JS branching, no hydration mismatch.
- *
- * @typedef {Object} TocItem
- * @property {string} id
- * @property {string} label
- * @property {TocItem[]} [children]
- *
- * @param {{ items: TocItem[], activeId?: string,
- *   onSelect?: (id: string) => void, className?: string }} props
- */
-
-function flatten(nodes, depth = 0, out = []) {
-  for (const n of nodes) {
-    out.push({ id: n.id, label: n.label, depth });
-    if (n.children) flatten(n.children, depth + 1, out);
-  }
-  return out;
-}
-
-/* Circular read-progress indicator. SVG circle whose stroke-dasharray
-   fills proportionally to the page's scroll progress (0 → 1). The
-   ring sits at the leading edge of the bar's toggle row and replaces
-   what was previously a static accent dot.
-
-   `progress` is computed in the parent and passed through here so
-   this component stays purely presentational (SSR-safe — no window
-   reads). */
-function ProgressRing({ progress }) {
-  // 24×24 viewBox with a 10-radius circle ≈ 62.83 perimeter.
-  const r = 10;
-  const c = 2 * Math.PI * r;
-  const dash = Math.max(0, Math.min(1, progress)) * c;
-  return (
-    <svg
-      className="velu-toc-bar__progress"
-      viewBox="0 0 24 24"
-      aria-hidden="true"
-      focusable="false"
-    >
-      {/* Background ring — faint, themed. */}
-      <circle
-        cx="12"
-        cy="12"
-        r={r}
-        fill="none"
-        stroke="var(--border-color)"
-        strokeWidth="2"
-      />
-      {/* Filled arc — starts at 12 o'clock (rotate -90deg). */}
-      <circle
-        cx="12"
-        cy="12"
-        r={r}
-        fill="none"
-        stroke="var(--accent-color)"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeDasharray={`${dash} ${c}`}
-        transform="rotate(-90 12 12)"
-      />
-    </svg>
-  );
-}
-
-export default function TocBar({
-  items = [],
-  activeId,
-  onSelect = () => {},
-  className = '',
-  ...rest
-}) {
-  const [expanded, setExpanded] = React.useState(false);
-
-  // Reading progress through the page: scrollY / (scrollable-distance).
-  // Listens to window scroll + resize; clamped to [0, 1]. Stays at 0
-  // on the server (no window) — matches the SSR-rendered ring (empty
-  // arc) on first paint, no hydration mismatch.
-  const [progress, setProgress] = React.useState(0);
-  React.useEffect(() => {
-    if (typeof window === 'undefined') return;
-    const update = () => {
-      const max = Math.max(
-        1,
-        document.documentElement.scrollHeight - window.innerHeight,
-      );
-      setProgress(Math.max(0, Math.min(1, window.scrollY / max)));
-    };
-    update();
-    window.addEventListener('scroll', update, { passive: true });
-    window.addEventListener('resize', update);
-    return () => {
-      window.removeEventListener('scroll', update);
-      window.removeEventListener('resize', update);
-    };
-  }, []);
-
-  const flat = React.useMemo(() => flatten(items), [items]);
-  // Header label tracks the active section: as the reader scrolls and
-  // the scroll-spy promotes the next heading, the collapsed bar
-  // updates to show where they are right now. Falls back to the root
-  // label (typically the page title) when nothing is active yet — and
-  // to "On this page" if the tree has no root either.
-  const root = items[0];
-  const activeLabel = React.useMemo(() => {
-    if (activeId == null) return null;
-    const hit = flat.find((f) => f.id === activeId);
-    return hit?.label ?? null;
-  }, [flat, activeId]);
-  const headerLabel = activeLabel ?? root?.label ?? 'On this page';
-
-  // When the user picks a row, collapse the bar so the dropdown
-  // doesn't cover the article. The dropdown is `position: absolute`
-  // overlay (see toc-bar.css), so collapsing it does NOT reflow
-  // the article — onSelect's scroll target stays valid whether we
-  // call it before or after `setExpanded(false)`.
-  const handleSelect = (id) => {
-    setExpanded(false);
-    onSelect(id);
-  };
-
-  // Auto-scroll the active row inside the expanded list, same util the
-  // right-rail Toc uses — keeps the active item visible if the list is
-  // long enough to scroll inside the bar.
-  const rootRef = React.useRef(null);
-  React.useEffect(() => {
-    if (!expanded || activeId == null) return;
-    const el = rootRef.current?.querySelector('[data-toc-bar-active="true"]');
-    scrollIntoNearestView(el);
-  }, [expanded, activeId]);
-
-  return (
-    <div
-      ref={rootRef}
-      className={`velu-toc-bar ${className}`.trim()}
-      data-expanded={expanded ? 'true' : 'false'}
-      {...rest}
-    >
-      <button
-        type="button"
-        className="velu-toc-bar__toggle"
-        onClick={() => setExpanded((v) => !v)}
-        aria-expanded={expanded}
-      >
-        {/* Reading-progress ring — fills as the reader scrolls. */}
-        <ProgressRing progress={progress} />
-        <span className="velu-toc-bar__title">{headerLabel}</span>
-        <ChevronDown
-          className="velu-toc-bar__chevron"
-          aria-hidden="true"
-          focusable="false"
-        />
-      </button>
-      {/* The list is ALWAYS in the DOM so CSS can transition between
-          collapsed and expanded states. Visibility is driven by the
-          parent's `data-expanded` attribute via CSS, not by
-          conditional rendering. `aria-hidden` keeps the collapsed
-          list out of the accessibility tree. */}
-      <ul className="velu-toc-bar__list" aria-hidden={!expanded}>
-        {flat.map((item) => {
-          const active = item.id === activeId;
-          return (
-            <li
-              key={item.id}
-              className={`velu-toc-bar__item${active ? ' velu-toc-bar__item--active' : ''}`}
-              style={{
-                paddingInlineStart: `calc(var(--s2) + ${item.depth} * var(--s1))`,
-              }}
-              data-toc-bar-active={active ? 'true' : undefined}
-              onClick={() => handleSelect(item.id)}
-              tabIndex={expanded ? 0 : -1}
-            >
-              {item.label}
-            </li>
-          );
-        })}
-      </ul>
-    </div>
-  );
-}
+import React from 'react';
+import { ChevronDown } from 'lucide-react';
+import scrollIntoNearestView from '../lib/scrollIntoNearestView.js';
+
+/**
+ * TocBar — narrow-layout counterpart to <Toc>.
+ *
+ * Same data contract as <Toc> (`items`, `activeId`, `onSelect`), but
+ * renders as a single sticky bar above the article that expands into a
+ * vertical list on click. Used in the tablet layout where the right
+ * rail is hidden by a container query — the bar is the only TOC at
+ * narrow widths.
+ *
+ * The component is always rendered; visibility is controlled by CSS
+ * (`@container docs (max-width: 1024px)` in toc-bar.css). That way
+ * the page hierarchy/state is identical at every viewport size — no
+ * JS branching, no hydration mismatch.
+ *
+ * @typedef {Object} TocItem
+ * @property {string} id
+ * @property {string} label
+ * @property {TocItem[]} [children]
+ *
+ * @param {{ items: TocItem[], activeId?: string,
+ *   onSelect?: (id: string) => void, className?: string }} props
+ */
+
+function flatten(nodes, depth = 0, out = []) {
+  for (const n of nodes) {
+    out.push({ id: n.id, label: n.label, depth });
+    if (n.children) flatten(n.children, depth + 1, out);
+  }
+  return out;
+}
+
+/* Circular read-progress indicator. SVG circle whose stroke-dasharray
+   fills proportionally to the page's scroll progress (0 → 1). The
+   ring sits at the leading edge of the bar's toggle row and replaces
+   what was previously a static accent dot.
+
+   `progress` is computed in the parent and passed through here so
+   this component stays purely presentational (SSR-safe — no window
+   reads). */
+function ProgressRing({ progress }) {
+  // 24×24 viewBox with a 10-radius circle ≈ 62.83 perimeter.
+  const r = 10;
+  const c = 2 * Math.PI * r;
+  const dash = Math.max(0, Math.min(1, progress)) * c;
+  return (
+    <svg
+      className="velu-toc-bar__progress"
+      viewBox="0 0 24 24"
+      aria-hidden="true"
+      focusable="false"
+    >
+      {/* Background ring — faint, themed. */}
+      <circle
+        cx="12"
+        cy="12"
+        r={r}
+        fill="none"
+        stroke="var(--border-color)"
+        strokeWidth="2"
+      />
+      {/* Filled arc — starts at 12 o'clock (rotate -90deg). */}
+      <circle
+        cx="12"
+        cy="12"
+        r={r}
+        fill="none"
+        stroke="var(--accent-color)"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeDasharray={`${dash} ${c}`}
+        transform="rotate(-90 12 12)"
+      />
+    </svg>
+  );
+}
+
+export default function TocBar({
+  items = [],
+  activeId,
+  onSelect = () => {},
+  className = '',
+  ...rest
+}) {
+  const [expanded, setExpanded] = React.useState(false);
+
+  // Reading progress through the page: scrollY / (scrollable-distance).
+  // Listens to window scroll + resize; clamped to [0, 1]. Stays at 0
+  // on the server (no window) — matches the SSR-rendered ring (empty
+  // arc) on first paint, no hydration mismatch.
+  const [progress, setProgress] = React.useState(0);
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const update = () => {
+      const max = Math.max(
+        1,
+        document.documentElement.scrollHeight - window.innerHeight,
+      );
+      setProgress(Math.max(0, Math.min(1, window.scrollY / max)));
+    };
+    update();
+    window.addEventListener('scroll', update, { passive: true });
+    window.addEventListener('resize', update);
+    return () => {
+      window.removeEventListener('scroll', update);
+      window.removeEventListener('resize', update);
+    };
+  }, []);
+
+  const flat = React.useMemo(() => flatten(items), [items]);
+  // Header label tracks the active section: as the reader scrolls and
+  // the scroll-spy promotes the next heading, the collapsed bar
+  // updates to show where they are right now. Falls back to the root
+  // label (typically the page title) when nothing is active yet — and
+  // to "On this page" if the tree has no root either.
+  const root = items[0];
+  const activeLabel = React.useMemo(() => {
+    if (activeId == null) return null;
+    const hit = flat.find((f) => f.id === activeId);
+    return hit?.label ?? null;
+  }, [flat, activeId]);
+  const headerLabel = activeLabel ?? root?.label ?? 'On this page';
+
+  // When the user picks a row, collapse the bar so the dropdown
+  // doesn't cover the article. The dropdown is `position: absolute`
+  // overlay (see toc-bar.css), so collapsing it does NOT reflow
+  // the article — onSelect's scroll target stays valid whether we
+  // call it before or after `setExpanded(false)`.
+  const handleSelect = (id) => {
+    setExpanded(false);
+    onSelect(id);
+  };
+
+  // Auto-scroll the active row inside the expanded list, same util the
+  // right-rail Toc uses — keeps the active item visible if the list is
+  // long enough to scroll inside the bar.
+  const rootRef = React.useRef(null);
+  React.useEffect(() => {
+    if (!expanded || activeId == null) return;
+    const el = rootRef.current?.querySelector('[data-toc-bar-active="true"]');
+    scrollIntoNearestView(el);
+  }, [expanded, activeId]);
+
+  return (
+    <div
+      ref={rootRef}
+      className={`velu-toc-bar ${className}`.trim()}
+      data-expanded={expanded ? 'true' : 'false'}
+      {...rest}
+    >
+      <button
+        type="button"
+        className="velu-toc-bar__toggle"
+        onClick={() => setExpanded((v) => !v)}
+        aria-expanded={expanded}
+      >
+        {/* Reading-progress ring — fills as the reader scrolls. */}
+        <ProgressRing progress={progress} />
+        <span className="velu-toc-bar__title">{headerLabel}</span>
+        <ChevronDown
+          className="velu-toc-bar__chevron"
+          aria-hidden="true"
+          focusable="false"
+        />
+      </button>
+      {/* The list is ALWAYS in the DOM so CSS can transition between
+          collapsed and expanded states. Visibility is driven by the
+          parent's `data-expanded` attribute via CSS, not by
+          conditional rendering. `aria-hidden` keeps the collapsed
+          list out of the accessibility tree. */}
+      <ul className="velu-toc-bar__list" aria-hidden={!expanded}>
+        {flat.map((item) => {
+          const active = item.id === activeId;
+          return (
+            <li
+              key={item.id}
+              className={`velu-toc-bar__item${active ? ' velu-toc-bar__item--active' : ''}`}
+              style={{
+                paddingInlineStart: `calc(var(--s2) + ${item.depth} * var(--s1))`,
+              }}
+              data-toc-bar-active={active ? 'true' : undefined}
+              onClick={() => handleSelect(item.id)}
+              tabIndex={expanded ? 0 : -1}
+            >
+              {item.label}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

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

@@ -1,87 +1,87 @@
-import React from 'react';
-import resolveIcon from '../lib/resolveIcon.jsx';
-
-/**
- * Tree + Folder + File — file-tree display with nestable folders.
- *
- *   <Tree>
- *     <Folder name="app">
- *       <File name="layout.tsx" />
- *       <File name="page.tsx" />
- *       <Folder name="api">
- *         <File name="route.ts" />
- *       </Folder>
- *     </Folder>
- *     <File name="package.json" />
- *   </Tree>
- *
- * Each Folder may carry children (more Folders/Files); the inner
- * <div className="velu-tree__nest"> draws a vertical rail on its
- * inline-start edge to connect siblings.
- *
- * `icon` accepts a lucide id string (defaults: `folder` / `file`) or any
- * React node — same `resolveIcon` convention as Sidebar / Card / etc.
- */
-
-export default function Tree({ children, className = '', ...rest }) {
-  return (
-    <div className={`velu-tree ${className}`.trim()} {...rest}>
-      {children}
-    </div>
-  );
-}
-
-function ItemIcon({ icon }) {
-  return (
-    <span className="velu-tree__icon" aria-hidden="true">
-      {typeof icon === 'string'
-        ? resolveIcon(icon, { size: '1em' })
-        : icon}
-    </span>
-  );
-}
-
-export function Folder({
-  name,
-  icon = 'folder',
-  defaultOpen = true,
-  children,
-  className = '',
-  ...rest
-}) {
-  // Native <details>/<summary>: zero JS, SSR-safe, accessible. Click
-  // anywhere on the folder row toggles. CSS hides the children when
-  // the <details> is not [open], so the rail collapses with them.
-  return (
-    <details
-      className={`velu-tree__group ${className}`.trim()}
-      open={defaultOpen || undefined}
-      {...rest}
-    >
-      <summary className="velu-tree__item velu-tree__item--folder">
-        <ItemIcon icon={icon} />
-        <span className="velu-tree__label">{name}</span>
-      </summary>
-      {children != null && children !== false && (
-        <div className="velu-tree__nest">{children}</div>
-      )}
-    </details>
-  );
-}
-
-export function File({
-  name,
-  icon = 'file',
-  className = '',
-  ...rest
-}) {
-  return (
-    <div
-      className={`velu-tree__item velu-tree__item--file ${className}`.trim()}
-      {...rest}
-    >
-      <ItemIcon icon={icon} />
-      <span className="velu-tree__label">{name}</span>
-    </div>
-  );
-}
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * Tree + Folder + File — file-tree display with nestable folders.
+ *
+ *   <Tree>
+ *     <Folder name="app">
+ *       <File name="layout.tsx" />
+ *       <File name="page.tsx" />
+ *       <Folder name="api">
+ *         <File name="route.ts" />
+ *       </Folder>
+ *     </Folder>
+ *     <File name="package.json" />
+ *   </Tree>
+ *
+ * Each Folder may carry children (more Folders/Files); the inner
+ * <div className="velu-tree__nest"> draws a vertical rail on its
+ * inline-start edge to connect siblings.
+ *
+ * `icon` accepts a lucide id string (defaults: `folder` / `file`) or any
+ * React node — same `resolveIcon` convention as Sidebar / Card / etc.
+ */
+
+export default function Tree({ children, className = '', ...rest }) {
+  return (
+    <div className={`velu-tree ${className}`.trim()} {...rest}>
+      {children}
+    </div>
+  );
+}
+
+function ItemIcon({ icon }) {
+  return (
+    <span className="velu-tree__icon" aria-hidden="true">
+      {typeof icon === 'string'
+        ? resolveIcon(icon, { size: '1em' })
+        : icon}
+    </span>
+  );
+}
+
+export function Folder({
+  name,
+  icon = 'folder',
+  defaultOpen = true,
+  children,
+  className = '',
+  ...rest
+}) {
+  // Native <details>/<summary>: zero JS, SSR-safe, accessible. Click
+  // anywhere on the folder row toggles. CSS hides the children when
+  // the <details> is not [open], so the rail collapses with them.
+  return (
+    <details
+      className={`velu-tree__group ${className}`.trim()}
+      open={defaultOpen || undefined}
+      {...rest}
+    >
+      <summary className="velu-tree__item velu-tree__item--folder">
+        <ItemIcon icon={icon} />
+        <span className="velu-tree__label">{name}</span>
+      </summary>
+      {children != null && children !== false && (
+        <div className="velu-tree__nest">{children}</div>
+      )}
+    </details>
+  );
+}
+
+export function File({
+  name,
+  icon = 'file',
+  className = '',
+  ...rest
+}) {
+  return (
+    <div
+      className={`velu-tree__item velu-tree__item--file ${className}`.trim()}
+      {...rest}
+    >
+      <ItemIcon icon={icon} />
+      <span className="velu-tree__label">{name}</span>
+    </div>
+  );
+}