@cogenta/theme-docs 0.3.2

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

@@ -0,0 +1,170 @@
+import type { CollectionListBlock } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  buildCollectionListQuery,
+  type ContentEntry,
+  entryDate,
+  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
+ * (`@cogenta/theme-kit`'s `buildCollectionListQuery`, shared across every
+ * theme), 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 }
+
+/**
+ * The general-purpose row: a cover image (`entryImage`, contract D
+ * `theme@1.4`) when the collection carries one, title, excerpt and date —
+ * this is what a non-docs collection placed in this block gets.
+ */
+function renderRow(entry: ContentEntry, ctx: RenderContext, tag: HeadingTag): HtmlElement {
+  const date = entryDate(entry)
+  const excerpt = entryExcerpt(entry)
+  const image = entryImage(entry, ctx)
+  return h(
+    'li',
+    { class: 'cg-list__row' },
+    image === undefined
+      ? null
+      : h(
+          'div',
+          { class: 'cg-list__thumb' },
+          renderImageSource(image, { loading: 'lazy', className: 'cg-list__thumb-image' }),
+        ),
+    h(
+      'div',
+      { class: 'cg-list__body' },
+      heading(
+        tag,
+        { class: 'cg-list__title' },
+        h('a', { class: 'cg-list__link', href: entryHref(entry, ctx) }, entryTitle(entry, ctx)),
+      ),
+      date === undefined
+        ? null
+        : h(
+            'time',
+            { class: 'cg-list__date', datetime: date },
+            new Intl.DateTimeFormat(ctx.locale, { dateStyle: 'long' }).format(new Date(date)),
+          ),
+      excerpt === undefined ? null : h('p', { class: 'cg-list__excerpt' }, excerpt),
+    ),
+  )
+}
+
+/**
+ * `doc_page`'s own layout: a compact, multi-column index grouped by the
+ * entry's own `section` field and ordered by its own `order` field within
+ * each group — neither is a valid `collectionList.sort.field` (contract B
+ * fixes that union to `id`/`createdAt`/`updatedAt`), so the theme re-groups
+ * and re-sorts the already-fetched slice itself rather than asking for a
+ * sort the contract does not offer. Sections are ordered alphabetically for
+ * a deterministic page; entries within a section fall back to the order
+ * they were fetched in when `order` is absent or not a number.
+ */
+function renderGuidesIndex(entries: readonly ContentEntry[], ctx: RenderContext): HtmlElement {
+  const groups = new Map<string, ContentEntry[]>()
+  entries.forEach((entry) => {
+    const section =
+      typeof entry.section === 'string' && entry.section !== ''
+        ? entry.section
+        : ctx.t('entry.untitled')
+    const list = groups.get(section) ?? []
+    list.push(entry)
+    groups.set(section, list)
+  })
+
+  const sortedSections = [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))
+
+  return h(
+    'div',
+    { class: 'cg-guides' },
+    sortedSections.map(([section, sectionEntries]) => {
+      const ordered = [...sectionEntries].sort((a, b) => {
+        const orderA = typeof a.order === 'number' ? a.order : Number.POSITIVE_INFINITY
+        const orderB = typeof b.order === 'number' ? b.order : Number.POSITIVE_INFINITY
+        return orderA - orderB
+      })
+      return h(
+        'div',
+        { class: 'cg-guides__section' },
+        h('h3', { class: 'cg-guides__heading' }, section),
+        h(
+          'ul',
+          { class: 'cg-guides__items' },
+          ordered.map((entry) =>
+            h(
+              'li',
+              { class: 'cg-guides__item' },
+              h(
+                'a',
+                { class: 'cg-guides__link', href: entryHref(entry, ctx) },
+                entryTitle(entry, ctx),
+              ),
+            ),
+          ),
+        ),
+      )
+    }),
+  )
+}
+
+export function renderCollectionList(
+  block: CollectionListBlock,
+  ctx: RenderContext,
+  entries: readonly ContentEntry[],
+): HtmlElement {
+  const hasTitle = block.title !== undefined
+  const entryTag = nestedHeadingTag('collectionList', hasTitle)
+  const isGuidesIndex = block.collection === 'doc_page'
+
+  const body =
+    entries.length === 0
+      ? h('p', { class: 'cg-list__empty' }, ctx.t('collection.empty'))
+      : isGuidesIndex
+        ? renderGuidesIndex(entries, ctx)
+        : h(
+            'ul',
+            { class: 'cg-list__items' },
+            entries.map((entry) => renderRow(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' && !isGuidesIndex
+      ? h(
+          'div',
+          {
+            class: 'cg-list__viewport',
+            role: 'region',
+            'aria-label': block.title ?? ctx.t('collection.carousel'),
+            tabindex: '0',
+          },
+          body,
+        )
+      : body,
+  )
+}

package/src/render/blocks/cta.ts

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

package/src/render/blocks/embed.ts

@@ -0,0 +1,94 @@
+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, no poster
+ * image fetched from the provider.
+ */
+
+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:
+      return null
+  }
+}
+
+function consentCard(block: EmbedBlock, ctx: RenderContext, reason: string): HtmlElement {
+  return h(
+    'div',
+    { class: 'cg-embed__placeholder' },
+    h('p', { class: 'cg-embed__provider', 'aria-hidden': 'true' }, block.provider),
+    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,46 @@
+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, and the expanded state announced to assistive
+ * technology all come from the browser, at zero bytes of JavaScript.
+ */
+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'
+
+/**
+ * The item's title is the link, so the link's accessible name is the
+ * feature's own name (WCAG 2.4.4) — the block carries no separate label
+ * field to write a "learn more" with anyway.
+ *
+ * `icon` names a symbol, never markup: when the name is one `renderIcon`
+ * recognises it becomes a real inline glyph, `aria-hidden` since the title
+ * already names the card. An unrecognised name keeps the bare, empty
+ * `data-icon` span for a skin/plugin to key off.
+ */
+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,39 @@
+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.
+ */
+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,61 @@
+import type { HeroBlock } from '@cogenta/blocks'
+import {
+  actionList,
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  image,
+  type RenderContext,
+  renderIcon,
+} 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.
+ *
+ * A reference-docs hero: copy on the left, a decorative search-looking
+ * prompt right under the actions (purely presentational — `aria-hidden`,
+ * no `<input>`, no `<form>` — this theme ships zero client JavaScript and a
+ * fake control that looked operable would be a worse failure than no
+ * control at all), and an optional small illustration on the right rather
+ * than a full-bleed image wash, matching the information-dense register the
+ * aesthetic direction asks for.
+ */
+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' }, 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')),
+      h(
+        'div',
+        { class: 'cg-hero__search', 'aria-hidden': 'true' },
+        renderIcon('search', { className: 'cg-hero__search-icon' }),
+        h('span', { class: 'cg-hero__search-text' }, 'Search the docs…'),
+        h('kbd', { class: 'cg-hero__search-key' }, '/'),
+      ),
+    ),
+    block.media === undefined
+      ? null
+      : h(
+          'div',
+          { class: 'cg-hero__panel' },
+          image(ctx, block.media, {
+            className: 'cg-hero__media',
+            loading: 'eager',
+            sizes: '(min-width: 64rem) 32vw, 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). The lighter-weight "as seen in" 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,36 @@
+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,
+ * and a screen reader announces the caption as belonging to the image
+ * instead of as loose text after it.
+ */
+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,
+  )
+}