@rathnasgala2/template 3.2.1 → 4.1.0

package/src/core/internal/page-kinds.js

@@ -88,6 +88,10 @@ import { getMessages } from './messages.js';
 import { resolveTextDirection } from './text-direction.js';
 import { deriveAuthorSlugs, routeSegmentForLabel } from './route-labels.js';
 import { derivePublicBasePath, joinPublicRoute } from './route.js';
+import {
+  assertSupportedComposition,
+  EDITORIAL_COMPOSITION,
+} from './template-composition.js';
 
 /** Listing page size (index and per-year archive pages). Scoped decision:
  * this renderer has no externally fixed page size; 10 is a deterministic,
@@ -383,11 +387,46 @@ export function homeDocumentTitle(name, tagline) {
  * @param {import('../../../types/index.d.ts').InteractionsModule} [options.interactions]
  *   the validated interactions module; when set, every article page carries
  *   the interactions section and is interaction-bearing
+ * @param {unknown} [options.composition] the schema-validated structural
+ *   composition selected by the theme; defaults to Editorial only for
+ *   theme-less renderer use
  * @returns {GeneratedPage[]} every generated page, in a stable, deterministic
  *   order
  */
 export function buildGeneratedPages(validatedInput, options) {
   const { publication, authors, content, basePath, baseUrl } = validatedInput;
+  const composition = assertSupportedComposition(
+    options.composition ?? EDITORIAL_COMPOSITION,
+  );
+  /**
+   * Preserve every content region while giving each article direction its
+   * own reading sequence and semantic container.
+   *
+   * @param {{head: string, cover: string, toc: string, prose: string, foot: string}} parts
+   * @returns {string}
+   */
+  const articleStructure = ({ head, cover, toc, prose, foot }) => {
+    /**
+     * @param {string} contents rendered article regions
+     * @param {string} [element] semantic wrapper element
+     * @returns {string}
+     */
+    const grid = (contents, element = 'div') =>
+      `<${element} class="g-wrap g-article-grid">${contents}</${element}>`;
+    if (composition.profile === 'newsletter') {
+      return `<section>${head}${cover}${grid(prose + toc, 'section')}${foot}</section>`;
+    }
+    if (composition.profile === 'visual') {
+      return `<div>${cover}${head}${grid(prose + toc)}</div>${foot}`;
+    }
+    if (composition.profile === 'personal') {
+      return `<section>${head}${cover}${grid(prose)}${toc ? grid(toc, 'section') : ''}${foot}</section>`;
+    }
+    if (composition.profile === 'developer') {
+      return `<div>${head}${cover}${grid(toc + prose, 'section')}${foot}</div>`;
+    }
+    return head + cover + grid(toc + prose) + foot;
+  };
   const interactionsModule = interactionsActive(options.interactions)
     ? options.interactions
     : undefined;
@@ -612,13 +651,32 @@ export function buildGeneratedPages(validatedInput, options) {
    * @param {string} [afterHtml] markup after the list (pagination)
    * @returns {string}
    */
-  const rowList = (items, afterHtml = '') =>
-    `<section class="g-wrap g-section">` +
-    (items.length > 0
-      ? `<div class="g-list">${items.map((record) => cardOf(record, 'row', 2)).join('')}</div>`
-      : `<p>${text('emptyListingLabel')}</p>`) +
-    afterHtml +
-    `</section>`;
+  const rowList = (items, afterHtml = '') => {
+    const grid = composition.listingLayout === 'image-grid';
+    const issueCards = composition.listingLayout === 'issues';
+    const datedRows = composition.listingLayout === 'dated-rows';
+    const outer =
+      composition.profile === 'personal' || composition.profile === 'developer'
+        ? 'div'
+        : 'section';
+    const contents =
+      items.length > 0
+        ? datedRows
+          ? `<div class="g-list g-dated-list">${items
+              .map(
+                (record) =>
+                  `<div class="g-dated-row"><time class="g-date-stamp" datetime="${escapeHtml(record.frontmatter.publishedAt)}">` +
+                  `${call('formatDate', record.frontmatter.publishedAt)}</time>${cardOf(record, 'row', 2)}</div>`,
+              )
+              .join('')}</div>`
+          : `<div class="${grid ? 'g-grid' : 'g-list'}">${items
+              .map((record) =>
+                cardOf(record, grid || issueCards ? 'grid' : 'row', 2),
+              )
+              .join('')}</div>`
+        : `<p>${text('emptyListingLabel')}</p>`;
+    return `<${outer} class="g-wrap g-section" data-gala-listing-layout="${composition.listingLayout}">${contents}${afterHtml}</${outer}>`;
+  };
 
   /**
    * One listing page's metadata: bare title, `<title>`, description,
@@ -710,6 +768,28 @@ export function buildGeneratedPages(validatedInput, options) {
         ? `<p class="g-dek">${escapeHtml(author.biography)}</p>`
         : '') +
       links;
+    const authorHead = listingHead({
+      breadcrumbHtml: crumbs(
+        [{ label: /** @type {string} */ (messages.authorsSectionLabel) }],
+        [{ label: author.displayName }],
+      ),
+      kicker: /** @type {string} */ (messages.authorKickerLabel),
+      count: authored.length,
+      title: author.displayName,
+      descriptionHtml: intro,
+      markHtml: avatar(author),
+    });
+    const authoredList = rowList(authored);
+    const authorContents =
+      composition.profile === 'newsletter'
+        ? `<section>${authorHead}${authoredList}</section>`
+        : composition.profile === 'visual'
+          ? `<div>${authorHead}<section>${authoredList}</section></div>`
+          : composition.profile === 'personal'
+            ? `<section>${authorHead}<div>${authoredList}</div></section>`
+            : composition.profile === 'developer'
+              ? `<div>${authorHead}<div>${authoredList}</div></div>`
+              : authorHead + authoredList;
     pages.push({
       kind: 'author',
       route: authorRoute(author),
@@ -737,17 +817,9 @@ export function buildGeneratedPages(validatedInput, options) {
         }),
       ),
       bodyHtml:
-        listingHead({
-          breadcrumbHtml: crumbs(
-            [{ label: /** @type {string} */ (messages.authorsSectionLabel) }],
-            [{ label: author.displayName }],
-          ),
-          kicker: /** @type {string} */ (messages.authorKickerLabel),
-          count: authored.length,
-          title: author.displayName,
-          descriptionHtml: intro,
-          markHtml: avatar(author),
-        }) + rowList(authored),
+        `<div data-gala-author-layout="${composition.authorLayout}">` +
+        authorContents +
+        `</div>`,
     });
   }
 
@@ -822,7 +894,7 @@ export function buildGeneratedPages(validatedInput, options) {
       editionSelector +
       `</div>`;
     const cover = hero
-      ? `<figure class="g-wrap g-article-cover">${renderImage({ image: hero, alt: heroMedia?.role === 'decorative' ? '' : (heroMedia?.alt ?? ''), priority: true })}</figure>`
+      ? `<figure class="${composition.articleLayout === 'full-bleed' ? 'g-article-cover g-article-cover-full-bleed' : 'g-wrap g-article-cover'}">${renderImage({ image: hero, alt: heroMedia?.role === 'decorative' ? '' : (heroMedia?.alt ?? ''), priority: true })}</figure>`
       : '';
     const tocNav = contents
       ? `<nav class="g-toc" aria-label="${text('onThisPageLabel')}"><p class="g-label">${icon('list')}${text('onThisPageLabel')}</p>${contents}</nav>`
@@ -1001,8 +1073,8 @@ export function buildGeneratedPages(validatedInput, options) {
       interactionBearing: Boolean(interactions),
       lastModified: contentLastModified(frontmatter),
       bodyHtml:
-        `<article class="g-article">${isArticle || isEdition ? '<div class="g-progress" aria-hidden="true"></div>' : ''}${head}${cover}` +
-        `<div class="g-wrap g-article-grid">${tocNav}${prose}</div>${foot}</article>` +
+        `<article class="g-article" data-gala-article-layout="${composition.articleLayout}">${isArticle || isEdition ? '<div class="g-progress" aria-hidden="true"></div>' : ''}` +
+        `${articleStructure({ head, cover, toc: tocNav, prose, foot })}</article>` +
         after +
         (isArticle ? newsletterHtml : ''),
     });
@@ -1093,15 +1165,49 @@ export function buildGeneratedPages(validatedInput, options) {
         ? `<section class="g-wrap g-section"><div class="g-section-head"><h2>${text('moreArticlesHeading')}</h2></div>` +
           `<div class="g-list">${items.map((r) => cardOf(r, 'row')).join('')}</div>${pagination}</section>`
         : '';
-    const bodyHtml =
-      pageNumber === 1
+    const homeParts =
+      composition.profile === 'newsletter'
         ? homeHeading +
-          homeFeatured +
           homeTags +
+          homeFeatured +
           homeLatest +
-          homeSeries +
           moreList +
+          homeSeries +
           newsletterHtml
+        : composition.profile === 'visual'
+          ? homeHeading +
+            homeFeatured +
+            homeLatest +
+            homeSeries +
+            homeTags +
+            moreList +
+            newsletterHtml
+          : composition.profile === 'personal'
+            ? homeHeading +
+              homeLatest +
+              homeFeatured +
+              moreList +
+              homeTags +
+              homeSeries +
+              newsletterHtml
+            : composition.profile === 'developer'
+              ? homeHeading +
+                homeTags +
+                homeLatest +
+                homeSeries +
+                homeFeatured +
+                moreList +
+                newsletterHtml
+              : homeHeading +
+                homeFeatured +
+                homeTags +
+                homeLatest +
+                homeSeries +
+                moreList +
+                newsletterHtml;
+    const bodyHtml =
+      pageNumber === 1
+        ? `<div data-gala-home-layout="${composition.homeLayout}">${homeParts}</div>`
         : listingHead({
             breadcrumbHtml: crumbs([
               { label: /** @type {string} */ (messages.indexHeading) },

package/src/core/internal/template-composition.js

@@ -0,0 +1,185 @@
+/**
+ * Generation-4 template composition admission.
+ *
+ * A composition is one complete, immutable product direction. Admission is
+ * deliberately by exact object equality so fields from different directions
+ * cannot be combined into renderer states that were never designed or tested.
+ */
+
+/** The immutable generation-4 composition schema identity. */
+export const TEMPLATE_COMPOSITION_SCHEMA_ID =
+  'urn:gala:schema:template-composition:2.0.0';
+
+const SCHEMA_FIELDS = Object.freeze({
+  schemaId: TEMPLATE_COMPOSITION_SCHEMA_ID,
+  schemaVersion: '2.0.0',
+});
+
+/** The complete Editorial composition. */
+export const EDITORIAL_COMPOSITION = Object.freeze({
+  ...SCHEMA_FIELDS,
+  profile: 'editorial',
+  homeLayout: 'magazine',
+  articleLayout: 'editorial',
+  authorLayout: 'portrait',
+  listingLayout: 'rows',
+  headerLayout: 'masthead',
+  footerLayout: 'expanded',
+  mediaRatio: 'landscape',
+  density: 'comfortable',
+});
+
+/** The complete Newsletter composition. */
+export const NEWSLETTER_COMPOSITION = Object.freeze({
+  ...SCHEMA_FIELDS,
+  profile: 'newsletter',
+  homeLayout: 'newspaper',
+  articleLayout: 'issue',
+  authorLayout: 'profile',
+  listingLayout: 'issues',
+  headerLayout: 'publication',
+  footerLayout: 'expanded',
+  mediaRatio: 'landscape',
+  density: 'comfortable',
+});
+
+/** The complete Visual composition. */
+export const VISUAL_COMPOSITION = Object.freeze({
+  ...SCHEMA_FIELDS,
+  profile: 'visual',
+  homeLayout: 'gallery',
+  articleLayout: 'full-bleed',
+  authorLayout: 'portfolio',
+  listingLayout: 'image-grid',
+  headerLayout: 'minimal',
+  footerLayout: 'compact',
+  mediaRatio: 'mixed',
+  density: 'comfortable',
+});
+
+/** The complete Personal composition. */
+export const PERSONAL_COMPOSITION = Object.freeze({
+  ...SCHEMA_FIELDS,
+  profile: 'personal',
+  homeLayout: 'chronological',
+  articleLayout: 'prose',
+  authorLayout: 'biography',
+  listingLayout: 'dated-rows',
+  headerLayout: 'compact',
+  footerLayout: 'compact',
+  mediaRatio: 'landscape',
+  density: 'spacious',
+});
+
+/** The complete Developer composition. */
+export const DEVELOPER_COMPOSITION = Object.freeze({
+  ...SCHEMA_FIELDS,
+  profile: 'developer',
+  homeLayout: 'topic-index',
+  articleLayout: 'technical',
+  authorLayout: 'biography',
+  listingLayout: 'rows',
+  headerLayout: 'utility',
+  footerLayout: 'compact',
+  mediaRatio: 'landscape',
+  density: 'compact',
+});
+
+/** Every complete composition implemented by generation 4. */
+export const SUPPORTED_COMPOSITIONS = Object.freeze([
+  EDITORIAL_COMPOSITION,
+  NEWSLETTER_COMPOSITION,
+  VISUAL_COMPOSITION,
+  PERSONAL_COMPOSITION,
+  DEVELOPER_COMPOSITION,
+]);
+
+/** @type {Readonly<Record<string, (typeof SUPPORTED_COMPOSITIONS)[number]>>} */
+const COMPOSITION_BY_PROFILE = Object.freeze(
+  Object.fromEntries(
+    SUPPORTED_COMPOSITIONS.map((composition) => [
+      composition.profile,
+      composition,
+    ]),
+  ),
+);
+
+const COMPOSITION_ATTRIBUTE_NAMES = Object.freeze({
+  profile: 'data-gala-profile',
+  homeLayout: 'data-gala-home-layout',
+  articleLayout: 'data-gala-article-layout',
+  authorLayout: 'data-gala-author-layout',
+  listingLayout: 'data-gala-listing-layout',
+  headerLayout: 'data-gala-header-layout',
+  footerLayout: 'data-gala-footer-layout',
+  mediaRatio: 'data-gala-media-ratio',
+  density: 'data-gala-density',
+});
+
+/** @typedef {(typeof SUPPORTED_COMPOSITIONS)[number]} SupportedComposition */
+/** @typedef {Exclude<keyof SupportedComposition, 'schemaId' | 'schemaVersion'>} CompositionField */
+
+/** Public semantic attribute catalogs corresponding to composition fields. */
+export const COMPOSITION_ATTRIBUTE_CATALOG = Object.freeze(
+  /** @type {readonly [CompositionField, string][]} */ (
+    Object.entries(COMPOSITION_ATTRIBUTE_NAMES)
+  ).map(([field, name]) =>
+    Object.freeze({
+      field,
+      name,
+      values: Object.freeze([
+        ...new Set(
+          SUPPORTED_COMPOSITIONS.map((composition) => composition[field]),
+        ),
+      ]),
+    }),
+  ),
+);
+
+/** Every public semantic attribute/value pair themes may select. */
+export const COMPOSITION_ATTRIBUTES = Object.freeze(
+  COMPOSITION_ATTRIBUTE_CATALOG.flatMap(({ field, name, values }) =>
+    values.map((value) => Object.freeze({ field, name, value })),
+  ),
+);
+
+/**
+ * Admit exactly one complete composition implemented by this renderer.
+ *
+ * @param {unknown} candidate a complete template-composition document
+ * @returns {(typeof SUPPORTED_COMPOSITIONS)[number]} canonical composition
+ */
+export function assertSupportedComposition(candidate) {
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    throw new Error(
+      `composition must be a complete ${TEMPLATE_COMPOSITION_SCHEMA_ID} document`,
+    );
+  }
+  const composition = /** @type {Record<string, unknown>} */ (candidate);
+  const selected =
+    typeof composition.profile === 'string' &&
+    Object.hasOwn(COMPOSITION_BY_PROFILE, composition.profile)
+      ? COMPOSITION_BY_PROFILE[composition.profile]
+      : undefined;
+  if (!selected) {
+    throw new Error(
+      `composition.profile (${JSON.stringify(composition.profile)}) is not implemented by this renderer`,
+    );
+  }
+  const expectedKeys = Object.keys(selected).sort();
+  const actualKeys = Object.keys(composition).sort();
+  if (JSON.stringify(actualKeys) !== JSON.stringify(expectedKeys)) {
+    throw new Error(
+      `composition must contain exactly ${expectedKeys.join(', ')}`,
+    );
+  }
+  for (const [key, expected] of Object.entries(selected)) {
+    if (composition[key] !== expected) {
+      throw new Error(
+        `composition.${key} (${JSON.stringify(composition[key])}) is not ` +
+          `implemented for ${selected.profile}; expected ${JSON.stringify(expected)}`,
+      );
+    }
+  }
+  return selected;
+}

package/src/core/internal/theme-assets.js

@@ -77,16 +77,21 @@ import { validateGalaDocument } from '@rathnasgala2/schemas';
 import { ThemeAssetError } from '../errors.js';
 import { digestBytes } from './canonical-jcs.js';
 import {
-  buildTemplateStylingContract,
-  TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION,
-} from './appearance/styling-contract.js';
+  assertThemePalette,
+  buildPaletteStylesheet,
+  PALETTE_STYLESHEET_DIRECTORY,
+  PALETTE_STYLESHEET_MEDIA_TYPE,
+} from './appearance/palette-sheet.js';
+import { buildTemplateStylingContract } from './appearance/styling-contract.js';
+import { TEMPLATE_RENDERER_VERSION } from './package-version.js';
 import { MEDIA_TYPE_BY_FORMAT, sniffMediaFormat } from './media/sniff.js';
 import { sanitizeThemeSvg } from './media/theme-svg-sanitizer.js';
 import { projectFixedAssetPath } from './route.js';
 import { satisfiesTemplateRange } from './semver-range.js';
 import { escapeHtml } from './skeleton.js';
+import { assertSupportedComposition } from './template-composition.js';
 
-/** @type {string} the `urn:gala:schema:theme-contract:2.0.0` schema id
+/** @type {string} the immutable `urn:gala:schema:theme-contract:2.0.0` schema id
  * every consumed `theme.json` is validated against (TPL-H1). */
 const THEME_CONTRACT_SCHEMA_ID = 'urn:gala:schema:theme-contract:2.0.0';
 
@@ -413,9 +418,24 @@ function admitPassiveAssetBytes(relativePath, bytes) {
 function assertThemeContractIntegrity(themeJson) {
   const validation = validateGalaDocument(THEME_CONTRACT_SCHEMA_ID, themeJson);
   if (!validation.valid) {
+    // A palette block the closed schema itself refuses (unknown or
+    // non-drivable key, bad profile, bad role) is a palette refusal, not a
+    // generic contract refusal, so the author sees one code for it.
+    if (
+      validation.diagnostics.every((diagnostic) =>
+        String(diagnostic.instancePointer ?? '').startsWith('/palette'),
+      )
+    ) {
+      throw new ThemeAssetError(
+        'THEME_PALETTE_INVALID',
+        `theme.json palette failed ${THEME_CONTRACT_SCHEMA_ID} validation ` +
+          `(${validation.diagnostics.length} diagnostic(s)): ` +
+          JSON.stringify(validation.diagnostics),
+      );
+    }
     throw new ThemeAssetError(
       'THEME_CONTRACT_SCHEMA_INVALID',
-      `theme.json failed urn:gala:schema:theme-contract:2.0.0 validation ` +
+      `theme.json failed ${THEME_CONTRACT_SCHEMA_ID} validation ` +
         `(${validation.diagnostics.length} diagnostic(s)): ` +
         JSON.stringify(validation.diagnostics),
     );
@@ -441,7 +461,7 @@ function assertThemeContractIntegrity(themeJson) {
   let templateRangeSatisfied;
   try {
     templateRangeSatisfied = satisfiesTemplateRange(
-      TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION,
+      TEMPLATE_RENDERER_VERSION,
       /** @type {string} */ (themeJson.templateRange),
     );
   } catch (error) {
@@ -455,9 +475,20 @@ function assertThemeContractIntegrity(themeJson) {
       'THEME_CONTRACT_VERSION_MISMATCH',
       `theme.json.templateRange (${themeJson.templateRange}) does not admit ` +
         `this renderer's own published version ` +
-        `(${TEMPLATE_STYLING_CONTRACT_TEMPLATE_VERSION})`,
+        `(${TEMPLATE_RENDERER_VERSION})`,
+    );
+  }
+  try {
+    assertSupportedComposition(themeJson.composition);
+  } catch (error) {
+    throw new ThemeAssetError(
+      'THEME_COMPOSITION_UNSUPPORTED',
+      /** @type {Error} */ (error).message,
     );
   }
+  // Template 4.1.0: every theme declares its palette bindings; a theme
+  // without them (any 4.0.0 package) is refused, with no fallback path.
+  assertThemePalette(themeJson);
 }
 
 /**
@@ -486,10 +517,14 @@ function subresourceIntegrityAttribute(bytes) {
  * @param {string} options.basePath the build input's `basePath`
  * @param {string} [options.publicBasePath] the base path emitted `<link href>`
  *   values use (`route.js#derivePublicBasePath`); defaults to `basePath`
+ * @param {unknown} [options.appearanceTokens] `appearance.tokens` (`{}` or
+ *   absent selects the theme's default palette); the derived palette sheet
+ *   is written and linked after the theme's own stylesheets
  * @returns {Promise<{
  *   files: {path: string, bytes: Buffer}[],
  *   assets: import('../../../types/index.d.ts').ManifestAssetEntry[],
  *   linkTagsHtml: string,
+ *   composition: (typeof import('./template-composition.js').SUPPORTED_COMPOSITIONS)[number],
  * }>} the files to write (already `basePath`-joined), their manifest rows
  *   (same joined paths), and the ready-to-insert `<link>` markup
  */
@@ -497,6 +532,7 @@ export async function loadThemeAssets({
   themeDirectory,
   basePath,
   publicBasePath = basePath,
+  appearanceTokens = {},
 }) {
   const { bytes: themeJsonBytes } = await readDeclaredThemeFile(
     themeDirectory,
@@ -556,6 +592,27 @@ export async function loadThemeAssets({
     );
   }
 
+  // Template 4.1.0: the publication palette sheet, derived on every build
+  // (`{}` selects the theme's default palette), content-addressed, linked
+  // last with SRI and manifested like every theme stylesheet.
+  const paletteSheet = buildPaletteStylesheet(themeJson, appearanceTokens);
+  const paletteRelativePath = `${PALETTE_STYLESHEET_DIRECTORY}/${paletteSheet.fileName}`;
+  const paletteOutputPath = projectFixedAssetPath(
+    basePath,
+    `/${paletteRelativePath}`,
+  );
+  files.push({ path: paletteOutputPath, bytes: paletteSheet.bytes });
+  assets.push({
+    path: paletteOutputPath,
+    mediaType: PALETTE_STYLESHEET_MEDIA_TYPE,
+    byteLength: String(paletteSheet.bytes.byteLength),
+    sha256: digestBytes(paletteSheet.bytes),
+    immutable: false,
+  });
+  linkTags.push(
+    `<link rel="stylesheet" href="${escapeHtml(`/${projectFixedAssetPath(publicBasePath, `/${paletteRelativePath}`)}`)}" integrity="${subresourceIntegrityAttribute(paletteSheet.bytes)}" crossorigin="anonymous">`,
+  );
+
   // TPL-M2 fix: partition by the already-shape-validated `stylesheets` list
   // itself, not by comparing `asset.mediaType` against the literal string
   // `'text/css'` — a theme declaring its own stylesheet rows with the same
@@ -611,7 +668,12 @@ export async function loadThemeAssets({
     });
   }
 
-  return { files, assets, linkTagsHtml: linkTags.join('') };
+  return {
+    files,
+    assets,
+    linkTagsHtml: linkTags.join(''),
+    composition: assertSupportedComposition(themeJson.composition),
+  };
 }
 
 /**