@veluai/velu 0.1.0

package/src/navigation.js

@@ -0,0 +1,434 @@
+import GithubSlugger from 'github-slugger';
+import ISO6391 from 'iso-639-1';
+
+/**
+ * navigation.js — the PURE, framework-agnostic navigation model. No
+ * `fs`, no React, no Node-only imports: this file is imported by BOTH
+ * the Node-side Vite plugin (to normalize + walk) AND the browser
+ * runtime (to resolve the active page → sidebar/header). Sharing the
+ * exact same code on both sides is what keeps SSR and client render
+ * in lockstep (no hydration drift).
+ *
+ * Model: `velu.json`'s `navigation` is normalized into a canonical
+ * tree whose containment order is FIXED, regardless of how the author
+ * nested things, and identical to the URL-prefix order:
+ *
+ *   AXIS_ORDER:  product → version → language → tabs → groups → pages
+ *   URL:         /<product?>/<version?>/<language?>/<page-path>
+ *
+ * Default axis values contribute no URL segment. Dropdowns are out of
+ * scope by design.
+ */
+
+export const AXIS_ORDER = ['product', 'version', 'language'];
+
+// `language` in velu.json is stored as an ISO 639-1 code (e.g. "en");
+// the switcher shows the code + its native name. iso-639-1 covers the
+// full set of codes; unknown/invalid codes fall back to the code.
+function languageName(code) {
+  const c = String(code).toLowerCase();
+  return ISO6391.getNativeName(c) || code;
+}
+
+/** Fresh slugger per call → pure (no cross-call dedup state). */
+export function slugify(s) {
+  return new GithubSlugger().slug(String(s ?? ''));
+}
+
+/**
+ * Map a content page path to its in-context URL leaf:
+ *   "index"        → "/"
+ *   "sync/index"   → "/sync"
+ *   "sync/github"  → "/sync/github"
+ * Defined ONCE so collect + resolve never disagree.
+ */
+export function urlForPath(pagePath) {
+  const segs = String(pagePath)
+    .replace(/^\/+|\/+$/g, '')
+    .split('/')
+    .filter(Boolean);
+  if (segs[segs.length - 1] === 'index') segs.pop();
+  return '/' + segs.join('/');
+}
+
+/** Normalize a request/location path: drop query+hash, collapse a
+ *  trailing slash (except root), ensure a leading slash. Used on both
+ *  sides so the active-page lookup matches identically. */
+export function normalizeUrl(url) {
+  let u = String(url).split('#')[0].split('?')[0];
+  // Decode percent-encoding so non-ASCII slugs (e.g. an "Español"
+  // language → "/español") match whether the browser sends the path
+  // encoded ("/espa%C3%B1ol") or decoded.
+  try {
+    u = decodeURI(u);
+  } catch {
+    /* malformed escape — leave as-is */
+  }
+  if (!u.startsWith('/')) u = '/' + u;
+  if (u.length > 1) u = u.replace(/\/+$/, '');
+  return u || '/';
+}
+
+const titleCase = (s) =>
+  String(s)
+    .replace(/[-_]+/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+
+const lastSeg = (url) => {
+  const segs = String(url).split('/').filter(Boolean);
+  return segs[segs.length - 1] ?? '';
+};
+
+// ── Normalization ──────────────────────────────────────────────────
+
+/**
+ * Build the canonical tree from a raw `navigation` object. At each
+ * level we honor a fixed precedence (products > versions > languages >
+ * tabs > leaf), so canonically-authored configs (axes nested in
+ * AXIS_ORDER, or only one axis) collapse to the intended tree. A leaf
+ * level mixes anchors + groups + pages as siblings.
+ */
+export function normalizeNavigation(raw) {
+  const root = { kind: 'root', children: normalizeChildren(raw ?? {}) };
+  applyDefaults(root.children);
+  return root;
+}
+
+function normalizeChildren(obj) {
+  // Anchors are pinned links that may sit alongside ANY level (incl.
+  // next to tabs as "global" anchors), so collect them regardless of
+  // which grouping branch this container uses.
+  const anchors = Array.isArray(obj.anchors)
+    ? obj.anchors.map(normalizeAnchor)
+    : [];
+  if (Array.isArray(obj.products))
+    return [...anchors, ...obj.products.map(normalizeProduct)];
+  if (Array.isArray(obj.versions))
+    return [...anchors, ...obj.versions.map(normalizeVersion)];
+  if (Array.isArray(obj.languages))
+    return [...anchors, ...obj.languages.map(normalizeLanguage)];
+  if (Array.isArray(obj.tabs))
+    return [...anchors, ...obj.tabs.map(normalizeTab)];
+  const out = [...anchors];
+  if (Array.isArray(obj.groups)) out.push(...obj.groups.map(normalizeGroup));
+  if (Array.isArray(obj.pages)) out.push(...obj.pages.map(normalizePageEntry));
+  return out;
+}
+
+function normalizeProduct(p) {
+  return {
+    kind: 'product',
+    label: p.name ?? p.product,
+    slug: slugify(p.product),
+    icon: p.icon,
+    color: p.color,
+    default: Boolean(p.default),
+    children: normalizeChildren(p),
+  };
+}
+
+function normalizeVersion(v) {
+  return {
+    kind: 'version',
+    label: v.version,
+    slug: slugify(v.version),
+    default: Boolean(v.default),
+    children: normalizeChildren(v),
+  };
+}
+
+function normalizeLanguage(l) {
+  const code = String(l.language);
+  return {
+    kind: 'language',
+    code,
+    label: languageName(code),
+    slug: slugify(code),
+    default: Boolean(l.default),
+    children: normalizeChildren(l),
+  };
+}
+
+function normalizeTab(t) {
+  return {
+    kind: 'tab',
+    label: t.tab,
+    slug: slugify(t.tab),
+    icon: t.icon,
+    href: t.href,
+    children: normalizeChildren(t),
+  };
+}
+
+function normalizeAnchor(a) {
+  return {
+    kind: 'anchor',
+    label: a.anchor,
+    icon: a.icon,
+    href: a.href,
+    color: a.color,
+  };
+}
+
+function normalizeGroup(g) {
+  const pages = (g.pages ?? []).map(normalizePageEntry);
+  // A group `root` is its landing page. velu-ui's Sidebar section
+  // heading isn't a link, so surface root as the group's FIRST item
+  // (its label comes from the root page's frontmatter, like any page).
+  if (g.root) pages.unshift({ kind: 'page', pagePath: g.root });
+  return {
+    kind: 'group',
+    label: g.group,
+    icon: g.icon,
+    expanded: Boolean(g.expanded),
+    root: g.root,
+    children: pages,
+  };
+}
+
+/** A `pages[]` entry is either a string (page path) or a nested group. */
+function normalizePageEntry(entry) {
+  if (typeof entry === 'string') return { kind: 'page', pagePath: entry };
+  return normalizeGroup(entry);
+}
+
+/**
+ * Ensure each axis sibling-set has exactly one default: if the author
+ * marked none, the first declared becomes default (so an axis never
+ * prefixes every URL). Recurses through the whole tree.
+ */
+function applyDefaults(children) {
+  for (const kind of AXIS_ORDER) {
+    const sibs = children.filter((c) => c.kind === kind);
+    if (sibs.length && !sibs.some((s) => s.default)) sibs[0].default = true;
+  }
+  for (const c of children) if (c.children) applyDefaults(c.children);
+}
+
+// ── Walking ────────────────────────────────────────────────────────
+
+/**
+ * Walk the tree to every page leaf, computing its full URL (with the
+ * accumulated NON-default axis prefix) and its ancestor chain. Pure —
+ * the Node side adds fs existence on top (see navigation-node.js); the
+ * runtime uses it directly for resolution. Returns:
+ *   [{ pagePath, url, ctx, ancestors:Node[] }]
+ */
+export function walkPages(tree) {
+  const out = [];
+  const visit = (node, ctx, ancestors) => {
+    if (node.kind === 'page') {
+      out.push({
+        pagePath: node.pagePath,
+        url: urlInCtx(node.pagePath, ctx),
+        ctx: { ...ctx },
+        ancestors,
+        node,
+      });
+      return;
+    }
+    let next = ctx;
+    if (node.kind === 'product')
+      next = { ...ctx, product: node.default ? null : node.slug };
+    else if (node.kind === 'version')
+      next = { ...ctx, version: node.default ? null : node.slug };
+    else if (node.kind === 'language')
+      next = { ...ctx, language: node.default ? null : node.slug };
+    const nextAncestors =
+      node.kind === 'root' ? ancestors : [...ancestors, node];
+    for (const c of node.children ?? []) visit(c, next, nextAncestors);
+  };
+  visit(tree, { product: null, version: null, language: null }, []);
+  return out;
+}
+
+/** Compose a page URL from a page path + an axis context. */
+function urlInCtx(pagePath, ctx) {
+  const prefix = [ctx.product, ctx.version, ctx.language].filter(Boolean);
+  const leaf = urlForPath(pagePath).split('/').filter(Boolean);
+  return '/' + [...prefix, ...leaf].join('/');
+}
+
+// ── Resolution (runtime) ───────────────────────────────────────────
+
+/**
+ * Resolve the active page for a URL into everything the chrome needs.
+ * `pagesMap` is url → { frontmatter, ... } (from the virtual module),
+ * used to source sidebar labels from page frontmatter titles.
+ *
+ * Returns null when no page matches (404). Otherwise:
+ *   {
+ *     url, frontmatter,
+ *     sidebarSections, anchors,
+ *     tabs, activeTab,
+ *     products, activeProduct,
+ *     versions, activeVersion,
+ *     languages, activeLanguage,
+ *     breadcrumb,
+ *   }
+ */
+export function resolve(url, tree, pagesMap = {}) {
+  const norm = normalizeUrl(url);
+  const entries = walkPages(tree);
+  const match = entries.find((e) => e.url === norm);
+  if (!match) return null;
+
+  const { ctx, ancestors } = match;
+  const ancOf = (kind) => ancestors.filter((a) => a.kind === kind).pop();
+  const tabAnc = ancOf('tab');
+  const axisAnc = ancestors
+    .filter((a) => AXIS_ORDER.includes(a.kind))
+    .pop();
+  const productAnc = ancOf('product');
+  const versionAnc = ancOf('version');
+  const languageAnc = ancOf('language');
+
+  // Sidebar/anchor container = nearest tab, else nearest axis node,
+  // else the root. Its group/page children form the sidebar; its
+  // anchor children form the context-zone anchors.
+  const container = tabAnc || axisAnc || tree;
+  const containerKids = container.children ?? [];
+  const sidebarSections = buildSidebar(
+    containerKids.filter((n) => n.kind === 'group' || n.kind === 'page'),
+    pagesMap,
+    ctx,
+  );
+  // Anchors are gathered from every container along the active path —
+  // root (global), the active product/version/language, and the active
+  // tab — so global anchors show on every page while tab-scoped ones
+  // show only within their tab.
+  const anchors = [tree, productAnc, versionAnc, languageAnc, tabAnc]
+    .filter(Boolean)
+    .flatMap((c) => (c.children ?? []).filter((n) => n.kind === 'anchor'))
+    .map((a) => ({ label: a.label, icon: a.icon, href: a.href, external: true }));
+
+  // Tabs live directly under the innermost axis node (or root).
+  const tabParent = axisAnc || tree;
+  const tabNodes = (tabParent.children ?? []).filter((n) => n.kind === 'tab');
+  const firstUrlUnder = (node) => {
+    const e = entries.find((en) => en.ancestors.includes(node));
+    return e ? e.url : node.href ?? '#';
+  };
+  const tabs = tabNodes.map((t) => ({
+    label: t.label,
+    icon: t.icon,
+    href: firstUrlUnder(t),
+  }));
+  const activeTab = tabAnc ? firstUrlUnder(tabAnc) : undefined;
+
+  // Switchers: sibling axis options + the URL to land on when chosen
+  // (first page of that option's subtree). Each option set is scoped
+  // to the active outer axis (versions within the active product, etc).
+  const axisOptions = (kind, parent) =>
+    (parent?.children ?? tree.children ?? [])
+      .filter((n) => n.kind === kind)
+      .map((n) => ({
+        label: n.label,
+        code: n.code, // language code (undefined for product/version)
+        slug: n.slug,
+        icon: n.icon,
+        default: n.default,
+        href: firstUrlUnder(n),
+        active: n === ancOf(kind),
+      }));
+  const products = axisOptions('product', tree);
+  const versions = axisOptions('version', productAnc ?? tree);
+  const languages = axisOptions('language', versionAnc ?? productAnc ?? tree);
+
+  // Breadcrumb: tab → group ancestors → page title.
+  const groupAncestors = ancestors.filter((a) => a.kind === 'group');
+  const pageTitle = pagesMap[norm]?.frontmatter?.title ?? titleCase(lastSeg(norm));
+  const breadcrumb = [
+    ...(tabAnc ? [{ label: tabAnc.label }] : []),
+    ...groupAncestors.map((g) => ({ label: g.label })),
+    { label: pageTitle },
+  ];
+
+  // Prev / next = neighbors in the sidebar's reading order (the
+  // flattened page sequence of the active section).
+  const ordered = flattenSidebar(sidebarSections);
+  const idx = ordered.findIndex((p) => p.href === norm);
+  const prev = idx > 0 ? ordered[idx - 1] : undefined;
+  const next = idx >= 0 && idx < ordered.length - 1 ? ordered[idx + 1] : undefined;
+
+  return {
+    url: norm,
+    frontmatter: pagesMap[norm]?.frontmatter ?? {},
+    sidebarSections,
+    anchors,
+    tabs,
+    activeTab,
+    products,
+    activeProduct: productAnc?.label,
+    versions,
+    activeVersion: versionAnc?.label,
+    languages,
+    activeLanguage: languageAnc?.label,
+    activeLanguageCode: languageAnc?.code,
+    breadcrumb,
+    prev,
+    next,
+  };
+}
+
+/** Flatten sidebar sections (incl. nested groups) to an ordered list of
+ *  page links {label, href} — the page reading order for prev/next. */
+function flattenSidebar(sections) {
+  const out = [];
+  const walk = (items) => {
+    for (const it of items) {
+      if (it.items) walk(it.items);
+      else out.push({ label: it.label, href: it.href });
+    }
+  };
+  for (const s of sections) walk(s.items);
+  return out;
+}
+
+/**
+ * Map a list of (group|page) nodes to the velu-ui Sidebar `sections`
+ * shape: [{ title, icon, items:[{ label, href, icon, items }] }].
+ * Loose top-level pages (not inside a group) collect into a leading
+ * untitled section. Page labels come from frontmatter title, falling
+ * back to a title-cased URL segment (the SAME fallback on both render
+ * sides). Sidebar derives open/active state from `activeHref`, so we
+ * don't compute it here.
+ */
+export function buildSidebar(nodes, pagesMap, ctx) {
+  const sections = [];
+  let loose = null;
+  for (const n of nodes) {
+    if (n.kind === 'group') {
+      sections.push({
+        title: n.label,
+        icon: n.icon,
+        items: itemsFor(n.children, pagesMap, ctx),
+      });
+    } else if (n.kind === 'page') {
+      if (!loose) {
+        loose = { title: '', items: [] };
+        sections.push(loose);
+      }
+      loose.items.push(itemFor(n, pagesMap, ctx));
+    }
+  }
+  return sections;
+}
+
+function itemsFor(nodes, pagesMap, ctx) {
+  return (nodes ?? []).map((n) =>
+    n.kind === 'group'
+      ? {
+          label: n.label,
+          icon: n.icon,
+          items: itemsFor(n.children, pagesMap, ctx),
+        }
+      : itemFor(n, pagesMap, ctx),
+  );
+}
+
+function itemFor(pageNode, pagesMap, ctx) {
+  const href = urlInCtx(pageNode.pagePath, ctx);
+  const fm = pagesMap[href]?.frontmatter;
+  return { label: fm?.title ?? titleCase(lastSeg(href)), href };
+}