@cogenta/theme-portfolio 1.1.2 → 1.3.3

package/src/render/project.ts

@@ -0,0 +1,140 @@
+import {
+  type HtmlElement,
+  h,
+  type PageContent,
+  type PageEntryMeta,
+  type PageEntryTerm,
+  renderImageSource,
+} from '@cogenta/theme-kit'
+import { taxonomyLabel, yearLabel, yearOf } from './layout.js'
+
+/**
+ * The page of one project, and the plain page title everything else gets.
+ *
+ * A project page opens the way a studio presents a case study:
+ *
+ * 1. the title, very large, across the grid;
+ * 2. the statement (the entry's excerpt) in the lead size, across eight
+ *    columns;
+ * 3. the lead visual, the project's own cover, full width at its own shape;
+ * 4. the fact sheet: one column per fact, a hairline over the row. The year
+ *    comes from the entry's publication date, labelled with the platform's
+ *    own word for "year" in the page's language; every other column is one
+ *    taxonomy the collection declares (a client, the disciplines, the team),
+ *    labelled with the taxonomy's own name and listing its terms, each linked
+ *    to its archive.
+ *
+ * The body that follows is the editor's own blocks. On a project page a
+ * `prose` block sets its text in two columns on a wide screen (`work.css`,
+ * keyed on the `cg-project` class of `<main>`).
+ */
+
+/** What makes a page a project: it has an entry with a cover image and is not a plain page. */
+export function isProject(entry: PageEntryMeta | undefined): entry is PageEntryMeta {
+  return entry !== undefined && entry.image !== undefined && entry.collection !== 'page'
+}
+
+interface Fact {
+  readonly key: string
+  readonly label: string
+  readonly values: readonly HtmlElement[]
+}
+
+function termValue(term: PageEntryTerm): HtmlElement {
+  return h(
+    'li',
+    { class: 'cg-facts__value' },
+    term.href === null
+      ? term.label
+      : h('a', { class: 'cg-facts__link', href: term.href }, term.label),
+  )
+}
+
+function facts(entry: PageEntryMeta, locale: string): readonly Fact[] {
+  const out: Fact[] = []
+  const iso = entry.publishedAt
+  const year = iso === undefined ? undefined : yearOf(iso)
+  if (iso !== undefined && year !== undefined) {
+    out.push({
+      key: 'year',
+      label: yearLabel(locale),
+      values: [h('li', { class: 'cg-facts__value' }, h('time', { datetime: iso }, year))],
+    })
+  }
+  const groups = new Map<string, PageEntryTerm[]>()
+  for (const term of entry.terms ?? []) {
+    const group = groups.get(term.taxonomy)
+    if (group === undefined) groups.set(term.taxonomy, [term])
+    else group.push(term)
+  }
+  for (const [taxonomy, terms] of groups) {
+    out.push({
+      key: taxonomy,
+      label: taxonomyLabel(taxonomy, locale),
+      values: terms.map(termValue),
+    })
+  }
+  return out
+}
+
+function renderFacts(entry: PageEntryMeta, locale: string): HtmlElement | null {
+  const list = facts(entry, locale)
+  if (list.length === 0) return null
+  return h(
+    'dl',
+    { class: 'cg-facts', 'data-count': String(Math.min(list.length, 4)) },
+    list.map((fact) =>
+      h(
+        'div',
+        { class: 'cg-facts__item', 'data-fact': fact.key },
+        h('dt', { class: 'cg-facts__label' }, fact.label),
+        h('dd', { class: 'cg-facts__values' }, h('ul', { class: 'cg-facts__list' }, fact.values)),
+      ),
+    ),
+  )
+}
+
+export function renderProjectHeader(
+  page: PageContent,
+  entry: PageEntryMeta,
+  locale: string,
+): HtmlElement {
+  const image = entry.image
+  return h(
+    'header',
+    { class: 'cg-project-head' },
+    h(
+      'div',
+      { class: 'cg-container cg-project-head__inner' },
+      h('h1', { class: 'cg-project-head__title' }, page.title),
+      entry.excerpt === undefined
+        ? null
+        : h('p', { class: 'cg-project-head__statement' }, entry.excerpt),
+      image === undefined
+        ? null
+        : h(
+            'figure',
+            { class: 'cg-project-head__lead' },
+            renderImageSource(image, {
+              className: 'cg-project-head__image',
+              loading: 'eager',
+              sizes: '(min-width: 96rem) 92rem, 100vw',
+            }),
+          ),
+      renderFacts(entry, locale),
+    ),
+  )
+}
+
+/** The title of any other page: set large on the grid, with nothing around it. */
+export function renderPageHeader(page: PageContent): HtmlElement {
+  return h(
+    'header',
+    { class: 'cg-page-head' },
+    h(
+      'div',
+      { class: 'cg-container cg-page-head__inner' },
+      h('h1', { class: 'cg-page-head__title' }, page.title),
+    ),
+  )
+}

package/src/render/render-block.ts

@@ -5,8 +5,8 @@ import {
   h,
   type PageContent,
   pageHasOwnHeading,
+  providedBlockNode,
   type RenderContext,
-  renderEntryHeader,
   resolveBlockForRender,
   withBlockKey,
   withBlockVariant,
@@ -28,14 +28,10 @@ import { renderQuote } from './blocks/quote.js'
 import { renderStatCounter } from './blocks/stat-counter.js'
 import { renderStats } from './blocks/stats.js'
 import { renderTestimonial } from './blocks/testimonial.js'
+import { isProject, renderPageHeader, renderProjectHeader } from './project.js'
 
-/**
- * `PageContent`/`FetchedEntries`/`pageHasOwnHeading`/`withBlockKey` are
- * `@cogenta/theme-kit`'s own — re-exported here so this package's public
- * surface names them, the same shape every theme package shares them under.
- */
 export type { FetchedEntries, PageContent }
-export { pageHasOwnHeading, renderEntryHeader, withBlockKey }
+export { pageHasOwnHeading, withBlockKey }
 
 export function renderBlock(
   block: VocabularyBlock,
@@ -43,17 +39,19 @@ export function renderBlock(
   entries: FetchedEntries = {},
   registry?: BlockRegistry,
 ): HtmlElement | null {
-  // `block`'s type says `VocabularyBlock`, but the value crossing this
-  // boundary from stored content is not always literally one of the shared
-  // vocabulary — resolving here is what turns an unimplemented theme-private
-  // block into its declared fallback instead of a silently blank slot.
+  // A block a plugin provides arrives already rendered by the host, in a
+  // process of its own (contract D theme@1.7). Nothing else in this theme
+  // needs to know such blocks exist.
+  const provided = providedBlockNode(block, ctx)
+  if (provided !== null) return withBlockVariant(provided, block.variant)
+  // A stored block is not always literally one of the shared vocabulary:
+  // resolving here turns an unimplemented theme-private block into its
+  // declared fallback instead of a silently blank slot.
   const resolved = resolveBlockForRender(block, VOCABULARY_NAMES, registry)
   if (resolved === null) return null
   const known = resolved as unknown as VocabularyBlock
-  // `withBlockVariant` (blocks@2.0, RFC 0002) is applied once here, after
-  // dispatch, rather than inside each of the seventeen block renderers —
-  // `variant` is envelope data every block carries identically, exactly the
-  // same reasoning `withBlockKey` in `renderPage` already follows for `_key`.
+  // `variant` is envelope data every block carries identically, applied once
+  // here rather than by each of the seventeen renderers.
   return withBlockVariant(renderKnownBlock(known, ctx, entries), known.variant)
 }
 
@@ -98,8 +96,9 @@ function renderKnownBlock(
     case 'logoStrip':
       return renderLogoStrip(known, ctx)
     default: {
-      // Exhaustive over contract B's vocabulary: `known` is `never` here, so a
-      // block this package does not implement stops it compiling until it is.
+      // Exhaustive over contract B: `known` is `never` here, so a block this
+      // package does not implement stops it compiling until it is. `null`
+      // rather than a throw: choosing a fallback is the render layer's job.
       const unreachable: never = known
       void unreachable
       return null
@@ -108,48 +107,53 @@ function renderKnownBlock(
 }
 
 /**
- * `renderEntryHeader` (`theme@1.4`) draws the eyebrow/title/excerpt/meta/
- * cover furniture for a page backed by a real content entry — a project —
- * and already returns `null` for a page with no `entry` meta *and* for one
- * whose blocks draw their own heading (a `hero`), so the bare
- * `<h1 class="cg-page__title">` fallback below is the right markup in both
- * of those cases and only those — never a double heading, and never a page
- * with none at all. A page rendered before `theme@1.4` (`page.entry`
- * absent) gets exactly the pre-1.4 markup, byte for byte.
- */
-/**
- * `withBlockKey` stamps `data-block-key` (the L16 builder's own hook); this
- * theme additionally stamps a real `id`, the block's own `_key`, on the same
- * element — `_key` is already unique within a page (contract B), so it
- * doubles as a genuine in-page anchor. The header/footer's own single-page
- * links (the `portfolio` blueprint's "Work"/"Services" nav) resolve to a
- * real target this way, rather than a `#fragment` nothing on the page
- * answers to.
+ * The block's own `_key` doubles as an in-page anchor: it is unique within a
+ * page (contract B), so a menu item such as `/#home-work` lands on the block
+ * it names rather than on a fragment nothing answers to.
  */
-function withBlockAnchor(element: HtmlElement | null, key: string): HtmlElement | null {
+function withAnchor(element: HtmlElement | null, key: string): HtmlElement | null {
   if (element === null) return null
   return { ...element, attrs: { ...element.attrs, id: key } }
 }
 
+/**
+ * `<main id="cg-main">` is mandatory: it is the skip link's target, written
+ * by `@cogenta/cli`'s `theme-render.ts` outside any theme's control.
+ *
+ * Three openings, and exactly one `h1` in each:
+ *
+ * - a page whose blocks include a `hero` lets the hero carry the title (the
+ *   studio's statement, on a home page);
+ * - a project (`isProject`: an entry with a cover that is not a plain page)
+ *   gets the project header: title, statement, lead visual, fact sheet;
+ * - anything else gets its title set large on the grid.
+ *
+ * `withBlockKey` stamps every rendered block with its contract-B `_key`, so
+ * the visual page builder (L16) can map a clicked element back to its block.
+ */
 export function renderPage(
   page: PageContent,
   ctx: RenderContext,
   entries: FetchedEntries = {},
   registry?: BlockRegistry,
 ): HtmlElement {
-  const entryHeader = renderEntryHeader(page, ctx)
+  const ownHeading = pageHasOwnHeading(page.blocks)
+  const project = !ownHeading && isProject(page.entry) ? page.entry : undefined
+  const opening = ownHeading
+    ? null
+    : project !== undefined
+      ? renderProjectHeader(page, project, ctx.locale)
+      : renderPageHeader(page)
+
   return h(
     'main',
-    { class: 'cg-main', id: 'cg-main' },
-    entryHeader,
-    entryHeader === null && !pageHasOwnHeading(page.blocks)
-      ? h('h1', { class: 'cg-page__title' }, page.title)
-      : null,
+    {
+      class: project !== undefined ? 'cg-main cg-project' : 'cg-main',
+      id: 'cg-main',
+    },
+    opening,
     page.blocks.map((block) =>
-      withBlockAnchor(
-        withBlockKey(renderBlock(block, ctx, entries, registry), block._key),
-        block._key,
-      ),
+      withAnchor(withBlockKey(renderBlock(block, ctx, entries, registry), block._key), block._key),
     ),
   )
 }

package/src/render/term-archive.ts

@@ -1,88 +1,110 @@
-import { type HtmlElement, h, type TermArchiveInput } from '@cogenta/theme-kit'
+import {
+  type HtmlElement,
+  h,
+  type TermArchiveEntry,
+  type TermArchiveInput,
+} from '@cogenta/theme-kit'
+import { taxonomyLabel, yearOf } from './layout.js'
+import { renderIndexRow, type Work } from './work.js'
 
 /**
- * The taxonomy-term archive (contract D `theme@1.3`), in this theme's own
- * brutalist-editorial voice: the term set as a display heading with the
- * taxonomy name as a kicker above it, and the entries as the same numbered
- * `cg-entry` rows `collectionList` already renders here — an index, not a
- * card grid.
+ * The page of one taxonomy term (contract D `theme@1.3`): every project filed
+ * under a discipline, a client or a member of the team.
  *
- * Reusing the block's own classes rather than inventing archive-only ones is
- * deliberate: it is what makes an archive of work look like this theme's
- * lists without a second stylesheet to keep in step.
+ * It is set as the studio's index, not as a grid: an archive entry carries no
+ * picture (`TermArchiveEntry` has none), and a grid of empty frames is worse
+ * than a well-set list. The taxonomy's own name sits above the term in the
+ * caption size; the term itself is the page's one `h1`, very large; each
+ * project is a ruled row with its title, its statement when it has one, and
+ * its year; sub-terms and the pager are
+ * underlined words, the pager's arrows drawn by the stylesheet.
  */
-export function renderTermArchive(input: TermArchiveInput): HtmlElement {
-  const items = input.entries.map((entry, index) =>
-    h(
-      'li',
-      { class: 'cg-entry' },
-      h(
-        'div',
-        { class: 'cg-entry__body' },
-        h(
-          'span',
-          { class: 'cg-entry__index', 'aria-hidden': 'true' },
-          String(index + 1).padStart(2, '0'),
-        ),
-        h(
-          'h2',
-          { class: 'cg-entry__title' },
-          entry.href === null
-            ? entry.title
-            : h('a', { class: 'cg-entry__link', href: entry.href }, entry.title),
-        ),
-        entry.publishedAt === null
-          ? null
-          : h(
-              'time',
-              { class: 'cg-entry__date', datetime: entry.publishedAt },
-              entry.publishedAt.slice(0, 10),
-            ),
-        entry.summary === null ? null : h('p', { class: 'cg-entry__excerpt' }, entry.summary),
-      ),
-    ),
-  )
+function workFromArchive(entry: TermArchiveEntry): Work {
+  const year = entry.publishedAt === null ? undefined : yearOf(entry.publishedAt)
+  return {
+    href: entry.href,
+    title: entry.title,
+    caption: year === undefined ? {} : { year },
+    ...(entry.summary === null ? {} : { summary: entry.summary }),
+  }
+}
 
+function pager(input: TermArchiveInput): HtmlElement | null {
+  if (input.page.previousHref === null && input.page.nextHref === null) return null
   return h(
-    'main',
-    { class: 'cg-main cg-archive', id: 'cg-main' },
-    input.ancestors.length === 0
+    'nav',
+    { class: 'cg-archive__pager', 'aria-label': input.labels.pagination },
+    input.page.previousHref === null
       ? 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))),
-          ),
+          'a',
+          {
+            class: 'cg-arrow-link',
+            'data-direction': 'back',
+            rel: 'prev',
+            href: input.page.previousHref,
+          },
+          input.labels.previous,
         ),
-    h('p', { class: 'cg-collection__title' }, input.taxonomyName),
-    h('h1', { class: 'cg-page__title' }, input.term.label),
-    input.children.length === 0
+    input.page.nextHref === null
       ? 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))),
+          'a',
+          { class: 'cg-arrow-link', rel: 'next', href: input.page.nextHref },
+          input.labels.next,
         ),
-    items.length === 0
-      ? h('p', { class: 'cg-collection__empty' }, input.labels.empty)
-      : h('ul', { class: 'cg-collection__items' }, ...items),
-    pager(input),
   )
 }
 
-function pager(input: TermArchiveInput): HtmlElement | null {
-  if (input.page.previousHref === null && input.page.nextHref === null) return null
+export function renderTermArchive(input: TermArchiveInput): HtmlElement {
   return h(
-    'nav',
-    { class: 'cg-archive__pager', 'aria-label': input.labels.pagination },
-    input.page.previousHref === null
-      ? null
-      : h('a', { rel: 'prev', href: input.page.previousHref }, input.labels.previous),
-    input.page.nextHref === null
-      ? null
-      : h('a', { rel: 'next', href: input.page.nextHref }, input.labels.next),
+    'main',
+    { class: 'cg-main cg-archive', id: 'cg-main' },
+    h(
+      'header',
+      { class: 'cg-archive__head' },
+      h(
+        'div',
+        { class: 'cg-container cg-archive__head-inner' },
+        input.ancestors.length === 0
+          ? null
+          : h(
+              'nav',
+              { class: 'cg-archive__breadcrumb', 'aria-label': input.labels.breadcrumb },
+              h(
+                'ol',
+                { class: 'cg-archive__trail' },
+                input.ancestors.map((link) => h('li', {}, h('a', { href: link.href }, link.label))),
+              ),
+            ),
+        h('p', { class: 'cg-archive__kicker' }, taxonomyLabel(input.taxonomyName, input.locale)),
+        h('h1', { class: 'cg-archive__title' }, input.term.label),
+        input.children.length === 0
+          ? null
+          : h(
+              'ul',
+              { class: 'cg-archive__children', 'aria-label': input.labels.subterms },
+              input.children.map((child) =>
+                h('li', {}, h('a', { class: 'cg-arrow-link', href: child.href }, child.label)),
+              ),
+            ),
+      ),
+    ),
+    h(
+      'section',
+      { class: 'cg-section cg-collection', 'data-form': 'index' },
+      h(
+        'div',
+        { class: 'cg-container cg-collection__inner' },
+        input.entries.length === 0
+          ? h('p', { class: 'cg-empty' }, input.labels.empty)
+          : h(
+              'ol',
+              { class: 'cg-index', 'data-count': String(input.entries.length) },
+              input.entries.map((entry) => renderIndexRow(workFromArchive(entry), 'h2')),
+            ),
+        pager(input),
+      ),
+    ),
   )
 }

package/src/render/widget-areas.ts

@@ -0,0 +1,25 @@
+/**
+ * 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
+ * colophon, on the footer's twelve columns; the page areas are placed by the
+ * host in the shared `cg-sidebar-layout` markup, which `styles/widgets.css`
+ * sets on the page's own grid: the column beside the content takes the last
+ * columns of the twelve, the way the header's navigation does.
+ */
+export const widgetAreas: readonly {
+  readonly id: string
+  readonly label: string
+  readonly description?: string
+}[] = [
+  {
+    id: 'sidebar',
+    label: 'Beside the page',
+    description:
+      'Beside an index of work (a discipline, a client, a member of the team) and search results.',
+  },
+  {
+    id: 'content-after',
+    label: 'After the work',
+    description: 'Under a project or a page, before the footer: more work, a way to get in touch.',
+  },
+]

package/src/render/work.ts

@@ -0,0 +1,124 @@
+import {
+  type ContentEntry,
+  entryHref,
+  entryImage,
+  entryTitle,
+  type HeadingTag,
+  type HtmlElement,
+  h,
+  heading,
+  type ImageSource,
+  type RenderContext,
+  renderImageSource,
+} from '@cogenta/theme-kit'
+import { captionUnder, entryCaption, renderCaption, type WorkCaption } from './layout.js'
+
+/**
+ * One piece of work as a listing sets it: the image, square-cornered and
+ * edge to edge within its columns, then the title and the caption line
+ * (client, discipline, year). The grid, the strip and the index all build
+ * their rows from this one unit.
+ *
+ * The title is the one link. The image links to the same page but is taken
+ * out of the tab order and hidden from assistive technology, so a keyboard or
+ * screen-reader user meets each project once.
+ */
+export interface Work {
+  readonly href: string | null
+  readonly title: string
+  readonly caption: WorkCaption
+  readonly image?: ImageSource
+  /** A sentence about the work, when the source carries one and the slot shows it (the archive index). */
+  readonly summary?: string
+}
+
+/** Covers are drawn at 3:2; a listing never asks for another shape, so no card is cropped differently from its neighbour. */
+const COVER_WIDTH = 2000
+
+export function workFromEntry(entry: ContentEntry, ctx: RenderContext): Work {
+  const image = entryImage(entry, ctx, {
+    width: COVER_WIDTH,
+    height: Math.round((COVER_WIDTH * 2) / 3),
+    fit: 'cover',
+  })
+  return {
+    href: entryHref(entry, ctx),
+    title: entryTitle(entry, ctx),
+    caption: entryCaption(entry),
+    ...(image === undefined || image.kind !== 'image' ? {} : { image }),
+  }
+}
+
+export interface WorkCardOptions {
+  readonly tag: HeadingTag
+  readonly sizes: string
+  readonly loading?: 'eager' | 'lazy'
+}
+
+function titleOf(work: Work, tag: HeadingTag, className: string): HtmlElement {
+  return heading(
+    tag,
+    { class: className },
+    work.href === null
+      ? work.title
+      : h('a', { class: 'cg-work__link', href: work.href }, work.title),
+  )
+}
+
+export function renderWorkCard(work: Work, options: WorkCardOptions): HtmlElement {
+  const picture =
+    work.image === undefined
+      ? h('div', { class: 'cg-work__media', 'data-empty': 'true' })
+      : h(
+          work.href === null ? 'div' : 'a',
+          work.href === null
+            ? { class: 'cg-work__media' }
+            : { class: 'cg-work__media', href: work.href, tabindex: '-1', 'aria-hidden': 'true' },
+          renderImageSource(work.image, {
+            className: 'cg-work__image',
+            sizes: options.sizes,
+            loading: options.loading ?? 'lazy',
+          }),
+        )
+  return h(
+    'article',
+    { class: 'cg-work' },
+    picture,
+    h(
+      'div',
+      { class: 'cg-work__text' },
+      titleOf(work, options.tag, 'cg-work__title'),
+      renderCaption(captionUnder(work.caption, work.title), 'cg-work__caption'),
+    ),
+  )
+}
+
+/**
+ * A row of the index: the title, then the client, the discipline and the
+ * year in their own columns, a hairline under each. The columns carry no
+ * header row: a header is words, and a theme has no translation for them.
+ * The client and the discipline share one wrapper, so on a phone they read
+ * as one line under the title; on a wide screen the wrapper steps aside
+ * (`display: contents`) and each takes its column.
+ */
+export function renderIndexRow(work: Work, tag: HeadingTag): HtmlElement {
+  const { client, discipline, year } = work.caption
+  return h(
+    'li',
+    { class: 'cg-index__row' },
+    titleOf(work, tag, 'cg-index__title'),
+    work.summary === undefined
+      ? h(
+          'span',
+          { class: 'cg-index__meta' },
+          h('span', { class: 'cg-index__cell', 'data-part': 'client' }, client ?? ''),
+          h('span', { class: 'cg-index__cell', 'data-part': 'discipline' }, discipline ?? ''),
+        )
+      : h(
+          'span',
+          { class: 'cg-index__meta' },
+          h('span', { class: 'cg-index__summary' }, work.summary),
+        ),
+    h('span', { class: 'cg-index__cell', 'data-part': 'year' }, year ?? ''),
+  )
+}