@cogenta/theme-association 0.3.3 → 0.5.4

package/src/render/figures.ts

@@ -0,0 +1,68 @@
+/**
+ * Two readings of plain text a charity writes all the time, recognised from
+ * the words themselves rather than from a setting contract B does not have.
+ *
+ * - **A breakdown.** Figures that are all percentages and add up to a whole
+ *   (95 to 105, for rounding) say where the money goes: they are drawn as
+ *   shares of one total, with a bar each, instead of four unrelated numbers.
+ * - **What a gift pays for.** A call to action whose sentences start with an
+ *   amount of money ("£12 buys a week of fresh vegetables for one family.")
+ *   lists those amounts large beside what they pay for. Any other text stays
+ *   the paragraph it was written as.
+ */
+
+export function shareOf(value: string, unit: string | undefined): number | undefined {
+  const joined = unit === undefined ? value.trim() : `${value.trim()}${unit.trim()}`
+  const match = /^(\d{1,3}(?:[.,]\d+)?)\s*%$/.exec(joined)
+  if (match === null) return undefined
+  const share = Number.parseFloat((match[1] as string).replace(',', '.'))
+  return share >= 0 && share <= 100 ? share : undefined
+}
+
+export function isBreakdown(
+  items: readonly { readonly value: string; readonly unit?: string | undefined }[],
+): boolean {
+  if (items.length < 2) return false
+  const shares = items.map((item) => shareOf(item.value, item.unit))
+  if (shares.some((share) => share === undefined)) return false
+  const total = (shares as number[]).reduce((sum, share) => sum + share, 0)
+  return total >= 95 && total <= 105
+}
+
+export interface Gift {
+  readonly amount: string
+  readonly text: string
+}
+
+export interface GiftList {
+  readonly lead: string | undefined
+  readonly gifts: readonly Gift[]
+  readonly tail: string | undefined
+}
+
+const GIFT = /^([£€$]\s?\d[\d,.]*(?:\s(?:a|per|each)\s(?:week|month|year))?)\s+(\S[\s\S]*)$/u
+
+/** The sentences of `text` that start with an amount, or `undefined` when fewer than two do. */
+export function giftsOf(text: string | undefined): GiftList | undefined {
+  if (text === undefined) return undefined
+  const sentences = text
+    .trim()
+    .split(/(?<=[.;])\s+/)
+    .filter((sentence) => sentence !== '')
+  const first = sentences.findIndex((sentence) => GIFT.test(sentence))
+  if (first === -1) return undefined
+  let last = first
+  while (last + 1 < sentences.length && GIFT.test(sentences[last + 1] as string)) last += 1
+  const gifts = sentences.slice(first, last + 1).map((sentence) => {
+    const match = GIFT.exec(sentence) as RegExpExecArray
+    return { amount: match[1] as string, text: match[2] as string }
+  })
+  if (gifts.length < 2) return undefined
+  const lead = sentences.slice(0, first).join(' ')
+  const tail = sentences.slice(last + 1).join(' ')
+  return {
+    lead: lead === '' ? undefined : lead,
+    gifts,
+    tail: tail === '' ? undefined : tail,
+  }
+}

package/src/render/layout.ts

@@ -0,0 +1,78 @@
+import {
+  type Attributes,
+  blockHeadingTag,
+  type Child,
+  type HtmlElement,
+  h,
+  heading,
+} from '@cogenta/theme-kit'
+
+/**
+ * The frame every block of this theme renders into.
+ *
+ * The outer element carries the one section rhythm (`--ca-section`, the same
+ * for every block) and paints edge to edge when a block is a band. The inner
+ * element is the twelve-column container, so a section title, a figure, a
+ * date and a caption all start on the same line.
+ *
+ * `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: 'section' | 'div',
+  block: string,
+  className: string,
+  attrs: Attributes,
+  inner: 'div' | 'figure',
+  ...children: readonly Child[]
+): HtmlElement {
+  return h(
+    outer,
+    { class: `ca-section ${className}`, 'data-block': block, ...attrs },
+    h(inner, { class: `ca-container ${className}__inner` }, ...children),
+  )
+}
+
+/**
+ * A titled block's heading, in the display face at the section size, on the
+ * first column of the grid. `null` for an untitled block: no empty heading.
+ */
+export function sectionHead(blockName: string, title: string | undefined): HtmlElement | null {
+  if (title === undefined) return null
+  return h(
+    'div',
+    { class: 'ca-head' },
+    heading(
+      blockHeadingTag(blockName) ?? 'h2',
+      { class: 'ca-head__title', 'data-field': 'title' },
+      title,
+    ),
+  )
+}
+
+/**
+ * The words of an arrow link, with the last word wrapped in a span that
+ * cannot break and that carries the arrow (`::after`, drawn by the
+ * stylesheet). A line can then break between words but never between the
+ * last word and its arrow, so an arrow is never left alone at the start of a
+ * line, and the words keep one continuous underline: the arrow is an atomic
+ * inline, which a text decoration does not reach.
+ */
+export function arrowWords(text: string): Child[] {
+  const trimmed = text.trim()
+  const at = trimmed.lastIndexOf(' ')
+  const end = h('span', { class: 'ca-arrow-link__end' }, trimmed.slice(at + 1))
+  return at === -1 ? [end] : [trimmed.slice(0, at + 1), end]
+}
+
+/** A paragraph that renders only when the text is there: no empty `<p>` on the page. */
+export function optionalText(
+  tag: string,
+  className: string,
+  value: string | undefined,
+  attrs: Attributes = {},
+): HtmlElement | null {
+  if (value === undefined || value.trim() === '') return null
+  return h(tag, { class: className, ...attrs }, value)
+}

package/src/render/page-head.ts

@@ -0,0 +1,193 @@
+import {
+  type HtmlElement,
+  h,
+  type PageContent,
+  type PageEntryMeta,
+  type RenderContext,
+  renderImageSource,
+} from '@cogenta/theme-kit'
+import { eventTimeOf, factsOf, renderDateBlock, renderFacts } from './details.js'
+import { associationString } from './strings.js'
+
+/**
+ * The opening of every page that has no hero. Three kinds, and exactly one
+ * `h1` in each:
+ *
+ * - **An event** (its `theme@1.5` fields carry a date): the date block large
+ *   on the first three columns, the way a noticeboard poster leads with the
+ *   day; the title, the summary and the practical details (when, where, what
+ *   it costs, whether to book) on the rest; the photograph under them across
+ *   the container.
+ * - **An entry with details or a photograph** (a programme, a story): the
+ *   title, the summary and the details on the first seven columns; a portrait
+ *   photograph beside them on the last four, a landscape one under them.
+ * - **Anything else** (about, donate, a privacy notice): the title large on
+ *   the grid, and the summary under it when there is one.
+ *
+ * A host older than `theme@1.5` sends no fields, so its event pages open like
+ * any other entry: title, summary and photograph, never a date read from
+ * somewhere it was not given. A host older than `theme@1.4` sends no entry at
+ * all, and the page opens on its bare title.
+ */
+
+function formatDate(iso: string, locale: string): string {
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(
+      new Date(iso),
+    )
+  } catch {
+    return iso
+  }
+}
+
+/** Date, author and reading time, for an entry that has a publication date. */
+function meta(entry: PageEntryMeta, ctx: RenderContext): HtmlElement | null {
+  if (entry.publishedAt === undefined) return null
+  return h(
+    'p',
+    { class: 'ca-page-head__meta' },
+    h('time', { datetime: entry.publishedAt }, formatDate(entry.publishedAt, ctx.locale)),
+    entry.author === undefined ? null : h('span', {}, entry.author.name),
+    entry.readingMinutes === undefined
+      ? null
+      : h('span', {}, ctx.t('entry.readingTime', { minutes: entry.readingMinutes })),
+  )
+}
+
+function terms(entry: PageEntryMeta): HtmlElement | null {
+  if (entry.terms === undefined || entry.terms.length === 0) return null
+  return h(
+    'ul',
+    { class: 'ca-page-head__terms' },
+    entry.terms.map((term) =>
+      h('li', {}, term.href === null ? term.label : h('a', { href: term.href }, term.label)),
+    ),
+  )
+}
+
+function details(entry: PageEntryMeta, ctx: RenderContext, className: string): HtmlElement | null {
+  const facts = renderFacts(factsOf(entry.fields ?? {}, ctx.locale), 'ca-facts')
+  if (facts === null) return null
+  return h(
+    'div',
+    { class: className },
+    h('h2', { class: 'cg-visually-hidden' }, associationString(ctx.locale, 'details')),
+    facts,
+  )
+}
+
+function renderEventHead(
+  page: PageContent,
+  entry: PageEntryMeta,
+  ctx: RenderContext,
+): HtmlElement | null {
+  const time = eventTimeOf(entry.fields)
+  if (time === undefined) return null
+  return h(
+    'header',
+    { class: 'ca-event', 'data-cover': String(entry.image !== undefined) },
+    h(
+      'div',
+      { class: 'ca-container ca-event__inner' },
+      h(
+        'div',
+        { class: 'ca-event__date' },
+        renderDateBlock(time, ctx.locale, 'ca-when', { year: true }),
+      ),
+      h(
+        'div',
+        { class: 'ca-event__heading' },
+        terms(entry),
+        h('h1', { class: 'ca-event__title' }, page.title),
+        entry.excerpt === undefined ? null : h('p', { class: 'ca-event__lead' }, entry.excerpt),
+      ),
+      details(entry, ctx, 'ca-event__details'),
+      entry.image === undefined
+        ? null
+        : h(
+            'figure',
+            { class: 'ca-event__cover' },
+            renderImageSource(entry.image, {
+              className: 'ca-event__image',
+              loading: 'eager',
+              sizes: '(min-width: 82rem) 78rem, 100vw',
+            }),
+          ),
+    ),
+  )
+}
+
+function renderEntryHead(
+  page: PageContent,
+  entry: PageEntryMeta,
+  ctx: RenderContext,
+): HtmlElement | null {
+  const facts = details(entry, ctx, 'ca-entry__details')
+  const cover = entry.image
+  if (facts === null && cover === undefined) return null
+  const orientation =
+    cover === undefined ? 'none' : cover.height > cover.width ? 'portrait' : 'landscape'
+  return h(
+    'header',
+    { class: 'ca-entry', 'data-cover': orientation },
+    h(
+      'div',
+      { class: 'ca-container ca-entry__inner' },
+      h(
+        'div',
+        { class: 'ca-entry__heading' },
+        terms(entry),
+        h('h1', { class: 'ca-entry__title' }, page.title),
+        entry.excerpt === undefined ? null : h('p', { class: 'ca-entry__lead' }, entry.excerpt),
+        meta(entry, ctx),
+        facts,
+      ),
+      cover === undefined
+        ? null
+        : h(
+            'figure',
+            { class: 'ca-entry__cover' },
+            renderImageSource(cover, {
+              className: 'ca-entry__image',
+              loading: 'eager',
+              sizes:
+                orientation === 'portrait'
+                  ? '(min-width: 64rem) 30vw, 100vw'
+                  : '(min-width: 82rem) 78rem, 100vw',
+            }),
+          ),
+    ),
+  )
+}
+
+function renderPlainHead(page: PageContent, ctx: RenderContext): HtmlElement {
+  const entry = page.entry
+  return h(
+    'header',
+    { class: 'ca-page-head' },
+    h(
+      'div',
+      { class: 'ca-container ca-page-head__inner' },
+      entry === undefined ? null : terms(entry),
+      h('h1', { class: 'ca-page-head__title' }, page.title),
+      entry?.excerpt === undefined ? null : h('p', { class: 'ca-page-head__lead' }, entry.excerpt),
+      entry === undefined ? null : meta(entry, ctx),
+    ),
+  )
+}
+
+export type PageHeadKind = 'event' | 'entry' | 'page'
+
+export function renderPageHead(
+  page: PageContent,
+  ctx: RenderContext,
+): { readonly kind: PageHeadKind; readonly node: HtmlElement } {
+  const entry = page.entry
+  if (entry !== undefined) {
+    const eventHead = renderEventHead(page, entry, ctx)
+    if (eventHead !== null) return { kind: 'event', node: eventHead }
+    const entryHead = renderEntryHead(page, entry, ctx)
+    if (entryHead !== null) return { kind: 'entry', node: entryHead }
+  }
+  return { kind: 'page', node: renderPlainHead(page, ctx) }
+}

package/src/render/render-block.ts

@@ -5,8 +5,8 @@ import {
   h,
   type PageContent,
   pageHasOwnHeading,
+  providedBlockNode,
   type RenderContext,
-  renderEntryHeader,
   resolveBlockForRender,
   withBlockKey,
   withBlockVariant,
@@ -28,9 +28,9 @@ 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 { renderPageHead } from './page-head.js'
 
 export type { FetchedEntries, PageContent }
-export { pageHasOwnHeading, renderEntryHeader, withBlockKey }
 
 export function renderBlock(
   block: VocabularyBlock,
@@ -38,16 +38,19 @@ export function renderBlock(
   entries: FetchedEntries = {},
   registry?: BlockRegistry,
 ): HtmlElement | null {
-  // `block`'s type says `VocabularyBlock`, but the value crossing this
-  // boundary from stored content is not always literally one of the shared
-  // vocabulary — resolving here is what turns an unimplemented theme-private
-  // block into its declared fallback instead of a silently blank slot.
+  // 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)
+  // 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 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.
+  // `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), known.variant)
 }
 
@@ -92,12 +95,9 @@ function renderKnownBlock(
     case 'logoStrip':
       return renderLogoStrip(known, ctx)
     default: {
-      // Exhaustive over contract B's vocabulary: `known` is `never` here, so
-      // a block this package does not implement stops it compiling until it
-      // is. 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.
+      // 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: never = known
       void unreachable
       return null
@@ -106,18 +106,26 @@ function renderKnownBlock(
 }
 
 /**
- * `<main id="cg-main">` is mandatory: it is the skip-link's target, written
- * once by `@cogenta/cli`'s `theme-render.ts` outside any theme's control.
+ * A real `id` beside `withBlockKey`'s `data-block-key`, so a link to
+ * `/donate#<key>` has somewhere to land. Contract B's `_key` is unique within
+ * one page's block list, so it can never collide on a page this theme
+ * rendered.
+ */
+function withAnchorId(element: HtmlElement | null, key: string): HtmlElement | null {
+  if (element === null) return null
+  return { ...element, attrs: { ...element.attrs, id: key } }
+}
+
+/**
+ * `<main id="cg-main">` is mandatory: it is the skip link's target, written
+ * by the host outside any theme's control.
  *
- * `theme@1.4` (L25 D2): `renderEntryHeader` returns `null` both for a page
- * with no `entry` meta and for one whose blocks already draw their own
- * heading (a `hero`) — the bare `<h1 class="cg-page__title">` fallback below
- * is the right markup in both of those cases and only those, so the page
- * always carries exactly one `<h1>`.
+ * A page whose blocks include a `hero` lets the hero carry the title; any
+ * other page opens on `renderPageHead` (an event, an entry with details, or
+ * a plain title), so every page has exactly one `h1`.
  *
- * `withBlockKey` stamps every rendered block with its contract-B `_key` —
- * required so the visual page builder (L16) can map a clicked element in the
- * rendered iframe back to the block that produced it.
+ * `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: PageContent,
@@ -125,16 +133,21 @@ export function renderPage(
   entries: FetchedEntries = {},
   registry?: BlockRegistry,
 ): HtmlElement {
-  const entryHeader = renderEntryHeader(page, ctx)
+  const head = pageHasOwnHeading(page.blocks) ? null : renderPageHead(page, ctx)
+
   return h(
     'main',
-    { class: 'cg-main', id: 'cg-main' },
-    entryHeader,
-    entryHeader === null && !pageHasOwnHeading(page.blocks)
-      ? h('h1', { class: 'cg-page__title' }, page.title)
-      : null,
+    {
+      class: 'cg-main ca-main',
+      id: 'cg-main',
+      'data-opening': head === null ? 'hero' : head.kind,
+    },
+    head?.node ?? null,
     page.blocks.map((block) =>
-      withBlockKey(renderBlock(block, ctx, entries, registry), block._key),
+      withAnchorId(
+        withBlockKey(renderBlock(block, ctx, entries, registry), block._key),
+        block._key,
+      ),
     ),
   )
 }

package/src/render/strings.ts

@@ -0,0 +1,74 @@
+import { interpolate, themeLocaleFor } from '@cogenta/theme-kit'
+
+/**
+ * The few words a charity's own pages need that the shared vocabulary does
+ * not: the labels of an event's or a programme's details, the menu button,
+ * and the joining words of a time range.
+ *
+ * `@cogenta/theme-kit`'s `THEME_STRINGS` carries the strings every theme's
+ * blocks share; these belong to one register, so they live with the theme
+ * that draws them, in the two languages the shared table knows. A locale the
+ * table does not know reads English, the same rule `createThemeTranslator`
+ * follows.
+ */
+
+type AssociationStringKey =
+  | 'when'
+  | 'where'
+  | 'address'
+  | 'cost'
+  | 'booking'
+  | 'audience'
+  | 'contact'
+  | 'details'
+  | 'timeRange'
+  | 'menu'
+  | 'close'
+  | 'primaryNav'
+  | 'footerNav'
+  | 'share'
+
+const STRINGS: Readonly<Record<'en' | 'fr', Readonly<Record<AssociationStringKey, string>>>> = {
+  en: {
+    when: 'When',
+    where: 'Where',
+    address: 'Address',
+    cost: 'Cost',
+    booking: 'Booking',
+    audience: 'Who it is for',
+    contact: 'Contact',
+    details: 'Details',
+    timeRange: '{{start}} to {{end}}',
+    menu: 'Menu',
+    close: 'Close',
+    primaryNav: 'Primary',
+    footerNav: 'Footer',
+    share: 'Share of the total',
+  },
+  fr: {
+    when: 'Quand',
+    where: 'Où',
+    address: 'Adresse',
+    cost: 'Tarif',
+    booking: 'Inscription',
+    audience: 'Pour qui',
+    contact: 'Contact',
+    details: 'Informations pratiques',
+    timeRange: 'de {{start}} à {{end}}',
+    menu: 'Menu',
+    close: 'Fermer',
+    primaryNav: 'Navigation principale',
+    footerNav: 'Pied de page',
+    share: 'Part du total',
+  },
+}
+
+export function associationString(
+  locale: string,
+  key: AssociationStringKey,
+  values?: Readonly<Record<string, string | number>>,
+): string {
+  return interpolate(STRINGS[themeLocaleFor(locale)][key], values)
+}
+
+export type { AssociationStringKey }