@cogenta/theme-magazine 1.1.3 → 1.3.3

package/src/render/chrome.ts

@@ -5,48 +5,44 @@ import {
   escapeAttribute,
   escapeText,
   renderBrandMark,
+  renderFooterWidgets,
   renderSocialLinks,
   renderThemeToggle,
   serialize,
 } from '@cogenta/theme-kit'
 
 /**
- * The masthead. A magazine's front matter is a nameplate — the title set in
- * the display serif, centred, with a hairline rule above and below — and a
- * quiet rubric bar underneath it, the way a print contents strip reads. That
- * is a structurally different header from a left-aligned wordmark plus a
- * right-aligned menu (`theme-canonical`'s own layout): the nameplate gets
- * its own row so it can be set large without competing with the nav for
- * width, and the nav becomes a second, quieter row.
+ * The masthead and the colophon (`theme@1.4`), drawn the way a daily draws
+ * them.
  *
- * L25 pro pass (`theme@1.4`): the top strip now names today's date rather
- * than a static tagline (`Intl.DateTimeFormat(ctx.locale, { dateStyle:
- * 'full' })` on `new Date()` — legitimate here because every page renders
- * per request, `cogenta serve` never caches a rendered page across a day
- * boundary for an anonymous visitor beyond `security.pageMaxAge`, and this
- * theme's own masthead has never claimed to be static-generated — `theme.
- * config.ts` still declares `runtime: 'static'`, which describes what this
- * theme *needs* to render a page, not a promise that today's date is frozen
- * at build time); the rubric row now also carries `headerAction` as a filled
- * "Subscribe"-style button; and a CSS-only `<details>` disclosure collapses
- * the whole rubric row into a hamburger below the nameplate's own
- * breakpoint, exactly the technique `theme-blog`'s masthead already proved
- * against a real browser (a closed `<details>`'s non-summary content cannot
- * be forced open by CSS alone, so the collapsed and expanded nav are two
- * separate `<nav>`s, never one pushed into a state it was never opened
- * into — see that theme's own `chrome.ts` for the verified detail).
+ * Masthead, three rows:
  *
- * L26 D4 — the manual light/dark/system toggle (`renderThemeToggle`,
- * `@cogenta/theme-kit`) sits in the top strip, next to today's date, not in
- * the rubric row below: the top strip renders unconditionally on every
- * page, while the rubric (`hasRubric`) only renders when there is a nav or
- * a header action — a toggle placed there would vanish on a site with
- * neither, which is exactly the "dark mode looks unsupported" bug this
- * feature exists to fix.
+ * 1. A thin bar: today's date on the left, the `tagline` in the middle on a
+ *    wide screen, the `headerAction` and the light/dark control on the right.
+ *    The action lives here rather than in the navigation so it stays visible
+ *    on a phone with the menu closed.
+ * 2. The nameplate: the site's name in the display face, centred, or its
+ *    uploaded logo at nameplate scale.
+ * 3. The section navigation in spaced capitals between a double rule and a
+ *    hairline. Below the breakpoint it becomes a panel opened by a CSS-only
+ *    toggle, a visually hidden checkbox paired with a `<label>`, no
+ *    `<script>`. The checkbox and label are siblings placed before the
+ *    `<nav>` so the sibling combinator in `base.css` reaches it.
+ *
+ * The date is the date the page is rendered, which is what a masthead date
+ * means on a site rendered per request.
+ *
+ * Colophon: the name again on a double rule, then four columns (the tagline
+ * and `footerNote`, the footer navigation over two columns, the social
+ * profiles with their names), then the legal line: the copyright year and the
+ * site's name beside Cogenta's credit (`brandingHtml`, placed once, as
+ * received). No column carries a heading: a heading is a word, and a theme
+ * has no translation for it. Every `theme@1.4` field renders only when
+ * present, so a host that predates them still gets the name and navigation.
  */
 
-function renderNavItems(links: readonly ChromeNavLink[], className: string): string {
-  const items = links
+function navItems(links: readonly ChromeNavLink[]): string {
+  return links
     .filter((link) => link.href !== null || link.kind === 'submenu-placeholder')
     .map((link) => {
       const label = escapeText(link.label)
@@ -57,103 +53,126 @@ function renderNavItems(links: readonly ChromeNavLink[], className: string): str
       return `<li><a href="${href}"${target}${titleAttr}>${label}</a></li>`
     })
     .join('')
-  return items === '' ? '' : `<ul class="${className}">${items}</ul>`
-}
-
-/** The rubric row's own call-to-action link (`theme@1.4`) — a filled button, the masthead's one place of solid colour. */
-function renderHeaderAction(action: ChromeInput['headerAction']): string {
-  if (action === undefined) return ''
-  return (
-    `<a class="cg-action cg-masthead__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-masthead__bars" aria-hidden="true"></span>'
+function isoDay(date: Date): string {
+  return date.toISOString().slice(0, 10)
 }
 
-function todaysDate(locale: string): string {
+function formatToday(date: Date, locale: string, options: Intl.DateTimeFormatOptions): string {
   try {
-    return new Intl.DateTimeFormat(locale, { dateStyle: 'full' }).format(new Date())
+    return new Intl.DateTimeFormat(locale, options).format(date)
   } catch {
-    return new Date().toISOString().slice(0, 10)
+    return new Intl.DateTimeFormat('en', options).format(date)
   }
 }
 
+/** `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 siteNameText = escapeText(input.site.name)
-  const navItems = renderNavItems(input.headerNav, 'cg-masthead__menu')
-  const headerAction = renderHeaderAction(input.headerAction)
-  const footerNav = renderNavItems(input.footerNav, 'cg-colophon__menu')
   const homeHref = escapeAttribute(input.homeHref)
-  // A nameplate is the one place a masthead earns a logo: it replaces the
-  // wordmark on its own row. The colophon keeps the name in text, so the
-  // site is still named in a page whose images never load.
-  const nameplate = renderBrandMark(input.brand, { className: 'cg-masthead__logo' }) ?? siteNameText
-  const themeToggle = serialize(renderThemeToggle(input.locale, { className: 'cg-theme-toggle' }))
+  const sections = navItems(input.headerNav)
+  const today = new Date()
+  const longToday = escapeText(
+    formatToday(today, input.locale, {
+      weekday: 'long',
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+    }),
+  )
+  const shortToday = escapeText(
+    formatToday(today, input.locale, { weekday: 'short', month: 'short', day: 'numeric' }),
+  )
+  const plate =
+    renderBrandMark(input.brand, { className: 'cg-masthead__logo' }) ??
+    `<span class="cg-masthead__name">${siteNameText}</span>`
+  const action =
+    input.headerAction === undefined
+      ? ''
+      : `<a class="cg-action cg-masthead__action" data-emphasis="masthead" href="${escapeAttribute(
+          input.headerAction.href,
+        )}">${escapeText(input.headerAction.label)}</a>`
+  const toggle = serialize(renderThemeToggle(input.locale, { className: 'cg-theme-toggle' }))
+  const tagline =
+    input.tagline === undefined
+      ? ''
+      : `<p class="cg-masthead__tagline">${escapeText(input.tagline)}</p>`
 
-  const hasRubric = navItems !== '' || headerAction !== ''
-  // Two renderings of the same rubric row, never both visible at once (CSS,
-  // `min-width: 56rem`) — see the file-level comment for why this cannot be
-  // a single `<details open>` forced open at width.
-  const mobileRubric = !hasRubric
-    ? ''
-    : `<details class="cg-masthead__disclosure">` +
-      `<summary class="cg-masthead__toggle" aria-label="Menu">${menuGlyph()}</summary>` +
-      `<nav class="cg-masthead__panel" aria-label="Primary">${navItems}${headerAction}</nav>` +
-      `</details>`
-  const desktopRubric = !hasRubric
-    ? ''
-    : `<nav class="cg-masthead__nav" aria-label="Primary"><div class="cg-masthead__nav-inner">${navItems}${headerAction}</div></nav>`
+  const menu =
+    sections === ''
+      ? ''
+      : `<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">` +
+        `<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">` +
+        `<ul class="cg-masthead__sections">${sections}</ul>` +
+        `</nav>`
 
   const header =
-    `<header class="cg-masthead">` +
-    `<div class="cg-masthead__top">` +
-    `<span class="cg-masthead__date">${escapeText(todaysDate(input.locale))}</span>` +
-    `${themeToggle}` +
+    `<header class="cg-masthead" data-nav="${sections === '' ? 'none' : 'sections'}">` +
+    `<div class="cg-masthead__bar"><div class="cg-masthead__bar-inner">` +
+    `<p class="cg-masthead__date"><time datetime="${isoDay(today)}">` +
+    `<span class="cg-masthead__date-long">${longToday}</span>` +
+    `<span class="cg-masthead__date-short" aria-hidden="true">${shortToday}</span>` +
+    `</time></p>` +
+    `${tagline}` +
+    `<div class="cg-masthead__tools">${action}${toggle}</div>` +
+    `</div></div>` +
+    `<div class="cg-masthead__plate">` +
+    `<a class="cg-masthead__home" href="${homeHref}">${plate}</a>` +
     `</div>` +
-    `<div class="cg-masthead__nameplate">` +
-    `<a class="cg-masthead__wordmark" href="${homeHref}">${nameplate}</a>` +
-    `${mobileRubric}` +
-    `</div>` +
-    `${desktopRubric}` +
+    `${menu}` +
     `</header>`
 
-  const tagline =
+  const footerTagline =
     input.tagline === undefined
       ? ''
       : `<p class="cg-colophon__tagline" data-field="tagline">${escapeText(input.tagline)}</p>`
-  const social =
-    input.social === undefined
-      ? ''
-      : serialize(
-          renderSocialLinks(input.social, {
-            className: 'cg-colophon__social',
-            itemClassName: 'cg-colophon__social-item',
-          }) ?? { kind: 'text', value: '' },
-        )
-  const footerNote =
-    input.footerNote === undefined
-      ? ''
-      : `<p class="cg-colophon__note">${escapeText(input.footerNote)}</p>`
+  const note = input.footerNote === undefined ? '' : renderFooterNote(input.footerNote)
+  const footerLinks = navItems(input.footerNav)
+  const social = renderSocialLinks(input.social, {
+    className: 'cg-colophon__social',
+    itemClassName: 'cg-colophon__social-item',
+  })
+  const year = today.getFullYear()
+  // The footer widget columns (`theme@1.6`) sit under the name, above the
+  // colophon's own columns, set in the same register.
+  const footerWidgets = renderFooterWidgets(input.widgets, {
+    className: 'cg-colophon__widgets',
+    headingLevel: 'h2',
+  })
 
   const footer =
-    `<footer class="cg-colophon"><div class="cg-colophon__grid">` +
-    `<div class="cg-colophon__about">` +
-    `<a class="cg-colophon__wordmark" href="${homeHref}">${siteNameText}</a>` +
-    `${tagline}</div>` +
-    `<div class="cg-colophon__sections">` +
-    `<p class="cg-colophon__heading">Sections</p>` +
-    `${footerNav === '' ? '' : `<nav aria-label="Footer">${footerNav}</nav>`}` +
+    `<footer class="cg-colophon"><div class="cg-colophon__inner">` +
+    `<div class="cg-colophon__plate">` +
+    `<a class="cg-colophon__name" href="${homeHref}">${siteNameText}</a>` +
     `</div>` +
-    `<div class="cg-colophon__follow">` +
-    `<p class="cg-colophon__heading">Follow</p>` +
-    `${social}` +
+    `${footerWidgets === null ? '' : serialize(footerWidgets)}` +
+    `<div class="cg-colophon__grid">` +
+    `${footerTagline === '' && note === '' ? '' : `<div class="cg-colophon__about">${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>` +
-    `<div class="cg-colophon__meta">` +
-    `${footerNote}` +
+    `<div class="cg-colophon__legal">` +
+    `<p class="cg-colophon__copyright">© ${year} ${siteNameText}</p>` +
     `<div class="cg-colophon__branding">${input.brandingHtml}</div>` +
     `</div>` +
     `</div></footer>`

package/src/render/layout.ts

@@ -0,0 +1,105 @@
+import {
+  type Attributes,
+  blockHeadingTag,
+  type Child,
+  type ContentEntry,
+  type HtmlElement,
+  h,
+  heading,
+} from '@cogenta/theme-kit'
+
+/**
+ * The frame every block of this theme renders into, and the typographic
+ * furniture the blocks share.
+ *
+ * The outer element carries the section rhythm (`--cg-section`, applied once
+ * to every block alike) and paints edge to edge when a variant asks for a
+ * band. The inner element is the twelve-column container: a front page, a
+ * rail, an article and a colophon all sit on the same columns, so the left
+ * edge of a headline, a standfirst and a caption never drift apart.
+ *
+ * `inner` is `figure` for a block whose semantics are a figure (a quotation
+ * and its attribution, a photograph 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),
+  )
+}
+
+/**
+ * A titled block's head, set the way a newspaper sets a section label: a
+ * heavy rule in ink across the grid, the title in the display face under it.
+ * `null` for an untitled block, so a caller can drop it into its children.
+ */
+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,
+    ),
+  )
+}
+
+function parse(iso: string): Date | null {
+  const date = new Date(iso)
+  return Number.isNaN(date.getTime()) ? null : date
+}
+
+function format(date: Date, locale: string, options: Intl.DateTimeFormatOptions): string {
+  try {
+    return new Intl.DateTimeFormat(locale, { timeZone: 'UTC', ...options }).format(date)
+  } catch {
+    return new Intl.DateTimeFormat('en', { timeZone: 'UTC', ...options }).format(date)
+  }
+}
+
+/** `September 13, 2026` in the page's locale, or `null` when the value is not a date. */
+export function longDate(iso: string, locale: string): string | null {
+  const date = parse(iso)
+  return date === null ? null : format(date, locale, { dateStyle: 'long' })
+}
+
+/** `Sep 13, 2026`, the form a listing sets under a headline, or `null`. */
+export function shortDate(iso: string, locale: string): string | null {
+  const date = parse(iso)
+  return date === null ? null : format(date, locale, { dateStyle: 'medium' })
+}
+
+/**
+ * A taxonomy field stores a term id, never a label: a value shaped like one
+ * is not something a reader 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
+
+/**
+ * The label a listing sets above a headline, read from whichever of the usual
+ * field names a collection declares: `kicker` first (a topic, a form such as
+ * "Review", a columnist's name), then the plain-text section fields older
+ * schemas use. Never invented, and never a term id.
+ */
+const KICKER_FIELDS = ['kicker', 'rubric', 'section', 'category', 'topic', 'department'] as const
+
+export function entryKicker(entry: ContentEntry): string | undefined {
+  for (const field of KICKER_FIELDS) {
+    const value = entry[field]
+    if (typeof value === 'string' && value.trim() !== '' && !TERM_ID.test(value.trim())) {
+      return value
+    }
+  }
+  return undefined
+}

package/src/render/render-block.ts

@@ -5,12 +5,13 @@ import {
   h,
   type PageContent,
   pageHasOwnHeading,
+  providedBlockNode,
   type RenderContext,
-  renderEntryHeader,
   resolveBlockForRender,
   withBlockKey,
   withBlockVariant,
 } from '@cogenta/theme-kit'
+import { isArticle, renderArticleFooter, renderArticleHeader, renderPageHeader } from './article.js'
 import { renderAccordion } from './blocks/accordion.js'
 import { renderCollectionList } from './blocks/collection-list.js'
 import { renderCta } from './blocks/cta.js'
@@ -29,23 +30,27 @@ import { renderStatCounter } from './blocks/stat-counter.js'
 import { renderStats } from './blocks/stats.js'
 import { renderTestimonial } from './blocks/testimonial.js'
 
+export type { FetchedEntries, PageContent }
+
 export function renderBlock(
   block: VocabularyBlock,
   ctx: RenderContext,
   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, exactly the
-  // same reasoning `withBlockKey` in `renderPage` already follows for `_key`.
+  // `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)
 }
 
@@ -90,11 +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. `null`, not a throw — a theme has no `@cogenta/core` error types
-      // to reach for (contract D refuses that import), and a fallback block
-      // is the render layer's decision, 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
@@ -102,21 +105,28 @@ function renderKnownBlock(
   }
 }
 
+/** Marks the first `prose` block of an article, the one paragraph a drop cap may open. */
+function withOpening(element: HtmlElement | null): HtmlElement | null {
+  if (element === null) return null
+  return { ...element, attrs: { ...element.attrs, 'data-opening': 'true' } }
+}
+
 /**
- * Wraps every block in `<main id="cg-main">` — the skip link's anchor — and
- * marks each rendered block with its own `_key` (`withBlockKey`, mandatory:
- * it is what lets the L16 page builder map a clicked element on the real
- * rendered page back to the block that produced it). A page whose blocks
- * already carry a heading (a `hero`) gets no second `<h1>`.
+ * `<main id="cg-main">` is mandatory: it is the skip link's target, written
+ * by `@cogenta/cli`'s `theme-render.ts` outside any theme's control.
+ *
+ * Four openings, and exactly one `h1` in each:
  *
- * A page carrying `entry` (contract D `theme@1.4`) gets `renderEntryHeader`'s
- * furniture — classification eyebrow (styled in this masthead's own
- * journal-red accent, see `styles/base.css`'s `.cg-entry-header__terms`),
- * title, excerpt, date/author/reading-time meta and cover — instead of the
- * bare `<h1>` every other page falls back to; `renderEntryHeader` itself
- * returns `null` for a `blocks`-only page (e.g. `about`, which carries no
- * `entry`) or one that already draws its own heading, so the bare-title
- * fallback still applies there, exactly as before.
+ * - a page whose blocks include a `hero` lets the hero carry the title;
+ * - an entry that carries what an article has (`isArticle`) gets the
+ *   article header, and its first `prose` block may open on a drop cap;
+ * - a page that opens on a listing is a front: the masthead above already
+ *   names it, so its title stays in the outline for assistive technology and
+ *   out of sight, and the first story sits directly under the navigation;
+ * - anything else gets its title set as a section title.
+ *
+ * `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,13 +135,31 @@ export function renderPage(
   registry?: BlockRegistry,
 ): HtmlElement {
   const ownHeading = pageHasOwnHeading(page.blocks)
-  const entryHeader = ownHeading ? null : renderEntryHeader(page, ctx)
+  const article = !ownHeading && isArticle(page.entry) ? page.entry : undefined
+  const front = !ownHeading && article === undefined && page.blocks[0]?._type === 'collectionList'
+  const opening = ownHeading
+    ? null
+    : article !== undefined
+      ? renderArticleHeader(page, article, ctx)
+      : front
+        ? h('h1', { class: 'cg-visually-hidden' }, page.title)
+        : renderPageHeader(page)
+
+  const firstProse =
+    article === undefined ? undefined : page.blocks.find((block) => block._type === 'prose')
+
   return h(
     'main',
-    { class: 'cg-main', id: 'cg-main' },
-    ownHeading ? null : (entryHeader ?? h('h1', { class: 'cg-page__title' }, page.title)),
-    page.blocks.map((block) =>
-      withBlockKey(renderBlock(block, ctx, entries, registry), block._key),
-    ),
+    {
+      class:
+        article !== undefined ? 'cg-main cg-article' : front ? 'cg-main cg-front-page' : 'cg-main',
+      id: 'cg-main',
+    },
+    opening,
+    page.blocks.map((block) => {
+      const rendered = renderBlock(block, ctx, entries, registry)
+      return withBlockKey(block === firstProse ? withOpening(rendered) : rendered, block._key)
+    }),
+    article === undefined ? null : renderArticleFooter(article),
   )
 }