react-cheminfo 0.64.1 → 0.65.0

package/src/router/core/tabRouterTypes.ts

@@ -0,0 +1,158 @@
+import type { Language } from '../../i18n/core/languages.ts';
+
+/** A tab whose address carries more than the tab's own name. */
+export interface TabDefinition<Tab extends string = string> {
+  /** Identifier of the tab, as the state and the components name it. */
+  id: Tab;
+  /**
+   * The address of the tab, from the site's own root. The home tab is always
+   * written as `/`, whatever it declares here, so the site has one address for
+   * it instead of two holding the same thing.
+   * @default `/${id}`
+   */
+  path?: string;
+  /**
+   * Whether the tab addresses one of its items in a second path segment — a
+   * tutorial step, an exercise, an element — so a lecturer can hand out a deep
+   * link and a crawler indexes each item as a page of its own.
+   * @default false
+   */
+  takesId?: boolean;
+}
+
+/** How the addresses of a site's tabs are read and written. */
+export interface TabRouterOptions<Tab extends string> {
+  /** Every tab of the site, named on its own or described in full. */
+  tabs: ReadonlyArray<Tab | TabDefinition<Tab>>;
+  /**
+   * The tab living at the root, and the one an address the site does not know
+   * opens — a link written before a rename still lands somewhere.
+   */
+  home: Tab;
+  /**
+   * Whether the address is the path or the fragment. A public tool must use
+   * `'path'`: a `#` is dropped by half the tools that pass links around, the
+   * server never sees it, and a crawler indexes the whole site as one page.
+   * `'hash'` exists only so a site already routing that way can adopt this
+   * router before it moves.
+   * @default 'path'
+   */
+  mode?: 'path' | 'hash';
+  /**
+   * The path the site is served under: nothing on a host of its own, `/surge`
+   * as one tool among several on a shared one.
+   * @default ''
+   */
+  basePath?: string;
+  /**
+   * Read a `+` in a value as the character it is rather than as a space.
+   * Without it a shared SMILES breaks.
+   * @default true
+   */
+  literalPlus?: boolean;
+  /**
+   * Write a parameter carrying nothing back as the bare key, so a hand-typed
+   * `?embed` survives the round trip.
+   * @default false
+   */
+  keepEmptyValues?: boolean;
+  /**
+   * Also read an address whose page is named by an old `#/tab/item` fragment,
+   * so links handed out before the site routed by path keep working.
+   * @default false
+   */
+  adoptLegacyHash?: boolean;
+  /**
+   * The languages the site is written in, the default one included. Given,
+   * every route carries its `language`: a prefix between the mount and the
+   * tab — `/fr/tutorial` — with English written bare, so every link handed out
+   * before the site was translated still opens the page it names. A `?lang=` a
+   * sibling site handed the language over in is read when the prefix names
+   * none, and dropped from the parameters whenever it names a language of the
+   * site, since the route then says it once.
+   * @default undefined — the site speaks one language and its routes carry none
+   */
+  languages?: readonly Language[];
+}
+
+/** Where the app is: which tab, what it has open, and how it is set up. */
+export interface TabRoute<Tab extends string = string> {
+  /** The tab the address opens. */
+  tab: Tab;
+  /** The item its second segment names, `null` on a tab that takes none. */
+  id: string | null;
+  /** Decoded query parameters, the tool's own and the share configuration's. */
+  params: Record<string, string>;
+  /**
+   * The language the page is read in, present only on a router given
+   * `languages`: the prefix of the address, else the `?lang=` it carries, else
+   * the default language.
+   * @default undefined
+   */
+  language?: Language;
+}
+
+/** A route as a caller writes it, the parts it does not carry left out. */
+export interface TabRouteInput<Tab extends string = string> {
+  /** The tab to open; one the router does not know falls back to the home tab. */
+  tab: Tab;
+  /**
+   * The item the tab has open, ignored by a tab that addresses none.
+   * @default null
+   */
+  id?: string | null;
+  /**
+   * Query parameters to carry; an empty, `undefined` or `null` value is left out.
+   * @default {}
+   */
+  params?: Record<string, string | undefined | null>;
+  /**
+   * The language to write the address in, ignored by a router given no
+   * `languages`; one the site does not speak is written as the default.
+   * `writeRoute` keeps the language on screen when the route names none.
+   * @default the default language, written with no prefix
+   */
+  language?: Language;
+}
+
+/** The string ↔ route mapping of a site. */
+export interface TabRouter<Tab extends string = string> {
+  /** Whether the route lives in the path or in the fragment. */
+  mode: 'path' | 'hash';
+  /**
+   * The route an address denotes. An unknown tab, a trailing slash, an empty
+   * address and an escape that does not decode all resolve to something
+   * sensible rather than throwing.
+   */
+  parse: (address: string) => TabRoute<Tab>;
+  /** The address a route is reachable at, mount path and query included. */
+  format: (route: TabRouteInput<Tab>) => string;
+  /** Whether a string read out of an address names one of the site's tabs. */
+  isTab: (value: string) => value is Tab;
+  /**
+   * The address to put in the bar in place of a link written before the site
+   * routed by path: the page it names as this router writes it, with the query
+   * string kept as it was. `null` when the address is no such link, or when the
+   * router does not adopt them.
+   */
+  legacyAddress: (address: string) => string | null;
+  /**
+   * The address to put in the bar in place of one carrying a `?lang=` the site
+   * speaks: the language moved into the path — unless the path already names
+   * one, which wins — and every other part of the address kept. `null` when
+   * there is nothing to adopt, on a hash router, or on a router given no
+   * `languages`.
+   * @default undefined — a router built by hand adopts nothing
+   */
+  languageAddress?: (address: string) => string | null;
+  /**
+   * The path the site is served under, as the router normalised it.
+   * @default ''
+   */
+  basePath?: string;
+  /**
+   * The languages the router writes, as it was given them.
+   * @default undefined — the router writes no language
+   */
+  languages?: readonly Language[];
+}

package/src/seo/core/fitDescription.ts

@@ -0,0 +1,74 @@
+import {
+  DESCRIPTION_MAX,
+  DESCRIPTION_MIN,
+  DESCRIPTION_TARGET,
+} from './limits.ts';
+import { plainDescription, plainProse } from './plainDescription.ts';
+
+/** The window {@link fitDescription} grows a description into. */
+export interface FitDescriptionOptions {
+  /**
+   * The length growing stops at: a description past it keeps what it has.
+   * @default 132
+   */
+  target?: number;
+  /**
+   * The shortest description whole sentences of the base may stop at.
+   * @default 110
+   */
+  minLength?: number;
+  /**
+   * The longest description, a clause included: one that would run past it is
+   * not added.
+   * @default 160
+   */
+  maxLength?: number;
+}
+
+/**
+ * The sentence a page is indexed under, cut from its own prose and grown, when
+ * that prose is short, with what kind of page it is.
+ *
+ * The base is fitted first, as `plainDescription` fits it — markup resolved,
+ * whole sentences kept, a dot inside `C(=O)O` ending none. Each entry of
+ * `extras` is then one choice, written longest first: at most one of its
+ * clauses is added, the first that still fits, and growing stops once the text
+ * reaches `target`. So a page whose own prose fills a result keeps it, and only
+ * a short one is told it is "exercise 3 of 12".
+ *
+ * Nothing is refused here: a description still outside the window is what
+ * `routeProblems` reports, in the test every site asserts empty.
+ * @param base - The page's own prose, markup and all.
+ * @param extras - Clauses to grow it with, most worth reading first, each
+ * entry its alternatives from longest to shortest.
+ * @param options - The window the description is grown into.
+ * @returns The description.
+ */
+export function fitDescription(
+  base: string,
+  extras: ReadonlyArray<readonly string[]> = [],
+  options: FitDescriptionOptions = {},
+): string {
+  const {
+    target = DESCRIPTION_TARGET,
+    minLength = DESCRIPTION_MIN,
+    maxLength = DESCRIPTION_MAX,
+  } = options;
+  let text = plainDescription(base, { minLength, maxLength });
+  // Prose already cut mid-sentence is not grown: a clause after an ellipsis
+  // reads as two snippets.
+  if (text.endsWith('…')) return text;
+  for (const choice of extras) {
+    if (text.length >= target) break;
+    for (const clause of choice) {
+      const words = plainProse(clause);
+      if (words === '') continue;
+      const grown = text === '' ? words : `${text} ${words}`;
+      if (grown.length <= maxLength) {
+        text = grown;
+        break;
+      }
+    }
+  }
+  return text;
+}

package/src/seo/core/index.ts

@@ -1,6 +1,14 @@
 export type { AlternateOptions } from './alternates.ts';
 export { alternateLinkTags } from './alternates.ts';
 export type { DocumentMeta } from './documentMeta.ts';
+export type { FitDescriptionOptions } from './fitDescription.ts';
+export { fitDescription } from './fitDescription.ts';
+export {
+  DESCRIPTION_MAX,
+  DESCRIPTION_MIN,
+  DESCRIPTION_TARGET,
+  TITLE_LIMIT,
+} from './limits.ts';
 export { writeDocumentMeta } from './documentMeta.ts';
 export type {
   NoscriptEcosystem,
@@ -24,6 +32,13 @@ export { plainDescription, plainProse } from './plainDescription.ts';
 export type { RobotsDisallow } from './robots.ts';
 export { robotsTxt } from './robots.ts';
 export { routeProblems, withheldPhrase } from './routeProblems.ts';
+export type { RouteField } from './routeTable.ts';
+export {
+  ROUTE_FIELDS,
+  ROUTE_TABLE_FILE,
+  parseRouteTable,
+  serializeRouteTable,
+} from './routeTable.ts';
 export type { RouteMeta } from './routes.ts';
 export { assertRoutes, homeRoute, pageMetaFor, routeFor } from './routes.ts';
 export type { SiteFilesOptions } from './siteFiles.ts';
@@ -34,3 +49,5 @@ export type { StructuredDataOptions } from './structuredData.ts';
 export { structuredDataScript } from './structuredData.ts';
 export { PAGE_BODY_MARKER, PAGE_HEAD_MARKER, fill } from './template.ts';
 export { injectTrackingScript } from './trackingScript.ts';
+export type { PageContentRecord } from './pageContent.ts';
+export { pageContentOf } from './pageContent.ts';

package/src/seo/core/limits.ts

@@ -0,0 +1,27 @@
+/**
+ * The room a search result gives the words a page is indexed under. They are
+ * checked by `routeProblems` and fitted by `plainDescription` and
+ * `fitDescription`, so a site that composes its own prose reads them here
+ * rather than re-typing them.
+ */
+
+/**
+ * The longest title that survives a search result whole, before the site name
+ * is appended to it.
+ */
+export const TITLE_LIMIT = 60;
+
+/**
+ * The shortest description that says anything: under it a result pads the
+ * snippet with whatever text the crawler found on the page.
+ */
+export const DESCRIPTION_MIN = 110;
+
+/** The longest description a result shows without clipping it. */
+export const DESCRIPTION_MAX = 160;
+
+/**
+ * What a grown description aims for. It sits above {@link DESCRIPTION_MIN}
+ * because the floor is not the goal: a clause that fits is one the reader gets.
+ */
+export const DESCRIPTION_TARGET = 132;

package/src/seo/core/pageContent.ts

@@ -0,0 +1,42 @@
+/**
+ * The text each address says for itself, read from one record of the pages a
+ * site has written for.
+ */
+
+import type { Language } from '../../i18n/core/languages.ts';
+
+import type { PageContent } from './pageProse.ts';
+import type { RouteMeta } from './routes.ts';
+
+/**
+ * The pages a site has written for, by path, or a function giving them in
+ * each language.
+ */
+export type PageContentRecord =
+  | Readonly<Record<string, PageContent>>
+  | ((language: Language) => Readonly<Record<string, PageContent>>);
+
+/**
+ * What each address says for itself: the page written for its path when there
+ * is one, and otherwise the name and the sentence the route is already indexed
+ * under.
+ *
+ * The fallback repeats the snippet rather than adding to it, which is thin —
+ * but the route table writes those distinctly per page, so a thin page is never
+ * a duplicate of its neighbour, and no address ships the bare menu.
+ * @param pages - The pages written for, by path.
+ * @returns The function `cheminfoPrerender` calls once per route and language.
+ */
+export function pageContentOf(
+  pages: PageContentRecord,
+): (route: RouteMeta, language: Language) => PageContent {
+  return (route, language) => {
+    const written = typeof pages === 'function' ? pages(language) : pages;
+    return (
+      written[route.path] ?? {
+        heading: route.title,
+        paragraphs: [route.description],
+      }
+    );
+  };
+}

package/src/seo/core/plainDescription.ts

@@ -1,6 +1,8 @@
 import type { InlineSegment } from '../../pedagogy/core/inlineMarks.ts';
 import { parseInlineMarks } from '../../pedagogy/core/inlineMarks.ts';
 
+import { DESCRIPTION_MAX, DESCRIPTION_MIN } from './limits.ts';
+
 /** The room a search result gives a description. */
 export interface PlainDescriptionOptions {
   /**
@@ -34,8 +36,8 @@ export function plainDescription(
   prose: string,
   options: PlainDescriptionOptions = {},
 ): string {
-  const maxLength = options.maxLength ?? 160;
-  const minLength = options.minLength ?? 110;
+  const maxLength = options.maxLength ?? DESCRIPTION_MAX;
+  const minLength = options.minLength ?? DESCRIPTION_MIN;
   const text = plainProse(prose);
   if (text.length <= maxLength) return text;
   const whole = wholeSentences(text, maxLength);

package/src/seo/core/routeProblems.ts

@@ -11,15 +11,9 @@
  * The paths are `assertRoutes`' business; this is about the words.
  */
 
+import { DESCRIPTION_MAX, DESCRIPTION_MIN, TITLE_LIMIT } from './limits.ts';
 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

package/src/seo/core/routeTable.ts

@@ -0,0 +1,103 @@
+/**
+ * The route table a build writes beside its page, for the server that hands the
+ * page out: it titles every address from it, lists it in `sitemap.xml` and links
+ * it from the crawl path. The app's own table is the one thing that knows the
+ * pages, so there is one table rather than two that drift.
+ */
+
+import type { RouteMeta } from './routes.ts';
+import { assertRoutes } from './routes.ts';
+
+/** The file the table is written to, next to `index.html`. */
+export const ROUTE_TABLE_FILE = 'routes.json';
+
+/** A field of a route the table can carry. */
+export type RouteField = keyof RouteMeta;
+
+/** Every field of a route, in the order they are written. */
+export const ROUTE_FIELDS: readonly RouteField[] = [
+  'path',
+  'title',
+  'description',
+  'short',
+  'note',
+  'indexed',
+  'prefix',
+];
+
+/** The fields a route cannot be read without. */
+const REQUIRED_FIELDS: readonly RouteField[] = ['path', 'title', 'description'];
+
+/**
+ * Write a route table as the file a server reads back.
+ * @param routes - Every address the site answers.
+ * @param fields - The fields written; `path`, `title` and `description` are
+ * always written, since a route cannot be read without them.
+ * @returns The JSON document, ending with a newline.
+ */
+export function serializeRouteTable(
+  routes: readonly RouteMeta[],
+  fields: readonly RouteField[] = ROUTE_FIELDS,
+): string {
+  const written = new Set<RouteField>([...REQUIRED_FIELDS, ...fields]);
+  const order = ROUTE_FIELDS.filter((field) => written.has(field));
+  const table = routes.map((route) => {
+    const entry: Record<string, unknown> = {};
+    for (const field of order) {
+      if (route[field] !== undefined) entry[field] = route[field];
+    }
+    return entry;
+  });
+  return `${JSON.stringify(table, null, 2)}\n`;
+}
+
+/**
+ * Read a route table back, refusing anything the build did not write: an empty
+ * table, an entry missing its path, title or description, a field of the wrong
+ * type, or a table `assertRoutes` refuses.
+ * @param value - The parsed JSON.
+ * @returns The routes, carrying only the fields a route has, or `undefined`
+ * when the value is not a route table.
+ */
+export function parseRouteTable(value: unknown): RouteMeta[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) return undefined;
+  const routes: RouteMeta[] = [];
+  for (const entry of value) {
+    const route = readRoute(entry);
+    if (route === undefined) return undefined;
+    routes.push(route);
+  }
+  try {
+    assertRoutes(routes);
+  } catch {
+    return undefined;
+  }
+  return routes;
+}
+
+function readRoute(value: unknown): RouteMeta | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const entry = value as Record<string, unknown>;
+  const { path, title, description, short, note, indexed, prefix } = entry;
+  if (
+    typeof path !== 'string' ||
+    typeof title !== 'string' ||
+    typeof description !== 'string' ||
+    !isOptional(short, 'string') ||
+    !isOptional(note, 'string') ||
+    !isOptional(indexed, 'boolean') ||
+    !isOptional(prefix, 'boolean')
+  ) {
+    return undefined;
+  }
+  const route: RouteMeta = { path, title, description };
+  if (typeof short === 'string') route.short = short;
+  if (typeof note === 'string') route.note = note;
+  if (typeof indexed === 'boolean') route.indexed = indexed;
+  if (typeof prefix === 'boolean') route.prefix = prefix;
+  return route;
+}
+
+function isOptional(value: unknown, type: 'string' | 'boolean'): boolean {
+  return value === undefined || typeof value === type;
+}

package/src/seo/vite/index.ts

@@ -2,3 +2,5 @@ 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';
+export type { RouteTableOptions } from './routeTable.ts';
+export { cheminfoRouteTable } from './routeTable.ts';

package/src/seo/vite/prerender.ts

@@ -36,6 +36,8 @@ import { withLanguagePath } from '../../language/core/languagePath.ts';
 import { trimTrailingSlash } from '../../router/core/address.ts';
 import type { NoscriptText } from '../core/noscript.ts';
 import { noscriptIndex } from '../core/noscript.ts';
+import type { PageContentRecord } from '../core/pageContent.ts';
+import { pageContentOf } from '../core/pageContent.ts';
 import { pageHeadTags } from '../core/pageMeta.ts';
 import type { PageContent } from '../core/pageProse.ts';
 import type { RobotsDisallow } from '../core/robots.ts';
@@ -124,6 +126,15 @@ export interface PrerenderOptions {
    * @default undefined — every page carries the menu alone
    */
   content?: (route: RouteMeta, language: Language) => PageContent | undefined;
+  /**
+   * The pages written for, by path — or a function giving them per language —
+   * for a site that would otherwise write `content` only to look a path up in
+   * them. Every other address then says the name and the sentence its route
+   * is indexed under, so none ships the bare menu. `content`, when given, is
+   * read instead.
+   * @default undefined — `content` alone decides
+   */
+  pages?: PageContentRecord;
   /**
    * Every language the site is written in, the default one included.
    *
@@ -306,7 +317,7 @@ function crawlPathOf(
   const noscript =
     typeof declared === 'function' ? declared(language) : declared;
   if (noscript === false) return '';
-  const content = options.content?.(route, language);
+  const content = contentOf(options, route, language);
   const { routes: listed, ...prose } = noscript === true ? {} : noscript;
   // The crawl path of a translated page links to that language's addresses: a
   // French page listing the English ones is a crawler's only route out of it,
@@ -351,3 +362,17 @@ function withHtmlLang(template: string, language: Language): string {
     `<html$<attributes> lang="${language}"`,
   );
 }
+
+// What a page says for itself: the site's own function when it wrote one, and
+// otherwise the page it wrote for that path, or the route's name and sentence.
+function contentOf(
+  options: PrerenderOptions,
+  route: RouteMeta,
+  language: Language,
+): PageContent | undefined {
+  const { content, pages } = options;
+  if (content !== undefined) return content(route, language);
+  return pages === undefined
+    ? undefined
+    : pageContentOf(pages)(route, language);
+}

package/src/seo/vite/routeTable.ts

@@ -0,0 +1,79 @@
+/**
+ * Write the route table beside the page a server hands out.
+ *
+ * A site with a backend titles every address it answers, lists it in
+ * `sitemap.xml` and links it from the crawl path — and the app's own route table
+ * is the one thing that knows those addresses. So the build writes it next to
+ * `index.html`, from the very table the app reads, and `readRouteTable` in
+ * `react-cheminfo/server` reads it back: a page added to the site is indexed
+ * without anybody remembering to.
+ */
+
+import { writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Plugin } from 'vite';
+
+import type { RouteField } from '../core/routeTable.ts';
+import {
+  ROUTE_FIELDS,
+  ROUTE_TABLE_FILE,
+  serializeRouteTable,
+} from '../core/routeTable.ts';
+import type { RouteMeta } from '../core/routes.ts';
+import { assertRoutes } from '../core/routes.ts';
+
+/** Options of {@link cheminfoRouteTable}. */
+export interface RouteTableOptions {
+  /** Every address the site answers, each with its title and description. */
+  routes: readonly RouteMeta[];
+  /**
+   * The fields written for each route. `path`, `title` and `description` are
+   * always written: a server cannot read a route without them.
+   * @default every field of a route
+   */
+  fields?: readonly RouteField[];
+  /**
+   * The file written in the build.
+   * @default 'routes.json'
+   */
+  fileName?: string;
+}
+
+/**
+ * The Vite plugin writing the route table.
+ *
+ * The table is author configuration, so it is checked when the build starts —
+ * an address written twice, or one climbing out of the site, fails the build
+ * rather than shipping two sitemap entries for one page.
+ * @param options - The table, and which fields it carries.
+ * @returns The Vite plugin.
+ */
+export function cheminfoRouteTable(options: RouteTableOptions): Plugin {
+  const {
+    routes,
+    fields = ROUTE_FIELDS,
+    fileName = ROUTE_TABLE_FILE,
+  } = options;
+  let root = process.cwd();
+  let outDir = 'dist';
+
+  return {
+    name: 'cheminfo-route-table',
+    apply: 'build',
+    configResolved(config) {
+      root = config.root;
+      outDir = config.build.outDir;
+    },
+    buildStart() {
+      assertRoutes(routes);
+    },
+    writeBundle(output) {
+      const directory = output.dir ?? resolve(root, outDir);
+      writeFileSync(
+        join(directory, fileName),
+        serializeRouteTable(routes, fields),
+      );
+    },
+  };
+}