react-cheminfo 0.35.0 → 0.37.0

package/src/seo/core/pageMeta.ts

@@ -14,14 +14,26 @@
 
 import { siteDisplayName } from '../../ecosystem/core/lookup.ts';
 import type { SiteId, SiteRecord } from '../../ecosystem/core/sites.ts';
+import type { Language } from '../../i18n/core/languages.ts';
+import { DEFAULT_LANGUAGE } from '../../i18n/core/languages.ts';
+import {
+  readLanguagePath,
+  withLanguagePath,
+} from '../../language/core/languagePath.ts';
+import { withoutQueryOrFragment } from '../../router/core/address.ts';
+import { stripBasePath } from '../../router/core/basePath.ts';
 import { escapeAttribute, escapeText } from '../../share/core/escape.ts';
 
+import { alternateLinkTags } from './alternates.ts';
 import type { DocumentMeta } from './documentMeta.ts';
 import type { RouteMeta } from './routes.ts';
 import { pageMetaFor } from './routes.ts';
 import { mountPathOf, originOf, resolveSite } from './siteFiles.ts';
 import { PAGE_HEAD_MARKER, fill } from './template.ts';
 
+// A scheme and an authority: what `location.href` hands out.
+const ABSOLUTE_URL = /^[a-z][\d+.a-z-]*:\/\//i;
+
 /** Which site is being served, and what it answers. */
 export interface PageMetaOptions {
   /** The site, named or passed. */
@@ -48,6 +60,17 @@ export interface PageMetaOptions {
    * @default '/og.png'
    */
   image?: string;
+  /**
+   * Every language the site is written in, the default one included.
+   *
+   * The language is read off the address — `/fr/tutorial` is the French
+   * tutorial — so the canonical, the card and the `hreflang` set are written
+   * for the page actually being served, and the routes passed are the table in
+   * that language. A site writing one language leaves this out and nothing
+   * about its head changes.
+   * @default [the default language]
+   */
+  languages?: readonly Language[];
 }
 
 /**
@@ -74,12 +97,27 @@ export function injectPageMeta(html: string, options: PageMetaOptions): string {
  */
 export function pageHeadTags(options: PageMetaOptions): string {
   const name = siteDisplayName(resolveSite(options.site));
-  const description = routeMetaOf(options).description;
+  const route = routeMetaOf(options);
+  const description = route.description;
   const origin = originOf(options);
   const { title, canonical } = pageDocumentMeta(options);
   const image = absolute(options.image ?? '/og.png', origin);
+  const alternates = alternateLinkTags({
+    origin,
+    path: route.path,
+    languages: languagesOf(options),
+  });
+
+  // A maintenance screen says so on the page itself. `robots.txt` cannot: it
+  // stops the crawl, and an address nobody crawled is still listed from
+  // whatever links to it, with no description to show for it.
+  const robots =
+    route.indexed === false
+      ? ['<meta name="robots" content="noindex, nofollow" />']
+      : [];
 
   return [
+    ...robots,
     `<title>${escapeText(title)}</title>`,
     `<meta name="description" content="${escapeAttribute(description)}" />`,
     `<link rel="canonical" href="${escapeAttribute(canonical)}" />`,
@@ -90,6 +128,7 @@ export function pageHeadTags(options: PageMetaOptions): string {
     `<meta property="og:url" content="${escapeAttribute(canonical)}" />`,
     `<meta property="og:image" content="${escapeAttribute(image)}" />`,
     '<meta name="twitter:card" content="summary_large_image" />',
+    ...(alternates === '' ? [] : [alternates]),
   ].join('\n');
 }
 
@@ -112,15 +151,47 @@ export function pageDocumentMeta(
   return {
     title: `${meta.title} — ${siteDisplayName(site)}`,
     description: meta.description,
-    canonical: `${originOf(options)}${meta.path}`,
+    canonical: `${originOf(options)}${withLanguagePath(pageLanguage(options), meta.path)}`,
   };
 }
 
+/**
+ * The language an address is being served in.
+ *
+ * Read off the address itself rather than passed beside it, so the catalog a
+ * server picks and the canonical it writes cannot disagree.
+ * @param options - Which site, which address, and the languages it speaks.
+ * @returns The language named by the address, or the default one.
+ * @throws {Error} When the deployment names an origin that is not an absolute
+ * address.
+ */
+export function pageLanguage(options: PageMetaOptions): Language {
+  return readLanguagePath(ownPath(options), languagesOf(options)).language;
+}
+
 // A server behind a mount is handed the address the browser asked for, and the
 // route table is written from the site's own root, so the mount the origin
 // carries is taken off it before the table is read.
 function routeMetaOf(options: PageMetaOptions): RouteMeta {
-  return pageMetaFor(options.routes, options.url, mountPathOf(options));
+  const { path } = readLanguagePath(ownPath(options), languagesOf(options));
+  return pageMetaFor(options.routes, path);
+}
+
+// The address from the site's own root, the mount taken off, with the query
+// string and the fragment gone: what the language prefix is read off. An app
+// handing over `location.href` is answered too, so the one reading serves a
+// server, a build and a click alike.
+function ownPath(options: PageMetaOptions): string {
+  const url = options.url;
+  const path =
+    ABSOLUTE_URL.test(url) && URL.canParse(url)
+      ? new URL(url).pathname
+      : withoutQueryOrFragment(url);
+  return stripBasePath(mountPathOf(options), path);
+}
+
+function languagesOf(options: PageMetaOptions): readonly Language[] {
+  return options.languages ?? [DEFAULT_LANGUAGE];
 }
 
 function absolute(target: string, origin: string): string {

package/src/seo/core/pageProse.ts

@@ -0,0 +1,146 @@
+/**
+ * The text a page is indexed on, written into the HTML before anything runs.
+ *
+ * A prerendered site writes one file per address, and each of them carried the
+ * same body: the site's crawl path, and nothing else. A search engine clusters
+ * pages by the text it is handed, so a hundred and eighteen element pages
+ * differing only in their title are a hundred and seventeen duplicates — and
+ * which one it keeps is not ours to choose. A page heavy enough that the
+ * renderer never gets to it is indexed on that body alone.
+ *
+ * So what a site writes here is the text its running app already shows, drawn
+ * from the same data: the prose is not written twice, it is written where the
+ * build can reach it. Text only, and escaped — the addresses a reader follows
+ * are the crawl path's business.
+ */
+
+import { escapeText } from '../../share/core/escape.ts';
+
+/** A table of facts under the prose: the rows a page would show anyway. */
+export interface PageTable {
+  /** Header cells, left to right. */
+  columns: readonly string[];
+  /** Body rows, each as many cells as there are columns. */
+  rows: ReadonlyArray<readonly string[]>;
+  /**
+   * The sentence under the table, saying where the numbers come from.
+   * @default undefined — the table stands on its own
+   */
+  caption?: string;
+}
+
+/** One run of the page's text: a heading, prose, and the facts under it. */
+export interface PageSection {
+  /**
+   * The heading it opens with, as an `h2`.
+   * @default undefined — the run carries no heading
+   */
+  heading?: string;
+  /**
+   * The paragraphs under it, each taken as written.
+   * @default undefined — no prose
+   */
+  paragraphs?: readonly string[];
+  /**
+   * A list under the prose, one item per line.
+   * @default undefined — no list
+   */
+  list?: readonly string[];
+  /**
+   * A table under the prose.
+   * @default undefined — no table
+   */
+  table?: PageTable;
+}
+
+/** The whole of one page's text, as the page itself would say it. */
+export interface PageContent extends PageSection {
+  /**
+   * The page's own name, written as its `h1`. It answers the title the page is
+   * indexed under, so a reader who searched for it reads the same words again.
+   */
+  heading: string;
+  /**
+   * The runs under the opening prose, in reading order.
+   * @default undefined — the page is its opening prose
+   */
+  sections?: readonly PageSection[];
+}
+
+/**
+ * The page's text as HTML, everything below its heading.
+ *
+ * The heading itself is left to the caller, which already writes the one `h1`
+ * the page carries — `noscriptIndex` does.
+ * @param content - What the page says.
+ * @param indent - The indentation every line is written at.
+ * @default '  '
+ * @returns The HTML, opening with a newline, or `''` when the page says nothing
+ * below its heading.
+ */
+export function pageProseHtml(content: PageContent, indent = '  '): string {
+  // The page's own heading is the caller's `h1`; what is left of its opening run
+  // is prose like any section's.
+  const opening: PageSection = {
+    paragraphs: content.paragraphs,
+    list: content.list,
+    table: content.table,
+  };
+  const parts = [
+    sectionHtml(opening, indent),
+    ...(content.sections ?? []).map((section) => sectionHtml(section, indent)),
+  ];
+  return parts.join('');
+}
+
+function sectionHtml(section: PageSection, indent: string): string {
+  const lines: string[] = [];
+  if (section.heading !== undefined && section.heading.trim() !== '') {
+    lines.push(`${indent}<h2>${escapeText(section.heading)}</h2>`);
+  }
+  for (const paragraph of section.paragraphs ?? []) {
+    if (paragraph.trim() === '') continue;
+    lines.push(`${indent}<p>${escapeText(paragraph)}</p>`);
+  }
+  const list = listHtml(section.list, indent);
+  if (list !== '') lines.push(list);
+  const table = tableHtml(section.table, indent);
+  if (table !== '') lines.push(table);
+  return lines.length === 0 ? '' : `\n${lines.join('\n')}`;
+}
+
+function listHtml(list: readonly string[] | undefined, indent: string): string {
+  // A list with no item is not a list: `<ul>` holds at least one `<li>`.
+  if (list === undefined || list.length === 0) return '';
+  const items = list
+    .map((item) => `${indent}  <li>${escapeText(item)}</li>`)
+    .join('\n');
+  return `${indent}<ul>\n${items}\n${indent}</ul>`;
+}
+
+function tableHtml(table: PageTable | undefined, indent: string): string {
+  // A table with no row says nothing, and an empty `<tbody>` is not markup a
+  // crawler is owed.
+  if (table === undefined || table.rows.length === 0) return '';
+  const caption =
+    table.caption === undefined || table.caption.trim() === ''
+      ? ''
+      : `\n${indent}  <caption>${escapeText(table.caption)}</caption>`;
+  const head = table.columns
+    .map((column) => `<th>${escapeText(column)}</th>`)
+    .join('');
+  const body = table.rows
+    .map(
+      (row) =>
+        `${indent}    <tr>${row.map((cell) => `<td>${escapeText(cell)}</td>`).join('')}</tr>`,
+    )
+    .join('\n');
+  return `${indent}<table>${caption}
+${indent}  <thead>
+${indent}    <tr>${head}</tr>
+${indent}  </thead>
+${indent}  <tbody>
+${body}
+${indent}  </tbody>
+${indent}</table>`;
+}

package/src/seo/core/routeProblems.ts

@@ -0,0 +1,111 @@
+/**
+ * What is wrong with the prose a site is indexed under.
+ *
+ * A route table is the only place a search result is written, and it is written
+ * once and read for years, so the limits that decide whether a result is
+ * readable are checked rather than trusted: a title Google cuts in half, a
+ * description too short to say anything or long enough to be clipped, two pages
+ * sharing a sentence — which is how a site asks to be deduplicated down to one
+ * result — and a snippet promising something the page does not carry.
+ *
+ * The paths are `assertRoutes`' business; this is about the words.
+ */
+
+import type { RouteMeta } from './routes.ts';
+
+/** The longest title that survives a search result whole. */
+const TITLE_LIMIT = 60;
+/** The shortest description that says anything. */
+const DESCRIPTION_MIN = 110;
+/** The longest description a result shows without clipping it. */
+const DESCRIPTION_MAX = 160;
+
+/**
+ * What a site never says about itself, in the words it would say it in. A
+ * snippet naming a repository, a tracker or a licence is both a promise the
+ * page does not keep and a thing we do not publish.
+ */
+const WITHHELD =
+  /\b(?:licence|license|licensing|open[ -]source|repositor(?:y|ies)|issue tracker|source code|report a (?:problem|bug|issue))\b/i;
+
+/**
+ * The phrase in a snippet that names something a site does not publish.
+ *
+ * Shared with the build-time checker, which reads the same sentences back out
+ * of the pages they were written into: one list of words, checked where they
+ * are authored and again where they landed.
+ * @param text - A title or a description.
+ * @returns The phrase, or `undefined` when there is none.
+ */
+export function withheldPhrase(text: string): string | undefined {
+  return WITHHELD.exec(text)?.[0];
+}
+
+/**
+ * Check the table a site is indexed under, before a build reads it.
+ *
+ * Returns the problems rather than throwing, so a site asserts an empty list in
+ * its own test and reads every one of them at once.
+ * @param routes - Every address the site answers.
+ * @returns One line per problem, empty when the table is fit to ship.
+ */
+export function routeProblems(routes: readonly RouteMeta[]): string[] {
+  const problems: string[] = [];
+
+  if (routes.length === 0) {
+    problems.push('the table is empty: a site answers at least one route.');
+    return problems;
+  }
+
+  const titles = new Map<string, string>();
+  const descriptions = new Map<string, string>();
+
+  for (const route of routes) {
+    const at = route.path;
+
+    if (route.title.trim() === '') {
+      problems.push(`${at}: the title is empty.`);
+    } else if (route.title.length > TITLE_LIMIT) {
+      problems.push(
+        `${at}: the title is ${route.title.length} characters, and the site name is appended to it — at most ${TITLE_LIMIT} survives a result whole.`,
+      );
+    }
+
+    const length = route.description.length;
+    if (length < DESCRIPTION_MIN) {
+      problems.push(
+        `${at}: the description is ${length} characters — at least ${DESCRIPTION_MIN}, or the result says half of what the page is.`,
+      );
+    } else if (length > DESCRIPTION_MAX) {
+      problems.push(
+        `${at}: the description is ${length} characters — at most ${DESCRIPTION_MAX}, or the sentence is cut off in the result itself.`,
+      );
+    }
+
+    const titleFirst = titles.get(route.title);
+    if (titleFirst === undefined) {
+      titles.set(route.title, at);
+    } else {
+      problems.push(`${at}: the title repeats the one at ${titleFirst}.`);
+    }
+
+    const descriptionFirst = descriptions.get(route.description);
+    if (descriptionFirst === undefined) {
+      descriptions.set(route.description, at);
+    } else {
+      problems.push(
+        `${at}: the description repeats the one at ${descriptionFirst}.`,
+      );
+    }
+
+    const withheld =
+      withheldPhrase(route.title) ?? withheldPhrase(route.description);
+    if (withheld !== undefined) {
+      problems.push(
+        `${at}: the snippet says "${withheld}" — a site names no repository, tracker or licence of ours.`,
+      );
+    }
+  }
+
+  return problems;
+}

package/src/seo/core/routes.ts

@@ -42,6 +42,20 @@ export interface RouteMeta {
    * @default undefined — the link stands on its own
    */
   note?: string;
+  /**
+   * Whether a search engine is meant to list the page.
+   *
+   * A maintenance screen — a curation queue, an import run, an admin table — is
+   * a real address a signed-in person opens, so it belongs in the table the
+   * router and the tab title read. It is not a result anybody wants: it says
+   * nothing a visitor searched for, and a chemist who lands on it has been sent
+   * to the wrong place. Such a route is left out of the sitemap and the page
+   * answers `noindex`, which is how a page is kept out of the index — never a
+   * `Disallow`, which only stops the crawl and still lets the address be listed
+   * from a link somewhere else.
+   * @default true
+   */
+  indexed?: boolean;
   /**
    * Whether the route also answers every address beneath it, so a section
    * carrying more pages than a table can hold — an entry per structure, per

package/src/seo/core/siteFiles.ts

@@ -50,10 +50,11 @@ export interface SiteFilesOptions {
  */
 export function sitemapXml(options: SiteFilesOptions): string {
   const origin = originOf(options);
-  if (options.routes.length === 0) {
+  if (options.routes.every((route) => route.indexed === false)) {
     throw new Error('a sitemap lists at least one address');
   }
   const entries = options.routes
+    .filter((route) => route.indexed !== false)
     .map(
       (route) =>
         `  <url><loc>${escapeText(`${origin}${route.path}`)}</loc></url>`,

package/src/seo/vite/prerender.ts

@@ -27,6 +27,7 @@ import { trimTrailingSlash } from '../../router/core/address.ts';
 import type { NoscriptText } from '../core/noscript.ts';
 import { noscriptIndex } from '../core/noscript.ts';
 import { pageHeadTags } from '../core/pageMeta.ts';
+import type { PageContent } from '../core/pageProse.ts';
 import type { RobotsDisallow } from '../core/robots.ts';
 import { robotsTxt } from '../core/robots.ts';
 import type { RouteMeta } from '../core/routes.ts';
@@ -91,6 +92,18 @@ export interface PrerenderOptions {
    * @default true
    */
   noscript?: boolean | NoscriptText;
+  /**
+   * What each page says for itself, above the crawl path: its own heading, its
+   * prose and the facts it would show anyway, read from the same data the app
+   * renders from.
+   *
+   * Without it every address ships the same body — the site's menu — and a
+   * search engine handed a hundred identical bodies keeps one of them. It is a
+   * function of the route rather than a field of it, so the prose stays out of
+   * the bundle the browser downloads: only the build ever calls it.
+   * @default undefined — every page carries the menu alone
+   */
+  content?: (route: RouteMeta) => PageContent | undefined;
 }
 
 /**
@@ -104,18 +117,18 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
   const { site, routes, origin, robots = [] } = options;
   assertRoutes(routes);
   const structuredData = structuredDataOf(options);
-  const crawlPath = crawlPathOf(options);
 
   let out = 'dist';
   let serve = false;
   let logger: Logger | null = null;
 
-  const page = (template: string, url: string) => {
+  const page = (template: string, route: RouteMeta) => {
     const head = fill(
       template,
       PAGE_HEAD_MARKER,
-      `${pageHeadTags({ site, routes, origin, url })}${structuredData}`,
+      `${pageHeadTags({ site, routes, origin, url: route.path })}${structuredData}`,
     );
+    const crawlPath = crawlPathOf(options, route);
     return crawlPath === '' ? head : fill(head, PAGE_BODY_MARKER, crawlPath);
   };
 
@@ -132,17 +145,16 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
     // from the home route rather than shipped with its markers showing.
     transformIndexHtml: {
       order: 'post',
-      handler: (html: string) =>
-        serve ? page(html, homeRoute(routes).path) : html,
+      handler: (html: string) => (serve ? page(html, homeRoute(routes)) : html),
     },
 
     closeBundle() {
       if (serve) return;
       const template = readFileSync(join(out, 'index.html'), 'utf8');
 
-      const write = (url: string, file: string) => {
+      const write = (route: RouteMeta, file: string) => {
         mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, page(template, url));
+        writeFileSync(file, page(template, route));
       };
 
       let root = false;
@@ -150,7 +162,7 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
         const address = trimTrailingSlash(route.path);
         if (address === '/') root = true;
         write(
-          route.path,
+          route,
           address === '/'
             ? join(out, 'index.html')
             : join(out, address.slice(1), 'index.html'),
@@ -159,7 +171,7 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
       // The file a static server hands out for the mount itself. A table naming
       // no root would otherwise leave the template vite built, and ship a site
       // whose front page carries its markers instead of a head.
-      if (!root) write(homeRoute(routes).path, join(out, 'index.html'));
+      if (!root) write(homeRoute(routes), join(out, 'index.html'));
 
       writeFileSync(
         join(out, 'sitemap.xml'),
@@ -196,9 +208,16 @@ function structuredDataOf(options: PrerenderOptions): string {
   })}`;
 }
 
-function crawlPathOf(options: PrerenderOptions): string {
+function crawlPathOf(options: PrerenderOptions, route: RouteMeta): string {
   const { site, routes, origin, noscript = true } = options;
   if (noscript === false) return '';
+  const content = options.content?.(route);
   const { routes: listed, ...prose } = noscript === true ? {} : noscript;
-  return noscriptIndex({ site, origin, ...prose, routes: listed ?? routes });
+  return noscriptIndex({
+    site,
+    origin,
+    ...prose,
+    routes: listed ?? routes,
+    content,
+  });
 }