@rathnasgala2/template 2.2.0 → 3.0.1

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

@@ -138,14 +138,15 @@ export const APPEARANCE_DEFAULT_MODE = APPEARANCE_MODE_SYSTEM;
 export const APPEARANCE_STORAGE_KEY = 'gala:appearance:color-mode:v1';
 
 /**
- * The `id` the server-rendered `<select>` control carries, so the bootstrap
- * script's post-`DOMContentLoaded` wiring can find it with a single
- * `document.getElementById` call. Also used as the paired `<label for>`
- * target.
+ * The `id` the server-rendered colour-mode toggle `<button>` carries, so
+ * the site script's wiring can find it with a single
+ * `document.getElementById` call. The button is rendered `hidden`; the
+ * script reveals it (with JavaScript off the site simply follows the
+ * server-rendered default palette).
  *
  * @type {string}
  */
-export const APPEARANCE_SELECT_ID = 'gala-appearance-color-mode';
+export const APPEARANCE_TOGGLE_ID = 'gala-appearance-color-mode';
 
 /**
  * The candidate-output-directory-relative path the deterministic pre-paint

package/src/core/internal/appearance/controller-markup.js

@@ -1,44 +1,31 @@
 /**
- * The server-rendered Light/Dark/System appearance control, placed in the
- * header-actions slot. The control must be a native `select`, a radio
- * group, or a conforming menu/radio pattern; a three-state unlabeled icon
- * cycle is rejected.
+ * The server-rendered colour-mode toggle, placed in the header-actions slot:
+ * one icon button that the site script reveals and wires to cycle
+ * system, light, dark (with a circular-reveal view transition where the
+ * browser supports it). It is rendered `hidden` because it does nothing
+ * without the script; with JavaScript off the site simply follows the
+ * server-rendered default palette and no dead control is shown.
  *
- * Scoped decision (documented, not silently assumed): of those three
- * admitted patterns, this module implements a native `<select>` bound to a
- * visible, programmatically associated `<label>`. A native select needs no
- * `aria-pressed`/`aria-checked` bookkeeping of its own — its accessible
- * state is the browser-native selected-`<option>` relationship, exposed to
- * every platform accessibility API without any ARIA authored here — and it
- * is keyboard-operable (arrow keys, type-ahead, Enter/Space to open) by
- * native semantics alone, with no custom widget code to keep synchronized.
- * The select's initial selected option is always
- * {@link APPEARANCE_DEFAULT_MODE} (`system`): the actual stored/resolved
- * value is applied to `select.value` by the pre-paint bootstrap script's own
- * `DOMContentLoaded` phase once it runs (see `bootstrap-script.js`), so this
- * server-rendered default is only ever visible for the brief instant before
- * that phase completes, or permanently with JavaScript disabled — exactly
- * the required no-JS fallback: with JavaScript disabled, `system` is
- * preserved.
- *
- * This markup carries no inline `on*` handler and no `javascript:` URL, so
- * it needs no CSP allowance beyond the renderer's existing
- * `script-src 'self'` baseline; the bootstrap script (an external, same-
- * origin file) is what makes it interactive.
+ * The button's accessible name carries the current mode (for example
+ * "Appearance: System"); the script keeps it current from the three
+ * `data-label-*` attributes, which are the only localized text it needs.
+ * Which of the three mode icons shows is pure CSS, keyed off the root's
+ * selection attribute. The markup carries no inline `on*` handler and no
+ * `javascript:` URL, so it needs no CSP allowance beyond `script-src 'self'`.
  */
 
 import { escapeHtml } from '../skeleton.js';
+import { icon } from '../icons.js';
 import {
   APPEARANCE_DEFAULT_MODE,
   APPEARANCE_MODE_DARK,
   APPEARANCE_MODE_LIGHT,
   APPEARANCE_MODE_SYSTEM,
-  APPEARANCE_SELECT_ID,
+  APPEARANCE_TOGGLE_ID,
 } from './contract.js';
 
 /**
- * Render the appearance control's inner markup (a `<label>` plus its bound
- * `<select>`), for insertion into the header-actions slot.
+ * Render the appearance toggle button.
  *
  * @param {object} options rendering options
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
@@ -46,34 +33,38 @@ import {
  * @returns {string} the control markup
  */
 export function renderAppearanceControl({ messages }) {
-  const label = escapeHtml(
-    /** @type {string} */ (messages.appearanceControlLabel),
-  );
-  const selectId = escapeHtml(APPEARANCE_SELECT_ID);
-  /** @type {readonly {value: string, text: string}[]} */
-  const modes = [
-    {
-      value: APPEARANCE_MODE_LIGHT,
-      text: /** @type {string} */ (messages.appearanceModeLightLabel),
-    },
-    {
-      value: APPEARANCE_MODE_DARK,
-      text: /** @type {string} */ (messages.appearanceModeDarkLabel),
-    },
-    {
-      value: APPEARANCE_MODE_SYSTEM,
-      text: /** @type {string} */ (messages.appearanceModeSystemLabel),
-    },
-  ];
-  const options = modes
-    .map(({ value, text }) => {
-      const selectedAttribute =
-        value === APPEARANCE_DEFAULT_MODE ? ' selected' : '';
-      return `<option value="${escapeHtml(value)}"${selectedAttribute}>${escapeHtml(text)}</option>`;
-    })
+  const control = /** @type {string} */ (messages.appearanceControlLabel);
+  /** @type {Record<string, string>} */
+  const modeText = {
+    [APPEARANCE_MODE_LIGHT]: /** @type {string} */ (
+      messages.appearanceModeLightLabel
+    ),
+    [APPEARANCE_MODE_DARK]: /** @type {string} */ (
+      messages.appearanceModeDarkLabel
+    ),
+    [APPEARANCE_MODE_SYSTEM]: /** @type {string} */ (
+      messages.appearanceModeSystemLabel
+    ),
+  };
+  const labelOf = (/** @type {string} */ mode) =>
+    escapeHtml(`${control}: ${modeText[mode]}`);
+  const labelAttributes = [
+    APPEARANCE_MODE_SYSTEM,
+    APPEARANCE_MODE_LIGHT,
+    APPEARANCE_MODE_DARK,
+  ]
+    .map((mode) => ` data-label-${mode}="${labelOf(mode)}"`)
     .join('');
+  const modeIcon = (
+    /** @type {string} */ mode,
+    /** @type {string} */ iconName,
+  ) => `<span class="g-mode-icon g-mode-${mode}">${icon(iconName)}</span>`;
   return (
-    `<label for="${selectId}">${label}</label>` +
-    `<select id="${selectId}" name="${selectId}">${options}</select>`
+    `<button class="g-icon-btn" id="${escapeHtml(APPEARANCE_TOGGLE_ID)}" type="button" hidden` +
+    ` data-action="mode"${labelAttributes} aria-label="${labelOf(APPEARANCE_DEFAULT_MODE)}" title="${labelOf(APPEARANCE_DEFAULT_MODE)}">` +
+    modeIcon(APPEARANCE_MODE_SYSTEM, 'monitor') +
+    modeIcon(APPEARANCE_MODE_LIGHT, 'sun') +
+    modeIcon(APPEARANCE_MODE_DARK, 'moon') +
+    `</button>`
   );
 }

package/src/core/internal/appearance/minify-script.js

@@ -0,0 +1,69 @@
+/**
+ * A deliberately small, dependency-free, safe minifier for the one site
+ * script: it removes comments and indentation and drops blank lines. It
+ * never renames, reorders or joins statements, and it keeps every newline
+ * that remains, so automatic semicolon insertion behaves exactly as in the
+ * readable source. String literals and regular-expression literals are
+ * copied byte for byte.
+ */
+
+/**
+ * @param {string} previous the last non-whitespace character already
+ *   emitted ('' at the start of the source)
+ * @returns {boolean} whether a `/` here starts a regular-expression literal
+ *   (rather than a division)
+ */
+function regexAllowed(previous) {
+  return previous === '' || '(,=:[!&|?{};+-*%<>~^'.includes(previous);
+}
+
+/**
+ * @param {string} source readable JavaScript source (no template literals)
+ * @returns {string} the same program without comments, indentation or blank
+ *   lines
+ */
+export function minifyScript(source) {
+  let out = '';
+  let previous = '';
+  let index = 0;
+  const length = source.length;
+  while (index < length) {
+    const character = source[index];
+    const next = source[index + 1];
+    if (character === "'" || character === '"') {
+      let end = index + 1;
+      while (end < length && source[end] !== character) {
+        end += source[end] === '\\' ? 2 : 1;
+      }
+      out += source.slice(index, end + 1);
+      previous = character;
+      index = end + 1;
+    } else if (character === '/' && next === '/') {
+      while (index < length && source[index] !== '\n') index += 1;
+    } else if (character === '/' && next === '*') {
+      const end = source.indexOf('*/', index + 2);
+      index = end === -1 ? length : end + 2;
+    } else if (character === '/' && regexAllowed(previous)) {
+      let end = index + 1;
+      let inClass = false;
+      while (end < length && (inClass || source[end] !== '/')) {
+        if (source[end] === '\\') end += 1;
+        else if (source[end] === '[') inClass = true;
+        else if (source[end] === ']') inClass = false;
+        end += 1;
+      }
+      out += source.slice(index, end + 1);
+      previous = '/';
+      index = end + 1;
+    } else {
+      out += character;
+      if (!/\s/.test(character)) previous = character;
+      index += 1;
+    }
+  }
+  return `${out
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '')
+    .join('\n')}\n`;
+}

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

@@ -13,9 +13,10 @@
  * `internal/appearance/contract.js` — never a hand-typed literal
  * independent of what those modules emit.
  *
- * Public-hook budget (`publicThemeSlotHooks` is a `[1..64]`-entry set):
- * every catalog leaf below (28 type + 15 class + 2 id + 19 attribute-value)
- * has exactly one corresponding public hook, for exactly 64 entries — this
+ * Public-hook budget (`publicThemeSlotHooks` is a `[1..256]`-entry set since
+ * contract 3.0.0): every catalog leaf below (30 type + 127 class + 2 id + 19
+ * attribute-value) has exactly one corresponding public hook, for exactly
+ * 178 entries — this
  * renderer's complete public theming surface. A leaf with no matching hook
  * would be a catalog member no theme could ever validly select (a
  * used-but-undeclared public slot hook rejects), so catalogs and hooks are
@@ -48,7 +49,7 @@
  * or a `background-image`.
  *
  * Contract 2.1.0 (TPL-H2/TPL-H3/TPL-M7 fix): S2.0's empty `pseudoClasses`
- * catalog made every interaction state unstylable while the closed 35-token
+ * catalog made every interaction state unstylable while the closed 116-token
  * catalog already required `color-focus` and `color-link-visited`, tokens
  * only a pseudo-class can ever apply. {@link PSEUDO_CLASSES} publishes a
  * small closed catalog instead of widening indefinitely; the module
@@ -61,7 +62,7 @@
  * markdown-it's own CommonMark grammar (with `html:false`) never actually
  * produces — `b`, `i`, `u`, `s`, `del`, `ins`, `sub`, `sup`, `mark`, `small`,
  * `wbr`, `table`, `thead`, `tbody`, `tr`, `th`, `td`, `dl`, `dt`, `dd`,
- * `figure`, `figcaption` — is likewise excluded from `typeSelectors`: this
+ * `figcaption` — is likewise excluded from `typeSelectors`: this
  * catalog is every hook the template actually renders, not the sanitizer's
  * own defence-in-depth superset.
  */
@@ -70,7 +71,7 @@ import { HIGHLIGHT_GRAMMARS } from '../render-policy-content.js';
 import {
   APPEARANCE_RESOLVED_MODE_ATTRIBUTE,
   APPEARANCE_ROOT_ATTRIBUTE,
-  APPEARANCE_SELECT_ID,
+  APPEARANCE_TOGGLE_ID,
 } from './contract.js';
 import { PAGE_KIND_ATTRIBUTE, PAGE_KIND_VALUES } from '../page-kinds.js';
 import { SLOT_NAMES } from '../skeleton.js';
@@ -79,9 +80,9 @@ 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 = '2.1.0';
+export const TEMPLATE_STYLING_CONTRACT_VERSION = '3.0.0';
 /** @type {string} */
-export const TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION = '2.1.0';
+export const TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION = '3.0.0';
 
 /** @type {string} the `main-content` landmark's fixed `id`. */
 const MAIN_CONTENT_ID = 'main-content';
@@ -104,7 +105,7 @@ const MAIN_CONTENT_ID = 'main-content';
  *   `hover`.
  * - `visited`: the only way to consume the closed token catalog's own
  *   `color-link-visited`, which had no reachable application before this.
- * - `disabled`: the appearance `<select>` is a native form control, which
+ * - `disabled`: the appearance toggle is a native button control, which
  *   may legitimately be disabled by a later module; themes need a way to
  *   style that state today so it is not a breaking addition later.
  *
@@ -213,11 +214,13 @@ const TYPE_HOOKS = Object.freeze(
     ['prose-link', 'a'],
     ['media-image', 'img'],
     ['prose-divider', 'hr'],
-    ['control-label', 'label'],
-    ['control-select', 'select'],
-    ['control-option', 'option'],
     ['prose-span', 'span'],
     ['prose-time', 'time'],
+    ['control-button', 'button'],
+    ['disclosure-details', 'details'],
+    ['disclosure-summary', 'summary'],
+    ['landmark-section', 'section'],
+    ['media-figure', 'figure'],
   ].map(([hookId, tag]) =>
     Object.freeze({
       hookId,
@@ -228,13 +231,188 @@ const TYPE_HOOKS = Object.freeze(
 );
 
 /**
- * Every class-selector hook: the base Prism `.token` class plus one
- * `.language-<grammar>` hook per admitted highlight grammar (S2 scope: no
+ * The most public hooks a theme contract may declare
+ * (`theme-contract.slotHooks.maxItems`, raised from 64 to 256 in contract
+ * 3.0.0).
+ *
+ * @type {number}
+ */
+export const MAX_PUBLIC_HOOKS = 256;
+
+/**
+ * Contract 3.0.0: every `g-*` component class the template's own markup
+ * (`internal/chrome.js`, `internal/components.js`, `internal/page-kinds.js`
+ * and `internal/skeleton.js`) emits, grouped by component. The naming
+ * convention is the approved design reference's: `g-<component>` for the
+ * block and `g-<component>-<part>` for its parts; a variant adds a second
+ * class (`g-card g-card-row`). One hook per class, published as
+ * `ui-<name>`; `test/theme-styling-contract.test.js` fails if a rendered
+ * `g-*` class is missing here, or a class listed here is never rendered.
+ * Pure-layout needs a component can meet with an element/descendant
+ * selector (`.g-card h3`) deliberately get no class of their own, to stay
+ * under the 256-hook cap.
+ *
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const COMPONENT_CLASS_GROUPS = Object.freeze({
+  shared: [
+    'g-wrap',
+    'g-main',
+    'g-skip',
+    'g-sr',
+    'g-icon',
+    'g-dot',
+    'g-label',
+    'g-dek',
+    'g-btn',
+    'g-icon-btn',
+    'g-more',
+    'g-chip',
+    'g-badge',
+    'g-eyebrow',
+    'g-meta',
+    'g-avatar',
+    'g-byline',
+    'g-byline-text',
+    'g-section',
+    'g-section-head',
+    'g-grid',
+    'g-list',
+    'g-pills',
+    'g-pill',
+    'g-pill-count',
+    'g-crumbs',
+    'g-pagination',
+    'g-toast',
+  ],
+  header: [
+    'g-header',
+    'g-header-row',
+    'g-brand',
+    'g-mark',
+    'g-brand-text',
+    'g-brand-name',
+    'g-brand-tag',
+    'g-nav',
+    'g-actions',
+    'g-search-btn',
+    'g-menu',
+    'g-mode-icon',
+    'g-mode-system',
+    'g-mode-light',
+    'g-mode-dark',
+  ],
+  footer: [
+    'g-footer',
+    'g-footer-grid',
+    'g-footer-brand',
+    'g-footer-about',
+    'g-footer-col',
+    'g-footer-base',
+    'g-social',
+  ],
+  card: [
+    'g-card',
+    'g-card-row',
+    'g-card-link',
+    'g-card-media',
+    'g-card-placeholder',
+    'g-card-body',
+    'g-card-top',
+    'g-card-excerpt',
+    'g-card-foot',
+    'g-series-tag',
+  ],
+  home: [
+    'g-hero',
+    'g-hero-media',
+    'g-hero-body',
+    'g-topic-strip',
+    'g-series-card',
+    'g-series-list',
+    'g-series-n',
+    'g-newsletter',
+    'g-panel',
+    'g-panel-copy',
+  ],
+  article: [
+    'g-article',
+    'g-progress',
+    'g-article-head',
+    'g-article-labels',
+    'g-article-meta',
+    'g-share',
+    'g-article-cover',
+    'g-article-grid',
+    'g-toc',
+    'g-toc-list',
+    'g-toc-mobile',
+    'g-prose',
+    'g-tags',
+    'g-tag',
+    'g-article-foot',
+    'g-author-card',
+    'g-author-name',
+    'g-author-bio',
+    'g-series-box',
+    'g-series-here',
+    'g-pager',
+    'g-pager-link',
+    'g-pager-next',
+  ],
+  listing: ['g-topic-hero', 'g-topic-head', 'g-topic-icon'],
+  // Created at runtime by the optional site script (never server-rendered):
+  // the search dialog and its results, and the code block chrome. Published
+  // all the same so a theme can restyle them.
+  script: [
+    'g-kbd',
+    'g-search',
+    'g-search-box',
+    'g-search-input',
+    'g-search-results',
+    'g-search-hit',
+    'g-search-hit-text',
+    'g-search-hit-title',
+    'g-search-hit-meta',
+    'g-search-empty',
+    'g-codeblock',
+    'g-codebar',
+    'g-codebar-lang',
+    'g-copy',
+    'g-copy-idle',
+    'g-copy-done',
+  ],
+});
+
+/**
+ * The classes only the site script creates (the `script` group of
+ * {@link COMPONENT_CLASS_GROUPS}); the drift test checks these against the
+ * script source instead of the server-rendered HTML.
+ *
+ * @type {readonly string[]}
+ */
+export const SCRIPT_CREATED_CLASSES = Object.freeze([
+  ...COMPONENT_CLASS_GROUPS.script,
+]);
+
+/**
+ * Every class-selector hook: the `g-*` component classes
+ * ({@link COMPONENT_CLASS_GROUPS}), the base Prism `.token` class and one
+ * `.language-<grammar>` hook per admitted highlight grammar (no
  * per-token-kind class is public — see module documentation).
  *
  * @type {readonly StyleHookDefinition[]}
  */
 const CLASS_HOOKS = Object.freeze([
+  ...Object.values(COMPONENT_CLASS_GROUPS)
+    .flat()
+    .map((className) =>
+      Object.freeze({
+        hookId: `ui-${className.slice(2)}`,
+        selectorAtom: `.${className}`,
+        kind: /** @type {const} */ ('class'),
+      }),
+    ),
   Object.freeze({
     hookId: 'code-token',
     selectorAtom: '.token',
@@ -262,8 +440,8 @@ const ID_HOOKS = Object.freeze([
     kind: /** @type {const} */ ('id'),
   }),
   Object.freeze({
-    hookId: 'control-appearance-select',
-    selectorAtom: `#${APPEARANCE_SELECT_ID}`,
+    hookId: 'control-appearance-toggle',
+    selectorAtom: `#${APPEARANCE_TOGGLE_ID}`,
     kind: /** @type {const} */ ('id'),
   }),
 ]);
@@ -450,7 +628,7 @@ export const TEMPLATE_STYLING_CONTRACT_INVALID =
  * Structural self-validation of a `templateStylingContract` object against
  * its closed shape (the checks this repository can run
  * without a published `urn:gala:schema:template-styling-contract` schema
- * entry — no such schema ID is registered in `@rathnasgala2/schemas@2.11.0`;
+ * entry — no such schema ID is registered in `@rathnasgala2/schemas@3.0.0`;
  * only `urn:gala:schema:theme-contract:2.0.0` is, which this module's sibling
  * theme fixtures are validated against with the schema package's own
  * exported `validateGalaDocument`, see `test/theme-styling-contract.test.js`).
@@ -470,7 +648,7 @@ export function assertTemplateStylingContractShape(contract) {
   if (contract.profile !== 'gala-template-styling-contract-v2') {
     fail('profile');
   }
-  if (contract.contractVersion !== '2.1.0') fail('contractVersion');
+  if (contract.contractVersion !== '3.0.0') fail('contractVersion');
   if (contract.templatePackage !== '@rathnasgala2/template') {
     fail('templatePackage');
   }
@@ -585,7 +763,11 @@ export function assertTemplateStylingContractShape(contract) {
   const hooks = /** @type {{hookId: string, selectorAtom: string}[]} */ (
     contract.publicThemeSlotHooks
   );
-  if (!Array.isArray(hooks) || hooks.length < 1 || hooks.length > 64) {
+  if (
+    !Array.isArray(hooks) ||
+    hooks.length < 1 ||
+    hooks.length > MAX_PUBLIC_HOOKS
+  ) {
     fail('publicThemeSlotHooks length');
   }
   const seenAtoms = new Set();