@rathnasgala2/template 3.2.1 → 4.1.0

package/src/core/internal/appearance/palette-sheet.js

@@ -0,0 +1,217 @@
+/**
+ * The publication palette stylesheet: every build that supplies a theme
+ * package derives the theme's palette-driven tokens from the author's
+ * `appearance.tokens` (`{}` or absent selects the theme's own default
+ * palette), checks them, and writes them as one content-addressed
+ * `assets/gala-palette-<12 hex>.css` file linked after the theme's own
+ * stylesheets.
+ *
+ * All colour mathematics lives in `@rathnasgala2/schemas/palette`
+ * (`derivePalette`, `checkPalette`); this module never re-implements any of
+ * it. It only
+ *
+ * 1. derives the final token values,
+ * 2. re-checks every derived value against the theme-contract token grammar
+ *    (the same closed schema every theme token already passes),
+ * 3. checks every contrast pair in both modes, and
+ * 4. serialises the bound tokens into four blocks inside
+ *    `@layer gala-tokens`: the bare root (light), the
+ *    `prefers-color-scheme: dark` root, and the two resolved-mode selectors,
+ *    exactly the four blocks a theme's own `tokens.css` uses. The sheet is an
+ *    external same-origin file, so the CSP stays free of inline styles.
+ *
+ * The bytes are a pure function of the theme's palette-relevant data and the
+ * author's picks, so sites on the same theme default share identical bytes.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { validateGalaDocument } from '@rathnasgala2/schemas';
+import {
+  checkPalette,
+  derivePalette,
+  PaletteError,
+} from '@rathnasgala2/schemas/palette';
+
+import { ThemeAssetError } from '../../errors.js';
+import {
+  APPEARANCE_RESOLVED_MODE_ATTRIBUTE,
+  APPEARANCE_ROOT_ATTRIBUTE,
+} from './contract.js';
+
+/** @type {string} */
+export const PALETTE_STYLESHEET_DIRECTORY = 'assets';
+/** @type {string} */
+export const PALETTE_STYLESHEET_PREFIX = 'gala-palette-';
+/** @type {string} */
+export const PALETTE_STYLESHEET_MEDIA_TYPE = 'text/css; charset=utf-8';
+/** @type {number} the palette sheet's size ceiling (design D4). */
+export const PALETTE_STYLESHEET_MAXIMUM_BYTES = 16384;
+
+const THEME_CONTRACT_SCHEMA_ID = 'urn:gala:schema:theme-contract:2.0.0';
+
+/**
+ * @param {Record<string, string>} declarations `--gala-<key>` -> value
+ * @param {string} indent line indent
+ * @returns {string} the declaration lines
+ */
+function declarationLines(declarations, indent) {
+  return Object.entries(declarations)
+    .map(([key, value]) => `${indent}--gala-${key}: ${value};\n`)
+    .join('');
+}
+
+/**
+ * Serialise the bound tokens into the four-block sheet.
+ *
+ * @param {Record<string, {light: string, dark: string}>} tokens derived tokens
+ * @param {readonly string[]} bound the bound keys, in the theme's order
+ * @returns {string} the stylesheet text
+ */
+function serialisePaletteSheet(tokens, bound) {
+  const keys = [...bound].sort((a, b) =>
+    Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8')),
+  );
+  /** @type {Record<string, string>} */
+  const light = {};
+  /** @type {Record<string, string>} */
+  const dark = {};
+  for (const key of keys) {
+    light[key] = /** @type {{light: string, dark: string}} */ (
+      tokens[key]
+    ).light;
+    dark[key] = /** @type {{light: string, dark: string}} */ (tokens[key]).dark;
+  }
+  const root = `[${APPEARANCE_ROOT_ATTRIBUTE}]`;
+  const resolved = (/** @type {string} */ mode) =>
+    `[${APPEARANCE_ROOT_ATTRIBUTE}][${APPEARANCE_RESOLVED_MODE_ATTRIBUTE}="${mode}"]`;
+  return (
+    `@layer gala-tokens {\n` +
+    `  ${root} {\n${declarationLines(light, '    ')}  }\n` +
+    `  @media (prefers-color-scheme: dark) {\n` +
+    `    ${root} {\n${declarationLines(dark, '      ')}    }\n` +
+    `  }\n` +
+    `  ${resolved('light')} {\n${declarationLines(light, '    ')}  }\n` +
+    `  ${resolved('dark')} {\n${declarationLines(dark, '    ')}  }\n` +
+    `}\n`
+  );
+}
+
+/**
+ * Map a schemas `PaletteError` to the template's refusal shape.
+ *
+ * @param {unknown} error the thrown value
+ * @returns {never} always throws
+ */
+function rethrowPaletteError(error) {
+  if (error instanceof PaletteError) {
+    throw new ThemeAssetError(error.code, error.detail);
+  }
+  throw error;
+}
+
+/**
+ * Admit a theme's `palette` block: the theme must declare one and it must be
+ * well formed. There is no fallback for a theme without it.
+ *
+ * @param {Record<string, unknown>} themeJson the parsed `theme.json`
+ * @returns {void}
+ * @throws {ThemeAssetError} `THEME_PALETTE_MISSING` or `THEME_PALETTE_INVALID`
+ */
+export function assertThemePalette(themeJson) {
+  try {
+    derivePalette(
+      /** @type {Parameters<typeof derivePalette>[0]} */ (themeJson),
+      {},
+    );
+  } catch (error) {
+    rethrowPaletteError(error);
+  }
+}
+
+/**
+ * Derive, check and serialise the palette sheet for one build.
+ *
+ * @param {Record<string, unknown>} themeJson the admitted `theme.json`
+ * @param {unknown} appearanceTokens `appearance.tokens` (`{}` or absent for
+ *   the theme's default palette)
+ * @returns {{
+ *   text: string,
+ *   bytes: Buffer,
+ *   fileName: string,
+ * }} the sheet and its content-addressed file name
+ * @throws {ThemeAssetError} `APPEARANCE_PALETTE_INVALID` (malformed picks or
+ *   a derived value outside the token grammar), `APPEARANCE_PALETTE_CONTRAST`
+ *   (a pair below its minimum; the message names the pair, mode and ratio)
+ */
+export function buildPaletteStylesheet(themeJson, appearanceTokens) {
+  const theme = /** @type {Parameters<typeof derivePalette>[0]} */ (themeJson);
+  /** @type {ReturnType<typeof derivePalette>} */
+  let derived;
+  try {
+    derived = derivePalette(
+      theme,
+      /** @type {Parameters<typeof derivePalette>[1]} */ (
+        appearanceTokens ?? {}
+      ),
+    );
+  } catch (error) {
+    return rethrowPaletteError(error);
+  }
+
+  // Every derived value passes the closed token grammar: the theme-contract
+  // schema validates each token's value against its type, so substitute the
+  // derived values into the theme's own token rows and validate.
+  const finalTokens =
+    /** @type {{key: string, light: string, dark: string}[]} */ (
+      themeJson.tokens
+    ).map((row) => ({
+      ...row,
+      light: derived.tokens[row.key]?.light ?? row.light,
+      dark: derived.tokens[row.key]?.dark ?? row.dark,
+    }));
+  const validation = validateGalaDocument(THEME_CONTRACT_SCHEMA_ID, {
+    ...themeJson,
+    tokens: finalTokens,
+  });
+  if (!validation.valid) {
+    throw new ThemeAssetError(
+      'APPEARANCE_PALETTE_INVALID',
+      `a derived palette value is outside the token grammar ` +
+        `(${validation.diagnostics.length} diagnostic(s)): ` +
+        JSON.stringify(validation.diagnostics),
+    );
+  }
+
+  for (const mode of /** @type {const} */ (['light', 'dark'])) {
+    const check = checkPalette(derived, mode);
+    const failure = check.failures[0];
+    if (failure) {
+      const ratio =
+        failure.ratio === null
+          ? (failure.reason ?? 'unmeasurable')
+          : `${failure.ratio.toFixed(2)}:1`;
+      throw new ThemeAssetError(
+        'APPEARANCE_PALETTE_CONTRAST',
+        `${failure.pair} in ${mode} mode is ${ratio}, below ${failure.minimum}:1 ` +
+          `(${check.failures.length} failing pair(s) in ${mode} mode)`,
+        { pair: failure.pair, mode, failures: check.failures },
+      );
+    }
+  }
+
+  const text = serialisePaletteSheet(derived.tokens, derived.bound);
+  const bytes = Buffer.from(text, 'utf8');
+  if (bytes.byteLength > PALETTE_STYLESHEET_MAXIMUM_BYTES) {
+    throw new ThemeAssetError(
+      'APPEARANCE_PALETTE_INVALID',
+      `the palette stylesheet is ${bytes.byteLength} bytes, over ${PALETTE_STYLESHEET_MAXIMUM_BYTES}`,
+    );
+  }
+  const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 12);
+  return {
+    text,
+    bytes,
+    fileName: `${PALETTE_STYLESHEET_PREFIX}${hash}.css`,
+  };
+}

package/src/core/internal/appearance/styling-contract.js

@@ -74,15 +74,19 @@ import {
   APPEARANCE_TOGGLE_ID,
 } from './contract.js';
 import { PAGE_KIND_ATTRIBUTE, PAGE_KIND_VALUES } from '../page-kinds.js';
+import {
+  COMPOSITION_ATTRIBUTES,
+  COMPOSITION_ATTRIBUTE_CATALOG,
+} from '../template-composition.js';
 import { SLOT_NAMES } from '../skeleton.js';
 import { canonicalizeJcs, domainDigest } from '../canonical-jcs.js';
 
 /** @type {string} */
 export const TEMPLATE_STYLING_CONTRACT_PACKAGE = '@rathnasgala2/template';
 /** @type {string} */
-export const TEMPLATE_STYLING_CONTRACT_VERSION = '3.0.0';
+export const TEMPLATE_STYLING_CONTRACT_VERSION = '4.0.0';
 /** @type {string} */
-export const TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION = '3.0.0';
+export const TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION = '4.0.0';
 
 /** @type {string} the `main-content` landmark's fixed `id`. */
 const MAIN_CONTENT_ID = 'main-content';
@@ -278,6 +282,9 @@ export const COMPONENT_CLASS_GROUPS = Object.freeze({
     'g-section-head',
     'g-grid',
     'g-list',
+    'g-dated-list',
+    'g-dated-row',
+    'g-date-stamp',
     'g-pills',
     'g-pill',
     'g-pill-count',
@@ -343,6 +350,7 @@ export const COMPONENT_CLASS_GROUPS = Object.freeze({
     'g-article-meta',
     'g-share',
     'g-article-cover',
+    'g-article-cover-full-bleed',
     'g-article-grid',
     'g-toc',
     'g-toc-list',
@@ -468,6 +476,13 @@ const ATTRIBUTE_VALUE_HOOKS = Object.freeze([
       kind: /** @type {const} */ ('attribute'),
     }),
   ),
+  ...COMPOSITION_ATTRIBUTES.map(({ field, name, value }) =>
+    Object.freeze({
+      hookId: `composition-${field.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-${value}`,
+      selectorAtom: `[${name}="${value}"]`,
+      kind: /** @type {const} */ ('attribute'),
+    }),
+  ),
 ]);
 
 /** @type {readonly StyleHookDefinition[]} every public hook, unsorted. */
@@ -524,6 +539,12 @@ export function buildTemplateStylingContract() {
       values: sortedUniqueBytes(PAGE_KIND_VALUES),
       role: 'semantic',
     },
+    ...COMPOSITION_ATTRIBUTE_CATALOG.map(({ name, values }) => ({
+      name,
+      match: 'exact-value',
+      values: sortedUniqueBytes(values),
+      role: 'semantic',
+    })),
   ].sort((a, b) => {
     const bufferA = Buffer.from(canonicalizeJcs(a), 'utf8');
     const bufferB = Buffer.from(canonicalizeJcs(b), 'utf8');
@@ -648,7 +669,7 @@ export function assertTemplateStylingContractShape(contract) {
   if (contract.profile !== 'gala-template-styling-contract-v2') {
     fail('profile');
   }
-  if (contract.contractVersion !== '3.0.0') fail('contractVersion');
+  if (contract.contractVersion !== '4.0.0') fail('contractVersion');
   if (contract.templatePackage !== '@rathnasgala2/template') {
     fail('templatePackage');
   }

package/src/core/internal/chrome.js

@@ -52,6 +52,8 @@ function renderMark(name, mark) {
  * @param {string} [options.appearanceControlHtml] the already-rendered
  *   appearance control, inserted into the `header-actions` slot
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ * @param {string} options.profile the admitted composition profile
+ * @param {string} options.headerLayout the admitted composition's header layout
  * @returns {string} the rendered header
  */
 export function renderHeader({
@@ -66,6 +68,8 @@ export function renderHeader({
   searchIndexHref,
   appearanceControlHtml,
   messages,
+  profile,
+  headerLayout,
 }) {
   const label = (/** @type {string} */ key) =>
     escapeHtml(/** @type {string} */ (messages[key]));
@@ -74,19 +78,28 @@ export function renderHeader({
       ? `<details class="g-menu"><summary>${icon('menu')}<span class="g-sr">${label('menuSummaryLabel')}</span></summary>` +
         `<ul>${navItems.map((item) => renderNavItem(item, currentRoute, urlPrefix)).join('')}</ul></details>`
       : '';
-  return (
-    `<header class="g-header"><div class="g-wrap g-header-row">` +
+  const brand =
     `<a class="g-brand" href="${escapeHtml(homeRoute)}">${renderMark(publicationName, brandMark)}` +
     `<span class="g-brand-text"><span class="g-brand-name">${escapeHtml(publicationName)}</span>` +
-    `<span class="g-brand-tag">${escapeHtml(tagline)}</span></span></a>` +
-    navHtml +
+    `<span class="g-brand-tag">${escapeHtml(tagline)}</span></span></a>`;
+  const actions =
     `<div class="g-actions">` +
     `<button class="g-search-btn" type="button" hidden data-action="search" data-search-index="${escapeHtml(searchIndexHref)}" aria-label="${label('searchButtonAriaLabel')}">` +
     `${icon('search')}<span>${label('searchButtonLabel')}</span></button>` +
     renderSlot('header-actions', { html: appearanceControlHtml }) +
     menu +
-    `</div></div></header>`
-  );
+    `</div>`;
+  const content =
+    profile === 'newsletter'
+      ? actions + brand + navHtml
+      : profile === 'visual'
+        ? brand + actions + navHtml
+        : profile === 'personal'
+          ? navHtml + brand + actions
+          : profile === 'developer'
+            ? navHtml + actions + brand
+            : brand + navHtml + actions;
+  return `<header class="g-header" data-gala-header-layout="${escapeHtml(headerLayout)}"><div class="g-wrap g-header-row">${content}</div></header>`;
 }
 
 /**
@@ -146,6 +159,8 @@ function renderSocialLinks(socialLinks, rssHref, messages) {
  *   attribution line renders: the build input's
  *   `appearance.attribution.showMadeWith`, shown when absent
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ * @param {string} options.profile the admitted composition profile
+ * @param {string} options.footerLayout the admitted composition's footer layout
  * @returns {string} the rendered footer
  */
 export function renderFooter({
@@ -163,6 +178,8 @@ export function renderFooter({
   copyrightText,
   showAttribution,
   messages,
+  profile,
+  footerLayout,
 }) {
   const label = (/** @type {string} */ key) =>
     escapeHtml(/** @type {string} */ (messages[key]));
@@ -176,20 +193,31 @@ export function renderFooter({
       ? ''
       : `<nav class="g-footer-col" aria-label="${label(labelKey)}"><p class="g-label">${label(labelKey)}</p>` +
         `<ul>${items.map((item) => renderNavItem(item, undefined, urlPrefix)).join('')}</ul></nav>`;
-  return (
-    `<footer class="g-footer"><div class="g-wrap g-footer-grid">` +
+  const brand =
     `<div class="g-footer-brand">` +
     `<a class="g-brand" href="${escapeHtml(homeRoute)}">${renderMark(publicationName, brandMark)}` +
     `<span class="g-brand-name">${escapeHtml(publicationName)}</span></a>` +
     `<p class="g-footer-about">${escapeHtml(description)}</p>` +
     renderSocialLinks(socialLinks, rssHref, messages) +
-    `</div>` +
-    column('exploreColumnLabel', primaryItems) +
-    column('footerNavigationLabel', footerItems) +
+    `</div>`;
+  const primary = column('exploreColumnLabel', primaryItems);
+  const secondary = column('footerNavigationLabel', footerItems);
+  const profileCard =
     `<div class="g-footer-col">` +
     renderSlot('footer-profile', { html: authorHtml + footerProfileHtml }) +
-    `</div>` +
-    `</div>` +
+    `</div>`;
+  const grid =
+    profile === 'newsletter'
+      ? brand + profileCard + primary + secondary
+      : profile === 'visual'
+        ? brand + primary + profileCard + secondary
+        : profile === 'personal'
+          ? profileCard + brand + primary + secondary
+          : profile === 'developer'
+            ? primary + secondary + brand + profileCard
+            : brand + primary + secondary + profileCard;
+  return (
+    `<footer class="g-footer" data-gala-footer-layout="${escapeHtml(footerLayout)}"><div class="g-wrap g-footer-grid">${grid}</div>` +
     renderSlot('footer-auxiliary') +
     renderSlot('account-intent') +
     renderSlot('conversation') +

package/src/core/internal/eleventy-render.js

@@ -33,10 +33,10 @@
 import Eleventy from '@11ty/eleventy';
 
 import {
+  APPEARANCE_ALLOWED_ATTRIBUTE,
+  APPEARANCE_DEFAULT_ATTRIBUTE,
   APPEARANCE_RESOLVED_MODE_ATTRIBUTE,
   APPEARANCE_ROOT_ATTRIBUTE,
-  APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE,
-  COLOR_SCHEME_META_CONTENT,
 } from './appearance/contract.js';
 import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
 
@@ -78,7 +78,8 @@ import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
  *   rendered independent of JavaScript, so a theme's own no-JS
  *   `prefers-color-scheme` fallback CSS has a stable root scope to key off;
  * - (TPL-C1 fix) `data-gala-resolved-color-mode`, server-rendered as
- *   {@link APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE} (`"light"`) on the same
+ *   `data.resolvedColorMode` (the author's `light`/`dark` default, else
+ *   `"light"` for a `system` default) on the same
  *   `<html>` element, so `RESOLVED_PALETTE_SELECTORS.light` already matches
  *   before any script runs and a page is never unstyled UA-default HTML for
  *   a no-JS reader, a text-mode/archival crawler, or a load where the
@@ -87,7 +88,12 @@ import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
  *   this attribute with the resolved value for the reader's actual stored
  *   selection/system preference the instant it runs, so a scripted reader's
  *   experience is unchanged;
- * - `<meta name="color-scheme" content="light dark">`, so user-agent styling
+ * - `data-gala-color-mode-default` and `data-gala-color-mode-allowed`, the
+ *   author's "Visitors see" default and allowed modes
+ *   (`appearance.colorMode`), which the bootstrap script prefers over
+ *   `system` when the reader has no stored choice;
+ * - `<meta name="color-scheme">`, `light dark` unless the author allows a
+ *   single `light` or `dark` mode, so user-agent styling
  *   (form controls, scrollbars) and the initial paint already follow
  *   `prefers-color-scheme` before any script runs;
  * - the one `<script src>` this renderer ever emits (the appearance
@@ -128,12 +134,12 @@ import { PAGE_KIND_ATTRIBUTE } from './page-kinds.js';
  */
 const SKELETON_LAYOUT_SOURCE = [
   '<!doctype html>',
-  `<html lang="{{ lang }}" dir="{{ dir }}" ${APPEARANCE_ROOT_ATTRIBUTE} ${APPEARANCE_RESOLVED_MODE_ATTRIBUTE}="${APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE}">`,
+  `<html lang="{{ lang }}" dir="{{ dir }}" ${APPEARANCE_ROOT_ATTRIBUTE} ${APPEARANCE_RESOLVED_MODE_ATTRIBUTE}="{{ resolvedColorMode }}" ${APPEARANCE_DEFAULT_ATTRIBUTE}="{{ colorModeDefault }}" ${APPEARANCE_ALLOWED_ATTRIBUTE}="{{ colorModeAllowed }}">`,
   '<head>',
   '<meta charset="utf-8">',
   '<meta name="viewport" content="width=device-width, initial-scale=1">',
   '{{ cspMetaTag | safe }}',
-  `<meta name="color-scheme" content="${COLOR_SCHEME_META_CONTENT}">`,
+  '<meta name="color-scheme" content="{{ colorScheme }}">',
   // The interactions script (article pages, module on) is deferred and sits
   // on the appearance script's line, so a page without it is byte-identical
   // to before.
@@ -172,7 +178,7 @@ const SKELETON_LAYOUT_SOURCE = [
   '<link rel="stylesheet" href="{{ baseStylesheetHref }}">',
   '{{ themeStylesheetLinksHtml | safe }}',
   '</head>',
-  `<body ${PAGE_KIND_ATTRIBUTE}="{{ pageKind }}">`,
+  `<body ${PAGE_KIND_ATTRIBUTE}="{{ pageKind }}" data-gala-profile="{{ composition.profile }}" data-gala-home-layout="{{ composition.homeLayout }}" data-gala-article-layout="{{ composition.articleLayout }}" data-gala-author-layout="{{ composition.authorLayout }}" data-gala-listing-layout="{{ composition.listingLayout }}" data-gala-header-layout="{{ composition.headerLayout }}" data-gala-footer-layout="{{ composition.footerLayout }}" data-gala-media-ratio="{{ composition.mediaRatio }}" data-gala-density="{{ composition.density }}">`,
   '{{ content | safe }}',
   '</body>',
   '</html>',

package/src/core/internal/package-version.js

@@ -0,0 +1,11 @@
+/**
+ * The renderer's own published version, the single constant both the public
+ * `TEMPLATE_PACKAGE_VERSION` export and theme `templateRange` admission read.
+ * It is deliberately separate from the styling contract's
+ * `templateVersion` (`appearance/styling-contract.js`), which records the
+ * version the contract was published at and is part of the contract digest:
+ * a renderer release that does not change the contract keeps that digest.
+ *
+ * @type {string}
+ */
+export const TEMPLATE_RENDERER_VERSION = '4.1.0';