react-cheminfo 0.64.0 → 0.65.0

package/src/router/core/tabRouter.ts

@@ -1,8 +1,27 @@
 import { splitAddress, splitPath, trimTrailingSlash } from './address.ts';
 import { joinBasePath, normalizeBasePath, stripBasePath } from './basePath.ts';
+import {
+  adoptLanguageParam,
+  readRouteLanguage,
+  writeRouteLanguage,
+} from './languageRoute.ts';
 import { adoptLegacyHashAddress, pathFromLegacyHash } from './legacyHash.ts';
 import type { QueryStringOptions } from './query.ts';
 import { formatQueryString, parseQueryString } from './query.ts';
+import type {
+  TabRoute,
+  TabRouteInput,
+  TabRouter,
+  TabRouterOptions,
+} from './tabRouterTypes.ts';
+
+export type {
+  TabDefinition,
+  TabRoute,
+  TabRouteInput,
+  TabRouter,
+  TabRouterOptions,
+} from './tabRouterTypes.ts';
 
 /**
  * The two directions between an address and the page it names.
@@ -20,6 +39,7 @@ export function createTabRouter<Tab extends string>(
   const mode = options.mode ?? 'path';
   const basePath = normalizeBasePath(options.basePath ?? '');
   const adoptLegacyHash = options.adoptLegacyHash ?? false;
+  const siteLanguages = options.languages;
   const queryOptions: QueryStringOptions = {
     literalPlus: options.literalPlus ?? true,
     keepEmptyValues: options.keepEmptyValues ?? false,
@@ -50,8 +70,17 @@ export function createTabRouter<Tab extends string>(
 
   function parse(address: string): TabRoute<Tab> {
     const parts = readAddress(address, mode, basePath, adoptLegacyHash);
-    const params = parseQueryString(parts.search, queryOptions);
-    const segments = splitPath(parts.path);
+    const query = parseQueryString(parts.search, queryOptions);
+    if (siteLanguages === undefined) return routeOf(parts.path, query);
+    const read = readRouteLanguage(parts.path, query, siteLanguages);
+    return { ...routeOf(read.path, read.params), language: read.language };
+  }
+
+  function routeOf(
+    path: string,
+    params: Record<string, string>,
+  ): TabRoute<Tab> {
+    const segments = splitPath(path);
     const first = segments[0];
     const tab = first === undefined ? undefined : tabBySegment.get(first);
     if (tab === undefined) return { tab: options.home, id: null, params };
@@ -65,8 +94,12 @@ export function createTabRouter<Tab extends string>(
     const definition = definitions.get(tab);
     const base = tab === options.home ? '/' : (definition?.path ?? '/');
     const id = definition?.takesId === true ? (route.id ?? null) : null;
-    const path =
+    const page =
       id === null || base === '/' ? base : `${base}/${encodeURIComponent(id)}`;
+    const path =
+      siteLanguages === undefined
+        ? page
+        : writeRouteLanguage(route.language, page, siteLanguages);
     const search = formatQueryString(route.params ?? {}, queryOptions);
     const address = mode === 'hash' ? `#${path}` : joinBasePath(basePath, path);
     return search === '' ? address : `${address}?${search}`;
@@ -77,125 +110,34 @@ export function createTabRouter<Tab extends string>(
     const adopted = adoptLegacyHashAddress(address, { basePath });
     if (adopted === null) return null;
     const route = parse(adopted);
-    const path = format({ tab: route.tab, id: route.id });
+    const path = format({
+      tab: route.tab,
+      id: route.id,
+      language: route.language,
+    });
     const { search } = splitAddress(adopted);
     return search === '' ? path : `${path}?${search}`;
   }
 
-  return { mode, parse, format, isTab, legacyAddress };
-}
-
-/** 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;
-}
-
-/** 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>;
-}
-
-/** 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>;
-}
+  function languageAddress(address: string): string | null {
+    if (mode !== 'path' || siteLanguages === undefined) return null;
+    return adoptLanguageParam(address, {
+      basePath,
+      languages: siteLanguages,
+      queryOptions,
+    });
+  }
 
-/** 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;
+  return {
+    mode,
+    parse,
+    format,
+    isTab,
+    legacyAddress,
+    languageAddress,
+    basePath,
+    languages: siteLanguages,
+  };
 }
 
 interface NormalizedTab {

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