react-cheminfo 0.37.0 → 0.39.0

package/src/seo/core/startDocumentMeta.ts

@@ -52,18 +52,18 @@ export function startDocumentMeta(
 ): () => void {
   if (typeof document === 'undefined') return stopNothing;
 
+  // Everything the caller passed goes through, rather than the four fields this
+  // once named one by one: an option added to `PageMetaOptions` and forgotten
+  // here is dropped in silence. `languages` was, and every translated page took
+  // the English home page's title and canonical — type-checked, linted and unit
+  // tested all the way.
+  const { url, follow, ...page } = options;
+
   const write = (): void => {
-    writeDocumentMeta(
-      pageDocumentMeta({
-        site: options.site,
-        routes: options.routes,
-        url: options.url(),
-        origin: options.origin,
-      }),
-    );
+    writeDocumentMeta(pageDocumentMeta({ ...page, url: url() }));
   };
 
-  return (options.follow ?? writeOnce)(write);
+  return (follow ?? writeOnce)(write);
 }
 
 function writeOnce(write: () => void): () => void {

package/src/seo/vite/prerender.ts

@@ -23,6 +23,10 @@ import { dirname, join, resolve } from 'node:path';
 import type { Logger, Plugin } from 'vite';
 
 import type { SiteId, SiteRecord } from '../../ecosystem/core/sites.ts';
+import { CHROME_CATALOG } from '../../i18n/core/chromeCatalog.ts';
+import type { Language } from '../../i18n/core/languages.ts';
+import { DEFAULT_LANGUAGE } from '../../i18n/core/languages.ts';
+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';
@@ -40,8 +44,17 @@ import { PAGE_BODY_MARKER, PAGE_HEAD_MARKER, fill } from '../core/template.ts';
 export interface PrerenderOptions {
   /** The site, named or passed. */
   site: SiteRecord | SiteId;
-  /** Every address it answers, each with its title and description. */
-  routes: readonly RouteMeta[];
+  /**
+   * Every address it answers, each with its title and description.
+   *
+   * A translated site passes a function instead: the build calls it once per
+   * language and writes that language's table, so the title and the description
+   * a search result shows are in the language of the page it points at. The
+   * paths are the same in every language — an id is never translated, or a
+   * progress key, a share link and a bookmark would all break on a language
+   * switch.
+   */
+  routes: readonly RouteMeta[] | ((language: Language) => 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
@@ -91,7 +104,8 @@ export interface PrerenderOptions {
    * `<!--cheminfo:body-->` at all.
    * @default true
    */
-  noscript?: boolean | NoscriptText;
+  noscript?:
+    boolean | NoscriptText | ((language: Language) => boolean | NoscriptText);
   /**
    * What each page says for itself, above the crawl path: its own heading, its
    * prose and the facts it would show anyway, read from the same data the app
@@ -103,7 +117,19 @@ export interface PrerenderOptions {
    * the bundle the browser downloads: only the build ever calls it.
    * @default undefined — every page carries the menu alone
    */
-  content?: (route: RouteMeta) => PageContent | undefined;
+  content?: (route: RouteMeta, language: Language) => PageContent | undefined;
+  /**
+   * Every language the site is written in, the default one included.
+   *
+   * The build then writes one file per address per language — `/tutorial` and
+   * `/fr/tutorial` — each with its own `lang`, title, description and
+   * canonical, the `hreflang` set tying them together, and every variant in the
+   * sitemap. That is the whole of what makes a translation findable: a site
+   * keeping its language in a parameter or in storage serves five languages at
+   * one address, and a crawler indexes one.
+   * @default [the default language]
+   */
+  languages?: readonly Language[];
 }
 
 /**
@@ -114,21 +140,43 @@ export interface PrerenderOptions {
  * 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;
+  const { site, origin, robots = [] } = options;
+  const languages = options.languages ?? [DEFAULT_LANGUAGE];
+  const tableFor = (language: Language): readonly RouteMeta[] =>
+    typeof options.routes === 'function'
+      ? options.routes(language)
+      : options.routes;
+
+  // Every language answers the same addresses, so each table is checked and
+  // they are checked against each other: a translation that renames a path or
+  // drops a page writes a file the sitemap of another language names, and the
+  // `hreflang` set would point at an address that is not there.
+  const routes = tableFor(DEFAULT_LANGUAGE);
   assertRoutes(routes);
-  const structuredData = structuredDataOf(options);
+  for (const language of languages) {
+    if (language === DEFAULT_LANGUAGE) continue;
+    assertSamePaths(routes, tableFor(language), language);
+  }
+
+  const structuredData = structuredDataOf(options, routes);
 
   let out = 'dist';
   let serve = false;
   let logger: Logger | null = null;
 
-  const page = (template: string, route: RouteMeta) => {
+  const page = (template: string, route: RouteMeta, language: Language) => {
     const head = fill(
-      template,
+      withHtmlLang(template, language),
       PAGE_HEAD_MARKER,
-      `${pageHeadTags({ site, routes, origin, url: route.path })}${structuredData}`,
+      `${pageHeadTags({
+        site,
+        routes: tableFor(language),
+        origin,
+        languages,
+        url: withLanguagePath(language, route.path),
+      })}${structuredData}`,
     );
-    const crawlPath = crawlPathOf(options, route);
+    const crawlPath = crawlPathOf(options, route, language, tableFor(language));
     return crawlPath === '' ? head : fill(head, PAGE_BODY_MARKER, crawlPath);
   };
 
@@ -145,37 +193,60 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
     // from the home route rather than shipped with its markers showing.
     transformIndexHtml: {
       order: 'post',
-      handler: (html: string) => (serve ? page(html, homeRoute(routes)) : html),
+      handler: (html: string) =>
+        serve ? page(html, homeRoute(routes), DEFAULT_LANGUAGE) : html,
     },
 
-    closeBundle() {
+    async closeBundle() {
       if (serve) return;
+      // The crawl path names the family in the chrome's own words, and every
+      // language but the default arrives as a chunk of its own, so they are all
+      // fetched before a single file is written.
+      await Promise.all(
+        languages
+          .filter((language) => language !== DEFAULT_LANGUAGE)
+          .map((language) => CHROME_CATALOG.load(language)),
+      );
+
       const template = readFileSync(join(out, 'index.html'), 'utf8');
 
-      const write = (route: RouteMeta, file: string) => {
+      const write = (route: RouteMeta, language: Language, file: string) => {
         mkdirSync(dirname(file), { recursive: true });
-        writeFileSync(file, page(template, route));
+        writeFileSync(file, page(template, route, language));
       };
 
-      let root = false;
-      for (const route of routes) {
-        const address = trimTrailingSlash(route.path);
-        if (address === '/') root = true;
-        write(
-          route,
-          address === '/'
-            ? join(out, 'index.html')
-            : join(out, address.slice(1), 'index.html'),
-        );
+      let written = 0;
+      for (const language of languages) {
+        const table = tableFor(language);
+        let root = false;
+        for (const route of table) {
+          const address = trimTrailingSlash(
+            withLanguagePath(language, route.path),
+          );
+          if (address === '/') root = true;
+          write(
+            route,
+            language,
+            address === '/'
+              ? join(out, 'index.html')
+              : join(out, address.slice(1), 'index.html'),
+          );
+          written++;
+        }
+        // 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.
+        // A language other than the default already has its own front page at
+        // `/<language>`, so only the unprefixed one is ever missing.
+        if (!root && language === DEFAULT_LANGUAGE) {
+          write(homeRoute(table), language, join(out, 'index.html'));
+          written++;
+        }
       }
-      // 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), join(out, 'index.html'));
 
       writeFileSync(
         join(out, 'sitemap.xml'),
-        sitemapXml({ site, routes, origin }),
+        sitemapXml({ site, routes, origin, languages }),
       );
       if (robots !== false) {
         writeFileSync(
@@ -184,17 +255,22 @@ export function cheminfoPrerender(options: PrerenderOptions): Plugin {
         );
       }
 
+      const spoken =
+        languages.length > 1 ? ` in ${languages.length} languages` : '';
       logger?.info(
-        `${routes.length} pages prerendered, and listed in sitemap.xml`,
+        `${written} pages prerendered${spoken}, and listed in sitemap.xml`,
       );
     },
   };
 }
 
-function structuredDataOf(options: PrerenderOptions): string {
+function structuredDataOf(
+  options: PrerenderOptions,
+  routes: readonly RouteMeta[],
+): string {
   const { category, ...rest } = options;
   if (category === false) return '';
-  const { site, routes, origin } = rest;
+  const { site, origin } = rest;
   const { operatingSystem, description, browserRequirements, currency } = rest;
   return `\n${structuredDataScript({
     site,
@@ -208,16 +284,64 @@ function structuredDataOf(options: PrerenderOptions): string {
   })}`;
 }
 
-function crawlPathOf(options: PrerenderOptions, route: RouteMeta): string {
-  const { site, routes, origin, noscript = true } = options;
+function crawlPathOf(
+  options: PrerenderOptions,
+  route: RouteMeta,
+  language: Language,
+  routes: readonly RouteMeta[],
+): string {
+  const { site, origin } = options;
+  // The crawl path of a translated page is that language's: its heading, its
+  // intro and the label under every link. Declared as a function of the
+  // language, the site writes each of them from its own catalog; declared as a
+  // record, it is the same words on every language, which is what a site that
+  // speaks one wants and is what it used to be.
+  const declared = options.noscript ?? true;
+  const noscript =
+    typeof declared === 'function' ? declared(language) : declared;
   if (noscript === false) return '';
-  const content = options.content?.(route);
+  const content = options.content?.(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,
+  // and it would lead straight back out of the translation.
+  const menu = (listed ?? routes).map((entry) => ({
+    ...entry,
+    path: withLanguagePath(language, entry.path),
+  }));
   return noscriptIndex({
     site,
     origin,
     ...prose,
-    routes: listed ?? routes,
+    routes: menu,
     content,
+    language,
   });
 }
+
+// Two tables of one site answer the same addresses. A translated table that
+// renames or drops a path leaves the `hreflang` set of every other language
+// pointing at an address nothing wrote, which is a soft 404 on each of them.
+function assertSamePaths(
+  source: readonly RouteMeta[],
+  translated: readonly RouteMeta[],
+  language: Language,
+): void {
+  const wanted = source.map((route) => route.path).join(' ');
+  const written = translated.map((route) => route.path).join(' ');
+  if (wanted !== written) {
+    throw new Error(
+      `the ${language} route table answers different addresses than the source one: an address is the same in every language`,
+    );
+  }
+}
+
+// The template is written in the default language, so each file says which
+// language it is actually in. A page whose `lang` lies is read aloud wrong and
+// offered to the wrong reader.
+function withHtmlLang(template: string, language: Language): string {
+  return template.replace(
+    /<html(?<attributes>[^>]*)\slang="[^"]*"/i,
+    `<html$<attributes> lang="${language}"`,
+  );
+}

package/src/share/core/devices.ts

@@ -0,0 +1,80 @@
+/** The screens a link can be looked at on, before it is handed out. */
+export type SharePreviewDeviceKey = 'window' | 'mobile' | 'laptop' | 'hd';
+
+/** A screen the preview lays the page out at. */
+export interface SharePreviewSize {
+  /** Width in CSS pixels. */
+  width: number;
+  /** Height in CSS pixels. */
+  height: number;
+}
+
+/**
+ * The screens offered, in the order the capsules read. `window` is the
+ * reader's own, and is resolved against the browser rather than written here.
+ */
+export const SHARE_PREVIEW_DEVICES: readonly SharePreviewDeviceKey[] = [
+  'window',
+  'mobile',
+  'laptop',
+  'hd',
+];
+
+const FIXED_SIZES: Record<
+  Exclude<SharePreviewDeviceKey, 'window'>,
+  SharePreviewSize
+> = {
+  mobile: { width: 390, height: 844 },
+  laptop: { width: 1280, height: 800 },
+  hd: { width: 1920, height: 1080 },
+};
+
+/** What the preview falls back to where there is no window to measure. */
+const FALLBACK_WINDOW: SharePreviewSize = { width: 1280, height: 800 };
+
+/**
+ * The page size a device lays the preview out at.
+ * @param key - The device picked.
+ * @param window - The reader's own window, for the `window` device.
+ * @returns Its width and height in CSS pixels.
+ */
+export function sharePreviewSize(
+  key: SharePreviewDeviceKey,
+  window?: Partial<SharePreviewSize>,
+): SharePreviewSize {
+  if (key !== 'window') return FIXED_SIZES[key];
+  const width = window?.width ?? 0;
+  const height = window?.height ?? 0;
+  return width > 0 && height > 0 ? { width, height } : FALLBACK_WINDOW;
+}
+
+/**
+ * How far the page is shrunk to fit the pane it is previewed in.
+ *
+ * It is never enlarged: a phone shown bigger than a phone is not what the
+ * reader is checking.
+ * @param pane - The room the preview pane has.
+ * @param page - The size the page is laid out at.
+ * @returns The scale, between 0 and 1.
+ */
+export function sharePreviewScale(
+  pane: Partial<SharePreviewSize>,
+  page: SharePreviewSize,
+): number {
+  const width = pane.width ?? 0;
+  const height = pane.height ?? 0;
+  if (width <= 0 || height <= 0) return 1;
+  return Math.min(1, width / page.width, height / page.height);
+}
+
+/**
+ * The address as the preview's own bar writes it, without its scheme.
+ *
+ * What a reader checks there is the site and the query the link carries, and a
+ * bar as wide as a phone has no room for `https://`.
+ * @param url - The link the preview loads.
+ * @returns The address, scheme dropped.
+ */
+export function sharePreviewAddress(url: string): string {
+  return url.replace(/^[a-z][\w+.-]*:\/\//i, '');
+}

package/src/share/core/index.ts

@@ -9,7 +9,21 @@ export {
   suggestedShareConfig,
   visibleShareParts,
 } from './config.ts';
+export type { SharePreviewDeviceKey, SharePreviewSize } from './devices.ts';
+export {
+  SHARE_PREVIEW_DEVICES,
+  sharePreviewAddress,
+  sharePreviewScale,
+  sharePreviewSize,
+} from './devices.ts';
 export { escapeAttribute, escapeText } from './escape.ts';
+export type { ShareRegion } from './regions.ts';
+export {
+  SHARE_REGIONS_MESSAGE,
+  SHARE_REGIONS_REQUEST,
+  isShareRegionsRequest,
+  readShareRegions,
+} from './regions.ts';
 export type {
   BooleanParamOptions,
   IntegerParamOptions,

package/src/share/core/regions.ts

@@ -0,0 +1,87 @@
+/**
+ * Where each part of a page sits, so a share dialog can show which region of
+ * the preview a row of its list names.
+ *
+ * The two sides are different documents — the dialog and the framed page — so
+ * they speak by message. Everything that arrives is somebody else's input: a
+ * framed page is messaged by whatever page frames it, and a dialog by whatever
+ * it frames, so both ends read rather than trust.
+ */
+
+/** Asks a framed page to report where its parts are, and to keep reporting. */
+export const SHARE_REGIONS_REQUEST = 'cheminfo:share-regions-request';
+
+/** Carries the answer back to the dialog. */
+export const SHARE_REGIONS_MESSAGE = 'cheminfo:share-regions';
+
+/** The box one part of the page occupies, in the page's own coordinates. */
+export interface ShareRegion {
+  /** The name the part takes in `?hide=`. */
+  part: string;
+  /** Distance from the left edge of the page, in CSS pixels. */
+  x: number;
+  /** Distance from the top edge of the page, in CSS pixels. */
+  y: number;
+  /** Width of the box, in CSS pixels. */
+  width: number;
+  /** Height of the box, in CSS pixels. */
+  height: number;
+}
+
+/**
+ * Whether a message asks this page to report where its parts are.
+ * @param data - What arrived on the message event.
+ * @returns Whether it is the request.
+ */
+export function isShareRegionsRequest(data: unknown): boolean {
+  return messageType(data) === SHARE_REGIONS_REQUEST;
+}
+
+/**
+ * The regions a framed page reported, or `null` for anything else that arrived.
+ *
+ * A region with a name that is not a string, or a side that is not a finite
+ * number, is dropped rather than taken: a dialog drawing a box from a number it
+ * did not check draws it across the whole screen.
+ * @param data - What arrived on the message event.
+ * @returns The regions, or `null` when the message is not one.
+ */
+export function readShareRegions(data: unknown): ShareRegion[] | null {
+  if (messageType(data) !== SHARE_REGIONS_MESSAGE) return null;
+  const { regions } = data as { regions?: unknown };
+  if (!Array.isArray(regions)) return null;
+
+  const read: ShareRegion[] = [];
+  for (const candidate of regions) {
+    const region = readRegion(candidate);
+    if (region !== null) read.push(region);
+  }
+  return read;
+}
+
+function readRegion(candidate: unknown): ShareRegion | null {
+  if (typeof candidate !== 'object' || candidate === null) return null;
+  const { part, x, y, width, height } = candidate as Record<string, unknown>;
+  if (typeof part !== 'string' || part === '') return null;
+  if (
+    !Number.isFinite(x) ||
+    !Number.isFinite(y) ||
+    !Number.isFinite(width) ||
+    !Number.isFinite(height)
+  ) {
+    return null;
+  }
+  return {
+    part,
+    x: x as number,
+    y: y as number,
+    width: width as number,
+    height: height as number,
+  };
+}
+
+function messageType(data: unknown): string | null {
+  if (typeof data !== 'object' || data === null) return null;
+  const { type } = data as { type?: unknown };
+  return typeof type === 'string' ? type : null;
+}

package/src/share/ui/HiddenPartsProvider.tsx

@@ -2,6 +2,8 @@ import type { ReactElement, ReactNode } from 'react';
 import { useMemo } from 'react';
 
 import { HiddenPartsContext } from './hiddenParts.ts';
+import { ShareMarkingContext } from './shareMarking.ts';
+import { useShareRegionReports } from './useShareRegionReports.ts';
 
 export interface HiddenPartsProviderProps {
   /**
@@ -25,10 +27,13 @@ export function HiddenPartsProvider(
 ): ReactElement {
   const { hidden, children } = props;
   const parts = useMemo(() => new Set(hidden), [hidden]);
+  const marking = useShareRegionReports(parts);
 
   return (
     <HiddenPartsContext.Provider value={parts}>
-      {children}
+      <ShareMarkingContext.Provider value={marking}>
+        {children}
+      </ShareMarkingContext.Provider>
     </HiddenPartsContext.Provider>
   );
 }

package/src/share/ui/PagePart.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 
 import { useIsHidden } from './hiddenParts.ts';
+import { useShareMarking } from './shareMarking.ts';
 
 export interface PagePartProps {
   /** The name this region takes in `?hide=`. */
@@ -21,6 +22,16 @@ export interface PagePartProps {
 export function PagePart(props: PagePartProps): ReactNode {
   const { part, children } = props;
   const isHidden = useIsHidden();
+  const marking = useShareMarking();
 
-  return isHidden(part) ? null : children;
+  if (isHidden(part)) return null;
+  if (!marking) return children;
+
+  // `display: contents` so the marker is only a name the dialog can find, and
+  // never a box between the page and the part it holds.
+  return (
+    <div data-share-part={part} style={{ display: 'contents' }}>
+      {children}
+    </div>
+  );
 }

package/src/share/ui/ShareButton.tsx

@@ -2,6 +2,7 @@ import { Button, Icon } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 
 /** How the button is dressed for the bar it sits in. */
 export type ShareButtonVariant = 'nav-link' | 'blueprint';
@@ -61,7 +62,7 @@ export function ShareButton(props: ShareButtonProps): ReactElement {
   if (variant === 'blueprint') {
     return (
       <Button
-        className={className}
+        className={joinClassNames('no-print', className)}
         variant="minimal"
         icon="share"
         text={text}
@@ -75,11 +76,7 @@ export function ShareButton(props: ShareButtonProps): ReactElement {
   return (
     <button
       type="button"
-      className={
-        className === undefined
-          ? 'nav-link nav-link--icon'
-          : `nav-link nav-link--icon ${className}`
-      }
+      className={joinClassNames('nav-link nav-link--icon no-print', className)}
       title={title}
       aria-label={label}
       onClick={onClick}

package/src/share/ui/ShareConfigOptions.tsx

@@ -1,18 +1,14 @@
-import { Checkbox, H6 } from '@blueprintjs/core';
+import { H6 } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
 import type { HideablePart } from '../core/index.ts';
 
 import { SharePartOptions } from './SharePartOptions.tsx';
+import type { SharePartDescriptions } from './SharePartRow.tsx';
+import { SharePartRow } from './SharePartRow.tsx';
 
-const SECTION_STYLE: CSSProperties = { marginBottom: 18 };
-const HINT_STYLE: CSSProperties = {
-  display: 'block',
-  marginLeft: 26,
-  color: 'var(--text-muted, #5b6875)',
-  fontSize: 12,
-};
+const SECTION_STYLE: CSSProperties = { marginBottom: 14 };
 
 export interface ShareConfigOptionsProps {
   /** Whether the draft drops the site chrome. */
@@ -21,35 +17,46 @@ export interface ShareConfigOptionsProps {
   parts: readonly HideablePart[];
   /** The parts the draft switches off. */
   hidden: readonly string[];
+  /** Where each row says what switching it off does. */
+  descriptions: SharePartDescriptions;
   /** Called when the layout is switched. */
   onEmbedChange: (embed: boolean) => void;
   /** Called with the part and whether the link should switch it off. */
   onPartChange: (part: string, hidden: boolean) => void;
+  /** Called with the part the pointer is on, or `null` when it leaves. */
+  onPartPointed: (part: string | null) => void;
 }
 
 /**
- * The boxes of the share dialog: the layout, then one box per part of the page.
+ * The switches of the share dialog: the layout, then one per part of the page.
  * @param props - The draft's layout and parts, and how to change them.
  * @returns The two sections.
  */
 export function ShareConfigOptions(
   props: ShareConfigOptionsProps,
 ): ReactElement {
-  const { embed, parts, hidden, onEmbedChange, onPartChange } = props;
+  const {
+    embed,
+    parts,
+    hidden,
+    descriptions,
+    onEmbedChange,
+    onPartChange,
+    onPartPointed,
+  } = props;
   const t = useChromeT();
 
   return (
     <>
       <section className="share-section" style={SECTION_STYLE}>
         <H6>{t('share.layout')}</H6>
-        <Checkbox
-          checked={embed}
+        <SharePartRow
           label={t('share.embed')}
-          onChange={(event) => {
-            onEmbedChange(event.currentTarget.checked);
-          }}
+          description={t('share.embedHint')}
+          on={embed}
+          descriptions={descriptions}
+          onChange={onEmbedChange}
         />
-        <span style={HINT_STYLE}>{t('share.embedHint')}</span>
       </section>
 
       {parts.length > 0 ? (
@@ -58,7 +65,9 @@ export function ShareConfigOptions(
           <SharePartOptions
             parts={parts}
             hidden={hidden}
+            descriptions={descriptions}
             onChange={onPartChange}
+            onPointed={onPartPointed}
           />
         </section>
       ) : null}