@veluai/velu 0.1.13 → 0.1.15

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/SocialLinks.jsx

@@ -0,0 +1,90 @@
+import React from 'react';
+import Cluster from '../primitives/Cluster.jsx';
+
+/**
+ * SocialLinks — a row of social-platform icon links. Shared by the full
+ * PageFooter (centered at its base) and the compact content-foot row (next to
+ * "Powered by Velu" when there are no footer link columns).
+ *
+ * `socials` is `[{ kind, href }]`. Unknown kinds (no icon) are skipped.
+ *
+ * @param {{ socials?: {kind: string, href: string}[],
+ *           justify?: string, className?: string }} props
+ */
+
+/* Inline SVGs, fill: currentColor so they inherit the themed text color. */
+function GithubIcon() {
+  return (
+    <svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+      <path
+        fillRule="evenodd"
+        clipRule="evenodd"
+        d="M8 0C3.58 0 0 3.58 0 8C0 11.54 2.29 14.53 5.47 15.59C5.87 15.66 6.02 15.42 6.02 15.21C6.02 15.02 6.01 14.39 6.01 13.72C4 14.09 3.48 13.23 3.32 12.78C3.23 12.55 2.84 11.84 2.5 11.65C2.22 11.5 1.82 11.13 2.49 11.12C3.12 11.11 3.57 11.7 3.72 11.94C4.44 13.15 5.59 12.81 6.05 12.6C6.12 12.08 6.33 11.73 6.56 11.53C4.78 11.33 2.92 10.64 2.92 7.58C2.92 6.71 3.23 5.99 3.74 5.43C3.66 5.23 3.38 4.41 3.82 3.31C3.82 3.31 4.49 3.1 6.02 4.13C6.66 3.95 7.34 3.86 8.02 3.86C8.7 3.86 9.38 3.95 10.02 4.13C11.55 3.09 12.22 3.31 12.22 3.31C12.66 4.41 12.38 5.23 12.3 5.43C12.81 5.99 13.12 6.7 13.12 7.58C13.12 10.65 11.25 11.33 9.47 11.53C9.76 11.78 10.01 12.26 10.01 13.01C10.01 14.08 10 14.94 10 15.21C10 15.42 10.15 15.67 10.55 15.59C13.71 14.53 16 11.53 16 8C16 3.58 12.42 0 8 0Z"
+      />
+    </svg>
+  );
+}
+function XIcon() {
+  return (
+    <svg viewBox="0 0 1200 1227" fill="currentColor" aria-hidden="true">
+      <path d="M714.163 519.284 1160.89 0h-105.86L667.137 450.887 357.328 0H0l468.492 681.821L0 1226.37h105.866l409.625-476.152 327.181 476.152H1200L714.137 519.284h.026ZM569.165 687.828l-47.468-67.894-377.686-540.24h162.604l304.797 435.991 47.468 67.894 396.2 566.721H892.476L569.165 687.854v-.026Z" />
+    </svg>
+  );
+}
+function YoutubeIcon() {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 0 0 .502 6.186C0 8.07 0 12 0 12s0 3.93.502 5.814a3.016 3.016 0 0 0 2.122 2.136c1.871.505 9.376.505 9.376.505s7.505 0 9.377-.505a3.015 3.015 0 0 0 2.122-2.136C24 15.93 24 12 24 12s0-3.93-.502-5.814zM9.545 15.568V8.432L15.818 12l-6.273 3.568z" />
+    </svg>
+  );
+}
+function LinkedinIcon() {
+  return (
+    <svg viewBox="0 0 256 256" fill="currentColor" aria-hidden="true">
+      <path d="M218.123 218.127h-37.931v-59.403c0-14.165-.253-32.4-19.728-32.4-19.756 0-22.779 15.434-22.779 31.369v60.43h-37.93V95.967h36.413v16.694h.51a39.907 39.907 0 0 1 35.928-19.733c38.445 0 45.533 25.288 45.533 58.186l-.016 67.013ZM56.955 79.27c-12.157.002-22.014-9.852-22.016-22.009-.002-12.157 9.851-22.014 22.008-22.016 12.157-.003 22.014 9.851 22.016 22.008A22.013 22.013 0 0 1 56.955 79.27m18.966 138.858H37.95V95.967h37.97v122.16ZM237.033.018H18.89C8.58-.098.125 8.161-.001 18.471v219.053c.122 10.315 8.576 18.582 18.89 18.474h218.144c10.336.128 18.823-8.139 18.966-18.474V18.454c-.147-10.33-8.635-18.588-18.966-18.453" />
+    </svg>
+  );
+}
+
+export const SOCIAL_ICONS = {
+  github: GithubIcon,
+  x: XIcon,
+  youtube: YoutubeIcon,
+  linkedin: LinkedinIcon,
+};
+const SOCIAL_LABELS = {
+  github: 'GitHub',
+  x: 'X',
+  youtube: 'YouTube',
+  linkedin: 'LinkedIn',
+};
+
+export default function SocialLinks({ socials = [], justify, className = '' }) {
+  const known = socials.filter((s) => s && SOCIAL_ICONS[s.kind]);
+  if (!known.length) return null;
+  return (
+    <Cluster
+      space="var(--s-2)"
+      align="center"
+      justify={justify}
+      className={`velu-socials ${className}`.trim()}
+    >
+      {known.map((s, i) => {
+        const Icon = SOCIAL_ICONS[s.kind];
+        return (
+          <a
+            key={i}
+            href={s.href}
+            target="_blank"
+            rel="noreferrer"
+            aria-label={SOCIAL_LABELS[s.kind] ?? s.kind}
+            className="velu-social"
+            data-kind={s.kind}
+          >
+            <Icon />
+          </a>
+        );
+      })}
+    </Cluster>
+  );
+}

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