@cedros/data-react 0.1.7 → 0.1.8

package/dist/site-templates/docsNavigation.js

@@ -1,14 +1,16 @@
+import { normalizeDocsSlug, sortDocsEntries, } from "../docsContract.js";
 import { isRouteActive, normalizeRoutePath } from "./routing.js";
 export function buildDocsSidebarSections(docs, basePath = "/docs") {
     const grouped = new Map();
     docs.forEach((doc) => {
         const sectionLabel = doc.category ?? "Overview";
-        const sectionKey = sectionLabel.toLowerCase().replace(/\s+/gu, "-");
+        const sectionKey = normalizeFragment(doc.sectionKey ?? sectionLabel) || "overview";
         const current = grouped.get(sectionKey) ?? { label: sectionLabel, items: [] };
         current.items.push({
             key: doc.slug,
-            label: doc.title,
-            href: buildDocHref(basePath, doc.slug)
+            label: doc.navLabel ?? doc.title,
+            href: buildDocHref(basePath, doc.slug),
+            badge: doc.badge,
         });
         grouped.set(sectionKey, current);
     });
@@ -16,64 +18,77 @@ export function buildDocsSidebarSections(docs, basePath = "/docs") {
         .map(([key, value]) => ({
         key,
         label: value.label,
-        items: [...value.items].sort((left, right) => left.label.localeCompare(right.label))
+        items: [...value.items].sort((left, right) => left.label.localeCompare(right.label)),
     }))
         .sort((left, right) => left.label.localeCompare(right.label));
 }
 export function fetchDocEntry(docs, slugOrPath, options = {}) {
-    const normalizedLookup = normalizeDocLookup(slugOrPath, options.basePath);
-    return docs.find((doc) => {
-        const normalizedDocSlug = normalizeDocSlug(doc.slug);
-        return normalizedDocSlug === normalizedLookup || (!normalizedLookup && normalizedDocSlug === "index");
-    });
-}
-export function buildDocsTree(docs, basePath = "/docs") {
-    const sections = [];
-    const grouped = new Map();
-    docs.forEach((doc) => {
-        const sectionLabel = doc.category ?? "Overview";
-        const sectionKey = sectionLabel.toLowerCase().replace(/\s+/gu, "-");
-        const section = grouped.get(sectionKey) ?? { key: sectionKey, label: sectionLabel, nodes: [] };
-        if (!grouped.has(sectionKey)) {
-            grouped.set(sectionKey, section);
-            sections.push(section);
-        }
-        insertDocTreeNode(section.nodes, doc, basePath);
-    });
-    return sections;
+    const normalizedLookup = normalizeDocsSlug(slugOrPath, options);
+    return docs.find((doc) => docLookupCandidates(doc, options).some((candidate) => matchesDocLookup(candidate, normalizedLookup)));
 }
-export function buildHierarchicalDocsSidebarSections(docs, basePath = "/docs") {
-    return buildDocsTree(docs, basePath)
+/**
+ * Builds sidebar-ready docs navigation from a normalized docs collection.
+ *
+ * Groups by product automatically when multiple products exist and preserves explicit ordering fields when present.
+ */
+export function buildDocsNavigation(docs, options = {}) {
+    const sections = buildDocsTreeSections(docs, options)
         .map((section) => ({
         key: section.key,
         label: section.label,
-        items: flattenDocsTreeNodes(section.nodes)
+        items: flattenDocsTreeNodes(section.nodes),
     }))
         .filter((section) => section.items.length > 0);
+    const activeSections = withActiveDocsSidebar(sections, options.currentPath);
+    if (!options.collapsible || !options.currentPath) {
+        return activeSections;
+    }
+    return activeSections.map((section) => ({
+        ...section,
+        collapsed: !section.items.some((item) => item.isActive),
+    }));
 }
-export function buildDocsPrevNext(docs, currentSlugOrPath, options = {}) {
+export function buildDocsTree(docs, basePath = "/docs") {
+    return buildDocsTreeSections(docs, { basePath });
+}
+export function buildHierarchicalDocsSidebarSections(docs, basePath = "/docs") {
+    return buildDocsNavigation(docs, { basePath });
+}
+/**
+ * Builds previous/next links from the same ordered docs collection used for navigation.
+ *
+ * When the current doc belongs to a product, pager links stay inside that product by default.
+ */
+export function buildDocsArticlePager(docs, currentSlugOrPath, options = {}) {
     const current = fetchDocEntry(docs, currentSlugOrPath, options);
     if (!current) {
         return {};
     }
-    const currentSlug = normalizeDocSlug(current.slug);
-    const currentIndex = docs.findIndex((doc) => normalizeDocSlug(doc.slug) === currentSlug);
+    const scopedProduct = options.productSlug ?? current.productSlug;
+    const orderedDocs = resolveOrderedDocs(docs, {
+        ...options,
+        productSlug: scopedProduct,
+    });
+    const currentIndex = orderedDocs.findIndex((doc) => normalizeDocsSlug(doc.slug, options) === normalizeDocsSlug(current.slug, options));
     if (currentIndex === -1) {
         return {};
     }
     return {
-        previousDoc: buildDocsPagerLink(docs[currentIndex - 1], options.basePath),
-        nextDoc: buildDocsPagerLink(docs[currentIndex + 1], options.basePath)
+        previousDoc: buildDocsPagerLink(orderedDocs[currentIndex - 1], options.basePath),
+        nextDoc: buildDocsPagerLink(orderedDocs[currentIndex + 1], options.basePath),
     };
 }
+export function buildDocsPrevNext(docs, currentSlugOrPath, options = {}) {
+    return buildDocsArticlePager(docs, currentSlugOrPath, options);
+}
 export function withActiveDocsSidebar(sections, currentPath) {
     if (!currentPath) {
         return sections.map((section) => ({
             ...section,
             items: section.items.map((item) => ({
                 ...item,
-                isActive: item.isActive ?? false
-            }))
+                isActive: item.isActive ?? false,
+            })),
         }));
     }
     const candidateLengths = sections
@@ -89,64 +104,122 @@ export function withActiveDocsSidebar(sections, currentPath) {
                 isRouteActive(item.href, currentPath);
             return {
                 ...item,
-                isActive: item.isActive ?? inferredActive
+                isActive: item.isActive ?? inferredActive,
             };
-        })
+        }),
     }));
 }
-function buildDocHref(basePath, slug) {
-    const normalizedBasePath = normalizeRoutePath(basePath);
-    const normalizedSlug = normalizeDocSlug(slug);
-    if (!normalizedSlug) {
-        return normalizedBasePath;
-    }
-    if (normalizedBasePath === "/") {
-        return `/${normalizedSlug}`;
-    }
-    return `${normalizedBasePath}/${normalizedSlug}`;
+function buildDocsTreeSections(docs, options) {
+    const orderedDocs = resolveOrderedDocs(docs, options);
+    const groupByProduct = shouldGroupByProduct(orderedDocs, options.groupByProduct);
+    const sections = [];
+    const sectionMap = new Map();
+    orderedDocs.forEach((doc) => {
+        const identity = sectionIdentity(doc, groupByProduct);
+        let section = sectionMap.get(identity.key);
+        if (!section) {
+            section = { key: identity.key, label: identity.label, nodes: [] };
+            sectionMap.set(identity.key, section);
+            sections.push(section);
+        }
+        insertDocTreeNode(section.nodes, doc, options.basePath ?? "/docs", groupByProduct, options);
+    });
+    return sections;
 }
-function normalizeDocSlug(slug) {
-    return slug.trim().replace(/^\/+|\/+$/gu, "");
+function resolveOrderedDocs(docs, options) {
+    return sortDocsEntries(docs.filter((doc) => matchesNavigationScope(doc, options)), { preserveSourceOrder: options.preserveOrder !== false });
 }
-function normalizeDocLookup(value, basePath = "/docs") {
-    const normalizedValue = normalizeRoutePath(value).replace(/^\/+/u, "");
-    const normalizedBasePath = normalizeRoutePath(basePath).replace(/^\/+/u, "");
-    if (!normalizedBasePath) {
-        return normalizedValue;
+function matchesNavigationScope(doc, options) {
+    if (options.productSlug) {
+        const productSlug = normalizeDocsSlug(doc.productSlug ?? "", options);
+        if (!productSlug || productSlug !== normalizeDocsSlug(options.productSlug, options)) {
+            return false;
+        }
+    }
+    if (options.sectionKey) {
+        const sectionKey = normalizeFragment(doc.sectionKey);
+        if (!sectionKey || sectionKey !== normalizeFragment(options.sectionKey)) {
+            return false;
+        }
     }
-    if (normalizedValue === normalizedBasePath) {
-        return "";
+    return true;
+}
+function shouldGroupByProduct(docs, explicit) {
+    if (explicit !== undefined) {
+        return explicit;
     }
-    if (normalizedValue.startsWith(`${normalizedBasePath}/`)) {
-        return normalizedValue.slice(normalizedBasePath.length + 1);
+    return new Set(docs.map((doc) => normalizeFragment(doc.productSlug)).filter(Boolean)).size > 1;
+}
+function sectionIdentity(doc, groupByProduct) {
+    if (groupByProduct) {
+        const productSlug = normalizeDocsSlug(doc.productSlug ?? doc.slug.split("/")[0] ?? "");
+        return {
+            key: productSlug || "docs",
+            label: doc.productLabel ?? humanizeDocSegment(productSlug || "docs"),
+        };
     }
-    return normalizedValue;
+    const label = doc.sectionLabel ?? doc.category ?? "Overview";
+    return {
+        key: normalizeFragment(doc.sectionKey ?? label) || "overview",
+        label,
+    };
 }
-function insertDocTreeNode(nodes, doc, basePath) {
-    const segments = normalizedDocSegments(doc.slug);
+function insertDocTreeNode(nodes, doc, basePath, groupByProduct, options) {
+    const fullSegments = normalizedDocSegments(doc.slug, options);
+    const visibleSegments = visibleDocSegments(doc, groupByProduct, options);
+    if (visibleSegments.length === 0) {
+        nodes.push({
+            key: doc.slug,
+            slug: normalizeDocsSlug(doc.slug, options),
+            label: doc.navLabel ?? doc.title,
+            href: buildDocHref(basePath, doc.slug),
+            entry: doc,
+            children: [],
+        });
+        return;
+    }
     let cursor = nodes;
-    segments.forEach((segment, index) => {
-        const slug = segments.slice(0, index + 1).join("/");
-        let node = cursor.find((candidate) => candidate.slug === slug);
+    const hiddenCount = fullSegments.length - visibleSegments.length;
+    visibleSegments.forEach((segment, index) => {
+        const fullSlug = fullSegments.slice(0, hiddenCount + index + 1).join("/");
+        let node = cursor.find((candidate) => candidate.slug === fullSlug);
         if (!node) {
             node = {
-                key: slug || "index",
-                slug,
+                key: fullSlug || "index",
+                slug: fullSlug,
                 label: humanizeDocSegment(segment),
-                children: []
+                children: [],
             };
             cursor.push(node);
         }
-        if (index === segments.length - 1) {
+        if (index === visibleSegments.length - 1) {
             node.entry = doc;
             node.href = buildDocHref(basePath, doc.slug);
-            node.label = doc.title;
+            node.label = doc.navLabel ?? doc.title;
         }
         cursor = node.children;
     });
 }
-function normalizedDocSegments(slug) {
-    const normalized = normalizeDocSlug(slug);
+function visibleDocSegments(doc, groupByProduct, options) {
+    const segments = normalizedDocSegments(doc.slug, options);
+    if (groupByProduct) {
+        const productSlug = normalizeDocsSlug(doc.productSlug ?? "", options);
+        if (productSlug && segments[0] === productSlug) {
+            return segments.slice(1);
+        }
+        return segments;
+    }
+    const withoutProduct = doc.productSlug && segments[0] === normalizeDocsSlug(doc.productSlug, options)
+        ? segments.slice(1)
+        : segments;
+    const sectionKey = normalizeFragment(doc.sectionKey);
+    if (sectionKey && withoutProduct[0] === sectionKey) {
+        return withoutProduct.slice(1);
+    }
+    return withoutProduct;
+}
+function normalizedDocSegments(slug, options) {
+    const normalized = normalizeDocsSlug(slug, options);
     return normalized ? normalized.split("/").filter(Boolean) : ["index"];
 }
 function flattenDocsTreeNodes(nodes, depth = 0) {
@@ -157,7 +230,8 @@ function flattenDocsTreeNodes(nodes, depth = 0) {
                 key: node.key,
                 label: node.label,
                 href: node.href,
-                depth: Math.min(depth, 2)
+                depth: Math.min(depth, 2),
+                badge: node.entry.badge,
             });
         }
         items.push(...flattenDocsTreeNodes(node.children, depth + 1));
@@ -171,11 +245,40 @@ function buildDocsPagerLink(doc, basePath = "/docs") {
     return {
         title: doc.title,
         href: buildDocHref(basePath, doc.slug),
-        entry: doc
+        entry: doc,
     };
 }
+function buildDocHref(basePath, slug) {
+    const normalizedBasePath = normalizeRoutePath(basePath);
+    const normalizedSlug = normalizeDocsSlug(slug, { basePath });
+    if (!normalizedSlug || normalizedSlug === "index") {
+        return normalizedBasePath;
+    }
+    if (normalizedBasePath === "/") {
+        return `/${normalizedSlug}`;
+    }
+    return `${normalizedBasePath}/${normalizedSlug}`;
+}
+function docLookupCandidates(doc, options) {
+    const candidates = [normalizeDocsSlug(doc.slug, options)];
+    doc.aliases?.forEach((alias) => {
+        const normalized = normalizeDocsSlug(alias, options);
+        if (normalized) {
+            candidates.push(normalized);
+        }
+    });
+    return [...new Set(candidates.filter(Boolean))];
+}
+function matchesDocLookup(candidate, lookup) {
+    return candidate === lookup || (!lookup && (candidate === "" || candidate === "index"));
+}
+function normalizeFragment(value) {
+    return (value ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+|-+$/gu, "");
+}
 function humanizeDocSegment(segment) {
-    return segment
-        .replace(/[-_]+/gu, " ")
-        .replace(/\b\w/gu, (char) => char.toUpperCase());
+    return segment.replace(/[-_]+/gu, " ").replace(/\b\w/gu, (char) => char.toUpperCase());
 }

package/dist/site-templates/index.d.ts

@@ -5,7 +5,8 @@ export { DashboardShell, type DashboardShellProps, type DashboardNavItem } from
 export { DashboardOverviewTemplate, type DashboardOverviewTemplateProps, type DashboardPanel, type DashboardStat } from "./DashboardOverviewTemplate.js";
 export { isRouteActive, normalizeRoutePath, withActiveRouteState, type RouteAwareItem, type RouteMatcherOptions } from "./routing.js";
 export { buildContentListHref, collectFilterValues, collectDimensionValues, matchesFilterDimensions, prepareBlogIndex, prepareDocsIndex, type BlogIndexEntry, type BlogIndexQuery, type DocsIndexEntry, type DocsIndexQuery, type FilterDimension, type FilterDimensionValues, type PaginationResult } from "./contentIndex.js";
-export { buildDocsSidebarSections, buildDocsTree, buildHierarchicalDocsSidebarSections, buildDocsPrevNext, fetchDocEntry, withActiveDocsSidebar, type DocsTreeNode, type DocsTreeSection, type DocsPagerLink, type DocsPrevNext, type FetchDocEntryOptions, type DocsSidebarItem, type DocsSidebarSection } from "./docsNavigation.js";
+export { buildDocsNavigation, buildDocsArticlePager, buildDocsSidebarSections, buildDocsTree, buildHierarchicalDocsSidebarSections, buildDocsPrevNext, fetchDocEntry, withActiveDocsSidebar, type DocsTreeNode, type DocsTreeSection, type DocsPagerLink, type DocsPrevNext, type DocsNavigationOptions, type FetchDocEntryOptions, type DocsSidebarItem, type DocsSidebarSection } from "./docsNavigation.js";
+export { normalizeDocsHref, normalizeDocsSlug, type DocsBreadcrumb, type DocsEntryRecord, type DocsNormalizationOptions, type DocsTocHeading, } from "../docsContract.js";
 export { MarkdownContent, type MarkdownContentProps } from "./MarkdownContent.js";
 export { extractTocFromMarkdown, type TocEntry } from "./tocExtractor.js";
 export { DocsSidebar, type DocsSidebarProps } from "./DocsSidebar.js";

package/dist/site-templates/index.js

@@ -5,7 +5,8 @@ export { DashboardShell } from "./DashboardShell.js";
 export { DashboardOverviewTemplate } from "./DashboardOverviewTemplate.js";
 export { isRouteActive, normalizeRoutePath, withActiveRouteState } from "./routing.js";
 export { buildContentListHref, collectFilterValues, collectDimensionValues, matchesFilterDimensions, prepareBlogIndex, prepareDocsIndex } from "./contentIndex.js";
-export { buildDocsSidebarSections, buildDocsTree, buildHierarchicalDocsSidebarSections, buildDocsPrevNext, fetchDocEntry, withActiveDocsSidebar } from "./docsNavigation.js";
+export { buildDocsNavigation, buildDocsArticlePager, buildDocsSidebarSections, buildDocsTree, buildHierarchicalDocsSidebarSections, buildDocsPrevNext, fetchDocEntry, withActiveDocsSidebar } from "./docsNavigation.js";
+export { normalizeDocsHref, normalizeDocsSlug, } from "../docsContract.js";
 export { MarkdownContent } from "./MarkdownContent.js";
 export { extractTocFromMarkdown } from "./tocExtractor.js";
 export { DocsSidebar } from "./DocsSidebar.js";