@cogenta/theme-docs 0.3.2

package/src/render/blocks/pricing-table.ts

@@ -0,0 +1,72 @@
+import type { PricingTableBlock, PricingTier } from '@cogenta/blocks'
+import {
+  actionLink,
+  blockHeadingTag,
+  type HeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  nestedHeadingTag,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/**
+ * `blocks@2.0` (RFC 0001). Bordered plates, one lifted (border + a small
+ * "recommended" rule) when `highlighted` is set — an editorial signal,
+ * never a colour: it becomes `data-highlighted` for the stylesheet, and
+ * `aria-current` so the emphasis is announced, not only shown.
+ */
+function renderTier(tier: PricingTier, ctx: RenderContext, tag: HeadingTag): HtmlElement {
+  return h(
+    'li',
+    {
+      class: 'cg-pricing__tier',
+      'data-highlighted': tier.highlighted === true ? 'true' : undefined,
+      'aria-current': tier.highlighted === true ? 'true' : undefined,
+    },
+    heading(tag, { class: 'cg-pricing__name' }, tier.name),
+    h(
+      'p',
+      { class: 'cg-pricing__price' },
+      h('span', { class: 'cg-pricing__amount' }, tier.price),
+      tier.interval === undefined
+        ? null
+        : h('span', { class: 'cg-pricing__interval' }, tier.interval),
+    ),
+    tier.features.length === 0
+      ? null
+      : h(
+          'ul',
+          { class: 'cg-pricing__features' },
+          tier.features.map((feature) => h('li', { class: 'cg-pricing__feature' }, feature)),
+        ),
+    tier.action === undefined
+      ? null
+      : h(
+          'div',
+          { class: 'cg-pricing__action' },
+          actionLink(ctx, { ...tier.action, emphasis: tier.action.emphasis ?? 'primary' }),
+        ),
+  )
+}
+
+export function renderPricingTable(block: PricingTableBlock, ctx: RenderContext): HtmlElement {
+  const hasTitle = block.title !== undefined
+  const tierTag = nestedHeadingTag('pricingTable', hasTitle)
+  return h(
+    'section',
+    { class: 'cg-block cg-pricing', 'data-block': 'pricingTable' },
+    hasTitle
+      ? heading(
+          blockHeadingTag('pricingTable') ?? 'h2',
+          { class: 'cg-pricing__title', 'data-field': 'title' },
+          block.title ?? '',
+        )
+      : null,
+    h(
+      'ul',
+      { class: 'cg-pricing__tiers' },
+      block.tiers.map((tier) => renderTier(tier, ctx, tierTag)),
+    ),
+  )
+}

package/src/render/blocks/prose.ts

@@ -0,0 +1,49 @@
+import type { ProseBlock } from '@cogenta/blocks'
+import {
+  type HtmlElement,
+  type HtmlNode,
+  h,
+  type RenderContext,
+  renderRichText,
+} from '@cogenta/theme-kit'
+
+/**
+ * `prose` declares `headingLevel: 'none'`: it contributes no heading of its
+ * own. Whatever headings appear come from the rich text document, whose
+ * vocabulary starts at `h2`.
+ *
+ * Contract A's rich text schema (`@cogenta/schema`, frozen) has no fenced
+ * "code block" node — the only code-shaped thing it can carry is a
+ * paragraph whose sole span carries the `code` mark, which
+ * `renderRichText` (`@cogenta/theme-kit`) already turns into
+ * `<p><code>…</code></p>`. A documentation theme without a real, multi-line
+ * code block would be dishonest about what it is for, so this is the one
+ * place in the theme that post-processes theme-kit's own output rather than
+ * writing a second rich-text renderer: a `<p>` whose only child is a bare
+ * `<code>` is promoted to `<pre><code>`, everything else is untouched. The
+ * transform only ever changes two tag names on an already-escaped tree — no
+ * new content is invented, and R3 (a block never stores HTML) still holds,
+ * since the source is still the same structured span the editor wrote.
+ */
+function promoteCodeBlocks(nodes: readonly HtmlNode[]): readonly HtmlNode[] {
+  return nodes.map((node) => {
+    if (node.kind !== 'element') return node
+    if (
+      node.tag === 'p' &&
+      node.children.length === 1 &&
+      node.children[0]?.kind === 'element' &&
+      node.children[0].tag === 'code'
+    ) {
+      return h('pre', { class: 'cg-prose__code' }, node.children[0])
+    }
+    return node
+  })
+}
+
+export function renderProse(block: ProseBlock, ctx: RenderContext): HtmlElement {
+  return h(
+    'div',
+    { class: 'cg-block cg-prose', 'data-block': 'prose' },
+    promoteCodeBlocks(renderRichText(ctx, block.body)),
+  )
+}

package/src/render/blocks/quote.ts

@@ -0,0 +1,35 @@
+import type { QuoteBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+
+/**
+ * `<figure><blockquote>…</blockquote><figcaption>` is the attribution
+ * pattern the HTML spec prescribes: putting the author inside the
+ * `<blockquote>` would claim the author's name is part of what was said.
+ */
+export function renderQuote(block: QuoteBlock, ctx: RenderContext): HtmlElement {
+  const hasAttribution =
+    block.author !== undefined || block.role !== undefined || block.avatar !== undefined
+  return h(
+    'figure',
+    { class: 'cg-block cg-quote', 'data-block': 'quote' },
+    h('blockquote', { class: 'cg-quote__text' }, h('p', { 'data-field': 'text' }, block.text)),
+    hasAttribution
+      ? h(
+          'figcaption',
+          { class: 'cg-quote__attribution' },
+          block.avatar === undefined
+            ? null
+            : image(ctx, block.avatar, {
+                className: 'cg-quote__avatar',
+                variant: { width: 96, height: 96, fit: 'cover' },
+              }),
+          block.author === undefined
+            ? null
+            : h('span', { class: 'cg-quote__author', 'data-field': 'author' }, block.author),
+          block.role === undefined
+            ? null
+            : h('span', { class: 'cg-quote__role', 'data-field': 'role' }, block.role),
+        )
+      : null,
+  )
+}

package/src/render/blocks/stat-counter.ts

@@ -0,0 +1,37 @@
+import type { StatCounterBlock, StatCounterItem } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/**
+ * `blocks@2.0` (RFC 0001). A `<dl>`, exactly like `stats`: the label sits
+ * before the figure in markup (WCAG 1.3.2); the stylesheet paints the big
+ * figure first.
+ */
+function renderItem(item: StatCounterItem): HtmlElement {
+  return h(
+    'div',
+    { class: 'cg-kpi' },
+    h('dt', { class: 'cg-kpi__label' }, item.label),
+    h('dd', { class: 'cg-kpi__value' }, item.value),
+  )
+}
+
+export function renderStatCounter(block: StatCounterBlock, _ctx: RenderContext): HtmlElement {
+  return h(
+    'section',
+    { class: 'cg-block cg-kpis', 'data-block': 'statCounter' },
+    block.title === undefined
+      ? null
+      : heading(
+          blockHeadingTag('statCounter') ?? 'h2',
+          { class: 'cg-kpis__title', 'data-field': 'title' },
+          block.title,
+        ),
+    h('dl', { class: 'cg-kpis__items' }, block.stats.map(renderItem)),
+  )
+}

package/src/render/blocks/stats.ts

@@ -0,0 +1,38 @@
+import type { StatItem, StatsBlock } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/** A description list: each figure is the description of its label. */
+function renderItem(item: StatItem): HtmlElement {
+  return h(
+    'div',
+    { class: 'cg-stat' },
+    h('dt', { class: 'cg-stat__label' }, item.label),
+    h(
+      'dd',
+      { class: 'cg-stat__value' },
+      item.value,
+      item.unit === undefined ? null : h('span', { class: 'cg-stat__unit' }, item.unit),
+    ),
+  )
+}
+
+export function renderStats(block: StatsBlock, _ctx: RenderContext): HtmlElement {
+  return h(
+    'section',
+    { class: 'cg-block cg-stats', 'data-block': 'stats' },
+    block.title === undefined
+      ? null
+      : heading(
+          blockHeadingTag('stats') ?? 'h2',
+          { class: 'cg-stats__title', 'data-field': 'title' },
+          block.title,
+        ),
+    h('dl', { class: 'cg-stats__items' }, block.items.map(renderItem)),
+  )
+}

package/src/render/blocks/testimonial.ts

@@ -0,0 +1,36 @@
+import type { TestimonialBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, image, type RenderContext, renderRichText } from '@cogenta/theme-kit'
+
+/**
+ * `blocks@2.0` (RFC 0001). The same `<figure><blockquote>…</blockquote>
+ * <figcaption>` pattern `quote` uses, kept consistent so the two read as
+ * siblings — the quote itself is rich text here, and the attribution is
+ * the block's single grouped `attribution` field rather than three loose
+ * ones.
+ */
+export function renderTestimonial(block: TestimonialBlock, ctx: RenderContext): HtmlElement {
+  const { attribution } = block
+  return h(
+    'figure',
+    { class: 'cg-block cg-testimonial', 'data-block': 'testimonial' },
+    h('blockquote', { class: 'cg-testimonial__quote' }, renderRichText(ctx, block.quote)),
+    h(
+      'figcaption',
+      { class: 'cg-testimonial__attribution' },
+      attribution.avatar === undefined
+        ? null
+        : image(ctx, attribution.avatar, {
+            className: 'cg-testimonial__avatar',
+            variant: { width: 96, height: 96, fit: 'cover' },
+          }),
+      h(
+        'span',
+        { class: 'cg-testimonial__who' },
+        h('span', { class: 'cg-testimonial__name' }, attribution.name),
+        attribution.role === undefined
+          ? null
+          : h('span', { class: 'cg-testimonial__role' }, attribution.role),
+      ),
+    ),
+  )
+}

package/src/render/chrome.ts

@@ -0,0 +1,124 @@
+import {
+  type ChromeInput,
+  type ChromeNavLink,
+  type ChromeResult,
+  escapeAttribute,
+  escapeText,
+  renderBrandMark,
+  renderSocialLinks,
+  renderThemeToggle,
+  serialize,
+} from '@cogenta/theme-kit'
+
+/**
+ * This theme's own header and footer — structurally distinct from the
+ * canonical theme's, not a recolour of it: a docs site's header carries a
+ * genuine CSS-only mobile menu (a `<details>` disclosure, never a script),
+ * because "Docs / Guides / Reference / Blog" plus a header action does not
+ * fit a narrow viewport the way three links do.
+ *
+ * The mobile panel is a **second, hidden-by-default copy** of the same nav
+ * markup, not a repositioned single copy: two static layouts (`display:none`
+ * either way at a given viewport width) is the only zero-JS way to put the
+ * links inline on a wide screen and inside a disclosure on a narrow one.
+ * `display:none` removes the inactive copy from the accessibility tree, so a
+ * screen reader is never offered two "Primary" navigations at once — only
+ * the sighted, CSS-driven layout differs.
+ *
+ * Footer: brand column (name + tagline), a footer nav column, social links,
+ * a short "about" note, and Cogenta's own credit (or its white-label
+ * replacement) — `brandingHtml` placed exactly once, unaltered.
+ */
+
+function navItems(links: readonly ChromeNavLink[]): string {
+  return links
+    .filter((link) => link.href !== null || link.kind === 'submenu-placeholder')
+    .map((link) => {
+      const label = escapeText(link.label)
+      const titleAttr = link.title === null ? '' : ` title="${escapeAttribute(link.title)}"`
+      if (link.href === null) return `<li><span${titleAttr}>${label}</span></li>`
+      const href = escapeAttribute(link.href)
+      const target = link.openInNewTab ? ' target="_blank" rel="noopener"' : ''
+      return `<li><a href="${href}"${target}${titleAttr}>${label}</a></li>`
+    })
+    .join('')
+}
+
+function renderNav(links: readonly ChromeNavLink[], className: string, label: string): string {
+  const items = navItems(links)
+  return items === ''
+    ? ''
+    : `<nav class="${className}" aria-label="${label}"><ul class="cg-menu">${items}</ul></nav>`
+}
+
+/** The header's own call-to-action link (`theme@1.4`), reusing `.cg-action`'s own look. */
+function renderHeaderAction(action: ChromeInput['headerAction'], className: string): string {
+  if (action === undefined) return ''
+  return (
+    `<a class="cg-action ${className}" data-emphasis="primary" ` +
+    `href="${escapeAttribute(action.href)}">${escapeText(action.label)}</a>`
+  )
+}
+
+/** Three bars, drawn once for this file — not part of `renderIcon`'s closed vocabulary, since a "menu" glyph names no contract B field. */
+const HAMBURGER_SVG =
+  '<svg class="cg-nav-toggle__icon" viewBox="0 0 24 24" width="22" height="22" fill="none" ' +
+  'stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false">' +
+  '<path d="M4 6h16M4 12h16M4 18h16"/></svg>'
+
+export function renderChrome(input: ChromeInput): ChromeResult {
+  const siteName = escapeAttribute(input.site.name)
+  const siteNameText = escapeText(input.site.name)
+  const mark = renderBrandMark(input.brand, { className: 'cg-site-header__logo' }) ?? siteNameText
+
+  const desktopNav = renderNav(input.headerNav, 'cg-site-header__nav', 'Primary')
+  const themeToggle = serialize(renderThemeToggle(input.locale, { className: 'cg-theme-toggle' }))
+  const desktopAction = renderHeaderAction(input.headerAction, 'cg-site-header__action')
+
+  const mobileNavItems = navItems(input.headerNav)
+  const mobileAction = renderHeaderAction(input.headerAction, 'cg-nav-toggle__action')
+  const mobilePanel =
+    mobileNavItems === '' && mobileAction === ''
+      ? ''
+      : `<nav class="cg-nav-toggle__panel" aria-label="Primary">` +
+        `${mobileNavItems === '' ? '' : `<ul class="cg-menu">${mobileNavItems}</ul>`}` +
+        `${mobileAction}</nav>`
+
+  const toggle =
+    mobilePanel === ''
+      ? ''
+      : `<details class="cg-nav-toggle"><summary class="cg-nav-toggle__button" aria-label="Menu">${HAMBURGER_SVG}</summary>${mobilePanel}</details>`
+
+  const header =
+    `<header class="cg-site-header"><div class="cg-site-header__inner">` +
+    `<a class="cg-site-header__home" href="${escapeAttribute(input.homeHref)}">${mark}</a>` +
+    `${desktopNav}${themeToggle}${desktopAction}${toggle}` +
+    `</div></header>`
+
+  const footerNav = renderNav(input.footerNav, 'cg-site-footer__nav', 'Footer')
+  const tagline =
+    input.tagline === undefined
+      ? ''
+      : `<p class="cg-site-footer__tagline">${escapeText(input.tagline)}</p>`
+  const socialElement =
+    input.social === undefined
+      ? null
+      : renderSocialLinks(input.social, {
+          className: 'cg-site-footer__social',
+          itemClassName: 'cg-site-footer__social-item',
+        })
+  const social = socialElement === null ? '' : serialize(socialElement)
+  const footerNote =
+    input.footerNote === undefined
+      ? ''
+      : `<p class="cg-site-footer__note">${escapeText(input.footerNote)}</p>`
+
+  const footer =
+    `<footer class="cg-site-footer"><div class="cg-site-footer__grid">` +
+    `<div class="cg-site-footer__brand"><a href="${escapeAttribute(input.homeHref)}">${siteName}</a>${tagline}${social}</div>` +
+    `<div class="cg-site-footer__nav-col">${footerNav}</div>` +
+    `<div class="cg-site-footer__about-col">${footerNote}<div class="cg-site-footer__branding">${input.brandingHtml}</div></div>` +
+    `</div><div class="cg-site-footer__bottom"><span>${siteName}</span></div></footer>`
+
+  return { header, footer }
+}