@rathnasgala2/template 2.0.0

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

@@ -0,0 +1,159 @@
+/**
+ * The exact deterministic pre-paint appearance bootstrap script (brief S2
+ * section 3: "a versioned deterministic pre-paint bootstrap owned by
+ * `template`/`core` resolves local selection plus system preference and sets
+ * the root state before first themed paint. It is covered by the artifact
+ * digest, is CSP-compatible under `script-src 'self'` (therefore an external
+ * file, not inline), touches no network, account, content or unrelated
+ * storage key, and cannot hide the document indefinitely").
+ *
+ * This is the one and only browser bootstrap S2 ever emits ("Module absence
+ * and CSP equality": "the appearance controller is the only browser
+ * bootstrap"). Every name and value it embeds is read from
+ * `internal/appearance/contract.js`, the one module that owns them, so the
+ * server-rendered control markup and this script can never drift apart on a
+ * literal.
+ *
+ * Two independent phases, both inside the same one external file so the
+ * template never ships a second script:
+ *
+ * 1. A synchronous, top-level phase that runs immediately when this
+ *    blocking, non-`defer`/non-`async`/non-`module` `<script src>` executes
+ *    in `<head>` — before `<body>` is parsed, and so before any themed
+ *    paint. It resolves the stored selection (or `system`, gracefully
+ *    substituted for a missing/unreadable/invalid stored value — storage
+ *    failure never leaves the session unusable) against
+ *    `prefers-color-scheme` and sets both root attributes.
+ * 2. A `DOMContentLoaded`-deferred phase that wires the server-rendered
+ *    `<select>` control's `change` event once `<body>` exists (it cannot run
+ *    any earlier: the control has not been parsed yet at phase 1's own
+ *    execution point) and subscribes to live `prefers-color-scheme` changes,
+ *    updating the resolved attribute only while the current selection is
+ *    exactly `system` (brief: "an explicit `light`/`dark` choice is not
+ *    overridden by later system changes").
+ *
+ * Deliberately absent: no `document.documentElement.style` mutation of any
+ * kind (in particular, no hide-until-ready visibility toggle — brief:
+ * "cannot hide the document indefinitely" — this script never needs one,
+ * since it only ever sets attributes, never inline style), no network
+ * request, no cookie, no account/tracking identifier, no storage key other
+ * than {@link APPEARANCE_STORAGE_KEY}.
+ */
+
+import {
+  APPEARANCE_MODE_DARK,
+  APPEARANCE_MODE_LIGHT,
+  APPEARANCE_MODE_SYSTEM,
+  APPEARANCE_RESOLVED_MODE_ATTRIBUTE,
+  APPEARANCE_SELECTION_ATTRIBUTE,
+  APPEARANCE_SELECT_ID,
+  APPEARANCE_STORAGE_KEY,
+} from './contract.js';
+
+/**
+ * The exact bootstrap script source, byte-for-byte deterministic across
+ * builds: every interpolated value below is a fixed literal from
+ * `contract.js`, never a per-publication or per-build input.
+ *
+ * @type {string}
+ */
+export const APPEARANCE_BOOTSTRAP_SCRIPT_SOURCE = `(function () {
+  'use strict';
+  var STORAGE_KEY = ${JSON.stringify(APPEARANCE_STORAGE_KEY)};
+  var RESOLVED_ATTRIBUTE = ${JSON.stringify(APPEARANCE_RESOLVED_MODE_ATTRIBUTE)};
+  var SELECTION_ATTRIBUTE = ${JSON.stringify(APPEARANCE_SELECTION_ATTRIBUTE)};
+  var SELECT_ID = ${JSON.stringify(APPEARANCE_SELECT_ID)};
+  var MODE_LIGHT = ${JSON.stringify(APPEARANCE_MODE_LIGHT)};
+  var MODE_DARK = ${JSON.stringify(APPEARANCE_MODE_DARK)};
+  var MODE_SYSTEM = ${JSON.stringify(APPEARANCE_MODE_SYSTEM)};
+
+  function isKnownMode(value) {
+    return value === MODE_LIGHT || value === MODE_DARK || value === MODE_SYSTEM;
+  }
+
+  function readStoredSelection() {
+    try {
+      var value = window.localStorage.getItem(STORAGE_KEY);
+      if (isKnownMode(value)) {
+        return value;
+      }
+    } catch (error) {
+      // Storage blocked (private mode, disabled site data, quota): the
+      // session stays usable and this load falls back to MODE_SYSTEM below.
+    }
+    return MODE_SYSTEM;
+  }
+
+  function writeStoredSelection(mode) {
+    try {
+      window.localStorage.setItem(STORAGE_KEY, mode);
+    } catch (error) {
+      // Storage blocked: the selection simply does not persist past this
+      // load; the visible page state this call site also applies still
+      // updates normally.
+    }
+  }
+
+  function systemPrefersDark() {
+    try {
+      return !!(
+        window.matchMedia &&
+        window.matchMedia('(prefers-color-scheme: dark)').matches
+      );
+    } catch (error) {
+      return false;
+    }
+  }
+
+  function resolveMode(selection) {
+    if (selection === MODE_LIGHT || selection === MODE_DARK) {
+      return selection;
+    }
+    return systemPrefersDark() ? MODE_DARK : MODE_LIGHT;
+  }
+
+  function applySelection(selection) {
+    var root = document.documentElement;
+    root.setAttribute(SELECTION_ATTRIBUTE, selection);
+    root.setAttribute(RESOLVED_ATTRIBUTE, resolveMode(selection));
+  }
+
+  // Phase 1 (synchronous, pre-paint): resolve and apply immediately.
+  applySelection(readStoredSelection());
+
+  // Live system-preference changes, only while the reader's own selection is
+  // still exactly "system" (an explicit light/dark choice is never
+  // overridden by a later system change).
+  if (window.matchMedia) {
+    try {
+      var media = window.matchMedia('(prefers-color-scheme: dark)');
+      var onSystemChange = function () {
+        if (readStoredSelection() === MODE_SYSTEM) {
+          applySelection(MODE_SYSTEM);
+        }
+      };
+      if (typeof media.addEventListener === 'function') {
+        media.addEventListener('change', onSystemChange);
+      } else if (typeof media.addListener === 'function') {
+        media.addListener(onSystemChange);
+      }
+    } catch (error) {
+      // No live system-change subscription available: the resolved mode
+      // this load already applied simply stays static until next load.
+    }
+  }
+
+  // Phase 2 (deferred): wire the server-rendered control once it exists.
+  document.addEventListener('DOMContentLoaded', function () {
+    var select = document.getElementById(SELECT_ID);
+    if (!select) return;
+    select.value = readStoredSelection();
+    select.addEventListener('change', function () {
+      var next = select.value;
+      if (!isKnownMode(next)) return;
+      writeStoredSelection(next);
+      applySelection(next);
+    });
+  });
+})();
+`;

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

@@ -0,0 +1,193 @@
+/**
+ * The single module `contracts/theme-styling-contract.jcs` (S2-T12) targets
+ * for every Light/Dark/System appearance name this renderer owns (task
+ * packet S2-T07: "the `data-` attribute/class names the controller sets must
+ * be fixed constants exported from one module"; DEC-097's closed
+ * `templateStylingContract` catalog, section "Closed theme-package and
+ * stylesheet admission": the required root attribute row
+ * `{name:data-gala-publication-root,match:presence,values:[],role:root}` and
+ * the required palette attribute row
+ * `{name:data-gala-resolved-color-mode,match:exact-value,values:[dark,light],role:state}`;
+ * "The template renderer emits the exact root attribute and maintains
+ * exactly one `data-gala-resolved-color-mode="light"|"dark"` value on that
+ * same element before theme CSS is observed").
+ *
+ * Two attributes are exposed, deliberately kept separate (brief S2 section 3:
+ * "selection and resolved state are exposed separately through
+ * template-owned root attributes; theme CSS consumes only resolved state"):
+ *
+ * - {@link APPEARANCE_ROOT_ATTRIBUTE} and {@link APPEARANCE_RESOLVED_MODE_ATTRIBUTE}
+ *   are the two DEC-097-fixed theme-facing attributes above — part of the
+ *   published styling contract S2-T12 emits, never renamed here independent
+ *   of that contract.
+ * - {@link APPEARANCE_SELECTION_ATTRIBUTE} is this renderer's own
+ *   template-internal bookkeeping attribute (the reader's raw `light` /
+ *   `dark` / `system` choice, as opposed to `system`'s *resolved* value). It
+ *   is not a theme-styling-contract hook — DEC-097's attribute catalog does
+ *   not name it, and no theme selector may target it — but its name is still
+ *   fixed here, in this one module, exactly like the two contract-owned
+ *   attributes, so no other module ever invents its own literal for it.
+ *
+ * Both the pre-paint bootstrap script ({@link ../appearance/bootstrap-script.js})
+ * and the server-rendered control markup ({@link ../appearance/controller-markup.js})
+ * import every name/value from here; neither ever writes an attribute name,
+ * a mode value or the storage key as its own literal.
+ */
+
+import { joinBasePathAndRoute } from '../route.js';
+
+/**
+ * The DEC-097 `templateStylingContract.publicationRootSelector` attribute:
+ * a bare-presence attribute the template always renders on the document's
+ * root element (`<html>`), independent of JavaScript (`match:presence`).
+ *
+ * @type {string}
+ */
+export const APPEARANCE_ROOT_ATTRIBUTE = 'data-gala-publication-root';
+
+/**
+ * The DEC-097 `templateStylingContract.resolvedPaletteSelectors` attribute:
+ * an exact-value attribute (`"light"` or `"dark"`, never `"system"`) the
+ * pre-paint bootstrap script sets on the root element before first themed
+ * paint. Theme CSS consumes only this attribute, never
+ * {@link APPEARANCE_SELECTION_ATTRIBUTE}.
+ *
+ * @type {string}
+ */
+export const APPEARANCE_RESOLVED_MODE_ATTRIBUTE =
+  'data-gala-resolved-color-mode';
+
+/**
+ * Template-internal bookkeeping attribute carrying the reader's raw
+ * selection (`light` / `dark` / `system`), as opposed to
+ * {@link APPEARANCE_RESOLVED_MODE_ATTRIBUTE}'s resolved value. Not part of
+ * the published theme styling contract; no theme selector may target it.
+ *
+ * @type {string}
+ */
+export const APPEARANCE_SELECTION_ATTRIBUTE = 'data-gala-color-mode-selection';
+
+/** @type {'light'} */
+export const APPEARANCE_MODE_LIGHT = 'light';
+/** @type {'dark'} */
+export const APPEARANCE_MODE_DARK = 'dark';
+/** @type {'system'} */
+export const APPEARANCE_MODE_SYSTEM = 'system';
+
+/**
+ * Every canonical machine-readable selection value (brief S2 section 3:
+ * "canonical machine values are `light`, `dark`, `system`; `lite` is not a
+ * value").
+ *
+ * @type {readonly ['light', 'dark', 'system']}
+ */
+export const APPEARANCE_MODE_VALUES = Object.freeze([
+  APPEARANCE_MODE_LIGHT,
+  APPEARANCE_MODE_DARK,
+  APPEARANCE_MODE_SYSTEM,
+]);
+
+/**
+ * Every value {@link APPEARANCE_RESOLVED_MODE_ATTRIBUTE} may carry. `system`
+ * always resolves to one of these two; it is never a third selector value
+ * (DEC-097: "`system` is resolved to one of those values rather than
+ * becoming a third selector").
+ *
+ * @type {readonly ['light', 'dark']}
+ */
+export const APPEARANCE_RESOLVED_MODE_VALUES = Object.freeze([
+  APPEARANCE_MODE_LIGHT,
+  APPEARANCE_MODE_DARK,
+]);
+
+/**
+ * The initial reader default (brief S2 section 3: "initial reader default is
+ * `system`").
+ *
+ * @type {'system'}
+ */
+export const APPEARANCE_DEFAULT_MODE = APPEARANCE_MODE_SYSTEM;
+
+/**
+ * The one versioned local-storage key the pre-paint bootstrap script and the
+ * control's change handler both read/write (brief S2 section 3: "selection
+ * is stored under one versioned local key"). The trailing `v1` is this
+ * key's own version; a future incompatible storage format change mints a new
+ * key rather than reinterpreting old values, so an old browser's already
+ * stored `v1` value is simply orphaned (ignored, never migrated or deleted)
+ * rather than misread as a new format.
+ *
+ * @type {string}
+ */
+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.
+ *
+ * @type {string}
+ */
+export const APPEARANCE_SELECT_ID = 'gala-appearance-color-mode';
+
+/**
+ * The candidate-output-directory-relative path the deterministic pre-paint
+ * bootstrap script is written to (task packet S2-T07: "entered into the
+ * manifest through the S2-T03 path with `{path,byteLength,sha256}`"). Not
+ * content-addressed (unlike the S2-T05 media pipeline's derivative paths):
+ * this file's bytes are a pure function of this module's own constants, not
+ * of any per-publication input, so a stable path carries no collision risk.
+ * The `v1` component versions the bootstrap script's own behaviour,
+ * independent of {@link APPEARANCE_STORAGE_KEY}'s own versioning.
+ *
+ * @type {string}
+ */
+export const APPEARANCE_BOOTSTRAP_SCRIPT_PATH =
+  'assets/gala-appearance-bootstrap-v1.js';
+
+/**
+ * The root-absolute `<script src>` reference for a root (`/`) `basePath`
+ * publication. Every actual render joins this with the publication's own
+ * `basePath` through {@link appearanceBootstrapScriptHref} instead of using
+ * this literal directly (S2-T12 basePath fix, LOCAL-7 follow-up: an earlier
+ * version of this module used this root-absolute literal unconditionally,
+ * which 404s under a non-root `basePath` publication). This constant is
+ * retained as the one-place root-`basePath` literal every test and the
+ * `joinBasePathAndRoute` call below both agree on.
+ *
+ * @type {string}
+ */
+export const APPEARANCE_BOOTSTRAP_SCRIPT_HREF = `/${APPEARANCE_BOOTSTRAP_SCRIPT_PATH}`;
+
+/**
+ * The `basePath`-joined `<script src>` reference every generated page's
+ * skeleton layout actually uses (S2-T12 basePath fix).
+ *
+ * @param {string} basePath the build input's `basePath`
+ * @returns {string} the joined `href`
+ */
+export function appearanceBootstrapScriptHref(basePath) {
+  return joinBasePathAndRoute(basePath, APPEARANCE_BOOTSTRAP_SCRIPT_HREF);
+}
+
+/**
+ * The `manifestAsset`/`manifestRoute` `mediaType` enum member for a
+ * JavaScript file (`@rathnasgala2/schemas`' `artifact-manifest.schema.json`).
+ *
+ * @type {string}
+ */
+export const APPEARANCE_BOOTSTRAP_SCRIPT_MEDIA_TYPE =
+  'application/javascript; charset=utf-8';
+
+/**
+ * The `<meta name="color-scheme">` content value: both palettes are
+ * admitted, so the browser's own user-agent styling (form controls,
+ * scrollbars) and initial paint follow `prefers-color-scheme` immediately,
+ * independent of this renderer's own resolved-mode attribute (brief S2
+ * section 3: "`color-scheme` meta/CSS handling"; "with JavaScript disabled,
+ * CSS media queries preserve `system`").
+ *
+ * @type {string}
+ */
+export const COLOR_SCHEME_META_CONTENT = 'light dark';

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

@@ -0,0 +1,80 @@
+/**
+ * The server-rendered Light/Dark/System appearance control (task packet
+ * S2-T07: "the three-mode appearance control in the header-actions slot";
+ * brief S2 section 3: "the control is a native `select`, a radio group, or a
+ * conforming menu/radio pattern. A three-state unlabeled icon cycle is
+ * rejected").
+ *
+ * Scoped decision (documented, not silently assumed): of the brief's 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 no-JS fallback the brief requires ("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.
+ */
+
+import { escapeHtml } from '../skeleton.js';
+import {
+  APPEARANCE_DEFAULT_MODE,
+  APPEARANCE_MODE_DARK,
+  APPEARANCE_MODE_LIGHT,
+  APPEARANCE_MODE_SYSTEM,
+  APPEARANCE_SELECT_ID,
+} from './contract.js';
+
+/**
+ * Render the appearance control's inner markup (a `<label>` plus its bound
+ * `<select>`), for insertion into the header-actions slot.
+ *
+ * @param {object} options rendering options
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ *   the resolved message catalog
+ * @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>`;
+    })
+    .join('');
+  return (
+    `<label for="${selectId}">${label}</label>` +
+    `<select id="${selectId}" name="${selectId}">${options}</select>`
+  );
+}