@rathnasgala2/template 2.0.0 → 2.2.0

package/src/core/internal/skeleton.js

@@ -1,12 +1,11 @@
 /**
- * Core semantic HTML skeleton and navigation renderer (task packet S2-T06;
- * brief S2 section 3 "Semantic skeleton and appearance controller").
+ * Core semantic HTML skeleton and navigation renderer.
  *
  * This module renders only inert, static, CSP-`script-src 'self'`-compatible
  * markup: no inline `on*` attribute, no inline `<script>`, no `javascript:`
  * URL. Every user-visible chrome string it emits comes from
  * `internal/messages.js`'s catalog, never an inline literal, so localization
- * can find every string in one place (task packet S2-T06).
+ * can find every string in one place.
  *
  * Landmark contract every page kind in `internal/page-kinds.js` composes
  * through {@link renderPageBody}:
@@ -25,43 +24,43 @@
  *   `conversation`, `newsletter`, `edition-selector`).
  *
  * Core owns nine versioned semantic slots plus the collapsed
- * `article-footer-ad` slot (DEC-060): `header-actions`, `article-preamble`,
+ * `article-footer-ad` slot: `header-actions`, `article-preamble`,
  * `article-end`, `footer-profile`, `footer-auxiliary`, `account-intent`,
- * `conversation`, `newsletter` and `edition-selector`. S2 has no module
- * system (`build-input.modules` is always `{}`), so every slot renders empty
- * except `footer-profile`, which always wraps the publication's own
- * always-rendered footer card/author-profile content (there is no separate
- * module content to distinguish it from in S2). Each slot is one
- * `data-gala-slot="<name>"` attribute on an otherwise plain, non-landmark
- * `<div>` — an empty element with no accessible name contributes nothing to
- * the accessibility tree, so an empty slot is exactly as inert as one that
- * does not exist. The collapsed `article-footer-ad` slot additionally
- * carries the `hidden` attribute, so it produces no visible, accessibility,
- * layout, network or telemetry effect at all (DEC-060) until a later module
- * task (out of S2 scope) removes `hidden` for a selected placement — none
- * exist in S2 (`build-input.placements` is always `[]`).
+ * `conversation`, `newsletter` and `edition-selector`. This renderer has no
+ * module system (`build-input.modules` is always `{}`), so every slot
+ * renders empty except `footer-profile`, which always wraps the
+ * publication's own always-rendered footer card/author-profile content
+ * (there is no separate module content to distinguish it from here). Each
+ * slot is one `data-gala-slot="<name>"` attribute on an otherwise plain,
+ * non-landmark `<div>` — an empty element with no accessible name
+ * contributes nothing to the accessibility tree, so an empty slot is
+ * exactly as inert as one that does not exist. The collapsed
+ * `article-footer-ad` slot additionally carries the `hidden` attribute, so
+ * it produces no visible, accessibility, layout, network or telemetry
+ * effect at all until a later module (not built here) removes `hidden` for
+ * a selected placement — none exist here (`build-input.placements` is
+ * always `[]`).
  *
- * S2-T07 amendment: `header-actions` is no longer always-empty. It is core's
- * own home for the Light/Dark/System appearance control (brief S2 section 3:
- * "the three-mode appearance control in the header-actions slot") — core
- * content, not a module, so this slot's earlier "every slot ... renders
- * empty" description no longer covers it. Every other slot is unaffected.
+ * `header-actions` is not always-empty: it is core's own home for the
+ * Light/Dark/System appearance control (the three-mode appearance control
+ * in the header-actions slot) — core content, not a module, so this slot's
+ * earlier "every slot ... renders empty" description does not cover it.
+ * Every other slot is unaffected.
  *
  * The exact `selectorAtom`/hook-naming decisions here (`data-gala-slot`
- * attribute, one slot name per value) are S2-T06's own scoped proposal for
- * what S2-T12 later locks into the published
- * `contracts/theme-styling-contract.jcs` catalog; T12 has not run yet
- * (S2-T06 precedes it — S2-T07 then S2-T12), so this module documents the
- * decision here rather than pre-authoring that contract file itself.
+ * attribute, one slot name per value) are what
+ * `contracts/theme-styling-contract.jcs` later locks into its published
+ * catalog, so this module documents the decision here rather than
+ * pre-authoring that contract file itself.
  */
 
 /**
  * Every `data-gala-slot` value this renderer ever writes (the nine
- * versioned core slots plus the collapsed `article-footer-ad` slot,
- * DEC-060), sorted by UTF-8 bytes (S2-T12: `contracts/theme-styling-contract.jcs`
- * exposes one public theme hook per entry here, so this is the single
- * source of truth both `renderSlot` below and that contract builder read
- * from — never a second hand-typed literal list).
+ * versioned core slots plus the collapsed `article-footer-ad` slot), sorted
+ * by UTF-8 bytes. `contracts/theme-styling-contract.jcs` exposes one public
+ * theme hook per entry here, so this is the single source of truth both
+ * `renderSlot` below and that contract builder read from — never a second
+ * hand-typed literal list.
  *
  * @type {readonly string[]}
  */
@@ -89,6 +88,8 @@ const HTML_ESCAPES = Object.freeze({
   "'": '&#39;',
 });
 
+import { joinPublicRoute } from './route.js';
+
 /**
  * Escape a string for safe insertion into HTML text or a quoted attribute
  * value.
@@ -111,8 +112,8 @@ export function escapeHtml(value) {
  *   collapsed `article-footer-ad` slot
  * @param {object} [options] rendering options
  * @param {boolean} [options.collapsed] when `true`, additionally sets
- *   `hidden` (DEC-060's collapsed `article-footer-ad` slot)
- * @param {string} [options.html] already-rendered inner markup (S2-T07: the
+ *   `hidden` (the collapsed `article-footer-ad` slot)
+ * @param {string} [options.html] already-rendered inner markup (the
  *   `header-actions` slot's appearance control); every other slot omits this
  *   and stays empty
  * @returns {string} the slot element
@@ -143,19 +144,25 @@ export function renderSkipLink(messages) {
  *   `navigationItem` (or `navigationLeaf`, which never has children)
  * @param {string | undefined} currentRoute the current page's own joined
  *   route, so the matching link can carry `aria-current="page"`
+ * @param {string} urlPrefix the `baseUrl` path prefix prepended to an
+ *   internal route's href (`/` when `baseUrl` has no path)
  * @returns {string} the rendered `<li>`
  */
-function renderNavItem(item, currentRoute) {
+function renderNavItem(item, currentRoute, urlPrefix) {
   const label = escapeHtml(item.label);
   const href = escapeHtml(
-    /** @type {string} */ (item.type === 'internal' ? item.route : item.url),
+    /** @type {string} */ (
+      item.type === 'internal'
+        ? joinPublicRoute(urlPrefix, /** @type {string} */ (item.route))
+        : item.url
+    ),
   );
   const isCurrent = item.type === 'internal' && item.route === currentRoute;
   const currentAttribute = isCurrent ? ' aria-current="page"' : '';
   const children = item.children ?? [];
   const childList =
     children.length > 0
-      ? `<ul>${children.map((child) => renderNavItem(child, currentRoute)).join('')}</ul>`
+      ? `<ul>${children.map((child) => renderNavItem(child, currentRoute, urlPrefix)).join('')}</ul>`
       : '';
   return `<li><a href="${href}"${currentAttribute}>${label}</a>${childList}</li>`;
 }
@@ -171,16 +178,27 @@ function renderNavItem(item, currentRoute) {
  *   route
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
  *   the resolved message catalog
- * @returns {string} the rendered primary navigation, or an empty string when
- *   there are no authored items (the landmark is still meaningful with no
- *   items for a publication with no authored navigation)
+ * @param {string} [options.urlPrefix] the `baseUrl` path prefix for internal
+ *   hrefs (default `/`)
+ * @returns {string} the rendered primary navigation `<nav>`, always present
+ *   even when `items` is empty (TPL-M3): every page kind renders exactly
+ *   one primary-navigation landmark unconditionally
+ *   (`internal/page-kinds.js`'s own module documentation), so a reader
+ *   navigating by landmark list sees the same, predictable chrome structure
+ *   on every page regardless of whether that publication has authored any
+ *   navigation items yet.
  */
-export function renderPrimaryNavigation({ items, currentRoute, messages }) {
+export function renderPrimaryNavigation({
+  items,
+  currentRoute,
+  messages,
+  urlPrefix = '/',
+}) {
   const label = escapeHtml(
     /** @type {string} */ (messages.primaryNavigationLabel),
   );
   const itemsHtml = items
-    .map((item) => renderNavItem(item, currentRoute))
+    .map((item) => renderNavItem(item, currentRoute, urlPrefix))
     .join('');
   return `<nav aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
 }
@@ -193,14 +211,15 @@ export function renderPrimaryNavigation({ items, currentRoute, messages }) {
  *   `navigationNormalized.footerItems` (0..50 root items)
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
  *   the resolved message catalog
+ * @param {string} [options.urlPrefix] the `baseUrl` path prefix (default `/`)
  * @returns {string} the rendered footer navigation
  */
-export function renderFooterNavigation({ items, messages }) {
+export function renderFooterNavigation({ items, messages, urlPrefix = '/' }) {
   const label = escapeHtml(
     /** @type {string} */ (messages.footerNavigationLabel),
   );
   const itemsHtml = items
-    .map((item) => renderNavItem(item, undefined))
+    .map((item) => renderNavItem(item, undefined, urlPrefix))
     .join('');
   return `<nav aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
 }
@@ -306,8 +325,8 @@ export function renderPagination({
  * @param {{route: string, alt: string} | undefined} options.logo an optional
  *   core logo image, always carrying alternative text
  * @param {string} [options.appearanceControlHtml] the already-rendered
- *   Light/Dark/System appearance control (S2-T07:
- *   `internal/appearance/controller-markup.js`'s `renderAppearanceControl`),
+ *   Light/Dark/System appearance control
+ *   (`internal/appearance/controller-markup.js`'s `renderAppearanceControl`),
  *   inserted into the `header-actions` slot
  * @returns {string} the rendered header
  */

package/src/core/internal/source-inventory.js

@@ -1,10 +1,9 @@
 /**
  * Collect the distinct source records this renderer actually consumed from
- * a validated `build-input:2.0.0` instance, as
- * `manifestIncludedSource[]` rows (DEC-097 section 6: "`includedSources` has
- * set equality with the distinct source records placed in the
- * verified-input carrier ... a file used by multiple records appears once
- * and the role is the earliest value in the enum order").
+ * a validated `build-input:2.0.0` instance, as `manifestIncludedSource[]`
+ * rows: `includedSources` has set equality with the distinct source records
+ * placed in the verified-input carrier, a file used by multiple records
+ * appears once, and its role is the earliest value in the enum order.
  */
 
 /** @type {readonly string[]} */

package/src/core/internal/text-direction.js

@@ -7,8 +7,7 @@
  * against `node_modules/@rathnasgala2/schemas/schemas/build-input.schema.json`:
  * no `$defs` entry or property named `dir`/`direction` exists anywhere in the
  * schema). The semantic skeleton must still set an accurate `dir` attribute
- * per brief S2 section 3 ("localized content with mixed direction" is part of
- * acceptance test A's golden fixture), so this module derives it from the
+ * even for localized content with mixed direction, so this module derives it from the
  * tag's primary language subtag against the closed set of right-to-left
  * script languages in Unicode CLDR's exemplar set — the same approach HTML's
  * own `Intl.Locale` `textInfo.direction` uses, reimplemented here as a small