@veluai/velu 0.1.15 → 0.2.0

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

@@ -0,0 +1,63 @@
+import React from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * NotFound — the 404 page ("Direction 1 · Classic" from the design):
+ * a big accent-colored numeral, a short message, and a three-action row
+ * (Back to Home / Search the docs / Ask AI). Centered; the host layout
+ * supplies the header + footer. Pure tokens, so light/dark follow
+ * [data-theme] automatically.
+ *
+ * @param {{
+ *   homeHref?: string,
+ *   linkComponent?: React.ElementType,
+ *   onSearch?: () => void,
+ *   onAskAI?: () => void,
+ *   eyebrow?: string, title?: string, body?: string,
+ * }} props
+ */
+export default function NotFound({
+  homeHref = '/',
+  linkComponent = 'a',
+  onSearch,
+  onAskAI,
+  eyebrow = 'Error 404',
+  title = 'This page wandered off',
+  body = 'The page you’re looking for doesn’t exist or may have moved. Pick up the trail below.',
+}) {
+  const Link = linkComponent;
+  return (
+    <section className="velu-404">
+      <p className="velu-404__eyebrow">{eyebrow}</p>
+      <div className="velu-404__num" aria-hidden="true">
+        404
+      </div>
+      <h1 className="velu-404__title">{title}</h1>
+      <p className="velu-404__body">{body}</p>
+      <div className="velu-404__actions">
+        <Link className="velu-404__btn velu-404__btn--primary" href={homeHref}>
+          <span className="velu-404__btn-ic" aria-hidden="true">
+            {resolveIcon('house', { size: '1em' })}
+          </span>
+          Back to Home
+        </Link>
+        {onSearch && (
+          <button type="button" className="velu-404__btn" onClick={onSearch}>
+            <span className="velu-404__btn-ic" aria-hidden="true">
+              {resolveIcon('search', { size: '1em' })}
+            </span>
+            Search the docs
+          </button>
+        )}
+        {onAskAI && (
+          <button type="button" className="velu-404__btn" onClick={onAskAI}>
+            <span className="velu-404__btn-ic" aria-hidden="true">
+              {resolveIcon('sparkles', { size: '1em' })}
+            </span>
+            Ask AI
+          </button>
+        )}
+      </div>
+    </section>
+  );
+}

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

@@ -87,7 +87,7 @@ function ExternalIcon() {
 /** 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 { label, href = '#', icon, external, items, method } = item;
   const base = depth === 0 ? 'velu-sidebar__item' : 'velu-sidebar__subitem';
 
   if (items && items.length) {
@@ -125,7 +125,15 @@ function Node({ item, depth }) {
         aria-current={active ? 'page' : undefined}
         {...linkProps}
       >
-        <Icon icon={icon} />
+        {method ? (
+          <span
+            className={`velu-sidebar__method velu-method-badge--${String(method).toLowerCase()}`}
+          >
+            {method}
+          </span>
+        ) : (
+          <Icon icon={icon} />
+        )}
         <span className="velu-sidebar__label">{label}</span>
         {external ? <ExternalIcon /> : null}
       </LinkTag>

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

@@ -21,6 +21,7 @@ export default function TryItBar({
   path = '',
   cta = 'Try It',
   onTry,
+  loading = false,
   className = '',
   ...rest
 }) {
@@ -79,10 +80,21 @@ export default function TryItBar({
         type="button"
         className="velu-try-it__cta"
         onClick={onTry}
+        data-loading={loading ? 'true' : undefined}
+        disabled={loading || undefined}
+        aria-busy={loading || undefined}
       >
-        {cta}
-        <span className="velu-try-it__cta-icon" aria-hidden="true">
-          {resolveIcon('chevron-right', { size: '1em' })}
+        {/* Two stacked layers swap with a vertical slide: the label slides
+            down and out the bottom while the spinner slides in from the top.
+            overflow:hidden on the button clips both off-screen states. */}
+        <span className="velu-try-it__cta-label">
+          {cta}
+          <span className="velu-try-it__cta-icon" aria-hidden="true">
+            {resolveIcon('chevron-right', { size: '1em' })}
+          </span>
+        </span>
+        <span className="velu-try-it__cta-spinner" aria-hidden="true">
+          {resolveIcon('loader-circle', { size: '1em' })}
         </span>
       </button>
     </Cluster>

package/runtime/velu-ui/components/api-page.css

@@ -0,0 +1,208 @@
+/* Auto-generated OpenAPI reference page. Composes existing API components; this
+   only adds the page-level rhythm, the response tabs, and the playground's
+   live-response panel + body input. All tokens — light/dark via [data-theme]. */
+
+.velu-api-page__title {
+  font-size: var(--f-h1);
+  font-weight: var(--weight-bold);
+  line-height: 1.1;
+  letter-spacing: -0.02em;
+  margin: 0 0 var(--s1);
+}
+.velu-api-page__lede {
+  color: var(--muted-color);
+  margin: 0 0 var(--s2);
+}
+.velu-api-page__tryit {
+  margin-block: var(--s2);
+}
+.velu-api-page__section {
+  margin-block-start: var(--s3);
+}
+.velu-api-page__section > h2 {
+  font-size: var(--f-h3);
+  font-weight: var(--weight-semibold);
+  margin: 0 0 var(--s1);
+}
+.velu-api-page__enum {
+  margin-block-start: var(--s-3);
+  color: var(--muted-color);
+  font-size: var(--f-h6);
+}
+.velu-api-page__enum code {
+  margin-inline-end: var(--s-4);
+}
+
+/* ── Response sections (doc body) ──────────────────────────────────────── */
+/* One default-open accordion per status; the summary shows a status pill +
+   the content-type. */
+.velu-api-resp__head {
+  display: inline-flex;
+  align-items: baseline;
+  gap: var(--s0);
+}
+/* Plain status code — no pill chrome, no per-status color, regular weight. */
+.velu-api-resp__status {
+  font-family: var(--font-mono);
+}
+.velu-api-resp__ctype {
+  color: var(--muted-color);
+  font-family: var(--font-mono);
+  font-size: var(--f-h6);
+}
+.velu-api-resp__desc {
+  color: var(--muted-color);
+  margin: 0 0 var(--s1);
+}
+
+/* ── Playground live-response panel (ApiClient aside) ──────────────────── */
+/* A Body / Header tabbed card reusing the CodeGroup tab chrome
+   (.velu-code-block__*): Body shows a status-colored callout + the response
+   body; Header shows the response headers as a fixed-height scrollable table. */
+.velu-api-resp-panel__content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s1);
+  padding: var(--s1);
+  background: var(--page-bg);
+}
+.velu-api-resp-panel__status {
+  /* The Callout owns its color; keep the weight regular. */
+  font-size: var(--f-h6);
+}
+
+/* Body + Header tabs — fixed height, vertically scrollable, so a long
+   response never makes the panel grow unbounded. */
+.velu-api-resp-headers__scroll,
+.velu-api-resp-body__scroll {
+  max-block-size: 15rem;
+  overflow-y: auto;
+}
+/* The CodeBlock owns its own border/radius; let it fill the scroll box. */
+.velu-api-resp-body__scroll > .velu-code-block {
+  border: 0;
+  border-radius: 0;
+}
+
+/* Response headers table — flush rows with hairline dividers. */
+.velu-api-resp-headers {
+  inline-size: 100%;
+  border-collapse: collapse;
+  font-size: var(--f-h6);
+}
+.velu-api-resp-headers tr + tr td {
+  border-block-start: var(--border-width) solid var(--border-color);
+}
+.velu-api-resp-headers td {
+  padding: var(--s-2) var(--s-1);
+  vertical-align: top;
+  word-break: break-word;
+}
+.velu-api-resp-headers__key {
+  color: var(--muted-color);
+  font-family: var(--font-mono);
+  white-space: nowrap;
+  padding-inline-end: var(--s1) !important;
+}
+.velu-api-resp-headers__val {
+  font-family: var(--font-mono);
+  inline-size: 100%;
+}
+
+/* Editable JSON body in the playground. */
+.velu-api-body-input {
+  inline-size: 100%;
+  resize: vertical;
+  padding: var(--s0);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-sm);
+  background: var(--page-bg);
+  color: var(--text-color);
+  font-family: var(--font-mono);
+  font-size: var(--f-h6);
+  line-height: 1.5;
+}
+
+/* ── Right-rail samples ────────────────────────────────────────────────── */
+/* A TOC needs only ~280px, but the request/response code samples were being
+   cropped in that width. On API pages widen the right rail — both the aside
+   width AND the centre column's right margin read this one var, so they stay
+   in sync. (At < 1024px the @container query hides the rail + zeroes the
+   margin, so this wider value never affects narrow layouts.) */
+.velu-docs-layout[data-api='true'] {
+  --velu-aside-right-width: 28rem; /* 448px */
+}
+
+.velu-api-samples {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s2);
+}
+
+/* Breathing room inside each sample group — the code panels were reading
+   as cramped against the rail edge. */
+.velu-api-samples > * {
+  margin: 0;
+}
+.velu-api-samples :is(pre, code) {
+  font-size: var(--f-h6);
+  line-height: 1.6;
+}
+
+/* ── Try-It playground modal ───────────────────────────────────────────── */
+/* The playground renders above the page on a dimmed, blurred backdrop
+   rather than inline. */
+.velu-api-modal {
+  position: fixed;
+  inset: 0;
+  z-index: 80;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: clamp(var(--s1), 6vh, var(--s5)) var(--s2);
+  overflow-y: auto;
+  background: color-mix(in srgb, var(--page-bg) 35%, rgba(0, 0, 0, 0.55));
+  backdrop-filter: blur(6px) saturate(1.1);
+  -webkit-backdrop-filter: blur(6px) saturate(1.1);
+  animation: velu-api-modal-in 140ms ease-out;
+}
+.velu-api-modal__panel {
+  inline-size: 100%;
+  max-inline-size: 64rem;
+  border-radius: var(--radius-md);
+  box-shadow:
+    0 24px 64px -16px rgba(0, 0, 0, 0.45),
+    0 8px 24px -12px rgba(0, 0, 0, 0.35);
+  animation: velu-api-modal-rise 160ms cubic-bezier(0.2, 0.8, 0.2, 1);
+}
+@keyframes velu-api-modal-in {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@keyframes velu-api-modal-rise {
+  from { opacity: 0; transform: translateY(8px) scale(0.99); }
+  to { opacity: 1; transform: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .velu-api-modal,
+  .velu-api-modal__panel {
+    animation: none;
+  }
+}
+
+/* Compact method pill in the sidebar (replaces the icon for API endpoints). */
+.velu-sidebar__method {
+  flex: none;
+  font-family: var(--font-mono);
+  font-size: 0.6rem;
+  font-weight: var(--weight-bold);
+  letter-spacing: 0.03em;
+  padding: 0.18em 0.36em;
+  border-radius: var(--radius-xs, 4px);
+  text-transform: uppercase;
+}
+.velu-sidebar__method.velu-method-badge--get { color: var(--get-pill-color); background: color-mix(in srgb, var(--get-pill-color) 14%, transparent); }
+.velu-sidebar__method.velu-method-badge--post { color: var(--post-pill-color); background: color-mix(in srgb, var(--post-pill-color) 14%, transparent); }
+.velu-sidebar__method.velu-method-badge--put { color: var(--put-pill-color); background: color-mix(in srgb, var(--put-pill-color) 14%, transparent); }
+.velu-sidebar__method.velu-method-badge--patch { color: var(--patch-pill-color); background: color-mix(in srgb, var(--patch-pill-color) 14%, transparent); }
+.velu-sidebar__method.velu-method-badge--delete { color: var(--delete-pill-color); background: color-mix(in srgb, var(--delete-pill-color) 14%, transparent); }

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

@@ -175,9 +175,11 @@
   color: var(--text-color);
 }
 .velu-try-it__cta {
+  position: relative;
+  overflow: hidden;
   display: inline-flex;
   align-items: center;
-  gap: var(--s-2);
+  justify-content: center;
   padding-block: var(--s-3);
   padding-inline: var(--s0);
   background: var(--method-cta, var(--accent-color));
@@ -194,6 +196,56 @@
 .velu-try-it__cta:hover {
   background: color-mix(in srgb, var(--method-cta, var(--accent-color)) 88%, #000);
 }
+.velu-try-it__cta:disabled {
+  cursor: default;
+}
+
+/* Label (text + chevron) and the loading spinner are two stacked layers
+   that swap with a vertical slide: when loading, the label slides DOWN and
+   out the bottom while the spinner slides IN from the top. overflow:hidden
+   on the button clips the off-screen states. The label stays in normal flow
+   so it fixes the button's width; the spinner overlays it. */
+.velu-try-it__cta-label {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  transition: transform 0.22s ease, opacity 0.18s ease;
+}
+.velu-try-it__cta-spinner {
+  position: absolute;
+  inset: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  transform: translateY(-110%);
+  opacity: 0;
+  transition: transform 0.22s ease, opacity 0.18s ease;
+}
+.velu-try-it__cta[data-loading='true'] .velu-try-it__cta-label {
+  transform: translateY(120%);
+  opacity: 0;
+}
+.velu-try-it__cta[data-loading='true'] .velu-try-it__cta-spinner {
+  transform: translateY(0);
+  opacity: 1;
+}
+.velu-try-it__cta-spinner svg {
+  animation: velu-cta-spin 0.7s linear infinite;
+}
+@keyframes velu-cta-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .velu-try-it__cta-label,
+  .velu-try-it__cta-spinner {
+    transition-duration: 0.01ms;
+  }
+  .velu-try-it__cta-spinner svg {
+    animation-duration: 1.4s;
+  }
+}
 .velu-try-it--get   { --method-cta: var(--get-cta-color); }
 .velu-try-it--post  { --method-cta: var(--post-cta-color); }
 .velu-try-it--put   { --method-cta: var(--put-cta-color); }
@@ -213,6 +265,9 @@
   overflow: hidden;
   max-inline-size: 100%;
   min-inline-size: 0;
+  /* Own query container so the body grid reflows to the client's width
+     (it lives in a modal, outside the docs layout container). */
+  container: api-client / inline-size;
 }
 
 /* Modal close button — sits in its own row at the top of the client,
@@ -262,6 +317,7 @@
    AND natural height; the Cluster's align: flex-start keeps it from
    stretching to the taller TryItBar's height). */
 .velu-api-client__op {
+  position: relative;
   display: flex;
   align-items: center;
   gap: var(--s-2);
@@ -274,6 +330,20 @@
   line-height: var(--lh-h6);
   flex: none;
 }
+/* The clickable trigger when the operation is switchable — a bare button
+   that keeps the same layout as the static row. */
+.velu-api-client__op-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2);
+  margin: 0;
+  padding: 0;
+  background: transparent;
+  border: 0;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
 .velu-api-client__op-label {
   font-weight: var(--weight-medium);
 }
@@ -281,6 +351,55 @@
   display: inline-flex;
   align-items: center;
   color: var(--muted-color);
+  transition: transform 0.15s ease;
+}
+.velu-api-client__op-btn[aria-expanded='true'] .velu-api-client__op-chevron {
+  transform: rotate(180deg);
+}
+
+/* Operation switcher menu — lists every operation in the tab. */
+.velu-api-client__op-menu {
+  position: absolute;
+  inset-block-start: calc(100% + var(--s-3));
+  inset-inline-start: 0;
+  z-index: 5;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin: 0;
+  padding: var(--s-3);
+  list-style: none;
+  min-inline-size: 16rem;
+  max-block-size: 18rem;
+  overflow-y: auto;
+  background: var(--page-bg);
+  border: var(--border-width) solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: 0 12px 32px -12px rgba(0, 0, 0, 0.4);
+}
+.velu-api-client__op-item {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  inline-size: 100%;
+  padding: var(--s-3) var(--s-2);
+  background: transparent;
+  border: 0;
+  border-radius: var(--radius-sm);
+  color: var(--text-color);
+  font: inherit;
+  font-size: var(--f-h6);
+  text-align: start;
+  cursor: pointer;
+}
+.velu-api-client__op-item:hover,
+.velu-api-client__op-item--active {
+  background: var(--surface-color);
+}
+.velu-api-client__op-item-label {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 }
 
 /* Inside ApiClient the outer frame already supplies the box — strip
@@ -297,25 +416,62 @@
   background: transparent;
 }
 
-/* Two-column body. Falls back to single column on narrow widths via
-   a Switcher-style flex-wrap trick: flex-basis with a calc() that
-   flips when the container drops below the threshold. */
+/* Body grid with named areas so the three slots — form / live response /
+   code samples — can be placed AND reordered independently.
+   Wide (the client is its own query container, set on .velu-api-client):
+     form fills the left column; response sits top-right with the samples
+     below it. When there's no response yet, the samples take the whole right
+     column.
+   Narrow (single column): the live response moves ABOVE the form so a Send
+   result is visible without scrolling past the inputs; form then samples
+   follow. */
 .velu-api-client__body {
-  display: flex;
-  flex-wrap: wrap;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  grid-template-areas: 'form aside';
+  align-items: start;
   gap: var(--s2);
   padding: var(--s2);
 }
-.velu-api-client__left,
+.velu-api-client__body[data-has-response='true'] {
+  grid-template-areas:
+    'form response'
+    'form aside';
+}
+.velu-api-client__left {
+  grid-area: form;
+}
+.velu-api-client__response {
+  grid-area: response;
+}
 .velu-api-client__right {
-  flex-grow: 1;
-  flex-basis: calc((40rem - 100%) * 999);
+  grid-area: aside;
+}
+.velu-api-client__left,
+.velu-api-client__right,
+.velu-api-client__response {
   display: flex;
   flex-direction: column;
   gap: var(--s1);
   min-inline-size: 0;
 }
 
+@container api-client (max-width: 40rem) {
+  .velu-api-client__body,
+  .velu-api-client__body[data-has-response='true'] {
+    grid-template-columns: 1fr;
+    grid-template-areas:
+      'form'
+      'aside';
+  }
+  .velu-api-client__body[data-has-response='true'] {
+    grid-template-areas:
+      'response'
+      'form'
+      'aside';
+  }
+}
+
 .velu-api-client__title {
   margin: 0;
   font-size: var(--f-h3);