@cedros/data-react 0.1.5 → 0.1.7

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/react/theme.d.ts

@@ -0,0 +1,33 @@
+/** Theme mode selector. */
+export type ThemeMode = "light" | "dark";
+/**
+ * Typed theme token overrides using CSS variable names.
+ *
+ * Matches the `--cedros-*` variable namespace shared across
+ * cedros-login, cedros-pay, and cedros-data.
+ */
+export interface CedrosDataThemeOverrides {
+    "--cedros-background"?: string;
+    "--cedros-foreground"?: string;
+    "--cedros-muted"?: string;
+    "--cedros-muted-foreground"?: string;
+    "--cedros-border"?: string;
+    "--cedros-link"?: string;
+    "--cedros-primary"?: string;
+    "--cedros-primary-foreground"?: string;
+    "--cedros-accent"?: string;
+    "--cedros-ring"?: string;
+    "--cedros-radius"?: string;
+    "--cedros-success"?: string;
+    "--cedros-error"?: string;
+    [key: string]: string | undefined;
+}
+/** Value returned by `useCedrosDataTheme()`. */
+export interface CedrosDataThemeValue {
+    mode: ThemeMode;
+    isDark: boolean;
+    className: string;
+    style: React.CSSProperties;
+    unstyled: boolean;
+    overrides?: CedrosDataThemeOverrides;
+}

package/dist/react/theme.js

@@ -0,0 +1 @@
+export {};

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/SiteFooter.d.ts

@@ -1,4 +1,9 @@
 import type { ReactNode } from "react";
+/** Layout options for the site footer. */
+export interface FooterLayoutOptions {
+    /** Full-width stretches content to viewport edges. Default: "contained". */
+    width?: "contained" | "full";
+}
 export interface SiteFooterLink {
     key: string;
     label: string;
@@ -9,5 +14,6 @@ export interface SiteFooterProps {
     note?: string;
     links?: SiteFooterLink[];
     rightSlot?: ReactNode;
+    layout?: FooterLayoutOptions;
 }
-export declare function SiteFooter({ siteTitle, note, links, rightSlot }: SiteFooterProps): React.JSX.Element;
+export declare function SiteFooter({ siteTitle, note, links, rightSlot, layout }: SiteFooterProps): React.JSX.Element;

package/dist/site-templates/SiteFooter.js

@@ -1,4 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-export function SiteFooter({ siteTitle, note, links = [], rightSlot }) {
-    return (_jsx("footer", { className: "cedros-site__footer", children: _jsxs("div", { className: "cedros-site__container cedros-site__footer-inner", children: [_jsxs("div", { className: "cedros-site__footer-brand", children: [_jsx("span", { children: siteTitle }), note && _jsx("span", { children: note })] }), links.length > 0 && (_jsx("nav", { className: "cedros-site__footer-links", "aria-label": "Footer", children: links.map((link) => (_jsx("a", { href: link.route, className: "cedros-site__footer-link", children: link.label }, link.key))) })), rightSlot && _jsx("div", { className: "cedros-site__footer-right", children: rightSlot })] }) }));
+export function SiteFooter({ siteTitle, note, links = [], rightSlot, layout }) {
+    const footerClasses = layout?.width === "full"
+        ? "cedros-site__footer cedros-site__footer--full"
+        : "cedros-site__footer";
+    return (_jsx("footer", { className: footerClasses, children: _jsxs("div", { className: "cedros-site__container cedros-site__footer-inner", children: [_jsxs("div", { className: "cedros-site__footer-brand", children: [_jsx("span", { children: siteTitle }), note && _jsx("span", { children: note })] }), links.length > 0 && (_jsx("nav", { className: "cedros-site__footer-links", "aria-label": "Footer", children: links.map((link) => (_jsx("a", { href: link.route, className: "cedros-site__footer-link", children: link.label }, link.key))) })), rightSlot && _jsx("div", { className: "cedros-site__footer-right", children: rightSlot })] }) }));
 }

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

@@ -1,14 +1,22 @@
 import type { ReactNode } from "react";
+import type { NavLayoutOptions } from "./TopNav.js";
+import type { FooterLayoutOptions } from "./SiteFooter.js";
 export interface SiteNavigationItem {
     key: string;
     label: string;
     route: string;
 }
+/** Combined layout options for the full site shell. */
+export interface SiteLayoutOptions {
+    nav?: NavLayoutOptions;
+    footer?: FooterLayoutOptions;
+}
 export interface SiteLayoutProps {
     siteTitle: string;
     navigation: SiteNavigationItem[];
     children: ReactNode;
     brandHref?: string;
     footerNote?: string;
+    layout?: SiteLayoutOptions;
 }
-export declare function SiteLayout({ siteTitle, navigation, children, brandHref, footerNote }: SiteLayoutProps): React.JSX.Element;
+export declare function SiteLayout({ siteTitle, navigation, children, brandHref, footerNote, layout }: SiteLayoutProps): React.JSX.Element;

package/dist/site-templates/SiteLayout.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { SiteFooter } from "./SiteFooter.js";
 import { TopNav } from "./TopNav.js";
-export function SiteLayout({ siteTitle, navigation, children, brandHref = "/", footerNote = "Powered by cedros-data" }) {
-    return (_jsxs("div", { className: "cedros-site", children: [_jsx(TopNav, { siteTitle: siteTitle, navigation: navigation, brandHref: brandHref }), _jsx("main", { className: "cedros-site__main", children: _jsx("div", { className: "cedros-site__container", children: children }) }), _jsx(SiteFooter, { siteTitle: siteTitle, note: footerNote })] }));
+export function SiteLayout({ siteTitle, navigation, children, brandHref = "/", footerNote = "Powered by cedros-data", layout }) {
+    return (_jsxs("div", { className: "cedros-site", children: [_jsx(TopNav, { siteTitle: siteTitle, navigation: navigation, brandHref: brandHref, layout: layout?.nav }), _jsx("main", { className: "cedros-site__main", children: _jsx("div", { className: "cedros-site__container", children: children }) }), _jsx(SiteFooter, { siteTitle: siteTitle, note: footerNote, layout: layout?.footer })] }));
 }

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

@@ -1,10 +1,20 @@
 import type { ReactNode } from "react";
 import type { SiteNavigationItem } from "./SiteLayout.js";
+/** Layout options for the top navigation bar. */
+export interface NavLayoutOptions {
+    /** Full-width stretches logo/actions to viewport edges. Default: "contained". */
+    width?: "contained" | "full";
+    /** Where the main nav links sit. Default: "right". */
+    linkPosition?: "center" | "right";
+    /** Visual style for nav links. Default: "pill". */
+    linkStyle?: "text" | "pill";
+}
 export interface TopNavProps {
     siteTitle: string;
     navigation: SiteNavigationItem[];
     brandHref?: string;
     rightSlot?: ReactNode;
     currentPath?: string;
+    layout?: NavLayoutOptions;
 }
-export declare function TopNav({ siteTitle, navigation, brandHref, rightSlot, currentPath }: TopNavProps): React.JSX.Element;
+export declare function TopNav({ siteTitle, navigation, brandHref, rightSlot, currentPath, layout }: TopNavProps): React.JSX.Element;

package/dist/site-templates/TopNav.js

@@ -1,8 +1,18 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { withActiveRouteState } from "./routing.js";
-export function TopNav({ siteTitle, navigation, brandHref = "/", rightSlot, currentPath }) {
+export function TopNav({ siteTitle, navigation, brandHref = "/", rightSlot, currentPath, layout }) {
     const activeNavigation = currentPath
         ? withActiveRouteState(navigation, currentPath)
         : navigation.map((item) => ({ ...item, isActive: false }));
-    return (_jsx("header", { className: "cedros-site__header", children: _jsxs("div", { className: "cedros-site__container cedros-site__header-inner", children: [_jsx("a", { href: brandHref, className: "cedros-site__brand", children: siteTitle }), _jsx("nav", { className: "cedros-site__nav", "aria-label": "Primary", children: activeNavigation.map((item) => (_jsx("a", { href: item.route, className: `cedros-site__nav-link${item.isActive ? " cedros-site__nav-link--active" : ""}`, "aria-current": item.isActive ? "page" : undefined, children: item.label }, item.key))) }), rightSlot && _jsx("div", { className: "cedros-site__header-right", children: rightSlot })] }) }));
+    const headerClasses = buildHeaderClasses(layout);
+    const linkStyleClass = layout?.linkStyle === "text" ? " cedros-site__nav-link--text" : "";
+    return (_jsx("header", { className: headerClasses, children: _jsxs("div", { className: "cedros-site__container cedros-site__header-inner", children: [_jsx("a", { href: brandHref, className: "cedros-site__brand", children: siteTitle }), _jsx("nav", { className: "cedros-site__nav", "aria-label": "Primary", children: activeNavigation.map((item) => (_jsx("a", { href: item.route, className: `cedros-site__nav-link${linkStyleClass}${item.isActive ? " cedros-site__nav-link--active" : ""}`, "aria-current": item.isActive ? "page" : undefined, children: item.label }, item.key))) }), rightSlot && _jsx("div", { className: "cedros-site__header-right", children: rightSlot })] }) }));
+}
+function buildHeaderClasses(layout) {
+    let classes = "cedros-site__header";
+    if (layout?.width === "full")
+        classes += " cedros-site__header--full";
+    if (layout?.linkPosition === "center")
+        classes += " cedros-site__header--nav-center";
+    return classes;
 }

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

@@ -1,11 +1,11 @@
-export { SiteLayout, type SiteLayoutProps, type SiteNavigationItem } from "./SiteLayout.js";
-export { TopNav, type TopNavProps } from "./TopNav.js";
-export { SiteFooter, type SiteFooterProps, type SiteFooterLink } from "./SiteFooter.js";
+export { SiteLayout, type SiteLayoutProps, type SiteLayoutOptions, type SiteNavigationItem } from "./SiteLayout.js";
+export { TopNav, type TopNavProps, type NavLayoutOptions } from "./TopNav.js";
+export { SiteFooter, type SiteFooterProps, type SiteFooterLink, type FooterLayoutOptions } from "./SiteFooter.js";
 export { DashboardShell, type DashboardShellProps, type DashboardNavItem } from "./DashboardShell.js";
 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";