@cogenta/theme-docs 0.3.3 → 0.5.3

package/src/render/term-archive.ts

@@ -1,65 +1,71 @@
 import { type HtmlElement, h, type TermArchiveInput } from '@cogenta/theme-kit'
+import { longDate } from './layout.js'
 
 /**
- * The taxonomy-term archive (contract D `theme@1.3`) — a simple titled list,
- * deliberately: a documentation site's own information architecture is the
- * sidebar (`section`/`order`, plain fields), not a taxonomy, so this page is
- * the plain fallback for a term an editor still chooses to classify content
- * under, not a second navigation surface competing with the sidebar.
+ * The taxonomy-term archive (contract D `theme@1.3`): a titled index of
+ * ruled rows on the reading width. A documentation site's own information
+ * architecture is the sidebar (`section` and `order`), not a taxonomy, so
+ * this page is the plain, well-set fallback for a term an editor still
+ * classifies pages under, not a second navigation competing with it.
  */
 export function renderTermArchive(input: TermArchiveInput): HtmlElement {
   const rows = input.entries.map((entry) =>
     h(
       'li',
-      { class: 'cg-list__row' },
+      { class: 'cd-index__item' },
       h(
         'div',
-        { class: 'cg-list__body' },
+        { class: 'cd-index__words' },
         h(
           'h2',
-          { class: 'cg-list__title' },
+          { class: 'cd-index__title' },
           entry.href === null
             ? entry.title
-            : h('a', { class: 'cg-list__link', href: entry.href }, entry.title),
+            : h('a', { class: 'cd-index__link', href: entry.href }, entry.title),
         ),
-        entry.summary === null ? null : h('p', { class: 'cg-list__excerpt' }, entry.summary),
+        entry.summary === null ? null : h('p', { class: 'cd-index__text' }, entry.summary),
       ),
       entry.publishedAt === null
         ? null
         : h(
             'time',
-            { class: 'cg-list__date', datetime: entry.publishedAt },
-            entry.publishedAt.slice(0, 10),
+            { class: 'cd-index__date', datetime: entry.publishedAt },
+            longDate(entry.publishedAt, input.locale),
           ),
     ),
   )
 
   return h(
     'main',
-    { class: 'cg-main cg-archive', id: 'cg-main' },
-    input.ancestors.length === 0
-      ? null
-      : h(
-          'nav',
-          { class: 'cg-archive__breadcrumb', 'aria-label': input.labels.breadcrumb },
-          h(
-            'ol',
-            {},
-            ...input.ancestors.map((l) => h('li', {}, h('a', { href: l.href }, l.label))),
+    { class: 'cg-main cd-archive', id: 'cg-main' },
+    h(
+      'div',
+      { class: 'cd-archive__inner' },
+      input.ancestors.length === 0
+        ? null
+        : h(
+            'nav',
+            { class: 'cd-breadcrumb', 'aria-label': input.labels.breadcrumb },
+            h(
+              'ol',
+              { class: 'cd-breadcrumb__items' },
+              input.ancestors.map((link) => h('li', {}, h('a', { href: link.href }, link.label))),
+              h('li', { 'aria-current': 'page' }, input.term.label),
+            ),
           ),
-        ),
-    h('h1', { class: 'cg-page__title' }, input.term.label),
-    input.children.length === 0
-      ? null
-      : h(
-          'ul',
-          { class: 'cg-archive__children', 'aria-label': input.labels.subterms },
-          ...input.children.map((c) => h('li', {}, h('a', { href: c.href }, c.label))),
-        ),
-    rows.length === 0
-      ? h('p', { class: 'cg-list__empty' }, input.labels.empty)
-      : h('ul', { class: 'cg-list__items' }, ...rows),
-    pager(input),
+      h('h1', { class: 'cd-archive__title' }, input.term.label),
+      input.children.length === 0
+        ? null
+        : h(
+            'ul',
+            { class: 'cd-archive__children', 'aria-label': input.labels.subterms },
+            input.children.map((child) => h('li', {}, h('a', { href: child.href }, child.label))),
+          ),
+      rows.length === 0
+        ? h('p', { class: 'cd-empty' }, input.labels.empty)
+        : h('ul', { class: 'cd-index' }, rows),
+      pager(input),
+    ),
   )
 }
 
@@ -67,12 +73,30 @@ function pager(input: TermArchiveInput): HtmlElement | null {
   if (input.page.previousHref === null && input.page.nextHref === null) return null
   return h(
     'nav',
-    { class: 'cg-archive__pager', 'aria-label': input.labels.pagination },
+    { class: 'cd-pager', 'aria-label': input.labels.pagination },
     input.page.previousHref === null
       ? null
-      : h('a', { rel: 'prev', href: input.page.previousHref }, input.labels.previous),
+      : h(
+          'a',
+          {
+            class: 'cd-pager__link',
+            'data-direction': 'previous',
+            rel: 'prev',
+            href: input.page.previousHref,
+          },
+          h('span', { class: 'cd-pager__title' }, input.labels.previous),
+        ),
     input.page.nextHref === null
       ? null
-      : h('a', { rel: 'next', href: input.page.nextHref }, input.labels.next),
+      : h(
+          'a',
+          {
+            class: 'cd-pager__link',
+            'data-direction': 'next',
+            rel: 'next',
+            href: input.page.nextHref,
+          },
+          h('span', { class: 'cd-pager__title' }, input.labels.next),
+        ),
   )
 }

package/src/render/widget-areas.ts

@@ -0,0 +1,33 @@
+/**
+ * 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: readonly {
+  readonly id: string
+  readonly label: string
+  readonly description?: string
+}[] = [
+  {
+    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.',
+  },
+]

package/src/styles/archive.css

@@ -1,39 +1,33 @@
 /*
- * The taxonomy-term archive (contract D `theme@1.3`) — a simple titled list.
- *
- * Only the three things an archive adds beyond what `collectionList` already
- * styles — a breadcrumb, a sub-term row, a prev/next pager. The entry list
- * itself reuses `cg-list__items`/`cg-list__row`, on purpose: an archive of
- * entries must look like this theme's own list of entries.
+ * The taxonomy-term archive: a titled index on the reading width, with its
+ * breadcrumb, its sub-terms and its pager in the documentation's own
+ * furniture (`docs.css` draws the breadcrumb and the pager).
  */
 
-.cg-archive {
-  max-inline-size: var(--cg-page);
-  margin-inline: auto;
-  padding: var(--cg-s10) var(--cg-gutter);
+.cd-archive__inner {
+  --cd-edge: max(var(--cd-gutter), calc((100% - var(--cd-page)) / 2));
+  inline-size: 100%;
+  padding-block: calc(var(--cd-section) * 0.5) var(--cd-section);
+  padding-inline: var(--cd-edge) max(var(--cd-gutter), calc(100% - var(--cd-edge) - 52rem));
 }
 
-.cg-archive__breadcrumb ol,
-.cg-archive__children {
+.cd-archive__title {
+  margin-block: var(--cd-s3) var(--cd-s8);
+  font-size: var(--cd-size-title);
+  line-height: var(--cd-leading-display);
+  letter-spacing: var(--cd-tracking-display);
+}
+
+.cd-archive__children {
   display: flex;
   flex-wrap: wrap;
-  gap: var(--cg-s3);
-  margin: 0 0 var(--cg-s4);
+  gap: var(--cd-s2) var(--cd-s5);
+  margin: 0 0 var(--cd-s8);
   padding: 0;
   list-style: none;
-  font-size: var(--cg-text-sm);
+  font-size: var(--cd-text-ui);
 }
 
-.cg-archive__children {
-  margin-block: var(--cg-s4) var(--cg-s8);
-}
-
-.cg-archive__pager {
-  display: flex;
-  justify-content: space-between;
-  gap: var(--cg-s4);
-  margin-block-start: var(--cg-s10);
-  padding-block-start: var(--cg-s5);
-  border-block-start: 1px solid var(--cg-line-soft);
-  font-weight: var(--cg-weight-semibold);
+.cd-archive .cd-pager {
+  margin-block-start: var(--cd-s10);
 }