react-cheminfo 0.24.0 → 0.26.0

package/src/i18n/core/chromeCatalog.ts

@@ -0,0 +1,35 @@
+/**
+ * The text this library puts on the page.
+ *
+ * Every site of the family shows the same header, footer, Tools menu, Cite
+ * menu, share dialog and About page, so those words are translated once here
+ * rather than re-typed into eighteen catalogs of their own: one merged pull
+ * request writes every site in a new language.
+ */
+
+import en from '../../locales/en.json' with { type: 'json' };
+
+import { MessageCatalog } from './messageCatalog.ts';
+
+/** The name the page knows the chrome's own catalog by. */
+export const CHROME_CATALOG_ID = 'react-cheminfo';
+
+/** Every key the chrome declares. */
+export type ChromeKey = keyof typeof en;
+
+/**
+ * The chrome's messages. English is part of the page because it is what a
+ * missing message falls back to; the other three arrive as a chunk of their
+ * own, so a site read only in English downloads none of them.
+ */
+export const CHROME_CATALOG = new MessageCatalog<ChromeKey>({
+  id: CHROME_CATALOG_ID,
+  repository: 'cheminfo/react-cheminfo',
+  directory: 'src/locales',
+  source: en,
+  translations: {
+    fr: () => import('../../locales/fr.json', { with: { type: 'json' } }),
+    de: () => import('../../locales/de.json', { with: { type: 'json' } }),
+    es: () => import('../../locales/es.json', { with: { type: 'json' } }),
+  },
+});

package/src/i18n/core/index.ts

@@ -0,0 +1,26 @@
+export type { ChromeKey } from './chromeCatalog.ts';
+export { CHROME_CATALOG, CHROME_CATALOG_ID } from './chromeCatalog.ts';
+export type { Language } from './languages.ts';
+export {
+  DEFAULT_LANGUAGE,
+  LANGUAGES,
+  LANGUAGE_LABELS,
+  isLanguage,
+} from './languages.ts';
+export type {
+  LooseKey,
+  MessageCatalogOptions,
+  MessagesLoader,
+  TranslateOptions,
+} from './messageCatalog.ts';
+export { MessageCatalog } from './messageCatalog.ts';
+export type { MessageValues } from './messageValues.ts';
+export type { MessageSession } from './session.ts';
+export {
+  messageSession,
+  messagesVersion,
+  setMessageSession,
+  subscribeToMessages,
+} from './session.ts';
+export type { LoadedCatalogs } from './translateSetup.ts';
+export { loadCatalogs } from './translateSetup.ts';

package/src/i18n/core/languages.ts

@@ -0,0 +1,46 @@
+/**
+ * The languages the family speaks.
+ *
+ * Four, decided together rather than site by site: a visitor who switches to
+ * German on one tool and follows a link to the next must land in German there
+ * too, and a list that differs between two sites makes that impossible.
+ */
+
+/** Every language a site of the family is written in. */
+export const LANGUAGES = ['en', 'fr', 'de', 'es'] as const;
+
+/** One of {@link LANGUAGES}. */
+export type Language = (typeof LANGUAGES)[number];
+
+/**
+ * The language the catalogs are written in first, and the one every site opens
+ * in: an address naming it carries nothing, and a message a translation does
+ * not hold falls back to it.
+ */
+export const DEFAULT_LANGUAGE: Language = 'en';
+
+/**
+ * What a language switch writes behind each entry.
+ *
+ * A language names itself, in its own words: `Deutsch`, never `German`. A
+ * reader looking for their own language recognises it written their way, and
+ * would have to know English to find it written the other.
+ */
+export const LANGUAGE_LABELS: Record<Language, string> = {
+  en: 'English',
+  fr: 'Français',
+  de: 'Deutsch',
+  es: 'Español',
+};
+
+/**
+ * Whether a string is one of the languages the family speaks.
+ * @param value - Candidate tag, typically read off an address.
+ * @returns True when a catalog can be written in it.
+ */
+export function isLanguage(value: string): value is Language {
+  for (const language of LANGUAGES) {
+    if (language === value) return true;
+  }
+  return false;
+}

package/src/i18n/core/messageCatalog.ts

@@ -0,0 +1,202 @@
+/**
+ * One directory of messages, and the reading of it.
+ *
+ * A catalog is `en.json` — the source of truth — with one file per language
+ * beside it. English is part of the page, because it is what every missing
+ * message falls back to; the others are fetched when a visitor asks for them,
+ * so a site nobody reads in German never downloads the German.
+ *
+ * Only the plain `{name}` argument of ICU MessageFormat is filled here. A
+ * plural or a select needs the formatter itself, which is 40 kB an ordinary
+ * visit must not pay for — `check-messages` refuses one in a catalog, and the
+ * page is written with a key per branch instead.
+ */
+
+import type { CatalogSource, Messages } from '../../translate/core/catalog.ts';
+import { ownMessage } from '../../translate/core/catalog.ts';
+
+import type { Language } from './languages.ts';
+import { DEFAULT_LANGUAGE } from './languages.ts';
+import type { MessageValues } from './messageValues.ts';
+import { messageSession, notifyMessages } from './session.ts';
+
+/** A language's messages, fetched only once a visitor asks for that language. */
+export type MessagesLoader = () => Promise<{ default: Messages }>;
+
+/**
+ * A key the catalog declares, or any other string.
+ *
+ * Many keys are built from the data — `site.surge.tagline`, `element.Fe.name`
+ * — so a row added before the catalogs have caught up must read as itself
+ * rather than fail to compile.
+ */
+export type LooseKey<TKey extends string> =
+  TKey | (string & Record<never, never>);
+
+/** How a key is resolved when no catalog carries it, and with what. */
+export interface TranslateOptions {
+  /**
+   * What to answer when neither the language nor English carries the key.
+   * @default the key itself
+   */
+  fallback?: string;
+  /**
+   * What each `{placeholder}` of the message stands for.
+   * @default undefined
+   */
+  values?: MessageValues;
+}
+
+/** How a catalog is declared. */
+export interface MessageCatalogOptions<TKey extends string> {
+  /**
+   * The name the page knows the catalog by, unique on the page, e.g.
+   * `react-cheminfo` or `surge.cheminfo.org`.
+   */
+  id: string;
+  /** The GitHub repository the files live in, written `owner/repo`. */
+  repository: string;
+  /**
+   * The directory holding the locale files, relative to the repository root,
+   * e.g. `src/locales`.
+   */
+  directory: string;
+  /** The English messages, which are the keys the catalog declares. */
+  source: Record<TKey, string>;
+  /**
+   * The other languages: the messages themselves, or the import that fetches
+   * them. A language left out simply reads as English.
+   * @default {}
+   */
+  translations?: Partial<Record<Language, Messages | MessagesLoader>>;
+}
+
+/**
+ * The messages of one repository, read in whichever language the page is
+ * written in.
+ */
+export class MessageCatalog<TKey extends string = string> {
+  /** The name the page knows this catalog by. */
+  public readonly id: string;
+  /** What a translator's session and the overlay need to place an edit. */
+  public readonly source: CatalogSource;
+
+  readonly #loaded = new Map<Language, Messages>();
+  readonly #loaders = new Map<Language, MessagesLoader>();
+  readonly #pending = new Map<Language, Promise<Messages>>();
+
+  /**
+   * Declare a catalog.
+   * @param options - See {@link MessageCatalogOptions}.
+   */
+  public constructor(options: MessageCatalogOptions<TKey>) {
+    const { id, repository, directory, source, translations = {} } = options;
+    this.id = id;
+    this.source = { id, repository, directory, messages: source };
+    this.#loaded.set(DEFAULT_LANGUAGE, source);
+    for (const [language, messages] of Object.entries(translations)) {
+      if (messages === undefined) continue;
+      if (typeof messages === 'function') {
+        this.#loaders.set(language as Language, messages);
+      } else {
+        this.#loaded.set(language as Language, messages);
+      }
+    }
+  }
+
+  /**
+   * The languages this catalog carries, whether or not they are in memory.
+   * @returns The languages, English first.
+   */
+  public get languages(): Language[] {
+    return [...new Set([...this.#loaded.keys(), ...this.#loaders.keys()])];
+  }
+
+  /**
+   * The text a key carries in one language.
+   * @param key - Key to read.
+   * @param language - Language to read it in.
+   * @param options - See {@link TranslateOptions}.
+   * @returns The text.
+   */
+  public translate(
+    key: LooseKey<TKey>,
+    language: Language,
+    options: TranslateOptions = {},
+  ): string {
+    const { fallback = key, values } = options;
+    const english = this.source.messages;
+    const session = messageSession();
+    if (session !== null) {
+      // A key the catalog does not declare is not the translator's to edit:
+      // marking it would offer them a message that lives nowhere.
+      if (ownMessage(english, key) === undefined) return fill(fallback, values);
+      return session.format(this.id, key, values);
+    }
+    const translated = this.#loaded.get(language);
+    const message =
+      (translated === undefined ? undefined : ownMessage(translated, key)) ??
+      ownMessage(english, key) ??
+      fallback;
+    return fill(message, values);
+  }
+
+  /**
+   * The messages of a language, once they are in memory.
+   * @param language - Language asked for.
+   * @returns The messages, or an empty catalog while they are still coming.
+   */
+  public messages(language: Language): Messages {
+    return this.#loaded.get(language) ?? {};
+  }
+
+  /**
+   * Fetch a language's messages, if they are not in memory already.
+   * @param language - Language to read next.
+   * @returns Its messages.
+   */
+  public async load(language: Language): Promise<Messages> {
+    const loaded = this.#loaded.get(language);
+    if (loaded !== undefined) return loaded;
+    const pending = this.#pending.get(language);
+    if (pending !== undefined) return pending;
+    const loader = this.#loaders.get(language);
+    if (loader === undefined) return {};
+    const fetching = loader().then(
+      (module) => {
+        this.#loaded.set(language, module.default);
+        this.#pending.delete(language);
+        notifyMessages();
+        return module.default;
+      },
+      () => {
+        // A language that cannot be fetched is a page in English, never a
+        // page of raw keys: forget the attempt so a later render retries.
+        this.#pending.delete(language);
+        return {};
+      },
+    );
+    this.#pending.set(language, fetching);
+    return fetching;
+  }
+
+  /**
+   * Start fetching a language without waiting for it. Safe to call on every
+   * render: a language already in memory, or already on its way, costs
+   * nothing.
+   * @param language - Language the page is about to be written in.
+   */
+  public prefetch(language: Language): void {
+    if (this.#loaded.has(language) || this.#pending.has(language)) return;
+    void this.load(language);
+  }
+}
+
+const PLACEHOLDER = /\{(?<name>\w+)\}/g;
+
+function fill(message: string, values: MessageValues | undefined): string {
+  if (values === undefined) return message;
+  return message.replaceAll(PLACEHOLDER, (match, name: string) =>
+    Object.hasOwn(values, name) ? String(values[name]) : match,
+  );
+}

package/src/i18n/core/messageValues.ts

@@ -0,0 +1,2 @@
+/** What a message's `{placeholder}`s stand for. */
+export type MessageValues = Record<string, string | number>;

package/src/i18n/core/session.ts

@@ -0,0 +1,82 @@
+/**
+ * Where the page formats its messages from, and who is told when that changes.
+ *
+ * Ordinarily a message is read straight out of a catalog. While a translator
+ * has the page open, every message goes through their session instead — marked
+ * invisibly so the overlay can find it in the DOM, and answered with whatever
+ * they have typed rather than with what was published. Both the session and a
+ * language arriving late are changes the page has to redraw for, so they share
+ * one version counter and one set of listeners.
+ */
+
+import type { MessageValues } from './messageValues.ts';
+
+/**
+ * What a page in translate mode formats through — satisfied by
+ * `TranslateSession` from `react-cheminfo/translate`, which is never imported
+ * here: an ordinary visit must not load the ICU formatter behind it.
+ */
+export interface MessageSession {
+  /** The message of a catalog, formatted and marked. */
+  format: (catalogId: string, key: string, values?: MessageValues) => string;
+  /** Be told whenever an edit is typed; returns the function that stops it. */
+  subscribe?: (listener: () => void) => () => void;
+}
+
+let session: MessageSession | null = null;
+let stopListening: (() => void) | null = null;
+let version = 0;
+const listeners = new Set<() => void>();
+
+/**
+ * Format every message through a translator's session from now on.
+ *
+ * While one is set it is the session's locale the page is written in, not the
+ * visitor's preference, and every message carries the marker the overlay finds
+ * it by.
+ * @param active - The session, or `null` to go back to the catalogs.
+ */
+export function setMessageSession(active: MessageSession | null): void {
+  stopListening?.();
+  stopListening = null;
+  session = active;
+  if (active?.subscribe !== undefined) {
+    stopListening = active.subscribe(notifyMessages);
+  }
+  notifyMessages();
+}
+
+/**
+ * The session the page formats through, if a translator has it open.
+ * @returns The session, or `null`.
+ */
+export function messageSession(): MessageSession | null {
+  return session;
+}
+
+/**
+ * How many times the text of the page has changed — a session set or dropped,
+ * an edit typed, a language finished loading.
+ * @returns The count, which only ever grows.
+ */
+export function messagesVersion(): number {
+  return version;
+}
+
+/**
+ * Be told whenever the text of the page changes.
+ * @param listener - Called after each change.
+ * @returns The function that stops it.
+ */
+export function subscribeToMessages(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Say that the text of the page has changed. Never part of the public API. */
+export function notifyMessages(): void {
+  version++;
+  for (const listener of listeners) listener();
+}

package/src/i18n/core/translateSetup.ts

@@ -0,0 +1,47 @@
+/**
+ * Handing a page's catalogs to a translator.
+ *
+ * `startTranslating` wants the catalogs and, beside them, whatever of the
+ * target language is already published — that is what tells the overlay which
+ * messages are still missing. The published messages of a language are exactly
+ * what a catalog fetches on demand, so they are gathered here rather than
+ * re-imported by every site.
+ */
+
+import type { CatalogSource, Messages } from '../../translate/core/catalog.ts';
+
+import { isLanguage } from './languages.ts';
+import type { MessageCatalog } from './messageCatalog.ts';
+
+/** What `startTranslating` is handed. */
+export interface LoadedCatalogs {
+  /** The catalogs, as the session registers them. */
+  catalogs: CatalogSource[];
+  /** What is already published in the locale, by catalog id. */
+  translations: Record<string, Messages>;
+}
+
+/**
+ * Fetch what each catalog already publishes in a locale.
+ * @param catalogs - The catalogs the page renders from.
+ * @param locale - The locale being translated into, which may well be one the
+ * family does not speak yet — then nothing is published and every message is
+ * offered as missing.
+ * @returns See {@link LoadedCatalogs}.
+ */
+export async function loadCatalogs(
+  catalogs: ReadonlyArray<MessageCatalog<string>>,
+  locale: string,
+): Promise<LoadedCatalogs> {
+  const language = isLanguage(locale) ? locale : undefined;
+  const translations: Record<string, Messages> = {};
+  if (language !== undefined) {
+    const loaded = await Promise.all(
+      catalogs.map(async (catalog) => catalog.load(language)),
+    );
+    for (const [index, catalog] of catalogs.entries()) {
+      translations[catalog.id] = loaded[index] ?? {};
+    }
+  }
+  return { catalogs: catalogs.map((catalog) => catalog.source), translations };
+}

package/src/i18n/ui/LanguageSelect.tsx

@@ -0,0 +1,72 @@
+import type { ReactElement } from 'react';
+
+import type { HeaderToggleOption } from '../../chrome/ui/HeaderToggle.tsx';
+import { HeaderToggle } from '../../chrome/ui/HeaderToggle.tsx';
+import type { Language } from '../core/languages.ts';
+import { LANGUAGES, LANGUAGE_LABELS } from '../core/languages.ts';
+
+import { useChromeT } from './useT.ts';
+
+/** Props of {@link LanguageSelect}. */
+export interface LanguageSelectProps {
+  /** The language the site is written in. */
+  value: Language;
+  /** Called with the language picked. */
+  onChange: (language: Language) => void;
+  /**
+   * The languages on offer, for a site that is not written in all four yet.
+   * @default LANGUAGES
+   */
+  languages?: readonly Language[];
+  /**
+   * Whether the bar has run out of room, so the row collapses to the language
+   * in force and a click advances to the next.
+   * @default false
+   */
+  compact?: boolean;
+  /**
+   * `data-testid` of the row; each button carries it suffixed by its tag.
+   * @default 'language-select'
+   */
+  testId?: string;
+}
+
+/**
+ * The language switch of the site header: the tags themselves, the one in
+ * force pressed.
+ *
+ * A language names itself — `FR` in the bar, `Français` behind it — because a
+ * reader looking for their own language would have to know English to find it
+ * written any other way.
+ * @param props - See {@link LanguageSelectProps}.
+ * @returns The row.
+ */
+export function LanguageSelect(props: LanguageSelectProps): ReactElement {
+  const {
+    value,
+    onChange,
+    languages = LANGUAGES,
+    compact = false,
+    testId = 'language-select',
+  } = props;
+  const t = useChromeT();
+
+  return (
+    <HeaderToggle
+      label={t('language.label')}
+      options={languages.map(toOption)}
+      value={value}
+      onChange={onChange}
+      compact={compact}
+      testId={testId}
+    />
+  );
+}
+
+function toOption(language: Language): HeaderToggleOption<Language> {
+  return {
+    value: language,
+    label: language.toUpperCase(),
+    title: LANGUAGE_LABELS[language],
+  };
+}

package/src/i18n/ui/index.ts

@@ -0,0 +1,9 @@
+export type { LanguageSelectProps } from './LanguageSelect.tsx';
+export { LanguageSelect } from './LanguageSelect.tsx';
+export {
+  useIsTranslating,
+  useLanguage,
+  useMessagesVersion,
+} from './useLanguage.ts';
+export type { Translate } from './useT.ts';
+export { translateMessage, useChromeT, useT } from './useT.ts';

package/src/i18n/ui/useLanguage.ts

@@ -0,0 +1,48 @@
+import { useSyncExternalStore } from 'react';
+
+import { useSiteLanguage } from '../../language/ui/siteLanguageContext.ts';
+import type { Language } from '../core/languages.ts';
+import { DEFAULT_LANGUAGE, isLanguage } from '../core/languages.ts';
+import {
+  messageSession,
+  messagesVersion,
+  subscribeToMessages,
+} from '../core/session.ts';
+
+/**
+ * The language the page is written in.
+ *
+ * It is what the site declared with `SiteLanguage`, or what the address names
+ * when the site declared nothing — the same value every link out of the page
+ * carries, so the chrome is never written in a language the links deny.
+ * @returns The language.
+ */
+export function useLanguage(): Language {
+  const declared = useSiteLanguage();
+  return declared !== undefined && isLanguage(declared)
+    ? declared
+    : DEFAULT_LANGUAGE;
+}
+
+/**
+ * Redraw whenever the text of the page changes — a language finished loading,
+ * a translator typed an edit, a session was set or dropped.
+ * @returns The version the page was drawn at.
+ */
+export function useMessagesVersion(): number {
+  return useSyncExternalStore(
+    subscribeToMessages,
+    messagesVersion,
+    messagesVersion,
+  );
+}
+
+/**
+ * Whether a translator has the page open, in which case the language switch
+ * says nothing about what is on show.
+ * @returns True in translate mode.
+ */
+export function useIsTranslating(): boolean {
+  useMessagesVersion();
+  return messageSession() !== null;
+}

package/src/i18n/ui/useT.ts

@@ -0,0 +1,90 @@
+import type { ChromeKey } from '../core/chromeCatalog.ts';
+import { CHROME_CATALOG } from '../core/chromeCatalog.ts';
+import type {
+  Language,
+  LooseKey,
+  MessageValues,
+  TranslateOptions,
+} from '../core/index.ts';
+import type { MessageCatalog } from '../core/messageCatalog.ts';
+
+import { useLanguage, useMessagesVersion } from './useLanguage.ts';
+
+/**
+ * What a component reads its text with.
+ *
+ * `t(key)` is a key the catalog declares, checked at compile time.
+ * `t.or(key, fallback)` is a key built from the data — a site's id, an
+ * element's symbol — which the catalog may not have caught up with yet; it
+ * reads as the fallback rather than as a raw key.
+ */
+export type Translate<TKey extends string> = ((
+  key: LooseKey<TKey>,
+  values?: MessageValues,
+) => string) & {
+  or: (key: string, fallback: string, values?: MessageValues) => string;
+};
+
+/**
+ * The formatter of a catalog's text, in the language the page is written in.
+ *
+ * It is meant to be called while rendering, never kept in a module constant:
+ * the language and a translator's edits both change under the page, and only a
+ * render picks them up.
+ * @param catalog - The catalog to read, typed by its English keys.
+ * @returns See {@link Translate}.
+ */
+export function useT<TKey extends string>(
+  catalog: MessageCatalog<TKey>,
+): Translate<TKey> {
+  const language = useLanguage();
+  useMessagesVersion();
+  catalog.prefetch(language);
+  return translator(catalog, language);
+}
+
+// Built outside the hook, because the `or` form is a property of the function
+// itself and a render may not write to a value it has just read.
+function translator<TKey extends string>(
+  catalog: MessageCatalog<TKey>,
+  language: Language,
+): Translate<TKey> {
+  const translate = (key: LooseKey<TKey>, values?: MessageValues) =>
+    catalog.translate(key, language, { values });
+  translate.or = (key: string, fallback: string, values?: MessageValues) =>
+    catalog.translate(key, language, { fallback, values });
+  return translate;
+}
+
+/**
+ * The formatter of this library's own text — the header, the Tools menu, the
+ * share dialog, the About page.
+ *
+ * A site reads it for a word it shows beside the chrome's own, so `Share` and
+ * `Cite` are written the same way everywhere.
+ * @returns `t(key, values)`, typed by the chrome's English catalog.
+ */
+export function useChromeT(): Translate<ChromeKey> {
+  return useT(CHROME_CATALOG);
+}
+
+/**
+ * One message of a catalog, outside a component.
+ *
+ * Only for the rare place a hook cannot go — a label computed in a module
+ * helper, a message thrown from a worker. A component uses {@link useT}, which
+ * redraws when the language does.
+ * @param catalog - The catalog to read.
+ * @param key - Key to read.
+ * @param language - Language to read it in.
+ * @param options - See `TranslateOptions`.
+ * @returns The text.
+ */
+export function translateMessage<TKey extends string>(
+  catalog: MessageCatalog<TKey>,
+  key: LooseKey<TKey>,
+  language: Language,
+  options?: TranslateOptions,
+): string {
+  return catalog.translate(key, language, options);
+}