@veluai/velu 0.1.11 → 0.1.12

package/runtime/velu-ui/components/theme-toggle.css

@@ -1,70 +1,101 @@
-/* ThemeToggle — circular button with a sun/moon glyph; click flips
-   the theme. Geometry is a 32 × 32 circle with an 18 × 18 glyph
-   centred inside. The pill-with-slider design was replaced earlier;
-   only the circle survives now.
-
-   In light mode: --page-bg circle, sun glyph.
-   In dark mode:  --page-bg circle, moon glyph.
-
-   Visibility model: BOTH icons are always rendered, stacked at the
-   same `position: absolute` slot inside the button. Opacity controls
-   which one is visible. We use opacity (not display: none) because:
-
-     1. Stacked icons render at the exact same point — no layout
-        shift when the theme flips.
-     2. Opacity is not touched anywhere else for these elements, so
-        the cascade is trivial — no risk of a stray rule (preflight,
-        utility class, dev-time fallback) overriding `display: none`
-        and revealing the wrong icon.
-     3. Identical markup on server + client → SSR-safe, no hydration
-        mismatch and no icon flash.
-
-   All values are tokens. */
-
-.velu-theme-toggle {
-  /* `relative` so the absolutely-positioned icons inside are
-     anchored to this button, not the page. */
-  position: relative;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  inline-size: 2rem;
-  block-size: 2rem;
-  border: var(--border-width) solid var(--border-color);
-  border-radius: 999px;
-  padding: 0;
-  background: var(--page-bg);
-  cursor: pointer;
-  transition: border-color 0.12s ease, background 0.12s ease;
-}
-.velu-theme-toggle:hover {
-  border-color: var(--accent-color);
-}
-
-/* Both icons stack here, centred. Default opacity 0 — the per-theme
-   rules below switch one on. */
-.velu-theme-toggle__icon {
-  position: absolute;
-  inset-block-start: 50%;
-  inset-inline-start: 50%;
-  inline-size: 1.125rem;
-  block-size: 1.125rem;
-  margin-block-start: -0.5625rem;     /* half of block-size */
-  margin-inline-start: -0.5625rem;    /* half of inline-size */
-  color: var(--text-color);
-  opacity: 0;
-  transition: opacity 0.2s ease;
-  pointer-events: none;
-}
-
-/* Default (light) → sun on. */
-.velu-theme-toggle__icon--sun {
-  opacity: 1;
-}
-/* Dark theme → moon on, sun off. */
-[data-theme='dark'] .velu-theme-toggle__icon--sun {
-  opacity: 0;
-}
-[data-theme='dark'] .velu-theme-toggle__icon--moon {
-  opacity: 1;
-}
+/* ThemeToggle — circular button with a sun/moon glyph; click flips
+   the theme. Geometry is a 32 × 32 circle with an 18 × 18 glyph
+   centred inside. The pill-with-slider design was replaced earlier;
+   only the circle survives now.
+
+   In light mode: --page-bg circle, sun glyph.
+   In dark mode:  --page-bg circle, moon glyph.
+
+   Visibility model: BOTH icons are always rendered, stacked at the
+   same `position: absolute` slot inside the button. Opacity controls
+   which one is visible. We use opacity (not display: none) because:
+
+     1. Stacked icons render at the exact same point — no layout
+        shift when the theme flips.
+     2. Opacity is not touched anywhere else for these elements, so
+        the cascade is trivial — no risk of a stray rule (preflight,
+        utility class, dev-time fallback) overriding `display: none`
+        and revealing the wrong icon.
+     3. Identical markup on server + client → SSR-safe, no hydration
+        mismatch and no icon flash.
+
+   All values are tokens. */
+
+.velu-theme-toggle {
+  /* `relative` so the absolutely-positioned icons inside are
+     anchored to this button, not the page. */
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: 2rem;
+  block-size: 2rem;
+  border: var(--border-width) solid var(--border-color);
+  border-radius: 999px;
+  padding: 0;
+  background: var(--page-bg);
+  cursor: pointer;
+  transition: border-color 0.12s ease, background 0.12s ease,
+    transform 0.18s cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+.velu-theme-toggle:hover {
+  border-color: var(--accent-color);
+}
+/* Tactile press feedback on click. */
+.velu-theme-toggle:active {
+  transform: scale(0.9);
+}
+
+/* Both icons stack here, centred. Each animates in/out on a theme flip:
+   the hidden glyph is faded, shrunk, and rotated off its axis; the active
+   one springs to full size at 0deg. Centring is done with margins (above),
+   so `transform` is free to drive the rotate/scale animation. */
+.velu-theme-toggle__icon {
+  position: absolute;
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+  inline-size: 1.125rem;
+  block-size: 1.125rem;
+  margin-block-start: -0.5625rem;     /* half of block-size */
+  margin-inline-start: -0.5625rem;    /* half of inline-size */
+  color: var(--text-color);
+  opacity: 0;
+  transition: opacity 0.28s ease,
+    transform 0.4s cubic-bezier(0.34, 1.56, 0.64, 1);
+  pointer-events: none;
+}
+
+/* Hidden state per glyph — sun spins out clockwise, moon anti-clockwise,
+   so the swap reads as one rotating through the other. */
+.velu-theme-toggle__icon--sun {
+  transform: rotate(90deg) scale(0.4);
+}
+.velu-theme-toggle__icon--moon {
+  transform: rotate(-90deg) scale(0.4);
+}
+
+/* Exactly one glyph is shown — the sun in light, the moon in dark — at full
+   size, upright. Higher specificity than the hidden defaults above, so it
+   wins for whichever glyph the active theme selects. */
+:root:not([data-theme='dark']) .velu-theme-toggle__icon--sun,
+[data-theme='dark'] .velu-theme-toggle__icon--moon {
+  opacity: 1;
+  transform: rotate(0deg) scale(1);
+}
+
+/* Honour reduced-motion: keep a plain crossfade — no spin, scale, or press. */
+@media (prefers-reduced-motion: reduce) {
+  .velu-theme-toggle {
+    transition: border-color 0.12s ease, background 0.12s ease;
+  }
+  .velu-theme-toggle:active {
+    transform: none;
+  }
+  .velu-theme-toggle__icon {
+    transition: opacity 0.2s ease;
+  }
+  .velu-theme-toggle__icon--sun,
+  .velu-theme-toggle__icon--moon {
+    transform: none;
+  }
+}

package/runtime/velu-ui/index.js

@@ -1,46 +1,46 @@
-export { default as Stack } from './primitives/Stack.jsx';
-export { default as Switcher } from './primitives/Switcher.jsx';
-export { default as Cluster } from './primitives/Cluster.jsx';
-export { default as ThemeToggle } from './components/ThemeToggle.jsx';
-export { default as Sidebar } from './components/Sidebar.jsx';
-export { default as NavSelect } from './components/NavSelect.jsx';
-export { default as Toc } from './components/Toc.jsx';
-export { default as TocBar } from './components/TocBar.jsx';
-export { default as Callout } from './components/Callout.jsx';
-export { default as ErrorCard } from './components/ErrorCard.jsx';
-export {
-  default as Accordion,
-  AccordionGroup,
-} from './components/Accordion.jsx';
-export { default as Card, CardGroup } from './components/Card.jsx';
-export { default as Columns } from './components/Columns.jsx';
-export { default as Field } from './components/Field.jsx';
-export { default as Prompt } from './components/Prompt.jsx';
-export { default as Steps, Step } from './components/Steps.jsx';
-export { default as Tree, Folder, File } from './components/Tree.jsx';
-export { default as MethodBadge } from './components/MethodBadge.jsx';
-export { default as ApiPath } from './components/ApiPath.jsx';
-export { default as TryItBar } from './components/TryItBar.jsx';
-export { default as ApiField } from './components/ApiField.jsx';
-export { default as ApiClient } from './components/ApiClient.jsx';
-export { default as ApiSidebar } from './components/ApiSidebar.jsx';
-export { default as AskBar } from './components/AskBar.jsx';
-export { default as Chatbot } from './components/Chatbot.jsx';
-export { default as PageFeedback } from './components/PageFeedback.jsx';
-export { default as PageNav } from './components/PageNav.jsx';
-export { default as PageFooter } from './components/PageFooter.jsx';
-export { default as PoweredBy } from './components/PoweredBy.jsx';
-export { default as resolveIcon } from './lib/resolveIcon.jsx';
-export {
-  default as PageHeader,
-  VeluMark,
-} from './components/PageHeader.jsx';
-export { default as Search } from './components/Search.jsx';
-export { default as Image } from './components/Image.jsx';
-export {
-  default as CodeBlock,
-  CodeGroup,
-} from './components/CodeBlock.jsx';
-export {
-  default as defaultMdxComponents,
-} from './mdx-components.jsx';
+export { default as Stack } from './primitives/Stack.jsx';
+export { default as Switcher } from './primitives/Switcher.jsx';
+export { default as Cluster } from './primitives/Cluster.jsx';
+export { default as ThemeToggle } from './components/ThemeToggle.jsx';
+export { default as Sidebar } from './components/Sidebar.jsx';
+export { default as NavSelect } from './components/NavSelect.jsx';
+export { default as Toc } from './components/Toc.jsx';
+export { default as TocBar } from './components/TocBar.jsx';
+export { default as Callout } from './components/Callout.jsx';
+export { default as ErrorCard } from './components/ErrorCard.jsx';
+export {
+  default as Accordion,
+  AccordionGroup,
+} from './components/Accordion.jsx';
+export { default as Card, CardGroup } from './components/Card.jsx';
+export { default as Columns } from './components/Columns.jsx';
+export { default as Field } from './components/Field.jsx';
+export { default as Prompt } from './components/Prompt.jsx';
+export { default as Steps, Step } from './components/Steps.jsx';
+export { default as Tree, Folder, File } from './components/Tree.jsx';
+export { default as MethodBadge } from './components/MethodBadge.jsx';
+export { default as ApiPath } from './components/ApiPath.jsx';
+export { default as TryItBar } from './components/TryItBar.jsx';
+export { default as ApiField } from './components/ApiField.jsx';
+export { default as ApiClient } from './components/ApiClient.jsx';
+export { default as ApiSidebar } from './components/ApiSidebar.jsx';
+export { default as AskBar } from './components/AskBar.jsx';
+export { default as Chatbot } from './components/Chatbot.jsx';
+export { default as PageFeedback } from './components/PageFeedback.jsx';
+export { default as PageNav } from './components/PageNav.jsx';
+export { default as PageFooter } from './components/PageFooter.jsx';
+export { default as PoweredBy } from './components/PoweredBy.jsx';
+export { default as resolveIcon } from './lib/resolveIcon.jsx';
+export {
+  default as PageHeader,
+  VeluMark,
+} from './components/PageHeader.jsx';
+export { default as Search } from './components/Search.jsx';
+export { default as Image } from './components/Image.jsx';
+export {
+  default as CodeBlock,
+  CodeGroup,
+} from './components/CodeBlock.jsx';
+export {
+  default as defaultMdxComponents,
+} from './mdx-components.jsx';

package/runtime/velu-ui/lib/component-schemas.js

@@ -1,100 +1,100 @@
-// Per-component option schemas — the props whose wrong value would otherwise
-// render incorrectly *silently*. Deliberately small and high-signal; extend a
-// component's entry here when it gains a new constrained option.
-//
-// Pure data + a pure validator (no React, no other imports) so BOTH sides can
-// use it: the live MDX registry (velu-ui/mdx-components.jsx) validates at
-// render time, and `velu validate` (velu-cli) imports this same module to
-// statically check literal attributes — one source of truth, no drift.
-
-// Canonical accepted values (must match the components):
-//   Callout  — VARIANTS keys; the component is CASE-SENSITIVE (VARIANTS[type]).
-//   MethodBadge — METHODS; the component lower-cases the input first.
-export const CALLOUT_TYPES = ['note', 'warning', 'info', 'tip', 'check', 'danger', 'callout'];
-export const METHOD_NAMES = ['get', 'post', 'put', 'patch', 'delete'];
-
-// schema: { enums: { prop: { values, caseSensitive } }, required: [prop, …] }
-const SCHEMAS = {
-  Callout: { enums: { type: { values: CALLOUT_TYPES, caseSensitive: true } } },
-  MethodBadge: { enums: { method: { values: METHOD_NAMES, caseSensitive: false } } },
-  ApiPath: { enums: { method: { values: METHOD_NAMES, caseSensitive: false } } },
-  Image: { required: ['src'] },
-};
-
-// Smallest edit distance match within a set (for "did you mean"). Tiny inputs.
-function closest(value, values) {
-  const v = String(value).toLowerCase();
-  let best = null;
-  let bestD = Infinity;
-  for (const cand of values) {
-    const a = v;
-    const b = cand.toLowerCase();
-    // inline Levenshtein
-    const m = a.length;
-    const n = b.length;
-    const d = Array.from({ length: n + 1 }, (_, i) => i);
-    for (let i = 1; i <= m; i++) {
-      let prev = d[0];
-      d[0] = i;
-      for (let j = 1; j <= n; j++) {
-        const tmp = d[j];
-        d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
-        prev = tmp;
-      }
-    }
-    if (d[n] < bestD) {
-      bestD = d[n];
-      best = cand;
-    }
-  }
-  return bestD <= 3 ? best : null;
-}
-
-/**
- * Validate a component's props against its schema.
- * @param {string} name   component tag name
- * @param {object} props   props passed to it
- * @param {{ checkRequired?: boolean }} [opts]  static callers pass
- *        checkRequired:false because a prop supplied via a {expression}
- *        isn't a literal they can see, so "missing required" would be a
- *        false positive.
- * @returns an issue-shaped object (category 'invalid-props') or null if valid.
- *   { category, title, detail, hint, suggestion }
- */
-export function validateProps(name, props = {}, opts = {}) {
-  const { checkRequired = true } = opts;
-  const schema = SCHEMAS[name];
-  if (!schema) return null;
-
-  for (const req of checkRequired ? schema.required || [] : []) {
-    const v = props[req];
-    if (v == null || v === '') {
-      return {
-        category: 'invalid-props',
-        title: `<${name}> is missing the required "${req}" prop`,
-        hint: `Add ${req}="…" to the component.`,
-      };
-    }
-  }
-
-  for (const [prop, rule] of Object.entries(schema.enums || {})) {
-    if (!(prop in props) || props[prop] == null) continue;
-    const raw = props[prop];
-    const ok = rule.caseSensitive
-      ? rule.values.includes(raw)
-      : rule.values.map((s) => s.toLowerCase()).includes(String(raw).toLowerCase());
-    if (!ok) {
-      const guess = closest(raw, rule.values);
-      return {
-        category: 'invalid-props',
-        title: `Invalid "${prop}" on <${name}>: "${raw}"`,
-        detail: `Expected one of: ${rule.values.join(', ')}.`,
-        hint: guess ? `Did you mean "${guess}"?` : '',
-      };
-    }
-  }
-
-  return null;
-}
-
-export default validateProps;
+// Per-component option schemas — the props whose wrong value would otherwise
+// render incorrectly *silently*. Deliberately small and high-signal; extend a
+// component's entry here when it gains a new constrained option.
+//
+// Pure data + a pure validator (no React, no other imports) so BOTH sides can
+// use it: the live MDX registry (velu-ui/mdx-components.jsx) validates at
+// render time, and `velu validate` (velu-cli) imports this same module to
+// statically check literal attributes — one source of truth, no drift.
+
+// Canonical accepted values (must match the components):
+//   Callout  — VARIANTS keys; the component is CASE-SENSITIVE (VARIANTS[type]).
+//   MethodBadge — METHODS; the component lower-cases the input first.
+export const CALLOUT_TYPES = ['note', 'warning', 'info', 'tip', 'check', 'danger', 'callout'];
+export const METHOD_NAMES = ['get', 'post', 'put', 'patch', 'delete'];
+
+// schema: { enums: { prop: { values, caseSensitive } }, required: [prop, …] }
+const SCHEMAS = {
+  Callout: { enums: { type: { values: CALLOUT_TYPES, caseSensitive: true } } },
+  MethodBadge: { enums: { method: { values: METHOD_NAMES, caseSensitive: false } } },
+  ApiPath: { enums: { method: { values: METHOD_NAMES, caseSensitive: false } } },
+  Image: { required: ['src'] },
+};
+
+// Smallest edit distance match within a set (for "did you mean"). Tiny inputs.
+function closest(value, values) {
+  const v = String(value).toLowerCase();
+  let best = null;
+  let bestD = Infinity;
+  for (const cand of values) {
+    const a = v;
+    const b = cand.toLowerCase();
+    // inline Levenshtein
+    const m = a.length;
+    const n = b.length;
+    const d = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+      let prev = d[0];
+      d[0] = i;
+      for (let j = 1; j <= n; j++) {
+        const tmp = d[j];
+        d[j] = Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+        prev = tmp;
+      }
+    }
+    if (d[n] < bestD) {
+      bestD = d[n];
+      best = cand;
+    }
+  }
+  return bestD <= 3 ? best : null;
+}
+
+/**
+ * Validate a component's props against its schema.
+ * @param {string} name   component tag name
+ * @param {object} props   props passed to it
+ * @param {{ checkRequired?: boolean }} [opts]  static callers pass
+ *        checkRequired:false because a prop supplied via a {expression}
+ *        isn't a literal they can see, so "missing required" would be a
+ *        false positive.
+ * @returns an issue-shaped object (category 'invalid-props') or null if valid.
+ *   { category, title, detail, hint, suggestion }
+ */
+export function validateProps(name, props = {}, opts = {}) {
+  const { checkRequired = true } = opts;
+  const schema = SCHEMAS[name];
+  if (!schema) return null;
+
+  for (const req of checkRequired ? schema.required || [] : []) {
+    const v = props[req];
+    if (v == null || v === '') {
+      return {
+        category: 'invalid-props',
+        title: `<${name}> is missing the required "${req}" prop`,
+        hint: `Add ${req}="…" to the component.`,
+      };
+    }
+  }
+
+  for (const [prop, rule] of Object.entries(schema.enums || {})) {
+    if (!(prop in props) || props[prop] == null) continue;
+    const raw = props[prop];
+    const ok = rule.caseSensitive
+      ? rule.values.includes(raw)
+      : rule.values.map((s) => s.toLowerCase()).includes(String(raw).toLowerCase());
+    if (!ok) {
+      const guess = closest(raw, rule.values);
+      return {
+        category: 'invalid-props',
+        title: `Invalid "${prop}" on <${name}>: "${raw}"`,
+        detail: `Expected one of: ${rule.values.join(', ')}.`,
+        hint: guess ? `Did you mean "${guess}"?` : '',
+      };
+    }
+  }
+
+  return null;
+}
+
+export default validateProps;

package/runtime/velu-ui/lib/copyText.js

@@ -1,64 +1,64 @@
-/**
- * copyText — copy a string to the clipboard, working in BOTH secure and
- * insecure contexts.
- *
- * `navigator.clipboard` only exists in a secure context (HTTPS or
- * localhost). On a plain-HTTP origin — e.g. previewing the dev server
- * over the LAN at http://<ip>:8358 on a phone — it's `undefined`, so a
- * `if (!navigator.clipboard) return` guard makes copy buttons silently
- * no-op. This util falls back to the legacy `execCommand('copy')` via a
- * hidden textarea so copy still works on those origins.
- *
- * Must be called from a user gesture (click) — both paths require it.
- * Returns a Promise: resolves on success, rejects on failure.
- */
-export default function copyText(text) {
-  const str = String(text ?? '');
-
-  // Preferred path — async Clipboard API (secure contexts only).
-  if (
-    typeof navigator !== 'undefined' &&
-    navigator.clipboard &&
-    typeof window !== 'undefined' &&
-    window.isSecureContext
-  ) {
-    return navigator.clipboard.writeText(str);
-  }
-
-  // Fallback — hidden <textarea> + execCommand, for insecure origins.
-  return new Promise((resolve, reject) => {
-    if (typeof document === 'undefined') {
-      reject(new Error('copyText: no document'));
-      return;
-    }
-    const ta = document.createElement('textarea');
-    ta.value = str;
-    ta.setAttribute('readonly', '');
-    // Keep it out of view and inert, but still selectable.
-    ta.style.position = 'fixed';
-    ta.style.top = '0';
-    ta.style.left = '0';
-    ta.style.inlineSize = '1px';
-    ta.style.blockSize = '1px';
-    ta.style.padding = '0';
-    ta.style.border = 'none';
-    ta.style.opacity = '0';
-    document.body.appendChild(ta);
-    ta.focus();
-    ta.select();
-    try {
-      ta.setSelectionRange(0, str.length);
-    } catch {
-      /* some browsers reject setSelectionRange on a readonly field */
-    }
-    let ok = false;
-    try {
-      ok = document.execCommand('copy');
-    } catch {
-      ok = false;
-    }
-    document.body.removeChild(ta);
-    if (ok) resolve();
-    else reject(new Error('copyText: execCommand copy failed'));
-  });
-}
+/**
+ * copyText — copy a string to the clipboard, working in BOTH secure and
+ * insecure contexts.
+ *
+ * `navigator.clipboard` only exists in a secure context (HTTPS or
+ * localhost). On a plain-HTTP origin — e.g. previewing the dev server
+ * over the LAN at http://<ip>:8358 on a phone — it's `undefined`, so a
+ * `if (!navigator.clipboard) return` guard makes copy buttons silently
+ * no-op. This util falls back to the legacy `execCommand('copy')` via a
+ * hidden textarea so copy still works on those origins.
+ *
+ * Must be called from a user gesture (click) — both paths require it.
+ * Returns a Promise: resolves on success, rejects on failure.
+ */
+export default function copyText(text) {
+  const str = String(text ?? '');
+
+  // Preferred path — async Clipboard API (secure contexts only).
+  if (
+    typeof navigator !== 'undefined' &&
+    navigator.clipboard &&
+    typeof window !== 'undefined' &&
+    window.isSecureContext
+  ) {
+    return navigator.clipboard.writeText(str);
+  }
+
+  // Fallback — hidden <textarea> + execCommand, for insecure origins.
+  return new Promise((resolve, reject) => {
+    if (typeof document === 'undefined') {
+      reject(new Error('copyText: no document'));
+      return;
+    }
+    const ta = document.createElement('textarea');
+    ta.value = str;
+    ta.setAttribute('readonly', '');
+    // Keep it out of view and inert, but still selectable.
+    ta.style.position = 'fixed';
+    ta.style.top = '0';
+    ta.style.left = '0';
+    ta.style.inlineSize = '1px';
+    ta.style.blockSize = '1px';
+    ta.style.padding = '0';
+    ta.style.border = 'none';
+    ta.style.opacity = '0';
+    document.body.appendChild(ta);
+    ta.focus();
+    ta.select();
+    try {
+      ta.setSelectionRange(0, str.length);
+    } catch {
+      /* some browsers reject setSelectionRange on a readonly field */
+    }
+    let ok = false;
+    try {
+      ok = document.execCommand('copy');
+    } catch {
+      ok = false;
+    }
+    document.body.removeChild(ta);
+    if (ok) resolve();
+    else reject(new Error('copyText: execCommand copy failed'));
+  });
+}