react-cheminfo 0.4.0 → 0.4.1

package/src/seo/core/routes.ts

@@ -0,0 +1,79 @@
+/**
+ * The addresses a site answers, each with the name and the sentence it is
+ * indexed under.
+ *
+ * One table per site, read by three things: the build, which writes an HTML
+ * file per entry and the sitemap listing them; the head injector; and the
+ * running app, which retitles the tab after an in-app move. A page missing from
+ * the table is a page a search engine only ever sees as the home page.
+ */
+
+/** A page, as a crawler and a shared card see it. */
+export interface RouteMeta {
+  /** Absolute path, without a trailing slash and without a query string. */
+  path: string;
+  /** Under ~60 characters: the site name is appended to it. */
+  title: string;
+  /** One sentence, in the words someone would search for. */
+  description: string;
+}
+
+/**
+ * The route an address names.
+ * @param routes - Every address the site answers.
+ * @param path - Absolute path, without a query string.
+ * @returns Its entry, or `undefined` when the site does not know the address.
+ */
+export function routeFor(
+  routes: readonly RouteMeta[],
+  path: string,
+): RouteMeta | undefined {
+  const wanted = trimTrailingSlash(path) || '/';
+  for (const route of routes) {
+    if (trimTrailingSlash(route.path) === wanted) return route;
+  }
+  return undefined;
+}
+
+/**
+ * The page an address opens.
+ *
+ * An address the site does not know is described as the home page rather than
+ * invented on the fly, which is what the router does with it too. The query
+ * string never reaches the answer: the structure being drawn and the
+ * configuration a shared link carries are not pages of their own.
+ * @param routes - Every address the site answers.
+ * @param url - The address, query string and fragment included.
+ * @returns The route it is indexed as.
+ * @throws {Error} When the table is empty, so there is no page to fall back to.
+ */
+export function pageMetaFor(
+  routes: readonly RouteMeta[],
+  url: string,
+): RouteMeta {
+  const home = homeRoute(routes);
+  const cut = url.search(/[?#]/);
+  const path = cut === -1 ? url : url.slice(0, cut);
+  return routeFor(routes, path) ?? home;
+}
+
+/**
+ * The page an unknown address falls back to.
+ * @param routes - Every address the site answers.
+ * @returns The `/` entry, or the first one when the table names no root.
+ * @throws {Error} When the table is empty.
+ */
+export function homeRoute(routes: readonly RouteMeta[]): RouteMeta {
+  const first = routes[0];
+  if (first === undefined) throw new Error('a site answers at least one route');
+  return routeFor(routes, '/') ?? first;
+}
+
+/**
+ * Drop a trailing slash, so `/about/` and `/about` are one page.
+ * @param value - A path or an origin.
+ * @returns It, without the trailing slash `/` itself keeps.
+ */
+export function trimTrailingSlash(value: string): string {
+  return value.length > 1 && value.endsWith('/') ? value.slice(0, -1) : value;
+}

package/src/seo/core/siteFiles.ts

@@ -0,0 +1,150 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import { siteById, 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 { 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`;
+
+/** What a crawler is told about the site as a whole. */
+export interface SiteFilesOptions {
+  /** The site, named or passed. */
+  site: EcosystemSite | SiteId;
+  /** Every address it answers. */
+  routes: readonly RouteMeta[];
+  /**
+   * Origin every absolute address is built on.
+   * @default `https://<the site's host>`
+   */
+  origin?: string;
+}
+
+/**
+ * Every routed address, as the sitemap lists them.
+ * @param options - The site and its routes.
+ * @returns The `sitemap.xml` document.
+ */
+export function sitemapXml(options: SiteFilesOptions): string {
+  const origin = originOf(options);
+  const entries = options.routes
+    .map(
+      (route) =>
+        `  <url><loc>${escapeText(`${origin}${route.path}`)}</loc></url>`,
+    )
+    .join('\n');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</urlset>
+`;
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * 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.
+ * @param options - The site, and what kind of application it is.
+ * @returns The script tag, ready to put in the head.
+ */
+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>`;
+}
+
+/**
+ * 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.
+ */
+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}`,
+  );
+}

package/src/seo/vite/index.ts

@@ -0,0 +1,4 @@
+export type { OgCardOptions } from './ogCard.ts';
+export { OG_HEIGHT, OG_WIDTH, ogCardHtml } from './ogCard.ts';
+export type { PrerenderOptions } from './prerender.ts';
+export { cheminfoPrerender } from './prerender.ts';

package/src/seo/vite/ogCard.ts

@@ -0,0 +1,92 @@
+/**
+ * The 1200×630 card a link to a site unfurls into, as a page to screenshot.
+ *
+ * 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.
+ */
+
+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. */
+export const OG_WIDTH = 1200;
+
+/** The height every card is drawn at. */
+export const OG_HEIGHT = 630;
+
+/** What the card says, beyond the site's own name and mark. */
+export interface OgCardOptions {
+  /** The site, named or passed. */
+  site: EcosystemSite | SiteId;
+  /**
+   * The sentence under the name.
+   * @default the site's tagline
+   */
+  description?: string;
+}
+
+/**
+ * The card, as a standalone page.
+ *
+ * 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.
+ * @param options - Which site, and what it says.
+ * @returns A complete HTML document.
+ */
+export function ogCardHtml(options: OgCardOptions): string {
+  const site =
+    typeof options.site === 'string' ? siteById(options.site) : options.site;
+  const description = options.description ?? site.tagline;
+  const mark = renderToStaticMarkup(
+    createElement(SiteMark, { site, size: 132, colors: 'literal' }),
+  );
+  const dot = site.name.dot === true ? '<span class="dot">.</span>' : '';
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      * { box-sizing: border-box; margin: 0; }
+      body {
+        display: flex;
+        width: ${OG_WIDTH}px;
+        height: ${OG_HEIGHT}px;
+        flex-direction: column;
+        justify-content: center;
+        padding: 88px;
+        background: #ffffff;
+        color: #16202c;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+          Helvetica, Arial, sans-serif;
+        gap: 28px;
+      }
+      h1 { font-size: 76px; font-weight: 700; letter-spacing: -0.02em; }
+      .lead { color: ${site.brand}; }
+      .alt { color: ${site.brandAlt}; }
+      .dot { color: #8a96a3; }
+      p { max-width: 900px; color: #5b6875; font-size: 34px; line-height: 1.35; }
+      .rule {
+        width: 180px;
+        height: 10px;
+        border-radius: 5px;
+        background: ${site.brandAlt};
+      }
+    </style>
+  </head>
+  <body>
+    ${mark}
+    <h1><span class="lead">${escapeText(site.name.lead)}</span>${dot}<span class="alt">${escapeText(site.name.alt)}</span></h1>
+    <div class="rule"></div>
+    <p>${escapeText(description)}</p>
+  </body>
+</html>
+`;
+}

package/src/seo/vite/prerender.ts

@@ -0,0 +1,156 @@
+/**
+ * Write one real HTML file per routed address, and everything else a crawler
+ * fetches on its own.
+ *
+ * A site served by a static image has nothing to rewrite a head per request: a
+ * crawler gets whatever came off the wire. Without this every address carries
+ * the same title and a search engine folds the whole site into one result.
+ *
+ * These files are also what makes the server's catch-all fallback unnecessary.
+ * Every address the tool answers is on disk, so an address that is *not* on
+ * disk is genuinely not a page and must 404 rather than serving the tool under
+ * a name it does not have.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+import type { Logger, Plugin } from 'vite';
+
+import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
+import { injectPageMeta, insertBeforeHeadEnd } from '../core/pageMeta.ts';
+import type { RouteMeta } from '../core/routes.ts';
+import {
+  noscriptIndex,
+  robotsTxt,
+  sitemapXml,
+  structuredDataScript,
+} from '../core/siteFiles.ts';
+
+/** What the build needs to know to write the site's addresses. */
+export interface PrerenderOptions {
+  /** The site, named or passed. */
+  site: EcosystemSite | SiteId;
+  /** Every address it answers, each with its title and description. */
+  routes: readonly RouteMeta[];
+  /**
+   * Origin every absolute address is built on.
+   * @default `https://<the site's host>`
+   */
+  origin?: string;
+  /**
+   * Address prefixes `robots.txt` keeps out of the index, e.g. `/v1/`. Set to
+   * `false` to write no `robots.txt` at all, for a site that ships its own.
+   * @default []
+   */
+  robots?: false | readonly string[];
+  /**
+   * The schema.org category of the structured-data block, or `false` to write
+   * none.
+   * @default 'EducationalApplication'
+   */
+  category?: false | string;
+  /**
+   * What the tool needs to run, named in the structured-data block.
+   * @default 'Any modern browser'
+   */
+  operatingSystem?: string;
+  /**
+   * Whether the built page carries a `noscript` index of the addresses. It is
+   * the only crawl path through a site whose body is an empty root element.
+   * @default true
+   */
+  noscript?: boolean;
+}
+
+/**
+ * Prerender every routed address of a cheminfo site.
+ * @param options - The site, its routes, and what a crawler is told.
+ * @returns The Vite plugin.
+ */
+export function cheminfoPrerender(options: PrerenderOptions): Plugin {
+  const {
+    site,
+    routes,
+    origin,
+    robots = [],
+    category,
+    operatingSystem,
+    noscript = true,
+  } = options;
+  let out = 'dist';
+  let logger: Logger | null = null;
+
+  return {
+    name: 'cheminfo:prerender',
+    apply: 'build',
+
+    configResolved(config) {
+      out = resolve(config.root, config.build.outDir);
+      logger = config.logger;
+    },
+
+    transformIndexHtml: {
+      order: 'post',
+      handler(html) {
+        let page = html;
+        if (category !== false) {
+          page = insertBeforeHeadEnd(
+            page,
+            structuredDataScript({
+              site,
+              routes,
+              origin,
+              category,
+              operatingSystem,
+            }),
+          );
+        }
+        if (noscript) {
+          page = insertBeforeBodyEnd(
+            page,
+            noscriptIndex({ site, routes, origin }),
+          );
+        }
+        return page;
+      },
+    },
+
+    closeBundle() {
+      const index = readFileSync(join(out, 'index.html'), 'utf8');
+
+      for (const route of routes) {
+        const file =
+          route.path === '/'
+            ? join(out, 'index.html')
+            : join(out, route.path.slice(1), 'index.html');
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(
+          file,
+          injectPageMeta(index, { site, routes, origin, url: route.path }),
+        );
+      }
+
+      writeFileSync(
+        join(out, 'sitemap.xml'),
+        sitemapXml({ site, routes, origin }),
+      );
+      if (robots !== false) {
+        writeFileSync(
+          join(out, 'robots.txt'),
+          robotsTxt({ site, routes, origin }, robots),
+        );
+      }
+
+      logger?.info(
+        `${routes.length} pages prerendered, and listed in sitemap.xml`,
+      );
+    },
+  };
+}
+
+function insertBeforeBodyEnd(html: string, addition: string): string {
+  const body = html.lastIndexOf('</body>');
+  if (body === -1) return `${html}\n${addition}\n`;
+  return `${html.slice(0, body)}${addition}\n${html.slice(body)}`;
+}

package/src/vite.ts

@@ -0,0 +1 @@
+export * from './seo/vite/index.ts';