react-cheminfo 0.4.0 → 0.6.0

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/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,102 @@
+/**
+ * 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.
+ *
+ * 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 { siteById } from '../../ecosystem/core/lookup.ts';
+import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
+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.
+ *
+ * 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 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' }),
+  );
+  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,203 @@
+/**
+ * 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.
+ *
+ * The build's `index.html` is the template: it declares where its head and its
+ * crawl path go with `<!--cheminfo:head-->` and `<!--cheminfo:body-->`, and
+ * every file written here is filled from it. The dev server is filled the same
+ * way, from the home route, so what a developer opens is what the build ships.
+ *
+ * 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 type { NoscriptText } from '../core/noscript.ts';
+import { noscriptIndex } from '../core/noscript.ts';
+import { pageHeadTags } from '../core/pageMeta.ts';
+import type { RobotsDisallow } from '../core/robots.ts';
+import { robotsTxt } from '../core/robots.ts';
+import type { RouteMeta } from '../core/routes.ts';
+import { assertRoutes, homeRoute, trimTrailingSlash } from '../core/routes.ts';
+import { sitemapXml } from '../core/siteFiles.ts';
+import { structuredDataScript } from '../core/structuredData.ts';
+import { PAGE_BODY_MARKER, PAGE_HEAD_MARKER, fill } from '../core/template.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[];
+  /**
+   * Where the site is served, mount path included. Every absolute address is
+   * built on it, and `robots.txt` and the `noscript` index write their paths
+   * under its mount. The files on disk are laid out from the build's own root
+   * either way: it is the server that puts them under the mount.
+   * @default `https://<the site's host>`
+   */
+  origin?: string;
+  /**
+   * Addresses `robots.txt` keeps out of the index, e.g. `/v1/`, each optionally
+   * with the sentence saying why. Set to `false` to write no `robots.txt` at
+   * all, for a site that ships its own.
+   * @default []
+   */
+  robots?: false | ReadonlyArray<string | RobotsDisallow>;
+  /**
+   * 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;
+  /**
+   * What the tool does, in the structured-data block.
+   * @default the site's tagline
+   */
+  description?: string;
+  /**
+   * What a browser has to offer for the tool to run.
+   * @default 'Requires JavaScript'
+   */
+  browserRequirements?: string;
+  /**
+   * The currency the zero price is quoted in.
+   * @default 'EUR'
+   */
+  currency?: string;
+  /**
+   * Whether the built page carries a `noscript` index of the addresses, what it
+   * says, which pages it lists and how it writes their addresses. It is the
+   * only crawl path through a site whose body is an empty root element, so
+   * `false` leaves one without any — and is also what lets a template ship no
+   * `<!--cheminfo:body-->` at all.
+   * @default true
+   */
+  noscript?: boolean | NoscriptText;
+}
+
+/**
+ * Prerender every routed address of a cheminfo site.
+ * @param options - The site, its routes, and what a crawler is told.
+ * @returns The Vite plugin.
+ * @throws {Error} When the route table names an address twice or names one that
+ * is not a path, or when the origin is not an absolute address.
+ */
+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 head = fill(
+      template,
+      PAGE_HEAD_MARKER,
+      `${pageHeadTags({ site, routes, origin, url })}${structuredData}`,
+    );
+    return crawlPath === '' ? head : fill(head, PAGE_BODY_MARKER, crawlPath);
+  };
+
+  return {
+    name: 'cheminfo:prerender',
+
+    configResolved(config) {
+      serve = config.command === 'serve';
+      out = resolve(config.root, config.build.outDir);
+      logger = config.logger;
+    },
+
+    // A dev run has no build to prerender, so the page vite serves is filled
+    // from the home route rather than shipped with its markers showing.
+    transformIndexHtml: {
+      order: 'post',
+      handler: (html: string) =>
+        serve ? page(html, homeRoute(routes).path) : html,
+    },
+
+    closeBundle() {
+      if (serve) return;
+      const template = readFileSync(join(out, 'index.html'), 'utf8');
+
+      const write = (url: string, file: string) => {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, page(template, url));
+      };
+
+      let root = false;
+      for (const route of routes) {
+        const address = trimTrailingSlash(route.path);
+        if (address === '/') root = true;
+        write(
+          route.path,
+          address === '/'
+            ? join(out, 'index.html')
+            : join(out, address.slice(1), 'index.html'),
+        );
+      }
+      // 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'));
+
+      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 structuredDataOf(options: PrerenderOptions): string {
+  const { category, ...rest } = options;
+  if (category === false) return '';
+  const { site, routes, origin } = rest;
+  const { operatingSystem, description, browserRequirements, currency } = rest;
+  return `\n${structuredDataScript({
+    site,
+    routes,
+    origin,
+    category,
+    operatingSystem,
+    description,
+    browserRequirements,
+    currency,
+  })}`;
+}
+
+function crawlPathOf(options: PrerenderOptions): string {
+  const { site, routes, origin, noscript = true } = options;
+  if (noscript === false) return '';
+  const { routes: listed, ...prose } = noscript === true ? {} : noscript;
+  return noscriptIndex({ site, origin, ...prose, routes: listed ?? routes });
+}

package/src/vite.ts

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