@veluai/velu 0.1.0

package/runtime/velu-ui/components/toc-bar.css

@@ -0,0 +1,234 @@
+/* TocBar — narrow-layout counterpart to <Toc>.
+
+   Rendered always (so SSR / hydration markup matches at every size)
+   but VISIBLE only at narrow widths via a container query against the
+   docs layout. At wide widths the right-rail <Toc> takes over and
+   this bar is `display: none` — no media queries.
+
+   All values are tokens; light/dark via [data-theme]. */
+
+.velu-toc-bar {
+  /* Hidden by default — the wide layout uses the right-rail <Toc>.
+     Container query below flips it on at narrow widths. */
+  display: none;
+  /* Sticky to the top of the article so it stays in view as the
+     user scrolls through the page. Sits below the page header. */
+  position: sticky;
+  inset-block-start: var(--velu-header-height);
+  z-index: 5;
+  /* Frosted-glass background — same recipe as the scrolled header
+     (.velu-header--scrolled in page-header.css). 75% --page-bg + a
+     saturate/blur backdrop lets article content show through faintly
+     so the bar reads as a layer over the page rather than a solid
+     band. The dropdown below uses the same recipe so the bar +
+     expanded list look like one continuous translucent fabric. */
+  background: color-mix(in srgb, var(--page-bg) 75%, transparent);
+  backdrop-filter: saturate(140%) blur(12px);
+  -webkit-backdrop-filter: saturate(140%) blur(12px);
+  border-block-end: var(--border-width) solid var(--surface-color);
+  /* base.css's global `* { max-width: 66ch }` (the prose measure)
+     would otherwise cap the bar AND its dropdown well short of the
+     viewport edge — explicitly override it for the bar's subtree. */
+  max-inline-size: none;
+}
+.velu-toc-bar *,
+.velu-toc-bar {
+  max-inline-size: none;
+}
+/* When expanded, the dropdown's own border-block-end terminates
+   the combined bar+dropdown — suppress the bar's bottom border so
+   there isn't a double-printed line between bar and dropdown. The
+   toggle's `border-block-end` still draws the divider between the
+   toggle row and the list. Also drop the frosted recipe — the
+   dropdown reveals article content underneath, and a translucent
+   bar+dropdown would let the article text bleed through the menu.
+   Solid --page-bg keeps the list readable in either theme. */
+.velu-toc-bar[data-expanded='true'] {
+  border-block-end-color: transparent;
+  background: var(--page-bg);
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+}
+.velu-toc-bar[data-expanded='true'] .velu-toc-bar__list {
+  background: var(--page-bg);
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+}
+
+@container docs (max-width: 1024px) {
+  .velu-toc-bar {
+    display: block;
+  }
+}
+
+/* ── Toggle (collapsed header) ─────────────────────────────────────── */
+.velu-toc-bar__toggle {
+  display: flex;
+  align-items: center;
+  gap: var(--s-2);
+  inline-size: 100%;
+  /* Block padding fixed at 8px so the bar hugs its single-row
+     content tightly; inline padding stays on the spacing scale. */
+  padding-block: 0.5rem;
+  padding-inline: var(--s3);
+  /* Divider between the toggle row and the expanded list lives
+     here (not on the list) so it spans the toggle's full inline
+     size — touching the sidebar's vertical border on the left
+     instead of being inset by the list's leading margin. Hidden
+     when collapsed (TocBar's own bottom border terminates the
+     row). */
+  border-width: 0 0 var(--border-width) 0;
+  border-style: solid;
+  border-color: var(--surface-color);
+  background: transparent;
+  color: var(--text-color);
+  font: inherit;
+  font-size: var(--f-h5);
+  text-align: start;
+  cursor: pointer;
+}
+/* No interior divider between the toggle row and the dropdown —
+   they're one continuous fabric. The only horizontal line in the
+   expanded state is the dropdown's own border-block-end, at the
+   very bottom of the combined element. */
+.velu-toc-bar__toggle {
+  border-block-end-color: transparent;
+}
+
+/* Reading-progress ring — SVG circle whose stroke fills as the
+   reader scrolls. Sized like a chip so it reads as a peer of the
+   chevron at the other edge of the toggle row. */
+.velu-toc-bar__progress {
+  flex: none;
+  inline-size: 1.25em;
+  block-size: 1.25em;
+}
+
+.velu-toc-bar__title {
+  flex: 1;
+  min-inline-size: 0;
+}
+
+.velu-toc-bar__chevron {
+  flex: none;
+  inline-size: var(--f-body);
+  block-size: var(--f-body);
+  color: var(--muted-color);
+  transition: transform 0.2s ease;
+}
+.velu-toc-bar[data-expanded='true'] .velu-toc-bar__chevron {
+  transform: rotate(180deg);
+}
+
+/* ── Expanded list (overlay) ───────────────────────────────────────── */
+/* `position: absolute` overlay anchored to the bottom of the sticky
+   TocBar — the list does NOT participate in the article's normal
+   flow. That's the critical bit: when the user expands/collapses
+   the dropdown, the article does not reflow. Scroll targets
+   computed against the article (e.g. for a "scroll to this heading"
+   click) therefore remain valid regardless of dropdown state. */
+.velu-toc-bar__list {
+  /* `absolute` (relative to the sticky TocBar root) so the dropdown
+     stays glued to the bar — no measurement gap between bar's bottom
+     and dropdown's top. The bar itself is full-width of the centre
+     column, which at narrow widths reaches the viewport's right edge
+     (centre's `margin-inline-end: 0` via @container), so the dropdown
+     also reaches the viewport right edge via `inset-inline-end: 0`. */
+  position: absolute;
+  inset-block-start: 100%;
+  inset-inline-start: 0;
+  inset-inline-end: 0;
+  margin: 0;
+  list-style: none;
+  /* Vertical breathing room around items. */
+  padding-block: var(--s-1);
+  /* Items are pushed --s3 off the bar's left edge so they sit at
+     the rail's x position (drawn by ::before below). */
+  padding-inline-start: var(--s3);
+  padding-inline-end: 0;
+  /* Collapsed state — invisible, lifted slightly upward and out
+     of pointer events. The `[data-expanded='true']` rule below
+     animates these back on open. The list is ALWAYS in the DOM
+     (not conditionally rendered) so the transition can run both
+     directions. `visibility` is delayed via the transition's
+     0.18s tail so it switches AFTER the opacity fade completes
+     when closing. */
+  opacity: 0;
+  visibility: hidden;
+  transform: translateY(-0.25rem);
+  transform-origin: 0 0;
+  pointer-events: none;
+  transition:
+    opacity 0.18s ease,
+    transform 0.18s ease,
+    visibility 0s linear 0.18s;
+  /* Same frosted recipe as the bar above (no shadow, no top
+     border) so the open dropdown reads as the bar EXTENDED DOWN,
+     not a separate floating panel. */
+  background: color-mix(in srgb, var(--page-bg) 75%, transparent);
+  backdrop-filter: saturate(140%) blur(12px);
+  -webkit-backdrop-filter: saturate(140%) blur(12px);
+  /* Bottom border terminates the combined bar+dropdown against
+     the article below. Spans the FULL list width so it touches
+     the sidebar's vertical border on the left. */
+  border-block-end: var(--border-width) solid var(--surface-color);
+  /* Cap height so a long TOC scrolls INSIDE the dropdown rather
+     than overflowing the viewport. The active row is auto-scrolled
+     into view by `scrollIntoNearestView` in TocBar.jsx. */
+  max-block-size: min(
+    75vh,
+    calc(100vh - var(--velu-scroll-offset, 5rem) - 2rem)
+  );
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  /* Above the article but below sticky chrome above it. */
+  z-index: 4;
+}
+
+/* Expanded state — fade + slide into view. The opacity / transform
+   transitions run forward; visibility flips to `visible` instantly
+   so the dropdown is interactive immediately when opening. */
+.velu-toc-bar[data-expanded='true'] .velu-toc-bar__list {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+  pointer-events: auto;
+  transition:
+    opacity 0.18s ease,
+    transform 0.18s ease,
+    visibility 0s;
+}
+
+/* Vertical guide rail — inset by --s3 from the list's leading edge,
+   tall enough to span the items (between the padding-block bands).
+   Active item's 2px accent border (below) overlays it at its row. */
+.velu-toc-bar__list::before {
+  content: '';
+  position: absolute;
+  inset-block-start: var(--s-1);
+  inset-block-end: var(--s-1);
+  inset-inline-start: var(--s3);
+  inline-size: 1px;
+  background: var(--border-color);
+}
+
+.velu-toc-bar__item {
+  /* The list's own `padding-inline-start: var(--s3)` already places
+     each item's leading edge AT the rail's x position, so the
+     active item's 2px accent border overlays the rail at its row
+     with no negative-margin tricks. */
+  padding-block: var(--s-2);
+  padding-inline-end: var(--s3);
+  border-inline-start: 2px solid transparent;
+  color: var(--text-color);
+  font-size: var(--f-h6);
+  cursor: pointer;
+  transition: color 0.12s ease, border-color 0.12s ease;
+}
+.velu-toc-bar__item:hover {
+  color: var(--accent-color);
+}
+.velu-toc-bar__item--active {
+  color: var(--accent-color);
+  border-inline-start-color: var(--accent-color);
+}

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

@@ -0,0 +1,49 @@
+/* Tree — file-tree display. Monospace + small line-height for the
+   "code editor sidebar" look. All values are tokens; light/dark via
+   [data-theme]. */
+
+.velu-tree {
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+  font-size: var(--f-body);
+  line-height: 1.6;
+  color: var(--text-color);
+}
+
+.velu-tree__item {
+  display: flex;
+  align-items: center;
+  gap: var(--s-1);
+  padding-block: var(--s-4);
+}
+
+/* Folder summary acts as the click target — strip the native
+   disclosure triangle and make the whole row look like a button. */
+.velu-tree__item--folder {
+  cursor: pointer;
+  list-style: none;
+}
+.velu-tree__item--folder::-webkit-details-marker {
+  display: none;
+}
+
+.velu-tree__icon {
+  display: inline-flex;
+  align-items: center;
+  flex: none;
+  inline-size: var(--icon-size-lg);
+  block-size: var(--icon-size-lg);
+}
+
+.velu-tree__label {
+  font-family: inherit;
+}
+
+/* Nested children sit inside a div with a vertical rail (border-inline-
+   start) — that's the line connecting a folder's siblings. The
+   margin/padding offset places the rail roughly under the parent
+   folder icon's horizontal center. */
+.velu-tree__nest {
+  margin-inline-start: 0.625em;
+  padding-inline-start: 1em;
+  border-inline-start: var(--border-width) solid var(--border-color);
+}

package/runtime/velu-ui/index.js

@@ -0,0 +1,45 @@
+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 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/copyText.js

@@ -0,0 +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>:5173 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'));
+  });
+}

package/runtime/velu-ui/lib/lang-icons.jsx

@@ -0,0 +1,156 @@
+import React from 'react';
+import {
+  SiJavascript,
+  SiTypescript,
+  SiReact,
+  SiPython,
+  SiRuby,
+  SiGo,
+  SiRust,
+  SiOpenjdk,
+  SiSharp,
+  SiC,
+  SiCplusplus,
+  SiPhp,
+  SiSwift,
+  SiKotlin,
+  SiScala,
+  SiDart,
+  SiR,
+  SiHaskell,
+  SiElixir,
+  SiErlang,
+  SiLua,
+  SiPerl,
+  SiJulia,
+  SiOcaml,
+  SiFsharp,
+  SiNim,
+  SiZig,
+  SiClojure,
+  SiCoffeescript,
+  SiHtml5,
+  SiCss,
+  SiVuedotjs,
+  SiSvelte,
+  SiSolid,
+  SiJson,
+  SiYaml,
+  SiToml,
+  SiGraphql,
+  SiMarkdown,
+  SiLatex,
+  SiAsciidoctor,
+  SiGnubash,
+  SiFishshell,
+  SiNodedotjs,
+  SiMysql,
+  SiPostgresql,
+  SiSqlite,
+  SiMongodb,
+  SiRedis,
+  SiDocker,
+  SiKubernetes,
+  SiNginx,
+  SiApache,
+} from '@icons-pack/react-simple-icons';
+import { resolveLang } from './prism-loader.js';
+
+/**
+ * Language → icon mapping.
+ *
+ * Brand icons (JS / Python / Ruby / etc.) come from
+ * @icons-pack/react-simple-icons — monochrome SVG, tree-shaken, scales to
+ * the surrounding font size via `size="1em"`. Anything without a brand
+ * icon falls back to a semantic lucide id (string) which `resolveIcon`
+ * handles downstream.
+ *
+ * Tab's icon prop already accepts either a React node or a lucide id, so
+ * we can mix both freely here.
+ */
+
+// Brand icons (React components from simple-icons).
+const BRAND = {
+  javascript: SiJavascript,
+  typescript: SiTypescript,
+  jsx: SiReact,
+  tsx: SiReact,
+  python: SiPython,
+  ruby: SiRuby,
+  go: SiGo,
+  rust: SiRust,
+  java: SiOpenjdk,
+  csharp: SiSharp,
+  c: SiC,
+  cpp: SiCplusplus,
+  php: SiPhp,
+  swift: SiSwift,
+  kotlin: SiKotlin,
+  scala: SiScala,
+  dart: SiDart,
+  r: SiR,
+  haskell: SiHaskell,
+  elixir: SiElixir,
+  erlang: SiErlang,
+  lua: SiLua,
+  perl: SiPerl,
+  julia: SiJulia,
+  ocaml: SiOcaml,
+  fsharp: SiFsharp,
+  nim: SiNim,
+  zig: SiZig,
+  clojure: SiClojure,
+  coffeescript: SiCoffeescript,
+  html: SiHtml5,
+  css: SiCss,
+  vue: SiVuedotjs,
+  svelte: SiSvelte,
+  solid: SiSolid,
+  json: SiJson,
+  yaml: SiYaml,
+  toml: SiToml,
+  graphql: SiGraphql,
+  markdown: SiMarkdown,
+  mdx: SiMarkdown,
+  latex: SiLatex,
+  asciidoc: SiAsciidoctor,
+  bash: SiGnubash,
+  shell: SiGnubash,
+  sh: SiGnubash,
+  fish: SiFishshell,
+  nodejs: SiNodedotjs,
+  mysql: SiMysql,
+  postgresql: SiPostgresql,
+  plsql: SiPostgresql,
+  sqlite: SiSqlite,
+  mongodb: SiMongodb,
+  redis: SiRedis,
+  docker: SiDocker,
+  dockerfile: SiDocker,
+  kubernetes: SiKubernetes,
+  nginx: SiNginx,
+  apacheconf: SiApache,
+};
+
+// Generic lucide fallback for langs without a brand icon. Returns a
+// lucide id string — `resolveIcon` turns it into the icon component.
+const LUCIDE = {
+  sql: 'database',
+  xml: 'code-xml',
+  diff: 'git-compare-arrows',
+  ini: 'braces',
+  properties: 'braces',
+  powershell: 'terminal',
+  batch: 'terminal',
+  zsh: 'terminal',
+  text: 'file-code',
+  plaintext: 'file-code',
+};
+
+export function iconForLang(lang) {
+  if (!lang) return 'file-code';
+  const id = resolveLang(lang) || lang;
+  const Cmp = BRAND[id] || BRAND[lang];
+  if (Cmp) return <Cmp size="1em" />;
+  return LUCIDE[id] || LUCIDE[lang] || 'file-code';
+}