@rathnasgala2/template 2.0.0 → 2.2.0

package/src/core/internal/appearance/base-layer.js

@@ -0,0 +1,180 @@
+/**
+ * The template-owned `gala-base` cascade layer (TPL-H3/TPL-M7): a
+ * stylesheet this renderer itself writes on every build, independent of
+ * whether a theme is selected, carrying sane defaults for every
+ * contract-mandated chrome element (`internal/skeleton.js`'s skip link,
+ * headings, code/table overflow, image sizing, responsive spacing) plus the
+ * one rule that makes the closed token catalog's
+ * `color-focus`/`focus-width` tokens actually paint a ring (THD-H1): a real
+ * `outline-style: solid` under `:focus-visible`.
+ *
+ * This file is not admitted through, or generated from, the theme package
+ * pipeline in `internal/theme-assets.js` — it is not subject to
+ * `check-css-hooks.mjs`'s closed selector-admission grammar and may use any
+ * selector, property or pseudo-class, including `:focus-visible`,
+ * `html`/`body` and functional colors, because it is authored by the
+ * template, not by a theme. Its bytes are a pure function of this module's
+ * own literal source, not of any per-publication or per-theme input, so a
+ * fixed, non-content-addressed output path carries no collision risk
+ * (mirrors `internal/appearance/bootstrap-script.js`'s own reasoning for its
+ * fixed path).
+ *
+ * Every custom property this file reads (`--gala-*`) is read through a
+ * fallback value, since a theme is optional (`internal/theme-assets.js`'s
+ * `defaultThemeStylesheetLinksHtml` fallback path never defines any
+ * `--gala-*` property at all) — this layer must still produce a sane,
+ * legible default with no theme selected whatsoever.
+ *
+ * Cascade-layer precedence (TPL-M7): this layer's own declarations always
+ * lose to a theme's `gala-tokens`/`gala-components`/`gala-utilities` layer
+ * declarations for the same property on the same element, because this
+ * stylesheet's own first line is the fixed `@layer gala-base, gala-tokens,
+ * gala-components, gala-utilities, gala-print;` order statement — layer
+ * order is declared once, explicitly, independent of `<link>` emission
+ * order, and independent of which optional stylesheets a theme ships (a
+ * theme that omits `utilities.css` never populates `gala-utilities`, which
+ * is harmless: an empty layer in a declared order does nothing). A bare
+ * `@layer name, name, ...;` statement is not itself a style rule, so it
+ * needs no `'unsafe-inline'`/nonce/hash exemption from the
+ * `style-src 'self'` CSP baseline the way an inline `<style>` element would
+ * (TPL-H4): it ships as the first bytes of this external, same-origin
+ * stylesheet, and `internal/eleventy-render.js` always emits this
+ * stylesheet's own `<link>` before every theme stylesheet `<link>`.
+ */
+
+import { ORDERED_LAYERS } from './styling-contract.js';
+
+/** @type {string} the candidate-output-directory-relative path this
+ * stylesheet is always written to (never content-addressed; see module
+ * documentation). */
+export const GALA_BASE_STYLESHEET_PATH = 'assets/gala-base-v1.css';
+
+/** @type {string} the `manifestAsset`/`manifestRoute` `mediaType` for this
+ * stylesheet. */
+export const GALA_BASE_STYLESHEET_MEDIA_TYPE = 'text/css; charset=utf-8';
+
+/**
+ * The exact `gala-base` layer source, byte-for-byte deterministic across
+ * builds (no interpolated per-build value of any kind). Its first line is
+ * the fixed layer-order statement every published page relies on (see
+ * module documentation).
+ *
+ * @type {string}
+ */
+export const GALA_BASE_STYLESHEET_SOURCE = `@layer ${ORDERED_LAYERS.join(', ')};
+
+@layer gala-base {
+  [data-gala-publication-root] {
+    box-sizing: border-box;
+  }
+  [data-gala-publication-root] *,
+  [data-gala-publication-root] *::before,
+  [data-gala-publication-root] *::after {
+    box-sizing: inherit;
+  }
+
+  /* Skip link: the first focusable element on every page, visually hidden
+     until it receives keyboard focus, so it is announced and reachable by
+     assistive technology and keyboard users without being the first visible
+     line of every published page. */
+  [data-gala-publication-root] a[href="#main-content"] {
+    position: absolute;
+    top: -9999px;
+    left: 0;
+    z-index: 9999;
+    padding: var(--gala-space-2, 0.5rem) var(--gala-space-4, 1rem);
+    background-color: var(--gala-color-surface, Canvas);
+    color: var(--gala-color-text, CanvasText);
+  }
+  [data-gala-publication-root] a[href="#main-content"]:focus-visible {
+    top: 0;
+  }
+
+  /* The one rule that makes the closed token catalog's color-focus/
+     focus-width tokens actually paint a ring: outline-style is never set by
+     the token catalog alone (outline-color/outline-width longhands paint
+     nothing without it), and this layer's own low cascade precedence means
+     any theme-declared outline-color/outline-width in gala-components still
+     wins for the same element. */
+  [data-gala-publication-root] :focus-visible {
+    outline-style: solid;
+    outline-width: var(--gala-focus-width, 2px);
+    outline-color: var(--gala-color-focus, Highlight);
+    outline-offset: 2px;
+  }
+
+  /* Type scale, expressed with clamp() so it scales between a phone and a
+     desktop viewport without a discrete breakpoint; no theme sets this. */
+  [data-gala-publication-root] h1 {
+    font-size: clamp(1.75rem, 1.4rem + 1.5vw, 2.5rem);
+    line-height: 1.2;
+  }
+  [data-gala-publication-root] h2 {
+    font-size: clamp(1.375rem, 1.2rem + 0.8vw, 1.875rem);
+    line-height: 1.25;
+  }
+  [data-gala-publication-root] h3 {
+    font-size: clamp(1.125rem, 1.05rem + 0.4vw, 1.375rem);
+    line-height: 1.3;
+  }
+  [data-gala-publication-root] h4,
+  [data-gala-publication-root] h5,
+  [data-gala-publication-root] h6 {
+    font-size: clamp(1rem, 0.96rem + 0.2vw, 1.125rem);
+    line-height: 1.35;
+  }
+  [data-gala-publication-root] p,
+  [data-gala-publication-root] li {
+    font-size: 1rem;
+    line-height: 1.6;
+  }
+  [data-gala-publication-root] code,
+  [data-gala-publication-root] pre {
+    /* Corrects the monospace optical-size mismatch against surrounding
+       proportional text at the same nominal font-size. */
+    font-size: 0.9em;
+  }
+
+  /* Overflow/wrap containment: constrains a fenced code block or an
+     unbroken long token in prose to the viewport, never the whole page. */
+  [data-gala-publication-root] pre {
+    overflow-x: auto;
+  }
+  [data-gala-publication-root] article {
+    overflow-wrap: anywhere;
+  }
+  [data-gala-publication-root] img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  /* Responsive spacing: a small step at a tablet-and-up viewport width, so
+     header/main padding is not identical at 320px and 2560px. */
+  [data-gala-publication-root] header,
+  [data-gala-publication-root] footer {
+    padding: var(--gala-space-4, 1rem) var(--gala-space-4, 1rem);
+  }
+  [data-gala-publication-root] main {
+    padding: var(--gala-space-4, 1rem);
+  }
+  @media (min-width: 48rem) {
+    [data-gala-publication-root] header,
+    [data-gala-publication-root] footer {
+      padding: var(--gala-space-4, 1rem) var(--gala-space-6, 1.5rem);
+    }
+    [data-gala-publication-root] main {
+      padding: var(--gala-space-6, 1.5rem);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    [data-gala-publication-root] *,
+    [data-gala-publication-root] *::before,
+    [data-gala-publication-root] *::after {
+      animation-duration: 0.001ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.001ms !important;
+    }
+  }
+}
+`;

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

@@ -1,15 +1,15 @@
 /**
- * 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 exact deterministic pre-paint appearance bootstrap script: a versioned
+ * deterministic pre-paint bootstrap owned by `template`/`core` that 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").
+ * 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
+ * This is the one and only browser bootstrap this renderer ever emits: the
+ * appearance controller is the only browser
+ * bootstrap it ships. 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.
@@ -29,12 +29,12 @@
  *    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").
+ *    exactly `system`: 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,
+ * kind (in particular, no hide-until-ready visibility toggle — this script
+ * must never hide the document indefinitely, and never needs to,
  * 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}.

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

@@ -1,32 +1,32 @@
 /**
- * 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
+ * The single module `contracts/theme-styling-contract.jcs` targets for
+ * every Light/Dark/System appearance name this renderer owns: the
+ * `data-` attribute/class names the controller sets must be fixed
+ * constants exported from one module. The published
+ * `templateStylingContract` catalog's closed theme-package and stylesheet
+ * admission requires the 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
+ * the 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").
+ * 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"):
+ * Two attributes are exposed, deliberately kept separate: 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.
+ *   are the two fixed theme-facing attributes above — part of the published
+ *   styling contract, 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.
+ *   is not a theme-styling-contract hook — the published 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})
@@ -37,7 +37,7 @@
 import { joinBasePathAndRoute } from '../route.js';
 
 /**
- * The DEC-097 `templateStylingContract.publicationRootSelector` attribute:
+ * The `templateStylingContract.publicationRootSelector` attribute:
  * a bare-presence attribute the template always renders on the document's
  * root element (`<html>`), independent of JavaScript (`match:presence`).
  *
@@ -46,7 +46,7 @@ import { joinBasePathAndRoute } from '../route.js';
 export const APPEARANCE_ROOT_ATTRIBUTE = 'data-gala-publication-root';
 
 /**
- * The DEC-097 `templateStylingContract.resolvedPaletteSelectors` attribute:
+ * The `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
@@ -75,9 +75,8 @@ export const APPEARANCE_MODE_DARK = 'dark';
 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").
+ * Every canonical machine-readable selection value: `light`, `dark`,
+ * `system`; `lite` is not a value.
  *
  * @type {readonly ['light', 'dark', 'system']}
  */
@@ -89,9 +88,9 @@ export const APPEARANCE_MODE_VALUES = Object.freeze([
 
 /**
  * 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").
+ * always resolves to one of these two; it is never a third selector value —
+ * `system` is resolved to one of those values rather than becoming a third
+ * selector.
  *
  * @type {readonly ['light', 'dark']}
  */
@@ -101,8 +100,25 @@ export const APPEARANCE_RESOLVED_MODE_VALUES = Object.freeze([
 ]);
 
 /**
- * The initial reader default (brief S2 section 3: "initial reader default is
- * `system`").
+ * TPL-C1 fix: the server-rendered default for
+ * {@link APPEARANCE_RESOLVED_MODE_ATTRIBUTE} on `<html>`, present on every
+ * page independent of JavaScript (`internal/eleventy-render.js`'s
+ * `SKELETON_LAYOUT_SOURCE`). `light` is chosen because it is the value the
+ * bootstrap script's own `resolveMode` already falls back to when
+ * `prefers-color-scheme` cannot be read (`internal/appearance/
+ * bootstrap-script.js`'s `systemPrefersDark` catch branch), so the
+ * server-rendered default and the script's own no-signal fallback agree.
+ * The bootstrap script's phase 1 always overwrites this attribute
+ * synchronously before first paint for a reader whose browser runs it, so
+ * this default is observed only by a reader (or crawler) that never runs
+ * script at all.
+ *
+ * @type {'light'}
+ */
+export const APPEARANCE_SERVER_DEFAULT_RESOLVED_MODE = APPEARANCE_MODE_LIGHT;
+
+/**
+ * The initial reader default is `system`.
  *
  * @type {'system'}
  */
@@ -110,9 +126,9 @@ 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
+ * control's change handler both read/write. 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.
@@ -133,10 +149,10 @@ 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
+ * bootstrap script is written to, entered into the manifest as an ordinary
+ * `{path,byteLength,sha256}` asset row. Not content-addressed (unlike the
+ * 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.
@@ -150,9 +166,9 @@ export const APPEARANCE_BOOTSTRAP_SCRIPT_PATH =
  * 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
+ * this literal directly (basePath fix: 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.
  *
@@ -162,7 +178,7 @@ export const APPEARANCE_BOOTSTRAP_SCRIPT_HREF = `/${APPEARANCE_BOOTSTRAP_SCRIPT_
 
 /**
  * The `basePath`-joined `<script src>` reference every generated page's
- * skeleton layout actually uses (S2-T12 basePath fix).
+ * skeleton layout actually uses.
  *
  * @param {string} basePath the build input's `basePath`
  * @returns {string} the joined `href`
@@ -184,9 +200,8 @@ export const APPEARANCE_BOOTSTRAP_SCRIPT_MEDIA_TYPE =
  * 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`").
+ * independent of this renderer's own resolved-mode attribute — with
+ * JavaScript disabled, CSS media queries preserve `system`.
  *
  * @type {string}
  */

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

@@ -1,11 +1,10 @@
 /**
- * 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").
+ * 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.
  *
- * Scoped decision (documented, not silently assumed): of the brief's three
+ * 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
@@ -19,8 +18,8 @@
  * `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]").
+ * 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