@veluai/velu 0.1.0

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

@@ -0,0 +1,366 @@
+import React, {
+  useState,
+  useRef,
+  useEffect,
+  useMemo,
+  useCallback,
+} from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * Search — a Raycast-style command palette for the docs site. Ported
+ * from the Claude-Design "Velu Search" handoff and retokenized onto
+ * velu-ui's scale (themes for free via [data-theme]).
+ *
+ *   <Search results={[…]} onSelect={(item) => …} />
+ *
+ * Renders a trigger box (drop it at the top of the page). Clicking it —
+ * or pressing ⌘K / Ctrl+K anywhere — reveals the palette: a scrim plus
+ * a centered panel with a search input and grouped, keyboard-navigable
+ * results (↑/↓ to move, Enter to pick, Esc / scrim-click to close).
+ *
+ * @typedef {Object} SearchResult
+ * @property {string} id
+ * @property {string} group       'Recent Searches' | 'Suggested' | 'Pages'
+ * @property {string[]} breadcrumb
+ * @property {string} title
+ * @property {'page'|'anchor'|'ext'} kind
+ * @property {string} desc
+ * @property {string} [href]
+ *
+ * @param {{ results?: SearchResult[], placeholder?: string,
+ *           onSelect?: (item: SearchResult) => void,
+ *           className?: string }} props
+ */
+
+/* Sample result set — the demo data from the design. Override via the
+   `results` prop with real indexed content. */
+const DEFAULT_RESULTS = [
+  {
+    id: 'auth-pw',
+    group: 'Recent Searches',
+    breadcrumb: ['Authentication setup', 'Password'],
+    title: 'Password',
+    kind: 'anchor',
+    desc: 'Password authentication provides access control through credentials.',
+  },
+  {
+    id: 'gh-sync',
+    group: 'Recent Searches',
+    breadcrumb: ['Get Started', 'GitHub & GitLab Sync'],
+    title: 'Enabling GitHub sync',
+    kind: 'page',
+    desc: 'Connect a GitHub repository to keep your docs in sync on every push.',
+  },
+  {
+    id: 'ai-search',
+    group: 'Recent Searches',
+    breadcrumb: ['Your Docs Site'],
+    title: 'AI Search',
+    kind: 'page',
+    desc: 'Configure semantic search for your documentation site.',
+  },
+  {
+    id: 'quickstart',
+    group: 'Suggested',
+    breadcrumb: ['Get Started'],
+    title: 'Quickstart',
+    kind: 'page',
+    desc: 'Set up Velu and publish your first docs site in under 5 minutes.',
+  },
+  {
+    id: 'overview',
+    group: 'Suggested',
+    breadcrumb: ['Get Started'],
+    title: 'Overview',
+    kind: 'page',
+    desc: 'Velu is an AI-native documentation platform built for humans and AI agents.',
+  },
+  {
+    id: 'site-settings',
+    group: 'Suggested',
+    breadcrumb: ['Your Docs Site'],
+    title: 'Site Settings',
+    kind: 'page',
+    desc: 'Configure domain, theme, navigation and SEO for your docs site.',
+  },
+  {
+    id: 'oauth',
+    group: 'Pages',
+    breadcrumb: ['Authentication setup', 'OAuth'],
+    title: 'OAuth',
+    kind: 'anchor',
+    desc: 'Configure OAuth providers for sign-in.',
+  },
+  {
+    id: 'saml',
+    group: 'Pages',
+    breadcrumb: ['Authentication setup', 'SAML'],
+    title: 'SAML',
+    kind: 'anchor',
+    desc: 'Enterprise single sign-on via SAML 2.0.',
+  },
+];
+
+const GROUP_ORDER = ['Recent Searches', 'Suggested', 'Pages'];
+
+/* Left-hand glyph: '#' for an anchor, an icon for page / external. */
+function ResultGlyph({ kind }) {
+  if (kind === 'anchor') {
+    return <span className="velu-search__glyph-hash">#</span>;
+  }
+  const icon = kind === 'ext' ? 'external-link' : 'file-text';
+  return (
+    <span className="velu-search__glyph-icon">
+      {resolveIcon(icon, { size: '1em' })}
+    </span>
+  );
+}
+
+function Breadcrumb({ items }) {
+  return (
+    <div className="velu-search__crumbs">
+      {items.map((c, i) => (
+        <React.Fragment key={i}>
+          {i > 0 && <span className="velu-search__crumb-sep">›</span>}
+          <span>{c}</span>
+        </React.Fragment>
+      ))}
+    </div>
+  );
+}
+
+function PaletteRow({ item, selected, navMode, onHover, onSelect }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    // Only auto-scroll for keyboard nav — on mouse hover the pointer is
+    // already on the row, and scrolling there nudges the list (a 1px
+    // jitter that flickers a line at the list edge).
+    if (selected && navMode.current === 'keyboard' && ref.current) {
+      ref.current.scrollIntoView({ block: 'nearest' });
+    }
+  }, [selected, navMode]);
+  return (
+    <div
+      ref={ref}
+      className={`velu-search__row${selected ? ' velu-search__row--selected' : ''}`}
+      onMouseEnter={onHover}
+      onClick={onSelect}
+      role="option"
+      aria-selected={selected}
+    >
+      <div className="velu-search__row-glyph">
+        <ResultGlyph kind={item.kind} />
+      </div>
+      <Breadcrumb items={item.breadcrumb} />
+      <div className="velu-search__row-title">{item.title}</div>
+      <div className="velu-search__row-desc">{item.desc}</div>
+      <div className="velu-search__row-meta">
+        <span className="velu-search__kbd">↵</span>
+      </div>
+    </div>
+  );
+}
+
+/* The revealed palette — scrim + centered panel. */
+function SearchPalette({ results, placeholder, onSelect, onClose }) {
+  const [query, setQuery] = useState('');
+  const [selected, setSelected] = useState(0);
+  const inputRef = useRef(null);
+  // 'keyboard' | 'mouse' — which input last moved the selection; gates
+  // the rows' scrollIntoView so mouse hover doesn't jitter the list.
+  const navMode = useRef('keyboard');
+
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) {
+      // Empty query → just the recents.
+      return results.filter((r) => r.group === 'Recent Searches');
+    }
+    return results.filter((r) => {
+      const hay = `${r.title} ${r.breadcrumb.join(' ')} ${r.desc}`.toLowerCase();
+      return hay.includes(q);
+    });
+  }, [query, results]);
+
+  const grouped = useMemo(() => {
+    const map = new Map();
+    filtered.forEach((r) => {
+      if (!map.has(r.group)) map.set(r.group, []);
+      map.get(r.group).push(r);
+    });
+    return GROUP_ORDER.filter((g) => map.has(g)).map((g) => [g, map.get(g)]);
+  }, [filtered]);
+
+  const flat = useMemo(
+    () => grouped.flatMap(([, items]) => items),
+    [grouped],
+  );
+
+  useEffect(() => setSelected(0), [query]);
+
+  const pick = useCallback(
+    (item) => {
+      onSelect?.(item);
+      onClose();
+    },
+    [onSelect, onClose],
+  );
+
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onClose();
+      } else if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        navMode.current = 'keyboard';
+        setSelected((s) => Math.min(s + 1, flat.length - 1));
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        navMode.current = 'keyboard';
+        setSelected((s) => Math.max(s - 1, 0));
+      } else if (e.key === 'Enter') {
+        e.preventDefault();
+        if (flat[selected]) pick(flat[selected]);
+        else onClose();
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [flat, selected, pick, onClose]);
+
+  let rowIndex = -1;
+
+  return (
+    <div
+      className="velu-search__scrim"
+      onClick={onClose}
+      role="presentation"
+    >
+      <div
+        className="velu-search__palette"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Search"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="velu-search__input-wrap">
+          <span className="velu-search__input-icon" aria-hidden="true">
+            {resolveIcon('search', { size: '1em' })}
+          </span>
+          <input
+            ref={inputRef}
+            className="velu-search__input"
+            placeholder={placeholder}
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            spellCheck={false}
+            aria-label="Search query"
+          />
+          <span className="velu-search__kbd">esc</span>
+        </div>
+
+        <div className="velu-search__list" role="listbox">
+          {grouped.length === 0 && (
+            <div className="velu-search__empty">
+              <span className="velu-search__empty-icon" aria-hidden="true">
+                {resolveIcon('search-x', { size: '1em' })}
+              </span>
+              <div className="velu-search__empty-title">
+                No results for &ldquo;{query}&rdquo;
+              </div>
+              <div className="velu-search__empty-sub">
+                Try a different keyword or browse the sidebar.
+              </div>
+            </div>
+          )}
+          {grouped.map(([group, items]) => (
+            <div key={group}>
+              <div className="velu-search__group">{group}</div>
+              {items.map((item) => {
+                rowIndex += 1;
+                const idx = rowIndex;
+                return (
+                  <PaletteRow
+                    key={item.id}
+                    item={item}
+                    selected={idx === selected}
+                    navMode={navMode}
+                    onHover={() => {
+                      navMode.current = 'mouse';
+                      setSelected(idx);
+                    }}
+                    onSelect={() => pick(item)}
+                  />
+                );
+              })}
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function Search({
+  results = DEFAULT_RESULTS,
+  placeholder = 'Search documentation',
+  onSelect,
+  className = '',
+  ...rest
+}) {
+  const [open, setOpen] = useState(false);
+  // Show ⌘ K on Mac, Ctrl K elsewhere. SSR-safe: default to the
+  // non-Mac label (so the server render matches the first client
+  // render), then switch on the client if it's actually Mac.
+  const [isMac, setIsMac] = useState(false);
+  useEffect(() => {
+    if (typeof navigator === 'undefined') return;
+    const ua = navigator.userAgent || '';
+    const plat = navigator.platform || '';
+    setIsMac(/Mac|iPhone|iPad|iPod/i.test(plat) || /Mac/i.test(ua));
+  }, []);
+
+  // Global ⌘K (Mac) / Ctrl+K (Win/Linux) opens the palette.
+  useEffect(() => {
+    const onKey = (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
+        e.preventDefault();
+        setOpen(true);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+
+  return (
+    <>
+      <button
+        type="button"
+        className={`velu-search__trigger ${className}`.trim()}
+        onClick={() => setOpen(true)}
+        {...rest}
+      >
+        <span className="velu-search__trigger-icon" aria-hidden="true">
+          {resolveIcon('search', { size: '1.5em' })}
+        </span>
+        <span className="velu-search__trigger-label">Search…</span>
+        <span className="velu-search__kbd">{isMac ? '⌘ K' : 'Ctrl K'}</span>
+      </button>
+
+      {open && (
+        <SearchPalette
+          results={results}
+          placeholder={placeholder}
+          onSelect={onSelect}
+          onClose={() => setOpen(false)}
+        />
+      )}
+    </>
+  );
+}

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

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

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

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

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

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