@cogenta/theme-docs 0.3.3 → 0.5.3

package/dist/src/render/doc-index.js

@@ -0,0 +1,49 @@
+/**
+ * The documentation's own order, shared by the sidebar, the home page index
+ * and previous/next.
+ *
+ * A doc page carries two plain fields: `section` (the group it belongs to)
+ * and `order` (its place in that group). Neither is a sort field contract B
+ * allows a `collectionList` to ask for (`id`/`createdAt`/`updatedAt` only),
+ * so the list is fetched by creation date and ordered here: pages within a
+ * section by `order`, then by the order they were fetched in; sections by the
+ * smallest `order` they hold, then by the order they first appear. Two pages
+ * created in the same millisecond can come back in either order, so the
+ * documentation never depends on creation time alone.
+ */
+export const DOC_PAGE_COLLECTION = 'doc_page';
+export function isDocIndexBlock(block) {
+    return block._type === 'collectionList' && block.collection === DOC_PAGE_COLLECTION;
+}
+export function groupDocPages(entries, ctx) {
+    const groups = new Map();
+    entries.forEach((entry, position) => {
+        const section = typeof entry.section === 'string' && entry.section.trim() !== ''
+            ? entry.section.trim()
+            : ctx.t('entry.untitled');
+        const list = groups.get(section) ?? [];
+        list.push({ entry, position });
+        groups.set(section, list);
+    });
+    const orderOf = (entry) => typeof entry.order === 'number' ? entry.order : Number.POSITIVE_INFINITY;
+    return [...groups.entries()]
+        .map(([section, list], appearance) => ({
+        section,
+        appearance,
+        first: Math.min(...list.map((item) => orderOf(item.entry))),
+        entries: [...list]
+            .sort((a, b) => {
+            const orderA = orderOf(a.entry);
+            const orderB = orderOf(b.entry);
+            return orderA === orderB ? a.position - b.position : orderA - orderB;
+        })
+            .map((item) => item.entry),
+    }))
+        .sort((a, b) => (a.first === b.first ? a.appearance - b.appearance : a.first - b.first))
+        .map(({ section, entries }) => ({ section, entries }));
+}
+/** The reading order of the whole documentation: every group, in turn. */
+export function readingOrder(groups) {
+    return groups.flatMap((group) => group.entries);
+}
+//# sourceMappingURL=doc-index.js.map

package/dist/src/render/doc-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-index.js","sourceRoot":"","sources":["../../../src/render/doc-index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAA;AAO7C,MAAM,UAAU,eAAe,CAAC,KAAsB;IACpD,OAAO,KAAK,CAAC,KAAK,KAAK,gBAAgB,IAAI,KAAK,CAAC,UAAU,KAAK,mBAAmB,CAAA;AACrF,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,OAAgC,EAChC,GAAkB;IAElB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAuD,CAAA;IAC7E,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;QAClC,MAAM,OAAO,GACX,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;YAC9D,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;YACtB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAA;QAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;QACtC,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC9B,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAC3B,CAAC,CAAC,CAAA;IACF,MAAM,OAAO,GAAG,CAAC,KAAmB,EAAU,EAAE,CAC9C,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAA;IAC1E,OAAO,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;SACzB,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC;QACrC,OAAO;QACP,UAAU;QACV,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3D,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;aACf,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACb,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;YAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;YAC/B,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,GAAG,MAAM,CAAA;QACtE,CAAC,CAAC;aACD,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC;KAC7B,CAAC,CAAC;SACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;SACvF,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,YAAY,CAAC,MAA2B;IACtD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;AACjD,CAAC"}

package/dist/src/render/doc-page.d.ts

@@ -0,0 +1,6 @@
+import type { BlockRegistry, CollectionListBlock, VocabularyBlock } from '@cogenta/blocks';
+import { type FetchedEntries, type HtmlElement, type PageContent, type RenderContext } from '@cogenta/theme-kit';
+import { type HeadingAnchors } from './rich-text.js';
+export type BlockRenderer = (block: VocabularyBlock, ctx: RenderContext, entries: FetchedEntries, registry: BlockRegistry | undefined, anchors: HeadingAnchors) => HtmlElement | null;
+export declare function renderDocPage(page: PageContent, ctx: RenderContext, sidebarBlock: CollectionListBlock, entries: FetchedEntries, registry: BlockRegistry | undefined, renderOne: BlockRenderer): HtmlElement;
+//# sourceMappingURL=doc-page.d.ts.map

package/dist/src/render/doc-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-page.d.ts","sourceRoot":"","sources":["../../../src/render/doc-page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC1F,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EAEhB,KAAK,aAAa,EAEnB,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAAsB,KAAK,cAAc,EAAkB,MAAM,gBAAgB,CAAA;AA6NxF,MAAM,MAAM,aAAa,GAAG,CAC1B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,OAAO,EAAE,cAAc,KACpB,WAAW,GAAG,IAAI,CAAA;AAEvB,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,aAAa,EAClB,YAAY,EAAE,mBAAmB,EACjC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,SAAS,EAAE,aAAa,GACvB,WAAW,CAmDb"}

package/dist/src/render/doc-page.js

@@ -0,0 +1,127 @@
+import { entryHref, entryTitle, h, pageHasOwnHeading, withBlockKey, } from '@cogenta/theme-kit';
+import { groupDocPages, readingOrder } from './doc-index.js';
+import { longDate } from './layout.js';
+import { headingAnchors } from './rich-text.js';
+import { word } from './strings.js';
+/**
+ * A documentation page: navigation, the reading column, the table of
+ * contents.
+ *
+ * The navigation comes from the page's own first block, a `collectionList` on
+ * `doc_page` that the documentation blueprint seeds on every page for this
+ * purpose (contract B has no "this block is chrome" flag, and inventing one
+ * would be a contract change for one theme's layout). It is rendered as the
+ * sidebar and dropped from the stream of content blocks.
+ *
+ * Three columns on a wide screen: the sidebar held in view as the page
+ * scrolls, the article on its measure, and "On this page" built from the
+ * article's own `h2`/`h3`. The table of contents has no scroll spy (that
+ * would need a script); it is a plain list of links that stays in view. Two
+ * columns on a laptop (the table of contents goes), one on a phone, where the
+ * navigation folds into a `<details>` disclosure at the top of the article.
+ *
+ * The sidebar is in two copies: a plain `<nav>` for wide screens, and the
+ * same links inside the disclosure for narrow ones. A closed `<details>`
+ * hides its content through the browser's own `::details-content` box, which
+ * a stylesheet cannot reliably reopen on a wide screen (verified in Chrome in
+ * L25), so the desktop column is never a disclosure. Exactly one copy is
+ * displayed at any width, so a screen reader is never offered two.
+ *
+ * Under the article: the date the page last changed, and links to the
+ * previous and next pages in the documentation's reading order. No comment
+ * form and no "was this helpful" widget: neither could be answered honestly
+ * by a static page.
+ */
+function sidebarLinks(groups, ctx, current) {
+    return groups.map((group) => h('div', { class: 'cd-sidenav__group' }, h('p', { class: 'cd-sidenav__heading' }, group.section), h('ul', { class: 'cd-sidenav__links' }, group.entries.map((entry) => {
+        const target = entryHref(entry, ctx);
+        return h('li', { class: 'cd-sidenav__item' }, h('a', {
+            class: 'cd-sidenav__link',
+            href: target,
+            'aria-current': target === current ? 'page' : undefined,
+        }, entryTitle(entry, ctx)));
+    }))));
+}
+function renderSidebar(groups, ctx, current, currentEntry, title) {
+    const label = word(ctx.locale, 'documentation');
+    const section = typeof currentEntry?.section === 'string' ? currentEntry.section : undefined;
+    return [
+        h('nav', { class: 'cd-sidenav cd-sidenav--wide', 'aria-label': label }, sidebarLinks(groups, ctx, current)),
+        h('details', { class: 'cd-sidenav-disclosure' }, h('summary', { class: 'cd-sidenav-disclosure__summary' }, h('span', { class: 'cd-sidenav-disclosure__label' }, word(ctx.locale, 'menu')), h('span', { class: 'cd-sidenav-disclosure__where' }, section === undefined ? title : `${section} / ${title}`)), h('nav', { class: 'cd-sidenav cd-sidenav--narrow', 'aria-label': label }, sidebarLinks(groups, ctx, current))),
+    ];
+}
+function renderBreadcrumb(ctx, section, title) {
+    return h('nav', { class: 'cd-breadcrumb', 'aria-label': word(ctx.locale, 'breadcrumb') }, h('ol', { class: 'cd-breadcrumb__items' }, h('li', {}, h('a', { href: ctx.link('/') }, word(ctx.locale, 'docsHome'))), section === undefined ? null : h('li', {}, section), h('li', { 'aria-current': 'page' }, title)));
+}
+function renderToc(ctx, anchors) {
+    const list = [...anchors.values()];
+    if (list.length < 2)
+        return null;
+    const items = [];
+    let children = [];
+    let parent;
+    const close = () => {
+        if (parent === undefined) {
+            for (const orphan of children)
+                items.push(tocItem(orphan, []));
+        }
+        else {
+            items.push(tocItem(parent, children));
+        }
+        children = [];
+        parent = undefined;
+    };
+    for (const anchor of list) {
+        if (anchor.level === 2) {
+            close();
+            parent = anchor;
+        }
+        else {
+            children.push(anchor);
+        }
+    }
+    close();
+    return h('nav', { class: 'cd-toc', 'aria-labelledby': 'cd-toc-label' }, h('p', { class: 'cd-toc__label', id: 'cd-toc-label' }, word(ctx.locale, 'onThisPage')), h('ol', { class: 'cd-toc__items' }, items));
+}
+function tocItem(anchor, children) {
+    return h('li', { class: 'cd-toc__item', 'data-level': String(anchor.level) }, h('a', { class: 'cd-toc__link', href: `#${anchor.id}` }, anchor.text), children.length === 0
+        ? null
+        : h('ol', { class: 'cd-toc__items' }, children.map((child) => tocItem(child, []))));
+}
+function pagerLink(ctx, entry, direction) {
+    if (entry === undefined)
+        return null;
+    return h('a', {
+        class: 'cd-pager__link',
+        'data-direction': direction,
+        href: entryHref(entry, ctx),
+        rel: direction === 'previous' ? 'prev' : 'next',
+    }, h('span', { class: 'cd-pager__label' }, word(ctx.locale, direction)), h('span', { class: 'cd-pager__title' }, entryTitle(entry, ctx)));
+}
+function renderFoot(page, ctx, order, currentIndex) {
+    const updated = page.entry?.updatedAt;
+    const previous = currentIndex > 0 ? order[currentIndex - 1] : undefined;
+    const next = currentIndex >= 0 ? order[currentIndex + 1] : undefined;
+    const pager = previous === undefined && next === undefined
+        ? null
+        : h('nav', { class: 'cd-pager', 'aria-label': word(ctx.locale, 'pager') }, pagerLink(ctx, previous, 'previous'), pagerLink(ctx, next, 'next'));
+    return h('footer', { class: 'cd-doc__foot' }, updated === undefined
+        ? null
+        : h('p', { class: 'cd-doc__updated' }, `${word(ctx.locale, 'lastUpdated')} `, h('time', { datetime: updated }, longDate(updated, ctx.locale))), pager);
+}
+export function renderDocPage(page, ctx, sidebarBlock, entries, registry, renderOne) {
+    const groups = groupDocPages(entries[sidebarBlock._key] ?? [], ctx);
+    const order = readingOrder(groups);
+    const current = ctx.url.pathname;
+    const currentIndex = order.findIndex((entry) => entryHref(entry, ctx) === current);
+    const currentEntry = currentIndex >= 0 ? order[currentIndex] : undefined;
+    const section = typeof currentEntry?.section === 'string' ? currentEntry.section : undefined;
+    const content = page.blocks.slice(1);
+    const anchors = headingAnchors(content);
+    const ownHeading = pageHasOwnHeading(content);
+    const toc = renderToc(ctx, anchors);
+    return h('main', { class: 'cg-main cd-doc', id: 'cg-main', 'data-toc': toc === null ? 'false' : 'true' }, h('div', { class: 'cd-doc__layout' }, withBlockKey(h('div', { class: 'cd-doc__sidebar' }, renderSidebar(groups, ctx, current, currentEntry, page.title)), sidebarBlock._key), h('article', { class: 'cd-doc__article' }, h('header', { class: 'cd-doc__head' }, renderBreadcrumb(ctx, section, page.title), ownHeading ? null : h('h1', { class: 'cd-doc__title' }, page.title), page.entry?.excerpt === undefined
+        ? null
+        : h('p', { class: 'cd-doc__lede' }, page.entry.excerpt)), h('div', { class: 'cd-doc__body' }, content.map((block) => withBlockKey(renderOne(block, ctx, entries, registry, anchors), block._key))), renderFoot(page, ctx, order, currentIndex)), toc === null ? null : h('div', { class: 'cd-doc__toc' }, toc)));
+}
+//# sourceMappingURL=doc-page.js.map

package/dist/src/render/doc-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-page.js","sourceRoot":"","sources":["../../../src/render/doc-page.ts"],"names":[],"mappings":"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"}

package/dist/src/render/layout.d.ts

@@ -0,0 +1,23 @@
+import { type Attributes, type Child, type HtmlElement } from '@cogenta/theme-kit';
+/**
+ * The frame every block of this theme renders into.
+ *
+ * The outer element carries the one section rhythm (`--cd-section`, the same
+ * for every block) and paints edge to edge when a variant asks for a band.
+ * The inner element is the twelve-column container, so a section title, a
+ * link, a figure and a caption all start on the same left edge. Inside a
+ * documentation page the same markup is laid out in the reading column
+ * instead (`docs.css`), so a block placed in an article needs nothing extra.
+ *
+ * `inner` is `figure` for a block whose semantics are a figure (a quotation
+ * and its attribution, an image and its caption): `<figcaption>` must be a
+ * direct child of its `<figure>`.
+ */
+export declare function section(outer: 'section' | 'div', block: string, className: string, attrs: Attributes, inner: 'div' | 'figure', ...children: readonly Child[]): HtmlElement;
+/** A titled block's heading, from the first column, left-aligned with the content under it. */
+export declare function sectionHead(blockName: string, title: string | undefined): HtmlElement | null;
+/** A paragraph that renders only when the text is there: no empty `<p>` on the page. */
+export declare function optionalText(tag: string, className: string, value: string | undefined, attrs?: Attributes): HtmlElement | null;
+/** `Intl.DateTimeFormat`'s long date in the page's locale: "September 14, 2026". */
+export declare function longDate(iso: string, locale: string): string;
+//# sourceMappingURL=layout.d.ts.map

package/dist/src/render/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/render/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,KAAK,EACV,KAAK,WAAW,EAGjB,MAAM,oBAAoB,CAAA;AAE3B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,SAAS,GAAG,KAAK,EACxB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,KAAK,GAAG,QAAQ,EACvB,GAAG,QAAQ,EAAE,SAAS,KAAK,EAAE,GAC5B,WAAW,CAMb;AAED,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAW5F;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,GAAE,UAAe,GACrB,WAAW,GAAG,IAAI,CAGpB;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ5D"}

package/dist/src/render/layout.js

@@ -0,0 +1,40 @@
+import { blockHeadingTag, h, heading, } from '@cogenta/theme-kit';
+/**
+ * The frame every block of this theme renders into.
+ *
+ * The outer element carries the one section rhythm (`--cd-section`, the same
+ * for every block) and paints edge to edge when a variant asks for a band.
+ * The inner element is the twelve-column container, so a section title, a
+ * link, a figure and a caption all start on the same left edge. Inside a
+ * documentation page the same markup is laid out in the reading column
+ * instead (`docs.css`), so a block placed in an article needs nothing extra.
+ *
+ * `inner` is `figure` for a block whose semantics are a figure (a quotation
+ * and its attribution, an image and its caption): `<figcaption>` must be a
+ * direct child of its `<figure>`.
+ */
+export function section(outer, block, className, attrs, inner, ...children) {
+    return h(outer, { class: `cd-section ${className}`, 'data-block': block, ...attrs }, h(inner, { class: `cd-container ${className}__inner` }, ...children));
+}
+/** A titled block's heading, from the first column, left-aligned with the content under it. */
+export function sectionHead(blockName, title) {
+    if (title === undefined || title.trim() === '')
+        return null;
+    return h('div', { class: 'cd-head' }, heading(blockHeadingTag(blockName) ?? 'h2', { class: 'cd-head__title', 'data-field': 'title' }, title));
+}
+/** A paragraph that renders only when the text is there: no empty `<p>` on the page. */
+export function optionalText(tag, className, value, attrs = {}) {
+    if (value === undefined || value.trim() === '')
+        return null;
+    return h(tag, { class: className, ...attrs }, value);
+}
+/** `Intl.DateTimeFormat`'s long date in the page's locale: "September 14, 2026". */
+export function longDate(iso, locale) {
+    try {
+        return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(new Date(iso));
+    }
+    catch {
+        return iso.slice(0, 10);
+    }
+}
+//# sourceMappingURL=layout.js.map

package/dist/src/render/layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../../src/render/layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,eAAe,EAGf,CAAC,EACD,OAAO,GACR,MAAM,oBAAoB,CAAA;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO,CACrB,KAAwB,EACxB,KAAa,EACb,SAAiB,EACjB,KAAiB,EACjB,KAAuB,EACvB,GAAG,QAA0B;IAE7B,OAAO,CAAC,CACN,KAAK,EACL,EAAE,KAAK,EAAE,cAAc,SAAS,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,EACnE,CAAC,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,gBAAgB,SAAS,SAAS,EAAE,EAAE,GAAG,QAAQ,CAAC,CACrE,CAAA;AACH,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,KAAyB;IACtE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IAC3D,OAAO,CAAC,CACN,KAAK,EACL,EAAE,KAAK,EAAE,SAAS,EAAE,EACpB,OAAO,CACL,eAAe,CAAC,SAAS,CAAC,IAAI,IAAI,EAClC,EAAE,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,OAAO,EAAE,EAClD,KAAK,CACN,CACF,CAAA;AACH,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,YAAY,CAC1B,GAAW,EACX,SAAiB,EACjB,KAAyB,EACzB,KAAK,GAAe,EAAE;IAEtB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAA;IAC3D,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,CAAA;AACtD,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,MAAc;IAClD,IAAI,CAAC;QACH,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,CACnF,IAAI,IAAI,CAAC,GAAG,CAAC,CACd,CAAA;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IACzB,CAAC;AACH,CAAC"}

package/dist/src/render/render-block.d.ts

@@ -3,13 +3,16 @@ import { type FetchedEntries, type HtmlElement, type PageContent, type RenderCon
 export type { FetchedEntries, PageContent };
 export declare function renderBlock(block: VocabularyBlock, ctx: RenderContext, entries?: FetchedEntries, registry?: BlockRegistry): HtmlElement | null;
 /**
- * `<main id="cg-main">` is mandatory: it is the skip-link's target, written
- * once by `@cogenta/cli`'s own render path.
+ * `<main id="cg-main">` is mandatory: it is the skip link's target, written
+ * by the host outside any theme's control.
  *
- * `withBlockKey` stamps every rendered block with its contract-B `_key`, on
- * every page including a doc page's content column — the visual page
- * builder maps a clicked element back to the block that produced it, for
- * this theme exactly as for every other one.
+ * A page whose first block is the documentation's own index on `doc_page` is
+ * a documentation page (`doc-page.ts`); every other page is laid out on the
+ * twelve-column grid. Exactly one `h1` on every page: a hero carries it when
+ * there is one, the page head otherwise.
+ *
+ * `withBlockKey` stamps every rendered block with its contract-B `_key`, so
+ * the visual page builder (L16) can map a clicked element back to its block.
  */
 export declare function renderPage(page: PageContent, ctx: RenderContext, entries?: FetchedEntries, registry?: BlockRegistry): HtmlElement;
 //# sourceMappingURL=render-block.d.ts.map

package/dist/src/render/render-block.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-block.d.ts","sourceRoot":"","sources":["../../../src/render/render-block.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAoB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC5F,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EAEhB,KAAK,aAAa,EAKnB,MAAM,oBAAoB,CAAA;AAmB3B,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,CAAA;AAE3C,wBAAgB,WAAW,CACzB,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,cAAmB,EAC5B,QAAQ,CAAC,EAAE,aAAa,GACvB,WAAW,GAAG,IAAI,CAKpB;AAsOD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,cAAmB,EAC5B,QAAQ,CAAC,EAAE,aAAa,GACvB,WAAW,CAcb"}
+{"version":3,"file":"render-block.d.ts","sourceRoot":"","sources":["../../../src/render/render-block.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAoB,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC5F,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EAGhB,KAAK,aAAa,EAInB,MAAM,oBAAoB,CAAA;AAuB3B,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,CAAA;AAoB3C,wBAAgB,WAAW,CACzB,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,cAAmB,EAC5B,QAAQ,CAAC,EAAE,aAAa,GACvB,WAAW,GAAG,IAAI,CAOpB;AAiFD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,cAAmB,EAC5B,QAAQ,CAAC,EAAE,aAAa,GACvB,WAAW,CAeb"}

package/dist/src/render/render-block.js

@@ -1,5 +1,5 @@
 import { VOCABULARY_NAMES } from '@cogenta/blocks';
-import { entryHref, entryTitle, h, pageHasOwnHeading, renderEntryHeader, resolveBlockForRender, withBlockKey, withBlockVariant, } from '@cogenta/theme-kit';
+import { h, pageHasOwnHeading, providedBlockNode, resolveBlockForRender, withBlockKey, withBlockVariant, } from '@cogenta/theme-kit';
 import { renderAccordion } from './blocks/accordion.js';
 import { renderCollectionList } from './blocks/collection-list.js';
 import { renderCta } from './blocks/cta.js';
@@ -17,19 +17,37 @@ import { renderQuote } from './blocks/quote.js';
 import { renderStatCounter } from './blocks/stat-counter.js';
 import { renderStats } from './blocks/stats.js';
 import { renderTestimonial } from './blocks/testimonial.js';
-export function renderBlock(block, ctx, entries = {}, registry) {
+import { isDocIndexBlock } from './doc-index.js';
+import { renderDocPage } from './doc-page.js';
+import { longDate } from './layout.js';
+import { headingAnchors } from './rich-text.js';
+function renderResolved(block, ctx, entries, registry, anchors) {
+    // A stored block is not always literally one of the shared vocabulary:
+    // resolving here turns an unimplemented theme-private block into its
+    // declared fallback instead of a silently blank slot.
     const resolved = resolveBlockForRender(block, VOCABULARY_NAMES, registry);
     if (resolved === null)
         return null;
     const known = resolved;
-    return withBlockVariant(renderKnownBlock(known, ctx, entries), known.variant);
+    // `variant` is envelope data every block carries identically, applied once
+    // here rather than by each of the seventeen renderers.
+    return withBlockVariant(renderKnownBlock(known, ctx, entries, anchors), known.variant);
+}
+export function renderBlock(block, ctx, entries = {}, registry) {
+    // A block a plugin provides arrives already rendered by the host, in a
+    // process of its own (contract D theme@1.7). Nothing else in this theme
+    // needs to know such blocks exist.
+    const provided = providedBlockNode(block, ctx);
+    if (provided !== null)
+        return withBlockVariant(provided, block.variant);
+    return renderResolved(block, ctx, entries, registry, headingAnchors([block]));
 }
-function renderKnownBlock(known, ctx, entries) {
+function renderKnownBlock(known, ctx, entries, anchors) {
     switch (known._type) {
         case 'hero':
             return renderHero(known, ctx);
         case 'prose':
-            return renderProse(known, ctx);
+            return renderProse(known, ctx, anchors);
         case 'mediaFigure':
             return renderMediaFigure(known, ctx);
         case 'featureGrid':
@@ -61,6 +79,9 @@ function renderKnownBlock(known, ctx, entries) {
         case 'logoStrip':
             return renderLogoStrip(known, ctx);
         default: {
+            // Exhaustive over contract B: `known` is `never` here, so a block this
+            // package does not implement stops it compiling until it is. `null`
+            // rather than a throw: choosing a fallback is the render layer's job.
             const unreachable = known;
             void unreachable;
             return null;
@@ -68,109 +89,35 @@ function renderKnownBlock(known, ctx, entries) {
     }
 }
 /**
- * The name every doc page's own blueprint-seeded sidebar `collectionList`
- * targets — checked structurally (first block, this collection) rather than
- * by any flag on the block, because contract B carries no "this is chrome,
- * not content" bit and inventing one would be a contract change for a
- * single theme's layout choice.
- */
-const DOC_PAGE_COLLECTION = 'doc_page';
-function isDocSidebarBlock(block) {
-    return block._type === 'collectionList' && block.collection === DOC_PAGE_COLLECTION;
-}
-/** The sidebar entry whose own link resolves to the page being rendered — the "current page" the brief asks the sidebar to highlight and the breadcrumb to name. */
-function findCurrentEntry(entries, ctx) {
-    return entries.find((entry) => entryHref(entry, ctx) === ctx.url.pathname);
-}
-/**
- * The doc-page sidebar — grouped by each entry's own `section` field, in the
- * order the entries were fetched (the blueprint seeds them in `order`
- * within a section already; `collectionList.sort` cannot name `section`/
- * `order`, so an editor who reorders sections relies on the fetch order,
- * exactly like the "All guides" index on the home page does).
+ * The opening of a page outside the documentation that has no hero: its
+ * title, its summary, and the date it was published when it has one.
  */
-function renderSidebarPanel(entries, ctx, currentHref) {
-    const groups = new Map();
-    for (const entry of entries) {
-        const section = typeof entry.section === 'string' && entry.section !== ''
-            ? entry.section
-            : ctx.t('entry.untitled');
-        const list = groups.get(section) ?? [];
-        list.push(entry);
-        groups.set(section, list);
-    }
-    return h('nav', { class: 'cg-docs__nav-panel', 'aria-label': 'Documentation' }, [...groups.entries()].map(([section, sectionEntries]) => h('div', { class: 'cg-docs__nav-group' }, h('p', { class: 'cg-docs__nav-heading' }, section), h('ul', { class: 'cg-docs__nav-items' }, sectionEntries.map((entry) => {
-        const href = entryHref(entry, ctx);
-        const isCurrent = href === currentHref;
-        return h('li', {}, h('a', {
-            class: 'cg-docs__nav-link',
-            href,
-            'aria-current': isCurrent ? 'page' : undefined,
-        }, entryTitle(entry, ctx)));
-    })))));
+function renderPageHead(page, ctx) {
+    const published = page.entry?.publishedAt;
+    return h('header', { class: 'cd-page-head' }, h('div', { class: 'cd-container cd-page-head__inner' }, h('h1', { class: 'cd-page-head__title' }, page.title), page.entry?.excerpt === undefined
+        ? null
+        : h('p', { class: 'cd-page-head__lead' }, page.entry.excerpt), published === undefined
+        ? null
+        : h('p', { class: 'cd-page-head__meta' }, h('time', { datetime: published }, longDate(published, ctx.locale)))));
 }
 /**
- * The sidebar, in two copies — the same zero-JS technique `chrome.ts` already
- * uses for the header's own mobile menu, and for the same reason: Chrome (and
- * every other engine implementing the current HTML rendering rules) hides a
- * closed `<details>`'s non-summary content through its own internal
- * `::details-content` box, not through the plain CSS `display: none` the spec
- * text describes — so a stylesheet rule that sets `display: block` on that
- * content, however specific, does not reliably bring it back while the
- * element itself stays closed. Verified live: a build with a single
- * `<details>` forced open only above the two-column breakpoint rendered an
- * empty sidebar column at 1280px in a real Chrome tab, despite every
- * computed style reporting `display: block`.
+ * `<main id="cg-main">` is mandatory: it is the skip link's target, written
+ * by the host outside any theme's control.
  *
- * The fix is the same one already proven for the header: a plain, always-
- * live `<nav>` for the desktop column (nothing to collapse, so nothing for
- * the browser to hide), and a **separate** `<details>` disclosure — a full
- * second copy of the same panel — for narrow viewports. Exactly one of the
- * two is ever `display: block` at a given viewport width (`base.css`), so a
- * screen reader is never offered two "Documentation" navigations at once,
- * matching the header's own accessibility guarantee.
- */
-function renderSidebar(entries, ctx, currentHref) {
-    return h('div', { class: 'cg-docs__nav-desktop' }, renderSidebarPanel(entries, ctx, currentHref));
-}
-function renderSidebarMobile(entries, ctx, currentHref) {
-    return h('details', { class: 'cg-docs__nav-mobile' }, h('summary', { class: 'cg-docs__nav-toggle' }, 'On this site'), renderSidebarPanel(entries, ctx, currentHref));
-}
-function renderBreadcrumb(section, title) {
-    return h('nav', { class: 'cg-docs__breadcrumb', 'aria-label': 'Breadcrumb' }, h('ol', {}, section === undefined ? null : h('li', {}, section), h('li', { 'aria-current': 'page' }, title)));
-}
-/**
- * A doc page: two columns, CSS-only. The sidebar comes from the page's own
- * *first* block — a `collectionList` on `doc_page` the blueprint seeds on
- * every doc page for exactly this purpose — rendered as navigation rather
- * than as a card list, and dropped from the ordinary block stream so it
- * never also appears as content. The remaining blocks render in the content
- * column, unchanged.
- */
-function renderDocPage(page, ctx, sidebarBlock, entries, registry) {
-    const sidebarEntries = entries[sidebarBlock._key] ?? [];
-    const currentHref = ctx.url.pathname;
-    const current = findCurrentEntry(sidebarEntries, ctx);
-    const section = typeof current?.section === 'string' ? current.section : undefined;
-    const contentBlocks = page.blocks.slice(1);
-    const hasOwnHeading = pageHasOwnHeading(contentBlocks);
-    const entryHeader = renderEntryHeader(page, ctx);
-    return h('main', { class: 'cg-main cg-docs', id: 'cg-main' }, withBlockKey(h('div', { class: 'cg-docs__nav' }, renderSidebar(sidebarEntries, ctx, currentHref), renderSidebarMobile(sidebarEntries, ctx, currentHref)), sidebarBlock._key), h('div', { class: 'cg-docs__content' }, renderBreadcrumb(section, page.title), entryHeader ?? (hasOwnHeading ? null : h('h1', { class: 'cg-docs__title' }, page.title)), contentBlocks.map((block) => withBlockKey(renderBlock(block, ctx, entries, registry), block._key))));
-}
-/**
- * `<main id="cg-main">` is mandatory: it is the skip-link's target, written
- * once by `@cogenta/cli`'s own render path.
+ * A page whose first block is the documentation's own index on `doc_page` is
+ * a documentation page (`doc-page.ts`); every other page is laid out on the
+ * twelve-column grid. Exactly one `h1` on every page: a hero carries it when
+ * there is one, the page head otherwise.
  *
- * `withBlockKey` stamps every rendered block with its contract-B `_key`, on
- * every page including a doc page's content column — the visual page
- * builder maps a clicked element back to the block that produced it, for
- * this theme exactly as for every other one.
+ * `withBlockKey` stamps every rendered block with its contract-B `_key`, so
+ * the visual page builder (L16) can map a clicked element back to its block.
  */
 export function renderPage(page, ctx, entries = {}, registry) {
     const first = page.blocks[0];
-    if (first !== undefined && isDocSidebarBlock(first)) {
-        return renderDocPage(page, ctx, first, entries, registry);
+    if (first !== undefined && isDocIndexBlock(first)) {
+        return renderDocPage(page, ctx, first, entries, registry, renderResolved);
     }
-    return h('main', { class: 'cg-main', id: 'cg-main' }, pageHasOwnHeading(page.blocks) ? null : h('h1', { class: 'cg-page__title' }, page.title), page.blocks.map((block) => withBlockKey(renderBlock(block, ctx, entries, registry), block._key)));
+    const anchors = headingAnchors(page.blocks);
+    return h('main', { class: 'cg-main cd-main', id: 'cg-main' }, pageHasOwnHeading(page.blocks) ? null : renderPageHead(page, ctx), page.blocks.map((block) => withBlockKey(renderResolved(block, ctx, entries, registry, anchors), block._key)));
 }
 //# sourceMappingURL=render-block.js.map

package/dist/src/render/render-block.js.map

@@ -1 +1 @@
-{"version":3,"file":"render-block.js","sourceRoot":"","sources":["../../../src/render/render-block.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"render-block.js","sourceRoot":"","sources":["../../../src/render/render-block.ts"],"names":[],"mappings":"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"}

package/dist/src/render/rich-text.d.ts

@@ -0,0 +1,26 @@
+import type { RichTextDocument, VocabularyBlock } from '@cogenta/blocks';
+import { type HtmlNode, type RenderContext } from '@cogenta/theme-kit';
+export interface HeadingAnchor {
+    readonly id: string;
+    readonly text: string;
+    readonly level: 2 | 3;
+}
+/** Anchors by `${blockKey}:${nodeKey}`, in reading order. */
+export type HeadingAnchors = ReadonlyMap<string, HeadingAnchor>;
+export declare function slugify(value: string): string;
+/**
+ * One id per `h2`/`h3` of every `prose` block on a page, unique across the
+ * page: a second "Examples" becomes `examples-2`. Computed once for the whole
+ * page, so the table of contents and the headings always agree.
+ */
+export declare function headingAnchors(blocks: readonly VocabularyBlock[]): HeadingAnchors;
+export declare function keyChord(value: string): readonly string[] | null;
+export interface DocsRichTextOptions {
+    /** The block the document belongs to, and the page's anchors. Absent: headings get no id (a FAQ answer, say). */
+    readonly anchors?: {
+        readonly blockKey: string;
+        readonly map: HeadingAnchors;
+    };
+}
+export declare function renderDocsRichText(ctx: RenderContext, document: RichTextDocument, options?: DocsRichTextOptions): readonly HtmlNode[];
+//# sourceMappingURL=rich-text.d.ts.map

package/dist/src/render/rich-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-text.d.ts","sourceRoot":"","sources":["../../../src/render/rich-text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAsB,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC5F,OAAO,EAEL,KAAK,QAAQ,EAEb,KAAK,aAAa,EAGnB,MAAM,oBAAoB,CAAA;AA6C3B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAA;CACtB;AAED,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;AAW/D,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAUD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,cAAc,CAsBjF;AAyND,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAYhE;AAyBD,MAAM,WAAW,mBAAmB;IAClC,iHAAiH;IACjH,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAA;KAAE,CAAA;CAC/E;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,mBAAwB,GAChC,SAAS,QAAQ,EAAE,CAkErB"}