@cedros/data-react 0.1.6 → 0.1.7

package/README.md

@@ -217,13 +217,18 @@ Tipping:
 Docs templates:
 - `DocsIndexTemplate`
 - `DocArticleTemplate` (GitBook-style left nav + right TOC)
+- both accept `headless` to skip the built-in `SiteLayout`, or `renderLayout={(content) => ...}` to wrap the docs UI in an existing app shell
 
 Content rendering and helpers:
 - `MarkdownContent`
 - `Breadcrumbs`
 - `ContentPagination`
 - `withActiveRouteState`
+- `fetchDocEntry`
 - `buildDocsSidebarSections`
+- `buildDocsTree`
+- `buildHierarchicalDocsSidebarSections`
+- `buildDocsPrevNext`
 - `withActiveDocsSidebar`
 - `prepareBlogIndex`
 - `prepareDocsIndex`
@@ -319,6 +324,8 @@ Docs/blog templates default to `bodyMarkdown`.
 
 This keeps markdown as the safe default and avoids unsafe HTML rendering by default.
 
+Docs search helpers also inspect optional `bodyMarkdown`, `bodyText`, `bodyHtml`, and `searchText` fields on docs entries, so callers can opt into body/full-text matching without changing the query API.
+
 ## Server helpers and API key
 
 `@cedros/data-react/server` provides Next.js data-fetching helpers that call cedros-data directly:

package/dist/react/contentCollections.d.ts

@@ -0,0 +1,4 @@
+import type { ContentType } from "./types.js";
+export declare function collectionNameForContentType(contentType: ContentType): string;
+export declare function collectionNamesForContentType(contentType: ContentType): string[];
+export declare function queryEntriesByContentType<T>(serverUrl: string, contentType: ContentType, buildBody: (collectionName: string) => Record<string, unknown>, apiKey?: string): Promise<T>;

package/dist/react/contentCollections.js

@@ -0,0 +1,48 @@
+import { fetchJson } from "./fetch.js";
+const CANONICAL_CONTENT_TYPE_COLLECTIONS = {
+    page: "pages",
+    blog: "blog",
+    docs: "docs",
+    learn: "learn",
+    project: "projects",
+    airdrop: "airdrops",
+};
+const CONTENT_TYPE_COLLECTION_ALIASES = {
+    blog: ["blogs"],
+    learn: ["courses"],
+};
+export function collectionNameForContentType(contentType) {
+    return CANONICAL_CONTENT_TYPE_COLLECTIONS[contentType];
+}
+export function collectionNamesForContentType(contentType) {
+    const canonicalName = collectionNameForContentType(contentType);
+    const aliases = CONTENT_TYPE_COLLECTION_ALIASES[contentType] ?? [];
+    return [canonicalName, ...aliases.filter((alias) => alias !== canonicalName)];
+}
+export async function queryEntriesByContentType(serverUrl, contentType, buildBody, apiKey) {
+    return queryEntriesByCollectionNames(serverUrl, collectionNamesForContentType(contentType), buildBody, apiKey);
+}
+async function queryEntriesByCollectionNames(serverUrl, collectionNames, buildBody, apiKey) {
+    let lastCollectionNotFoundError;
+    const lastCollectionName = collectionNames[collectionNames.length - 1];
+    for (const collectionName of collectionNames) {
+        try {
+            return await fetchJson(serverUrl, "/entries/query", {
+                method: "POST",
+                body: buildBody(collectionName),
+                apiKey,
+            });
+        }
+        catch (error) {
+            if (!isCollectionNotFoundError(error) || collectionName === lastCollectionName) {
+                throw error;
+            }
+            lastCollectionNotFoundError = error;
+        }
+    }
+    throw (lastCollectionNotFoundError ??
+        new Error("@cedros/data-react: no collection names were configured"));
+}
+function isCollectionNotFoundError(error) {
+    return error instanceof Error && /collection not found/i.test(error.message);
+}

package/dist/react/entries.js

@@ -1,4 +1,5 @@
-import { fetchJson, resolveApiKey, resolveServerUrl } from "./fetch.js";
+import { resolveApiKey, resolveServerUrl } from "./fetch.js";
+import { queryEntriesByContentType } from "./contentCollections.js";
 /**
  * Fetches a single blog post by slug, optionally passing visitor_id for metered reads.
  *
@@ -10,7 +11,6 @@ export async function fetchBlogPost(slug, options) {
     const serverUrl = resolveServerUrl(options);
     const apiKey = resolveApiKey(options);
     const body = {
-        collection_name: "blog",
         entry_keys: [slug],
         limit: 1,
         offset: 0,
@@ -18,10 +18,9 @@ export async function fetchBlogPost(slug, options) {
     if (options?.visitorId) {
         body.visitor_id = options.visitorId;
     }
-    const entries = await fetchJson(serverUrl, "/entries/query", {
-        method: "POST",
-        body,
-        apiKey,
-    });
+    const entries = await queryEntriesByContentType(serverUrl, "blog", (collectionName) => ({
+        ...body,
+        collection_name: collectionName,
+    }), apiKey);
     return entries.length > 0 ? entries[0] : null;
 }

package/dist/react/sitemap.js

@@ -1,13 +1,5 @@
-import { fetchJson, resolveApiKey, resolveServerUrl } from "./fetch.js";
-/** Map of content types to their collection names in cedros-data. */
-const CONTENT_TYPE_COLLECTIONS = {
-    page: "pages",
-    blog: "blog",
-    docs: "docs",
-    learn: "learn",
-    project: "projects",
-    airdrop: "airdrops",
-};
+import { resolveApiKey, resolveServerUrl } from "./fetch.js";
+import { queryEntriesByContentType } from "./contentCollections.js";
 /** Default change frequency and priority for each content type. */
 const CONTENT_TYPE_DEFAULTS = {
     page: { changeFrequency: "monthly", priority: 0.8 },
@@ -67,17 +59,12 @@ export async function loadSitemapEntries(options) {
     return entries;
 }
 async function fetchCollectionSlugs(serverUrl, contentType, apiKey) {
-    const collectionName = CONTENT_TYPE_COLLECTIONS[contentType];
     const defaults = CONTENT_TYPE_DEFAULTS[contentType];
-    const records = await fetchJson(serverUrl, "/entries/query", {
-        method: "POST",
-        body: {
-            collection_name: collectionName,
-            limit: 1000,
-            offset: 0,
-        },
-        apiKey,
-    });
+    const records = await queryEntriesByContentType(serverUrl, contentType, (collectionName) => ({
+        collection_name: collectionName,
+        limit: 1000,
+        offset: 0,
+    }), apiKey);
     return records.map((record) => {
         const slug = record.payload.slug ??
             record.payload.route?.replace(/^\//, "") ??

package/dist/react/slugs.js

@@ -1,13 +1,5 @@
-import { fetchJson, resolveApiKey, resolveServerUrl } from "./fetch.js";
-/** Map of content types to their collection names in cedros-data. */
-const CONTENT_TYPE_COLLECTIONS = {
-    page: "pages",
-    blog: "blog",
-    docs: "docs",
-    learn: "learn",
-    project: "projects",
-    airdrop: "airdrops",
-};
+import { resolveApiKey, resolveServerUrl } from "./fetch.js";
+import { queryEntriesByContentType } from "./contentCollections.js";
 /**
  * Returns all slugs for a given content type, for use with
  * Next.js `generateStaticParams`.
@@ -26,16 +18,11 @@ const CONTENT_TYPE_COLLECTIONS = {
 export async function listContentSlugs(contentType, options) {
     const serverUrl = resolveServerUrl(options);
     const apiKey = resolveApiKey(options);
-    const collectionName = CONTENT_TYPE_COLLECTIONS[contentType];
-    const records = await fetchJson(serverUrl, "/entries/query", {
-        method: "POST",
-        body: {
-            collection_name: collectionName,
-            limit: 1000,
-            offset: 0,
-        },
-        apiKey,
-    });
+    const records = await queryEntriesByContentType(serverUrl, contentType, (collectionName) => ({
+        collection_name: collectionName,
+        limit: 1000,
+        offset: 0,
+    }), apiKey);
     return records.map((record) => record.payload.slug ?? record.entry_key);
 }
 /**

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

@@ -1,11 +1,12 @@
 import type { SiteNavigationItem } from "./SiteLayout.js";
 import { type DocsIndexEntry } from "./contentIndex.js";
 import { type DocsSidebarSection } from "./docsNavigation.js";
+import { type DocsTemplateShellOptions } from "./docsTemplateShell.js";
 export interface DocsIndexItem extends DocsIndexEntry {
 }
-export interface DocsIndexTemplateProps {
-    siteTitle: string;
-    navigation: SiteNavigationItem[];
+export interface DocsIndexTemplateProps extends DocsTemplateShellOptions {
+    siteTitle?: string;
+    navigation?: SiteNavigationItem[];
     docs: DocsIndexItem[];
     title?: string;
     description?: string;
@@ -22,10 +23,10 @@ export interface DocsIndexTemplateProps {
     sidebarSections?: DocsSidebarSection[];
     sidebarTitle?: string;
 }
-export declare function DocsIndexTemplate({ siteTitle, navigation, docs, title, description, basePath, currentPath, query, category, tag, sort, page, pageSize, categories, tags, sidebarSections, sidebarTitle }: DocsIndexTemplateProps): React.JSX.Element;
-export interface DocArticleTemplateProps {
-    siteTitle: string;
-    navigation: SiteNavigationItem[];
+export declare function DocsIndexTemplate({ siteTitle, navigation, docs, title, description, basePath, currentPath, query, category, tag, sort, page, pageSize, categories, tags, sidebarSections, sidebarTitle, headless, renderLayout }: DocsIndexTemplateProps): React.JSX.Element;
+export interface DocArticleTemplateProps extends DocsTemplateShellOptions {
+    siteTitle?: string;
+    navigation?: SiteNavigationItem[];
     title: string;
     bodyMarkdown?: string;
     bodyHtml?: string;
@@ -57,4 +58,4 @@ export interface DocArticleTemplateProps {
     };
     editHref?: string;
 }
-export declare function DocArticleTemplate({ siteTitle, navigation, title, bodyMarkdown, bodyHtml, allowUnsafeHtmlFallback, lastUpdated, readingMinutes, basePath, currentPath, searchQuery, docs, sidebarSections, sidebarTitle, breadcrumbs, toc, previousDoc, nextDoc, editHref }: DocArticleTemplateProps): React.JSX.Element;
+export declare function DocArticleTemplate({ siteTitle, navigation, title, bodyMarkdown, bodyHtml, allowUnsafeHtmlFallback, lastUpdated, readingMinutes, basePath, currentPath, searchQuery, docs, sidebarSections, sidebarTitle, breadcrumbs, toc, previousDoc, nextDoc, editHref, headless, renderLayout }: DocArticleTemplateProps): React.JSX.Element;

package/dist/site-templates/DocsTemplates.js

@@ -1,17 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { SiteLayout } from "./SiteLayout.js";
 import { buildContentListHref, collectFilterValues, prepareDocsIndex } from "./contentIndex.js";
 import { Breadcrumbs, ContentPagination } from "./contentUi.js";
-import { buildDocsSidebarSections, withActiveDocsSidebar } from "./docsNavigation.js";
+import { buildHierarchicalDocsSidebarSections, buildDocsSidebarSections, withActiveDocsSidebar } from "./docsNavigation.js";
 import { DocsSidebar } from "./DocsSidebar.js";
+import { renderDocsTemplateShell } from "./docsTemplateShell.js";
 import { MarkdownContent } from "./MarkdownContent.js";
 import { TocScrollSpy } from "./tocScrollSpy.js";
-export function DocsIndexTemplate({ siteTitle, navigation, docs, title = "Documentation", description = "", basePath = "/docs", currentPath, query = "", category = "", tag = "", sort = "title-asc", page = 1, pageSize = 10, categories, tags, sidebarSections, sidebarTitle = "Docs" }) {
+export function DocsIndexTemplate({ siteTitle, navigation, docs, title = "Documentation", description = "", basePath = "/docs", currentPath, query = "", category = "", tag = "", sort = "title-asc", page = 1, pageSize = 10, categories, tags, sidebarSections, sidebarTitle = "Docs", headless = false, renderLayout }) {
     const normalizedFilters = collectFilterValues(docs);
     const resolvedCategories = categories ?? normalizedFilters.categories;
     const resolvedTags = tags ?? normalizedFilters.tags;
     const activePath = currentPath ?? basePath;
-    const resolvedSidebarSections = withActiveDocsSidebar(sidebarSections ?? buildDocsSidebarSections(docs, basePath), activePath);
+    const resolvedSidebarSections = withActiveDocsSidebar(sidebarSections ?? buildDefaultDocsSidebarSections(docs, basePath), activePath);
     const result = prepareDocsIndex(docs, {
         query,
         category,
@@ -20,21 +20,31 @@ export function DocsIndexTemplate({ siteTitle, navigation, docs, title = "Docume
         page,
         pageSize
     });
-    return (_jsx(SiteLayout, { siteTitle: siteTitle, navigation: navigation, children: _jsxs("section", { className: "cedros-site__docs-page", children: [_jsx(DocsSidebar, { title: sidebarTitle, basePath: basePath, searchQuery: query, sections: resolvedSidebarSections }), _jsxs("div", { className: "cedros-site__docs-main", children: [_jsxs("section", { className: "cedros-site__card", children: [_jsx("span", { className: "cedros-site__pill", children: "docs" }), _jsx("h1", { className: "cedros-site__title", style: { marginTop: "0.6rem" }, children: title }), description && _jsx("p", { className: "cedros-site__subtitle", children: description }), _jsxs("p", { className: "cedros-site__entry-meta", style: { marginTop: "0.6rem" }, children: [result.totalItems, " results"] })] }), _jsx(DocsIndexControls, { basePath: basePath, query: query, category: category, tag: tag, sort: sort, categories: resolvedCategories, tags: resolvedTags }), result.totalItems === 0 && (_jsxs("section", { className: "cedros-site__card cedros-site__empty-state", children: [_jsx("h2", { className: "cedros-site__title", style: { fontSize: "1.25rem" }, children: "No documentation pages found" }), _jsx("p", { className: "cedros-site__subtitle", style: { marginTop: "0.6rem" }, children: "Try a broader query or clear filters." })] })), result.totalItems > 0 && (_jsxs(_Fragment, { children: [_jsx("section", { className: "cedros-site__content-grid cedros-site__content-grid--docs", children: result.items.map((doc) => (_jsxs("article", { className: "cedros-site__card cedros-site__entry-card", children: [_jsx("h2", { className: "cedros-site__entry-title", children: _jsx("a", { href: `${basePath}/${doc.slug}`, children: doc.title }) }), doc.description && _jsx("p", { className: "cedros-site__subtitle", children: doc.description }), (doc.lastUpdated || doc.category) && (_jsx("p", { className: "cedros-site__entry-meta", children: [doc.category, doc.lastUpdated ? `Updated ${doc.lastUpdated}` : ""]
-                                                    .filter(Boolean)
-                                                    .join(" • ") })), doc.tags && doc.tags.length > 0 && (_jsx("div", { className: "cedros-site__tag-list", children: doc.tags.map((entryTag) => (_jsx("a", { href: buildContentListHref(basePath, {
-                                                        q: query,
-                                                        category,
-                                                        tag: entryTag,
-                                                        sort
-                                                    }), className: "cedros-site__pill", children: entryTag }, entryTag))) }))] }, doc.slug))) }), _jsx(ContentPagination, { basePath: basePath, page: result.page, totalPages: result.totalPages, query: { q: query, category, tag, sort } })] }))] })] }) }));
+    return renderDocsTemplateShell((_jsxs("section", { className: "cedros-site__docs-page", children: [_jsx(DocsSidebar, { title: sidebarTitle, basePath: basePath, searchQuery: query, sections: resolvedSidebarSections }), _jsxs("div", { className: "cedros-site__docs-main", children: [_jsxs("section", { className: "cedros-site__card", children: [_jsx("span", { className: "cedros-site__pill", children: "docs" }), _jsx("h1", { className: "cedros-site__title", style: { marginTop: "0.6rem" }, children: title }), description && _jsx("p", { className: "cedros-site__subtitle", children: description }), _jsxs("p", { className: "cedros-site__entry-meta", style: { marginTop: "0.6rem" }, children: [result.totalItems, " results"] })] }), _jsx(DocsIndexControls, { basePath: basePath, query: query, category: category, tag: tag, sort: sort, categories: resolvedCategories, tags: resolvedTags }), result.totalItems === 0 && (_jsxs("section", { className: "cedros-site__card cedros-site__empty-state", children: [_jsx("h2", { className: "cedros-site__title", style: { fontSize: "1.25rem" }, children: "No documentation pages found" }), _jsx("p", { className: "cedros-site__subtitle", style: { marginTop: "0.6rem" }, children: "Try a broader query or clear filters." })] })), result.totalItems > 0 && (_jsxs(_Fragment, { children: [_jsx("section", { className: "cedros-site__content-grid cedros-site__content-grid--docs", children: result.items.map((doc) => (_jsxs("article", { className: "cedros-site__card cedros-site__entry-card", children: [_jsx("h2", { className: "cedros-site__entry-title", children: _jsx("a", { href: `${basePath}/${doc.slug}`, children: doc.title }) }), doc.description && _jsx("p", { className: "cedros-site__subtitle", children: doc.description }), (doc.lastUpdated || doc.category) && (_jsx("p", { className: "cedros-site__entry-meta", children: [doc.category, doc.lastUpdated ? `Updated ${doc.lastUpdated}` : ""]
+                                                .filter(Boolean)
+                                                .join(" • ") })), doc.tags && doc.tags.length > 0 && (_jsx("div", { className: "cedros-site__tag-list", children: doc.tags.map((entryTag) => (_jsx("a", { href: buildContentListHref(basePath, {
+                                                    q: query,
+                                                    category,
+                                                    tag: entryTag,
+                                                    sort
+                                                }), className: "cedros-site__pill", children: entryTag }, entryTag))) }))] }, doc.slug))) }), _jsx(ContentPagination, { basePath: basePath, page: result.page, totalPages: result.totalPages, query: { q: query, category, tag, sort } })] }))] })] })), {
+        siteTitle,
+        navigation,
+        headless,
+        renderLayout
+    });
 }
-export function DocArticleTemplate({ siteTitle, navigation, title, bodyMarkdown, bodyHtml, allowUnsafeHtmlFallback = false, lastUpdated, readingMinutes, basePath = "/docs", currentPath, searchQuery = "", docs = [], sidebarSections, sidebarTitle = "Docs", breadcrumbs = [], toc = [], previousDoc, nextDoc, editHref }) {
+export function DocArticleTemplate({ siteTitle, navigation, title, bodyMarkdown, bodyHtml, allowUnsafeHtmlFallback = false, lastUpdated, readingMinutes, basePath = "/docs", currentPath, searchQuery = "", docs = [], sidebarSections, sidebarTitle = "Docs", breadcrumbs = [], toc = [], previousDoc, nextDoc, editHref, headless = false, renderLayout }) {
     const activePath = currentPath ?? breadcrumbs[breadcrumbs.length - 1]?.href;
-    const resolvedSidebarSections = withActiveDocsSidebar(sidebarSections ?? buildDocsSidebarSections(docs, basePath), activePath);
-    return (_jsx(SiteLayout, { siteTitle: siteTitle, navigation: navigation, children: _jsxs("section", { className: "cedros-site__docs-page cedros-site__docs-page--article", children: [_jsx(DocsSidebar, { title: sidebarTitle, basePath: basePath, searchQuery: searchQuery, sections: resolvedSidebarSections }), _jsxs("article", { className: "cedros-site__card cedros-site__article cedros-site__docs-article", children: [_jsx(Breadcrumbs, { trail: breadcrumbs }), _jsxs("div", { className: "cedros-site__article-header", children: [_jsx("span", { className: "cedros-site__pill", children: "docs" }), _jsx("h1", { className: "cedros-site__title", children: title }), (lastUpdated || readingMinutes) && (_jsx("p", { className: "cedros-site__entry-meta", children: [lastUpdated ? `Last updated ${lastUpdated}` : "", readingTime(readingMinutes)]
-                                        .filter(Boolean)
-                                        .join(" • ") }))] }), _jsx(MarkdownContent, { bodyMarkdown: bodyMarkdown, bodyHtml: bodyHtml, allowUnsafeHtmlFallback: allowUnsafeHtmlFallback }), (previousDoc || nextDoc || editHref) && (_jsxs("footer", { className: "cedros-site__doc-footer", children: [previousDoc && (_jsxs("a", { href: previousDoc.href, className: "cedros-site__nav-link", children: ["\u2190 ", previousDoc.title] })), nextDoc && (_jsxs("a", { href: nextDoc.href, className: "cedros-site__nav-link", children: [nextDoc.title, " \u2192"] })), editHref && (_jsx("a", { href: editHref, className: "cedros-site__nav-link", children: "Suggest edit" }))] }))] }), toc.length > 0 && (_jsxs("aside", { className: "cedros-site__card cedros-site__toc", children: [_jsx("h2", { className: "cedros-site__toc-title", children: "On this page" }), _jsx(TocScrollSpy, { entries: toc })] }))] }) }));
+    const resolvedSidebarSections = withActiveDocsSidebar(sidebarSections ?? buildDefaultDocsSidebarSections(docs, basePath), activePath);
+    return renderDocsTemplateShell((_jsxs("section", { className: "cedros-site__docs-page cedros-site__docs-page--article", children: [_jsx(DocsSidebar, { title: sidebarTitle, basePath: basePath, searchQuery: searchQuery, sections: resolvedSidebarSections }), _jsxs("article", { className: "cedros-site__card cedros-site__article cedros-site__docs-article", children: [_jsx(Breadcrumbs, { trail: breadcrumbs }), _jsxs("div", { className: "cedros-site__article-header", children: [_jsx("span", { className: "cedros-site__pill", children: "docs" }), _jsx("h1", { className: "cedros-site__title", children: title }), (lastUpdated || readingMinutes) && (_jsx("p", { className: "cedros-site__entry-meta", children: [lastUpdated ? `Last updated ${lastUpdated}` : "", readingTime(readingMinutes)]
+                                    .filter(Boolean)
+                                    .join(" • ") }))] }), _jsx(MarkdownContent, { bodyMarkdown: bodyMarkdown, bodyHtml: bodyHtml, allowUnsafeHtmlFallback: allowUnsafeHtmlFallback }), (previousDoc || nextDoc || editHref) && (_jsxs("footer", { className: "cedros-site__doc-footer", children: [previousDoc && (_jsxs("a", { href: previousDoc.href, className: "cedros-site__nav-link", children: ["\u2190 ", previousDoc.title] })), nextDoc && (_jsxs("a", { href: nextDoc.href, className: "cedros-site__nav-link", children: [nextDoc.title, " \u2192"] })), editHref && (_jsx("a", { href: editHref, className: "cedros-site__nav-link", children: "Suggest edit" }))] }))] }), toc.length > 0 && (_jsxs("aside", { className: "cedros-site__card cedros-site__toc", children: [_jsx("h2", { className: "cedros-site__toc-title", children: "On this page" }), _jsx(TocScrollSpy, { entries: toc })] }))] })), {
+        siteTitle,
+        navigation,
+        headless,
+        renderLayout
+    });
 }
 function DocsIndexControls({ basePath, query, category, tag, sort, categories, tags }) {
     return (_jsxs("form", { method: "get", action: basePath, className: "cedros-site__controls cedros-site__card", children: [_jsxs("label", { className: "cedros-site__control", children: [_jsx("span", { children: "Search" }), _jsx("input", { type: "search", name: "q", defaultValue: query, placeholder: "Search docs" })] }), _jsxs("label", { className: "cedros-site__control", children: [_jsx("span", { children: "Category" }), _jsxs("select", { name: "category", defaultValue: category, children: [_jsx("option", { value: "", children: "All" }), categories.map((entry) => (_jsx("option", { value: entry, children: entry }, entry)))] })] }), _jsxs("label", { className: "cedros-site__control", children: [_jsx("span", { children: "Tag" }), _jsxs("select", { name: "tag", defaultValue: tag, children: [_jsx("option", { value: "", children: "All" }), tags.map((entry) => (_jsx("option", { value: entry, children: entry }, entry)))] })] }), _jsxs("label", { className: "cedros-site__control", children: [_jsx("span", { children: "Sort" }), _jsxs("select", { name: "sort", defaultValue: sort, children: [_jsx("option", { value: "title-asc", children: "Title A-Z" }), _jsx("option", { value: "title-desc", children: "Title Z-A" }), _jsx("option", { value: "updated-desc", children: "Recently updated" }), _jsx("option", { value: "updated-asc", children: "Least recently updated" })] })] }), _jsxs("div", { className: "cedros-site__control-actions", children: [_jsx("button", { className: "cedros-site__nav-link", type: "submit", children: "Apply" }), _jsx("a", { className: "cedros-site__nav-link", href: basePath, children: "Clear" })] })] }));
@@ -45,3 +55,8 @@ function readingTime(minutes) {
     }
     return `${minutes} min read`;
 }
+function buildDefaultDocsSidebarSections(docs, basePath) {
+    return docs.some((doc) => doc.slug.includes("/"))
+        ? buildHierarchicalDocsSidebarSections(docs, basePath)
+        : buildDocsSidebarSections(docs, basePath);
+}

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

@@ -40,6 +40,10 @@ export interface DocsIndexEntry {
     category?: string;
     tags?: string[];
     lastUpdated?: string;
+    bodyMarkdown?: string;
+    bodyHtml?: string;
+    bodyText?: string;
+    searchText?: string;
 }
 export interface DocsIndexQuery {
     query?: string;

package/dist/site-templates/contentIndex.js

@@ -125,7 +125,7 @@ function matchesDocsQuery(entry, query) {
     if (!normalizedQuery) {
         return true;
     }
-    const haystack = [entry.title, entry.description, entry.category, ...(entry.tags ?? [])].join(" ").toLowerCase();
+    const haystack = buildDocsSearchText(entry);
     return haystack.includes(normalizedQuery);
 }
 function compareBlogEntries(left, right, sort) {
@@ -159,6 +159,20 @@ function toTimestamp(value) {
     const parsed = Date.parse(value ?? "");
     return Number.isNaN(parsed) ? 0 : parsed;
 }
+function buildDocsSearchText(entry) {
+    return [
+        entry.title,
+        entry.description,
+        entry.category,
+        ...(entry.tags ?? []),
+        entry.searchText,
+        entry.bodyText,
+        entry.bodyMarkdown,
+        entry.bodyHtml
+    ]
+        .join(" ")
+        .toLowerCase();
+}
 function paginate(items, pageInput, pageSizeInput) {
     const pageSize = sanitizePositiveInt(pageSizeInput, 10);
     const totalItems = items.length;

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

@@ -4,7 +4,7 @@ export interface DocsSidebarItem {
     label: string;
     href: string;
     isActive?: boolean;
-    depth?: 0 | 1 | 2;
+    depth?: number;
     badge?: string;
 }
 export interface DocsSidebarSection {
@@ -14,5 +14,34 @@ export interface DocsSidebarSection {
     /** When true, section renders collapsed by default in the sidebar. */
     collapsed?: boolean;
 }
+export interface DocsTreeNode<T extends DocsIndexEntry = DocsIndexEntry> {
+    key: string;
+    slug: string;
+    label: string;
+    href?: string;
+    entry?: T;
+    children: DocsTreeNode<T>[];
+}
+export interface DocsTreeSection<T extends DocsIndexEntry = DocsIndexEntry> {
+    key: string;
+    label: string;
+    nodes: DocsTreeNode<T>[];
+}
+export interface DocsPagerLink<T extends DocsIndexEntry = DocsIndexEntry> {
+    title: string;
+    href: string;
+    entry: T;
+}
+export interface DocsPrevNext<T extends DocsIndexEntry = DocsIndexEntry> {
+    previousDoc?: DocsPagerLink<T>;
+    nextDoc?: DocsPagerLink<T>;
+}
+export interface FetchDocEntryOptions {
+    basePath?: string;
+}
 export declare function buildDocsSidebarSections(docs: DocsIndexEntry[], basePath?: string): DocsSidebarSection[];
+export declare function fetchDocEntry<T extends DocsIndexEntry>(docs: T[], slugOrPath: string, options?: FetchDocEntryOptions): T | undefined;
+export declare function buildDocsTree<T extends DocsIndexEntry>(docs: T[], basePath?: string): DocsTreeSection<T>[];
+export declare function buildHierarchicalDocsSidebarSections<T extends DocsIndexEntry>(docs: T[], basePath?: string): DocsSidebarSection[];
+export declare function buildDocsPrevNext<T extends DocsIndexEntry>(docs: T[], currentSlugOrPath: string, options?: FetchDocEntryOptions): DocsPrevNext<T>;
 export declare function withActiveDocsSidebar(sections: DocsSidebarSection[], currentPath?: string): DocsSidebarSection[];

package/dist/site-templates/docsNavigation.js

@@ -8,7 +8,7 @@ export function buildDocsSidebarSections(docs, basePath = "/docs") {
         current.items.push({
             key: doc.slug,
             label: doc.title,
-            href: `${basePath}/${doc.slug}`
+            href: buildDocHref(basePath, doc.slug)
         });
         grouped.set(sectionKey, current);
     });
@@ -20,6 +20,52 @@ export function buildDocsSidebarSections(docs, basePath = "/docs") {
     }))
         .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;
+}
+export function buildHierarchicalDocsSidebarSections(docs, basePath = "/docs") {
+    return buildDocsTree(docs, basePath)
+        .map((section) => ({
+        key: section.key,
+        label: section.label,
+        items: flattenDocsTreeNodes(section.nodes)
+    }))
+        .filter((section) => section.items.length > 0);
+}
+export function buildDocsPrevNext(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);
+    if (currentIndex === -1) {
+        return {};
+    }
+    return {
+        previousDoc: buildDocsPagerLink(docs[currentIndex - 1], options.basePath),
+        nextDoc: buildDocsPagerLink(docs[currentIndex + 1], options.basePath)
+    };
+}
 export function withActiveDocsSidebar(sections, currentPath) {
     if (!currentPath) {
         return sections.map((section) => ({
@@ -48,3 +94,88 @@ export function withActiveDocsSidebar(sections, currentPath) {
         })
     }));
 }
+function buildDocHref(basePath, slug) {
+    const normalizedBasePath = normalizeRoutePath(basePath);
+    const normalizedSlug = normalizeDocSlug(slug);
+    if (!normalizedSlug) {
+        return normalizedBasePath;
+    }
+    if (normalizedBasePath === "/") {
+        return `/${normalizedSlug}`;
+    }
+    return `${normalizedBasePath}/${normalizedSlug}`;
+}
+function normalizeDocSlug(slug) {
+    return slug.trim().replace(/^\/+|\/+$/gu, "");
+}
+function normalizeDocLookup(value, basePath = "/docs") {
+    const normalizedValue = normalizeRoutePath(value).replace(/^\/+/u, "");
+    const normalizedBasePath = normalizeRoutePath(basePath).replace(/^\/+/u, "");
+    if (!normalizedBasePath) {
+        return normalizedValue;
+    }
+    if (normalizedValue === normalizedBasePath) {
+        return "";
+    }
+    if (normalizedValue.startsWith(`${normalizedBasePath}/`)) {
+        return normalizedValue.slice(normalizedBasePath.length + 1);
+    }
+    return normalizedValue;
+}
+function insertDocTreeNode(nodes, doc, basePath) {
+    const segments = normalizedDocSegments(doc.slug);
+    let cursor = nodes;
+    segments.forEach((segment, index) => {
+        const slug = segments.slice(0, index + 1).join("/");
+        let node = cursor.find((candidate) => candidate.slug === slug);
+        if (!node) {
+            node = {
+                key: slug || "index",
+                slug,
+                label: humanizeDocSegment(segment),
+                children: []
+            };
+            cursor.push(node);
+        }
+        if (index === segments.length - 1) {
+            node.entry = doc;
+            node.href = buildDocHref(basePath, doc.slug);
+            node.label = doc.title;
+        }
+        cursor = node.children;
+    });
+}
+function normalizedDocSegments(slug) {
+    const normalized = normalizeDocSlug(slug);
+    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)
+            });
+        }
+        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 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,7 @@ 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 { buildDocsSidebarSections, buildDocsTree, buildHierarchicalDocsSidebarSections, buildDocsPrevNext, fetchDocEntry, withActiveDocsSidebar, type DocsTreeNode, type DocsTreeSection, type DocsPagerLink, type DocsPrevNext, type FetchDocEntryOptions, type DocsSidebarItem, type DocsSidebarSection } from "./docsNavigation.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,7 @@ 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 { buildDocsSidebarSections, buildDocsTree, buildHierarchicalDocsSidebarSections, buildDocsPrevNext, fetchDocEntry, withActiveDocsSidebar } from "./docsNavigation.js";
 export { MarkdownContent } from "./MarkdownContent.js";
 export { extractTocFromMarkdown } from "./tocExtractor.js";
 export { DocsSidebar } from "./DocsSidebar.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cedros/data-react",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "React components, page templates, and Next.js integration for cedros-data",
   "type": "module",
   "main": "./dist/react/index.js",