@veluai/velu 0.1.0

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

@@ -0,0 +1,63 @@
+import React from 'react';
+import Cluster from '../primitives/Cluster.jsx';
+
+/**
+ * ApiPath — monospace URL path renderer. The path is split into two
+ * kinds of segments and laid out via <Cluster>:
+ *
+ *  - hardcoded segment   the static chunks ("/project/preview/")
+ *  - dynamic segment     the {param} placeholders (rendered as
+ *                        method-tinted pills)
+ *
+ *   <ApiPath method="POST" path="/project/preview/{projectId}" />
+ *   → [ "/project/preview/" ] [ {projectId} ]
+ *
+ * Hardcoded chunks stay intact (never break mid-text), so narrow widths
+ * wrap between segments rather than mid-word. Dynamic pills wrap to a
+ * new line as a unit.
+ */
+
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+
+export default function ApiPath({
+  method = 'GET',
+  path = '',
+  className = '',
+  ...rest
+}) {
+  const key = String(method).toLowerCase();
+  const safe = METHODS.includes(key) ? key : 'get';
+
+  // Split only on {param} groups — keep the hardcoded text between
+  // params as single segments so narrow-width wrapping breaks at the
+  // segment boundary, never mid-word.
+  const tokens = String(path).split(/(\{[^}]+\})/).filter(Boolean);
+
+  return (
+    <Cluster
+      as="span"
+      space="var(--s-2)"
+      align="center"
+      className={`velu-api-path ${className}`.trim()}
+      {...rest}
+    >
+      {tokens.map((tok, i) => {
+        if (tok.startsWith('{') && tok.endsWith('}')) {
+          return (
+            <span
+              key={i}
+              className={`velu-api-path__param velu-api-path__param--${safe}`}
+            >
+              {tok}
+            </span>
+          );
+        }
+        return (
+          <span key={i} className="velu-api-path__segment">
+            {tok}
+          </span>
+        );
+      })}
+    </Cluster>
+  );
+}

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

@@ -0,0 +1,122 @@
+import React from 'react';
+import Stack from '../primitives/Stack.jsx';
+import resolveIcon from '../lib/resolveIcon.jsx';
+import MethodBadge from './MethodBadge.jsx';
+
+/**
+ * ApiSidebar — navigation for API reference pages. Like <Sidebar> but
+ * flat (no nested folders): every entry is a single endpoint shown as
+ * a method pill + name. Entries are organized into groups, each with
+ * an optional icon.
+ *
+ *   <ApiSidebar
+ *     activeHref="/api/trigger"
+ *     linkComponent={RouterLink}
+ *     sections={[
+ *       {
+ *         title: 'Admin',
+ *         icon: 'rocket',
+ *         endpoints: [
+ *           { method: 'POST',   label: 'Trigger', href: '/api/trigger' },
+ *           { method: 'GET',    label: 'Get deployment-status',
+ *             href: '/api/status' },
+ *           { method: 'DELETE', label: 'Trigger Preview deployment',
+ *             href: '/api/preview' },
+ *         ],
+ *       },
+ *     ]}
+ *   />
+ *
+ * Vertical rhythm = the Stack primitive (DRY, same as <Sidebar>);
+ * api.css holds only the rail / active state / row layout / icon size.
+ * Selection is route-driven (`endpoint.href === activeHref`, or
+ * `endpoint.active: true`). Router-agnostic via `linkComponent`.
+ *
+ * @typedef {Object} ApiEndpoint
+ * @property {string} method   HTTP method — drives the MethodBadge color
+ * @property {string} label    endpoint display name
+ * @property {string} [href]
+ * @property {boolean} [active]
+ *
+ * @param {{ sections: { title?: string, icon?: string|React.ReactNode,
+ *           endpoints: ApiEndpoint[] }[], activeHref?: string,
+ *           linkComponent?: React.ElementType, className?: string }} props
+ */
+
+const Ctx = React.createContext({ activeHref: undefined, Link: 'a' });
+
+function Icon({ icon }) {
+  const node = resolveIcon(icon);
+  return node ? (
+    <span className="velu-api-sidebar__icon" aria-hidden="true">
+      {node}
+    </span>
+  ) : null;
+}
+
+function Endpoint({ endpoint }) {
+  const { activeHref, Link } = React.useContext(Ctx);
+  const { method = 'GET', label, href = '#', active } = endpoint;
+  const isActive = Boolean(
+    active || (href != null && href === activeHref),
+  );
+  const cls = `velu-api-sidebar__item${
+    isActive ? ' velu-api-sidebar__item--active' : ''
+  }`;
+  return (
+    <li>
+      <Link
+        className={cls}
+        href={href}
+        aria-current={isActive ? 'page' : undefined}
+      >
+        <MethodBadge method={method} />
+        <span className="velu-api-sidebar__label">{label}</span>
+      </Link>
+    </li>
+  );
+}
+
+export default function ApiSidebar({
+  sections = [],
+  activeHref,
+  linkComponent = 'a',
+  className = '',
+  ...rest
+}) {
+  const ctx = React.useMemo(
+    () => ({ activeHref, Link: linkComponent }),
+    [activeHref, linkComponent],
+  );
+  return (
+    <Ctx.Provider value={ctx}>
+      <Stack
+        as="nav"
+        space="var(--s1)"
+        className={`velu-api-sidebar ${className}`.trim()}
+        aria-label="API reference"
+        {...rest}
+      >
+        {sections.map((section, i) => (
+          <React.Fragment key={i}>
+            {section.title != null && (
+              <h5 className="velu-api-sidebar__section">
+                <Icon icon={section.icon} />
+                {section.title}
+              </h5>
+            )}
+            <Stack
+              as="ul"
+              space="var(--s0)"
+              className="velu-api-sidebar__list"
+            >
+              {(section.endpoints ?? []).map((ep, j) => (
+                <Endpoint key={j} endpoint={ep} />
+              ))}
+            </Stack>
+          </React.Fragment>
+        ))}
+      </Stack>
+    </Ctx.Provider>
+  );
+}

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

@@ -0,0 +1,71 @@
+import React, { useState } from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * AskBar — an "ask a question" input card.
+ *
+ *   <AskBar onSubmit={(q) => …} />
+ *
+ * The component owns only the card visuals (border, glow-on-focus,
+ * multi-line input, circular send button). PLACEMENT is the consumer's
+ * job — the docs page pins it `position: absolute` to the bottom of
+ * the article column so content scrolls behind its opaque surface.
+ *
+ *  - `placeholder` input placeholder (default "Ask a question…")
+ *  - `onSubmit(value)` fired on the send button or Enter (Shift+Enter
+ *    inserts a newline). Dummy-friendly — omit it and the bar is inert.
+ *
+ * The send affordance is a circular accent button with an up-arrow;
+ * the card border glows in the accent color while the input is focused.
+ */
+
+export default function AskBar({
+  placeholder = 'Ask a question…',
+  onSubmit,
+  className = '',
+  ...rest
+}) {
+  const [value, setValue] = useState('');
+
+  function submit() {
+    const q = value.trim();
+    if (!q) return;
+    onSubmit?.(q);
+    setValue('');
+  }
+
+  function onKeyDown(e) {
+    // Enter sends; Shift+Enter inserts a newline.
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      submit();
+    }
+  }
+
+  // Disable the send button until there's non-whitespace input. The
+  // CSS reads :disabled to render it muted + un-hoverable; React reads
+  // the attribute to short-circuit clicks too.
+  const isEmpty = value.trim().length === 0;
+
+  return (
+    <div className={`velu-ask-bar ${className}`.trim()} {...rest}>
+      <textarea
+        className="velu-ask-bar__input"
+        placeholder={placeholder}
+        value={value}
+        onChange={(e) => setValue(e.target.value)}
+        onKeyDown={onKeyDown}
+        rows={2}
+      />
+      <button
+        type="button"
+        className="velu-ask-bar__send"
+        onClick={submit}
+        disabled={isEmpty}
+        aria-label="Ask"
+      >
+        {resolveIcon('arrow-up', { size: '1em' })}
+      </button>
+    </div>
+  );
+}

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

@@ -0,0 +1,114 @@
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * Callout — admonition box (note/warning/info/tip/check/danger/callout).
+ *
+ * Fully tokenized: each `type` maps to its Figma bg + stroke token pair
+ * (base.css, light + dark), so theming is automatic via [data-theme]. Border
+ * + icon use the stroke; surface uses the bg; body uses --text-color.
+ * Spacing/radius from the modular scale.
+ *
+ * Layout: the icon is FLOATED into the text flow (not a fixed column) — it
+ * sits on the first line and the text wraps beside it, then subsequent/wrapped
+ * lines flow back UNDER the icon (no hanging indent). `display: flow-root`
+ * contains the float cleanly (no clipping, no clearfix hack).
+ *
+ * Content-driven & extensible: `icon` is a **lucide icon id string**
+ * (kebab-case), resolved by the shared resolveIcon util (also accepts a
+ * node). `stroke` / `bg` override the variant colors for custom callouts.
+ *
+ * SSR-safe & presentational (no effects/refs).
+ *
+ * @param {{ type?: 'note'|'warning'|'info'|'tip'|'check'|'danger'|'callout',
+ *   icon?: string|React.ReactNode, stroke?: string, bg?: string,
+ *   children: React.ReactNode, className?: string }} props
+ */
+
+// Variant icon defaults are lucide IDS (not components) → one resolution path.
+const VARIANTS = {
+  note: { bg: '--note-bg-color', stroke: '--note-stroke-color', icon: 'pencil' },
+  warning: {
+    bg: '--warning-bg-color',
+    stroke: '--warning-stroke-color',
+    icon: 'triangle-alert',
+  },
+  info: { bg: '--info-bg-color', stroke: '--info-stroke-color', icon: 'info' },
+  tip: {
+    bg: '--tip-bg-color',
+    stroke: '--tip-stroke-color',
+    icon: 'lightbulb',
+  },
+  check: {
+    bg: '--check-bg-color',
+    stroke: '--check-stroke-color',
+    icon: 'circle-check',
+  },
+  danger: {
+    bg: '--danger-bg-color',
+    stroke: '--danger-stroke-color',
+    icon: 'shield-alert',
+  },
+  callout: {
+    bg: '--callout-bg-color',
+    stroke: '--callout-stroke-color',
+    icon: 'message-circle',
+  },
+};
+
+export default function Callout({
+  type = 'note',
+  icon,
+  stroke,
+  bg,
+  children,
+  className = '',
+  style,
+  ...rest
+}) {
+  const v = VARIANTS[type] || VARIANTS.note;
+  const strokeColor = stroke ?? `var(${v.stroke})`;
+  const bgColor = bg ?? `var(${v.bg})`;
+  // size only; stroke weight comes from the global --icon-stroke token
+  // (.lucide rule in base.css), not set per-icon.
+  const iconNode = resolveIcon(icon ?? v.icon, { size: '1em' });
+
+  return (
+    <div
+      className={className}
+      style={{
+        display: 'flow-root', // contains the floated icon, no clipping
+        padding: 'var(--s0) var(--s3)',
+        background: bgColor,
+        border: `var(--border-width) solid ${strokeColor}`,
+        borderRadius: 'var(--radius-sm)',
+        color: 'var(--text-color)',
+        fontSize: 'var(--f-body)',
+        lineHeight: 'var(--lh-body)',
+        ...style,
+      }}
+      {...rest}
+    >
+      {iconNode && (
+        <span
+          aria-hidden="true"
+          style={{
+            float: 'left',
+            display: 'inline-flex',
+            alignItems: 'center',
+            // one line-box tall (body font-size × body line-height token) so
+            // the icon is centered on the FIRST line; text wraps beside it
+            // then flows back under it (no hanging indent).
+            blockSize: 'calc(var(--f-body) * var(--lh-body))',
+            marginInlineEnd: 'var(--s-1)',
+            color: strokeColor,
+            fontSize: 'var(--f-body)',
+          }}
+        >
+          {iconNode}
+        </span>
+      )}
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,131 @@
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+import Switcher from '../primitives/Switcher.jsx';
+
+/**
+ * Card + CardGroup — content / horizontal / image / CTA cards.
+ *
+ * The card itself is NEVER a link and has NO hover state. The only
+ * interactive element is the CTA: pass `cta={{ label, href }}` to render a
+ * single "Click Here ›" link. Everything else is static presentation.
+ *
+ * Fully tokenized (border-width, border-color, radius scale, spacing, type,
+ * line-height, accent, icon-stroke) → light/dark automatic via [data-theme].
+ * SSR-safe & presentational.
+ *
+ * Variants (combinable):
+ *  - basic: icon (accent, --f-h2) + title (--f-h4) + body
+ *  - `horizontal`: icon vertically centered on the left, title+body right
+ *  - `img`: image fills the top, clipped to the radius
+ *  - `cta`: { label, href } → the single clickable "Click Here ›" link
+ *
+ * `icon` is a lucide id string (shared resolveIcon).
+ *
+ * @param {{ title?: React.ReactNode, icon?: string, horizontal?: boolean,
+ *   img?: string, imgAlt?: string,
+ *   cta?: {label: React.ReactNode, href: string},
+ *   children?: React.ReactNode, className?: string }} props
+ */
+
+export function Card({
+  title,
+  icon,
+  horizontal = false,
+  img,
+  imgAlt = '',
+  cta,
+  children,
+  className = '',
+  ...rest
+}) {
+  const cls = [
+    'velu-card',
+    horizontal && 'velu-card--horizontal',
+    img && 'velu-card--image',
+    cta && 'velu-card--cta',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const iconEl = icon ? (
+    <span className="velu-card__icon" aria-hidden="true">
+      {resolveIcon(icon, { size: '1em' })}
+    </span>
+  ) : null;
+
+  const ctaEl = cta ? (
+    <a className="velu-card__cta" href={cta.href}>
+      {cta.label}
+      <span className="velu-card__cta-icon" aria-hidden="true">
+        {resolveIcon('chevron-right', { size: '1em' })}
+      </span>
+    </a>
+  ) : null;
+
+  const titleEl = title ? (
+    <div className="velu-card__title">{title}</div>
+  ) : null;
+  const textEl = children ? (
+    <div className="velu-card__text">{children}</div>
+  ) : null;
+
+  return (
+    <div className={cls} {...rest}>
+      {img && (
+        <div className="velu-card__media">
+          <img src={img} alt={imgAlt} loading="lazy" />
+        </div>
+      )}
+
+      <div className="velu-card__body">
+        {horizontal ? (
+          <>
+            {iconEl}
+            <div className="velu-card__content">
+              {titleEl}
+              {textEl}
+              {ctaEl}
+            </div>
+          </>
+        ) : (
+          <>
+            {!img ? iconEl : null}
+            {titleEl}
+            {textEl}
+            {ctaEl}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * CardGroup — a row of Cards that switches to a FULL vertical stack the
+ * moment any one card would fall below the per-card minimum. Thin wrapper
+ * over the Switcher primitive: just supplies `min` (Switcher does the
+ * count-aware threshold math). `limit` hard-caps items per row.
+ */
+export function CardGroup({
+  space = 'var(--s0)',
+  min = 'var(--card-min, 18ch)',
+  limit = 3,
+  children,
+  className = '',
+  ...rest
+}) {
+  return (
+    <Switcher
+      className={`velu-card-group ${className}`.trim()}
+      space={space}
+      min={min}
+      limit={limit}
+      {...rest}
+    >
+      {children}
+    </Switcher>
+  );
+}
+
+export default Card;