@veluai/velu 0.1.0

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

@@ -0,0 +1,375 @@
+import React, {
+  Children,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { Highlight } from 'prism-react-renderer';
+import { ensureLang, hasLang, resolveLang } from '../lib/prism-loader.js';
+import { iconForLang } from '../lib/lang-icons.jsx';
+import resolveIcon from '../lib/resolveIcon.jsx';
+import copyText from '../lib/copyText.js';
+
+/**
+ * CodeBlock + CodeGroup — syntax-highlighted code with optional filename
+ * label or tabbed group of language alternatives.
+ *
+ * Standalone (with filename):
+ *   <CodeBlock filename="index.js" language="javascript" lineNumbers
+ *              icon="file-code">
+ *     {`let greeting = function (name) {
+ *   console.log(\`Hello, \${name}!\`);
+ * };`}
+ *   </CodeBlock>
+ *
+ * Grouped (tabbed):
+ *   <CodeGroup>
+ *     <CodeBlock title="Javascript" language="javascript">{js}</CodeBlock>
+ *     <CodeBlock title="Ruby"       language="ruby">{rb}</CodeBlock>
+ *     <CodeBlock title="Python"     language="python">{py}</CodeBlock>
+ *   </CodeGroup>
+ *
+ * Highlighting uses prism-react-renderer with an empty theme — token CSS
+ * classes (`.token.<type>`) are styled in code-block.css using
+ * `--syntax-*` tokens that switch per [data-theme]. Languages outside the
+ * prism-react-renderer default bundle are LAZY-LOADED from prismjs on
+ * first use via the loader in lib/prism-loader.js — SSR (and the first
+ * client render) shows plain code for unloaded langs, then upgrades to
+ * highlighted once the lang's prism file has fetched. No 1.4 MB bundle
+ * tax for languages the page doesn't actually use.
+ */
+
+// Empty theme so prism-react-renderer emits class names but no inline
+// colors — all styling lives in code-block.css.
+const NO_THEME = { plain: {}, styles: [] };
+
+function normalize(code) {
+  if (typeof code !== 'string') return '';
+  return code.replace(/^\n+/, '').replace(/\n+$/, '');
+}
+
+// Parse a highlight spec into a Set of 1-based line numbers.
+//   "1-3,5,7-9"  → {1,2,3,5,7,8,9}
+//   [1, 2, 5]    → {1,2,5}
+//   null / ''    → null (nothing highlighted)
+function parseHighlight(spec) {
+  if (spec == null || spec === '') return null;
+  if (Array.isArray(spec)) {
+    const s = new Set();
+    for (const n of spec) {
+      const v = Number(n);
+      if (Number.isFinite(v)) s.add(v);
+    }
+    return s.size ? s : null;
+  }
+  if (typeof spec !== 'string') return null;
+  const s = new Set();
+  for (const part of spec.split(',')) {
+    const t = part.trim();
+    if (!t) continue;
+    const dash = t.indexOf('-');
+    if (dash > 0) {
+      const a = parseInt(t.slice(0, dash), 10);
+      const b = parseInt(t.slice(dash + 1), 10);
+      if (Number.isFinite(a) && Number.isFinite(b)) {
+        const lo = Math.min(a, b);
+        const hi = Math.max(a, b);
+        for (let i = lo; i <= hi; i++) s.add(i);
+      }
+    } else {
+      const n = parseInt(t, 10);
+      if (Number.isFinite(n)) s.add(n);
+    }
+  }
+  return s.size ? s : null;
+}
+
+function TabLabel({ icon, label }) {
+  return (
+    <>
+      {icon != null && (
+        <span className="velu-code-block__tab-icon" aria-hidden="true">
+          {typeof icon === 'string' ? resolveIcon(icon, { size: '1em' }) : icon}
+        </span>
+      )}
+      <span className="velu-code-block__tab-label">{label}</span>
+    </>
+  );
+}
+
+function Tab({ active, onClick, icon, label }) {
+  const cls = `velu-code-block__tab${
+    active ? ' velu-code-block__tab--active' : ''
+  }`;
+  if (onClick) {
+    return (
+      <button
+        type="button"
+        role="tab"
+        aria-selected={active}
+        className={cls}
+        onClick={onClick}
+      >
+        <TabLabel icon={icon} label={label} />
+      </button>
+    );
+  }
+  return (
+    <div className={cls}>
+      <TabLabel icon={icon} label={label} />
+    </div>
+  );
+}
+
+function CopyButton({ code }) {
+  const [copied, setCopied] = useState(false);
+
+  function copy() {
+    copyText(code).then(
+      () => {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1400);
+      },
+      () => {
+        /* clipboard write rejected (permissions / no focus) — silently noop */
+      },
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={copy}
+      className="velu-code-block__copy"
+      aria-label={copied ? 'Copied' : 'Copy code'}
+      title={copied ? 'Copied' : 'Copy'}
+    >
+      {resolveIcon(copied ? 'check' : 'copy', { size: '1em' })}
+    </button>
+  );
+}
+
+function CodeBody({ code, language, lineNumbers, highlight }) {
+  const canonical = resolveLang(language) || 'text';
+  const highlightSet = parseHighlight(highlight);
+
+  // Initial render uses 'text' (no highlighting) — this guarantees SSR
+  // and the first client render produce identical HTML regardless of
+  // what's in Prism.languages on each side (which may diverge in dev
+  // mode due to HMR leaving cached grammar mutations behind). After
+  // hydration, useEffect kicks ensureLang and bumps to the real lang —
+  // highlighting then upgrades in a normal state-update render.
+  const [renderLang, setRenderLang] = useState('text');
+
+  useEffect(() => {
+    let cancelled = false;
+    ensureLang(canonical).then(() => {
+      if (!cancelled && hasLang(canonical)) setRenderLang(canonical);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [canonical]);
+
+  return (
+    <div className="velu-code-block__body">
+      <CopyButton code={normalize(code)} />
+      <Highlight
+        code={normalize(code)}
+        language={renderLang}
+        theme={NO_THEME}
+      >
+        {({ tokens, getLineProps, getTokenProps }) => (
+          <pre className="velu-code-block__pre">
+            {tokens.map((line, i) => {
+              const lineProps = getLineProps({ line });
+              const isHi = highlightSet?.has(i + 1);
+              return (
+                <div
+                  key={i}
+                  {...lineProps}
+                  className={`velu-code-block__line ${
+                    lineProps.className || ''
+                  } ${isHi ? 'velu-code-block__line--highlight' : ''}`.trim()}
+                >
+                  {lineNumbers && (
+                    <span
+                      className="velu-code-block__line-number"
+                      aria-hidden="true"
+                    >
+                      {i + 1}
+                    </span>
+                  )}
+                  <span className="velu-code-block__line-code">
+                    {line.map((token, j) => (
+                      <span key={j} {...getTokenProps({ token })} />
+                    ))}
+                  </span>
+                </div>
+              );
+            })}
+          </pre>
+        )}
+      </Highlight>
+    </div>
+  );
+}
+
+// Explicit `icon` always wins. `withIcon` defaults to true, so an icon
+// is auto-rendered from `lib/lang-icons.jsx` based on the language;
+// pass `withIcon={false}` to suppress.
+function pickIcon({ icon, withIcon, language }) {
+  if (icon != null) return icon;
+  if (withIcon === false) return null;
+  return iconForLang(language);
+}
+
+export function CodeBlock({
+  filename,
+  title,
+  language = 'text',
+  icon,
+  withIcon = true,
+  lineNumbers = false,
+  highlight,
+  children,
+  className = '',
+  ...rest
+}) {
+  const cls = `velu-code-block ${className}`.trim();
+  const label = filename || title;
+  const tabIcon = pickIcon({ icon, withIcon, language });
+  return (
+    <div className={cls} {...rest}>
+      {label && (
+        <div className="velu-code-block__header">
+          <Tab active icon={tabIcon} label={label} />
+        </div>
+      )}
+      <CodeBody
+        code={children}
+        language={language}
+        lineNumbers={lineNumbers}
+        highlight={highlight}
+      />
+    </div>
+  );
+}
+CodeBlock.displayName = 'CodeBlock';
+
+// Hook that tracks whether a scrollable element can scroll further left
+// or right. Resolves layout-driven overflow without media queries.
+function useScrollEdges(ref) {
+  const [canLeft, setCanLeft] = useState(false);
+  const [canRight, setCanRight] = useState(false);
+
+  const update = useCallback(() => {
+    const el = ref.current;
+    if (!el) return;
+    setCanLeft(el.scrollLeft > 1);
+    setCanRight(el.scrollLeft + el.clientWidth < el.scrollWidth - 1);
+  }, [ref]);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    update();
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    // Also observe each child so adding/removing tabs retriggers update.
+    for (const c of el.children) ro.observe(c);
+    el.addEventListener('scroll', update, { passive: true });
+    return () => {
+      ro.disconnect();
+      el.removeEventListener('scroll', update);
+    };
+  }, [ref, update]);
+
+  return { canLeft, canRight, update };
+}
+
+export function CodeGroup({
+  children,
+  className = '',
+  defaultIndex = 0,
+  ...rest
+}) {
+  const blocks = Children.toArray(children).filter(
+    (c) =>
+      isValidElement(c) &&
+      (c.type === CodeBlock || c.type?.displayName === 'CodeBlock'),
+  );
+  const [active, setActive] = useState(defaultIndex);
+  const tabsRef = useRef(null);
+  const { canLeft, canRight } = useScrollEdges(tabsRef);
+  const block = blocks[active] || blocks[0];
+  if (!block) return null;
+
+  const {
+    language = 'text',
+    lineNumbers = false,
+    highlight,
+    children: code,
+  } = block.props;
+  const cls = `velu-code-block velu-code-block--group ${className}`.trim();
+
+  function scrollDir(dir) {
+    tabsRef.current?.scrollBy({ left: dir * 160, behavior: 'smooth' });
+  }
+
+  return (
+    <div className={cls} {...rest}>
+      <div className="velu-code-block__header">
+        {canLeft && (
+          <button
+            type="button"
+            className="velu-code-block__nav"
+            onClick={() => scrollDir(-1)}
+            aria-label="Scroll tabs left"
+          >
+            {resolveIcon('chevron-left', { size: '1em' })}
+          </button>
+        )}
+        <div
+          ref={tabsRef}
+          className="velu-code-block__tabs"
+          role="tablist"
+        >
+          {blocks.map((b, i) => {
+            const { title, icon, withIcon, language } = b.props;
+            const tabIcon = pickIcon({ icon, withIcon, language });
+            return (
+              <Tab
+                key={i}
+                active={i === active}
+                onClick={() => setActive(i)}
+                icon={tabIcon}
+                label={title || `Tab ${i + 1}`}
+              />
+            );
+          })}
+        </div>
+        {canRight && (
+          <button
+            type="button"
+            className="velu-code-block__nav"
+            onClick={() => scrollDir(1)}
+            aria-label="Scroll tabs right"
+          >
+            {resolveIcon('chevron-right', { size: '1em' })}
+          </button>
+        )}
+      </div>
+      <CodeBody
+        code={code}
+        language={language}
+        lineNumbers={lineNumbers}
+        highlight={highlight}
+      />
+    </div>
+  );
+}
+
+export default CodeBlock;

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

@@ -0,0 +1,56 @@
+import React from 'react';
+import Switcher from '../primitives/Switcher.jsx';
+
+/**
+ * Columns — generic column layout for heterogeneous content (Card,
+ * Callout, CodeBlock, Image, plain JSX — anything). Thin wrapper over
+ * the Switcher primitive, mirroring CardGroup's responsive pattern but
+ * without coupling to any specific child component.
+ *
+ *  <Columns cols={2}>
+ *    <Card title="A" />
+ *    <CodeBlock language="js">{snippet}</CodeBlock>
+ *  </Columns>
+ *
+ * Behavior:
+ *  - `cols` (default 2) — max number of items in a row. Acts as
+ *    Switcher's `limit`: passing more children than `cols` collapses
+ *    the layout to a full vertical stack (matches CardGroup).
+ *  - `min` — per-item minimum width (default --columns-min token, 18ch).
+ *    The instant any one column would fall below `min`, all columns
+ *    stack vertically. Driven by Switcher's count-aware threshold
+ *    math; no media queries.
+ *  - `space` — gap between items (default --s1).
+ *
+ * Want multiple items in a single column? Wrap them in a Stack:
+ *
+ *  <Columns cols={3}>
+ *    <Card title="left" />
+ *    <Stack>
+ *      <Card title="middle top" />
+ *      <Card title="middle bottom" />
+ *    </Stack>
+ *    <Callout>right</Callout>
+ *  </Columns>
+ */
+
+export default function Columns({
+  cols = 2,
+  space = 'var(--s1)',
+  min = 'var(--columns-min, 18ch)',
+  children,
+  className = '',
+  ...rest
+}) {
+  return (
+    <Switcher
+      className={`velu-columns ${className}`.trim()}
+      space={space}
+      min={min}
+      limit={cols}
+      {...rest}
+    >
+      {children}
+    </Switcher>
+  );
+}

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

@@ -0,0 +1,81 @@
+import React from 'react';
+import Cluster from '../primitives/Cluster.jsx';
+
+/**
+ * Field — a documentation row for an API parameter / config option.
+ *
+ *   <Field name="depth" pre="GET" type="number" required default={3}
+ *          post="optional"
+ *   >
+ *     An example of a parameter field. Description text wraps below
+ *     the chip row.
+ *   </Field>
+ *
+ * Layout (left → right, all in a single flex-wrap row):
+ *   [pre chip] [name] [type chip] [required pill]
+ *   [default: VALUE] [post chip]      followed by the description
+ *
+ * - `name`     — required-ish; the parameter identifier (accent, bold, mono)
+ * - `pre`      — small monospace chip rendered before `name` (e.g. method
+ *                or namespace). React-node or string.
+ * - `type`     — small monospace chip after `name` (e.g. "string", "number")
+ * - `required` — boolean → renders the red "required" pill
+ * - `default`  — value rendered as `default: <value>` in italic monospace
+ *                (renamed locally because `default` is a reserved word)
+ * - `post`     — trailing chip after default
+ * - `children` — description block beneath the chip row
+ *
+ * Sibling Field elements get a hairline divider via CSS — drop them next
+ * to each other and the separators appear; no wrapper required.
+ *
+ * Fully tokenized: chips use --surface-color, required pill mixes with
+ * --accent-color, default is --muted-color italic. Light/dark
+ * automatic via [data-theme] like the rest of velu-ui.
+ */
+
+export default function Field({
+  name,
+  pre,
+  type,
+  required = false,
+  default: defaultValue,
+  post,
+  children,
+  className = '',
+  ...rest
+}) {
+  const hasDefault = defaultValue !== undefined && defaultValue !== null;
+  return (
+    <div className={`velu-field ${className}`.trim()} {...rest}>
+      {/* Cluster handles the wrap-friendly inline row layout — chips +
+          name + type + required + default + post — with a 16px gap and
+          baseline alignment so the bold name doesn't shift vertically
+          relative to its sibling chips. */}
+      <Cluster space="var(--s0)" align="baseline">
+        {pre != null && (
+          <span className="velu-field__chip">{pre}</span>
+        )}
+        {name != null && (
+          <span className="velu-field__name">{name}</span>
+        )}
+        {type != null && (
+          <span className="velu-field__chip">{type}</span>
+        )}
+        {required && (
+          <span className="velu-field__required">required</span>
+        )}
+        {hasDefault && (
+          <span className="velu-field__default">
+            default: {String(defaultValue)}
+          </span>
+        )}
+        {post != null && (
+          <span className="velu-field__chip">{post}</span>
+        )}
+      </Cluster>
+      {children != null && children !== false && (
+        <div className="velu-field__body">{children}</div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,163 @@
+import React from 'react';
+
+/**
+ * Image — image content with optional caption and decorative chrome.
+ *
+ * Variants:
+ *  - plain      <Image src alt />
+ *  - captioned  <Image src alt caption="..." />
+ *  - window     <Image src alt chrome="window" caption?/>
+ *  - frame      <Image src alt chrome="frame"  caption?/>
+ *
+ * Window/frame use a pure SVG+CSS liquid-glass pattern (lucasromerodb/
+ * liquid-glass-effect-macos): an SVG <filter> with feTurbulence →
+ * feDisplacementMap provides real refraction; a 4-layer div stack
+ * (effect/tint/shine/content) builds the glass material.
+ * No library, no SSR/hydration concerns — pure declarative DOM + CSS.
+ */
+
+const GLASS_FILTER_ID = 'velu-glass-distortion';
+
+function GlassFilterDefs() {
+  return (
+    <svg
+      aria-hidden="true"
+      style={{ position: 'absolute', inlineSize: 0, blockSize: 0 }}
+    >
+      {/* Turbulence-driven displacement of the backdrop. Used via
+          `backdrop-filter: url(#...)` so SourceGraphic IS the backdrop. */}
+      <filter
+        id={GLASS_FILTER_ID}
+        x="0%"
+        y="0%"
+        width="100%"
+        height="100%"
+        filterUnits="objectBoundingBox"
+      >
+        <feTurbulence
+          type="fractalNoise"
+          baseFrequency="0.008 0.008"
+          numOctaves="2"
+          seed="5"
+          result="noise"
+        />
+        <feDisplacementMap
+          in="SourceGraphic"
+          in2="noise"
+          scale="80"
+          xChannelSelector="R"
+          yChannelSelector="G"
+        />
+      </filter>
+    </svg>
+  );
+}
+
+function Glass({ className = '', children }) {
+  return (
+    <div className={`velu-glass ${className}`.trim()}>
+      <div className="velu-glass__effect" aria-hidden="true" />
+      <div className="velu-glass__tint" aria-hidden="true" />
+      <div className="velu-glass__shine" aria-hidden="true" />
+      <div className="velu-glass__content">{children}</div>
+    </div>
+  );
+}
+
+function WindowChrome({ src, alt }) {
+  return (
+    <div className="velu-image__window">
+      <GlassFilterDefs />
+      <div className="velu-image__glow" aria-hidden="true" />
+      <div className="velu-image__noise" aria-hidden="true" />
+      <Glass className="velu-image__window-surface">
+        <div className="velu-image__window-inner">
+          <Glass className="velu-image__chrome">
+            <span className="velu-image__dots" aria-hidden="true">
+              <span className="velu-image__dot velu-image__dot--red" />
+              <span className="velu-image__dot velu-image__dot--yellow" />
+              <span className="velu-image__dot velu-image__dot--green" />
+            </span>
+            <span className="velu-image__urlbar" aria-hidden="true" />
+          </Glass>
+          <img
+            src={src}
+            alt={alt}
+            loading="lazy"
+            className="velu-image__img velu-image__img--flush"
+          />
+        </div>
+      </Glass>
+    </div>
+  );
+}
+
+function DeviceFrame({ src, alt }) {
+  return (
+    <div className="velu-image__frame">
+      <GlassFilterDefs />
+      <div className="velu-image__glow" aria-hidden="true" />
+      <div className="velu-image__noise" aria-hidden="true" />
+      <Glass className="velu-image__frame-bezel">
+        <div className="velu-image__frame-screen">
+          <img
+            src={src}
+            alt={alt}
+            loading="lazy"
+            className="velu-image__img velu-image__img--flush"
+          />
+        </div>
+      </Glass>
+    </div>
+  );
+}
+
+export default function Image({
+  src,
+  alt = '',
+  caption,
+  chrome,
+  className = '',
+  ...rest
+}) {
+  // Fall back to the caption for alt text when no alt is provided, so a
+  // captioned image stays accessible without forcing duplication.
+  // Only string captions are usable as alt — React-node captions are
+  // ignored here.
+  const effectiveAlt = alt || (typeof caption === 'string' ? caption : '');
+
+  let body;
+  let variantClass = '';
+  if (chrome === 'window') {
+    body = <WindowChrome src={src} alt={effectiveAlt} />;
+    variantClass = 'velu-image--chrome';
+  } else if (chrome === 'frame') {
+    body = <DeviceFrame src={src} alt={effectiveAlt} />;
+    variantClass = 'velu-image--chrome';
+  } else {
+    body = (
+      <img
+        src={src}
+        alt={effectiveAlt}
+        loading="lazy"
+        className="velu-image__img"
+      />
+    );
+  }
+
+  const cls = `velu-image ${variantClass} ${className}`.trim();
+
+  if (caption) {
+    return (
+      <figure className={cls} {...rest}>
+        {body}
+        <figcaption className="velu-image__caption">{caption}</figcaption>
+      </figure>
+    );
+  }
+  return (
+    <div className={cls} {...rest}>
+      {body}
+    </div>
+  );
+}

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

@@ -0,0 +1,31 @@
+import React from 'react';
+
+/**
+ * MethodBadge — colored monospace pill showing an HTTP method.
+ *
+ *   <MethodBadge method="POST" />
+ *
+ * Colors come from the per-method tokens in base.css:
+ *   --post-pill-color / --post-pill-stroke-color  (and post-cta-color)
+ *   --get-* / --put-* / --delete-* / --patch-*
+ *
+ * Used by <ApiPath>, <TryItBar>, and <ApiClient>; also exportable
+ * standalone for inline endpoint references in prose.
+ */
+
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+
+export default function MethodBadge({
+  method = 'GET',
+  className = '',
+  ...rest
+}) {
+  const key = String(method).toLowerCase();
+  const safe = METHODS.includes(key) ? key : 'get';
+  const cls = `velu-method-badge velu-method-badge--${safe} ${className}`.trim();
+  return (
+    <span className={cls} {...rest}>
+      {String(method).toUpperCase()}
+    </span>
+  );
+}