@cedros/data-react 0.1.6 → 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: `${basePath}/${doc.slug}`
+            label: doc.navLabel ?? doc.title,
+            href: buildDocHref(basePath, doc.slug),
+            badge: doc.badge,
         });
         grouped.set(sectionKey, current);
     });
@@ -16,18 +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 = normalizeDocsSlug(slugOrPath, options);
+    return docs.find((doc) => docLookupCandidates(doc, options).some((candidate) => matchesDocLookup(candidate, normalizedLookup)));
+}
+/**
+ * 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),
+    }))
+        .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 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 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(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
@@ -43,8 +104,181 @@ export function withActiveDocsSidebar(sections, currentPath) {
                 isRouteActive(item.href, currentPath);
             return {
                 ...item,
-                isActive: item.isActive ?? inferredActive
+                isActive: item.isActive ?? inferredActive,
             };
-        })
+        }),
     }));
 }
+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 resolveOrderedDocs(docs, options) {
+    return sortDocsEntries(docs.filter((doc) => matchesNavigationScope(doc, options)), { preserveSourceOrder: options.preserveOrder !== false });
+}
+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;
+        }
+    }
+    return true;
+}
+function shouldGroupByProduct(docs, explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    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"),
+        };
+    }
+    const label = doc.sectionLabel ?? doc.category ?? "Overview";
+    return {
+        key: normalizeFragment(doc.sectionKey ?? label) || "overview",
+        label,
+    };
+}
+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;
+    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: fullSlug || "index",
+                slug: fullSlug,
+                label: humanizeDocSegment(segment),
+                children: [],
+            };
+            cursor.push(node);
+        }
+        if (index === visibleSegments.length - 1) {
+            node.entry = doc;
+            node.href = buildDocHref(basePath, doc.slug);
+            node.label = doc.navLabel ?? doc.title;
+        }
+        cursor = node.children;
+    });
+}
+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) {
+    return nodes.flatMap((node) => {
+        const items = [];
+        if (node.entry && node.href) {
+            items.push({
+                key: node.key,
+                label: node.label,
+                href: node.href,
+                depth: Math.min(depth, 2),
+                badge: node.entry.badge,
+            });
+        }
+        items.push(...flattenDocsTreeNodes(node.children, depth + 1));
+        return items;
+    });
+}
+function buildDocsPagerLink(doc, basePath = "/docs") {
+    if (!doc) {
+        return undefined;
+    }
+    return {
+        title: doc.title,
+        href: buildDocHref(basePath, doc.slug),
+        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());
+}

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

@@ -0,0 +1,8 @@
+import { type SiteNavigationItem } from "./SiteLayout.js";
+export interface DocsTemplateShellOptions {
+    siteTitle?: string;
+    navigation?: SiteNavigationItem[];
+    headless?: boolean;
+    renderLayout?: (content: React.JSX.Element) => React.JSX.Element;
+}
+export declare function renderDocsTemplateShell(content: React.JSX.Element, options: DocsTemplateShellOptions): React.JSX.Element;

package/dist/site-templates/docsTemplateShell.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SiteLayout } from "./SiteLayout.js";
+export function renderDocsTemplateShell(content, options) {
+    if (options.renderLayout) {
+        return options.renderLayout(content);
+    }
+    if (options.headless) {
+        return content;
+    }
+    if (options.siteTitle === undefined || options.navigation === undefined) {
+        throw new Error("Docs templates require `siteTitle` and `navigation` unless `headless` or `renderLayout` is provided.");
+    }
+    return (_jsx(SiteLayout, { siteTitle: options.siteTitle, navigation: options.navigation, children: content }));
+}

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, withActiveDocsSidebar, 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, 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";