@cogenta/theme-portfolio 1.1.2

package/src/render/blocks/logos.ts

@@ -0,0 +1,63 @@
+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: a link whose only content
+ * is an image with alt text is already named.
+ *
+ * Rendered as a single-row ledger rather than a grid of tiles — a running
+ * mono index beside each mark, in a desaturated register that resolves to
+ * full ink only on hover or focus (`blocks.css`), which is the theme's own
+ * take on the "selected clients" strip.
+ */
+function renderItem(item: LogoItem, ctx: RenderContext, index: number): HtmlElement {
+  const logo = image(ctx, item.media, {
+    className: 'cg-logo__image',
+    altFrom: item.name,
+    variant: { fit: 'contain' },
+  })
+  return h(
+    'li',
+    { class: 'cg-logo' },
+    h(
+      'span',
+      { class: 'cg-logo__index', 'aria-hidden': 'true' },
+      String(index + 1).padStart(2, '0'),
+    ),
+    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, index) => renderItem(item, ctx, index)),
+    ),
+  )
+}

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

@@ -0,0 +1,51 @@
+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.
+ *
+ * The "Fig. 01" plate number that precedes the caption is drawn entirely
+ * from a CSS counter (`counter-increment: cg-figure` in `blocks.css`) — it
+ * is not stored data, so it renumbers itself as figures are added or
+ * removed and never needs updating here.
+ *
+ * `align` is written as a data attribute, never as a class: contract B's
+ * values are `start`/`end`, an intent that mirrors in right-to-left
+ * locales, and the skin decides what it means.
+ */
+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}`,
+    },
+    h(
+      'div',
+      { class: 'cg-figure__frame' },
+      image(ctx, block.media, {
+        className: 'cg-figure__media',
+        sizes: '(min-width: 48rem) 42rem, 100vw',
+      }),
+    ),
+    hasCaption
+      ? h(
+          'figcaption',
+          { class: 'cg-figure__caption' },
+          block.caption === undefined
+            ? null
+            : h('span', { class: 'cg-figure__plate' }, block.caption),
+          block.credit === undefined
+            ? null
+            : h('span', { class: 'cg-figure__credit', 'data-field': 'credit' }, block.credit),
+        )
+      : null,
+  )
+}

package/src/render/blocks/pricing-table.ts

@@ -0,0 +1,69 @@
+import type { PricingTableBlock, PricingTier } from '@cogenta/blocks'
+import {
+  actionLink,
+  blockHeadingTag,
+  type HeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  nestedHeadingTag,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/**
+ * `highlighted` is an editorial signal, never a colour (RFC 0001's own
+ * comment on the field): it is written as `data-highlighted="true"` for the
+ * skin to key off, and the tier additionally carries `aria-current="true"`
+ * — the closest native semantic for "the one the author means you to pick"
+ * among a set of siblings.
+ */
+function renderTier(tier: PricingTier, ctx: RenderContext, tag: HeadingTag): HtmlElement {
+  return h(
+    'li',
+    {
+      class: 'cg-pricing__tier',
+      'data-highlighted': tier.highlighted === true ? 'true' : undefined,
+      'aria-current': tier.highlighted === true ? 'true' : undefined,
+    },
+    heading(tag, { class: 'cg-pricing__name' }, tier.name),
+    h(
+      'p',
+      { class: 'cg-pricing__price' },
+      tier.price,
+      tier.interval === undefined
+        ? null
+        : h('span', { class: 'cg-pricing__interval' }, tier.interval),
+    ),
+    tier.features.length === 0
+      ? null
+      : h(
+          'ul',
+          { class: 'cg-pricing__features' },
+          tier.features.map((feature) => h('li', {}, feature)),
+        ),
+    tier.action === undefined
+      ? null
+      : h('div', { class: 'cg-pricing__action' }, actionLink(ctx, tier.action)),
+  )
+}
+
+export function renderPricingTable(block: PricingTableBlock, ctx: RenderContext): HtmlElement {
+  const hasTitle = block.title !== undefined
+  const tierTag = nestedHeadingTag('pricingTable', hasTitle)
+  return h(
+    'section',
+    { class: 'cg-block cg-pricing', 'data-block': 'pricingTable' },
+    hasTitle
+      ? heading(
+          blockHeadingTag('pricingTable') ?? 'h2',
+          { class: 'cg-pricing__title', 'data-field': 'title' },
+          block.title ?? '',
+        )
+      : null,
+    h(
+      'ul',
+      { class: 'cg-pricing__tiers' },
+      block.tiers.map((tier) => renderTier(tier, ctx, tierTag)),
+    ),
+  )
+}

package/src/render/blocks/prose.ts

@@ -0,0 +1,22 @@
+import type { ProseBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, type RenderContext, renderRichText } from '@cogenta/theme-kit'
+
+/**
+ * `prose` declares `headingLevel: 'none'`: it contributes no heading of its
+ * own. Whatever headings appear come from the rich text document, whose
+ * vocabulary starts at `h2`.
+ *
+ * The wrapper is deliberately plain — a rich text document is arbitrary
+ * editorial content, and the only honest DOM shape for arbitrary content is
+ * "here it is". The distinctive editorial treatment (a dropped first
+ * capital, an oversized `h2`, a hairline-and-number rule before each
+ * heading) lives entirely in `blocks.css`, driven off the very structure
+ * `renderRichText` already produces.
+ */
+export function renderProse(block: ProseBlock, ctx: RenderContext): HtmlElement {
+  return h(
+    'div',
+    { class: 'cg-block cg-prose', 'data-block': 'prose' },
+    renderRichText(ctx, block.body),
+  )
+}

package/src/render/blocks/quote.ts

@@ -0,0 +1,48 @@
+import type { QuoteBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+
+/**
+ * `<figure><blockquote>…</blockquote><figcaption>` is the attribution
+ * pattern the HTML spec prescribes: putting the author inside the
+ * `<blockquote>` would claim the author's name is part of what was said.
+ *
+ * Set left-aligned at display scale rather than centred — a pull quote that
+ * fills the column edge to edge, the way a magazine breaks one out of a
+ * feature. The attribution is set in the mono register, the theme's
+ * register for credits and metadata.
+ *
+ * The avatar is decorative here — the name is right beside it in text — so
+ * its media entity's alt text is expected to be empty. `image` still writes
+ * the attribute either way.
+ */
+export function renderQuote(block: QuoteBlock, ctx: RenderContext): HtmlElement {
+  const hasAttribution =
+    block.author !== undefined || block.role !== undefined || block.avatar !== undefined
+  return h(
+    'figure',
+    { class: 'cg-block cg-quote', 'data-block': 'quote' },
+    h('blockquote', { class: 'cg-quote__text' }, h('p', { 'data-field': 'text' }, block.text)),
+    hasAttribution
+      ? h(
+          'figcaption',
+          { class: 'cg-quote__attribution' },
+          block.avatar === undefined
+            ? null
+            : image(ctx, block.avatar, {
+                className: 'cg-quote__avatar',
+                variant: { width: 96, height: 96, fit: 'cover' },
+              }),
+          h(
+            'span',
+            { class: 'cg-quote__names' },
+            block.author === undefined
+              ? null
+              : h('span', { class: 'cg-quote__author', 'data-field': 'author' }, block.author),
+            block.role === undefined
+              ? null
+              : h('span', { class: 'cg-quote__role', 'data-field': 'role' }, block.role),
+          ),
+        )
+      : null,
+  )
+}

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

@@ -0,0 +1,49 @@
+import type { StatCounterBlock, StatCounterItem } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/**
+ * 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.
+ */
+function renderItem(item: StatCounterItem, index: number): 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),
+  )
+}
+
+export function renderStatCounter(block: StatCounterBlock, _ctx: RenderContext): HtmlElement {
+  return h(
+    '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)),
+    ),
+  )
+}

package/src/render/blocks/stats.ts

@@ -0,0 +1,49 @@
+import type { StatItem, StatsBlock } from '@cogenta/blocks'
+import {
+  blockHeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  type RenderContext,
+} from '@cogenta/theme-kit'
+
+/**
+ * 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.
+ */
+function renderItem(item: StatItem): HtmlElement {
+  return h(
+    'div',
+    { class: 'cg-stat' },
+    h('dt', { class: 'cg-stat__label' }, item.label),
+    h(
+      'dd',
+      { class: 'cg-stat__value' },
+      item.value,
+      item.unit === undefined ? null : h('span', { class: 'cg-stat__unit' }, item.unit),
+    ),
+  )
+}
+
+export function renderStats(block: StatsBlock, _ctx: RenderContext): HtmlElement {
+  return h(
+    '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)),
+  )
+}

package/src/render/blocks/testimonial.ts

@@ -0,0 +1,45 @@
+import type { TestimonialBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, image, type RenderContext, renderRichText } from '@cogenta/theme-kit'
+
+/**
+ * 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.
+ */
+export function renderTestimonial(block: TestimonialBlock, ctx: RenderContext): HtmlElement {
+  const { attribution } = block
+  return h(
+    'figure',
+    { class: 'cg-block cg-testimonial', 'data-block': 'testimonial' },
+    h('blockquote', { class: 'cg-testimonial__quote' }, renderRichText(ctx, block.quote)),
+    h(
+      'figcaption',
+      { class: 'cg-testimonial__attribution' },
+      attribution.avatar === undefined
+        ? null
+        : image(ctx, attribution.avatar, {
+            className: 'cg-testimonial__avatar',
+            variant: { width: 96, height: 96, fit: 'cover' },
+          }),
+      h(
+        'span',
+        { class: 'cg-testimonial__names' },
+        h('span', { class: 'cg-testimonial__name' }, attribution.name),
+        attribution.role === undefined
+          ? null
+          : h('span', { class: 'cg-testimonial__role' }, attribution.role),
+      ),
+    ),
+  )
+}

package/src/render/chrome.ts

@@ -0,0 +1,142 @@
+import {
+  type ChromeInput,
+  type ChromeNavLink,
+  type ChromeResult,
+  escapeAttribute,
+  escapeText,
+  renderBrandMark,
+  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 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.
+ *
+ * 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.
+ */
+
+function renderNavLinks(links: readonly ChromeNavLink[], className: string): string {
+  if (links.length === 0) return ''
+  const items = links
+    .filter((link) => link.href !== null || link.kind === 'submenu-placeholder')
+    .map((link, index) => {
+      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>`
+      }
+      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>`
+      )
+    })
+    .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>'
+}
+
+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 hasMenu = headerNav !== '' || headerAction !== ''
+  const nav = hasMenu
+    ? `<nav class="cg-site-header__nav" id="cg-nav" aria-label="Primary">${headerNav}${headerAction}</nav>`
+    : ''
+  const toggle = 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>`
+    : ''
+
+  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}` +
+    `</div></header>`
+
+  const tagline =
+    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>`
+
+  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>`
+
+  return { header, footer }
+}