react-cheminfo 0.53.0 → 0.55.0

package/src/contact/ui/ContactButton.tsx

@@ -0,0 +1,74 @@
+import type { ReactElement } from 'react';
+
+import { NavLink } from '../../chrome/ui/NavLink.tsx';
+import { useLanguage } from '../../i18n/ui/useLanguage.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { contactFormUrl, contactUrl } from '../core/contactUrl.ts';
+
+/** What the Contact entry of a header needs. */
+export interface ContactButtonProps {
+  /** The site the reader writes about, written into the form. */
+  siteId: string;
+  /**
+   * Address of the form, with `{site}` and `{page}` where they are written.
+   * @default the family's form in the language of the page (`CONTACT_FORM_URLS`)
+   */
+  formUrl?: string;
+  /**
+   * The page the reader is on, written into the form.
+   * @default the address of the current page
+   */
+  page?: string;
+  /**
+   * What the entry reads. In a compact bar it is not written, but it stays what
+   * the pointer and a screen reader are told.
+   * @default the chrome's own word for it, in the language of the page
+   */
+  label?: string;
+  /**
+   * What the pointer is told.
+   * @default the chrome's own sentence, in the language of the page
+   */
+  title?: string;
+  /**
+   * Class names added after the component's own.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The Contact entry of a site header: it opens the family's contact form in a new tab,
+ * with the site and the page already filled in, so the reader only writes the message.
+ * The form is opened, never embedded, so nothing is loaded from it before the click.
+ * @param props - The site, and the form it opens.
+ * @returns The entry, or nothing while no form address is set.
+ */
+export function ContactButton(props: ContactButtonProps): ReactElement | null {
+  const {
+    siteId,
+    page = globalThis.location?.href ?? '',
+    label,
+    title,
+    className,
+  } = props;
+  const t = useChromeT();
+  const language = useLanguage();
+  const formUrl = props.formUrl ?? contactFormUrl(language);
+
+  if (formUrl === '') return null;
+
+  return (
+    <NavLink
+      item={{
+        id: 'contact',
+        label: label ?? t('chrome.contact'),
+        icon: 'chat',
+        href: contactUrl(formUrl, { site: siteId, page }),
+        external: true,
+        title: title ?? t('chrome.contactTitle'),
+      }}
+      className={className}
+    />
+  );
+}

package/src/contact/ui/index.ts

@@ -0,0 +1,2 @@
+export type { ContactButtonProps } from './ContactButton.tsx';
+export { ContactButton } from './ContactButton.tsx';

package/src/core.ts

@@ -5,6 +5,7 @@ export * from './chart/core/index.ts';
 export * from './citation/core/index.ts';
 export * from './clipboard/core/index.ts';
 export * from './color/core/index.ts';
+export * from './contact/core/index.ts';
 export * from './credits/core/index.ts';
 export * from './delimited/core/index.ts';
 export * from './download/core/index.ts';

package/src/i18n/core/index.ts

@@ -15,6 +15,8 @@ export type {
 } from './messageCatalog.ts';
 export { MessageCatalog } from './messageCatalog.ts';
 export type { MessageValues } from './messageValues.ts';
+export type { Translate } from './translate.ts';
+export { catalogTranslate } from './translate.ts';
 export type { ProsePiece } from './prose.ts';
 export { splitProse } from './prose.ts';
 export type { MessageSession } from './session.ts';

package/src/i18n/core/messageCatalog.ts

@@ -141,6 +141,19 @@ export class MessageCatalog<TKey extends string = string> {
     return fill(message, values);
   }
 
+  /**
+   * Whether the catalog declares a key at all.
+   *
+   * English is the list of keys, so this is what a loop walking a numbered
+   * family of messages — `how.limits.p1`, `p2`, … — stops on, and what tells a
+   * page a section was never written from one left untranslated.
+   * @param key - Key to look for.
+   * @returns True when English carries it.
+   */
+  public declares(key: string): boolean {
+    return ownMessage(this.source.messages, key) !== undefined;
+  }
+
   /**
    * The messages of a language, once they are in memory.
    * @param language - Language asked for.

package/src/i18n/core/translate.ts

@@ -0,0 +1,51 @@
+/**
+ * The formatter a catalog's text is read through, outside React.
+ *
+ * `useT` is this function with the page's language and a redraw wired to it;
+ * the build and a site's own tests need the same shape without either, so it
+ * lives here rather than in the hook. A site never writes its own: four of
+ * them had, each with a slightly different fallback.
+ */
+
+import type { Language } from './languages.ts';
+import type { LooseKey, MessageCatalog } from './messageCatalog.ts';
+import type { MessageValues } from './messageValues.ts';
+
+/**
+ * What text is read 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;
+};
+
+/**
+ * A catalog's formatter, in one language.
+ *
+ * In a component this is `useT`, which also redraws when the language or a
+ * translator's edit changes it. Here it is for the places a hook cannot go:
+ * the build writing a head per address per language, a test asserting on the
+ * text a page shows, a label computed in a module helper.
+ * @param catalog - The catalog to read, typed by its English keys.
+ * @param language - The language to read it in.
+ * @returns See {@link Translate}.
+ */
+export function catalogTranslate<TKey extends string>(
+  catalog: MessageCatalog<TKey>,
+  language: Language,
+): Translate<TKey> {
+  // `or` is a property of the function itself, so the two are built together
+  // rather than assigned onto a value a render may already have read.
+  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;
+}

package/src/i18n/ui/useT.ts

@@ -3,27 +3,17 @@ import { CHROME_CATALOG } from '../core/chromeCatalog.ts';
 import type {
   Language,
   LooseKey,
-  MessageValues,
+  Translate,
   TranslateOptions,
 } from '../core/index.ts';
+import { catalogTranslate } 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's own shape belongs to the catalog, not to the hook, and a site
+// reads it from either entry point.
+export type { Translate } from '../core/index.ts';
 
 /**
  * The formatter of a catalog's text, in the language the page is written in.
@@ -40,20 +30,7 @@ export function useT<TKey extends string>(
   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;
+  return catalogTranslate(catalog, language);
 }
 
 /**

package/src/i18n/vite/index.ts

@@ -0,0 +1,5 @@
+export type {
+  LocaleCatalogOptions,
+  LocaleCatalogSource,
+} from './localeCatalog.ts';
+export { readLocaleCatalog } from './localeCatalog.ts';

package/src/i18n/vite/localeCatalog.ts

@@ -0,0 +1,121 @@
+/**
+ * A site's catalogs as the build reads them: all of them, off disk, at once.
+ *
+ * The page and the build want opposite things from the same files. A browser
+ * fetches one language — the one being read — so `en.json` is part of the
+ * bundle and the others are `import()`ed when a visitor asks, which is what
+ * keeps a site nobody reads in German from downloading the German. The build
+ * writes a head per address per language in one pass, so it wants every
+ * language, synchronously, before the first route table is asked for.
+ *
+ * Reading them rather than fetching them is what makes that possible. The
+ * page's loaders are written bare — `import('../locales/fr.json')` with no
+ * `with { type: 'json' }` — because the dev server serves a JSON file as a
+ * JavaScript module and a browser refuses a chunk it was promised JSON for.
+ * Node demands the attribute, so it cannot run those loaders: a build that
+ * awaited them had to be async and still only worked by keeping a second,
+ * eagerly imported copy of every catalog beside the first. `readFileSync` has
+ * no attribute, so there is nothing to work around.
+ *
+ * The identity comes from the page's own catalog, never re-typed here: pass
+ * `SITE_CATALOG.source` and the two provably name the same files.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Language } from '../core/index.ts';
+import { DEFAULT_LANGUAGE, LANGUAGES, MessageCatalog } from '../core/index.ts';
+
+/**
+ * Which catalog to read, which is the page catalog's own `source`.
+ *
+ * `MessageCatalog` publishes it for the translate overlay, and it already
+ * carries the three things a reader needs. Hand it over rather than writing
+ * them twice: a build that names its own directory is a build that can come to
+ * disagree with the page about which files the site is translated in.
+ */
+export interface LocaleCatalogSource {
+  /**
+   * The name the page knows the catalog by, which is the site's host, e.g.
+   * `surge.cheminfo.org`. A translator's edit is routed back to the right
+   * repository with it, so the build and the page must agree on it.
+   */
+  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. */
+  directory: string;
+}
+
+/** Where the directory is looked for. */
+export interface LocaleCatalogOptions {
+  /**
+   * What the source's relative `directory` is resolved against. The default is
+   * the working directory, which is the repository root for both callers: a
+   * Vite config and a vitest run.
+   * @default process.cwd()
+   */
+  root?: string;
+}
+
+/**
+ * Every language a site is written in, read off disk into one catalog.
+ *
+ * For the build and for a site's own tests, never for the page: it reads the
+ * filesystem, and the translations it holds are tens of kilobytes a first
+ * visit must not pay for. Read one language out of it with `catalogTranslate`.
+ *
+ * A language whose file is absent is left out, which the catalog already reads
+ * as English — a half-translated site serves the pages it has rather than
+ * failing the build. A missing English file is a misconfiguration and throws:
+ * every key and every fallback is declared there.
+ * @param source - The page catalog's own `source`. See {@link LocaleCatalogSource}.
+ * @param options - See {@link LocaleCatalogOptions}.
+ * @returns The catalog, every language it carries already in memory.
+ */
+export function readLocaleCatalog<TKey extends string = string>(
+  source: LocaleCatalogSource,
+  options: LocaleCatalogOptions = {},
+): MessageCatalog<TKey> {
+  const { id, repository, directory } = source;
+  const folder = resolve(options.root ?? process.cwd(), directory);
+  const english = readMessages(folder, DEFAULT_LANGUAGE);
+  if (english === undefined) {
+    throw new Error(
+      `no ${DEFAULT_LANGUAGE}.json in ${folder}: a catalog declares its keys and its fallbacks there`,
+    );
+  }
+  const translations: Partial<Record<Language, Record<string, string>>> = {};
+  for (const language of LANGUAGES) {
+    if (language === DEFAULT_LANGUAGE) continue;
+    const messages = readMessages(folder, language);
+    if (messages !== undefined) translations[language] = messages;
+  }
+  return new MessageCatalog<TKey>({
+    id,
+    repository,
+    directory,
+    source: english,
+    translations,
+  });
+}
+
+/**
+ * One language's messages, read off disk.
+ * @param folder - The resolved directory holding the locale files.
+ * @param language - The language whose file to read.
+ * @returns Its messages, or `undefined` when the site does not carry it.
+ */
+function readMessages(
+  folder: string,
+  language: Language,
+): Record<string, string> | undefined {
+  let text: string;
+  try {
+    text = readFileSync(join(folder, `${language}.json`), 'utf8');
+  } catch {
+    return undefined;
+  }
+  return JSON.parse(text) as Record<string, string>;
+}

package/src/locales/de.json

@@ -3,6 +3,8 @@
   "chrome.pages": "Seiten",
   "chrome.about": "Über",
   "chrome.aboutTitle": "Was diese Seite ist, worauf sie aufbaut und wie man sie zitiert",
+  "chrome.contact": "Kontakt",
+  "chrome.contactTitle": "Eine Frage, ein Problem, eine Idee? Schreiben Sie uns",
   "account.signIn": "Anmelden",
   "account.signOut": "Abmelden",
   "account.signedInAs": "Angemeldet als {name}",

package/src/locales/en.json

@@ -3,6 +3,8 @@
   "chrome.pages": "Pages",
   "chrome.about": "About",
   "chrome.aboutTitle": "What this site is, what it is built on, and how to cite it",
+  "chrome.contact": "Contact",
+  "chrome.contactTitle": "A question, a problem or an idea? Write to us",
   "account.signIn": "Sign in",
   "account.signOut": "Sign out",
   "account.signedInAs": "Signed in as {name}",

package/src/locales/es.json

@@ -3,6 +3,8 @@
   "chrome.pages": "Páginas",
   "chrome.about": "Acerca de",
   "chrome.aboutTitle": "Qué es este sitio, en qué se basa y cómo citarlo",
+  "chrome.contact": "Contacto",
+  "chrome.contactTitle": "¿Una pregunta, un problema, una idea? Escríbanos",
   "account.signIn": "Iniciar sesión",
   "account.signOut": "Cerrar sesión",
   "account.signedInAs": "Sesión iniciada como {name}",

package/src/locales/fr.json

@@ -3,6 +3,8 @@
   "chrome.pages": "Pages",
   "chrome.about": "À propos",
   "chrome.aboutTitle": "Ce qu'est ce site, sur quoi il est bâti et comment le citer",
+  "chrome.contact": "Contact",
+  "chrome.contactTitle": "Une question, un problème, une idée ? Écrivez-nous",
   "account.signIn": "Se connecter",
   "account.signOut": "Se déconnecter",
   "account.signedInAs": "Connecté comme {name}",

package/src/locales/it.json

@@ -3,6 +3,8 @@
   "chrome.pages": "Pagine",
   "chrome.about": "Informazioni",
   "chrome.aboutTitle": "Cosa è questo sito, su cosa si basa e come citarlo",
+  "chrome.contact": "Contatto",
+  "chrome.contactTitle": "Una domanda, un problema, un'idea? Scriveteci",
   "account.signIn": "Accedi",
   "account.signOut": "Esci",
   "account.signedInAs": "Accesso effettuato come {name}",

package/src/ui.ts

@@ -4,6 +4,7 @@ export * from './capsule/ui/index.ts';
 export * from './chart/ui/index.ts';
 export * from './chrome/ui/index.ts';
 export * from './citation/ui/index.ts';
+export * from './contact/ui/index.ts';
 export * from './clipboard/ui/index.ts';
 export * from './color/ui/index.ts';
 export * from './confirm/ui/index.ts';

package/src/vite.ts

@@ -1,3 +1,4 @@
 export * from './build/vite/index.ts';
+export * from './i18n/vite/index.ts';
 export * from './seo/vite/index.ts';
 export * from './slides/vite/index.ts';

package/styles/chrome.css

@@ -192,6 +192,27 @@ button {
   padding: 0.3rem 0.5rem;
 }
 
+/* Every utility of the bar takes the same box, whatever it is built on — a link,
+   or a Blueprint button opening a menu — so the marks stand evenly spaced: the
+   same padding, no minimum width, no room kept beside the glyph for the hidden
+   label, and one glyph size. */
+.app-header-actions .bp6-button:has(> .bp6-icon:not(.bp6-icon-caret-down)) {
+  min-width: 0;
+  padding: 0.3rem 0.5rem;
+}
+
+.app-header-actions
+  .bp6-button:has(> .bp6-icon:not(.bp6-icon-caret-down))
+  > .bp6-icon {
+  margin: 0;
+}
+
+.app-header-actions .nav-link--icon > .bp6-icon > svg,
+.app-header-actions .bp6-button > .bp6-icon > svg {
+  width: 16px;
+  height: 16px;
+}
+
 /* A setting the bar shows as its own values — the language, the scale a
    temperature is read on — the one in force pressed. The values carry no
    glyph, which is what keeps them written where a utility is only its mark. */