react-cheminfo 0.3.0 → 0.4.1

package/src/router/core/pageAddresses.ts

@@ -0,0 +1,106 @@
+import { normalizePath, splitAddress } from './address.ts';
+import { joinBasePath, normalizeBasePath, stripBasePath } from './basePath.ts';
+
+/**
+ * The table of everything the site answers, read by the three things that must
+ * agree on it: the build, which writes one HTML file per entry and the sitemap
+ * listing them; the server or the entrypoint, which titles the page it hands
+ * out; and the running app, which retitles the tab after an in-app move.
+ *
+ * Pure and DOM-free, so the prerender script imports the same table under Node
+ * that the browser imports at run time. A page missing from it is a page a
+ * search engine only ever sees as the home page.
+ * @param options - The pages, in the order the site presents them.
+ * @returns The three lookups the build and the app share.
+ */
+export function createPageAddresses<Page extends PageWithPath>(
+  options: PageAddressesOptions<Page>,
+): PageAddresses<Page> {
+  const pages = options.pages;
+  const first = pages[0];
+  if (first === undefined) {
+    throw new Error('createPageAddresses needs at least one page');
+  }
+  const home: Page = first;
+  const basePath = normalizeBasePath(options.basePath ?? '');
+
+  const byPath = new Map<string, Page>();
+  for (const page of pages) {
+    byPath.set(normalizePath(page.path), page);
+  }
+
+  function everyPage(): readonly Page[] {
+    return pages;
+  }
+
+  function canonicalPathOf(page: Page): string {
+    return joinBasePath(basePath, normalizePath(page.path));
+  }
+
+  function pageAt(address: string): Page {
+    const path = normalizePath(
+      stripBasePath(basePath, splitAddress(address).path),
+    );
+    const exact = byPath.get(path);
+    if (exact !== undefined) return exact;
+    return deepestPageUnder(pages, path) ?? home;
+  }
+
+  return { everyPage, canonicalPathOf, pageAt };
+}
+
+/** The one thing a page must carry: the address it is reachable at. */
+export interface PageWithPath {
+  /** Address from the site's own root, e.g. `/exercises`. */
+  path: string;
+}
+
+/** How a site's pages are turned into addresses. */
+export interface PageAddressesOptions<Page extends PageWithPath> {
+  /**
+   * Every page, deep addresses included. The first is the home page, and is
+   * what an address the site does not know opens.
+   */
+  pages: readonly Page[];
+  /**
+   * 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;
+}
+
+/** The lookups a site's pages answer. */
+export interface PageAddresses<Page extends PageWithPath> {
+  /** Every page, in the order given: what the sitemap lists and the build writes. */
+  everyPage: () => readonly Page[];
+  /**
+   * The address a page is indexed under, mount path included and query string
+   * dropped — a structure being edited and a share configuration are not pages.
+   */
+  canonicalPathOf: (page: Page) => string;
+  /**
+   * The page an address opens. An address below a page it does not list is that
+   * page — a link written before an exercise was renamed still opens, and is
+   * indexed as the exercises — and an address it knows nothing about is the
+   * home page.
+   */
+  pageAt: (address: string) => Page;
+}
+
+function deepestPageUnder<Page extends PageWithPath>(
+  pages: readonly Page[],
+  path: string,
+): Page | undefined {
+  let deepest: Page | undefined;
+  let depth = 0;
+  for (const page of pages) {
+    const candidate = normalizePath(page.path);
+    if (candidate === '/' || candidate.length <= depth) continue;
+    if (path.startsWith(`${candidate}/`)) {
+      deepest = page;
+      depth = candidate.length;
+    }
+  }
+  return deepest;
+}

package/src/router/core/query.ts

@@ -0,0 +1,87 @@
+import { safeDecode } from './address.ts';
+
+/** How a query string is read and written. */
+export interface QueryStringOptions {
+  /**
+   * Keep a `+` in a value as the character it is, rather than reading it as
+   * the space `URLSearchParams` decodes it to. A SMILES carries `+` for a
+   * charged atom, and `CC[N+](C)(C)C` handed out in a link has to survive.
+   * @default true
+   */
+  literalPlus?: boolean;
+  /**
+   * Write a parameter carrying nothing back as the bare key, so a hand-typed
+   * flag such as `?embed` survives the round trip. Left off, an empty value is
+   * dropped and an unconfigured link stays clean.
+   * @default false
+   */
+  keepEmptyValues?: boolean;
+}
+
+/**
+ * Read a query string.
+ *
+ * Forgiving by design, because the address is hand-editable and arrives from
+ * bookmarks, course pages and lecture slides: a repeated key keeps its last
+ * value, a key carrying nothing is kept as an empty value so a bare `?embed`
+ * reads as present, and an escape that does not decode is taken literally.
+ * @param search - The query string, with or without its leading `?`.
+ * @param options - How the values are decoded.
+ * @returns One entry per key, decoded.
+ */
+export function parseQueryString(
+  search: string,
+  options: QueryStringOptions = {},
+): Record<string, string> {
+  const literalPlus = options.literalPlus ?? true;
+  const query: Record<string, string> = {};
+  const text = search.startsWith('?') ? search.slice(1) : search;
+  for (const part of text.split('&')) {
+    if (part === '') continue;
+    const index = part.indexOf('=');
+    const rawKey = index === -1 ? part : part.slice(0, index);
+    const rawValue = index === -1 ? '' : part.slice(index + 1);
+    const key = decodeValue(rawKey, literalPlus);
+    if (key === '') continue;
+    query[key] = decodeValue(rawValue, literalPlus);
+  }
+  return query;
+}
+
+/**
+ * Write a query string.
+ *
+ * A parameter left at nothing is dropped unless `keepEmptyValues` asks for it,
+ * and `undefined` or `null` removes a parameter outright, so a page can hand
+ * its whole state to this function and get back only what it actually carries.
+ * @param params - The parameters, in the order they should be written.
+ * @param options - How the values are encoded.
+ * @returns The query string, without its leading `?`, empty when nothing is carried.
+ */
+export function formatQueryString(
+  params: Readonly<Record<string, string | undefined | null>>,
+  options: QueryStringOptions = {},
+): string {
+  const keepEmptyValues = options.keepEmptyValues ?? false;
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (key === '' || value === undefined || value === null) continue;
+    if (value === '') {
+      if (keepEmptyValues) parts.push(encodeValue(key));
+      continue;
+    }
+    parts.push(`${encodeValue(key)}=${encodeValue(value)}`);
+  }
+  return parts.join('&');
+}
+
+// A comma is legal in a query value and is what separates the keys of `hide`
+// and the formulas of a list; escaped to `%2C` a link stops being one a teacher
+// can read out loud.
+function encodeValue(value: string): string {
+  return encodeURIComponent(value).replaceAll('%2C', ',');
+}
+
+function decodeValue(value: string, literalPlus: boolean): string {
+  return safeDecode(literalPlus ? value : value.replaceAll('+', ' '));
+}

package/src/router/core/tabRouter.ts

@@ -0,0 +1,214 @@
+import { splitAddress, splitPath } from './address.ts';
+import { joinBasePath, normalizeBasePath, stripBasePath } from './basePath.ts';
+import { pathFromLegacyHash } from './legacyHash.ts';
+import type { QueryStringOptions } from './query.ts';
+import { formatQueryString, parseQueryString } from './query.ts';
+
+/**
+ * The two directions between an address and the page it names.
+ *
+ * Both functions are pure: they take and return strings, never touch
+ * `location`, and know none of the parameter names the tool carries — the share
+ * configuration owns those. That is what makes the round trip unit-testable
+ * without a DOM, and usable from a prerender script under Node.
+ * @param options - The tabs of the site and how their addresses are written.
+ * @returns The parser, the serialiser, and the test for a known tab.
+ */
+export function createTabRouter<Tab extends string>(
+  options: TabRouterOptions<Tab>,
+): TabRouter<Tab> {
+  const mode = options.mode ?? 'path';
+  const basePath = normalizeBasePath(options.basePath ?? '');
+  const adoptLegacyHash = options.adoptLegacyHash ?? false;
+  const queryOptions: QueryStringOptions = {
+    literalPlus: options.literalPlus ?? true,
+    keepEmptyValues: options.keepEmptyValues ?? false,
+  };
+
+  const definitions = new Map<string, NormalizedTab>();
+  for (const tab of options.tabs) {
+    const definition = typeof tab === 'string' ? { id: tab } : tab;
+    definitions.set(definition.id, {
+      path: normalizeTabPath(definition.path ?? `/${definition.id}`),
+      takesId: definition.takesId ?? false,
+    });
+  }
+  definitions.set(
+    options.home,
+    definitions.get(options.home) ?? { path: '/', takesId: false },
+  );
+
+  const tabBySegment = new Map<string, Tab>();
+  for (const [id, definition] of definitions) {
+    const segment = definition.path.slice(1);
+    if (segment !== '') tabBySegment.set(segment, id as Tab);
+  }
+
+  function isTab(value: string): value is Tab {
+    return definitions.has(value);
+  }
+
+  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 first = segments[0];
+    const tab = first === undefined ? undefined : tabBySegment.get(first);
+    if (tab === undefined) return { tab: options.home, id: null, params };
+    const second = segments[1];
+    const takesId = definitions.get(tab)?.takesId ?? false;
+    return { tab, id: takesId && second !== undefined ? second : null, params };
+  }
+
+  function format(route: TabRouteInput<Tab>): string {
+    const tab = definitions.has(route.tab) ? route.tab : options.home;
+    const definition = definitions.get(tab);
+    const base = tab === options.home ? '/' : (definition?.path ?? '/');
+    const id = definition?.takesId === true ? (route.id ?? null) : null;
+    const path =
+      id === null || base === '/' ? base : `${base}/${encodeURIComponent(id)}`;
+    const search = formatQueryString(route.params ?? {}, queryOptions);
+    const address = mode === 'hash' ? `#${path}` : joinBasePath(basePath, path);
+    return search === '' ? address : `${address}?${search}`;
+  }
+
+  return { parse, format, isTab };
+}
+
+/** 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>;
+}
+
+/** The string ↔ route mapping of a site. */
+export interface TabRouter<Tab extends string = string> {
+  /**
+   * 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;
+}
+
+interface NormalizedTab {
+  path: string;
+  takesId: boolean;
+}
+
+function readAddress(
+  address: string,
+  mode: 'path' | 'hash',
+  basePath: string,
+  adoptLegacyHash: boolean,
+): { path: string; search: string } {
+  if (mode === 'hash') {
+    const fragment = address.includes('#')
+      ? splitAddress(address).fragment
+      : address;
+    const { path, search } = splitAddress(fragment);
+    return { path, search };
+  }
+
+  const outer = splitAddress(address);
+  const path = stripBasePath(basePath, outer.path);
+  if (adoptLegacyHash && path === '/') {
+    const legacy = pathFromLegacyHash(address);
+    if (legacy !== null) return splitAddress(legacy);
+  }
+  return { path, search: outer.search };
+}
+
+function normalizeTabPath(path: string): string {
+  const opened = path.startsWith('/') ? path : `/${path}`;
+  const closed = opened.replace(/\/+$/, '');
+  return closed === '' ? '/' : closed;
+}

package/src/seo/core/documentMeta.ts

@@ -0,0 +1,92 @@
+/**
+ * Keep the head in step with the page on screen after an in-app move.
+ *
+ * The server, or the build that wrote one file per address, already titled the
+ * page it handed out; this is what a click inside the app changes, and what a
+ * crawler that renders the page reads afterwards. Every access to the document
+ * is guarded, so a prerender script importing this under Node does nothing
+ * rather than throwing.
+ * @param meta - What the page on screen is called and where it is indexed.
+ */
+export function writeDocumentMeta(meta: DocumentMeta): void {
+  if (typeof document === 'undefined') return;
+  documentTitle(meta.title);
+  if (meta.description !== undefined) metaDescription(meta.description);
+  if (meta.canonical !== undefined) canonicalLink(meta.canonical);
+}
+
+/**
+ * Name the browser tab.
+ * @param title - The title of the page, site name included.
+ */
+export function documentTitle(title: string): void {
+  if (typeof document === 'undefined') return;
+  document.title = title;
+}
+
+/**
+ * Point the canonical link at the address the page is indexed under, creating
+ * the tag when the served page carries none.
+ *
+ * The query string is dropped, and so is any fragment: the structure being
+ * edited and the configuration a shared link carries are not pages of their
+ * own, and indexing them as such splits one result into hundreds.
+ * @param href - The address of the page, absolute so a crawler can resolve it.
+ */
+export function canonicalLink(href: string): void {
+  if (typeof document === 'undefined') return;
+  const address = withoutQuery(href);
+  if (address === '') return;
+
+  const existing = document.querySelector<HTMLLinkElement>(
+    'link[rel="canonical"]',
+  );
+  if (existing) {
+    existing.href = address;
+    return;
+  }
+
+  const link = document.createElement('link');
+  link.rel = 'canonical';
+  document.head.append(link);
+  link.href = address;
+}
+
+/** What a page is called and where it is indexed. */
+export interface DocumentMeta {
+  /** The title of the tab, the search result and the shared card. */
+  title: string;
+  /**
+   * One sentence describing this page, in the words someone would search for.
+   * Left out, the description the page was served with stays as it is — which
+   * is what every crawler but a rendering one has already read.
+   * @default undefined
+   */
+  description?: string;
+  /**
+   * The absolute address the page is indexed under. Left out, the canonical
+   * link the page was served with stays as it is.
+   * @default undefined
+   */
+  canonical?: string;
+}
+
+function metaDescription(content: string): void {
+  const existing = document.querySelector<HTMLMetaElement>(
+    'meta[name="description"]',
+  );
+  if (existing) {
+    existing.content = content;
+    return;
+  }
+
+  const meta = document.createElement('meta');
+  meta.name = 'description';
+  document.head.append(meta);
+  meta.content = content;
+}
+
+function withoutQuery(href: string): string {
+  const cut = href.search(/[?#]/);
+  return cut === -1 ? href : href.slice(0, cut);
+}

package/src/seo/core/index.ts

@@ -0,0 +1,26 @@
+export type { DocumentMeta } from './documentMeta.ts';
+export {
+  canonicalLink,
+  documentTitle,
+  writeDocumentMeta,
+} from './documentMeta.ts';
+export type { PageMetaOptions } from './pageMeta.ts';
+export {
+  injectPageMeta,
+  insertBeforeHeadEnd,
+  pageDocumentMeta,
+} from './pageMeta.ts';
+export type { RouteMeta } from './routes.ts';
+export {
+  homeRoute,
+  pageMetaFor,
+  routeFor,
+  trimTrailingSlash,
+} from './routes.ts';
+export type { SiteFilesOptions, StructuredDataOptions } from './siteFiles.ts';
+export {
+  noscriptIndex,
+  robotsTxt,
+  sitemapXml,
+  structuredDataScript,
+} from './siteFiles.ts';

package/src/seo/core/pageMeta.ts

@@ -0,0 +1,127 @@
+/**
+ * The head of the page a crawler is handed.
+ *
+ * Googlebot renders JavaScript, but Bing, a Slack unfurl, an LMS preview and
+ * every academic indexer read the HTML that came off the wire — so the title,
+ * the description and the canonical of a page must already be in it. A site
+ * with a server rewrites them per request; a static one writes one file per
+ * address at build time. Both call this, which is pure string work: no
+ * `window`, no `node:fs`.
+ */
+
+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 { DocumentMeta } from './documentMeta.ts';
+import type { RouteMeta } from './routes.ts';
+import { pageMetaFor, trimTrailingSlash } from './routes.ts';
+
+/** Which site is being served, and what it answers. */
+export interface PageMetaOptions {
+  /** The site, named or passed. */
+  site: EcosystemSite | SiteId;
+  /** Every address it answers, each with its title and description. */
+  routes: readonly RouteMeta[];
+  /** The address being written, query string included. */
+  url: string;
+  /**
+   * Origin every absolute address is built on. A server passes the one the
+   * request arrived on; a build leaves it out and the site's own host is used.
+   * @default `https://<the site's host>`
+   */
+  origin?: string;
+  /**
+   * The card a link to the page unfurls into, as an absolute address or a path.
+   * @default '/og.png'
+   */
+  image?: string;
+}
+
+/**
+ * Give a page the title, the description and the canonical address of the route
+ * it answers, plus the card a link to it unfurls into.
+ * @param html - The built page.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The page, with its head rewritten for that route.
+ */
+export function injectPageMeta(html: string, options: PageMetaOptions): string {
+  const site = resolveSite(options.site);
+  const meta = pageMetaFor(options.routes, options.url);
+  const name = siteDisplayName(site);
+  const origin = trimTrailingSlash(options.origin ?? `https://${site.host}`);
+  const { title, canonical } = pageDocumentMeta(options);
+  const image = absolute(options.image ?? '/og.png', origin);
+
+  const head = [
+    `<link rel="canonical" href="${escapeAttribute(canonical)}" />`,
+    '<meta property="og:type" content="website" />',
+    `<meta property="og:site_name" content="${escapeAttribute(name)}" />`,
+    `<meta property="og:title" content="${escapeAttribute(title)}" />`,
+    `<meta property="og:description" content="${escapeAttribute(meta.description)}" />`,
+    `<meta property="og:url" content="${escapeAttribute(canonical)}" />`,
+    `<meta property="og:image" content="${escapeAttribute(image)}" />`,
+    '<meta name="twitter:card" content="summary_large_image" />',
+  ].join('\n');
+
+  return insertBeforeHeadEnd(
+    replaceDescription(replaceTitle(html, title), meta.description),
+    head,
+  );
+}
+
+/**
+ * What the page on screen is called and where it is indexed, for the app to
+ * write after an in-app move.
+ *
+ * The same title and canonical the build wrote into the file it served, so a
+ * click that changes the page cannot disagree with the page a crawler fetched.
+ * @param options - Which site, which address, and where it is served from.
+ * @returns The title, the description and the canonical of that address.
+ */
+export function pageDocumentMeta(options: PageMetaOptions): Required<DocumentMeta> {
+  const site = resolveSite(options.site);
+  const meta = pageMetaFor(options.routes, options.url);
+  const origin = trimTrailingSlash(options.origin ?? `https://${site.host}`);
+  return {
+    title: `${meta.title} — ${siteDisplayName(site)}`,
+    description: meta.description,
+    canonical: `${origin}${meta.path}`,
+  };
+}
+
+/**
+ * Put an addition at the end of the head, where a tracking snippet and a
+ * structured-data block both belong.
+ * @param html - The page.
+ * @param addition - The markup to add, taken as written.
+ * @returns The page, with the addition before `</head>`.
+ */
+export function insertBeforeHeadEnd(html: string, addition: string): string {
+  const head = html.lastIndexOf('</head>');
+  if (head === -1) return `${html}\n${addition}\n`;
+  return `${html.slice(0, head)}${addition}\n${html.slice(head)}`;
+}
+
+function resolveSite(site: EcosystemSite | SiteId): EcosystemSite {
+  return typeof site === 'string' ? siteById(site) : site;
+}
+
+function absolute(target: string, origin: string): string {
+  return target.startsWith('/') ? `${origin}${target}` : target;
+}
+
+function replaceTitle(html: string, title: string): string {
+  const replacement = `<title>${escapeText(title)}</title>`;
+  return html.includes('<title>')
+    ? html.replace(/<title>[\s\S]*?<\/title>/, replacement)
+    : insertBeforeHeadEnd(html, replacement);
+}
+
+function replaceDescription(html: string, description: string): string {
+  const replacement = `<meta name="description" content="${escapeAttribute(description)}" />`;
+  const existing = /<meta[^>]*name="description"[^>]*>/;
+  return existing.test(html)
+    ? html.replace(existing, replacement)
+    : insertBeforeHeadEnd(html, replacement);
+}