@cedros/data-react 0.1.7 → 0.1.8

package/dist/docsContract.d.ts

@@ -0,0 +1,56 @@
+export interface DocsTocHeading {
+    id: string;
+    label: string;
+    depth?: 2 | 3 | 4;
+}
+export interface DocsBreadcrumb {
+    label: string;
+    href: string;
+}
+export interface DocsEntryRecord {
+    slug: string;
+    title: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    lastUpdated?: string;
+    bodyMarkdown?: string;
+    bodyHtml?: string;
+    bodyText?: string;
+    searchText?: string;
+    status?: string;
+    productSlug?: string;
+    productLabel?: string;
+    productOrder?: number;
+    sectionKey?: string;
+    sectionLabel?: string;
+    sectionOrder?: number;
+    order?: number;
+    readingMinutes?: number;
+    toc?: DocsTocHeading[];
+    breadcrumbs?: DocsBreadcrumb[];
+    editHref?: string;
+    sourcePath?: string;
+    sourceHref?: string;
+    navLabel?: string;
+    navOrder?: number;
+    aliases?: string[];
+    badge?: string;
+}
+export interface DocsNormalizationOptions {
+    aliases?: Record<string, string>;
+    basePath?: string;
+}
+export interface DocsFilterOptions extends DocsNormalizationOptions {
+    productSlug?: string;
+    sectionKey?: string;
+    includeDrafts?: boolean;
+}
+export interface SortDocsEntriesOptions {
+    preserveSourceOrder?: boolean;
+}
+export declare function normalizeDocsSlug(value: string, options?: DocsNormalizationOptions): string;
+export declare function normalizeDocsHref(href: string, options?: DocsNormalizationOptions): string;
+export declare function matchesDocsEntryFilter(entry: DocsEntryRecord, options?: DocsFilterOptions): boolean;
+export declare function compareDocsEntriesByOrder(left: DocsEntryRecord, right: DocsEntryRecord): number;
+export declare function sortDocsEntries<T extends DocsEntryRecord>(entries: T[], options?: SortDocsEntriesOptions): T[];

package/dist/docsContract.js

@@ -0,0 +1,136 @@
+const DEFAULT_DOCS_BASE_PATH = "/docs";
+const ABSOLUTE_URL_PATTERN = /^[a-z][a-z\d+\-.]*:\/\//iu;
+export function normalizeDocsSlug(value, options = {}) {
+    const { pathname } = splitHref(value);
+    const basePath = normalizeBasePath(options.basePath);
+    let relativePath = trimSlashes(pathname);
+    if (!relativePath) {
+        return "";
+    }
+    const normalizedBase = trimSlashes(basePath);
+    if (normalizedBase) {
+        if (relativePath === normalizedBase) {
+            relativePath = "";
+        }
+        else if (relativePath.startsWith(`${normalizedBase}/`)) {
+            relativePath = relativePath.slice(normalizedBase.length + 1);
+        }
+    }
+    const segments = relativePath
+        .split("/")
+        .filter(Boolean)
+        .map(slugifySegment);
+    if (segments.length === 0) {
+        return "";
+    }
+    const aliasMap = normalizeAliasMap(options.aliases);
+    if (segments[0] && aliasMap[segments[0]]) {
+        segments[0] = aliasMap[segments[0]];
+    }
+    return segments.join("/");
+}
+export function normalizeDocsHref(href, options = {}) {
+    const { origin, suffix } = splitHref(href);
+    const slug = normalizeDocsSlug(href, options);
+    const basePath = normalizeBasePath(options.basePath);
+    const path = slug ? `${basePath}/${slug}`.replace(/\/+/gu, "/") : basePath;
+    if (origin) {
+        return `${origin}${path}${suffix}`;
+    }
+    return `${path}${suffix}`;
+}
+export function matchesDocsEntryFilter(entry, options = {}) {
+    if (!options.includeDrafts && entry.status?.trim().toLowerCase() === "draft") {
+        return false;
+    }
+    if (options.productSlug) {
+        const entryProduct = normalizeDocsSlug(entry.productSlug ?? "", options);
+        const expectedProduct = normalizeDocsSlug(options.productSlug, options);
+        if (!entryProduct || entryProduct !== expectedProduct) {
+            return false;
+        }
+    }
+    if (options.sectionKey) {
+        const entrySection = normalizeFragment(entry.sectionKey);
+        const expectedSection = normalizeFragment(options.sectionKey);
+        if (!entrySection || entrySection !== expectedSection) {
+            return false;
+        }
+    }
+    return true;
+}
+export function compareDocsEntriesByOrder(left, right) {
+    return (compareOptionalNumber(left.productOrder, right.productOrder) ||
+        compareOptionalText(left.productSlug, right.productSlug) ||
+        compareOptionalNumber(left.sectionOrder, right.sectionOrder) ||
+        compareOptionalText(left.sectionKey, right.sectionKey) ||
+        compareOptionalNumber(left.order, right.order) ||
+        compareOptionalNumber(left.navOrder, right.navOrder));
+}
+export function sortDocsEntries(entries, options = {}) {
+    const preserveSourceOrder = options.preserveSourceOrder !== false;
+    return entries
+        .map((entry, index) => ({ entry, index }))
+        .sort((left, right) => {
+        const byOrder = compareDocsEntriesByOrder(left.entry, right.entry);
+        if (byOrder !== 0) {
+            return byOrder;
+        }
+        if (preserveSourceOrder) {
+            return left.index - right.index;
+        }
+        return (compareOptionalText(left.entry.navLabel ?? left.entry.title, right.entry.navLabel ?? right.entry.title) ||
+            compareOptionalText(left.entry.slug, right.entry.slug) ||
+            left.index - right.index);
+    })
+        .map(({ entry }) => entry);
+}
+function splitHref(value) {
+    const [withoutHash, hash = ""] = value.split("#", 2);
+    const [withoutQuery, query = ""] = withoutHash.split("?", 2);
+    const suffix = `${query ? `?${query}` : ""}${hash ? `#${hash}` : ""}`;
+    if (ABSOLUTE_URL_PATTERN.test(withoutQuery)) {
+        const url = new URL(withoutQuery);
+        return {
+            origin: url.origin,
+            pathname: url.pathname,
+            suffix,
+        };
+    }
+    return {
+        origin: "",
+        pathname: withoutQuery,
+        suffix,
+    };
+}
+function normalizeBasePath(basePath = DEFAULT_DOCS_BASE_PATH) {
+    const trimmed = `/${trimSlashes(basePath)}`;
+    return trimmed === "/" ? DEFAULT_DOCS_BASE_PATH : trimmed;
+}
+function normalizeAliasMap(aliases) {
+    if (!aliases) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(aliases)
+        .map(([from, to]) => [slugifySegment(from), slugifySegment(to)])
+        .filter(([from, to]) => from && to));
+}
+function trimSlashes(value) {
+    return value.trim().replace(/^\/+|\/+$/gu, "");
+}
+function slugifySegment(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+|-+$/gu, "");
+}
+function normalizeFragment(value) {
+    return slugifySegment(value ?? "");
+}
+function compareOptionalNumber(left, right) {
+    return (left ?? Number.MAX_SAFE_INTEGER) - (right ?? Number.MAX_SAFE_INTEGER);
+}
+function compareOptionalText(left, right) {
+    return (left ?? "").localeCompare(right ?? "");
+}

package/dist/react/docs.d.ts

@@ -0,0 +1,14 @@
+import { type DocsEntryRecord } from "../docsContract.js";
+import type { DocsFetchOptions } from "./types.js";
+/**
+ * Loads the normalized docs corpus from cedros-data and applies product/section filters.
+ *
+ * Returns docs in package ordering, excluding drafts unless `includeDrafts` is true.
+ */
+export declare function fetchDocsIndex(options?: DocsFetchOptions): Promise<DocsEntryRecord[]>;
+/**
+ * Resolves a single docs article by canonical slug, current route, or any declared alias.
+ *
+ * Returns `null` when the requested doc does not exist after normalization.
+ */
+export declare function fetchDocsEntry(slugOrPath: string, options?: DocsFetchOptions): Promise<DocsEntryRecord | null>;

package/dist/react/docs.js

@@ -0,0 +1,207 @@
+import { fetchDocEntry as findDocEntry } from "../site-templates/docsNavigation.js";
+import { matchesDocsEntryFilter, normalizeDocsHref, normalizeDocsSlug, sortDocsEntries, } from "../docsContract.js";
+import { resolveApiKey, resolveServerUrl } from "./fetch.js";
+import { fetchJson } from "./fetch.js";
+const DEFAULT_DOCS_COLLECTION = "docs";
+const DOCS_BATCH_SIZE = 1_000;
+/**
+ * Loads the normalized docs corpus from cedros-data and applies product/section filters.
+ *
+ * Returns docs in package ordering, excluding drafts unless `includeDrafts` is true.
+ */
+export async function fetchDocsIndex(options = {}) {
+    const serverUrl = resolveServerUrl(options);
+    const apiKey = resolveApiKey(options);
+    const collectionName = options.collectionName ?? DEFAULT_DOCS_COLLECTION;
+    const records = await fetchAllDocsRecords(serverUrl, collectionName, apiKey);
+    const docs = sortDocsEntries(records
+        .map((record) => normalizeDocsEntry(record, options))
+        .filter((entry) => matchesDocsEntryFilter(entry, options)));
+    const offset = Math.max(0, Math.floor(options.offset ?? 0));
+    const end = options.limit === undefined
+        ? undefined
+        : offset + Math.max(0, Math.floor(options.limit));
+    return docs.slice(offset, end);
+}
+/**
+ * Resolves a single docs article by canonical slug, current route, or any declared alias.
+ *
+ * Returns `null` when the requested doc does not exist after normalization.
+ */
+export async function fetchDocsEntry(slugOrPath, options = {}) {
+    const docs = await fetchDocsIndex({
+        ...options,
+        limit: undefined,
+        offset: undefined,
+    });
+    return findDocEntry(docs, slugOrPath, options) ?? null;
+}
+async function fetchAllDocsRecords(serverUrl, collectionName, apiKey) {
+    const records = [];
+    let offset = 0;
+    for (;;) {
+        const batch = await fetchJson(serverUrl, "/entries/query", {
+            method: "POST",
+            body: {
+                collection_name: collectionName,
+                limit: DOCS_BATCH_SIZE,
+                offset,
+            },
+            apiKey,
+        });
+        records.push(...batch);
+        if (batch.length < DOCS_BATCH_SIZE) {
+            return records;
+        }
+        offset += batch.length;
+    }
+}
+function normalizeDocsEntry(record, options) {
+    const payload = record.payload;
+    const bodyMarkdown = readStringAny(payload, [
+        "bodyMarkdown",
+        "body_markdown",
+        "markdown",
+        "body",
+    ]);
+    const slug = normalizeDocsSlug(readStringAny(payload, ["slug", "routeSlug", "path", "route"]) ??
+        record.entry_key, options) || "index";
+    return {
+        slug,
+        title: readStringAny(payload, ["title", "navTitle"]) ?? humanizeDocsSlug(slug),
+        description: readStringAny(payload, ["description"]) ??
+            inferDescription(bodyMarkdown),
+        category: readStringAny(payload, ["category"]),
+        tags: readStringArray(payload, "tags"),
+        lastUpdated: readStringAny(payload, [
+            "lastUpdated",
+            "updatedAt",
+            "updated_at",
+            "publishedAt",
+        ]) ?? record.updated_at,
+        bodyMarkdown,
+        bodyHtml: readStringAny(payload, ["bodyHtml", "body_html"]),
+        bodyText: readStringAny(payload, ["bodyText", "body_text"]),
+        searchText: readStringAny(payload, ["searchText", "search_text"]),
+        status: readStringAny(payload, ["status"]),
+        productSlug: normalizeDocsSlug(readStringAny(payload, ["productSlug", "productKey", "product"]) ?? "", options) || undefined,
+        productLabel: readStringAny(payload, ["productLabel", "productTitle"]),
+        productOrder: readNumberAny(payload, ["productOrder"]),
+        sectionKey: normalizeSectionKey(readStringAny(payload, ["sectionKey", "section", "sidebarSection"])),
+        sectionLabel: readStringAny(payload, [
+            "sectionLabel",
+            "sectionTitle",
+            "section",
+            "sidebarSection",
+            "category",
+        ]),
+        sectionOrder: readNumberAny(payload, ["sectionOrder"]),
+        order: readNumberAny(payload, ["order", "navOrder"]),
+        readingMinutes: readNumberAny(payload, ["readingMinutes"]),
+        toc: readToc(payload),
+        breadcrumbs: readBreadcrumbs(payload, options),
+        editHref: readStringAny(payload, ["editHref", "editUrl", "sourceUrl"]),
+        sourcePath: readStringAny(payload, ["sourcePath"]),
+        sourceHref: readStringAny(payload, ["sourceHref", "sourceUrl"]),
+        navLabel: readStringAny(payload, ["navLabel", "navTitle"]),
+        navOrder: readNumberAny(payload, ["navOrder", "order"]),
+        aliases: readStringArray(payload, "aliases")
+            .map((value) => normalizeDocsSlug(value, options))
+            .filter(Boolean),
+        badge: readStringAny(payload, ["badge"]),
+    };
+}
+function readBreadcrumbs(payload, options) {
+    const raw = payload.breadcrumbs;
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const breadcrumbs = raw
+        .map((value) => asObject(value))
+        .filter((entry) => entry !== undefined)
+        .map((entry) => {
+        const label = readStringAny(entry, ["label", "title"]);
+        const href = readStringAny(entry, ["href", "url", "path"]);
+        if (!label || !href) {
+            return undefined;
+        }
+        return {
+            label,
+            href: normalizeDocsHref(href, options),
+        };
+    })
+        .filter((entry) => entry !== undefined);
+    return breadcrumbs.length > 0 ? breadcrumbs : undefined;
+}
+function readToc(payload) {
+    const raw = payload.toc;
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const headings = raw
+        .map((value) => asObject(value))
+        .filter((entry) => entry !== undefined)
+        .map((entry) => {
+        const id = readString(entry, "id");
+        const label = readString(entry, "label");
+        if (!id || !label) {
+            return undefined;
+        }
+        const depth = readNumber(entry, "depth");
+        const heading = {
+            id,
+            label,
+            depth: depth === 2 || depth === 3 || depth === 4
+                ? depth
+                : undefined,
+        };
+        return heading;
+    })
+        .filter((entry) => entry !== undefined);
+    return headings.length > 0 ? headings : undefined;
+}
+function inferDescription(markdown) {
+    const paragraph = markdown
+        ?.split(/\n{2,}/u)
+        .map((segment) => segment.replace(/^#+\s+/gmu, "").trim())
+        .find((segment) => segment && !segment.startsWith("```"));
+    return paragraph || undefined;
+}
+function humanizeDocsSlug(slug) {
+    const leaf = slug.split("/").pop() ?? slug;
+    return leaf.replace(/[-_]+/gu, " ").replace(/\b\w/gu, (char) => char.toUpperCase());
+}
+function normalizeSectionKey(value) {
+    return value
+        ?.trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/^-+|-+$/gu, "") || undefined;
+}
+function asObject(value) {
+    return value !== null && typeof value === "object" ? value : undefined;
+}
+function readString(payload, key) {
+    const value = payload[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function readStringAny(payload, keys) {
+    return keys.map((key) => readString(payload, key)).find(Boolean);
+}
+function readNumber(payload, key) {
+    const value = payload[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function readNumberAny(payload, keys) {
+    return keys.map((key) => readNumber(payload, key)).find((value) => value !== undefined);
+}
+function readStringArray(payload, key) {
+    const value = payload[key];
+    if (typeof value === "string" && value.trim()) {
+        return [value.trim()];
+    }
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+}

package/dist/react/index.d.ts

@@ -9,4 +9,5 @@ export type { ThemeMode, CedrosDataThemeOverrides, CedrosDataThemeValue, } from
 export { CmsContent, type CmsContentProps } from "./CmsContent.js";
 export { getOrCreateVisitorId } from "./visitor.js";
 export { sanitizeCmsHtml, renderCmsMarkdown } from "./sanitize.js";
-export type { CmsPageRecord, PageMetadataInput, SiteDataRecord, SanitizeOptions, ContentType, MeteredReadsInfo, } from "./types.js";
+export { normalizeDocsHref, normalizeDocsSlug } from "../docsContract.js";
+export type { CmsPageRecord, PageMetadataInput, SiteDataRecord, SanitizeOptions, ContentType, DocsBreadcrumb, DocsEntryRecord, DocsFetchOptions, DocsNormalizationOptions, DocsTocHeading, MeteredReadsInfo, } from "./types.js";

package/dist/react/index.js

@@ -8,3 +8,4 @@ export { CedrosDataProvider, useCedrosDataTheme, useCedrosDataThemeOptional, } f
 export { CmsContent } from "./CmsContent.js";
 export { getOrCreateVisitorId } from "./visitor.js";
 export { sanitizeCmsHtml, renderCmsMarkdown } from "./sanitize.js";
+export { normalizeDocsHref, normalizeDocsSlug } from "../docsContract.js";

package/dist/react/server.d.ts

@@ -8,7 +8,8 @@
  * Do not import this module in client components.
  */
 export { buildPageMetadata, generatePageMetadata, type PageMetadata, } from "./metadata.js";
+export { fetchDocsEntry, fetchDocsIndex } from "./docs.js";
 export { loadSitemapEntries } from "./sitemap.js";
 export { fetchBlogPost } from "./entries.js";
 export { listBlogSlugs, listContentSlugs, listLearnPathIds, } from "./slugs.js";
-export type { BuildPageMetadataOptions, CmsPageRecord, MeteredReadsInfo, PageMetadataInput, SiteDataRecord, SitemapEntry, ServerFetchOptions, ContentType, } from "./types.js";
+export type { BuildPageMetadataOptions, CmsPageRecord, MeteredReadsInfo, PageMetadataInput, SiteDataRecord, SitemapEntry, ServerFetchOptions, DocsBreadcrumb, DocsEntryRecord, DocsFetchOptions, DocsNormalizationOptions, DocsTocHeading, ContentType, } from "./types.js";

package/dist/react/server.js

@@ -8,6 +8,7 @@
  * Do not import this module in client components.
  */
 export { buildPageMetadata, generatePageMetadata, } from "./metadata.js";
+export { fetchDocsEntry, fetchDocsIndex } from "./docs.js";
 export { loadSitemapEntries } from "./sitemap.js";
 export { fetchBlogPost } from "./entries.js";
 export { listBlogSlugs, listContentSlugs, listLearnPathIds, } from "./slugs.js";

package/dist/react/types.d.ts

@@ -1,3 +1,4 @@
+import type { DocsBreadcrumb, DocsEntryRecord, DocsNormalizationOptions, DocsTocHeading } from "../docsContract.js";
 /** Content type identifiers used across cedros-data. */
 export type ContentType = "page" | "blog" | "docs" | "learn" | "project" | "airdrop";
 /**
@@ -97,3 +98,19 @@ export interface ServerFetchOptions {
     /** Visitor ID for metered-reads tracking. Use `getOrCreateVisitorId()` on the client. */
     visitorId?: string;
 }
+/** Options for loading docs entries from the cedros-data backend. */
+export interface DocsFetchOptions extends ServerFetchOptions, DocsNormalizationOptions {
+    /** Override the backend collection. Defaults to "docs". */
+    collectionName?: string;
+    /** Restrict results to a single product slug. */
+    productSlug?: string;
+    /** Restrict results to a single section key. */
+    sectionKey?: string;
+    /** Include draft docs. Defaults to false. */
+    includeDrafts?: boolean;
+    /** Final limit applied after docs are normalized and filtered. */
+    limit?: number;
+    /** Final offset applied after docs are normalized and filtered. */
+    offset?: number;
+}
+export type { DocsBreadcrumb, DocsEntryRecord, DocsNormalizationOptions, DocsTocHeading, };

package/dist/site-templates/BlogTemplates.js

@@ -6,10 +6,12 @@ import { MarkdownContent } from "./MarkdownContent.js";
 import { BlogSearchInput, BookmarkButton, FilterDimensionChips } from "./blogControls.js";
 import { TipWidget } from "./tipControls.js";
 import { ContentPaywall } from "./paywallControls.js";
+import { BlogIndexControls } from "./blogTemplateUi.js";
 export function BlogIndexTemplate({ siteTitle, navigation, posts, title = "Blog", description = "", basePath = "/blog", query = "", category = "", tag = "", sort = "newest", page = 1, pageSize = 8, categories, tags, filterDimensions, activeFilters, onFilterChange, onSearch, bookmarkedSlugs, onBookmarkToggle }) {
     const normalizedFilters = collectFilterValues(posts);
     const resolvedCategories = categories ?? normalizedFilters.categories;
     const resolvedTags = tags ?? normalizedFilters.tags;
+    const totalPosts = posts.length;
     const result = prepareBlogIndex(posts, {
         query,
         category,
@@ -20,22 +22,24 @@ export function BlogIndexTemplate({ siteTitle, navigation, posts, title = "Blog"
         dimensions: activeFilters
     });
     const useClientControls = !!(filterDimensions || onSearch);
-    return (_jsxs(SiteLayout, { siteTitle: siteTitle, navigation: navigation, children: [_jsxs("section", { className: "cedros-site__card", children: [_jsx("h1", { className: "cedros-site__title", children: title }), description && _jsx("p", { className: "cedros-site__subtitle", children: description })] }), useClientControls ? (_jsxs("section", { className: "cedros-site__card", style: { display: "grid", gap: "0.7rem" }, children: [onSearch && _jsx(BlogSearchInput, { defaultValue: query, onSearch: onSearch }), filterDimensions && onFilterChange && (_jsx(FilterDimensionChips, { dimensions: filterDimensions, active: activeFilters ?? {}, onChange: onFilterChange }))] })) : (_jsx(BlogIndexControls, { 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 posts found" }), _jsx("p", { className: "cedros-site__subtitle", style: { marginTop: "0.6rem" }, children: "Adjust filters or search terms to find matching articles." })] })), result.totalItems > 0 && (_jsxs(_Fragment, { children: [_jsx("section", { className: "cedros-site__content-grid", children: result.items.map((post) => (_jsxs("article", { className: "cedros-site__card cedros-site__entry-card", children: [_jsxs("div", { className: "cedros-site__entry-header", children: [_jsx("h2", { className: "cedros-site__entry-title", children: _jsx("a", { href: `${basePath}/${post.slug}`, children: post.title }) }), bookmarkedSlugs && onBookmarkToggle ? (_jsxs("div", { style: { display: "inline-flex", gap: "0.35rem", alignItems: "center" }, children: [post.publishedAt && _jsx("span", { className: "cedros-site__pill", children: post.publishedAt }), _jsx(BookmarkButton, { slug: post.slug, isBookmarked: bookmarkedSlugs.has(post.slug), onToggle: onBookmarkToggle })] })) : (post.publishedAt && _jsx("span", { className: "cedros-site__pill", children: post.publishedAt }))] }), (post.author || post.readingMinutes) && (_jsx("p", { className: "cedros-site__entry-meta", children: [post.author, readingTime(post.readingMinutes)].filter(Boolean).join(" • ") })), post.excerpt && _jsx("p", { className: "cedros-site__subtitle", children: post.excerpt }), post.tags && post.tags.length > 0 && (_jsx("div", { className: "cedros-site__tag-list", children: post.tags.map((entryTag) => (_jsx("a", { href: buildContentListHref(basePath, { q: query, category, tag: entryTag, sort }), className: "cedros-site__pill", children: entryTag }, entryTag))) }))] }, post.slug))) }), _jsx(ContentPagination, { basePath: basePath, page: result.page, totalPages: result.totalPages, query: { q: query, category, tag, sort } })] }))] }));
+    return (_jsx(SiteLayout, { siteTitle: siteTitle, navigation: navigation, children: _jsxs("section", { className: "cedros-site__blog-page", children: [_jsxs("section", { className: "cedros-site__card cedros-site__blog-hero", children: [_jsxs("div", { className: "cedros-site__blog-hero-copy", children: [_jsx("span", { className: "cedros-site__pill cedros-site__pill--strong", children: "Journal" }), _jsx("h1", { className: "cedros-site__title cedros-site__blog-hero-title", children: title }), description && _jsx("p", { className: "cedros-site__subtitle cedros-site__blog-hero-subtitle", children: description })] }), _jsxs("dl", { className: "cedros-site__hero-stats", children: [_jsxs("div", { className: "cedros-site__hero-stat", children: [_jsx("dt", { children: "Posts" }), _jsx("dd", { children: totalPosts })] }), _jsxs("div", { className: "cedros-site__hero-stat", children: [_jsx("dt", { children: "Categories" }), _jsx("dd", { children: resolvedCategories.length })] }), _jsxs("div", { className: "cedros-site__hero-stat", children: [_jsx("dt", { children: "Topics" }), _jsx("dd", { children: resolvedTags.length })] })] })] }), useClientControls ? (_jsxs("section", { className: "cedros-site__card cedros-site__blog-controls-panel", children: [_jsxs("div", { className: "cedros-site__controls-header", children: [_jsxs("div", { children: [_jsx("p", { className: "cedros-site__eyebrow", children: "Discover" }), _jsx("h2", { className: "cedros-site__section-title", children: "Search and explore the latest posts" })] }), _jsx("p", { className: "cedros-site__entry-meta", children: "Use search and topic chips to narrow down the editorial feed." })] }), onSearch && _jsx(BlogSearchInput, { defaultValue: query, onSearch: onSearch }), filterDimensions && onFilterChange && (_jsx(FilterDimensionChips, { dimensions: filterDimensions, active: activeFilters ?? {}, onChange: onFilterChange }))] })) : (_jsx(BlogIndexControls, { 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("p", { className: "cedros-site__eyebrow", children: "No matches" }), _jsx("h2", { className: "cedros-site__section-title", children: "No posts found" }), _jsx("p", { className: "cedros-site__subtitle", children: "Adjust filters or search terms to find matching articles." })] })), result.totalItems > 0 && (_jsxs(_Fragment, { children: [_jsxs("div", { className: "cedros-site__section-heading", children: [_jsxs("div", { children: [_jsx("p", { className: "cedros-site__eyebrow", children: "Latest posts" }), _jsx("h2", { className: "cedros-site__section-title", children: "News, analysis, and product updates" })] }), _jsxs("p", { className: "cedros-site__entry-meta", children: [result.totalItems, " matching posts"] })] }), _jsx("section", { className: "cedros-site__content-grid cedros-site__content-grid--blog", children: result.items.map((post) => {
+                                const cardMetadata = [post.publishedAt, post.author, readingTime(post.readingMinutes)]
+                                    .filter(Boolean)
+                                    .join(" • ");
+                                return (_jsxs("article", { className: "cedros-site__card cedros-site__entry-card cedros-site__blog-card", children: [_jsxs("div", { className: "cedros-site__blog-card-top", children: [_jsx("div", { className: "cedros-site__blog-card-taxonomy", children: post.category && (_jsx("a", { href: buildContentListHref(basePath, { q: query, category: post.category, tag, sort }), className: "cedros-site__pill", children: post.category })) }), bookmarkedSlugs && onBookmarkToggle && (_jsx(BookmarkButton, { slug: post.slug, isBookmarked: bookmarkedSlugs.has(post.slug), onToggle: onBookmarkToggle }))] }), _jsx("h2", { className: "cedros-site__entry-title cedros-site__entry-title--blog", children: _jsx("a", { href: `${basePath}/${post.slug}`, children: post.title }) }), post.excerpt && _jsx("p", { className: "cedros-site__subtitle", children: post.excerpt }), post.tags && post.tags.length > 0 && (_jsx("div", { className: "cedros-site__tag-list", children: post.tags.map((entryTag) => (_jsx("a", { href: buildContentListHref(basePath, { q: query, category, tag: entryTag, sort }), className: "cedros-site__pill", children: entryTag }, entryTag))) })), _jsxs("div", { className: "cedros-site__blog-card-footer", children: [cardMetadata && _jsx("p", { className: "cedros-site__entry-meta", children: cardMetadata }), _jsx("a", { href: `${basePath}/${post.slug}`, className: "cedros-site__button cedros-site__button--ghost", children: "Read post" })] })] }, post.slug));
+                            }) }), _jsx(ContentPagination, { basePath: basePath, page: result.page, totalPages: result.totalPages, query: { q: query, category, tag, sort } })] }))] }) }));
 }
 export function BlogPostTemplate({ siteTitle, navigation, title, bodyMarkdown, bodyHtml, allowUnsafeHtmlFallback = false, publishedAt, updatedAt, author, category, tags = [], readingMinutes, canonicalUrl, breadcrumbs = [], relatedPosts = [], basePath = "/blog", isBookmarked, onBookmarkToggle, slug, tipping, paywall }) {
     const metadata = [publishedAt, updatedAt ? `Updated ${updatedAt}` : "", author, readingTime(readingMinutes)].filter(Boolean);
     const showBookmark = isBookmarked !== undefined && onBookmarkToggle && slug;
-    return (_jsxs(SiteLayout, { siteTitle: siteTitle, navigation: navigation, children: [_jsx(Breadcrumbs, { trail: breadcrumbs }), _jsxs("article", { className: "cedros-site__card cedros-site__article", children: [_jsxs("div", { className: "cedros-site__article-header", children: [showBookmark ? (_jsxs("div", { style: { display: "inline-flex", gap: "0.35rem", alignItems: "center" }, children: [_jsx("span", { className: "cedros-site__pill", children: "blog" }), _jsx(BookmarkButton, { slug: slug, isBookmarked: isBookmarked, onToggle: onBookmarkToggle })] })) : (_jsx("span", { className: "cedros-site__pill", children: "blog" })), _jsx("h1", { className: "cedros-site__title", children: title }), metadata.length > 0 && _jsx("p", { className: "cedros-site__entry-meta", children: metadata.join(" • ") }), (category || tags.length > 0) && (_jsxs("div", { className: "cedros-site__tag-list", children: [category && (_jsx("a", { href: buildContentListHref(basePath, { category }), className: "cedros-site__pill", children: category })), tags.map((tag) => (_jsx("a", { href: buildContentListHref(basePath, { tag }), className: "cedros-site__pill", children: tag }, tag)))] })), canonicalUrl && (_jsx("a", { href: canonicalUrl, className: "cedros-site__subtitle", style: { marginTop: "0.5rem" }, children: "Canonical URL" }))] }), renderPaywallOrContent({
-                        paywall,
-                        bodyMarkdown,
-                        bodyHtml,
-                        allowUnsafeHtmlFallback
-                    })] }), tipping?.enabled && (_jsx("section", { className: "cedros-site__card", children: _jsx(TipWidget, { dataServerUrl: tipping.dataServerUrl, recipient: tipping.allowPerPostRecipient && tipping.recipientOverride
-                        ? tipping.recipientOverride
-                        : tipping.recipient, currencies: tipping.currencies, presets: tipping.presets, label: tipping.label, description: tipping.description, senderAddress: tipping.senderAddress, signTransaction: tipping.signTransaction }) })), relatedPosts.length > 0 && (_jsxs("section", { className: "cedros-site__card", children: [_jsx("h2", { style: { margin: 0, fontSize: "1.02rem" }, children: "Related posts" }), _jsx("div", { className: "cedros-site__content-grid", style: { marginTop: "0.75rem" }, children: relatedPosts.map((post) => (_jsxs("article", { className: "cedros-site__entry-card", children: [_jsx("h3", { className: "cedros-site__entry-title", style: { marginTop: 0 }, children: _jsx("a", { href: `${basePath}/${post.slug}`, children: post.title }) }), post.excerpt && _jsx("p", { className: "cedros-site__subtitle", children: post.excerpt })] }, post.slug))) })] }))] }));
-}
-function BlogIndexControls({ 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 blog posts" })] }), _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: "newest", children: "Newest" }), _jsx("option", { value: "oldest", children: "Oldest" }), _jsx("option", { value: "title-asc", children: "Title A-Z" }), _jsx("option", { value: "title-desc", children: "Title Z-A" })] })] }), _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" })] })] }));
+    return (_jsx(SiteLayout, { siteTitle: siteTitle, navigation: navigation, children: _jsxs("section", { className: "cedros-site__blog-page cedros-site__blog-page--article", children: [_jsxs("article", { className: "cedros-site__card cedros-site__article cedros-site__blog-article", children: [_jsxs("div", { className: "cedros-site__article-top", children: [_jsx(Breadcrumbs, { trail: breadcrumbs }), _jsxs("div", { className: "cedros-site__blog-article-actions", children: [canonicalUrl && (_jsx("a", { href: canonicalUrl, className: "cedros-site__button cedros-site__button--ghost", children: "Canonical URL" })), showBookmark && (_jsx(BookmarkButton, { slug: slug, isBookmarked: isBookmarked, onToggle: onBookmarkToggle }))] })] }), _jsxs("div", { className: "cedros-site__article-header", children: [_jsx("span", { className: "cedros-site__pill cedros-site__pill--strong", children: "Blog" }), _jsx("h1", { className: "cedros-site__title", children: title }), metadata.length > 0 && (_jsx("div", { className: "cedros-site__article-meta-list", children: metadata.map((entry) => (_jsx("span", { className: "cedros-site__meta-chip", children: entry }, entry))) })), (category || tags.length > 0) && (_jsxs("div", { className: "cedros-site__blog-taxonomy", children: [category && (_jsx("a", { href: buildContentListHref(basePath, { category }), className: "cedros-site__pill", children: category })), tags.map((tag) => (_jsx("a", { href: buildContentListHref(basePath, { tag }), className: "cedros-site__pill", children: tag }, tag)))] }))] }), _jsx("div", { className: "cedros-site__article-body", children: renderPaywallOrContent({
+                                paywall,
+                                bodyMarkdown,
+                                bodyHtml,
+                                allowUnsafeHtmlFallback
+                            }) })] }), tipping?.enabled && (_jsxs("section", { className: "cedros-site__card cedros-site__blog-support-card", children: [_jsxs("div", { className: "cedros-site__blog-support-header", children: [_jsx("p", { className: "cedros-site__eyebrow", children: "Support" }), _jsx("h2", { className: "cedros-site__section-title", children: "Tip the author or support the publication" })] }), _jsx(TipWidget, { dataServerUrl: tipping.dataServerUrl, recipient: tipping.allowPerPostRecipient && tipping.recipientOverride
+                                ? tipping.recipientOverride
+                                : tipping.recipient, currencies: tipping.currencies, presets: tipping.presets, label: tipping.label, description: tipping.description, senderAddress: tipping.senderAddress, signTransaction: tipping.signTransaction })] })), relatedPosts.length > 0 && (_jsxs("section", { className: "cedros-site__card cedros-site__blog-related", children: [_jsxs("div", { className: "cedros-site__blog-related-header", children: [_jsx("p", { className: "cedros-site__eyebrow", children: "Continue reading" }), _jsx("h2", { className: "cedros-site__section-title", children: "Related posts" })] }), _jsx("div", { className: "cedros-site__blog-related-grid", children: relatedPosts.map((post) => (_jsxs("article", { className: "cedros-site__card cedros-site__blog-related-card", children: [_jsx("h3", { className: "cedros-site__entry-title cedros-site__entry-title--blog", children: _jsx("a", { href: `${basePath}/${post.slug}`, children: post.title }) }), post.excerpt && _jsx("p", { className: "cedros-site__subtitle", children: post.excerpt }), _jsx("div", { className: "cedros-site__blog-card-footer", children: _jsx("a", { href: `${basePath}/${post.slug}`, className: "cedros-site__button cedros-site__button--ghost", children: "Read post" }) })] }, post.slug))) })] }))] }) }));
 }
 function readingTime(minutes) {
     if (!minutes) {

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

@@ -11,4 +11,4 @@ export interface DocsSidebarProps {
  * Desktop: always visible, sticky.
  * Mobile: hidden behind a hamburger button; overlay closes on link click.
  */
-export declare function DocsSidebar({ title, basePath, searchQuery, sections, }: DocsSidebarProps): React.JSX.Element;
+export declare function DocsSidebar({ title, basePath, searchQuery, sections }: DocsSidebarProps): React.JSX.Element;

package/dist/site-templates/DocsSidebar.js

@@ -7,7 +7,7 @@ import { useState } from "react";
  * Desktop: always visible, sticky.
  * Mobile: hidden behind a hamburger button; overlay closes on link click.
  */
-export function DocsSidebar({ title, basePath, searchQuery, sections, }) {
+export function DocsSidebar({ title, basePath, searchQuery, sections }) {
     const [open, setOpen] = useState(false);
-    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "cedros-site__sidebar-toggle", "aria-label": "Toggle sidebar", "aria-expanded": open, onClick: () => setOpen((prev) => !prev), children: title }), open && (_jsx("div", { className: "cedros-site__sidebar-overlay", onClick: () => setOpen(false), role: "presentation" })), _jsxs("aside", { className: `cedros-site__card cedros-site__docs-sidebar${open ? " cedros-site__docs-sidebar--open" : ""}`, children: [_jsx("h2", { className: "cedros-site__docs-sidebar-title", children: title }), _jsx("form", { method: "get", action: basePath, className: "cedros-site__docs-search", children: _jsxs("label", { className: "cedros-site__control", children: [_jsx("span", { children: "Search docs" }), _jsx("input", { type: "search", name: "q", defaultValue: searchQuery, placeholder: "Search docs..." })] }) }), _jsx("a", { href: basePath, className: "cedros-site__docs-root-link", children: "Browse all docs" }), sections.length === 0 && (_jsx("p", { className: "cedros-site__entry-meta", children: "No sections available yet." })), sections.map((section) => (_jsxs("details", { className: "cedros-site__docs-section", open: section.collapsed !== true, children: [_jsx("summary", { className: "cedros-site__docs-section-title", children: section.label }), _jsx("nav", { className: "cedros-site__docs-section-links", "aria-label": section.label, children: section.items.map((item) => (_jsxs("a", { href: item.href, className: `cedros-site__docs-item cedros-site__docs-item--depth-${item.depth ?? 0}${item.isActive ? " cedros-site__docs-item--active" : ""}`, "aria-current": item.isActive ? "page" : undefined, onClick: () => setOpen(false), children: [_jsx("span", { children: item.label }), item.badge && (_jsx("span", { className: "cedros-site__docs-item-badge", children: item.badge }))] }, item.key))) })] }, section.key)))] })] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("button", { type: "button", className: "cedros-site__sidebar-toggle", "aria-label": "Toggle sidebar", "aria-expanded": open, onClick: () => setOpen((prev) => !prev), children: [_jsxs("span", { className: "cedros-site__sidebar-toggle-copy", children: [_jsx("span", { className: "cedros-site__sidebar-toggle-label", children: title }), _jsxs("span", { className: "cedros-site__sidebar-toggle-meta", children: [sections.length, " sections"] })] }), _jsx("span", { className: "cedros-site__sidebar-toggle-state", children: open ? "Close" : "Open" })] }), open && (_jsx("div", { className: "cedros-site__sidebar-overlay", onClick: () => setOpen(false), role: "presentation" })), _jsxs("aside", { className: `cedros-site__card cedros-site__docs-sidebar${open ? " cedros-site__docs-sidebar--open" : ""}`, children: [_jsxs("div", { className: "cedros-site__docs-sidebar-top", children: [_jsxs("div", { children: [_jsx("p", { className: "cedros-site__eyebrow", children: "Navigation" }), _jsx("h2", { className: "cedros-site__docs-sidebar-title", children: title })] }), _jsx("button", { type: "button", className: "cedros-site__docs-sidebar-close", "aria-label": "Close sidebar", onClick: () => setOpen(false), children: "Close" })] }), _jsx("p", { className: "cedros-site__docs-sidebar-meta", children: "Browse sections, search directly, or return to the full index." }), _jsx("form", { method: "get", action: basePath, className: "cedros-site__docs-search", children: _jsxs("label", { className: "cedros-site__control", children: [_jsx("span", { children: "Search docs" }), _jsx("input", { type: "search", name: "q", defaultValue: searchQuery, placeholder: "Search docs..." })] }) }), _jsx("a", { href: basePath, className: "cedros-site__docs-root-link", children: "Browse all documentation" }), sections.length === 0 && (_jsx("p", { className: "cedros-site__entry-meta", children: "No sections available yet." })), sections.map((section) => (_jsxs("details", { className: "cedros-site__docs-section", open: section.collapsed !== true, children: [_jsx("summary", { className: "cedros-site__docs-section-title", children: section.label }), _jsx("nav", { className: "cedros-site__docs-section-links", "aria-label": section.label, children: section.items.map((item) => (_jsxs("a", { href: item.href, className: `cedros-site__docs-item cedros-site__docs-item--depth-${item.depth ?? 0}${item.isActive ? " cedros-site__docs-item--active" : ""}`, "aria-current": item.isActive ? "page" : undefined, onClick: () => setOpen(false), children: [_jsx("span", { children: item.label }), item.badge && (_jsx("span", { className: "cedros-site__docs-item-badge", children: item.badge }))] }, item.key))) })] }, section.key)))] })] }));
 }