react-cheminfo 0.4.1 → 0.7.0

package/src/seo/core/noscript.ts

@@ -0,0 +1,195 @@
+/**
+ * A readable page for a visitor, or a crawler, with no JavaScript.
+ *
+ * The body of our sites is an empty root element, so this is the only crawl
+ * path through them that costs nothing to render — and it is honest: it says
+ * the tool needs JavaScript, and links the addresses it answers.
+ */
+
+import { siteById, siteDisplayName } from '../../ecosystem/core/lookup.ts';
+import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
+import { ECOSYSTEM_SITES, siteUrl } from '../../ecosystem/core/sites.ts';
+import { joinBasePath } from '../../router/core/basePath.ts';
+import { escapeAttribute, escapeText } from '../../share/core/escape.ts';
+
+import type { RouteMeta } from './routes.ts';
+import type { SiteFilesOptions } from './siteFiles.ts';
+import { mountPathOf, resolveSite } from './siteFiles.ts';
+
+/** How the addresses of the site's own pages are written. */
+export type NoscriptHrefs = 'absolute' | 'relative';
+
+/** A page the block links, and the pages listed under it. */
+export interface NoscriptRoute extends RouteMeta {
+  /**
+   * Pages listed under this one, as a list nested in its item — the sections of
+   * an exercise set under the set itself.
+   * @default undefined — the item carries no list
+   */
+  children?: readonly NoscriptRoute[];
+}
+
+/** Which of the family's other sites are listed, and how. */
+export interface NoscriptEcosystem {
+  /**
+   * The sites listed, in the order they are named. The site writing the block
+   * is never one of them, whether or not it is named: the list is headed *Our
+   * other tools*.
+   * @default every other site in the family, in the family's own order
+   */
+  sites?: readonly SiteId[];
+  /**
+   * Whether each host is followed by ` — ` and the site's one-line tagline.
+   * @default true
+   */
+  taglines?: boolean;
+}
+
+/** The prose of the block, where the site says more than its record does. */
+export interface NoscriptText {
+  /**
+   * The heading the block opens with.
+   * @default the site's display name
+   */
+  heading?: string;
+  /**
+   * The paragraph under it, taken as written. It is the one place a reader with
+   * no JavaScript is told what the tool is, so it may say more than the tagline
+   * — but it still has to say that the tool needs JavaScript.
+   * @default the tagline, followed by the sentence naming the requirement
+   */
+  intro?: string;
+  /**
+   * Whether the family's other sites are listed under the site's own pages, and
+   * which of them. A crawler that runs no script has no other path from one of
+   * our tools to the next, so a site that lists none leaves it with none.
+   * `true` lists every other site with its tagline; an object names the sites,
+   * or drops the taglines, or both.
+   * @default false
+   */
+  ecosystem?: boolean | NoscriptEcosystem;
+  /**
+   * How the site's own addresses are written. `'absolute'` writes them from the
+   * root of the host, under the mount the origin names. `'relative'` writes
+   * `./exercises` and `./`, which the page resolves against its own `<base>` —
+   * the only shape that works for an image whose mount is chosen at container
+   * startup, because it bakes no mount into the build at all. The `<base>` such
+   * a deployment stamps in ends with a slash, or a relative address resolves
+   * one directory too high.
+   * @default 'absolute'
+   */
+  hrefs?: NoscriptHrefs;
+  /**
+   * The pages the block links, when they are not the site's whole route table.
+   * A crawl path is a menu: a site whose table carries an entry per tutorial
+   * step lists the tutorial, not its hundred and thirty-seven steps.
+   * @default every route the site answers
+   */
+  routes?: readonly NoscriptRoute[];
+}
+
+/** What the block says, and which addresses it links. */
+export interface NoscriptOptions
+  extends Omit<SiteFilesOptions, 'routes'>, Omit<NoscriptText, 'routes'> {
+  /** The addresses it links, each with the label it is linked under. */
+  routes: readonly NoscriptRoute[];
+}
+
+/**
+ * The `noscript` block, ready to put in the body.
+ *
+ * An absolute address is written under the mount the deployment named, so a
+ * build published as one tool among several on a shared host links its own
+ * pages rather than the root of the host it shares.
+ * @param options - The site, the pages it links, and the prose that opens the
+ * block.
+ * @returns The block.
+ * @throws {Error} When the deployment named an origin that is not an absolute
+ * address.
+ */
+export function noscriptIndex(options: NoscriptOptions): string {
+  const site = resolveSite(options.site);
+  const hrefs = options.hrefs ?? 'absolute';
+  const mount = hrefs === 'absolute' ? mountPathOf(options) : '';
+  const heading = escapeText(options.heading ?? siteDisplayName(site));
+  const intro = escapeText(
+    options.intro ??
+      `${site.tagline} This tool needs JavaScript; these are the pages it offers:`,
+  );
+
+  return `<noscript>
+  <h1>${heading}</h1>
+  <p>${intro}</p>${pageList(options.routes, mount, hrefs, '  ')}${familyList(site.id, options.ecosystem)}
+</noscript>`;
+}
+
+function pageList(
+  routes: readonly NoscriptRoute[],
+  mount: string,
+  hrefs: NoscriptHrefs,
+  indent: string,
+): string {
+  // A list with no item is not a list: `<ul>` holds at least one `<li>`.
+  if (routes.length === 0) return '';
+  const items = routes
+    .map((route) => pageItem(route, mount, hrefs, `${indent}  `))
+    .join('\n');
+  return `\n${indent}<ul>\n${items}\n${indent}</ul>`;
+}
+
+function pageItem(
+  route: NoscriptRoute,
+  mount: string,
+  hrefs: NoscriptHrefs,
+  indent: string,
+): string {
+  const href = escapeAttribute(pageHref(route.path, mount, hrefs));
+  const label = escapeText(labelOf(route));
+  const note =
+    route.note === undefined || route.note.trim() === ''
+      ? ''
+      : ` — ${escapeText(route.note)}`;
+  const children = route.children ?? [];
+  const link = `<a href="${href}">${label}</a>${note}`;
+  if (children.length === 0) return `${indent}<li>${link}</li>`;
+  return `${indent}<li>${link}${pageList(children, mount, hrefs, `${indent}  `)}
+${indent}</li>`;
+}
+
+function pageHref(path: string, mount: string, hrefs: NoscriptHrefs): string {
+  if (hrefs === 'absolute') return joinBasePath(mount, path);
+  return `./${path.startsWith('/') ? path.slice(1) : path}`;
+}
+
+function labelOf(route: NoscriptRoute): string {
+  const short = route.short;
+  return short !== undefined && short.trim() !== '' ? short : route.title;
+}
+
+function familyList(
+  current: SiteId,
+  ecosystem: boolean | NoscriptEcosystem | undefined,
+): string {
+  if (ecosystem === undefined || ecosystem === false) return '';
+  const listed = ecosystem === true ? {} : ecosystem;
+  const taglines = listed.taglines ?? true;
+  const items: string[] = [];
+  for (const site of familySites(listed.sites)) {
+    if (site.id === current) continue;
+    const tagline = taglines ? ` — ${escapeText(site.tagline)}` : '';
+    items.push(
+      `    <li><a href="${escapeAttribute(siteUrl(site))}">${escapeText(site.host)}</a>${tagline}</li>`,
+    );
+  }
+  if (items.length === 0) return '';
+  return `
+  <h2>Our other tools</h2>
+  <ul>
+${items.join('\n')}
+  </ul>`;
+}
+
+function familySites(sites: readonly SiteId[] | undefined): EcosystemSite[] {
+  if (sites === undefined) return [...ECOSYSTEM_SITES];
+  return sites.map((id) => siteById(id));
+}

package/src/seo/core/pageMeta.ts

@@ -4,18 +4,23 @@
  * Googlebot renders JavaScript, but Bing, a Slack unfurl, an LMS preview and
  * every academic indexer read the HTML that came off the wire — so the title,
  * the description and the canonical of a page must already be in it. A site
- * with a server rewrites them per request; a static one writes one file per
+ * with a server writes them per request; a static one writes one file per
  * address at build time. Both call this, which is pure string work: no
  * `window`, no `node:fs`.
+ *
+ * The page it is given is the template, which declares where its head goes and
+ * carries none of its own, so this only ever writes — see `./template.ts`.
  */
 
-import { siteById, siteDisplayName } from '../../ecosystem/core/lookup.ts';
+import { siteDisplayName } from '../../ecosystem/core/lookup.ts';
 import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
 import { escapeAttribute, escapeText } from '../../share/core/escape.ts';
 
 import type { DocumentMeta } from './documentMeta.ts';
 import type { RouteMeta } from './routes.ts';
-import { pageMetaFor, trimTrailingSlash } from './routes.ts';
+import { pageMetaFor } from './routes.ts';
+import { mountPathOf, originOf, resolveSite } from './siteFiles.ts';
+import { PAGE_HEAD_MARKER, fill } from './template.ts';
 
 /** Which site is being served, and what it answers. */
 export interface PageMetaOptions {
@@ -23,11 +28,18 @@ export interface PageMetaOptions {
   site: EcosystemSite | SiteId;
   /** Every address it answers, each with its title and description. */
   routes: readonly RouteMeta[];
-  /** The address being written, query string included. */
+  /**
+   * The address being written, query string included: a path, or the absolute
+   * address an app reads off the page it is on.
+   */
   url: string;
   /**
-   * Origin every absolute address is built on. A server passes the one the
-   * request arrived on; a build leaves it out and the site's own host is used.
+   * Where the site is served, mount path included, e.g.
+   * `https://learn.cheminfo.org/surge`. A server passes the one the request
+   * arrived on; a build leaves it out and the site's own host is used. Every
+   * address written here is composed on it, so the mount is carried by the
+   * origin rather than applied a second time. It is an absolute address, or it
+   * is refused.
    * @default `https://<the site's host>`
    */
   origin?: string;
@@ -41,33 +53,44 @@ export interface PageMetaOptions {
 /**
  * Give a page the title, the description and the canonical address of the route
  * it answers, plus the card a link to it unfurls into.
- * @param html - The built page.
+ * @param html - The built template.
  * @param options - Which site, which address, and where it is served from.
- * @returns The page, with its head rewritten for that route.
+ * @returns The page, with its head written for that route.
+ * @throws {Error} When the page carries no `<!--cheminfo:head-->`, when the
+ * site answers no route, or when it names an origin that is not an absolute
+ * address.
  */
 export function injectPageMeta(html: string, options: PageMetaOptions): string {
-  const site = resolveSite(options.site);
-  const meta = pageMetaFor(options.routes, options.url);
-  const name = siteDisplayName(site);
-  const origin = trimTrailingSlash(options.origin ?? `https://${site.host}`);
+  return fill(html, PAGE_HEAD_MARKER, pageHeadTags(options));
+}
+
+/**
+ * The head a route is indexed and shared under, for a caller writing more into
+ * the same place — a structured-data block, a tracking snippet.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The tags, one per line.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export function pageHeadTags(options: PageMetaOptions): string {
+  const name = siteDisplayName(resolveSite(options.site));
+  const description = routeMetaOf(options).description;
+  const origin = originOf(options);
   const { title, canonical } = pageDocumentMeta(options);
   const image = absolute(options.image ?? '/og.png', origin);
 
-  const head = [
+  return [
+    `<title>${escapeText(title)}</title>`,
+    `<meta name="description" content="${escapeAttribute(description)}" />`,
     `<link rel="canonical" href="${escapeAttribute(canonical)}" />`,
     '<meta property="og:type" content="website" />',
     `<meta property="og:site_name" content="${escapeAttribute(name)}" />`,
     `<meta property="og:title" content="${escapeAttribute(title)}" />`,
-    `<meta property="og:description" content="${escapeAttribute(meta.description)}" />`,
+    `<meta property="og:description" content="${escapeAttribute(description)}" />`,
     `<meta property="og:url" content="${escapeAttribute(canonical)}" />`,
     `<meta property="og:image" content="${escapeAttribute(image)}" />`,
     '<meta name="twitter:card" content="summary_large_image" />',
   ].join('\n');
-
-  return insertBeforeHeadEnd(
-    replaceDescription(replaceTitle(html, title), meta.description),
-    head,
-  );
 }
 
 /**
@@ -78,50 +101,28 @@ export function injectPageMeta(html: string, options: PageMetaOptions): string {
  * click that changes the page cannot disagree with the page a crawler fetched.
  * @param options - Which site, which address, and where it is served from.
  * @returns The title, the description and the canonical of that address.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
  */
-export function pageDocumentMeta(options: PageMetaOptions): Required<DocumentMeta> {
+export function pageDocumentMeta(
+  options: PageMetaOptions,
+): Required<DocumentMeta> {
   const site = resolveSite(options.site);
-  const meta = pageMetaFor(options.routes, options.url);
-  const origin = trimTrailingSlash(options.origin ?? `https://${site.host}`);
+  const meta = routeMetaOf(options);
   return {
     title: `${meta.title} — ${siteDisplayName(site)}`,
     description: meta.description,
-    canonical: `${origin}${meta.path}`,
+    canonical: `${originOf(options)}${meta.path}`,
   };
 }
 
-/**
- * Put an addition at the end of the head, where a tracking snippet and a
- * structured-data block both belong.
- * @param html - The page.
- * @param addition - The markup to add, taken as written.
- * @returns The page, with the addition before `</head>`.
- */
-export function insertBeforeHeadEnd(html: string, addition: string): string {
-  const head = html.lastIndexOf('</head>');
-  if (head === -1) return `${html}\n${addition}\n`;
-  return `${html.slice(0, head)}${addition}\n${html.slice(head)}`;
-}
-
-function resolveSite(site: EcosystemSite | SiteId): EcosystemSite {
-  return typeof site === 'string' ? siteById(site) : site;
+// 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));
 }
 
 function absolute(target: string, origin: string): string {
   return target.startsWith('/') ? `${origin}${target}` : target;
 }
-
-function replaceTitle(html: string, title: string): string {
-  const replacement = `<title>${escapeText(title)}</title>`;
-  return html.includes('<title>')
-    ? html.replace(/<title>[\s\S]*?<\/title>/, replacement)
-    : insertBeforeHeadEnd(html, replacement);
-}
-
-function replaceDescription(html: string, description: string): string {
-  const replacement = `<meta name="description" content="${escapeAttribute(description)}" />`;
-  const existing = /<meta[^>]*name="description"[^>]*>/;
-  return existing.test(html)
-    ? html.replace(existing, replacement)
-    : insertBeforeHeadEnd(html, replacement);
-}

package/src/seo/core/robots.ts

@@ -0,0 +1,114 @@
+/**
+ * The crawl policy.
+ *
+ * Our tools are meant to be found, so only the endpoints are kept out of the
+ * index — an API prefix and its documentation are not pages — and each one may
+ * say in a comment why, because a policy nobody can read is a policy nobody
+ * maintains.
+ *
+ * Every line of this file is a directive, so nothing an author writes may
+ * become one they did not: a path is a single line that says something, and
+ * carries no fragment, or it is refused; and a comment is folded onto the one
+ * line it is written as.
+ */
+
+import { joinBasePath } from '../../router/core/basePath.ts';
+
+import type { SiteFilesOptions } from './siteFiles.ts';
+import { mountPathOf, originOf } from './siteFiles.ts';
+
+/** One address kept out of the index, and why. */
+export interface RobotsDisallow {
+  /**
+   * The address prefix, from the site's own root, e.g. `/v1/`. It is a path,
+   * on one line, saying something, carrying no `#`, and padded by nothing: a
+   * blank one would read as `Disallow: /` and keep the whole site out of the
+   * index — RFC 9309 eats the trailing whitespace of a line, so `"   "` is read
+   * as nothing at all — one carrying a line break would write whatever follows
+   * it as a directive of its own, everything from a `#` onwards is read as a
+   * comment, which truncates the path silently, and a padded one is not the
+   * address it looks like: `" /v1/"` does not start at the site root, so it is
+   * written `Disallow: / /v1/` and matches no address at all, leaving the
+   * endpoint crawled by the very line meant to keep it out.
+   */
+  path: string;
+  /**
+   * One sentence written as a `#` line above the directive. The `#` is added
+   * when it is not already there, every run of whitespace is folded to a single
+   * space so the sentence stays on its own line, and a blank one is written as
+   * no line at all.
+   * @default undefined — the directive is written on its own
+   */
+  comment?: string;
+}
+
+const NEWLINE = /[\n\r]/;
+
+const WHITESPACE = /\s+/g;
+
+/**
+ * The crawl policy of the address the site is served at.
+ *
+ * Every path is written under the mount, so a build published as one tool among
+ * several on a shared host allows what it actually answers rather than claiming
+ * the whole host. The sitemap is named only because this module also writes it:
+ * a `Sitemap:` line pointing at a 404 is reported as an error on every fetch.
+ * @param options - The site, its routes, and where it is served.
+ * @param disallow - Addresses to keep out of the index, each optionally with
+ * the sentence saying why.
+ * @returns The `robots.txt` document.
+ * @throws {Error} When a disallowed address is blank, spans more than one line,
+ * carries a `#` or is padded with whitespace, or when the deployment named an
+ * origin that is not an absolute address.
+ */
+export function robotsTxt(
+  options: SiteFilesOptions,
+  disallow: ReadonlyArray<string | RobotsDisallow> = [],
+): string {
+  const mount = mountPathOf(options);
+  const lines = ['User-agent: *', `Allow: ${joinBasePath(mount, '/')}`];
+
+  for (const entry of disallow) {
+    const rule = typeof entry === 'string' ? { path: entry } : entry;
+    const comment =
+      rule.comment === undefined ? undefined : commentLine(rule.comment);
+    if (comment !== undefined) lines.push(comment);
+    lines.push(`Disallow: ${joinBasePath(mount, disallowPath(rule.path))}`);
+  }
+
+  lines.push('', `Sitemap: ${originOf(options)}/sitemap.xml`, '');
+  return lines.join('\n');
+}
+
+function disallowPath(path: string): string {
+  if (path === '') {
+    throw new Error('a disallowed address is a path, never the empty string');
+  }
+  if (path.trim() === '') {
+    throw new Error(
+      `a disallowed address is a path, never blank: ${JSON.stringify(path)}`,
+    );
+  }
+  if (NEWLINE.test(path)) {
+    throw new Error(
+      `a disallowed address is written on one line: ${JSON.stringify(path)}`,
+    );
+  }
+  if (path.includes('#')) {
+    throw new Error(
+      `a disallowed address carries no fragment: ${JSON.stringify(path)}`,
+    );
+  }
+  if (path !== path.trim()) {
+    throw new Error(
+      `a disallowed address is written without padding: ${JSON.stringify(path)}`,
+    );
+  }
+  return path;
+}
+
+function commentLine(comment: string): string | undefined {
+  const text = comment.replaceAll(WHITESPACE, ' ').trim();
+  if (text === '') return undefined;
+  return text.startsWith('#') ? text : `# ${text}`;
+}