@cogenta/theme-entreprise 1.1.3 → 1.4.0

package/src/render/blocks/logos.ts

@@ -7,25 +7,24 @@ import {
   image,
   type RenderContext,
 } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * A "trusted by" client strip. 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.
+ * A client register: wordmarks in greyscale, each in its own cell of a ruled
+ * table, so a dozen marks of different shapes and weights still line up.
  *
- * The restrained, grayscale-leaning treatment (`filter: grayscale()` in the
- * stylesheet) is the "held back until hovered" client-logo language the
- * aesthetic direction calls for — a `filter`, never `grayscale` baked into
- * the media itself, since the underlying asset still arrives as a real
- * `<img>` from `image()`.
+ * Contract B says the organisation's name is the accessible name of the
+ * link, so the image carries it as `alt` when the media entity has none, and
+ * no visually hidden duplicate is added. Greyscale is a `filter` in the
+ * stylesheet, never baked into the media: the same asset still renders in
+ * colour wherever a site owner uses it elsewhere.
  */
 function renderItem(item: LogoItem, ctx: RenderContext): HtmlElement {
   const logo = image(ctx, item.media, {
     className: 'cg-clients__logo',
     altFrom: item.name,
     variant: { fit: 'contain' },
+    sizes: '12rem',
   })
   return h(
     'li',
@@ -41,20 +40,37 @@ function renderItem(item: LogoItem, ctx: RenderContext): HtmlElement {
 }
 
 export function renderLogos(block: LogosBlock, ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     'section',
-    { class: 'cg-clients', 'data-block': 'logos' },
+    'logos',
+    'cg-clients',
+    {},
+    'div',
     block.title === undefined
       ? null
-      : heading(
-          blockHeadingTag('logos') ?? 'h2',
-          { class: 'cg-clients__title', 'data-field': 'title' },
-          block.title,
+      : h(
+          'div',
+          { class: 'cg-head' },
+          heading(
+            blockHeadingTag('logos') ?? 'h2',
+            { class: 'cg-head__title', 'data-field': 'title' },
+            block.title,
+          ),
         ),
     h(
       'ul',
-      { class: 'cg-clients__items' },
+      { class: 'cg-clients__items', 'data-columns': String(columnsFor(block.items.length)) },
       block.items.map((item) => renderItem(item, ctx)),
     ),
   )
 }
+
+/**
+ * How many columns the register uses on a wide screen: four when the marks
+ * fill whole rows of four, otherwise three, so a register never ends on a
+ * row of empty ruled cells when a whole-row layout exists.
+ */
+function columnsFor(count: number): number {
+  if (count <= 3) return Math.max(count, 1)
+  return count % 4 === 0 ? 4 : 3
+}

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

@@ -1,39 +1,47 @@
 import type { MediaFigureBlock } from '@cogenta/blocks'
 import { aspectRatio, type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * `<figure>`/`<figcaption>`, matching the pattern the HTML spec prescribes for
- * an image and its own caption — a `<figcaption>` outside the `<figure>` would
- * lose that association for assistive technology.
+ * An image and its caption, placed on the grid by `align`.
  *
- * The frame reads as a bordered plate with a small caption rule underneath,
- * distinct from a floated/rounded treatment: the "structured, edged"
- * language this theme uses everywhere a picture appears.
+ * `wide` gives the image nine columns and sets the caption in the three to
+ * its right, under a hairline, aligned to the image's foot, the way an
+ * annual report places an exhibit and its note. `start` and `end` do the
+ * same on a narrower image; `center` keeps the caption under the image;
+ * `full` lets the image run the full width of the page. No frame, no shadow,
+ * no rounded corner: the picture is the object.
+ *
+ * `<figure>`/`<figcaption>` keep the caption associated with the image for
+ * assistive technology, which is why the figure is the grid container itself.
  */
 export function renderMediaFigure(block: MediaFigureBlock, ctx: RenderContext): HtmlElement {
   const ratio = aspectRatio(block.ratio)
   const hasCaption = block.caption !== undefined || block.credit !== undefined
-  return h(
-    'figure',
+  return section(
+    'div',
+    'mediaFigure',
+    'cg-figure',
     {
-      class: 'cg-figure',
-      'data-block': 'mediaFigure',
       'data-align': block.align ?? 'center',
       style: ratio === undefined ? undefined : `--cg-ratio:${ratio}`,
     },
+    'figure',
     h(
       'div',
-      { class: 'cg-figure__frame' },
+      { class: 'cg-figure__media' },
       image(ctx, block.media, {
-        className: 'cg-figure__media',
-        sizes: '(min-width: 48rem) 42rem, 100vw',
+        className: 'cg-figure__image',
+        sizes: block.align === 'full' ? '100vw' : '(min-width: 64rem) 75vw, 100vw',
       }),
     ),
     hasCaption
       ? h(
           'figcaption',
           { class: 'cg-figure__caption' },
-          block.caption,
+          block.caption === undefined
+            ? null
+            : h('span', { class: 'cg-figure__text', 'data-field': 'caption' }, block.caption),
           block.credit === undefined
             ? null
             : h('span', { class: 'cg-figure__credit', 'data-field': 'credit' }, block.credit),

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

@@ -9,17 +9,18 @@ import {
   nestedHeadingTag,
   type RenderContext,
 } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * `blocks@2.0` (RFC 0001). A side-by-side plan comparison — the ledger-row
- * language this theme uses for `featureGrid` would flatten the very
- * distinction a pricing table exists to show, so tiers instead sit as a row
- * of bordered plates, one plate lifted (border + a small "recommended" rule)
- * when `highlighted` is set.
+ * `blocks@2.0` (RFC 0001). A comparison set as a ruled table rather than a
+ * row of cards: tiers stand side by side between vertical hairlines, each
+ * with its name in small capitals, the price in the display serif with
+ * tabular numerals, the inclusions as a ruled list and the action at the
+ * foot, aligned across tiers.
  *
  * `highlighted` is an editorial signal, never a colour: it becomes
- * `data-highlighted` for the stylesheet to key off, and `aria-current` so the
- * emphasis is announced, not only shown.
+ * `data-highlighted` (a heavier rule above that tier, in ink) and
+ * `aria-current`, so the emphasis is announced as well as shown.
  */
 function renderTier(tier: PricingTier, ctx: RenderContext, tag: HeadingTag): HtmlElement {
   return h(
@@ -50,7 +51,10 @@ function renderTier(tier: PricingTier, ctx: RenderContext, tag: HeadingTag): Htm
       : h(
           'div',
           { class: 'cg-pricing__action' },
-          actionLink(ctx, { ...tier.action, emphasis: tier.action.emphasis ?? 'primary' }),
+          actionLink(ctx, {
+            ...tier.action,
+            emphasis: tier.action.emphasis ?? (tier.highlighted === true ? 'primary' : 'secondary'),
+          }),
         ),
   )
 }
@@ -58,19 +62,26 @@ function renderTier(tier: PricingTier, ctx: RenderContext, tag: HeadingTag): Htm
 export function renderPricingTable(block: PricingTableBlock, ctx: RenderContext): HtmlElement {
   const hasTitle = block.title !== undefined
   const tierTag = nestedHeadingTag('pricingTable', hasTitle)
-  return h(
+  return section(
     'section',
-    { class: 'cg-pricing', 'data-block': 'pricingTable' },
+    'pricingTable',
+    'cg-pricing',
+    {},
+    'div',
     hasTitle
-      ? heading(
-          blockHeadingTag('pricingTable') ?? 'h2',
-          { class: 'cg-pricing__title', 'data-field': 'title' },
-          block.title ?? '',
+      ? h(
+          'div',
+          { class: 'cg-head' },
+          heading(
+            blockHeadingTag('pricingTable') ?? 'h2',
+            { class: 'cg-head__title', 'data-field': 'title' },
+            block.title ?? '',
+          ),
         )
       : null,
     h(
       'ul',
-      { class: 'cg-pricing__tiers' },
+      { class: 'cg-pricing__tiers', 'data-count': String(Math.min(block.tiers.length, 4)) },
       block.tiers.map((tier) => renderTier(tier, ctx, tierTag)),
     ),
   )

package/src/render/blocks/prose.ts

@@ -1,11 +1,25 @@
 import type { ProseBlock } from '@cogenta/blocks'
 import { type HtmlElement, h, type RenderContext, renderRichText } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * `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`.
+ * A reading column set on the right-hand two thirds of the grid.
+ *
+ * On a wide screen the text starts at the fifth column and holds a 66ch
+ * measure; a second-level heading inside the document hangs out into the
+ * four columns to its left (`blocks.css`), so a long page reads as a report,
+ * with its section titles in the margin, rather than as one centred column.
+ *
+ * `prose` declares `headingLevel: 'none'`: whatever headings appear come
+ * from the rich text document, whose vocabulary starts at `h2`.
  */
 export function renderProse(block: ProseBlock, ctx: RenderContext): HtmlElement {
-  return h('div', { class: 'cg-prose', 'data-block': 'prose' }, renderRichText(ctx, block.body))
+  return section(
+    'div',
+    'prose',
+    'cg-text',
+    {},
+    'div',
+    h('div', { class: 'cg-prose' }, renderRichText(ctx, block.body)),
+  )
 }

package/src/render/blocks/quote.ts

@@ -1,35 +1,39 @@
 import type { QuoteBlock } from '@cogenta/blocks'
 import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * A testimonial card, not a centred pull-quote: a bordered panel with a
- * vertical accent rule beside the quotation and the attribution set below a
- * thin divider — the shape a case-study or client-testimonial section takes
- * on a serious B2B site.
+ * An editorial quotation inside the reading column: the display serif in
+ * italic, under a hairline, with the attribution set small beneath it.
  *
- * `<figure><blockquote>…</blockquote><figcaption>` is the attribution
- * pattern the HTML spec prescribes: putting the author inside the
- * `<blockquote>` would claim the author's name was part of what was said.
+ * Quieter than `testimonial`, which is this theme's large pull quote: a
+ * `quote` belongs to the flow of a page, aligned with the prose column
+ * rather than spread across the grid, and never in a shaded box.
  *
- * The avatar is decorative here — the name sits right beside it in text —
- * so its media entity's alt text is expected to be empty; `image` still
- * writes the attribute either way (WCAG 1.1.1).
+ * `<figure><blockquote>…</blockquote><figcaption>` is the attribution pattern
+ * the HTML spec prescribes: putting the name inside the `<blockquote>` would
+ * claim it was part of what was said. The portrait is decorative (the name
+ * is right beside it), so its media entity's alt text is expected to be
+ * empty; `image` writes the attribute either way (WCAG 1.1.1).
  */
 export function renderQuote(block: QuoteBlock, ctx: RenderContext): HtmlElement {
   const hasAttribution =
     block.author !== undefined || block.role !== undefined || block.avatar !== undefined
-  return h(
+  return section(
+    'div',
+    'quote',
+    'cg-quote',
+    {},
     'figure',
-    { class: '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' },
+          { class: 'cg-quote__cite' },
           block.avatar === undefined
             ? null
             : image(ctx, block.avatar, {
-                className: 'cg-quote__avatar',
+                className: 'cg-quote__portrait',
                 variant: { width: 96, height: 96, fit: 'cover' },
               }),
           h(

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

@@ -6,40 +6,45 @@ import {
   heading,
   type RenderContext,
 } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * `blocks@2.0` (RFC 0001). Narrower than `stats` (no `unit`), and treated
- * that way here: `stats` reads as a quiet KPI strip on the page's own
- * surface, while `statCounter` is this theme's confident "impact numbers"
- * band — an accent-tinted panel of big, tabular figures, the instinct the
- * aesthetic direction already asks for on `stats` pushed one step further
- * for the narrower, single-figure shape this block offers.
+ * `blocks@2.0` (RFC 0001). Narrower than `stats` (no `unit`), and laid out as
+ * its counterpart: where `stats` is a single row between vertical rules,
+ * `statCounter` keeps its title in the left four columns and sets its
+ * figures in a two-by-two table on the right eight, each under a horizontal
+ * hairline, the way an annual report lists its headline numbers.
  *
- * A `<dl>`, exactly like `stats`: each figure is the description of its
- * label, which is what `<dt>`/`<dd>` mean. The label sits before the figure
- * in markup, the same reading-order guarantee `stats` gives (WCAG 1.3.2);
- * the stylesheet is free to paint the big figure first.
+ * A `<dl>`, with the label first in the markup for the same reading-order
+ * reason as `stats`.
  */
 function renderItem(item: StatCounterItem): HtmlElement {
   return h(
     'div',
-    { class: 'cg-kpi' },
-    h('dt', { class: 'cg-kpi__label' }, item.label),
-    h('dd', { class: 'cg-kpi__value' }, item.value),
+    { class: 'cg-counter' },
+    h('dt', { class: 'cg-counter__label' }, item.label),
+    h('dd', { class: 'cg-counter__value' }, item.value),
   )
 }
 
 export function renderStatCounter(block: StatCounterBlock, _ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     'section',
-    { class: 'cg-kpis', 'data-block': 'statCounter' },
+    'statCounter',
+    'cg-counters',
+    { 'data-titled': block.title === undefined ? 'false' : 'true' },
+    'div',
     block.title === undefined
       ? null
-      : heading(
-          blockHeadingTag('statCounter') ?? 'h2',
-          { class: 'cg-kpis__title', 'data-field': 'title' },
-          block.title,
+      : h(
+          'div',
+          { class: 'cg-head cg-head--aside' },
+          heading(
+            blockHeadingTag('statCounter') ?? 'h2',
+            { class: 'cg-head__title', 'data-field': 'title' },
+            block.title,
+          ),
         ),
-    h('dl', { class: 'cg-kpis__items' }, block.stats.map(renderItem)),
+    h('dl', { class: 'cg-counters__items' }, block.stats.map(renderItem)),
   )
 }

package/src/render/blocks/stats.ts

@@ -6,45 +6,55 @@ import {
   heading,
   type RenderContext,
 } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * The "by the numbers" strip. A description list, exactly as the canonical
- * theme uses — each figure is the description of its label, which is what
- * `<dt>`/`<dd>` mean, and it survives being read linearly — but laid out as
- * one continuous row of big, confident figures separated by vertical rules
- * (`border-inline-start` on every item but the first) rather than as
- * separate shadowed tiles: the "real KPI strip" read the aesthetic
- * direction asks for.
+ * Key figures as one typographic row between vertical rules: the figure in
+ * the display serif with lining, tabular numerals, its unit set smaller in
+ * the same face, and the label in small text beneath. No coloured band and
+ * no tiles.
  *
- * The label sits above the figure in the markup and the skin is free to
- * repaint the order visually; reading order and visual order stay
- * independent either way (WCAG 1.3.2).
+ * A description list, because each figure is the description of its label.
+ * The label comes first in the markup, so a screen reader announces what a
+ * number means before the number (WCAG 1.3.2); the stylesheet paints the
+ * figure above it.
  */
 function renderItem(item: StatItem): HtmlElement {
   return h(
     'div',
-    { class: 'cg-metric' },
-    h('dt', { class: 'cg-metric__label' }, item.label),
+    { class: 'cg-stat' },
+    h('dt', { class: 'cg-stat__label' }, item.label),
     h(
       'dd',
-      { class: 'cg-metric__value' },
+      { class: 'cg-stat__value' },
       item.value,
-      item.unit === undefined ? null : h('span', { class: 'cg-metric__unit' }, item.unit),
+      item.unit === undefined ? null : h('span', { class: 'cg-stat__unit' }, item.unit),
     ),
   )
 }
 
 export function renderStats(block: StatsBlock, _ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     'section',
-    { class: 'cg-metrics', 'data-block': 'stats' },
+    'stats',
+    'cg-stats',
+    {},
+    'div',
     block.title === undefined
       ? null
-      : heading(
-          blockHeadingTag('stats') ?? 'h2',
-          { class: 'cg-metrics__title', 'data-field': 'title' },
-          block.title,
+      : h(
+          'div',
+          { class: 'cg-head' },
+          heading(
+            blockHeadingTag('stats') ?? 'h2',
+            { class: 'cg-head__title', 'data-field': 'title' },
+            block.title,
+          ),
         ),
-    h('dl', { class: 'cg-metrics__items' }, block.items.map(renderItem)),
+    h(
+      'dl',
+      { class: 'cg-stats__items', 'data-count': String(Math.min(block.items.length, 5)) },
+      block.items.map(renderItem),
+    ),
   )
 }

package/src/render/blocks/testimonial.ts

@@ -1,40 +1,44 @@
 import type { TestimonialBlock } from '@cogenta/blocks'
 import { type HtmlElement, h, image, type RenderContext, renderRichText } from '@cogenta/theme-kit'
+import { section } from '../layout.js'
 
 /**
- * `blocks@2.0` (RFC 0001). This theme's "client success" panel — the same
- * `<figure><blockquote>…</blockquote><figcaption>` pattern `quote` uses, kept
- * consistent so the two read as siblings, but the quote itself is rich text
- * (a testimonial may carry a link or emphasis the shorter, plain-text `quote`
- * block cannot) and the attribution is the block's single grouped
- * `attribution` field rather than three loose ones.
+ * `blocks@2.0` (RFC 0001). The large pull quote: one client's words set in
+ * the display serif across ten columns, with typographic quotation marks
+ * hung in the margin, and a small square portrait beside the name.
  *
- * The avatar is decorative, exactly like `quote`'s own: the name sits right
- * beside it in text, so its media entity's alt text is expected to be empty;
- * `image` still writes the attribute either way (WCAG 1.1.1).
+ * No tinted panel, no border on one side, no italic box: the size of the
+ * type and the space around it are the emphasis. The quote is rich text, so
+ * a testimonial may carry a link or emphasis the plain-text `quote` cannot.
+ *
+ * The portrait is decorative (the name is beside it in text), so its alt
+ * text is expected to be empty; `image` writes the attribute either way.
  */
 export function renderTestimonial(block: TestimonialBlock, ctx: RenderContext): HtmlElement {
   const { attribution } = block
-  return h(
+  return section(
+    'div',
+    'testimonial',
+    'cg-pullquote',
+    {},
     'figure',
-    { class: 'cg-testimonial', 'data-block': 'testimonial' },
-    h('blockquote', { class: 'cg-testimonial__quote' }, renderRichText(ctx, block.quote)),
+    h('blockquote', { class: 'cg-pullquote__quote' }, renderRichText(ctx, block.quote)),
     h(
       'figcaption',
-      { class: 'cg-testimonial__attribution' },
+      { class: 'cg-pullquote__cite' },
       attribution.avatar === undefined
         ? null
         : image(ctx, attribution.avatar, {
-            className: 'cg-testimonial__avatar',
-            variant: { width: 96, height: 96, fit: 'cover' },
+            className: 'cg-pullquote__portrait',
+            variant: { width: 144, height: 144, fit: 'cover' },
           }),
       h(
         'span',
-        { class: 'cg-testimonial__who' },
-        h('span', { class: 'cg-testimonial__name' }, attribution.name),
+        { class: 'cg-pullquote__who' },
+        h('span', { class: 'cg-pullquote__name' }, attribution.name),
         attribution.role === undefined
           ? null
-          : h('span', { class: 'cg-testimonial__role' }, attribution.role),
+          : h('span', { class: 'cg-pullquote__role' }, attribution.role),
       ),
     ),
   )