@cogenta/theme-docs 0.3.2 → 0.5.3

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

@@ -1,72 +1,65 @@
 import type { PricingTableBlock, PricingTier } from '@cogenta/blocks'
 import {
   actionLink,
-  blockHeadingTag,
-  type HeadingTag,
   type HtmlElement,
   h,
-  heading,
   nestedHeadingTag,
   type RenderContext,
 } from '@cogenta/theme-kit'
+import { optionalText, section, sectionHead } from '../layout.js'
+import { word } from '../strings.js'
 
 /**
- * `blocks@2.0` (RFC 0001). Bordered plates, one lifted (border + a small
- * "recommended" rule) when `highlighted` is set — an editorial signal,
- * never a colour: it becomes `data-highlighted` for the stylesheet, and
- * `aria-current` so the emphasis is announced, not only shown.
+ * Plans, the way a documentation site shows them (support plans, usage
+ * limits): columns side by side between hairlines, never cards. Each plan
+ * names itself, prints its price in tabular numerals with the interval after
+ * it, lists what it includes as ruled lines, and ends on its action. The
+ * recommended plan is marked by a rule in ink above it and a word, never by a
+ * tinted background.
  */
-function renderTier(tier: PricingTier, ctx: RenderContext, tag: HeadingTag): HtmlElement {
+function tier(item: PricingTier, ctx: RenderContext, tag: string): HtmlElement {
+  const highlighted = item.highlighted === true
   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),
+    { class: 'cd-plans__item', 'data-highlighted': highlighted ? 'true' : 'false' },
+    h(
+      'div',
+      { class: 'cd-plans__head' },
+      h(tag, { class: 'cd-plans__name' }, item.name),
+      highlighted ? h('p', { class: 'cd-plans__flag' }, word(ctx.locale, 'recommended')) : null,
+    ),
     h(
       'p',
-      { class: 'cg-pricing__price' },
-      h('span', { class: 'cg-pricing__amount' }, tier.price),
-      tier.interval === undefined
-        ? null
-        : h('span', { class: 'cg-pricing__interval' }, tier.interval),
+      { class: 'cd-plans__price' },
+      h('span', { class: 'cd-plans__amount' }, item.price),
+      optionalText('span', 'cd-plans__interval', item.interval),
     ),
-    tier.features.length === 0
+    item.features.length === 0
       ? null
       : h(
           'ul',
-          { class: 'cg-pricing__features' },
-          tier.features.map((feature) => h('li', { class: 'cg-pricing__feature' }, feature)),
+          { class: 'cd-plans__features' },
+          item.features.map((feature) => h('li', { class: 'cd-plans__feature' }, feature)),
         ),
-    tier.action === undefined
+    item.action === undefined
       ? null
-      : h(
-          'div',
-          { class: 'cg-pricing__action' },
-          actionLink(ctx, { ...tier.action, emphasis: tier.action.emphasis ?? 'primary' }),
-        ),
+      : h('div', { class: 'cd-plans__action' }, actionLink(ctx, item.action)),
   )
 }
 
 export function renderPricingTable(block: PricingTableBlock, ctx: RenderContext): HtmlElement {
-  const hasTitle = block.title !== undefined
-  const tierTag = nestedHeadingTag('pricingTable', hasTitle)
-  return h(
+  const tag = nestedHeadingTag('pricingTable', block.title !== undefined)
+  return section(
     'section',
-    { class: 'cg-block cg-pricing', 'data-block': 'pricingTable' },
-    hasTitle
-      ? heading(
-          blockHeadingTag('pricingTable') ?? 'h2',
-          { class: 'cg-pricing__title', 'data-field': 'title' },
-          block.title ?? '',
-        )
-      : null,
+    'pricingTable',
+    'cd-plans',
+    { 'data-count': String(Math.min(block.tiers.length, 4)) },
+    'div',
+    sectionHead('pricingTable', block.title),
     h(
       'ul',
-      { class: 'cg-pricing__tiers' },
-      block.tiers.map((tier) => renderTier(tier, ctx, tierTag)),
+      { class: 'cd-plans__items' },
+      block.tiers.map((item) => tier(item, ctx, tag)),
     ),
   )
 }

package/src/render/blocks/prose.ts

@@ -1,49 +1,34 @@
 import type { ProseBlock } from '@cogenta/blocks'
-import {
-  type HtmlElement,
-  type HtmlNode,
-  h,
-  type RenderContext,
-  renderRichText,
-} from '@cogenta/theme-kit'
+import { type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+import { type HeadingAnchors, headingAnchors, renderDocsRichText } from '../rich-text.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`.
+ * Running text. `prose` declares `headingLevel: 'none'`: its headings come
+ * from the rich text document, whose vocabulary starts at `h2`.
  *
- * Contract A's rich text schema (`@cogenta/schema`, frozen) has no fenced
- * "code block" node — the only code-shaped thing it can carry is a
- * paragraph whose sole span carries the `code` mark, which
- * `renderRichText` (`@cogenta/theme-kit`) already turns into
- * `<p><code>…</code></p>`. A documentation theme without a real, multi-line
- * code block would be dishonest about what it is for, so this is the one
- * place in the theme that post-processes theme-kit's own output rather than
- * writing a second rich-text renderer: a `<p>` whose only child is a bare
- * `<code>` is promoted to `<pre><code>`, everything else is untouched. The
- * transform only ever changes two tag names on an already-escaped tree — no
- * new content is invented, and R3 (a block never stores HTML) still holds,
- * since the source is still the same structured span the editor wrote.
+ * The body is set on the reading measure from the first column; code blocks,
+ * notes and reference tables are read out of the document by
+ * `renderDocsRichText` (see its own comment for the four shapes).
+ *
+ * `anchors` is the page's own set of heading ids, so the table of contents
+ * and the headings agree; a prose block rendered on its own computes its own.
  */
-function promoteCodeBlocks(nodes: readonly HtmlNode[]): readonly HtmlNode[] {
-  return nodes.map((node) => {
-    if (node.kind !== 'element') return node
-    if (
-      node.tag === 'p' &&
-      node.children.length === 1 &&
-      node.children[0]?.kind === 'element' &&
-      node.children[0].tag === 'code'
-    ) {
-      return h('pre', { class: 'cg-prose__code' }, node.children[0])
-    }
-    return node
-  })
-}
-
-export function renderProse(block: ProseBlock, ctx: RenderContext): HtmlElement {
+export function renderProse(
+  block: ProseBlock,
+  ctx: RenderContext,
+  anchors: HeadingAnchors = headingAnchors([block]),
+): HtmlElement {
   return h(
     'div',
-    { class: 'cg-block cg-prose', 'data-block': 'prose' },
-    promoteCodeBlocks(renderRichText(ctx, block.body)),
+    { class: 'cd-section cd-prose', 'data-block': 'prose' },
+    h(
+      'div',
+      { class: 'cd-container cd-prose__inner' },
+      h(
+        'div',
+        { class: 'cd-prose__body cd-rich' },
+        renderDocsRichText(ctx, block.body, { anchors: { blockKey: block._key, map: anchors } }),
+      ),
+    ),
   )
 }

package/src/render/blocks/quote.ts

@@ -1,34 +1,40 @@
 import type { QuoteBlock } from '@cogenta/blocks'
 import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { optionalText, section } from '../layout.js'
 
 /**
- * `<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.
+ * A quotation: in documentation, a line from an RFC, a maintainer or a team
+ * that runs the product. Set at the quote size on the reading measure, in
+ * real curly quotation marks drawn by the stylesheet, hanging from a rule in
+ * ink on its left; the attribution under it, with a small round portrait when
+ * there is one.
  */
 export function renderQuote(block: QuoteBlock, ctx: RenderContext): HtmlElement {
-  const hasAttribution =
-    block.author !== undefined || block.role !== undefined || block.avatar !== undefined
-  return h(
+  const hasAttribution = block.author !== undefined || block.role !== undefined
+  return section(
+    'div',
+    'quote',
+    'cd-quote',
+    {},
     'figure',
-    { class: 'cg-block cg-quote', 'data-block': 'quote' },
-    h('blockquote', { class: 'cg-quote__text' }, h('p', { 'data-field': 'text' }, block.text)),
+    h(
+      'blockquote',
+      { class: 'cd-quote__body' },
+      h('p', { class: 'cd-quote__text', 'data-field': 'text' }, block.text),
+    ),
     hasAttribution
       ? h(
           'figcaption',
-          { class: 'cg-quote__attribution' },
+          { class: 'cd-person' },
           block.avatar === undefined
             ? null
-            : image(ctx, block.avatar, {
-                className: 'cg-quote__avatar',
-                variant: { width: 96, height: 96, fit: 'cover' },
-              }),
-          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),
+            : image(ctx, block.avatar, { className: 'cd-person__avatar', sizes: '2.5rem' }),
+          h(
+            'span',
+            { class: 'cd-person__words' },
+            optionalText('span', 'cd-person__name', block.author, { 'data-field': 'author' }),
+            optionalText('span', 'cd-person__role', block.role, { 'data-field': 'role' }),
+          ),
         )
       : null,
   )

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

@@ -1,37 +1,35 @@
-import type { StatCounterBlock, StatCounterItem } from '@cogenta/blocks'
-import {
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  type RenderContext,
-} from '@cogenta/theme-kit'
+import type { StatCounterBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+import { section, sectionHead } from '../layout.js'
 
 /**
- * `blocks@2.0` (RFC 0001). A `<dl>`, exactly like `stats`: the label sits
- * before the figure in markup (WCAG 1.3.2); the stylesheet paints the big
- * figure first.
+ * A row of counts ("Releases this year", "Supported runtimes"): the same
+ * ruled, tabular register as `stats`, without units. Nothing counts up on
+ * scroll; the figure is simply printed.
  */
-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),
-  )
-}
-
 export function renderStatCounter(block: StatCounterBlock, _ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     'section',
-    { class: 'cg-block cg-kpis', 'data-block': 'statCounter' },
-    block.title === undefined
-      ? null
-      : heading(
-          blockHeadingTag('statCounter') ?? 'h2',
-          { class: 'cg-kpis__title', 'data-field': 'title' },
-          block.title,
+    'statCounter',
+    'cd-figures',
+    { 'data-count': String(Math.min(block.stats.length, 4)) },
+    'div',
+    sectionHead('statCounter', block.title),
+    h(
+      'dl',
+      { class: 'cd-figures__items' },
+      block.stats.map((stat) =>
+        h(
+          'div',
+          { class: 'cd-figures__item' },
+          h('dt', { class: 'cd-figures__label' }, stat.label),
+          h(
+            'dd',
+            { class: 'cd-figures__value' },
+            h('span', { class: 'cd-figures__number' }, stat.value),
+          ),
         ),
-    h('dl', { class: 'cg-kpis__items' }, block.stats.map(renderItem)),
+      ),
+    ),
   )
 }

package/src/render/blocks/stats.ts

@@ -1,38 +1,41 @@
-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. */
-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),
-    ),
-  )
-}
+import type { StatsBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+import { optionalText, section, sectionHead } from '../layout.js'
 
+/**
+ * Figures the way a benchmark or a limits page prints them: a ruled row of
+ * up to four columns, each value in tabular numerals with its unit smaller on
+ * the same baseline, and a one-line label under it. The rule above each
+ * figure is the only structure; there is no box behind the row.
+ *
+ * A `<dl>`, since each figure is the value of its label; the label comes
+ * first in the markup (so it is announced first) and is drawn under the
+ * figure.
+ */
 export function renderStats(block: StatsBlock, _ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     '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,
+    'stats',
+    'cd-figures',
+    { 'data-count': String(Math.min(block.items.length, 4)) },
+    'div',
+    sectionHead('stats', block.title),
+    h(
+      'dl',
+      { class: 'cd-figures__items' },
+      block.items.map((item) =>
+        h(
+          'div',
+          { class: 'cd-figures__item' },
+          h('dt', { class: 'cd-figures__label' }, item.label),
+          h(
+            'dd',
+            { class: 'cd-figures__value' },
+            h('span', { class: 'cd-figures__number' }, item.value),
+            optionalText('span', 'cd-figures__unit', item.unit),
+          ),
         ),
-    h('dl', { class: 'cg-stats__items' }, block.items.map(renderItem)),
+      ),
+    ),
   )
 }

package/src/render/blocks/testimonial.ts

@@ -1,35 +1,34 @@
 import type { TestimonialBlock } from '@cogenta/blocks'
-import { type HtmlElement, h, image, type RenderContext, renderRichText } from '@cogenta/theme-kit'
+import { type HtmlElement, h, image, type RenderContext } from '@cogenta/theme-kit'
+import { optionalText, section } from '../layout.js'
+import { renderDocsRichText } from '../rich-text.js'
 
 /**
- * `blocks@2.0` (RFC 0001). The same `<figure><blockquote>…</blockquote>
- * <figcaption>` pattern `quote` uses, kept consistent so the two read as
- * siblings — the quote itself is rich text here, and the attribution is
- * the block's single grouped `attribution` field rather than three loose
- * ones.
+ * One person's account of using the product: the same register as `quote`
+ * (a rule in ink on the left, real quotation marks), with rich text, so a
+ * testimonial can hold a second paragraph or a command in `code`. The first
+ * paragraph is set at the quote size, the rest at the reading size.
  */
 export function renderTestimonial(block: TestimonialBlock, ctx: RenderContext): HtmlElement {
   const { attribution } = block
-  return h(
+  return section(
+    'div',
+    'testimonial',
+    'cd-testimonial',
+    {},
     'figure',
-    { class: 'cg-block cg-testimonial', 'data-block': 'testimonial' },
-    h('blockquote', { class: 'cg-testimonial__quote' }, renderRichText(ctx, block.quote)),
+    h('blockquote', { class: 'cd-testimonial__quote' }, renderDocsRichText(ctx, block.quote)),
     h(
       'figcaption',
-      { class: 'cg-testimonial__attribution' },
+      { class: 'cd-person' },
       attribution.avatar === undefined
         ? null
-        : image(ctx, attribution.avatar, {
-            className: 'cg-testimonial__avatar',
-            variant: { width: 96, height: 96, fit: 'cover' },
-          }),
+        : image(ctx, attribution.avatar, { className: 'cd-person__avatar', sizes: '2.5rem' }),
       h(
         'span',
-        { class: 'cg-testimonial__who' },
-        h('span', { class: 'cg-testimonial__name' }, attribution.name),
-        attribution.role === undefined
-          ? null
-          : h('span', { class: 'cg-testimonial__role' }, attribution.role),
+        { class: 'cd-person__words' },
+        h('span', { class: 'cd-person__name' }, attribution.name),
+        optionalText('span', 'cd-person__role', attribution.role),
       ),
     ),
   )