@cogenta/theme-docs 0.3.3 → 0.5.3

package/src/render/blocks/faq.ts

@@ -1,46 +1,35 @@
-import type { FaqBlock, FaqItem } from '@cogenta/blocks'
-import {
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  type RenderContext,
-  renderRichText,
-} from '@cogenta/theme-kit'
+import type { FaqBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, nestedHeadingTag, type RenderContext } from '@cogenta/theme-kit'
+import { section, sectionHead } from '../layout.js'
+import { renderDocsRichText } from '../rich-text.js'
 
 /**
- * `<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.
+ * Questions a reader asks before reading further ("Which databases are
+ * supported"), answered in the open: no disclosure to click. The title on
+ * the first four columns, the questions and answers on the last eight in two
+ * columns of ruled items on a wide screen, each question a real heading so a
+ * screen reader's heading list reaches it.
  */
-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(
+  const tag = nestedHeadingTag('faq', 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',
+    'cd-faq',
+    { 'data-titled': block.title === undefined ? 'false' : 'true' },
+    'div',
+    sectionHead('faq', block.title),
     h(
-      'ul',
-      { class: 'cg-faq__items' },
-      block.items.map((item) => renderItem(item, ctx)),
+      'div',
+      { class: 'cd-faq__items' },
+      block.items.map((item) =>
+        h(
+          'div',
+          { class: 'cd-faq__item' },
+          h(tag, { class: 'cd-faq__question' }, item.question),
+          h('div', { class: 'cd-faq__answer cd-rich' }, renderDocsRichText(ctx, item.answer)),
+        ),
+      ),
     ),
   )
 }

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

@@ -1,67 +1,59 @@
 import type { FeatureGridBlock, FeatureItem } from '@cogenta/blocks'
 import {
-  blockHeadingTag,
-  type HeadingTag,
   type HtmlElement,
   h,
-  heading,
   href,
   nestedHeadingTag,
   type RenderContext,
   renderIcon,
 } from '@cogenta/theme-kit'
+import { optionalText, section, sectionHead } from '../layout.js'
 
 /**
- * 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.
+ * Short entries in three columns: "Start here", "Get help". No card, no tile,
+ * no background: each entry hangs from a hairline, its title is the link (an
+ * underlined arrow link when there is one), and one or two lines under it say
+ * what the reader will find. An icon, when the item names one this theme
+ * knows, is a small stroke drawing inline before the title in the secondary
+ * ink, the size of the text it sits beside.
  *
- * `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.
+ * Three columns on a desk, two on a tablet, one on a phone; four items make
+ * a row of four on a wide screen, so no row is left with an empty cell.
  */
-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' },
+function entry(item: FeatureItem, ctx: RenderContext, tag: string): HtmlElement {
+  const icon =
     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),
+      : renderIcon(item.icon, { className: 'cd-features__icon', size: 18 })
+  return h(
+    'li',
+    { class: 'cd-features__item' },
+    h(
+      tag,
+      { class: 'cd-features__title' },
+      icon,
+      item.link === undefined
+        ? h('span', {}, item.title)
+        : h('a', { class: 'cd-arrow-link', href: href(ctx, item.link) }, item.title),
+    ),
+    optionalText('p', 'cd-features__text', item.text),
   )
 }
 
 export function renderFeatureGrid(block: FeatureGridBlock, ctx: RenderContext): HtmlElement {
-  const hasTitle = block.title !== undefined
-  const itemTag = nestedHeadingTag('featureGrid', hasTitle)
-  return h(
+  const tag = nestedHeadingTag('featureGrid', block.title !== undefined)
+  const count = block.items.length
+  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',
+    'cd-features',
+    { 'data-count': String(count % 4 === 0 ? 4 : Math.min(count, 3)) },
+    'div',
+    sectionHead('featureGrid', block.title),
     h(
       'ul',
-      { class: 'cg-features__items' },
-      block.items.map((item) => renderItem(item, ctx, itemTag)),
+      { class: 'cd-features__items' },
+      block.items.map((item) => entry(item, ctx, tag)),
     ),
   )
 }

package/src/render/blocks/gallery.ts

@@ -1,39 +1,43 @@
 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.
+ * A set of screenshots or diagrams, each in the hairline frame.
+ *
+ * - `grid`: two or three columns, every frame cropped to the same 16:10 so
+ *   the rows stay level.
+ * - `masonry`: three columns that keep each picture's own proportions.
+ * - `carousel`: one row that scrolls sideways inside the container, with
+ *   scroll snapping and no script, named so a screen reader announces it as
+ *   a scrollable group.
  */
 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 carousel = block.layout === 'carousel'
+  return section(
+    'div',
+    'gallery',
+    'cd-gallery',
+    { 'data-layout': block.layout, 'data-count': String(Math.min(block.items.length, 6)) },
+    'div',
+    h(
+      'ul',
+      {
+        class: 'cd-gallery__items',
+        ...(carousel
+          ? { role: 'region', 'aria-label': ctx.t('gallery.carousel'), tabindex: 0 }
+          : {}),
+      },
+      block.items.map((item) =>
+        h(
+          'li',
+          { class: 'cd-gallery__item cd-frame' },
+          image(ctx, item.media, {
+            className: 'cd-gallery__image cd-frame__image',
+            sizes: '(min-width: 64rem) 25rem, (min-width: 40rem) 50vw, 100vw',
+          }),
+        ),
       ),
     ),
   )
-
-  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

@@ -1,61 +1,57 @@
 import type { HeroBlock } from '@cogenta/blocks'
-import {
-  actionList,
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  image,
-  type RenderContext,
-  renderIcon,
-} from '@cogenta/theme-kit'
+import { actionList, type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { optionalText } from '../layout.js'
+import { renderSearchForm } from '../search.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 documentation site: a clear statement and the search.
  *
- * 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.
+ * Left-aligned on the grid, never centred. An eyebrow, when there is one, is
+ * a quiet line above the title (a product and its version), never a badge.
+ * The title is short and set large on the first eight columns, the subtitle
+ * says in two sentences what the documentation covers, and under it the
+ * search field at its large size: a real `GET /search` form, the first thing
+ * a reader of documentation reaches for. The actions follow, the primary one
+ * as the small teal control and the rest as underlined arrow links.
+ *
+ * Media, when an editor adds one, is a diagram or a screenshot on the last
+ * five columns in the hairline frame, loaded eagerly: it is above the fold by
+ * construction. Nothing decorative stands in for it when there is none.
  */
 export function renderHero(block: HeroBlock, ctx: RenderContext): HtmlElement {
-  const tag = blockHeadingTag('hero') ?? 'h1'
+  const actions = actionList(ctx, block.actions, ctx.t('hero.actions'))
+  const media = block.media !== undefined
+
   return h(
     'section',
-    { class: 'cg-block cg-hero', 'data-block': 'hero' },
+    { class: 'cd-section cd-hero', 'data-block': 'hero', 'data-media': media ? 'true' : 'false' },
     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')),
+      { class: 'cd-container cd-hero__inner' },
       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(
+        { class: 'cd-hero__copy' },
+        optionalText('p', 'cd-hero__eyebrow', block.eyebrow, { 'data-field': 'eyebrow' }),
+        h('h1', { class: 'cd-hero__title', 'data-field': 'title' }, block.title),
+        optionalText('p', 'cd-hero__subtitle', block.subtitle, { 'data-field': 'subtitle' }),
+        h(
           'div',
-          { class: 'cg-hero__panel' },
-          image(ctx, block.media, {
-            className: 'cg-hero__media',
-            loading: 'eager',
-            sizes: '(min-width: 64rem) 32vw, 100vw',
-          }),
+          { class: 'cd-hero__search' },
+          renderSearchForm(ctx.locale, 'cd-search-hero', 'large'),
         ),
+        actions === null ? null : h('div', { class: 'cd-hero__actions' }, actions),
+      ),
+      block.media === undefined
+        ? null
+        : h(
+            'figure',
+            { class: 'cd-hero__media cd-frame' },
+            image(ctx, block.media, {
+              className: 'cd-hero__image cd-frame__image',
+              loading: 'eager',
+              sizes: '(min-width: 64rem) 30rem, 100vw',
+            }),
+          ),
+    ),
   )
 }

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

@@ -1,31 +1,31 @@
-import type { LogoStripBlock, LogoStripItem } from '@cogenta/blocks'
+import type { LogoStripBlock } from '@cogenta/blocks'
 import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { optionalText, section } from '../layout.js'
 
 /**
- * `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.
+ * A strip of wordmarks ("Runs in production at"): the caption on its own
+ * line above, then one row of marks at one height in grey, wrapping to three
+ * and then two to a row on smaller screens. A hairline above separates the
+ * strip from what precedes 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' },
+  return section(
+    'div',
+    'logoStrip',
+    'cd-strip',
+    { 'data-count': String(Math.min(block.logos.length, 6)) },
+    'div',
+    optionalText('p', 'cd-strip__caption', block.caption, { 'data-field': 'caption' }),
     h(
       'ul',
-      { class: 'cg-logo-band__items' },
-      block.logos.map((item) => renderItem(item, ctx)),
+      { class: 'cd-strip__items' },
+      block.logos.map((logo) =>
+        h(
+          'li',
+          { class: 'cd-strip__item' },
+          image(ctx, logo.media, { className: 'cd-strip__image cd-mark', sizes: '9rem' }),
+        ),
+      ),
     ),
-    block.caption === undefined
-      ? null
-      : h('figcaption', { class: 'cg-logo-band__caption', 'data-field': 'caption' }, block.caption),
   )
 }

package/src/render/blocks/logos.ts

@@ -1,52 +1,42 @@
-import type { LogoItem, LogosBlock } from '@cogenta/blocks'
-import {
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  image,
-  type RenderContext,
-} from '@cogenta/theme-kit'
+import type { LogosBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { section, sectionHead } from '../layout.js'
 
 /**
- * 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.
+ * Named organisations (the companies running the product, the platforms it
+ * integrates with) as a ruled grid: hairlines between cells, each wordmark in
+ * grey at one height, linked when the block gives an address. The
+ * organisation's name is the image's accessible name when the media library
+ * has no alt text.
+ *
+ * Wordmarks are shown in grey in light and inverted in dark, so a logo drawn
+ * in dark ink stays legible on the dark ground.
  */
-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(
+  return section(
     '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,
-        ),
+    'logos',
+    'cd-logos',
+    { 'data-count': String(Math.min(block.items.length, 6)) },
+    'div',
+    sectionHead('logos', block.title),
     h(
       'ul',
-      { class: 'cg-logos__items' },
-      block.items.map((item) => renderItem(item, ctx)),
+      { class: 'cd-logos__items' },
+      block.items.map((item) => {
+        const mark = image(ctx, item.media, {
+          className: 'cd-logos__image cd-mark',
+          altFrom: item.name,
+          sizes: '10rem',
+        })
+        return h(
+          'li',
+          { class: 'cd-logos__item' },
+          item.url === undefined
+            ? mark
+            : h('a', { class: 'cd-logos__link', href: ctx.link(item.url), rel: 'noopener' }, mark),
+        )
+      }),
     ),
   )
 }

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

@@ -1,36 +1,58 @@
 import type { MediaFigureBlock } from '@cogenta/blocks'
 import { aspectRatio, type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { optionalText } from '../layout.js'
 
 /**
- * `<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.
+ * A diagram, a screenshot or a photograph, in the hairline frame, with its
+ * caption and credit under it in the secondary ink.
+ *
+ * `align` (contract B) places the frame: `wide` takes the whole container
+ * (or the whole reading column on a documentation page), `center` the middle
+ * eight columns, `start` and `end` eight columns on either side, and `full`
+ * runs to the edges of the window, without a frame.
+ *
+ * `ratio` crops from the top edge, so an interface keeps its title bar; a
+ * focal point set in the media library still wins.
  */
+const SIZES: Readonly<Record<string, string>> = {
+  full: '100vw',
+  wide: '(min-width: 80rem) 76rem, 100vw',
+  center: '(min-width: 64rem) 50rem, 100vw',
+  start: '(min-width: 64rem) 50rem, 100vw',
+  end: '(min-width: 64rem) 50rem, 100vw',
+}
+
 export function renderMediaFigure(block: MediaFigureBlock, ctx: RenderContext): HtmlElement {
+  const align = block.align ?? 'wide'
   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,
+    'div',
+    { class: 'cd-section cd-figure', 'data-block': 'mediaFigure', 'data-align': align },
+    h(
+      'figure',
+      { class: 'cd-container cd-figure__inner' },
+      h(
+        'div',
+        {
+          class: align === 'full' ? 'cd-figure__media' : 'cd-figure__media cd-frame',
+          style: ratio === undefined ? undefined : `aspect-ratio:${ratio}`,
+          'data-ratio': ratio === undefined ? 'original' : 'fixed',
+        },
+        image(ctx, block.media, {
+          className: 'cd-figure__image cd-frame__image',
+          sizes: SIZES[align] ?? '100vw',
+        }),
+      ),
+      hasCaption
+        ? h(
+            'figcaption',
+            { class: 'cd-figure__caption' },
+            optionalText('span', 'cd-figure__text', block.caption, { 'data-field': 'caption' }),
+            optionalText('span', 'cd-figure__credit', block.credit, { 'data-field': 'credit' }),
+          )
+        : null,
+    ),
   )
 }