@rathnasgala2/template 3.1.0 → 3.2.0

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

@@ -15,6 +15,10 @@
  *   `/authors/<id>`;
  * - `article` / `page` — one page per `content[]` record, at its own
  *   `contentFrontmatterNormalized` route;
+ * - an `edition` record (`kind: "edition"`, `internal/editions.js`) is an
+ *   article page too, for the page-kind hook: it renders at
+ *   `<article>/quick-read`, `/standard` or `/deep-dive`, names the article as
+ *   its canonical URL, is `noindex, follow`, and never enters a listing;
  * - `index` — a paginated reverse-chronological listing of every
  *   `status: "published"` `kind: "article"` record (an `unlisted` record is
  *   reachable only by its own direct route or an authored navigation entry,
@@ -62,11 +66,17 @@ import {
   createComponents,
   createMediaImage,
   extractH2Headings,
-  lazyBodyImages,
   plainText,
   renderImage,
   renderNewsletterPanel,
 } from './components.js';
+import {
+  editionKindLabel,
+  editionRoute,
+  listedEditions,
+  renderEditionSelector,
+  resolveEditions,
+} from './editions.js';
 import { truncateAtWord } from './seo.js';
 import { createStructuredData } from './structured-data.js';
 import { icon } from './icons.js';
@@ -123,9 +133,13 @@ export const PAGE_KIND_VALUES = Object.freeze(
 
 /**
  * @param {import('../../../types/index.d.ts').ContentFrontmatterNormalized} frontmatter
- * @returns {string} the record's own canonical route (un-joined)
+ * @returns {string} the record's own canonical route (un-joined); an
+ *   edition's is derived from the article it restates, never authored
  */
 export function contentRoute(frontmatter) {
+  if (frontmatter.kind === 'edition' && frontmatter.edition) {
+    return editionRoute(frontmatter.edition);
+  }
   return frontmatter.route ?? `/${frontmatter.slug}`;
 }
 
@@ -153,6 +167,9 @@ function paginate(items, pageSize) {
  * @property {'profile' | 'author' | 'article' | 'page' | 'index' | 'tag' | 'series' | 'archive'} kind
  * @property {string} route an un-joined `canonicalRoute` (caller joins with
  *   `basePath`)
+ * @property {string} [canonicalRoute] the un-joined route the page's
+ *   `<link rel="canonical">` names when it is not the page's own (an edition
+ *   names its article)
  * @property {string} title the page's `<title>` text
  * @property {string} language the page's BCP-47 language tag
  * @property {string} [direction] the page's resolved base text direction (assigned by buildGeneratedPages's own return mapping)
@@ -351,7 +368,12 @@ export function homeDocumentTitle(name, tagline) {
  * `build-input:2.0.0` instance.
  *
  * @param {import('../../../types/index.d.ts').NormalizedBuildInput} validatedInput
- * @param {object} [options] rendering options
+ * @param {object} options rendering options
+ * @param {(body: string) => string} options.pageBody turns a body into its
+ *   page form (every image naming its media derivatives, lazily loaded)
+ * @param {import('./editions.js').EditionResolution} [options.editions] where
+ *   each edition sits beside its article; resolved from the build input when
+ *   the caller has not already done so
  * @param {readonly {path: string, mediaType: string}[]} [options.mediaAssets]
  *   the media pipeline's finished `assets` list, used to resolve every
  *   image reference (hero, avatar) to its emitted URL; an image with no
@@ -364,7 +386,7 @@ export function homeDocumentTitle(name, tagline) {
  * @returns {GeneratedPage[]} every generated page, in a stable, deterministic
  *   order
  */
-export function buildGeneratedPages(validatedInput, options = {}) {
+export function buildGeneratedPages(validatedInput, options) {
   const { publication, authors, content, basePath, baseUrl } = validatedInput;
   const interactionsModule = interactionsActive(options.interactions)
     ? options.interactions
@@ -372,6 +394,7 @@ export function buildGeneratedPages(validatedInput, options = {}) {
   const publicBasePath = derivePublicBasePath(baseUrl, basePath);
   const messages = getMessages(publication.defaultLanguage);
   const authorsById = new Map(authors.map((author) => [author.id, author]));
+  const editions = options.editions ?? resolveEditions(content, contentRoute);
 
   /**
    * @param {string} route an un-joined route
@@ -474,7 +497,11 @@ export function buildGeneratedPages(validatedInput, options = {}) {
   const publishedArticles = selectPublishedArticles(content);
   const byTag = groupBy(publishedArticles, (r) => r.frontmatter.tags);
   const bySeries = groupBy(
-    content.filter((r) => r.frontmatter.status === 'published'),
+    content.filter(
+      (r) =>
+        r.frontmatter.kind !== 'edition' &&
+        r.frontmatter.status === 'published',
+    ),
     (r) => (r.frontmatter.series ? [r.frontmatter.series] : []),
   );
   for (const bucket of bySeries.values()) {
@@ -658,7 +685,7 @@ export function buildGeneratedPages(validatedInput, options = {}) {
       bodyHtml:
         `<article class="g-article"><div class="g-wrap g-article-head">` +
         `<h1>${escapeHtml(publication.title)}</h1></div>` +
-        `<div class="g-wrap g-article-grid"><div class="g-prose">${lazyBodyImages(publication.profile.body.body)}</div></div></article>`,
+        `<div class="g-wrap g-article-grid"><div class="g-prose">${options.pageBody(publication.profile.body.body)}</div></div></article>`,
     });
   }
 
@@ -727,7 +754,15 @@ export function buildGeneratedPages(validatedInput, options = {}) {
   for (const record of content) {
     const { frontmatter } = record;
     const isArticle = frontmatter.kind === 'article';
-    const hero = mediaImage(frontmatter.hero?.file);
+    // An edition restates `original`; a document that is not one is its own.
+    const edition = editions.byRecord.get(record);
+    const isEdition = edition !== undefined;
+    const original = edition?.original ?? record;
+    // An edition with no cover of its own wears its article's.
+    const heroMedia = isEdition
+      ? (frontmatter.hero ?? original.frontmatter.hero)
+      : frontmatter.hero;
+    const hero = mediaImage(heroMedia?.file);
     const headings = extractH2Headings(record.body);
     const contents =
       headings.length >= CONTENTS_MIN_HEADINGS
@@ -738,12 +773,17 @@ export function buildGeneratedPages(validatedInput, options = {}) {
             )
             .join('')}</ol>`
         : '';
-    const firstTag = frontmatter.tags[0];
+    const firstTag = original.frontmatter.tags[0];
     const trail = [
-      ...(isArticle && firstTag
+      ...((isArticle || isEdition) && firstTag
         ? [{ label: firstTag, route: tagHref(firstTag) }]
         : []),
-      { label: frontmatter.title },
+      ...(edition
+        ? [
+            { label: original.frontmatter.title, route: recordHref(original) },
+            { label: editionKindLabel(edition.kind, messages) },
+          ]
+        : [{ label: frontmatter.title }]),
     ];
     const partLabel = partLabelOf(record);
     const series = frontmatter.series;
@@ -754,6 +794,19 @@ export function buildGeneratedPages(validatedInput, options = {}) {
           : '') +
         `${escapeHtml(series)}</a>`
       : '';
+    const share =
+      `<div class="g-share" role="group" aria-label="${text('shareLabel')}" hidden>` +
+      `<button class="g-icon-btn" type="button" data-action="copy-link" aria-label="${text('copyLinkLabel')}" title="${text('copyLinkLabel')}">${icon('link')}</button>` +
+      `<button class="g-icon-btn" type="button" data-action="bookmark" aria-pressed="false" aria-label="${text('saveForLaterLabel')}" title="${text('saveForLaterLabel')}">${icon('bookmark')}</button>` +
+      `</div>`;
+    // The article and each of its editions offer the same selector.
+    const editionSelector = renderEditionSelector({
+      messages,
+      originalHref: recordHref(original),
+      entries: listedEditions(editions.byOriginal.get(original), edition),
+      current: edition,
+      site,
+    });
     const head =
       `<div class="g-wrap g-article-head">${renderBreadcrumbs({ trail: [homeStep, ...trail], messages })}` +
       (isArticle
@@ -763,16 +816,13 @@ export function buildGeneratedPages(validatedInput, options = {}) {
       (frontmatter.description
         ? `<p class="g-dek">${escapeHtml(frontmatter.description)}</p>`
         : '') +
-      (isArticle
-        ? `<div class="g-article-meta">${byline(record, true)}` +
-          `<div class="g-share" role="group" aria-label="${text('shareLabel')}" hidden>` +
-          `<button class="g-icon-btn" type="button" data-action="copy-link" aria-label="${text('copyLinkLabel')}" title="${text('copyLinkLabel')}">${icon('link')}</button>` +
-          `<button class="g-icon-btn" type="button" data-action="bookmark" aria-pressed="false" aria-label="${text('saveForLaterLabel')}" title="${text('saveForLaterLabel')}">${icon('bookmark')}</button>` +
-          `</div></div>`
+      (isArticle || isEdition
+        ? `<div class="g-article-meta">${byline(record, true)}${isArticle ? share : ''}</div>`
         : '') +
+      editionSelector +
       `</div>`;
     const cover = hero
-      ? `<figure class="g-wrap g-article-cover">${renderImage({ image: hero, alt: frontmatter.hero?.role === 'decorative' ? '' : (frontmatter.hero?.alt ?? ''), priority: true })}</figure>`
+      ? `<figure class="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>`
@@ -792,7 +842,7 @@ export function buildGeneratedPages(validatedInput, options = {}) {
     const prose =
       `<div class="g-prose">${tocMobile}` +
       renderSlot('article-preamble') +
-      lazyBodyImages(record.body) +
+      options.pageBody(record.body) +
       tags +
       renderSlot('article-end') +
       renderSlot('article-footer-ad', { collapsed: true }) +
@@ -874,8 +924,17 @@ export function buildGeneratedPages(validatedInput, options = {}) {
     const articleTrail = [
       homeStep,
       ...trail.slice(0, -1),
-      { label: frontmatter.title, route: recordHref(record) },
+      {
+        label: trail.at(-1)?.label ?? frontmatter.title,
+        route: recordHref(record),
+      },
     ];
+    // An edition with no social image of its own shares its article's.
+    const social = socialOfContent(
+      isEdition && !frontmatter.socialImage && !frontmatter.hero
+        ? original.frontmatter
+        : frontmatter,
+    );
     const articleGraph = isArticle
       ? sd.article({
           url: ownUrl,
@@ -905,14 +964,24 @@ export function buildGeneratedPages(validatedInput, options = {}) {
           dateModified: contentLastModified(frontmatter),
         });
     pages.push({
-      kind: frontmatter.kind,
+      // An edition is an article page for the page-kind hook.
+      kind: frontmatter.kind === 'edition' ? 'article' : frontmatter.kind,
       route: contentRoute(frontmatter),
+      canonicalRoute: edition ? contentRoute(original.frontmatter) : undefined,
       title: frontmatter.title,
-      documentTitle: documentTitleOf(frontmatter.title),
+      documentTitle: documentTitleOf(
+        edition
+          ? msg(
+              'editionPageTitle',
+              frontmatter.title,
+              editionKindLabel(edition.kind, messages),
+            )
+          : frontmatter.title,
+      ),
       language: frontmatter.language,
       description: contentDescription(record),
-      ogType: isArticle ? 'article' : 'website',
-      ...socialOfContent(frontmatter),
+      ogType: isArticle || isEdition ? 'article' : 'website',
+      ...social,
       jsonLd: sd.serialize(articleGraph),
       articleMeta: isArticle
         ? {
@@ -924,12 +993,15 @@ export function buildGeneratedPages(validatedInput, options = {}) {
             tags: [...frontmatter.tags],
           }
         : undefined,
+      // An edition is never indexed: its article is the reference.
       robotsContent:
-        frontmatter.status === 'unlisted' ? 'noindex, follow' : undefined,
+        isEdition || frontmatter.status === 'unlisted'
+          ? 'noindex, follow'
+          : undefined,
       interactionBearing: Boolean(interactions),
       lastModified: contentLastModified(frontmatter),
       bodyHtml:
-        `<article class="g-article">${isArticle ? '<div class="g-progress" aria-hidden="true"></div>' : ''}${head}${cover}` +
+        `<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>` +
         after +
         (isArticle ? newsletterHtml : ''),

package/src/core/internal/skeleton.js

@@ -19,10 +19,11 @@
  * - exactly one `<main id="main-content">`; each page kind places its own
  *   breadcrumb `<nav>` and single `<h1>` inside it;
  * - exactly one `<footer>` (brand, description, social links, navigation
- *   columns, author profile, copyright and the template attribution line),
+ *   columns, author profile, copyright and the template attribution line,
+ *   which `appearance.attribution.showMadeWith: false` omits),
  *   plus the always-present, currently-empty core slots (`footer-auxiliary`,
- *   `account-intent`, `conversation`, `newsletter`, `edition-selector`),
- *   rendered by `internal/chrome.js`.
+ *   `account-intent`, `conversation`, `newsletter`), rendered by
+ *   `internal/chrome.js`.
  *
  * Core owns nine versioned semantic slots plus the collapsed
  * `article-footer-ad` slot: `header-actions`, `article-preamble`,
@@ -46,7 +47,11 @@
  * 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.
+ *
+ * `edition-selector` is not a footer slot: it is rendered by the article page
+ * kind (`internal/editions.js`) at the end of the article head, on an article
+ * that has a published edition and on each edition page, and is not rendered
+ * on a page with no edition to offer. Every other slot is unaffected.
  *
  * The exact `selectorAtom`/hook-naming decisions here (`data-gala-slot`
  * attribute, one slot name per value) are what
@@ -106,6 +111,22 @@ export function escapeHtml(value) {
   return escaped;
 }
 
+/**
+ * Decode the five predefined entities {@link escapeHtml} produces, turning an
+ * attribute value as it appears in sanitized HTML back into its text.
+ *
+ * @param {string} value an attribute value as it appears in HTML source
+ * @returns {string} the value with the five predefined entities decoded
+ */
+export function unescapeHtml(value) {
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+}
+
 /**
  * Render one always-present, currently-empty core semantic slot.
  *

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

@@ -89,6 +89,10 @@ export function collectIncludedSources(buildInput) {
       contentRecord.frontmatter.socialImage,
       contentRecord.sourceRevision,
     );
+    // The document's inventoried media (its body images' sources).
+    for (const mediaFile of contentRecord.media ?? []) {
+      recordResolvedFile(record, mediaFile, contentRecord.sourceRevision);
+    }
   }
 
   if (buildInput.navigation.source.kind === 'authored') {