@cogenta/theme-portfolio 1.1.2 → 1.3.3

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

@@ -1,49 +1,31 @@
 import type { StatCounterBlock, StatCounterItem } from '@cogenta/blocks'
-import {
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  type RenderContext,
-} from '@cogenta/theme-kit'
+import { type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+import { section, sectionHead } from '../layout.js'
 
 /**
- * Narrower than `stats` (no `unit`, RFC 0001's own reasoning), so this is not
- * `stats.ts`'s description list of labelled figures again with a field
- * dropped — it is set as a single running strip of oversized digits
- * separated by hairlines, the way a spec sheet's headline numbers run across
- * a masthead, each with its own zero-padded index the way `logos.ts` numbers
- * its marks. `stats.ts` stays the fuller, boxed "by the numbers" panel.
+ * A ruled table of figures from the fourth column, one row per figure: what
+ * it counts on the left in the text face, the value on the right in the
+ * display width with tabular numerals, so a column of numbers lines up.
+ * Where `stats` sets figures side by side, this sets them as a list read
+ * down the page. It carries no unit, the narrower shape contract B gives it.
  */
-function renderItem(item: StatCounterItem, index: number): HtmlElement {
+function renderItem(item: StatCounterItem): HtmlElement {
   return h(
-    'li',
-    { class: 'cg-counter__item' },
-    h(
-      'span',
-      { class: 'cg-counter__index', 'aria-hidden': 'true' },
-      String(index + 1).padStart(2, '0'),
-    ),
-    h('span', { class: 'cg-counter__value' }, item.value),
-    h('span', { class: 'cg-counter__label' }, item.label),
+    'div',
+    { class: 'cg-tally__row' },
+    h('dt', { class: 'cg-tally__label' }, item.label),
+    h('dd', { class: 'cg-tally__value' }, item.value),
   )
 }
 
 export function renderStatCounter(block: StatCounterBlock, _ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     'section',
-    { class: 'cg-block cg-counter', 'data-block': 'statCounter' },
-    block.title === undefined
-      ? null
-      : heading(
-          blockHeadingTag('statCounter') ?? 'h2',
-          { class: 'cg-counter__title', 'data-field': 'title' },
-          block.title,
-        ),
-    h(
-      'ul',
-      { class: 'cg-counter__items' },
-      block.stats.map((item, index) => renderItem(item, index)),
-    ),
+    'statCounter',
+    'cg-tally cg-split',
+    { 'data-titled': block.title === undefined ? 'false' : 'true' },
+    'div',
+    sectionHead('statCounter', block.title),
+    h('dl', { class: 'cg-tally__rows' }, block.stats.map(renderItem)),
   )
 }

package/src/render/blocks/stats.ts

@@ -1,49 +1,34 @@
 import type { StatItem, StatsBlock } from '@cogenta/blocks'
-import {
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  type RenderContext,
-} from '@cogenta/theme-kit'
+import { type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+import { section, sectionHead } from '../layout.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.
- *
- * Figures are set at the theme's biggest display scale and in tabular mono
- * numerals — a portfolio's "by the numbers" row reads like a spec sheet,
- * not a dashboard widget.
+ * Figures side by side, the way a studio states its record: each figure very
+ * large in the display width with tabular numerals, its unit after it at the
+ * text size, and what it counts under it, a hairline over every column.
  */
 function renderItem(item: StatItem): HtmlElement {
   return h(
     'div',
-    { class: 'cg-stat' },
-    h('dt', { class: 'cg-stat__label' }, item.label),
+    { class: 'cg-figures__item' },
     h(
-      'dd',
-      { class: 'cg-stat__value' },
-      item.value,
-      item.unit === undefined ? null : h('span', { class: 'cg-stat__unit' }, item.unit),
+      'dt',
+      { class: 'cg-figures__figure' },
+      h('span', { class: 'cg-figures__value' }, item.value),
+      item.unit === undefined ? null : h('span', { class: 'cg-figures__unit' }, item.unit),
     ),
+    h('dd', { class: 'cg-figures__label' }, item.label),
   )
 }
 
 export function renderStats(block: StatsBlock, _ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     '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)),
+    'stats',
+    'cg-figures',
+    { 'data-count': String(Math.min(block.items.length, 4)) },
+    'div',
+    sectionHead('stats', block.title),
+    h('dl', { class: 'cg-figures__items' }, block.items.map(renderItem)),
   )
 }

package/src/render/blocks/testimonial.ts

@@ -1,44 +1,38 @@
 import type { TestimonialBlock } from '@cogenta/blocks'
 import { type HtmlElement, h, image, type RenderContext, renderRichText } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * Distinct from `quote` on purpose (RFC 0001): `quote` is this theme's full-
- * bleed pull quote, set left-aligned at display scale with no frame. A wall
- * of testimonials needs to sit several-up without each one reading as a
- * headline, so this is a bordered card instead — the same "cut paper"
- * language `feature-grid.ts` uses for its items, at a quieter type scale.
- *
- * `attribution` arrives as one grouped field (RFC 0001's own reasoning for
- * shaping it that way), so its `name`/`role` are not marked `data-field`:
- * that attribute is reserved for a plain-text field the block schema
- * declares at the top level, and neither of these is one — only `attribution`
- * itself is, and it is not plain text.
- *
- * The avatar is decorative, exactly like `quote.ts`'s own — the name sits
- * right beside it in text, so its media entity's alt text is expected empty.
+ * A longer word from a client, quieter than `quote`: the words at the lead
+ * size from the fourth column, a hairline above them, and the client under
+ * them with their role. Where `quote` is a line set large, a testimonial is a
+ * paragraph meant to be read.
  */
 export function renderTestimonial(block: TestimonialBlock, ctx: RenderContext): HtmlElement {
   const { attribution } = block
-  return h(
+  return section(
+    'div',
+    'testimonial',
+    'cg-word',
+    {},
     'figure',
-    { class: 'cg-block cg-testimonial', 'data-block': 'testimonial' },
-    h('blockquote', { class: 'cg-testimonial__quote' }, renderRichText(ctx, block.quote)),
+    h('blockquote', { class: 'cg-word__quote' }, renderRichText(ctx, block.quote)),
     h(
       'figcaption',
-      { class: 'cg-testimonial__attribution' },
+      { class: 'cg-word__attribution' },
       attribution.avatar === undefined
         ? null
         : image(ctx, attribution.avatar, {
-            className: 'cg-testimonial__avatar',
+            className: 'cg-word__avatar',
             variant: { width: 96, height: 96, fit: 'cover' },
           }),
       h(
         'span',
-        { class: 'cg-testimonial__names' },
-        h('span', { class: 'cg-testimonial__name' }, attribution.name),
+        { class: 'cg-word__who' },
+        h('span', { class: 'cg-word__name' }, attribution.name),
         attribution.role === undefined
           ? null
-          : h('span', { class: 'cg-testimonial__role' }, attribution.role),
+          : h('span', { class: 'cg-word__role' }, attribution.role),
       ),
     ),
   )

package/src/render/chrome.ts

@@ -5,138 +5,140 @@ import {
   escapeAttribute,
   escapeText,
   renderBrandMark,
+  renderFooterWidgets,
   renderSocialLinks,
   renderThemeToggle,
   serialize,
 } from '@cogenta/theme-kit'
 
 /**
- * The chrome this theme ships (`theme@1.4`): a thin, sticky index bar up
- * top — the site name treated as a typographic mark rather than a logo
- * slot, a running index number, a real desktop `<nav>`, `headerAction`
- * (`"Let's talk"`, a flat filled button) and a CSS-only mobile menu — and a
- * footer that becomes a second headline: the site name set at display
- * scale, repeated as a closing statement, the `tagline` beneath it, then a
- * real row of footer navigation, social icons (`renderSocialLinks`) and the
- * `footerNote` beside the branding fragment.
+ * The header and the footer (`theme@1.4`), as quiet as a studio's own.
  *
- * The mobile menu is the same checkbox/label trick every L25 theme uses —
- * a visually-hidden `<input type="checkbox">` paired with a `<label>`
- * styled as a three-bar button; `base.css`'s sibling combinator is what
- * reveals the panel when the box is checked, so there is exactly one real
- * `<nav>` in the markup (the same one desktop and mobile both use, retiled
- * by CSS at the breakpoint), never two copies of the same links.
+ * Header, one row on the twelve columns: the studio's name on the left (or
+ * its uploaded logo), the `tagline` in the middle columns on a wide screen,
+ * the navigation on the right with the `headerAction` as its last link, and
+ * the light/dark control. No bar, no button, no sticky shadow. Below the
+ * breakpoint the navigation becomes a full-height panel of large links opened
+ * by a CSS-only toggle: a visually hidden checkbox paired with a `<label>`,
+ * placed before the `<nav>` so the sibling combinator in `base.css` reaches
+ * it. There is exactly one `<nav>` in the markup, retiled by CSS.
  *
- * Both fragments are built with the same string-escaping discipline
- * `theme-kit`'s own reference chrome uses (`escapeText`/`escapeAttribute`) —
- * `headerNav`/`footerNav` arrive pre-resolved and are rendered as given,
- * never invented or dropped, and `brandingHtml` is placed, never altered.
- * Every `theme@1.4` field (`tagline`/`social`/`footerNote`/`headerAction`)
- * is optional and additive: a host or a site that never sets one gets
- * exactly the `1.3` markup in that spot, byte for byte (`chrome.test.ts`'s
- * "without the new fields" cases).
- *
- * The manual light/dark/system toggle (`renderThemeToggle`, `@cogenta/
- * theme-kit`, L26) is unconditional — every render carries it, `theme@1.4`
- * or not — placed as its own sibling after the nav/hamburger pair so it
- * stays visible whether or not the mobile menu is open, styled in this
- * theme's own hairline-bordered, sharp-cornered register in `base.css`
- * rather than canonical's pill button.
+ * Footer, a hairline and three columns: the name, the tagline and the
+ * `footerNote`; the footer navigation; the social profiles with their names.
+ * Before them, the footer widget columns (`theme@1.6`) when a site has placed
+ * any: a tier of their own right under the footer's hairline, on the same
+ * twelve columns, so an invitation to get in touch opens the footer the way a
+ * studio's own does. Then the legal line: the copyright year and the studio's
+ * name beside Cogenta's credit (`brandingHtml`, placed once, as received). No
+ * column carries a heading of the theme's own: a heading is a word, and a
+ * theme has no translation for it (a widget's title is the site's own words).
+ * Every `theme@1.4` field renders only when present, so a host that predates
+ * them still gets the name and the navigation.
  */
 
-function renderNavLinks(links: readonly ChromeNavLink[], className: string): string {
-  if (links.length === 0) return ''
-  const items = links
+function navItems(links: readonly ChromeNavLink[], className: string): string {
+  return links
     .filter((link) => link.href !== null || link.kind === 'submenu-placeholder')
-    .map((link, index) => {
+    .map((link) => {
       const label = escapeText(link.label)
       const titleAttr = link.title === null ? '' : ` title="${escapeAttribute(link.title)}"`
-      const number = String(index + 1).padStart(2, '0')
-      if (link.href === null) {
-        return `<li><span class="cg-nav__index" aria-hidden="true">${number}</span><span${titleAttr}>${label}</span></li>`
-      }
+      if (link.href === null)
+        return `<li class="${className}"><span${titleAttr}>${label}</span></li>`
       const href = escapeAttribute(link.href)
       const target = link.openInNewTab ? ' target="_blank" rel="noopener"' : ''
-      return (
-        `<li><span class="cg-nav__index" aria-hidden="true">${number}</span>` +
-        `<a href="${href}"${target}${titleAttr}>${label}</a></li>`
-      )
+      return `<li class="${className}"><a href="${href}"${target}${titleAttr}>${label}</a></li>`
     })
     .join('')
-  return items === '' ? '' : `<ul class="${className}">${items}</ul>`
-}
-
-/** The header's own call-to-action link (`theme@1.4`) — a flat filled button, the theme's one accent-coloured control, at the tail of the nav list. */
-function renderHeaderAction(action: ChromeInput['headerAction']): string {
-  if (action === undefined) return ''
-  return (
-    `<a class="cg-action cg-site-header__action" data-emphasis="primary" ` +
-    `href="${escapeAttribute(action.href)}">${escapeText(action.label)}</a>`
-  )
 }
 
-/** A hamburger mark drawn from three stacked bars — no icon font, no glyph a font might not ship. */
-function menuGlyph(): string {
-  return '<span class="cg-nav-toggle-bar"></span><span class="cg-nav-toggle-bar"></span><span class="cg-nav-toggle-bar"></span>'
+/** `footerNote` as paragraphs: a blank line starts a new one. */
+function renderFooterNote(note: string): string {
+  const paragraphs = note
+    .replace(/\r\n?/g, '\n')
+    .split(/\n\s*\n/)
+    .map((paragraph) => paragraph.replace(/\s*\n\s*/g, ' ').trim())
+    .filter((paragraph) => paragraph !== '')
+  if (paragraphs.length === 0) return ''
+  return `<div class="cg-colophon__note">${paragraphs
+    .map((paragraph) => `<p>${escapeText(paragraph)}</p>`)
+    .join('')}</div>`
 }
 
 export function renderChrome(input: ChromeInput): ChromeResult {
   const siteName = escapeText(input.site.name)
   const home = escapeAttribute(input.homeHref)
-  const headerNav = renderNavLinks(input.headerNav, 'cg-nav')
-  const footerNav = renderNavLinks(input.footerNav, 'cg-nav cg-nav--footer')
-  const headerAction = renderHeaderAction(input.headerAction)
-  const themeToggle = serialize(renderThemeToggle(input.locale, { className: 'cg-theme-toggle' }))
-  // The asterisk glyph is this theme's own typographic mark. It belongs to
-  // the *wordmark* treatment, so an uploaded logo replaces both together —
-  // an asterisk stapled to somebody else's logo is not a design decision
-  // this theme gets to make on their behalf.
-  const logo = renderBrandMark(input.brand, { className: 'cg-site-header__logo' })
-  const mark = logo ?? `<span class="cg-site-header__glyph" aria-hidden="true">*</span>${siteName}`
+  const links = navItems(input.headerNav, 'cg-masthead__item')
+  const action =
+    input.headerAction === undefined
+      ? ''
+      : `<a class="cg-masthead__action" href="${escapeAttribute(input.headerAction.href)}">${escapeText(
+          input.headerAction.label,
+        )}</a>`
+  const toggle = serialize(renderThemeToggle(input.locale, { className: 'cg-theme-toggle' }))
+  const logo = renderBrandMark(input.brand, { className: 'cg-masthead__logo' })
+  const mark = logo ?? `<span class="cg-masthead__wordmark">${siteName}</span>`
+  const tagline =
+    input.tagline === undefined
+      ? ''
+      : `<p class="cg-masthead__tagline">${escapeText(input.tagline)}</p>`
 
-  const hasMenu = headerNav !== '' || headerAction !== ''
-  const nav = hasMenu
-    ? `<nav class="cg-site-header__nav" id="cg-nav" aria-label="Primary">${headerNav}${headerAction}</nav>`
-    : ''
-  const toggle = hasMenu
+  const hasMenu = links !== '' || action !== ''
+  const menu = hasMenu
     ? `<input type="checkbox" id="cg-nav-toggle" class="cg-nav-toggle-input" aria-label="Menu">` +
-      `<label for="cg-nav-toggle" class="cg-nav-toggle-label" aria-hidden="true">${menuGlyph()}</label>`
+      `<label for="cg-nav-toggle" class="cg-nav-toggle-label" aria-hidden="true">` +
+      `<span class="cg-nav-toggle-bar"></span><span class="cg-nav-toggle-bar"></span>` +
+      `</label>` +
+      `<nav class="cg-masthead__nav" id="cg-nav" aria-label="Primary">` +
+      `${links === '' ? '' : `<ul class="cg-masthead__links">${links}</ul>`}` +
+      `${action}` +
+      `</nav>`
     : ''
 
   const header =
-    `<header class="cg-site-header"><div class="cg-site-header__inner">` +
-    `<a class="cg-site-header__mark" href="${home}">${mark}</a>` +
-    `${toggle}${nav}` +
-    `${themeToggle}` +
+    `<header class="cg-masthead" data-nav="${hasMenu ? 'links' : 'none'}">` +
+    `<div class="cg-masthead__inner">` +
+    `<a class="cg-masthead__home" href="${home}">${mark}</a>` +
+    `${tagline}` +
+    `${menu}` +
+    `${toggle}` +
     `</div></header>`
 
-  const tagline =
+  const footerTagline =
     input.tagline === undefined
       ? ''
-      : `<p class="cg-site-footer__tagline" data-field="tagline">${escapeText(input.tagline)}</p>`
-  const social =
-    input.social === undefined
-      ? ''
-      : serialize(
-          renderSocialLinks(input.social, {
-            className: 'cg-site-footer__social',
-            itemClassName: 'cg-site-footer__social-item',
-          }) ?? { kind: 'text', value: '' },
-        )
-  const footerNote =
-    input.footerNote === undefined
-      ? ''
-      : `<p class="cg-site-footer__note">${escapeText(input.footerNote)}</p>`
+      : `<p class="cg-colophon__tagline" data-field="tagline">${escapeText(input.tagline)}</p>`
+  const note = input.footerNote === undefined ? '' : renderFooterNote(input.footerNote)
+  const footerLinks = navItems(input.footerNav, 'cg-colophon__item')
+  const social = renderSocialLinks(input.social, {
+    className: 'cg-colophon__social',
+    itemClassName: 'cg-colophon__social-item',
+  })
+  const year = new Date().getFullYear()
+  // The footer widget columns (`theme@1.6`): a tier above the name, the pages
+  // and the profiles, under the footer's hairline, on the footer's own grid.
+  const footerWidgets = renderFooterWidgets(input.widgets, {
+    className: 'cg-colophon__widgets',
+    headingLevel: 'h2',
+  })
 
   const footer =
-    `<footer class="cg-site-footer"><div class="cg-site-footer__inner">` +
-    `<a class="cg-site-footer__statement" href="${home}">${siteName}</a>` +
-    `${tagline}` +
-    `<div class="cg-site-footer__row">` +
-    `${footerNav === '' ? '' : `<nav aria-label="Footer">${footerNav}</nav>`}` +
-    `${social === '' ? '' : `<div class="cg-site-footer__social-col">${social}</div>`}` +
-    `<div class="cg-site-footer__meta">${footerNote}<div class="cg-site-footer__branding">${input.brandingHtml}</div></div>` +
-    `</div></div></footer>`
+    `<footer class="cg-colophon"><div class="cg-colophon__inner">` +
+    `${footerWidgets === null ? '' : serialize(footerWidgets)}` +
+    `<div class="cg-colophon__about">` +
+    `<a class="cg-colophon__name" href="${home}">${siteName}</a>` +
+    `${footerTagline}${note}` +
+    `</div>` +
+    `${
+      footerLinks === ''
+        ? ''
+        : `<nav class="cg-colophon__nav" aria-label="Footer"><ul class="cg-colophon__links">${footerLinks}</ul></nav>`
+    }` +
+    `${social === null ? '' : `<div class="cg-colophon__follow">${serialize(social)}</div>`}` +
+    `<div class="cg-colophon__legal">` +
+    `<p class="cg-colophon__copyright">© ${year} ${siteName}</p>` +
+    `<div class="cg-colophon__branding">${input.brandingHtml}</div>` +
+    `</div>` +
+    `</div></footer>`
 
   return { header, footer }
 }

package/src/render/layout.ts

@@ -0,0 +1,177 @@
+import {
+  type Attributes,
+  blockHeadingTag,
+  type Child,
+  type ContentEntry,
+  entryDate,
+  type HtmlElement,
+  h,
+  heading,
+} from '@cogenta/theme-kit'
+
+/**
+ * The frame every block of this theme renders into, and the small pieces of
+ * typography the blocks share.
+ *
+ * The outer element carries the one section rhythm (`--cg-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 the left edge of a
+ * statement, a project image, a caption and a list of services is always 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: `cg-section ${className}`, 'data-block': block, ...attrs },
+    h(inner, { class: `cg-container ${className}__inner` }, ...children),
+  )
+}
+
+/**
+ * The label of a titled block: a hairline across the whole container and the
+ * title under it, small, in the text face. A studio lets the work carry the
+ * page, so a section says what it is and gets out of the way. On a wide
+ * screen the label sits in the first three columns and the content starts at
+ * the fourth (`.cg-split`), or it runs above a full-width grid.
+ */
+export function sectionHead(blockName: string, title: string | undefined): HtmlElement | null {
+  if (title === undefined) return null
+  return h(
+    'div',
+    { class: 'cg-head' },
+    heading(
+      blockHeadingTag(blockName) ?? 'h2',
+      { class: 'cg-head__title', 'data-field': 'title' },
+      title,
+    ),
+  )
+}
+
+/**
+ * A taxonomy field stores a term id, never a label: a value shaped like one
+ * is not something a visitor can be shown.
+ */
+const TERM_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+function plainText(entry: ContentEntry, fields: readonly string[]): string | undefined {
+  for (const field of fields) {
+    const value = entry[field]
+    if (typeof value === 'string' && value.trim() !== '' && !TERM_ID.test(value.trim())) {
+      return value.trim()
+    }
+  }
+  return undefined
+}
+
+const CLIENT_FIELDS = ['client', 'clientName', 'customer', 'organisation', 'organization'] as const
+const DISCIPLINE_FIELDS = ['discipline', 'role', 'service', 'category', 'kicker'] as const
+
+/** A four-digit year, from a `year` field when the collection keeps one, or from the entry's date. */
+export function entryYear(entry: ContentEntry): string | undefined {
+  const declared = entry.year
+  if (typeof declared === 'string' && /^\d{4}$/.test(declared.trim())) return declared.trim()
+  if (typeof declared === 'number' && Number.isInteger(declared)) return String(declared)
+  const iso = entryDate(entry)
+  return iso === undefined ? undefined : yearOf(iso)
+}
+
+/** `2025` from an ISO 8601 date, or `undefined` when the value is not one. */
+export function yearOf(iso: string): string | undefined {
+  const date = new Date(iso)
+  return Number.isNaN(date.getTime()) ? undefined : String(date.getUTCFullYear())
+}
+
+/**
+ * The caption line a studio sets under a piece of work: client, discipline,
+ * year, in that order, each only when the entry carries it. Read from the
+ * plain-text fields a collection declares, never from a taxonomy id and never
+ * invented.
+ */
+export interface WorkCaption {
+  readonly client?: string
+  readonly discipline?: string
+  readonly year?: string
+}
+
+export function entryCaption(entry: ContentEntry): WorkCaption {
+  const client = plainText(entry, CLIENT_FIELDS)
+  const discipline = plainText(entry, DISCIPLINE_FIELDS)
+  const year = entryYear(entry)
+  return {
+    ...(client === undefined ? {} : { client }),
+    ...(discipline === undefined ? {} : { discipline }),
+    ...(year === undefined ? {} : { year }),
+  }
+}
+
+/**
+ * A caption never repeats the title it sits under: a project named after its
+ * client ("Fenmore Building Society") keeps the discipline and the year only.
+ * The index, where the client has a column of its own, keeps it.
+ */
+export function captionUnder(caption: WorkCaption, title: string): WorkCaption {
+  if (caption.client === undefined) return caption
+  if (!title.toLocaleLowerCase().includes(caption.client.toLocaleLowerCase())) return caption
+  const { client: _repeated, ...rest } = caption
+  return rest
+}
+
+/** The caption as markup: one paragraph, one span per part, the separators drawn by the stylesheet. */
+export function renderCaption(caption: WorkCaption, className: string): HtmlElement | null {
+  const parts = [
+    caption.client === undefined
+      ? null
+      : h('span', { class: `${className}-part`, 'data-part': 'client' }, caption.client),
+    caption.discipline === undefined
+      ? null
+      : h('span', { class: `${className}-part`, 'data-part': 'discipline' }, caption.discipline),
+    caption.year === undefined
+      ? null
+      : h('span', { class: `${className}-part`, 'data-part': 'year' }, caption.year),
+  ].filter((part): part is HtmlElement => part !== null)
+  if (parts.length === 0) return null
+  return h('p', { class: className }, parts)
+}
+
+/**
+ * A taxonomy's own name, as a label: `disciplines` becomes `Disciplines`,
+ * `project_team` becomes `Project team`. The name is the one the site owner
+ * gave the taxonomy; this only sets it in sentence case.
+ */
+export function taxonomyLabel(name: string, locale: string): string {
+  const words = name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .toLowerCase()
+  if (words === '') return name
+  return words.charAt(0).toLocaleUpperCase(locale) + words.slice(1)
+}
+
+/**
+ * The word for "year" in the page's own language, from the platform's own
+ * data (`Intl.DisplayNames`), so the fact sheet of a project page labels its
+ * date without a translation table this theme would have to carry.
+ */
+export function yearLabel(locale: string): string {
+  try {
+    const name = new Intl.DisplayNames([locale], { type: 'dateTimeField' }).of('year')
+    if (name !== undefined && name !== '') {
+      return name.charAt(0).toLocaleUpperCase(locale) + name.slice(1)
+    }
+  } catch {
+    // An invalid locale tag: fall through to the English field name.
+  }
+  return 'Year'
+}