@veluai/velu 0.1.0

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

@@ -0,0 +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>
+  );
+}

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

@@ -0,0 +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>
+  );
+}

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

@@ -0,0 +1,90 @@
+import React, { useState } from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+import Cluster from '../primitives/Cluster.jsx';
+import copyText from '../lib/copyText.js';
+import MethodBadge from './MethodBadge.jsx';
+import ApiPath from './ApiPath.jsx';
+
+/**
+ * TryItBar — compact endpoint row: method badge + path + copy icon + a
+ * method-colored "Try It" CTA. Mirrors Mintlify's docs "try-it" row.
+ *
+ *   <TryItBar method="POST" path="/project/preview/{projectId}" />
+ *
+ * CTA is a dummy `<button>` (no fetch / playground wiring) — slot a
+ * handler in via the `onTry` prop when there's a real client. Copy
+ * writes the full "METHOD path" string to clipboard.
+ */
+
+export default function TryItBar({
+  method = 'GET',
+  path = '',
+  cta = 'Try It',
+  onTry,
+  className = '',
+  ...rest
+}) {
+  const [copied, setCopied] = useState(false);
+  const key = String(method).toLowerCase();
+
+  function copy() {
+    copyText(`${String(method).toUpperCase()} ${path}`).then(
+      () => {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1400);
+      },
+      () => {
+        /* silently no-op */
+      },
+    );
+  }
+
+  const cls = `velu-try-it velu-try-it--${key} ${className}`.trim();
+
+  return (
+    // Outer bar is a Cluster — the inner bordered row and the Try It
+    // button are its two children, so they wrap as a unit on narrow
+    // widths (Try It drops below the row).
+    <Cluster
+      space="var(--s-1)"
+      justify="flex-end"
+      align="center"
+      className={cls}
+      {...rest}
+    >
+      {/* Inner bordered group. The method pill + url segments live in
+          their own Cluster that wraps internally; the copy button is a
+          separate sibling pinned to the top-right (align-self:
+          flex-start) so it never drops below the wrapped path. */}
+      <div className="velu-try-it__row">
+        <Cluster
+          space="var(--s-1)"
+          align="center"
+          className="velu-try-it__endpoint"
+        >
+          <MethodBadge method={method} />
+          <ApiPath method={method} path={path} />
+        </Cluster>
+        <button
+          type="button"
+          className="velu-try-it__copy"
+          onClick={copy}
+          aria-label={copied ? 'Copied' : 'Copy endpoint'}
+          title={copied ? 'Copied' : 'Copy'}
+        >
+          {resolveIcon(copied ? 'check' : 'copy', { size: '1em' })}
+        </button>
+      </div>
+      <button
+        type="button"
+        className="velu-try-it__cta"
+        onClick={onTry}
+      >
+        {cta}
+        <span className="velu-try-it__cta-icon" aria-hidden="true">
+          {resolveIcon('chevron-right', { size: '1em' })}
+        </span>
+      </button>
+    </Cluster>
+  );
+}

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

@@ -0,0 +1,92 @@
+/* Accordion — all values are tokens; light/dark via [data-theme].
+   Selectors required (summary:hover, [open], chevron rotate, group
+   dividers) so this component has CSS, like sidebar.css. Namespaced. */
+
+.velu-accordion {
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+  overflow: hidden; /* clip header tint + dividers to the rounded corners */
+  /* `<details>` isn't in base.css's `max-width: none` override list, so
+     it'd otherwise clamp to --measure (66ch). Opt out so the accordion
+     fills the article column. Same fix is applied to the group below. */
+  max-inline-size: none;
+  inline-size: 100%;
+}
+
+.velu-accordion__summary {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  /* matches Callout padding exactly: --s0 block, --s3 inline */
+  padding: var(--s0) var(--s3);
+  cursor: pointer;
+  list-style: none; /* removes the native disclosure triangle */
+  color: var(--text-color);
+  font-size: var(--f-body);
+  line-height: var(--lh-body);
+  /* `<summary>` isn't in base.css's `max-width: none` override list,
+     so without this it'd clamp to --measure (66ch) and the hover
+     surface would stop short of the accordion's right edge. */
+  max-inline-size: none;
+  inline-size: 100%;
+  box-sizing: border-box;
+}
+.velu-accordion__summary::-webkit-details-marker {
+  display: none;
+}
+.velu-accordion__summary:hover {
+  background: var(--surface-color);
+}
+.velu-accordion[open] > .velu-accordion__summary {
+  background: var(--surface-color);
+}
+
+.velu-accordion__chevron {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--f-body);
+  block-size: var(--f-body);
+  transition: transform 0.15s ease;
+}
+.velu-accordion[open] > .velu-accordion__summary .velu-accordion__chevron {
+  transform: rotate(90deg);
+}
+
+.velu-accordion__content {
+  /* same inline padding as the header so body text aligns under it */
+  padding: var(--s0) var(--s3);
+  border-top: var(--border-width) solid var(--border-color); /* header / content divider */
+  color: var(--text-color);
+  font-size: var(--f-body);
+  line-height: var(--lh-body);
+  /* Same reason as `__summary` above — opt out of base.css's
+     --measure cap so the divider line + content area span the full
+     accordion width. */
+  max-inline-size: none;
+  inline-size: 100%;
+  box-sizing: border-box;
+}
+
+/* Group: many items in ONE bordered box; dividers between; outer radius
+   only (children clipped by overflow:hidden). */
+.velu-accordion-group {
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+  /* Group is a <div> (already covered by base.css's override), but we
+     pin it explicitly here so a future markup swap can't regress. */
+  max-inline-size: none;
+  inline-size: 100%;
+}
+.velu-accordion--in-group {
+  border: 0;
+  border-radius: 0;
+  overflow: visible;
+}
+.velu-accordion-group
+  > .velu-accordion--in-group
+  + .velu-accordion--in-group {
+  border-top: var(--border-width) solid var(--border-color);
+}