@rathnasgala2/template 2.2.0 → 3.0.0

package/src/core/internal/render-policy-content.js

@@ -271,7 +271,7 @@ export const CSP_HEADER_ONLY_DIRECTIVES = Object.freeze([
 export const CONTENT_SECURITY_POLICY_META_BASELINE =
   "default-src 'none'; base-uri 'none'; object-src 'none'; " +
   "form-action 'none'; script-src 'self'; " +
-  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; " +
+  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'self'; " +
   "media-src 'self'; manifest-src 'self'; worker-src 'none'";
 
 /**
@@ -287,7 +287,7 @@ export const CONTENT_SECURITY_POLICY_META_BASELINE =
 export const CONTENT_SECURITY_POLICY_COMPLETE =
   "default-src 'none'; base-uri 'none'; object-src 'none'; " +
   "frame-ancestors 'none'; form-action 'none'; script-src 'self'; " +
-  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'none'; " +
+  "style-src 'self'; img-src 'self'; font-src 'self'; connect-src 'self'; " +
   "media-src 'self'; manifest-src 'self'; worker-src 'none'";
 
 /**

package/src/core/internal/robots.js

@@ -0,0 +1,78 @@
+/**
+ * `robots.txt` generation.
+ *
+ * Every site allows all crawlers and names its sitemap by absolute URL. The
+ * publication may additionally opt out of AI training and AI-assistant
+ * crawlers through `publication.crawlers.ai` (`"allow"` | `"block"`, absent
+ * means allow). The field is read defensively, exactly like
+ * `publication.newsletter`: a build input that predates it, or carries any
+ * other value, is treated as `"allow"`.
+ *
+ * Unlisted (`noindex`) pages are deliberately not disallowed here: a
+ * crawler can only honour a `noindex` directive on a page it is allowed to
+ * fetch.
+ *
+ * Only a `robots.txt` at the host root is honoured by crawlers. This file is
+ * always written at the output root; when the site is served from a path
+ * (for example a GitHub project site), the host's own root `robots.txt` is
+ * what crawlers read, and the `Sitemap:` line here still names the absolute
+ * sitemap URL so it can be copied there.
+ */
+
+/**
+ * The AI crawler and assistant user agents blocked by `crawlers.ai:
+ * "block"`: training crawlers, search crawlers and user-initiated fetchers
+ * of the major AI providers.
+ *
+ * @type {readonly string[]}
+ */
+export const AI_CRAWLER_USER_AGENTS = Object.freeze([
+  'GPTBot',
+  'ChatGPT-User',
+  'OAI-SearchBot',
+  'ClaudeBot',
+  'Claude-User',
+  'Claude-SearchBot',
+  'anthropic-ai',
+  'Google-Extended',
+  'PerplexityBot',
+  'Perplexity-User',
+  'CCBot',
+  'Applebot-Extended',
+  'Bytespider',
+  'Meta-ExternalAgent',
+  'Amazonbot',
+]);
+
+/**
+ * @param {unknown} publication `publication` (may predate `crawlers`)
+ * @returns {'allow' | 'block'} the AI crawler policy
+ */
+export function readAiCrawlerPolicy(publication) {
+  const crawlers = /** @type {{crawlers?: unknown} | undefined} */ (
+    publication && typeof publication === 'object' ? publication : undefined
+  )?.crawlers;
+  const ai =
+    crawlers && typeof crawlers === 'object'
+      ? /** @type {{ai?: unknown}} */ (crawlers).ai
+      : undefined;
+  return ai === 'block' ? 'block' : 'allow';
+}
+
+/**
+ * @param {object} options
+ * @param {'allow' | 'block'} options.aiPolicy
+ * @param {string} options.sitemapUrl the absolute sitemap URL
+ * @returns {string} the exact `robots.txt` text
+ */
+export function buildRobotsTxt({ aiPolicy, sitemapUrl }) {
+  /** @type {string[]} */
+  const groups = ['User-agent: *\nAllow: /'];
+  if (aiPolicy === 'block') {
+    for (const agent of AI_CRAWLER_USER_AGENTS) {
+      groups.push(`User-agent: ${agent}\nDisallow: /`);
+    }
+  }
+  groups.push(`Sitemap: ${sitemapUrl}`);
+  return `${groups.join('\n\n')}\n`;
+}

package/src/core/internal/route-labels.js

@@ -65,3 +65,34 @@ export function routeSegmentForLabel(label) {
   const prefix = asciiReadablePrefix(label);
   return prefix.length > 0 ? `${prefix}-${hash}` : hash;
 }
+
+/**
+ * Derive each author's URL segment: a readable slug of the display name
+ * (lowercase ASCII, at most 48 characters), stable for a given name. When a
+ * name yields no ASCII characters or two authors yield the same slug, the
+ * author with the lower id keeps the slug and every other one falls back to
+ * its id, so a segment is always unique and a later colliding author never
+ * moves an existing author's URL.
+ *
+ * @param {readonly {id: string, displayName: string}[]} authors
+ * @returns {Map<string, string>} author id to URL segment
+ */
+export function deriveAuthorSlugs(authors) {
+  /** @type {Map<string, string>} */
+  const slugs = new Map();
+  const taken = new Set(authors.map((author) => author.id));
+  const ordered = authors.slice().sort((a, b) => (a.id < b.id ? -1 : 1));
+  for (const author of ordered) {
+    const slug = asciiReadablePrefix(author.displayName);
+    if (
+      slug !== '' &&
+      !taken.has(slug) &&
+      ![...slugs.values()].includes(slug)
+    ) {
+      slugs.set(author.id, slug);
+    } else {
+      slugs.set(author.id, author.id);
+    }
+  }
+  return slugs;
+}

package/src/core/internal/seo.js

@@ -112,3 +112,56 @@ export function resolveSocialImageUrl({
 export function twitterCardType(hasImage) {
   return hasImage ? 'summary_large_image' : 'summary';
 }
+
+/**
+ * Shorten plain text to at most `max` characters at a word boundary,
+ * appending an ellipsis when anything was cut (a `<meta name="description">`
+ * is read as a short snippet, so a clean cut beats a mid-word one).
+ *
+ * @param {string} text plain text
+ * @param {number} max the longest result, ellipsis included
+ * @returns {string} the original text when it fits, else the shortened text
+ */
+export function truncateAtWord(text, max) {
+  const collapsed = text.replace(/\s+/g, ' ').trim();
+  const characters = Array.from(collapsed);
+  if (characters.length <= max) return collapsed;
+  const clipped = characters.slice(0, max - 1).join('');
+  const cut = /\s/.test(clipped) ? clipped.replace(/\s+\S*$/, '') : clipped;
+  return `${cut.replace(/[\s,;:.–-]+$/, '')}…`;
+}
+
+/**
+ * Resolve one social image to its absolute URL and pixel dimensions.
+ *
+ * @param {object} options
+ * @param {readonly {path: string, mediaType: string}[]} options.mediaAssets
+ * @param {Readonly<Record<string, {width: number, height: number}>>} [options.mediaDimensions]
+ *   the media pipeline's pixel dimensions per derivative path
+ * @param {{path: string, sourceDigest: string} | undefined} options.reference
+ * @param {string} options.baseUrl
+ * @param {string} options.basePath the public base path
+ * @returns {{url: string, width?: number, height?: number} | undefined}
+ */
+export function resolveSocialImage({
+  mediaAssets,
+  mediaDimensions = {},
+  reference,
+  baseUrl,
+  basePath,
+}) {
+  const url = resolveSocialImageUrl({
+    mediaAssets,
+    reference,
+    baseUrl,
+    basePath,
+  });
+  if (!url) return undefined;
+  const size =
+    mediaDimensions[
+      /** @type {string} */ (
+        resolveOriginalDerivativePath(mediaAssets, reference)
+      )
+    ];
+  return { url, width: size?.width, height: size?.height };
+}

package/src/core/internal/skeleton.js

@@ -11,17 +11,18 @@
  * through {@link renderPageBody}:
  *
  * - a skip link, the very first focusable element, targeting `#main-content`;
- * - exactly one `<header>` (home link with the validated publication name and
- *   an optional core logo carrying required alternative text, plus the
- *   always-present, currently-empty `header-actions` slot);
- * - exactly one primary `<nav>` built from `navigationNormalized.items`;
- * - exactly one `<main id="main-content">`, carrying an optional breadcrumb
- *   `<nav>` before the page's own single `<h1>`;
- * - exactly one `<footer>` with the publication name, resolved footer
- *   navigation, footer profile slot, copyright/license text and the
- *   template attribution line, plus the remaining always-present,
- *   currently-empty core slots (`footer-auxiliary`, `account-intent`,
- *   `conversation`, `newsletter`, `edition-selector`).
+ * - exactly one `<header>` (brand mark or monogram, publication name and
+ *   tagline, the one primary `<nav>` built from `navigationNormalized.items`,
+ *   a script-revealed search button, the `header-actions` slot carrying the
+ *   appearance control, and a `<details>` mobile menu), rendered by
+ *   `internal/chrome.js`;
+ * - 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),
+ *   plus the always-present, currently-empty core slots (`footer-auxiliary`,
+ *   `account-intent`, `conversation`, `newsletter`, `edition-selector`),
+ *   rendered by `internal/chrome.js`.
  *
  * Core owns nine versioned semantic slots plus the collapsed
  * `article-footer-ad` slot: `header-actions`, `article-preamble`,
@@ -133,7 +134,7 @@ export function renderSlot(slotName, options = {}) {
  */
 export function renderSkipLink(messages) {
   const label = escapeHtml(/** @type {string} */ (messages.skipToContent));
-  return `<a href="#main-content">${label}</a>`;
+  return `<a class="g-skip" href="#main-content">${label}</a>`;
 }
 
 /**
@@ -148,7 +149,7 @@ export function renderSkipLink(messages) {
  *   internal route's href (`/` when `baseUrl` has no path)
  * @returns {string} the rendered `<li>`
  */
-function renderNavItem(item, currentRoute, urlPrefix) {
+export function renderNavItem(item, currentRoute, urlPrefix) {
   const label = escapeHtml(item.label);
   const href = escapeHtml(
     /** @type {string} */ (
@@ -200,28 +201,7 @@ export function renderPrimaryNavigation({
   const itemsHtml = items
     .map((item) => renderNavItem(item, currentRoute, urlPrefix))
     .join('');
-  return `<nav aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
-}
-
-/**
- * Render the footer `<nav>` from `navigationNormalized.footerItems`.
- *
- * @param {object} options rendering options
- * @param {readonly import('../../../types/index.d.ts').NavigationItem[]} options.items
- *   `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, urlPrefix = '/' }) {
-  const label = escapeHtml(
-    /** @type {string} */ (messages.footerNavigationLabel),
-  );
-  const itemsHtml = items
-    .map((item) => renderNavItem(item, undefined, urlPrefix))
-    .join('');
-  return `<nav aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
+  return `<nav class="g-nav" aria-label="${label}"><ul>${itemsHtml}</ul></nav>`;
 }
 
 /**
@@ -262,7 +242,7 @@ export function renderBreadcrumbs({ trail, messages }) {
       return `<li><a href="${escapeHtml(step.route)}">${text}</a></li>`;
     })
     .join('');
-  return `<nav aria-label="${label}"><ol>${items}</ol></nav>`;
+  return `<nav class="g-crumbs" aria-label="${label}"><ol>${items}</ol></nav>`;
 }
 
 /**
@@ -307,7 +287,7 @@ export function renderPagination({
       ? `<a rel="next" href="${escapeHtml(routeForPage(currentPage + 1))}">${nextLabel}</a>`
       : `<span>${nextLabel}</span>`;
   return (
-    `<nav aria-label="${label}"><ul>` +
+    `<nav class="g-pagination" aria-label="${label}"><ul>` +
     `<li>${previous}</li>` +
     `<li aria-current="page">${statusLabel}</li>` +
     `<li>${next}</li>` +
@@ -316,117 +296,62 @@ export function renderPagination({
 }
 
 /**
- * Render the one `<header>` landmark.
+ * Render the (initially invisible) status region the site script uses for
+ * short confirmations, and the carrier of every localized string the script
+ * needs: each one is a plain `data-*` attribute, so the script ships no
+ * language of its own. With JavaScript off it is an empty, inert live region.
  *
- * @param {object} options rendering options
- * @param {string} options.homeRoute the publication's own home route
- *   (`basePath`, joined)
- * @param {string} options.publicationName the validated publication title
- * @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
- *   (`internal/appearance/controller-markup.js`'s `renderAppearanceControl`),
- *   inserted into the `header-actions` slot
- * @returns {string} the rendered header
- */
-export function renderHeader({
-  homeRoute,
-  publicationName,
-  logo,
-  appearanceControlHtml,
-}) {
-  const name = escapeHtml(publicationName);
-  const href = escapeHtml(homeRoute);
-  const logoHtml = logo
-    ? `<img src="${escapeHtml(logo.route)}" alt="${escapeHtml(logo.alt)}">`
-    : '';
-  return (
-    '<header>' +
-    `<a href="${href}">${logoHtml}<span>${name}</span></a>` +
-    renderSlot('header-actions', { html: appearanceControlHtml }) +
-    '</header>'
-  );
-}
-
-/**
- * Render the one `<footer>` landmark.
- *
- * @param {object} options rendering options
- * @param {string} options.publicationName the validated publication title
- * @param {string} options.footerNavHtml the already-rendered footer
- *   navigation (see {@link renderFooterNavigation})
- * @param {string} options.footerProfileHtml the already-rendered
- *   `footer-profile` slot content (footer card and/or author cards; may be
- *   empty when the publication authored neither)
- * @param {string | undefined} options.copyrightText an optional
- *   already-resolved copyright/license text line
- * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
+ * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} messages
  *   the resolved message catalog
- * @returns {string} the rendered footer
+ * @returns {string} the toast element
  */
-export function renderFooter({
-  publicationName,
-  footerNavHtml,
-  footerProfileHtml,
-  copyrightText,
-  messages,
-}) {
-  const name = escapeHtml(publicationName);
-  const copyrightHtml = copyrightText
-    ? `<p>${escapeHtml(copyrightText)}</p>`
-    : '';
-  const attribution = escapeHtml(
-    /** @type {string} */ (messages.footerAttributionLabel),
-  );
-  return (
-    '<footer>' +
-    `<p>${name}</p>` +
-    footerNavHtml +
-    `<div data-gala-slot="footer-profile">${footerProfileHtml}</div>` +
-    renderSlot('footer-auxiliary') +
-    renderSlot('account-intent') +
-    renderSlot('conversation') +
-    renderSlot('newsletter') +
-    renderSlot('edition-selector') +
-    copyrightHtml +
-    `<p>${attribution}</p>` +
-    '</footer>'
-  );
+export function renderToast(messages) {
+  /** @type {readonly [string, string][]} */
+  const strings = [
+    ['search-label', 'searchButtonAriaLabel'],
+    ['search-placeholder', 'searchPlaceholderLabel'],
+    ['search-empty', 'searchEmptyLabel'],
+    ['search-unavailable', 'searchUnavailableLabel'],
+    ['copy', 'copyCodeLabel'],
+    ['copied', 'copiedLabel'],
+    ['link-copied', 'linkCopiedLabel'],
+    ['copy-blocked', 'copyBlockedLabel'],
+    ['code-selected', 'codeSelectedLabel'],
+    ['saved', 'savedLabel'],
+    ['unsaved', 'unsavedLabel'],
+  ];
+  const attributes = strings
+    .map(
+      ([name, key]) =>
+        ` data-${name}="${escapeHtml(/** @type {string} */ (messages[key]))}"`,
+    )
+    .join('');
+  return `<div class="g-toast" role="status" aria-live="polite"${attributes}></div>`;
 }
 
 /**
  * Compose one complete page body (everything inside `<body>`) from its
  * pre-rendered landmark parts. Every page kind in `internal/page-kinds.js`
  * funnels through this one function, so the landmark order and count (one
- * skip link, one header, one primary nav, one main, one footer) can never
- * drift between page kinds.
+ * skip link, one header carrying the one primary nav, one main, one footer)
+ * can never drift between page kinds.
  *
  * @param {object} options rendering options
  * @param {Readonly<Record<string, string | ((...args: string[]) => string)>>} options.messages
  *   the resolved message catalog
- * @param {string} options.headerHtml the already-rendered header
- * @param {string} options.navHtml the already-rendered primary navigation
+ * @param {string} options.headerHtml the already-rendered header (which
+ *   contains the primary navigation; see `internal/chrome.js`)
  * @param {string} options.footerHtml the already-rendered footer
- * @param {string} [options.breadcrumbHtml] an optional already-rendered
- *   breadcrumb, inserted before the page's own `<h1>`
- * @param {string} options.mainHtml the page kind's own inner markup, always
- *   starting with exactly one `<h1>`
+ * @param {string} options.mainHtml the page kind's own inner markup,
+ *   including its breadcrumb (when it has one) and exactly one `<h1>`
  * @returns {string} the complete `<body>` inner HTML
  */
-export function renderPageBody({
-  messages,
-  headerHtml,
-  navHtml,
-  footerHtml,
-  breadcrumbHtml,
-  mainHtml,
-}) {
+export function renderPageBody({ messages, headerHtml, footerHtml, mainHtml }) {
   return (
     renderSkipLink(messages) +
+    renderToast(messages) +
     headerHtml +
-    navHtml +
-    `<main id="main-content">${breadcrumbHtml ?? ''}${mainHtml}</main>` +
+    `<main id="main-content" class="g-main" tabindex="-1">${mainHtml}</main>` +
     footerHtml
   );
 }