react-cheminfo 0.4.1 → 0.6.0

package/src/seo/core/siteFiles.ts

@@ -1,21 +1,26 @@
 /**
- * The files and blocks a crawler reads besides the head: the sitemap, the
- * robots policy, the structured-data block and the list of addresses a visitor
- * without JavaScript can still follow.
+ * The sitemap, and what every other file a crawler fetches on its own is
+ * derived from: which site is being written, where it is served, and the path
+ * it is mounted at.
  *
- * All four are derived from the site's own record and its route table, so a
- * page added to the table is added to every one of them at once.
+ * A deployment names where it serves the site in full — origin and mount path
+ * in one value — because the origin is what a canonical link and a sitemap
+ * entry need. The mount is read back out of it here, so the addresses these
+ * files hand out start where the site actually answers.
  */
 
-import { siteById, siteDisplayName } from '../../ecosystem/core/lookup.ts';
+import { siteById } from '../../ecosystem/core/lookup.ts';
 import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
-import { escapeAttribute, escapeText } from '../../share/core/escape.ts';
+import { basePathOf } from '../../router/core/basePath.ts';
+import { escapeText } from '../../share/core/escape.ts';
 
 import type { RouteMeta } from './routes.ts';
 import { trimTrailingSlash } from './routes.ts';
 
-/** The sequence that must not appear raw inside a script element. */
-const SCRIPT_SAFE_LESS_THAN = String.raw`\u003c`;
+// A crawler fetches what it is given over HTTP, so an origin is written in one
+// of the two schemes it speaks. Parsing alone does not say that: `localhost:3000`
+// parses, with `localhost:` as its scheme and `3000` as its path.
+const HTTP_ORIGIN = /^https?:\/\//i;
 
 /** What a crawler is told about the site as a whole. */
 export interface SiteFilesOptions {
@@ -24,7 +29,9 @@ export interface SiteFilesOptions {
   /** Every address it answers. */
   routes: readonly RouteMeta[];
   /**
-   * Origin every absolute address is built on.
+   * Where the site is served, mount path included, e.g.
+   * `https://learn.cheminfo.org/surge`. Every absolute address is built on it,
+   * and every path one of these files writes starts at its mount.
    * @default `https://<the site's host>`
    */
   origin?: string;
@@ -32,11 +39,20 @@ export interface SiteFilesOptions {
 
 /**
  * Every routed address, as the sitemap lists them.
+ *
+ * A sitemap names at least one address: `<url>` is required by the sitemaps.org
+ * schema, and `robots.txt` advertises the file, so an empty one is reported as
+ * an error on every fetch rather than read as a site with nothing to index.
  * @param options - The site and its routes.
  * @returns The `sitemap.xml` document.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
  */
 export function sitemapXml(options: SiteFilesOptions): string {
   const origin = originOf(options);
+  if (options.routes.length === 0) {
+    throw new Error('a sitemap lists at least one address');
+  }
   const entries = options.routes
     .map(
       (route) =>
@@ -51,100 +67,46 @@ ${entries}
 }
 
 /**
- * The crawl policy.
- *
- * Our tools are meant to be found, so only the endpoints are disallowed — an
- * API prefix and its documentation are not pages. 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 and its routes.
- * @param disallow - Address prefixes to keep out of the index.
- * @returns The `robots.txt` document.
+ * The site these files are being written for.
+ * @param site - The site, named or passed.
+ * @returns Its record.
  */
-export function robotsTxt(
-  options: SiteFilesOptions,
-  disallow: readonly string[] = [],
-): string {
-  const lines = ['User-agent: *', 'Allow: /'];
-  for (const path of disallow) lines.push(`Disallow: ${path}`);
-  lines.push('', `Sitemap: ${originOf(options)}/sitemap.xml`, '');
-  return lines.join('\n');
-}
-
-/** What the structured-data block says the tool is. */
-export interface StructuredDataOptions extends SiteFilesOptions {
-  /**
-   * The schema.org application category.
-   * @default 'EducationalApplication'
-   */
-  category?: string;
-  /**
-   * What the tool needs to run.
-   * @default 'Any modern browser'
-   */
-  operatingSystem?: string;
+export function resolveSite(site: EcosystemSite | SiteId): EcosystemSite {
+  return typeof site === 'string' ? siteById(site) : site;
 }
 
 /**
- * One `application/ld+json` block describing the tool.
+ * Where the site is served, as an absolute address without a trailing slash.
  *
- * It is the same on every page of a site — what varies per page is the head —
- * so it is written into the built page once rather than per route.
- * @param options - The site, and what kind of application it is.
- * @returns The script tag, ready to put in the head.
+ * It is an absolute `http` or `https` address or it is refused: a canonical
+ * link, an `og:url` and a sitemap entry are addresses a crawler resolves on its
+ * own, and one written from an origin missing its scheme is resolved against
+ * whatever directory the page was fetched from — pointing every page of the
+ * site at a sibling of itself. A dev or staging origin written `localhost:3000`
+ * is refused for the same reason: it parses, but as a path under a `localhost:`
+ * scheme, so the mount read back off it would be `/3000`.
+ * @param options - The site and where it is served.
+ * @returns The origin, mount path included when the deployment named one.
+ * @throws {Error} When the deployment named something that is not an absolute
+ * `http` or `https` address.
  */
-export function structuredDataScript(options: StructuredDataOptions): string {
-  const site = resolveSite(options.site);
-  const data = {
-    '@context': 'https://schema.org',
-    '@type': 'WebApplication',
-    name: siteDisplayName(site),
-    url: `${originOf(options)}/`,
-    description: site.tagline,
-    applicationCategory: options.category ?? 'EducationalApplication',
-    operatingSystem: options.operatingSystem ?? 'Any modern browser',
-    offers: { '@type': 'Offer', price: '0', priceCurrency: 'EUR' },
-    publisher: { '@type': 'Organization', name: 'cheminfo' },
-  };
-  const json = JSON.stringify(data, null, 2).replaceAll(
-    '<',
-    SCRIPT_SAFE_LESS_THAN,
-  );
-  return `<script type="application/ld+json">\n${json}\n</script>`;
+export function originOf(options: SiteFilesOptions): string {
+  const origin = options.origin ?? `https://${resolveSite(options.site).host}`;
+  if (!HTTP_ORIGIN.test(origin) || !URL.canParse(origin)) {
+    throw new Error(
+      `an origin is an absolute address, e.g. https://surge.cheminfo.org: ${JSON.stringify(origin)}`,
+    );
+  }
+  return trimTrailingSlash(origin);
 }
 
 /**
- * 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 every address it answers.
- * @param options - The site and its routes.
- * @returns The `noscript` block, ready to put in the body.
+ * The path the deployment is mounted at, read off the address it named.
+ * @param options - The site and where it is served.
+ * @returns `''` for a site owning its host, `/surge` for one mounted under it.
+ * @throws {Error} When the deployment named something that is not an absolute
+ * address, so there is no path to read off it.
  */
-export function noscriptIndex(options: SiteFilesOptions): string {
-  const site = resolveSite(options.site);
-  const items = options.routes
-    .map(
-      (route) =>
-        `    <li><a href="${escapeAttribute(route.path)}">${escapeText(route.title)}</a></li>`,
-    )
-    .join('\n');
-  return `<noscript>
-  <h1>${escapeText(siteDisplayName(site))}</h1>
-  <p>${escapeText(site.tagline)} This tool needs JavaScript; these are the pages it offers:</p>
-  <ul>
-${items}
-  </ul>
-</noscript>`;
-}
-
-function resolveSite(site: EcosystemSite | SiteId): EcosystemSite {
-  return typeof site === 'string' ? siteById(site) : site;
-}
-
-function originOf(options: SiteFilesOptions): string {
-  return trimTrailingSlash(
-    options.origin ?? `https://${resolveSite(options.site).host}`,
-  );
+export function mountPathOf(options: SiteFilesOptions): string {
+  return basePathOf(originOf(options));
 }

package/src/seo/core/startDocumentMeta.ts

@@ -0,0 +1,77 @@
+/**
+ * Keep the tab and the canonical link in step with the page on screen.
+ *
+ * The server, or the build that wrote one file per address, already titled the
+ * page it handed out; this is what a move inside the app changes, and what a
+ * crawler that renders the page reads afterwards. Every site did the same three
+ * things around it — read the address it is on, look it up in its route table,
+ * write the head — so all three live here, and a site says only where its
+ * address is read and how a change to it is noticed.
+ */
+
+import { writeDocumentMeta } from './documentMeta.ts';
+import type { PageMetaOptions } from './pageMeta.ts';
+import { pageDocumentMeta } from './pageMeta.ts';
+
+/** Where a site's address is read, and how a change to it is noticed. */
+export interface StartDocumentMetaOptions extends Omit<
+  PageMetaOptions,
+  'url' | 'image'
+> {
+  /**
+   * The address on screen, query string included: a path, or the absolute
+   * address read off the page. It is read again on every write, so a `follow`
+   * that tracks what it reads — a signals `effect` — notices the next page.
+   */
+  url: () => string;
+  /**
+   * How a change of page is noticed: `effect` from `@preact/signals-react`
+   * follows whichever signals `url` reads and hands back the function that
+   * stops it. Left out, the head is written once, which is what a site calling
+   * this from its own `popstate` handler wants.
+   * @default undefined — the head is written once
+   */
+  follow?: (write: () => void) => () => void;
+}
+
+/**
+ * Write the head of the page on screen, and keep it in step as the page
+ * changes.
+ *
+ * Nothing happens where there is no document — a prerender script, a unit test
+ * of the route table — so this is safe to call from a module either of them
+ * imports.
+ * @param options - The site, its routes, where its address is read and how a
+ * change to it is noticed.
+ * @returns The function that stops following, which does nothing when nothing
+ * was followed.
+ * @throws {Error} When the site answers no route, or names an origin that is
+ * not an absolute address.
+ */
+export function startDocumentMeta(
+  options: StartDocumentMetaOptions,
+): () => void {
+  if (typeof document === 'undefined') return stopNothing;
+
+  const write = (): void => {
+    writeDocumentMeta(
+      pageDocumentMeta({
+        site: options.site,
+        routes: options.routes,
+        url: options.url(),
+        origin: options.origin,
+      }),
+    );
+  };
+
+  return (options.follow ?? writeOnce)(write);
+}
+
+function writeOnce(write: () => void): () => void {
+  write();
+  return stopNothing;
+}
+
+function stopNothing(): void {
+  // Nothing was followed, so there is nothing to stop.
+}

package/src/seo/core/structuredData.ts

@@ -0,0 +1,80 @@
+/**
+ * One `application/ld+json` block describing the tool.
+ *
+ * It is the same on every page of a site — what varies per page is the head —
+ * so it is written into the built page once rather than per route.
+ */
+
+import { siteDisplayName } from '../../ecosystem/core/lookup.ts';
+
+import type { SiteFilesOptions } from './siteFiles.ts';
+import { originOf, resolveSite } from './siteFiles.ts';
+
+/** The sequence that must not appear raw inside a script element. */
+const SCRIPT_SAFE_LESS_THAN = String.raw`\u003c`;
+
+/** What the structured-data block says the tool is. */
+export interface StructuredDataOptions extends SiteFilesOptions {
+  /**
+   * The schema.org application category.
+   * @default 'EducationalApplication'
+   */
+  category?: string;
+  /**
+   * What the tool needs to run.
+   * @default 'Any modern browser'
+   */
+  operatingSystem?: string;
+  /**
+   * What the tool does, in the words a search result is read in. A site whose
+   * indexed sentence says more than the line its tile in the family menu
+   * carries writes it here.
+   * @default the site's tagline
+   */
+  description?: string;
+  /**
+   * What a browser has to offer for the tool to run. Ours run in the page.
+   * @default 'Requires JavaScript'
+   */
+  browserRequirements?: string;
+  /**
+   * The currency the price is quoted in. The price is zero either way, but the
+   * pair has to agree with the audience the site is read by.
+   * @default 'EUR'
+   */
+  currency?: string;
+}
+
+/**
+ * The structured-data block, ready to put in the head.
+ *
+ * It always says the tool is free: the price is zero, and a block that leaves
+ * that implicit is one a rich result declines to show.
+ * @param options - The site, and what kind of application it is.
+ * @returns The script tag.
+ */
+export function structuredDataScript(options: StructuredDataOptions): string {
+  const site = resolveSite(options.site);
+  const data = {
+    '@context': 'https://schema.org',
+    '@type': 'WebApplication',
+    name: siteDisplayName(site),
+    url: `${originOf(options)}/`,
+    description: options.description ?? site.tagline,
+    applicationCategory: options.category ?? 'EducationalApplication',
+    operatingSystem: options.operatingSystem ?? 'Any modern browser',
+    browserRequirements: options.browserRequirements ?? 'Requires JavaScript',
+    offers: {
+      '@type': 'Offer',
+      price: '0',
+      priceCurrency: options.currency ?? 'EUR',
+    },
+    isAccessibleForFree: true,
+    publisher: { '@type': 'Organization', name: 'cheminfo' },
+  };
+  const json = JSON.stringify(data, null, 2).replaceAll(
+    '<',
+    SCRIPT_SAFE_LESS_THAN,
+  );
+  return `<script type="application/ld+json">\n${json}\n</script>`;
+}

package/src/seo/core/template.ts

@@ -0,0 +1,54 @@
+/**
+ * Where a built page lets its head and its body be written.
+ *
+ * Every address of a site needs its own title, description, canonical and card,
+ * and a static build ships one `index.html`. Rather than look for the tags a
+ * page already carries and operate on them, the template says where they go:
+ * two comments, replaced by what the build or the server writes for the address
+ * being answered.
+ *
+ * ```html
+ * <head>
+ *   <meta charset="utf-8" />
+ *   <link rel="icon" href="%BASE_URL%favicon.svg" />
+ *   <!--cheminfo:head-->
+ * </head>
+ * <body>
+ *   <div id="root"></div>
+ *   <!--cheminfo:body-->
+ * </body>
+ * ```
+ *
+ * The template carries no title and no description of its own, so nothing can
+ * be duplicated and nothing has to be taken back out. Nothing is parsed and
+ * nothing is searched for but the marker, so what the rest of the page holds — a
+ * byte order mark, an implicit head, a `</head>` its prose displays or a script
+ * quotes, an unterminated comment — cannot reach the result.
+ */
+
+/** Where the head a crawler reads is written. */
+export const PAGE_HEAD_MARKER = '<!--cheminfo:head-->';
+
+/** Where the crawl path a visitor with no JavaScript reads is written. */
+export const PAGE_BODY_MARKER = '<!--cheminfo:body-->';
+
+/**
+ * Write content in the place the template kept for it.
+ *
+ * The marker is consumed, so a page is always filled from the template and
+ * never from a filled page: applying this twice throws rather than writing a
+ * second head, which is why idempotence is not something the caller has to
+ * defend.
+ * @param html - The template.
+ * @param marker - {@link PAGE_HEAD_MARKER} or {@link PAGE_BODY_MARKER}.
+ * @param content - The markup to write, taken as written: no `$&`, `$1` or
+ * `$<name>` is expanded.
+ * @returns The page.
+ * @throws {Error} When the template carries no such marker, rather than
+ * silently shipping a page with no head.
+ */
+export function fill(html: string, marker: string, content: string): string {
+  const at = html.indexOf(marker);
+  if (at === -1) throw new Error(`the page carries no ${marker}`);
+  return html.slice(0, at) + content + html.slice(at + marker.length);
+}

package/src/seo/vite/ogCard.ts

@@ -4,14 +4,14 @@
  * The card is the site's own mark, its two colours and its name, all read from
  * its record — so it is generated rather than hand-drawn. A mark redrawn in the
  * card is a mark that drifts from the one the site shows.
+ *
+ * React is reached for only when a card is actually drawn, and never at module
+ * load: this module sits in the same entry point as the prerender plugin, which
+ * a site must be able to import with none of the optional peers installed.
  */
 
-import { createElement } from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
-
 import { siteById } from '../../ecosystem/core/lookup.ts';
 import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
-import { SiteMark } from '../../ecosystem/ui/marks.tsx';
 import { escapeText } from '../../share/core/escape.ts';
 
 /** The width every card is drawn at. */
@@ -37,13 +37,23 @@ export interface OgCardOptions {
  * Screenshot it at {@link OG_WIDTH} × {@link OG_HEIGHT} — a headless browser is
  * the only thing here that can rasterise it, and every site already has one for
  * its end-to-end tests.
+ *
+ * Drawing the mark is the one thing here that needs React, so React is loaded
+ * on the call rather than by the module. The card is drawn by a build script
+ * that already awaits a browser, so the await costs it nothing.
  * @param options - Which site, and what it says.
  * @returns A complete HTML document.
  */
-export function ogCardHtml(options: OgCardOptions): string {
+export async function ogCardHtml(options: OgCardOptions): Promise<string> {
   const site =
     typeof options.site === 'string' ? siteById(options.site) : options.site;
   const description = options.description ?? site.tagline;
+  const [{ createElement }, { renderToStaticMarkup }, { SiteMark }] =
+    await Promise.all([
+      import('react'),
+      import('react-dom/server'),
+      import('../../ecosystem/ui/marks.tsx'),
+    ]);
   const mark = renderToStaticMarkup(
     createElement(SiteMark, { site, size: 132, colors: 'literal' }),
   );