@cogenta/theme-canonical 0.1.0

package/src/render/blocks/media-figure.ts

@@ -0,0 +1,42 @@
+import type { MediaFigureBlock } from '@cogenta/blocks'
+import type { RenderContext } from '../../theme-contract.js'
+import { type HtmlElement, h } from '../html.js'
+import { aspectRatio, image } from '../media.js'
+
+/**
+ * `<figure>`/`<figcaption>` rather than a div and a paragraph: the association
+ * between the picture and its caption is then in the markup, and a screen
+ * reader announces the caption as belonging to the image instead of as loose
+ * text after it.
+ *
+ * `align` is written as a data attribute, never as a class: contract B's values
+ * are `start`/`end`, an intent that mirrors in right-to-left locales, and the
+ * skin decides what it means.
+ */
+export function renderMediaFigure(block: MediaFigureBlock, ctx: RenderContext): HtmlElement {
+  const ratio = aspectRatio(block.ratio)
+  const hasCaption = block.caption !== undefined || block.credit !== undefined
+  return h(
+    'figure',
+    {
+      class: 'cg-block cg-figure',
+      'data-block': 'mediaFigure',
+      'data-align': block.align ?? 'center',
+      style: ratio === undefined ? undefined : `--cg-ratio:${ratio}`,
+    },
+    image(ctx, block.media, {
+      className: 'cg-figure__media',
+      sizes: '(min-width: 45rem) 40rem, 100vw',
+    }),
+    hasCaption
+      ? h(
+          'figcaption',
+          { class: 'cg-figure__caption' },
+          block.caption,
+          block.credit === undefined
+            ? null
+            : h('span', { class: 'cg-figure__credit' }, block.credit),
+        )
+      : null,
+  )
+}

package/src/render/blocks/prose.ts

@@ -0,0 +1,17 @@
+import type { ProseBlock } from '@cogenta/blocks'
+import type { RenderContext } from '../../theme-contract.js'
+import { type HtmlElement, h } from '../html.js'
+import { renderRichText } from '../rich-text.js'
+
+/**
+ * `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`.
+ */
+export function renderProse(block: ProseBlock, ctx: RenderContext): HtmlElement {
+  return h(
+    'div',
+    { class: 'cg-block cg-prose', 'data-block': 'prose' },
+    renderRichText(ctx, block.body),
+  )
+}

package/src/render/blocks/quote.ts

@@ -0,0 +1,39 @@
+import type { QuoteBlock } from '@cogenta/blocks'
+import type { RenderContext } from '../../theme-contract.js'
+import { type HtmlElement, h } from '../html.js'
+import { image } from '../media.js'
+
+/**
+ * `<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.
+ *
+ * The avatar is decorative here — the name is right beside it in text — so its
+ * media entity's alt text is expected to be empty. `image` still writes the
+ * attribute either way.
+ */
+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', {}, 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' }, block.author),
+          block.role === undefined ? null : h('span', { class: 'cg-quote__role' }, block.role),
+        )
+      : null,
+  )
+}

package/src/render/blocks/stats.ts

@@ -0,0 +1,41 @@
+import type { StatItem, StatsBlock } from '@cogenta/blocks'
+import type { RenderContext } from '../../theme-contract.js'
+import { blockHeadingTag, heading } from '../heading.js'
+import { type HtmlElement, h } from '../html.js'
+
+/**
+ * A description list: each figure is the description of its label, which is
+ * exactly what `<dt>`/`<dd>` mean, and it survives being read linearly.
+ *
+ * The label comes first in the markup and the skin puts the figure above it —
+ * reading order and visual order stay independent, which is what WCAG 1.3.2
+ * asks for. A `<div>` wrapper around each pair is valid inside `<dl>` and is
+ * what makes that reordering possible without breaking the association.
+ *
+ * The unit is a separate span so the skin can size it apart, and the pair is
+ * announced as one string either way.
+ */
+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' }, block.title),
+    h('dl', { class: 'cg-stats__items' }, block.items.map(renderItem)),
+  )
+}

package/src/render/entry.ts

@@ -0,0 +1,40 @@
+import type { ContentEntry, RenderContext } from '../theme-contract.js'
+
+/**
+ * Contract A fixes the system fields but not the schema-defined ones: which
+ * fields an entry has depends on its collection, and a theme that assumes
+ * `title` exists breaks on the first collection that calls it `name`.
+ *
+ * So every read of an unknown field goes through here, returns a fallback the
+ * visitor can live with, and never renders `undefined`.
+ */
+
+const TITLE_FIELDS = ['title', 'name', 'label'] as const
+
+export function entryTitle(entry: ContentEntry, ctx: RenderContext): string {
+  for (const field of TITLE_FIELDS) {
+    const value = entry[field]
+    if (typeof value === 'string' && value.trim() !== '') return value
+  }
+  return ctx.t('entry.untitled')
+}
+
+const EXCERPT_FIELDS = ['excerpt', 'summary', 'description'] as const
+
+export function entryExcerpt(entry: ContentEntry): string | undefined {
+  for (const field of EXCERPT_FIELDS) {
+    const value = entry[field]
+    if (typeof value === 'string' && value.trim() !== '') return value
+  }
+  return undefined
+}
+
+/** ISO 8601, for `<time datetime>`. Anything else is not a date this can use. */
+export function entryDate(entry: ContentEntry): string | undefined {
+  const value = entry.publishedAt ?? entry.createdAt
+  return typeof value === 'string' && !Number.isNaN(Date.parse(value)) ? value : undefined
+}
+
+export function entryHref(entry: ContentEntry, ctx: RenderContext): string {
+  return ctx.link({ collection: entry.collection, id: entry.id })
+}

package/src/render/heading.ts

@@ -0,0 +1,44 @@
+import type { HeadingLevel } from '@cogenta/blocks'
+import { VOCABULARY } from '@cogenta/blocks'
+import { type Child, type HtmlElement, h } from './html.js'
+
+/**
+ * The heading level of a block is **not** a theme decision: contract B fixes it
+ * in each block's `a11y.headingLevel`, and the theme reads it from there rather
+ * than restating it. Restating it is how an outline drifts — one block gets
+ * promoted in the theme, the page grows a second `h1`, and nothing fails.
+ */
+const DECLARED_LEVELS: ReadonlyMap<string, HeadingLevel> = new Map(
+  VOCABULARY.map((block) => [block.name, block.a11y.headingLevel]),
+)
+
+export type HeadingTag = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+
+/** The level a block's own title is rendered at, or `null` if it carries none. */
+export function blockHeadingTag(blockName: string): HeadingTag | null {
+  const level = DECLARED_LEVELS.get(blockName)
+  if (level === undefined || level === 'none') return null
+  return level
+}
+
+/**
+ * The level for a title *inside* a block — a feature's name, a listed entry.
+ *
+ * One below the block's own heading when the block renders one, and at the
+ * block's declared level when it does not: a `featureGrid` without a title must
+ * not start its items at `h3`, which would skip a level.
+ */
+export function nestedHeadingTag(blockName: string, blockRendersHeading: boolean): HeadingTag {
+  const own = blockHeadingTag(blockName) ?? 'h2'
+  if (!blockRendersHeading) return own
+  const next = Number(own.slice(1)) + 1
+  return `h${Math.min(next, 6)}` as HeadingTag
+}
+
+export function heading(
+  tag: HeadingTag,
+  attrs: Readonly<Record<string, string | number | boolean | undefined>>,
+  ...children: readonly Child[]
+): HtmlElement {
+  return h(tag, attrs, ...children)
+}

package/src/render/html.ts

@@ -0,0 +1,122 @@
+/**
+ * A minimal, dependency-free HTML tree and serialiser.
+ *
+ * Why the theme's markup is built here rather than written inline in the
+ * `.astro` files:
+ *
+ * 1. It is testable without an Astro toolchain — the twelve blocks get real
+ *    snapshot tests, and the heading outline and the `alt` rule get asserted on
+ *    the actual output rather than on a reading of the source.
+ * 2. There is **no way to emit raw HTML**. A block stores semantic data only
+ *    (rule R3); with no `raw()` escape hatch, a string that arrives in a block
+ *    field cannot become markup, whatever it contains.
+ *
+ * The `.astro` components in `src/blocks/` are the contract-D entry points and
+ * stay thin on purpose: one call each, so the two never drift.
+ */
+
+export type AttributeValue = string | number | boolean | undefined
+
+export type Attributes = Readonly<Record<string, AttributeValue>>
+
+export interface HtmlElement {
+  readonly kind: 'element'
+  readonly tag: string
+  readonly attrs: Attributes
+  readonly children: readonly HtmlNode[]
+}
+
+export interface HtmlText {
+  readonly kind: 'text'
+  readonly value: string
+}
+
+export type HtmlNode = HtmlElement | HtmlText
+
+/** Anything a caller may pass as a child. `null`/`false` drop out, so a
+ * conditional child reads as `condition && node` without a wrapper. */
+export type Child = HtmlNode | string | null | false | undefined | readonly Child[]
+
+/**
+ * Elements that carry no children and no closing tag. Serialising `<img>` with
+ * one would produce markup no parser agrees on.
+ */
+const VOID_ELEMENTS: ReadonlySet<string> = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'source',
+  'track',
+  'wbr',
+])
+
+export function text(value: string): HtmlText {
+  return { kind: 'text', value }
+}
+
+function flatten(children: readonly Child[], into: HtmlNode[]): void {
+  for (const child of children) {
+    if (child === null || child === false || child === undefined) continue
+    if (typeof child === 'string') {
+      into.push(text(child))
+      continue
+    }
+    if (Array.isArray(child)) {
+      flatten(child as readonly Child[], into)
+      continue
+    }
+    into.push(child as HtmlNode)
+  }
+}
+
+export function h(tag: string, attrs: Attributes = {}, ...children: readonly Child[]): HtmlElement {
+  const collected: HtmlNode[] = []
+  flatten(children, collected)
+  return { kind: 'element', tag, attrs, children: collected }
+}
+
+/**
+ * `&` first, or every following replacement would be escaped twice.
+ * `<` and `>` cover text; the quotes are escaped in attributes only, where they
+ * are the ones that can break out.
+ */
+export function escapeText(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+export function escapeAttribute(value: string): string {
+  return escapeText(value).replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+}
+
+function serializeAttributes(attrs: Attributes): string {
+  let out = ''
+  // Insertion order, not sorted: it is deterministic already, and an author
+  // reading a snapshot expects the order they wrote.
+  for (const [name, value] of Object.entries(attrs)) {
+    if (value === undefined || value === false) continue
+    if (value === true) {
+      out += ` ${name}`
+      continue
+    }
+    out += ` ${name}="${escapeAttribute(String(value))}"`
+  }
+  return out
+}
+
+export function serialize(node: HtmlNode): string {
+  if (node.kind === 'text') return escapeText(node.value)
+  const open = `<${node.tag}${serializeAttributes(node.attrs)}>`
+  if (VOID_ELEMENTS.has(node.tag)) return open
+  return `${open}${node.children.map(serialize).join('')}</${node.tag}>`
+}
+
+export function serializeAll(nodes: readonly HtmlNode[]): string {
+  return nodes.map(serialize).join('')
+}

package/src/render/media.ts

@@ -0,0 +1,62 @@
+import type { ImageOptions, MediaReference, RenderContext } from '../theme-contract.js'
+import { type HtmlElement, h } from './html.js'
+
+export interface ImageRenderOptions {
+  /** The `sizes` hint. Layout knowledge, so it belongs to the theme, not the block. */
+  readonly sizes?: string
+  /** `eager` only for what is above the fold — the hero, and nothing else. */
+  readonly loading?: 'lazy' | 'eager'
+  readonly className?: string
+  /**
+   * An accessible name the *block* provides — a logo's organisation name, for
+   * instance. It never invents alt text: it is used only where contract B says
+   * the block already carries the name.
+   */
+  readonly altFrom?: string
+  readonly variant?: ImageOptions
+}
+
+/**
+ * The only place the theme emits an `<img>`.
+ *
+ * `alt` is always written, never omitted: an image with no `alt` attribute is
+ * announced by its file name, while `alt=""` is announced as decorative. The
+ * difference is the whole of WCAG 1.1.1 here, and it cannot be left to whether
+ * a caller remembered.
+ *
+ * The alt text itself comes from the media entity through `ctx.image` — the
+ * theme has no business inventing one, and correcting it in the media library
+ * must fix every page at once.
+ */
+export function image(
+  ctx: RenderContext,
+  media: MediaReference,
+  options: ImageRenderOptions = {},
+): HtmlElement {
+  const source = ctx.image(media, options.variant)
+  return h('img', {
+    class: options.className,
+    src: source.src,
+    srcset: source.srcset === '' ? undefined : source.srcset,
+    sizes: options.sizes,
+    width: source.width,
+    height: source.height,
+    alt: source.alt !== '' ? source.alt : (options.altFrom ?? ''),
+    loading: options.loading ?? 'lazy',
+    decoding: 'async',
+    // The focal point is content data, not a style value: it says which part of
+    // the picture must survive a crop. Nothing else can carry it per-image.
+    style:
+      source.focal === null
+        ? undefined
+        : `object-position:${source.focal.x * 100}% ${source.focal.y * 100}%`,
+  })
+}
+
+/** Contract B's framing values, as a CSS `aspect-ratio`. `original` means none. */
+export function aspectRatio(ratio: string | undefined): string | undefined {
+  if (ratio === undefined || ratio === 'original') return undefined
+  const [width, height] = ratio.split(':')
+  if (width === undefined || height === undefined) return undefined
+  return `${width} / ${height}`
+}

package/src/render/render-block.ts

@@ -0,0 +1,97 @@
+import type { VocabularyBlock } from '@cogenta/blocks'
+import type { ContentEntry, RenderContext } from '../theme-contract.js'
+import { renderCollectionList } from './blocks/collection-list.js'
+import { renderCta } from './blocks/cta.js'
+import { renderEmbed } from './blocks/embed.js'
+import { renderFaq } from './blocks/faq.js'
+import { renderFeatureGrid } from './blocks/feature-grid.js'
+import { renderGallery } from './blocks/gallery.js'
+import { renderHero } from './blocks/hero.js'
+import { renderLogos } from './blocks/logos.js'
+import { renderMediaFigure } from './blocks/media-figure.js'
+import { renderProse } from './blocks/prose.js'
+import { renderQuote } from './blocks/quote.js'
+import { renderStats } from './blocks/stats.js'
+import { type HtmlElement, h } from './html.js'
+
+/**
+ * Entries already fetched for the `collectionList` blocks on the page, by the
+ * block's `_key`. Fetching happens in the Astro frontmatter, once per block,
+ * before any markup is built — a renderer that could await would make the
+ * number of round trips depend on the markup.
+ */
+export type FetchedEntries = Readonly<Record<string, readonly ContentEntry[]>>
+
+export function renderBlock(
+  block: VocabularyBlock,
+  ctx: RenderContext,
+  entries: FetchedEntries = {},
+): HtmlElement | null {
+  switch (block._type) {
+    case 'hero':
+      return renderHero(block, ctx)
+    case 'prose':
+      return renderProse(block, ctx)
+    case 'mediaFigure':
+      return renderMediaFigure(block, ctx)
+    case 'featureGrid':
+      return renderFeatureGrid(block, ctx)
+    case 'cta':
+      return renderCta(block, ctx)
+    case 'gallery':
+      return renderGallery(block, ctx)
+    case 'quote':
+      return renderQuote(block, ctx)
+    case 'faq':
+      return renderFaq(block, ctx)
+    case 'stats':
+      return renderStats(block, ctx)
+    case 'logos':
+      return renderLogos(block, ctx)
+    case 'collectionList':
+      return renderCollectionList(block, ctx, entries[block._key] ?? [])
+    case 'embed':
+      return renderEmbed(block, ctx)
+    default: {
+      // Exhaustive over contract B's twelve: `block` is `never` here, so a
+      // thirteenth block stops this package compiling until it is implemented.
+      // Returning null rather than throwing is deliberate — a theme has no
+      // access to `@cogenta/core`'s error types (contract D refuses the import),
+      // and choosing a fallback block is the render layer's job, not the
+      // theme's.
+      const unreachable: never = block
+      void unreachable
+      return null
+    }
+  }
+}
+
+export interface PageContent {
+  /** The entry's title. Rendered as the `h1` unless a hero already carries one. */
+  readonly title: string
+  readonly blocks: readonly VocabularyBlock[]
+}
+
+/**
+ * A page has exactly one `h1`.
+ *
+ * A `hero` declares `headingLevel: 'h1'` and renders the title itself, so the
+ * layout must not render a second one; without a hero, nothing else on the page
+ * would — `prose` starts at `h2` — and the page would have no `h1` at all.
+ */
+export function pageHasOwnHeading(blocks: readonly VocabularyBlock[]): boolean {
+  return blocks.some((block) => block._type === 'hero')
+}
+
+export function renderPage(
+  page: PageContent,
+  ctx: RenderContext,
+  entries: FetchedEntries = {},
+): HtmlElement {
+  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) => renderBlock(block, ctx, entries)),
+  )
+}

package/src/render/rich-text.ts

@@ -0,0 +1,150 @@
+import type { MarkDefinition, RichTextDocument, RichTextNode, Span } from '@cogenta/blocks'
+import type { RenderContext } from '../theme-contract.js'
+import { type HtmlNode, h, text } from './html.js'
+import { image } from './media.js'
+
+/**
+ * Rich text is a structured document, never HTML (contract A, ADR-0013). This
+ * is the whole of the theme's mapping from that document to markup.
+ *
+ * `h1` cannot occur — the vocabulary starts at `h2` — so the page keeps exactly
+ * one `h1` without this module having to defend against anything.
+ */
+
+type TextBlock = Extract<RichTextNode, { _type: 'block' }>
+
+const KNOWN_MARKS: ReadonlyMap<string, string> = new Map([
+  ['strong', 'strong'],
+  ['em', 'em'],
+  ['code', 'code'],
+])
+
+function applyMark(
+  ctx: RenderContext,
+  mark: string,
+  markDefs: readonly MarkDefinition[],
+  child: HtmlNode,
+): HtmlNode {
+  const tag = KNOWN_MARKS.get(mark)
+  if (tag !== undefined) return h(tag, {}, child)
+
+  const definition = markDefs.find((candidate) => candidate._key === mark)
+  if (definition === undefined) {
+    // An annotation this theme does not know stays text. Guessing markup for it
+    // is how a mark becomes an injection vector.
+    return child
+  }
+  if (definition._type === 'link') {
+    return h('a', { href: ctx.link(definition.href), rel: definition.rel }, child)
+  }
+  return h('a', { href: ctx.link({ collection: definition.collection, id: definition.id }) }, child)
+}
+
+function renderSpan(ctx: RenderContext, span: Span, markDefs: readonly MarkDefinition[]): HtmlNode {
+  let node: HtmlNode = text(span.text)
+  // Applied in reverse so the first mark ends up outermost, which keeps
+  // `['link', 'strong']` rendering as a link containing bold text.
+  for (const mark of [...span.marks].reverse()) {
+    node = applyMark(ctx, mark, markDefs, node)
+  }
+  return node
+}
+
+function renderChildren(ctx: RenderContext, block: TextBlock): readonly HtmlNode[] {
+  return block.children.map((span) => renderSpan(ctx, span, block.markDefs))
+}
+
+function isListItem(node: RichTextNode | undefined): node is TextBlock {
+  return node !== undefined && node._type === 'block' && node.listItem !== undefined
+}
+
+function levelOf(node: TextBlock): number {
+  return node.level ?? 1
+}
+
+/**
+ * Builds one list, and every list nested inside it, from a run of consecutive
+ * list items. A nested list lives *inside* the preceding `<li>` — putting it
+ * beside one produces a list whose items do not match what is announced.
+ */
+function buildList(
+  ctx: RenderContext,
+  nodes: RichTextDocument,
+  start: number,
+  level: number,
+): { readonly node: HtmlNode; readonly next: number } {
+  const first = nodes[start]
+  if (!isListItem(first)) return { node: text(''), next: start + 1 }
+  const kind = first.listItem
+  const items: HtmlNode[] = []
+  let index = start
+
+  while (index < nodes.length) {
+    const node = nodes[index]
+    if (!isListItem(node)) break
+    const nodeLevel = levelOf(node)
+    if (nodeLevel < level || node.listItem !== kind) break
+
+    if (nodeLevel > level) {
+      const nested = buildList(ctx, nodes, index, nodeLevel)
+      const last = items.pop()
+      items.push(
+        last === undefined || last.kind !== 'element'
+          ? h('li', {}, nested.node)
+          : h('li', last.attrs, ...last.children, nested.node),
+      )
+      index = nested.next
+      continue
+    }
+
+    items.push(h('li', {}, ...renderChildren(ctx, node)))
+    index += 1
+  }
+
+  return { node: h(kind === 'number' ? 'ol' : 'ul', {}, items), next: index }
+}
+
+function renderTextBlock(ctx: RenderContext, block: TextBlock): HtmlNode {
+  const children = renderChildren(ctx, block)
+  if (block.style === 'blockquote') return h('blockquote', {}, h('p', {}, ...children))
+  if (block.style === 'normal') return h('p', {}, ...children)
+  return h(block.style, {}, ...children)
+}
+
+export function renderRichText(
+  ctx: RenderContext,
+  document: RichTextDocument,
+): readonly HtmlNode[] {
+  const out: HtmlNode[] = []
+  let index = 0
+
+  while (index < document.length) {
+    const node = document[index]
+    if (node === undefined) break
+
+    if (isListItem(node)) {
+      const list = buildList(ctx, document, index, levelOf(node))
+      out.push(list.node)
+      index = list.next
+      continue
+    }
+
+    if (node._type === 'media') {
+      out.push(
+        h(
+          'figure',
+          { class: 'cg-prose__figure' },
+          image(ctx, node.id, { sizes: '(min-width: 45rem) 40rem, 100vw' }),
+          node.caption === undefined ? null : h('figcaption', {}, node.caption),
+        ),
+      )
+      index += 1
+      continue
+    }
+
+    out.push(renderTextBlock(ctx, node))
+    index += 1
+  }
+
+  return out
+}