@cogenta/theme-association 0.3.2

package/src/render/blocks/collection-list.ts

@@ -0,0 +1,144 @@
+import type { CollectionListBlock } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  buildCollectionListQuery,
+  type ContentEntry,
+  entryExcerpt,
+  entryHref,
+  entryImage,
+  entryTitle,
+  type HeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  nestedHeadingTag,
+  type RenderContext,
+  renderImageSource,
+} from '@cogenta/theme-kit'
+
+/**
+ * The only block of the seventeen that reads data at render time — contract
+ * B marks it `runtime: 'server'` for that reason. The read is *not* done
+ * here: `query` builds the request from the block's own fields, the caller
+ * awaits `ctx.content.list(...)` before rendering starts, and this function
+ * stays a pure function of the entries handed to it.
+ */
+export { buildCollectionListQuery as query }
+
+/** A string field, read straight off the raw entry — never invented. */
+function stringField(entry: ContentEntry, field: string): string | undefined {
+  const value = entry[field]
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined
+}
+
+/**
+ * "Upcoming events" cards are what this block is built around: a rounded,
+ * shadowed card whose left edge carries a big day/month badge, built
+ * straight from the entry's own `date` field when it has one — never from
+ * `entryDate` (which reads `publishedAt`/`createdAt`, a system field with a
+ * different meaning for an event than the date it actually happens on).
+ * `location` is read the same direct way, since it too is a schema field no
+ * shared helper names.
+ *
+ * An entry from a collection with neither `date` nor `location` — any other
+ * collection a site points a `collectionList` at — falls back to the same
+ * title/excerpt/cover row every other theme's list block shows, so this
+ * block stays generically usable, not association-only.
+ */
+function renderEntry(entry: ContentEntry, ctx: RenderContext, tag: HeadingTag): HtmlElement {
+  const rawDate = stringField(entry, 'date')
+  const parsed = rawDate === undefined ? null : new Date(rawDate)
+  const hasDate = parsed !== null && !Number.isNaN(parsed.getTime())
+  const location = stringField(entry, 'location')
+  const excerpt = entryExcerpt(entry)
+  const cover = entryImage(entry, ctx, { width: 320, height: 320, fit: 'cover' })
+
+  const badge = !hasDate
+    ? null
+    : h(
+        'time',
+        { class: 'cg-event-card__date', datetime: rawDate },
+        h('span', { class: 'cg-event-card__day' }, String((parsed as Date).getDate())),
+        h(
+          'span',
+          { class: 'cg-event-card__month' },
+          new Intl.DateTimeFormat(ctx.locale, { month: 'short' }).format(parsed as Date),
+        ),
+        h(
+          'span',
+          { class: 'cg-event-card__time' },
+          new Intl.DateTimeFormat(ctx.locale, { hour: 'numeric', minute: '2-digit' }).format(
+            parsed as Date,
+          ),
+        ),
+      )
+
+  return h(
+    'li',
+    { class: 'cg-event-card' },
+    badge,
+    cover === undefined
+      ? null
+      : h('div', { class: 'cg-event-card__cover' }, renderImageSource(cover, { loading: 'lazy' })),
+    h(
+      'div',
+      { class: 'cg-event-card__body' },
+      location === undefined ? null : h('p', { class: 'cg-event-card__location' }, location),
+      heading(
+        tag,
+        { class: 'cg-event-card__title' },
+        h(
+          'a',
+          { class: 'cg-event-card__link', href: entryHref(entry, ctx) },
+          entryTitle(entry, ctx),
+        ),
+      ),
+      excerpt === undefined ? null : h('p', { class: 'cg-event-card__excerpt' }, excerpt),
+    ),
+  )
+}
+
+export function renderCollectionList(
+  block: CollectionListBlock,
+  ctx: RenderContext,
+  entries: readonly ContentEntry[],
+): HtmlElement {
+  const hasTitle = block.title !== undefined
+  const entryTag = nestedHeadingTag('collectionList', hasTitle)
+  const items =
+    entries.length === 0
+      ? h('p', { class: 'cg-list__empty' }, ctx.t('collection.empty'))
+      : h(
+          'ul',
+          { class: 'cg-list__items cg-event-cards' },
+          entries.map((entry) => renderEntry(entry, ctx, entryTag)),
+        )
+
+  return h(
+    'section',
+    {
+      class: 'cg-block cg-list',
+      'data-block': 'collectionList',
+      'data-layout': block.layout,
+    },
+    hasTitle
+      ? heading(
+          blockHeadingTag('collectionList') ?? 'h2',
+          { class: 'cg-list__title-heading', 'data-field': 'title' },
+          block.title ?? '',
+        )
+      : null,
+    block.layout === 'carousel'
+      ? h(
+          'div',
+          {
+            class: 'cg-list__viewport',
+            role: 'region',
+            'aria-label': block.title ?? ctx.t('collection.carousel'),
+            tabindex: '0',
+          },
+          items,
+        )
+      : items,
+  )
+}

package/src/render/blocks/cta.ts

@@ -0,0 +1,37 @@
+import type { CtaBlock } from '@cogenta/blocks'
+import {
+  actionList,
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/**
+ * 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.
+ */
+export function renderCta(block: CtaBlock, ctx: RenderContext): HtmlElement {
+  return h(
+    'section',
+    { class: 'cg-block cg-cta', 'data-block': 'cta' },
+    h(
+      'div',
+      { class: 'cg-cta__inner' },
+      heading(
+        blockHeadingTag('cta') ?? 'h2',
+        { class: 'cg-cta__title', 'data-field': 'title' },
+        block.title,
+      ),
+      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),
+    ),
+  )
+}

package/src/render/blocks/embed.ts

@@ -0,0 +1,98 @@
+import type { EmbedBlock } from '@cogenta/blocks'
+import { aspectRatio, type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+
+/**
+ * Nothing here contacts a third party before the visitor has consented.
+ *
+ * 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.
+ */
+
+/** `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
+  const segments = url.pathname.split('/').filter((segment) => segment !== '')
+
+  switch (provider) {
+    case 'youtube': {
+      const id = url.hostname.endsWith('youtu.be')
+        ? segments[0]
+        : (url.searchParams.get('v') ?? segments[1])
+      return id === undefined || id === null ? null : `https://www.youtube-nocookie.com/embed/${id}`
+    }
+    case 'vimeo': {
+      const id = segments.find((segment) => /^\d+$/.test(segment))
+      return id === undefined ? null : `https://player.vimeo.com/video/${id}`
+    }
+    case 'dailymotion': {
+      const id = url.hostname.endsWith('dai.ly') ? segments[0] : segments[segments.length - 1]
+      return id === undefined ? null : `https://geo.dailymotion.com/player.html?video=${id}`
+    }
+    case 'spotify': {
+      const [kind, id] = segments
+      return kind === undefined || id === undefined
+        ? null
+        : `https://open.spotify.com/embed/${kind}/${id}`
+    }
+    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.
+      return null
+  }
+}
+
+function consentCard(block: EmbedBlock, ctx: RenderContext, reason: string): HtmlElement {
+  return h(
+    'div',
+    { class: 'cg-embed__placeholder' },
+    h('p', { class: 'cg-embed__notice' }, reason),
+    h(
+      'a',
+      {
+        class: 'cg-embed__link',
+        href: ctx.link(block.url),
+        rel: 'noopener noreferrer nofollow',
+      },
+      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)
+  const ratio = aspectRatio(block.ratio) ?? '16 / 9'
+
+  return h(
+    'div',
+    {
+      class: 'cg-block cg-embed',
+      'data-block': 'embed',
+      'data-provider': block.provider,
+      'data-consent': block.consentRequired ? 'required' : 'not-required',
+      style: `--cg-ratio:${ratio}`,
+    },
+    source === null
+      ? consentCard(
+          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,
+        }),
+  )
+}

package/src/render/blocks/faq.ts

@@ -0,0 +1,52 @@
+import type { FaqBlock, FaqItem } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  type RenderContext,
+  renderRichText,
+} from '@cogenta/theme-kit'
+
+/**
+ * `<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.
+ */
+function renderItem(item: FaqItem, ctx: RenderContext): 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)),
+    ),
+  )
+}
+
+export function renderFaq(block: FaqBlock, ctx: RenderContext): HtmlElement {
+  return h(
+    '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,
+        ),
+    h(
+      'ul',
+      { class: 'cg-faq__items' },
+      block.items.map((item) => renderItem(item, ctx)),
+    ),
+  )
+}

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

@@ -0,0 +1,67 @@
+import type { FeatureGridBlock, FeatureItem } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  type HeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  href,
+  nestedHeadingTag,
+  type RenderContext,
+  renderIcon,
+} from '@cogenta/theme-kit'
+
+/**
+ * "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.
+ *
+ * `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.
+ */
+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),
+        )
+  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),
+  )
+}
+
+export function renderFeatureGrid(block: FeatureGridBlock, ctx: RenderContext): HtmlElement {
+  const hasTitle = block.title !== undefined
+  const itemTag = nestedHeadingTag('featureGrid', hasTitle)
+  return h(
+    'section',
+    { class: 'cg-block cg-features', 'data-block': 'featureGrid' },
+    hasTitle
+      ? heading(
+          blockHeadingTag('featureGrid') ?? 'h2',
+          { class: 'cg-features__title', 'data-field': 'title' },
+          block.title ?? '',
+        )
+      : null,
+    h(
+      'ul',
+      { class: 'cg-features__items' },
+      block.items.map((item) => renderItem(item, ctx, itemTag)),
+    ),
+  )
+}

package/src/render/blocks/gallery.ts

@@ -0,0 +1,47 @@
+import type { GalleryBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+
+/**
+ * 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).
+ *
+ * `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.
+ */
+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' }),
+      ),
+    ),
+  )
+
+  return h(
+    'section',
+    {
+      class: 'cg-block cg-gallery',
+      'data-block': 'gallery',
+      'data-layout': block.layout,
+    },
+    block.layout === 'carousel'
+      ? h(
+          'div',
+          {
+            class: 'cg-gallery__viewport',
+            role: 'region',
+            'aria-label': ctx.t('gallery.carousel'),
+            tabindex: '0',
+          },
+          items,
+        )
+      : items,
+  )
+}

package/src/render/blocks/hero.ts

@@ -0,0 +1,60 @@
+import type { HeroBlock } from '@cogenta/blocks'
+import {
+  actionList,
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  image,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/**
+ * The hero carries the page's `h1` (contract B: `headingLevel: 'h1'`), so
+ * `renderPage` relies on it to avoid emitting a second one.
+ *
+ * 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.
+ */
+export function renderHero(block: HeroBlock, ctx: RenderContext): HtmlElement {
+  const tag = blockHeadingTag('hero') ?? 'h1'
+  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')),
+    ),
+    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.
+          image(ctx, block.media, {
+            className: 'cg-hero__media',
+            loading: 'eager',
+            sizes: '(min-width: 60rem) 44vw, 100vw',
+          }),
+        ),
+  )
+}

package/src/render/blocks/logo-strip.ts

@@ -0,0 +1,31 @@
+import type { LogoStripBlock, LogoStripItem } from '@cogenta/blocks'
+import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+
+/**
+ * `blocks@2.0` (RFC 0001). "Our partners" — the lighter-weight social-proof
+ * row next to `logos`: no per-logo name or link, so no accessible-name field
+ * to require — each image's own alt text (set once, in the media library)
+ * names it.
+ */
+function renderItem(item: LogoStripItem, ctx: RenderContext): HtmlElement {
+  return h(
+    'li',
+    { class: 'cg-logo-band__item' },
+    image(ctx, item.media, { className: 'cg-logo-band__image', variant: { fit: 'contain' } }),
+  )
+}
+
+export function renderLogoStrip(block: LogoStripBlock, ctx: RenderContext): HtmlElement {
+  return h(
+    'figure',
+    { class: 'cg-block cg-logo-band', 'data-block': 'logoStrip' },
+    h(
+      'ul',
+      { class: 'cg-logo-band__items' },
+      block.logos.map((item) => renderItem(item, ctx)),
+    ),
+    block.caption === undefined
+      ? null
+      : h('figcaption', { class: 'cg-logo-band__caption', 'data-field': 'caption' }, block.caption),
+  )
+}

package/src/render/blocks/logos.ts

@@ -0,0 +1,52 @@
+import type { LogoItem, LogosBlock } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  image,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/**
+ * Contract B says the organisation's name **is** the accessible name of the
+ * link. So the logo image carries it as alt text when the media entity has
+ * none, and no visually hidden duplicate is added.
+ */
+function renderItem(item: LogoItem, ctx: RenderContext): HtmlElement {
+  const logo = image(ctx, item.media, {
+    className: 'cg-logo__image',
+    altFrom: item.name,
+    variant: { fit: 'contain' },
+  })
+  return h(
+    'li',
+    { class: 'cg-logo' },
+    item.url === undefined
+      ? logo
+      : h(
+          'a',
+          { class: 'cg-logo__link', href: ctx.link(item.url), rel: 'noopener noreferrer' },
+          logo,
+        ),
+  )
+}
+
+export function renderLogos(block: LogosBlock, ctx: RenderContext): HtmlElement {
+  return h(
+    'section',
+    { class: 'cg-block cg-logos', 'data-block': 'logos' },
+    block.title === undefined
+      ? null
+      : heading(
+          blockHeadingTag('logos') ?? 'h2',
+          { class: 'cg-logos__title', 'data-field': 'title' },
+          block.title,
+        ),
+    h(
+      'ul',
+      { class: 'cg-logos__items' },
+      block.items.map((item) => renderItem(item, ctx)),
+    ),
+  )
+}

package/src/render/blocks/media-figure.ts

@@ -0,0 +1,38 @@
+import type { MediaFigureBlock } from '@cogenta/blocks'
+import { aspectRatio, type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+
+/**
+ * `<figure>`/`<figcaption>` rather than a div and a paragraph: the
+ * association between the picture and its caption is then in the markup.
+ *
+ * The media sits in a big rounded card (`cg-figure__media`, `--cg-radius-lg`)
+ * with a soft shadow, matching the hero's own frame treatment rather than a
+ * hard-edged photo.
+ */
+export function renderMediaFigure(block: MediaFigureBlock, ctx: RenderContext): HtmlElement {
+  const ratio = aspectRatio(block.ratio)
+  const hasCaption = block.caption !== undefined || block.credit !== undefined
+  return h(
+    'figure',
+    {
+      class: 'cg-block cg-figure',
+      'data-block': 'mediaFigure',
+      'data-align': block.align ?? 'center',
+      style: ratio === undefined ? undefined : `--cg-ratio:${ratio}`,
+    },
+    image(ctx, block.media, {
+      className: 'cg-figure__media',
+      sizes: '(min-width: 45rem) 40rem, 100vw',
+    }),
+    hasCaption
+      ? h(
+          'figcaption',
+          { class: 'cg-figure__caption' },
+          block.caption,
+          block.credit === undefined
+            ? null
+            : h('span', { class: 'cg-figure__credit', 'data-field': 'credit' }, block.credit),
+        )
+      : null,
+  )
+}