@cogenta/theme-canonical 0.2.0 → 1.1.0

package/src/render/media.ts

@@ -1,62 +1,2 @@
-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}`
-}
+/** Re-exported from `@cogenta/theme-kit` — see that package's `media.ts`. */
+export { aspectRatio, type ImageRenderOptions, image } from '@cogenta/theme-kit'

package/src/render/render-block.ts

@@ -1,5 +1,15 @@
-import type { VocabularyBlock } from '@cogenta/blocks'
-import type { ContentEntry, RenderContext } from '../theme-contract.js'
+import { type BlockRegistry, VOCABULARY_NAMES, type VocabularyBlock } from '@cogenta/blocks'
+import {
+  type FetchedEntries,
+  type PageContent,
+  pageHasOwnHeading,
+  renderEntryHeader,
+  resolveBlockForRender,
+  withBlockKey,
+  withBlockVariant,
+} from '@cogenta/theme-kit'
+import type { RenderContext } from '../theme-contract.js'
+import { renderAccordion } from './blocks/accordion.js'
 import { renderCollectionList } from './blocks/collection-list.js'
 import { renderCta } from './blocks/cta.js'
 import { renderEmbed } from './blocks/embed.js'
@@ -7,124 +17,124 @@ 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 { renderLogoStrip } from './blocks/logo-strip.js'
 import { renderLogos } from './blocks/logos.js'
 import { renderMediaFigure } from './blocks/media-figure.js'
+import { renderPricingTable } from './blocks/pricing-table.js'
 import { renderProse } from './blocks/prose.js'
 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'
 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.
+ * `PageContent`/`FetchedEntries`/`pageHasOwnHeading`/`withBlockKey` are
+ * `@cogenta/theme-kit`'s own — re-exported here (rather than only imported)
+ * so this package's public surface still names them, exactly as it did
+ * before they moved to the package every theme now shares them from.
  */
-export type FetchedEntries = Readonly<Record<string, readonly ContentEntry[]>>
+export type { FetchedEntries, PageContent }
+export { pageHasOwnHeading, renderEntryHeader, withBlockKey }
 
 export function renderBlock(
   block: VocabularyBlock,
   ctx: RenderContext,
   entries: FetchedEntries = {},
+  registry?: BlockRegistry,
 ): HtmlElement | null {
-  switch (block._type) {
+  // `block`'s type says `VocabularyBlock`, but the value crossing this
+  // boundary from stored content is not always literally one of the twelve —
+  // `theme-render.ts` cannot know at compile time what a block zone holds.
+  // Resolving here, once, is what 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 as unknown as VocabularyBlock
+  // `withBlockVariant` (blocks@2.0, RFC 0002) is applied once here, after
+  // dispatch, rather than inside each of the seventeen block renderers —
+  // `variant` is envelope data every block carries identically, exactly the
+  // same reasoning `withBlockKey` in `renderPage` already follows for `_key`.
+  return withBlockVariant(renderKnownBlock(known, ctx, entries), known.variant)
+}
+
+function renderKnownBlock(
+  known: VocabularyBlock,
+  ctx: RenderContext,
+  entries: FetchedEntries,
+): HtmlElement | null {
+  switch (known._type) {
     case 'hero':
-      return renderHero(block, ctx)
+      return renderHero(known, ctx)
     case 'prose':
-      return renderProse(block, ctx)
+      return renderProse(known, ctx)
     case 'mediaFigure':
-      return renderMediaFigure(block, ctx)
+      return renderMediaFigure(known, ctx)
     case 'featureGrid':
-      return renderFeatureGrid(block, ctx)
+      return renderFeatureGrid(known, ctx)
     case 'cta':
-      return renderCta(block, ctx)
+      return renderCta(known, ctx)
     case 'gallery':
-      return renderGallery(block, ctx)
+      return renderGallery(known, ctx)
     case 'quote':
-      return renderQuote(block, ctx)
+      return renderQuote(known, ctx)
     case 'faq':
-      return renderFaq(block, ctx)
+      return renderFaq(known, ctx)
     case 'stats':
-      return renderStats(block, ctx)
+      return renderStats(known, ctx)
     case 'logos':
-      return renderLogos(block, ctx)
+      return renderLogos(known, ctx)
     case 'collectionList':
-      return renderCollectionList(block, ctx, entries[block._key] ?? [])
+      return renderCollectionList(known, ctx, entries[known._key] ?? [])
     case 'embed':
-      return renderEmbed(block, ctx)
+      return renderEmbed(known, ctx)
+    case 'testimonial':
+      return renderTestimonial(known, ctx)
+    case 'pricingTable':
+      return renderPricingTable(known, ctx)
+    case 'accordion':
+      return renderAccordion(known, ctx)
+    case 'statCounter':
+      return renderStatCounter(known, ctx)
+    case 'logoStrip':
+      return renderLogoStrip(known, ctx)
     default: {
-      // Exhaustive over contract B's twelve: `block` is `never` here, so a
-      // thirteenth block stops this package compiling until it is implemented.
+      // Exhaustive over contract B's vocabulary: `known` is `never` here, so a
+      // block this package does not implement stops it compiling until it is
+      // — every case above is either implemented directly, or the value was
+      // already resolved to something that is by `resolveBlockForRender`.
       // 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
+      const unreachable: never = known
       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')
-}
-
-/**
- * Stamps the block's own `_key` onto the element it rendered to.
- *
- * The key is contract B's identity for a placed block — minted once, surviving
- * reorder, translation and version restore — so it is the one honest way for a
- * *reader* of the finished HTML to say "this piece of the page came from that
- * block". The visual page builder (L16) is such a reader: it shows the real
- * server-rendered page in an iframe and needs to map a clicked element back to
- * the block that produced it.
- *
- * Emitted on every render, never only in a builder mode. A preview that is
- * assembled differently from the published page is exactly the divergence the
- * builder exists to rule out — one render path, one output, and the fidelity
- * test can then assert byte equality rather than "close enough".
- *
- * It stays a data attribute and it stays out of the block renderers: no block
- * has to remember it, and nothing about layout or styling depends on it.
- *
- * Its companion is `data-field`, written by the block renderers themselves on
- * the single element that carries one plain-text field's whole value —
- * `hero`'s title, `quote`'s author, and so on. A field only earns the
- * attribute when it already had an element of its own: none of them changed
- * shape to get it, so the outline, the styling and the snapshots are the same
- * page they were, with one more attribute on some elements. Rich text and
- * repeated list items carry none, which is the honest answer — a builder
- * cannot edit them in place from a text node, and pretending otherwise would
- * be the divergence all of this exists to avoid.
- */
-function withBlockKey(element: HtmlElement | null, key: string): HtmlElement | null {
-  if (element === null) return null
-  return { ...element, attrs: { ...element.attrs, 'data-block-key': key } }
-}
-
 export function renderPage(
   page: PageContent,
   ctx: RenderContext,
   entries: FetchedEntries = {},
+  registry?: BlockRegistry,
 ): HtmlElement {
+  // `theme@1.4` (L25 D2): `renderEntryHeader` already returns `null` for a
+  // page with no `entry` meta *and* for one whose blocks already draw their
+  // own heading (a `hero`), so the bare `<h1 class="cg-page__title">`
+  // fallback below is the right markup in both of those cases and only
+  // those — never a double heading, and never a page with none at all.
+  const entryHeader = renderEntryHeader(page, ctx)
   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), block._key)),
+    entryHeader,
+    entryHeader === null && !pageHasOwnHeading(page.blocks)
+      ? h('h1', { class: 'cg-page__title' }, page.title)
+      : null,
+    page.blocks.map((block) =>
+      withBlockKey(renderBlock(block, ctx, entries, registry), block._key),
+    ),
   )
 }

package/src/render/rich-text.ts

@@ -1,150 +1,2 @@
-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
-}
+/** Re-exported from `@cogenta/theme-kit` — see that package's `rich-text.ts`. */
+export { renderRichText } from '@cogenta/theme-kit'

package/src/render/term-archive.ts

@@ -0,0 +1,85 @@
+import { type HtmlElement, h, type TermArchiveInput } from '@cogenta/theme-kit'
+
+/**
+ * The taxonomy-term archive (contract D `theme@1.3`).
+ *
+ * Built from this theme's *own* entry-card classes — the same `cg-entry`
+ * markup `collectionList` already renders — rather than a new set of
+ * archive-only classes: an archive of articles should look like a list of
+ * articles on this theme, and reusing the classes is what guarantees that
+ * without a second stylesheet to keep in step.
+ */
+export function renderTermArchive(input: TermArchiveInput): HtmlElement {
+  const items = input.entries.map((entry) =>
+    h(
+      'li',
+      { class: 'cg-entry' },
+      h(
+        'div',
+        { class: 'cg-entry__body' },
+        h(
+          'h2',
+          { class: 'cg-entry__title' },
+          entry.href === null
+            ? entry.title
+            : h('a', { class: 'cg-entry__link', href: entry.href }, entry.title),
+        ),
+        entry.publishedAt === null
+          ? null
+          : h(
+              'time',
+              { class: 'cg-entry__date', datetime: entry.publishedAt },
+              entry.publishedAt.slice(0, 10),
+            ),
+        entry.summary === null ? null : h('p', { class: 'cg-entry__excerpt' }, entry.summary),
+      ),
+    ),
+  )
+
+  return h(
+    'main',
+    { class: 'cg-main cg-archive', id: 'cg-main' },
+    input.ancestors.length === 0
+      ? null
+      : h(
+          'nav',
+          { class: 'cg-archive__breadcrumb', 'aria-label': input.labels.breadcrumb },
+          h(
+            'ol',
+            {},
+            ...input.ancestors.map((link) => h('li', {}, h('a', { href: link.href }, link.label))),
+          ),
+        ),
+    h('h1', { class: 'cg-page__title' }, input.term.label),
+    input.children.length === 0
+      ? null
+      : h(
+          'ul',
+          { class: 'cg-archive__children', 'aria-label': input.labels.subterms },
+          ...input.children.map((child) => h('li', {}, h('a', { href: child.href }, child.label))),
+        ),
+    items.length === 0
+      ? h('p', { class: 'cg-collection__empty' }, input.labels.empty)
+      : h('ul', { class: 'cg-collection__items' }, ...items),
+    renderPager(input),
+  )
+}
+
+/**
+ * Previous/next only — never a numbered pager. This renderer is handed the
+ * two hrefs the host resolved and no page-number list, so inventing one here
+ * would mean guessing URLs the host never said were valid.
+ */
+function renderPager(input: TermArchiveInput): HtmlElement | null {
+  if (input.page.previousHref === null && input.page.nextHref === null) return null
+  return h(
+    'nav',
+    { class: 'cg-archive__pager', 'aria-label': input.labels.pagination },
+    input.page.previousHref === null
+      ? null
+      : h('a', { rel: 'prev', href: input.page.previousHref }, input.labels.previous),
+    input.page.nextHref === null
+      ? null
+      : h('a', { rel: 'next', href: input.page.nextHref }, input.labels.next),
+  )
+}

package/src/styles/archive.css

@@ -0,0 +1,40 @@
+/*
+ * The taxonomy-term archive (contract D `theme@1.3`).
+ *
+ * Only the three things an archive adds beyond what `collectionList` already
+ * styles — a breadcrumb, a sub-term row, a prev/next pager. The entry list
+ * itself reuses the `cg-entry`/`cg-collection__items` rules, on purpose: an
+ * archive of articles must look like this theme's list of articles, and a
+ * second set of card rules is exactly how those two drift apart.
+ */
+
+.cg-archive {
+  max-inline-size: var(--cg-page);
+  margin-inline: auto;
+  padding: var(--cg-s10) var(--cg-gutter);
+}
+
+.cg-archive__breadcrumb ol,
+.cg-archive__children {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--cg-s3);
+  margin: 0 0 var(--cg-s4);
+  padding: 0;
+  list-style: none;
+  font-size: var(--cg-text-sm);
+}
+
+.cg-archive__children {
+  margin-block: var(--cg-s4) var(--cg-s8);
+}
+
+.cg-archive__pager {
+  display: flex;
+  justify-content: space-between;
+  gap: var(--cg-s4);
+  margin-block-start: var(--cg-s10);
+  padding-block-start: var(--cg-s5);
+  border-block-start: 1px solid var(--cg-line-soft);
+  font-weight: var(--cg-weight-semibold);
+}