@cogenta/theme-association 0.3.3 → 0.5.4

package/src/render/blocks/cta.ts

@@ -7,31 +7,60 @@ import {
   heading,
   type RenderContext,
 } from '@cogenta/theme-kit'
+import { giftsOf } from '../figures.js'
+import { optionalText, section } from '../layout.js'
 
 /**
- * The "Every gift counts" donate band — a full-width, tinted panel (the
- * skin's own accent, softened) rather than a plain section, so the one block
- * whose entire job is a call to act reads as the loudest thing on the page.
+ * The ask. On a charity's site the band that asks is the donation ask, so
+ * this theme gives it the signal yellow, across the whole width of the
+ * window: the title large on the first six columns, and on the other six the
+ * sentence and the actions, the first one a filled ink button.
+ *
+ * When the text says what a gift pays for, sentence by sentence, each
+ * sentence starting with an amount, the amounts are set large beside what
+ * they buy (`giftsOf`); any other text stays one paragraph.
+ *
+ * An invitation that is not a donation ask (a volunteer evening, a
+ * newsletter) asks for the quieter band with the `background` variant, which
+ * lays the same layout on the paper's darker stock.
  */
-export function renderCta(block: CtaBlock, ctx: RenderContext): HtmlElement {
+function body(block: CtaBlock): HtmlElement | null {
+  const gifts = giftsOf(block.text)
+  if (gifts === undefined) {
+    return optionalText('p', 'ca-cta__text', block.text, { 'data-field': 'text' })
+  }
   return h(
-    'section',
-    { class: 'cg-block cg-cta', 'data-block': 'cta' },
+    'div',
+    { class: 'ca-cta__gifts' },
+    gifts.lead === undefined ? null : h('p', { class: 'ca-cta__text' }, gifts.lead),
     h(
-      'div',
-      { class: 'cg-cta__inner' },
-      heading(
-        blockHeadingTag('cta') ?? 'h2',
-        { class: 'cg-cta__title', 'data-field': 'title' },
-        block.title,
+      'dl',
+      { class: 'ca-cta__ladder' },
+      gifts.gifts.map((gift) =>
+        h(
+          'div',
+          { class: 'ca-cta__gift' },
+          h('dt', { class: 'ca-cta__amount' }, gift.amount),
+          h('dd', { class: 'ca-cta__buys' }, gift.text),
+        ),
       ),
-      block.text === undefined
-        ? null
-        : h('p', { class: 'cg-cta__text', 'data-field': 'text' }, block.text),
-      // `actions` is required and non-empty for a `cta`, so the list is
-      // always rendered; the null branch stays reachable only through
-      // invalid data.
-      actionList(ctx, block.actions, block.title),
     ),
+    gifts.tail === undefined ? null : h('p', { class: 'ca-cta__text' }, gifts.tail),
+  )
+}
+
+export function renderCta(block: CtaBlock, ctx: RenderContext): HtmlElement {
+  return section(
+    'section',
+    'cta',
+    'ca-cta',
+    { 'data-band': 'signal' },
+    'div',
+    heading(
+      blockHeadingTag('cta') ?? 'h2',
+      { class: 'ca-cta__title', 'data-field': 'title' },
+      block.title,
+    ),
+    h('div', { class: 'ca-cta__body' }, body(block), actionList(ctx, block.actions, block.title)),
   )
 }

package/src/render/blocks/embed.ts

@@ -1,17 +1,20 @@
 import type { EmbedBlock } from '@cogenta/blocks'
 import { aspectRatio, type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+import { arrowWords, section } from '../layout.js'
 
 /**
- * Nothing here contacts a third party before the visitor has consented.
+ * A film about the food bank, a recording of the annual meeting, a post from
+ * a partner: eight columns of the reading width.
  *
- * When `consentRequired` is true the block renders a self-contained card and
- * an outbound link — no `<iframe>`, no `<script>`, no preconnect. The theme
- * ships no consent *button*, because it ships no JavaScript at all: granting
- * consent is a site-wide decision that belongs to the consent layer, not to
- * a block.
+ * Nothing here contacts a third party before the visitor consents: when
+ * `consentRequired` is set, or the provider has no cookie-free frame (a map,
+ * a post), a notice takes the frame's place. The notice is a short card
+ * inside a hairline, not an empty frame kept at the video's ratio: without a
+ * script there is nothing to load into that frame later, and a large blank
+ * rectangle on a page is a hole. A label, one sentence, and one arrow link to
+ * the original. No preconnect, no poster fetched from the provider, no
+ * consent button (this theme ships no script).
  */
-
-/** `null` means "this provider has no embeddable frame we trust". */
 function frameSource(provider: EmbedBlock['provider'], rawUrl: string): string | null {
   const url = URL.parse(rawUrl)
   if (url === null) return null
@@ -41,58 +44,73 @@ function frameSource(provider: EmbedBlock['provider'], rawUrl: string): string |
     case 'soundcloud':
       return `https://w.soundcloud.com/player/?url=${encodeURIComponent(rawUrl)}`
     default:
-      // bluesky, mastodon, other: a post embed is a script tag, which this
-      // theme does not load. The link card is the rendering.
+      // bluesky, mastodon, other: a post embed is a script tag and a map is
+      // a third-party page, neither of which this theme loads. The notice is
+      // the rendering.
       return null
   }
 }
 
-function consentCard(block: EmbedBlock, ctx: RenderContext, reason: string): HtmlElement {
+function notice(block: EmbedBlock, ctx: RenderContext, reason: string): HtmlElement {
   return h(
     'div',
-    { class: 'cg-embed__placeholder' },
-    h('p', { class: 'cg-embed__notice' }, reason),
+    { class: 'ca-embed__notice' },
+    h('p', { class: 'ca-embed__label' }, ctx.t('embed.label')),
+    h('p', { class: 'ca-embed__reason' }, reason),
     h(
       'a',
       {
-        class: 'cg-embed__link',
+        class: 'ca-arrow-link ca-embed__link',
         href: ctx.link(block.url),
         rel: 'noopener noreferrer nofollow',
       },
-      ctx.t('embed.open', { provider: block.provider }),
+      arrowWords(
+        block.provider === 'other'
+          ? ctx.t('embed.openOther')
+          : ctx.t('embed.open', { provider: block.provider }),
+      ),
     ),
   )
 }
 
 export function renderEmbed(block: EmbedBlock, ctx: RenderContext): HtmlElement {
   const source = block.consentRequired ? null : frameSource(block.provider, block.url)
+  // Without a ratio the frame would collapse and shift the layout as it loads.
   const ratio = aspectRatio(block.ratio) ?? '16 / 9'
 
-  return h(
+  return section(
     'div',
+    'embed',
+    'ca-embed',
     {
-      class: 'cg-block cg-embed',
-      'data-block': 'embed',
       'data-provider': block.provider,
       'data-consent': block.consentRequired ? 'required' : 'not-required',
-      style: `--cg-ratio:${ratio}`,
+      'data-frame': source === null ? 'notice' : 'player',
     },
+    'div',
     source === null
-      ? consentCard(
+      ? notice(
           block,
           ctx,
           block.consentRequired
             ? ctx.t('embed.consentRequired', { provider: block.provider })
             : ctx.t('embed.unsupported', { provider: block.provider }),
         )
-      : h('iframe', {
-          class: 'cg-embed__frame',
-          src: source,
-          title: ctx.t('embed.title', { provider: block.provider }),
-          loading: 'lazy',
-          referrerpolicy: 'strict-origin-when-cross-origin',
-          allow: 'accelerometer; clipboard-write; encrypted-media; picture-in-picture; fullscreen',
-          allowfullscreen: true,
-        }),
+      : h(
+          'div',
+          { class: 'ca-embed__frame', style: `aspect-ratio:${ratio}` },
+          h('iframe', {
+            class: 'ca-embed__player',
+            src: source,
+            // A frame with no accessible name is announced as "frame" and
+            // nothing else (WCAG 4.1.2).
+            title: ctx.t('embed.title', { provider: block.provider }),
+            loading: 'lazy',
+            referrerpolicy: 'strict-origin-when-cross-origin',
+            allow:
+              'accelerometer; clipboard-write; encrypted-media; picture-in-picture; fullscreen',
+            allowfullscreen: true,
+          }),
+        ),
   )
 }

package/src/render/blocks/faq.ts

@@ -1,52 +1,43 @@
 import type { FaqBlock, FaqItem } from '@cogenta/blocks'
 import {
-  blockHeadingTag,
   type HtmlElement,
   h,
   heading,
+  nestedHeadingTag,
   type RenderContext,
   renderRichText,
 } from '@cogenta/theme-kit'
+import { section, sectionHead } from '../layout.js'
 
 /**
- * `<details>`/`<summary>` rather than a scripted accordion: expanding,
- * keyboard operation, the expanded state announced to assistive technology
- * and in-page search all come from the browser, at zero bytes of
- * JavaScript — the same mechanism this theme's own mobile nav toggle uses.
- *
- * The question is plain text inside `<summary>`, not a heading: a heading
- * nested in a summary is rendered inconsistently across screen readers, and
- * the questions are already reachable as a list under the block's own
- * heading.
+ * The questions people ask before they give an hour or a pound, answered in
+ * the open: every answer is printed under its question, two columns of them
+ * on a wide screen, each pair under a hairline. A charity's answers are short
+ * and they are the point; hiding them behind a click makes a visitor work for
+ * reassurance. (The `accordion` block is the collapsible one.)
  */
-function renderItem(item: FaqItem, ctx: RenderContext): HtmlElement {
+function pair(item: FaqItem, ctx: RenderContext, titled: boolean): HtmlElement {
   return h(
-    'li',
-    { class: 'cg-faq__item' },
-    h(
-      'details',
-      { class: 'cg-faq__details' },
-      h('summary', { class: 'cg-faq__question' }, item.question),
-      h('div', { class: 'cg-faq__answer' }, renderRichText(ctx, item.answer)),
-    ),
+    'div',
+    { class: 'ca-faq__item' },
+    heading(nestedHeadingTag('faq', titled), { class: 'ca-faq__question' }, item.question),
+    h('div', { class: 'ca-faq__answer' }, renderRichText(ctx, item.answer)),
   )
 }
 
 export function renderFaq(block: FaqBlock, ctx: RenderContext): HtmlElement {
-  return h(
+  const titled = block.title !== undefined
+  return section(
     'section',
-    { class: 'cg-block cg-faq', 'data-block': 'faq' },
-    block.title === undefined
-      ? null
-      : heading(
-          blockHeadingTag('faq') ?? 'h2',
-          { class: 'cg-faq__title', 'data-field': 'title' },
-          block.title,
-        ),
+    'faq',
+    'ca-faq',
+    { 'data-titled': String(titled) },
+    'div',
+    sectionHead('faq', block.title),
     h(
-      'ul',
-      { class: 'cg-faq__items' },
-      block.items.map((item) => renderItem(item, ctx)),
+      'div',
+      { class: 'ca-faq__items' },
+      block.items.map((item) => pair(item, ctx, titled)),
     ),
   )
 }

package/src/render/blocks/feature-grid.ts

@@ -1,7 +1,5 @@
 import type { FeatureGridBlock, FeatureItem } from '@cogenta/blocks'
 import {
-  blockHeadingTag,
-  type HeadingTag,
   type HtmlElement,
   h,
   heading,
@@ -10,58 +8,92 @@ import {
   type RenderContext,
   renderIcon,
 } from '@cogenta/theme-kit'
+import { arrowWords, section, sectionHead } from '../layout.js'
 
 /**
- * "What we do" — three (or more) programme cards, each a rounded, softly
- * shadowed tile with its icon in a round chip. The item's title carries the
- * link, so the link's accessible name is the programme's own name (WCAG
- * 2.4.4) — the block has no separate "learn more" field to write.
+ * Two readings of the same block, chosen by its content rather than by a
+ * setting:
  *
- * `icon` names a symbol, never markup: it is exposed as a data attribute for
- * the skin and, when the name is one `renderIcon` recognises, a real inline
- * glyph — `aria-hidden`, since the title already names the programme.
+ * - **Ways in**, when an item names an icon this theme can draw: ruled
+ *   columns, each with a small line icon in the organisation's green, the
+ *   name, its sentence, and the name as an arrow link when it leads somewhere.
+ *   Never a tinted tile behind an icon, never a card.
+ * - **Steps**, when no item names an icon: an ordered list, each step under a
+ *   rule with its number set large in the display face, because a list of
+ *   things without pictures on a charity's site is almost always "how it
+ *   works": how to sign up, what happens after you give, the first evening.
  */
-function renderItem(item: FeatureItem, ctx: RenderContext, tag: HeadingTag): HtmlElement {
-  const title =
-    item.link === undefined
-      ? heading(tag, { class: 'cg-feature__title' }, item.title)
-      : heading(
-          tag,
-          { class: 'cg-feature__title' },
-          h('a', { class: 'cg-feature__link', href: href(ctx, item.link) }, item.title),
-        )
+function hasIcons(block: FeatureGridBlock): boolean {
+  return block.items.some((item) => item.icon !== undefined)
+}
+
+/**
+ * How many columns a wide screen gets: as many as there are items up to
+ * four, then three when the count divides by three, so six items make two
+ * full rows of three rather than a row of four and a row of two.
+ */
+export function columnsFor(count: number): number {
+  if (count <= 4) return count
+  return count % 3 === 0 ? 3 : 4
+}
+
+function name(item: FeatureItem, ctx: RenderContext): HtmlElement | string {
+  return item.link === undefined
+    ? item.title
+    : h('a', { class: 'ca-arrow-link', href: href(ctx, item.link) }, arrowWords(item.title))
+}
+
+function column(item: FeatureItem, ctx: RenderContext, titled: boolean): HtmlElement {
+  const icon =
+    item.icon === undefined ? null : renderIcon(item.icon, { className: 'ca-ways__icon', size: 28 })
   return h(
     'li',
-    { class: 'cg-feature' },
-    item.icon === undefined
-      ? null
-      : h(
-          'span',
-          { class: 'cg-feature__icon', 'data-icon': item.icon, 'aria-hidden': 'true' },
-          renderIcon(item.icon),
-        ),
-    title,
-    item.text === undefined ? null : h('p', { class: 'cg-feature__text' }, item.text),
+    { class: 'ca-ways__item' },
+    icon,
+    heading(nestedHeadingTag('featureGrid', titled), { class: 'ca-ways__name' }, name(item, ctx)),
+    item.text === undefined ? null : h('p', { class: 'ca-ways__text' }, item.text),
   )
 }
 
-export function renderFeatureGrid(block: FeatureGridBlock, ctx: RenderContext): HtmlElement {
-  const hasTitle = block.title !== undefined
-  const itemTag = nestedHeadingTag('featureGrid', hasTitle)
+function step(item: FeatureItem, ctx: RenderContext, titled: boolean, index: number): HtmlElement {
   return h(
+    'li',
+    { class: 'ca-steps__item' },
+    h('span', { class: 'ca-steps__number', 'aria-hidden': 'true' }, String(index + 1)),
+    heading(nestedHeadingTag('featureGrid', titled), { class: 'ca-steps__name' }, name(item, ctx)),
+    item.text === undefined ? null : h('p', { class: 'ca-steps__text' }, item.text),
+  )
+}
+
+export function renderFeatureGrid(block: FeatureGridBlock, ctx: RenderContext): HtmlElement {
+  const titled = block.title !== undefined
+  const count = String(columnsFor(block.items.length))
+  if (!hasIcons(block)) {
+    return section(
+      'section',
+      'featureGrid',
+      'ca-steps',
+      { 'data-titled': String(titled), 'data-count': count },
+      'div',
+      sectionHead('featureGrid', block.title),
+      h(
+        'ol',
+        { class: 'ca-steps__items' },
+        block.items.map((item, index) => step(item, ctx, titled, index)),
+      ),
+    )
+  }
+  return section(
     'section',
-    { class: 'cg-block cg-features', 'data-block': 'featureGrid' },
-    hasTitle
-      ? heading(
-          blockHeadingTag('featureGrid') ?? 'h2',
-          { class: 'cg-features__title', 'data-field': 'title' },
-          block.title ?? '',
-        )
-      : null,
+    'featureGrid',
+    'ca-ways',
+    { 'data-titled': String(titled), 'data-count': count },
+    'div',
+    sectionHead('featureGrid', block.title),
     h(
       'ul',
-      { class: 'cg-features__items' },
-      block.items.map((item) => renderItem(item, ctx, itemTag)),
+      { class: 'ca-ways__items' },
+      block.items.map((item) => column(item, ctx, titled)),
     ),
   )
 }

package/src/render/blocks/gallery.ts

@@ -1,47 +1,53 @@
 import type { GalleryBlock } from '@cogenta/blocks'
 import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * The carousel ships **no JavaScript**. It is a scroll-snapping list, which
- * gives touch swiping, trackpad scrolling and — because the list is focusable
- * and labelled — arrow-key scrolling, with none of the failure modes of a
- * scripted carousel (WCAG 2.2.2).
+ * Photographs of a year at the hall, in the three layouts contract B names:
  *
- * `grid` (the layout the association home page's photo gallery uses) shows
- * six rounded, evenly sized tiles — a warm contact sheet rather than a rigid
- * masonry wall.
+ * - `grid`: one picture takes the row at 16:9; two share it at 3:2; three
+ *   make one large picture on the first eight columns with the other two
+ *   stacked beside it; four make two rows of two at 3:2; five and more make
+ *   rows of three at 4:3. No row is ever left with a gap in it.
+ * - `masonry`: three columns of pictures at their own proportions.
+ * - `carousel`: a row of 4:3 crops that scrolls sideways, with native scroll
+ *   snapping. It is a focusable, labelled region so the row can be scrolled
+ *   from the keyboard; no script drives it.
  */
 export function renderGallery(block: GalleryBlock, ctx: RenderContext): HtmlElement {
-  const items = h(
-    'ul',
-    { class: 'cg-gallery__items' },
-    block.items.map((item) =>
-      h(
-        'li',
-        { class: 'cg-gallery__item' },
-        image(ctx, item.media, { sizes: '(min-width: 45rem) 20rem, 60vw' }),
-      ),
+  const count = block.items.length
+  const items = block.items.map((item, index) =>
+    h(
+      'li',
+      { class: 'ca-gallery__item' },
+      image(ctx, item.media, {
+        className: 'ca-gallery__image',
+        sizes:
+          block.layout === 'grid' && index === 0
+            ? '(min-width: 64rem) 52vw, 100vw'
+            : '(min-width: 64rem) 30vw, 80vw',
+      }),
     ),
   )
+  const list = h('ul', { class: 'ca-gallery__items' }, items)
 
-  return h(
-    'section',
-    {
-      class: 'cg-block cg-gallery',
-      'data-block': 'gallery',
-      'data-layout': block.layout,
-    },
+  return section(
+    'div',
+    'gallery',
+    'ca-gallery',
+    { 'data-layout': block.layout, 'data-count': count >= 5 ? 'many' : String(count) },
+    'div',
     block.layout === 'carousel'
       ? h(
           'div',
           {
-            class: 'cg-gallery__viewport',
+            class: 'ca-gallery__viewport',
             role: 'region',
             'aria-label': ctx.t('gallery.carousel'),
             tabindex: '0',
           },
-          items,
+          list,
         )
-      : items,
+      : list,
   )
 }

package/src/render/blocks/hero.ts

@@ -1,60 +1,73 @@
 import type { HeroBlock } from '@cogenta/blocks'
-import {
-  actionList,
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  image,
-  type RenderContext,
-} from '@cogenta/theme-kit'
+import { actionList, type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { optionalText } from '../layout.js'
 
 /**
- * The hero carries the page's `h1` (contract B: `headingLevel: 'h1'`), so
- * `renderPage` relies on it to avoid emitting a second one.
+ * The opening of a page: a photograph of the people the organisation works
+ * with, across the whole width of the window, and the statement of the cause
+ * set large on a sheet of the page's own paper that starts at the window's
+ * left edge and rises into the bottom of the photograph.
  *
- * The warm, community read this theme opens with: a rounded "eyebrow" pill
- * (the cause, not a generic label), a big friendly title in the display
- * face, and — when there is one — the media sitting in its own big rounded
- * card with a soft halo glow behind it (`cg-hero__halo`, purely decorative,
- * `aria-hidden`), rather than a hard-edged frame. Centred copy on mobile,
- * two columns from `md` up.
+ * On a wide screen the sheet holds the eyebrow and the statement on the first
+ * seven columns; the subtitle and the actions sit under the photograph on
+ * the last four, starting where the photograph ends, so the two halves of the
+ * opening read as one composition rather than a box with a hole beside it.
+ *
+ * The words are never laid over the picture. A headline floated in the middle
+ * of a dimmed photograph needs a veil to stay legible on every picture an
+ * editor may choose, and that veil is the look of every generated charity
+ * template; on the paper the statement is legible in both schemes whatever
+ * the photograph, and the faces keep their own light.
+ *
+ * The first action is the donation ask, drawn in the signal yellow; the
+ * others are underlined words. An eyebrow, when there is one, is a short line
+ * in the organisation's green, never a badge. Without media the block is the
+ * sheet alone.
+ *
+ * The image is the only one on a page loaded eagerly: it is above the fold
+ * by construction.
  */
 export function renderHero(block: HeroBlock, ctx: RenderContext): HtmlElement {
-  const tag = blockHeadingTag('hero') ?? 'h1'
+  const hasMedia = block.media !== undefined
+  const actions = actionList(ctx, block.actions, ctx.t('hero.actions'))
+  const hasAside = block.subtitle !== undefined || actions !== null
   return h(
     'section',
-    { class: 'cg-block cg-hero', 'data-block': 'hero' },
-    h(
-      'div',
-      { class: 'cg-hero__copy' },
-      block.eyebrow === undefined
-        ? null
-        : h(
-            'p',
-            { class: 'cg-hero__eyebrow', 'data-field': 'eyebrow' },
-            h('span', { class: 'cg-pill' }, block.eyebrow),
-          ),
-      heading(tag, { class: 'cg-hero__title', 'data-field': 'title' }, block.title),
-      block.subtitle === undefined
-        ? null
-        : h('p', { class: 'cg-hero__subtitle', 'data-field': 'subtitle' }, block.subtitle),
-      actionList(ctx, block.actions, ctx.t('hero.actions')),
-    ),
+    {
+      class: 'ca-section ca-hero ca-ask',
+      'data-block': 'hero',
+      'data-media': String(hasMedia),
+    },
     block.media === undefined
       ? null
       : h(
-          'div',
-          { class: 'cg-hero__frame' },
-          h('span', { class: 'cg-hero__halo', 'aria-hidden': 'true' }),
-          // The only image above the fold by construction, so the only one
-          // that must not be lazy — a lazy-loaded LCP element is a measured
-          // Lighthouse regression, not a theoretical one.
+          'figure',
+          { class: 'ca-hero__media' },
           image(ctx, block.media, {
-            className: 'cg-hero__media',
+            className: 'ca-hero__image',
             loading: 'eager',
-            sizes: '(min-width: 60rem) 44vw, 100vw',
+            sizes: '100vw',
           }),
         ),
+    h(
+      'div',
+      { class: 'ca-container ca-hero__inner' },
+      h(
+        'div',
+        { class: 'ca-hero__panel' },
+        optionalText('p', 'ca-kicker ca-hero__eyebrow', block.eyebrow, {
+          'data-field': 'eyebrow',
+        }),
+        h('h1', { class: 'ca-hero__title', 'data-field': 'title' }, block.title),
+      ),
+      hasAside
+        ? h(
+            'div',
+            { class: 'ca-hero__aside' },
+            optionalText('p', 'ca-hero__subtitle', block.subtitle, { 'data-field': 'subtitle' }),
+            actions,
+          )
+        : null,
+    ),
   )
 }