@cogenta/theme-docs 0.3.3 → 0.5.3

package/dist/src/render/widget-areas.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The widget areas this theme names (contract D `theme@1.6`). Declaring them
+ * is what tells the host this theme draws the footer columns inside its own
+ * footer; the page areas are placed by the host in the shared
+ * `cg-sidebar-layout` markup, which `styles/widgets.css` sets on this theme's
+ * own documentation grid.
+ *
+ * A documentation page already has two columns of its own beside the
+ * article: the navigation on the left and "On this page" on the right. The
+ * sidebar never becomes a fourth column next to them. It is the right-hand
+ * rail, shared with "On this page": the contents stay in view while the page
+ * is read, and the widgets sit at the foot of the rail, level with the end of
+ * the article, where a reader who finished the page looks for help and for
+ * what comes next. On a page without its own contents, and beside search
+ * results or an archive, the widgets are the rail.
+ */
+export declare const widgetAreas: readonly {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+}[];
+//# sourceMappingURL=widget-areas.d.ts.map

package/dist/src/render/widget-areas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-areas.d.ts","sourceRoot":"","sources":["../../../src/render/widget-areas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B,EAYA,CAAA"}

package/dist/src/render/widget-areas.js

@@ -0,0 +1,29 @@
+/**
+ * The widget areas this theme names (contract D `theme@1.6`). Declaring them
+ * is what tells the host this theme draws the footer columns inside its own
+ * footer; the page areas are placed by the host in the shared
+ * `cg-sidebar-layout` markup, which `styles/widgets.css` sets on this theme's
+ * own documentation grid.
+ *
+ * A documentation page already has two columns of its own beside the
+ * article: the navigation on the left and "On this page" on the right. The
+ * sidebar never becomes a fourth column next to them. It is the right-hand
+ * rail, shared with "On this page": the contents stay in view while the page
+ * is read, and the widgets sit at the foot of the rail, level with the end of
+ * the article, where a reader who finished the page looks for help and for
+ * what comes next. On a page without its own contents, and beside search
+ * results or an archive, the widgets are the rail.
+ */
+export const widgetAreas = [
+    {
+        id: 'sidebar',
+        label: 'Page rail',
+        description: 'The right-hand rail: under “On this page” and level with the end of a documentation page, beside search results and archives.',
+    },
+    {
+        id: 'content-after',
+        label: 'After the page',
+        description: 'In the reading column, after a page and its previous and next links.',
+    },
+];
+//# sourceMappingURL=widget-areas.js.map

package/dist/src/render/widget-areas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-areas.js","sourceRoot":"","sources":["../../../src/render/widget-areas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,WAAW,GAIlB;IACJ;QACE,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,WAAW;QAClB,WAAW,EACT,+HAA+H;KAClI;IACD;QACE,EAAE,EAAE,eAAe;QACnB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EAAE,sEAAsE;KACpF;CACF,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cogenta/theme-docs",
-  "version": "0.3.3",
+  "version": "0.5.3",
   "description": "A dense, reference-first documentation theme for Cogenta: a sticky sidebar-navigated doc layout, real code blocks, and a genuine dark mode — zero client JavaScript.",
   "license": "MPL-2.0",
   "type": "module",
@@ -36,9 +36,9 @@
     "directory": "packages/theme-docs"
   },
   "dependencies": {
-    "@cogenta/render": "0.2.4",
-    "@cogenta/theme-kit": "0.3.3",
-    "@cogenta/blocks": "1.0.4"
+    "@cogenta/blocks": "1.1.3",
+    "@cogenta/theme-kit": "0.5.3",
+    "@cogenta/render": "0.3.5"
   },
   "peerDependencies": {
     "astro": "^7.2.1"

package/src/index.ts

@@ -17,4 +17,6 @@ export * from './render/blocks/stats.js'
 export * from './render/blocks/testimonial.js'
 export * from './render/chrome.js'
 export * from './render/render-block.js'
+export { headingAnchors, keyChord, slugify } from './render/rich-text.js'
 export * from './render/term-archive.js'
+export * from './render/widget-areas.js'

package/src/render/blocks/accordion.ts

@@ -1,51 +1,40 @@
-import type { AccordionBlock, AccordionItem } from '@cogenta/blocks'
-import {
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  type RenderContext,
-  renderRichText,
-} from '@cogenta/theme-kit'
+import type { AccordionBlock } from '@cogenta/blocks'
+import { type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+import { section, sectionHead } from '../layout.js'
+import { renderDocsRichText } from '../rich-text.js'
 
 /**
- * `blocks@2.0` (RFC 0001). Reuses `faq`'s zero-JS `<details>`/`<summary>`
- * mechanics with a markup vocabulary of its own (`cg-panels`, not
- * `cg-faq`), a rotating chevron mark rather than a numbered row.
+ * Detail a reader opens when they need it (every error code, the fields of a
+ * response) as ruled rows on the reading measure.
+ *
+ * Every row is a `<details>`: it opens without a script, and the browser's
+ * own find-in-page still reaches a closed answer. The plus that turns into a
+ * minus is two hairlines drawn by the stylesheet, not a glyph.
  */
-function renderItem(item: AccordionItem, ctx: RenderContext): HtmlElement {
-  return h(
-    'li',
-    { class: 'cg-panels__item' },
-    h(
-      'details',
-      { class: 'cg-panels__details' },
-      h(
-        'summary',
-        { class: 'cg-panels__question' },
-        h('span', { class: 'cg-panels__question-text' }, item.question),
-        h('span', { class: 'cg-panels__chevron', 'aria-hidden': 'true' }),
-      ),
-      h('div', { class: 'cg-panels__answer' }, renderRichText(ctx, item.answer)),
-    ),
-  )
-}
-
 export function renderAccordion(block: AccordionBlock, ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     'section',
-    { class: 'cg-block cg-panels', 'data-block': 'accordion' },
-    block.title === undefined
-      ? null
-      : heading(
-          blockHeadingTag('accordion') ?? 'h2',
-          { class: 'cg-panels__title', 'data-field': 'title' },
-          block.title,
-        ),
+    'accordion',
+    'cd-accordion',
+    {},
+    'div',
+    sectionHead('accordion', block.title),
     h(
-      'ul',
-      { class: 'cg-panels__items' },
-      block.items.map((item) => renderItem(item, ctx)),
+      'div',
+      { class: 'cd-accordion__items' },
+      block.items.map((item) =>
+        h(
+          'details',
+          { class: 'cd-accordion__item' },
+          h(
+            'summary',
+            { class: 'cd-accordion__summary' },
+            h('span', { class: 'cd-accordion__question' }, item.question),
+            h('span', { class: 'cd-accordion__sign', 'aria-hidden': 'true' }),
+          ),
+          h('div', { class: 'cd-accordion__answer cd-rich' }, renderDocsRichText(ctx, item.answer)),
+        ),
+      ),
     ),
   )
 }

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

@@ -1,6 +1,5 @@
 import type { CollectionListBlock } from '@cogenta/blocks'
 import {
-  blockHeadingTag,
   buildCollectionListQuery,
   type ContentEntry,
   entryDate,
@@ -8,119 +7,122 @@ import {
   entryHref,
   entryImage,
   entryTitle,
-  type HeadingTag,
   type HtmlElement,
   h,
-  heading,
   nestedHeadingTag,
+  type QueryRequest,
   type RenderContext,
   renderImageSource,
 } from '@cogenta/theme-kit'
+import { DOC_PAGE_COLLECTION, groupDocPages } from '../doc-index.js'
+import { longDate, section, sectionHead } from '../layout.js'
 
 /**
- * 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.
+ * A list of entries, read by what they are as much as by the layout chosen.
+ *
+ * - **Doc pages: the documentation, by section.** The home page's "Browse"
+ *   block. One column per section (sections in the order the documentation
+ *   reads, pages by their own `order`), the section named in a small heading
+ *   over a hairline, its pages as a plain column of links. Up to four columns
+ *   on a desk, two on a tablet, one on a phone. The layout an editor picked
+ *   is ignored on purpose: a table of contents is not a carousel.
+ * - **`list`: an index.** Ruled rows: the title, the summary under it, and a
+ *   date on the right when the entry has one, in tabular numerals.
+ * - **`grid`**: three columns without cards. A picture, when there is one,
+ *   in the hairline frame at 16:10, then the title, the summary and the date.
+ * - **`carousel`**: the same items in one row that scrolls sideways.
+ *
+ * Each picture repeats the link of its title, so it is taken out of the tab
+ * order and hidden from assistive technology: one link per entry.
  */
-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))
 
+function renderDocIndex(
+  entries: readonly ContentEntry[],
+  ctx: RenderContext,
+  tag: string,
+): HtmlElement {
+  const groups = groupDocPages(entries, ctx)
   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(
+    { class: 'cd-browse', 'data-count': String(Math.min(groups.length, 4)) },
+    groups.map((group) =>
+      h(
         'div',
-        { class: 'cg-guides__section' },
-        h('h3', { class: 'cg-guides__heading' }, section),
+        { class: 'cd-browse__group' },
+        h(tag, { class: 'cd-browse__heading' }, group.section),
         h(
           'ul',
-          { class: 'cg-guides__items' },
-          ordered.map((entry) =>
+          { class: 'cd-browse__links' },
+          group.entries.map((entry) =>
             h(
               'li',
-              { class: 'cg-guides__item' },
+              { class: 'cd-browse__item' },
               h(
                 'a',
-                { class: 'cg-guides__link', href: entryHref(entry, ctx) },
+                { class: 'cd-browse__link', href: entryHref(entry, ctx) },
                 entryTitle(entry, ctx),
               ),
             ),
           ),
         ),
-      )
-    }),
+      ),
+    ),
+  )
+}
+
+function dateOf(entry: ContentEntry, ctx: RenderContext, className: string): HtmlElement | null {
+  const date = entryDate(entry)
+  if (date === undefined) return null
+  return h('time', { class: className, datetime: date }, longDate(date, ctx.locale))
+}
+
+function indexRow(entry: ContentEntry, ctx: RenderContext, tag: string): HtmlElement {
+  const excerpt = entryExcerpt(entry)
+  return h(
+    'li',
+    { class: 'cd-index__item' },
+    h(
+      'div',
+      { class: 'cd-index__words' },
+      h(
+        tag,
+        { class: 'cd-index__title' },
+        h('a', { class: 'cd-index__link', href: entryHref(entry, ctx) }, entryTitle(entry, ctx)),
+      ),
+      excerpt === undefined ? null : h('p', { class: 'cd-index__text' }, excerpt),
+    ),
+    dateOf(entry, ctx, 'cd-index__date'),
+  )
+}
+
+function card(entry: ContentEntry, ctx: RenderContext, tag: string): HtmlElement {
+  const excerpt = entryExcerpt(entry)
+  const source = entryImage(entry, ctx)
+  return h(
+    'li',
+    { class: 'cd-cards__item' },
+    source === undefined
+      ? null
+      : h(
+          'a',
+          {
+            class: 'cd-cards__media cd-frame',
+            href: entryHref(entry, ctx),
+            tabindex: -1,
+            'aria-hidden': 'true',
+          },
+          renderImageSource(source, {
+            className: 'cd-frame__image',
+            sizes: '(min-width: 64rem) 24rem, (min-width: 40rem) 50vw, 100vw',
+          }),
+        ),
+    h(
+      tag,
+      { class: 'cd-cards__title' },
+      h('a', { class: 'cd-cards__link', href: entryHref(entry, ctx) }, entryTitle(entry, ctx)),
+    ),
+    excerpt === undefined ? null : h('p', { class: 'cd-cards__text' }, excerpt),
+    dateOf(entry, ctx, 'cd-cards__date'),
   )
 }
 
@@ -129,42 +131,49 @@ export function renderCollectionList(
   ctx: RenderContext,
   entries: readonly ContentEntry[],
 ): HtmlElement {
-  const hasTitle = block.title !== undefined
-  const entryTag = nestedHeadingTag('collectionList', hasTitle)
-  const isGuidesIndex = block.collection === 'doc_page'
+  const tag = nestedHeadingTag('collectionList', block.title !== undefined)
+  const docs = block.collection === DOC_PAGE_COLLECTION
+  const shape = entries.length === 0 ? 'empty' : docs ? 'docs' : block.layout
 
   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)),
-          )
+    shape === 'empty'
+      ? h('p', { class: 'cd-empty' }, ctx.t('collection.empty'))
+      : shape === 'docs'
+        ? renderDocIndex(entries, ctx, tag)
+        : shape === 'list'
+          ? h(
+              'ul',
+              { class: 'cd-index' },
+              entries.map((entry) => indexRow(entry, ctx, tag)),
+            )
+          : h(
+              'ul',
+              {
+                class: 'cd-cards',
+                'data-carousel': shape === 'carousel' ? 'true' : 'false',
+                ...(shape === 'carousel'
+                  ? {
+                      role: 'region',
+                      'aria-label': block.title ?? ctx.t('collection.carousel'),
+                      tabindex: 0,
+                    }
+                  : {}),
+              },
+              entries.map((entry) => card(entry, ctx, tag)),
+            )
 
-  return h(
+  return section(
     '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,
+    'collectionList',
+    'cd-list',
+    { 'data-layout': block.layout, 'data-shape': shape },
+    'div',
+    sectionHead('collectionList', block.title),
+    body,
   )
 }
+
+/** The query this block needs, fetched by the host before any markup is built. */
+export function query(block: CollectionListBlock): QueryRequest {
+  return buildCollectionListQuery(block)
+}

package/src/render/blocks/cta.ts

@@ -1,25 +1,30 @@
 import type { CtaBlock } from '@cogenta/blocks'
-import {
-  actionList,
-  blockHeadingTag,
-  type HtmlElement,
-  h,
-  heading,
-  type RenderContext,
-} from '@cogenta/theme-kit'
+import { actionList, type HtmlElement, h, type RenderContext } from '@cogenta/theme-kit'
+import { optionalText, section } from '../layout.js'
 
+/**
+ * A closing line: "Stuck on something", "Upgrading from an older version".
+ * Between two hairlines held to the width of the content (never a coloured
+ * band, never a rule across the gutters): the title and a sentence on the
+ * first seven columns, the actions after them on a wide screen.
+ */
 export function renderCta(block: CtaBlock, ctx: RenderContext): HtmlElement {
-  return h(
+  return section(
     'section',
-    { class: 'cg-block cg-cta', 'data-block': 'cta' },
-    heading(
-      blockHeadingTag('cta') ?? 'h2',
-      { class: 'cg-cta__title', 'data-field': 'title' },
-      block.title,
+    'cta',
+    'cd-cta',
+    {},
+    'div',
+    h(
+      'div',
+      { class: 'cd-cta__panel' },
+      h(
+        'div',
+        { class: 'cd-cta__words' },
+        h('h2', { class: 'cd-cta__title', 'data-field': 'title' }, block.title),
+        optionalText('p', 'cd-cta__text', block.text, { 'data-field': 'text' }),
+      ),
+      h('div', { class: 'cd-cta__actions' }, actionList(ctx, block.actions, 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

@@ -2,11 +2,13 @@ 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.
+ * A recorded walkthrough, a talk, a post: embedded in the hairline frame.
  *
- * 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.
+ * Nothing here contacts a third party before the visitor has consented. When
+ * `consentRequired` is true (and for a provider this theme cannot embed) the
+ * frame holds a short notice and a link to the original instead: no
+ * `<iframe>`, no `<script>`, no preconnect, no poster fetched from the
+ * provider.
  */
 
 function frameSource(provider: EmbedBlock['provider'], rawUrl: string): string | null {
@@ -42,16 +44,15 @@ function frameSource(provider: EmbedBlock['provider'], rawUrl: string): string |
   }
 }
 
-function consentCard(block: EmbedBlock, ctx: RenderContext, reason: string): HtmlElement {
+function notice(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),
+    { class: 'cd-embed__notice' },
+    h('p', { class: 'cd-embed__reason' }, reason),
     h(
       'a',
       {
-        class: 'cg-embed__link',
+        class: 'cd-arrow-link cd-embed__link',
         href: ctx.link(block.url),
         rel: 'noopener noreferrer nofollow',
       },
@@ -67,28 +68,36 @@ export function renderEmbed(block: EmbedBlock, ctx: RenderContext): HtmlElement
   return h(
     'div',
     {
-      class: 'cg-block cg-embed',
+      class: 'cd-section cd-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,
-        }),
+    h(
+      'div',
+      { class: 'cd-container cd-embed__inner' },
+      h(
+        'div',
+        { class: 'cd-embed__frame cd-frame', style: `aspect-ratio:${ratio}` },
+        source === null
+          ? notice(
+              block,
+              ctx,
+              block.consentRequired
+                ? ctx.t('embed.consentRequired', { provider: block.provider })
+                : ctx.t('embed.unsupported', { provider: block.provider }),
+            )
+          : h('iframe', {
+              class: 'cd-embed__iframe',
+              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,
+            }),
+      ),
+    ),
   )
 }