react-cheminfo 0.25.0 → 0.27.0

package/src/deploy/core/types.ts

@@ -9,7 +9,8 @@ export type DeployProblemKind =
   | 'floating-sidecar'
   | 'missing-healthcheck'
   | 'missing-env-example'
-  | 'missing-deploy-ignore';
+  | 'missing-deploy-ignore'
+  | 'cacheable-page';
 
 /** One way a repository would fail, or silently mis-deploy, on the server. */
 export interface DeployProblem {

package/src/download/ui/FigureDownload.tsx

@@ -3,6 +3,7 @@ import { PopoverNext } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 import { useState } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { OverlayIconButton } from '../../overlay/ui/OverlayIconButton.tsx';
 import type { FigureFormat } from '../core/downloadFigure.ts';
 import { downloadFigure } from '../core/downloadFigure.ts';
@@ -50,12 +51,12 @@ export interface FigureDownloadProps {
   background?: string;
   /**
    * What the glyph is called, for the pointer and for a screen reader.
-   * @default 'Save this figure'
+   * @default the chrome's own line, in the language of the page
    */
   label?: string;
   /**
    * What the panel behind it is called.
-   * @default 'Save figure'
+   * @default the chrome's own line, in the language of the page
    */
   title?: string;
   /**
@@ -92,9 +93,10 @@ export interface FigureDownloadProps {
 export function FigureDownload(props: FigureDownloadProps): ReactElement {
   const { targetId, fileName, background, scales = FIGURE_SCALES } = props;
   const { defaultFormat = 'png', defaultScale = DEFAULT_FIGURE_SCALE } = props;
-  const { label = 'Save this figure', title = 'Save figure' } = props;
+  const { label, title } = props;
   const { icon = 'download', testId } = props;
 
+  const t = useChromeT();
   const [open, setOpen] = useState(false);
   const [format, setFormat] = useState<FigureFormat>(defaultFormat);
   const [scale, setScale] = useState(defaultScale);
@@ -132,7 +134,7 @@ export function FigureDownload(props: FigureDownloadProps): ReactElement {
       onInteraction={interact}
       content={
         <FigureDownloadPanel
-          title={title}
+          title={title ?? t('download.saveFigure')}
           format={format}
           scale={scale}
           scales={scales}
@@ -147,7 +149,7 @@ export function FigureDownload(props: FigureDownloadProps): ReactElement {
     >
       <OverlayIconButton
         icon={icon}
-        label={label}
+        label={label ?? t('download.saveThisFigure')}
         value={format.toUpperCase()}
         active={open}
         testId={testId}

package/src/download/ui/FigureDownloadPanel.tsx

@@ -1,6 +1,8 @@
 import type { ReactElement } from 'react';
 
-import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { Translate } from '../../i18n/ui/useT.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { OverlayAction } from '../../overlay/ui/OverlayAction.tsx';
 import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
 import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
@@ -66,16 +68,17 @@ export function FigureDownloadPanel(
 ): ReactElement {
   const { title, format, scale, scales, size, failure, saving } = props;
   const { onFormatChange, onScaleChange, onSave, rasterSvg = false } = props;
+  const t = useChromeT();
 
   const vector = format === 'svg' && !rasterSvg;
 
   return (
     <OverlayPanel
       title={title}
-      hint={hintOf(format, size, scale, failure, rasterSvg)}
+      hint={hintOf(format, size, scale, failure, rasterSvg, t)}
       actions={
         <OverlayAction
-          text="Save"
+          text={t('download.save')}
           icon="download"
           intent="primary"
           disabled={saving || size === null}
@@ -84,15 +87,25 @@ export function FigureDownloadPanel(
       }
     >
       <OverlaySegmented<FigureFormat>
-        label="Format"
-        help={FORMAT_HELP}
+        label={t('download.format')}
+        help={{
+          title: t('download.format'),
+          body: t('download.formatHelp'),
+        }}
         value={format}
         options={FORMAT_CHOICES}
         onChange={onFormatChange}
       />
       <OverlaySegmented
-        label="Resolution"
-        help={RESOLUTION_HELP}
+        label={t('download.resolution')}
+        help={{
+          title: t('download.resolution'),
+          body: t('download.resolutionHelp'),
+          example: {
+            code: '2×',
+            note: t('download.resolutionExample'),
+          },
+        }}
         value={String(scale)}
         options={scaleChoices(scales, size)}
         disabled={vector}
@@ -108,20 +121,6 @@ const FORMAT_CHOICES: ReadonlyArray<OverlayOption<FigureFormat>> = [
   { value: 'svg', label: 'SVG' },
 ];
 
-const FORMAT_HELP: HelpContent = {
-  title: 'Format',
-  body: 'A PNG is a picture of the figure, which is what a slide, a chat window or an issue accepts. An SVG is the figure itself: every line stays sharp however far it is enlarged, and it can still be edited afterwards.',
-};
-
-const RESOLUTION_HELP: HelpContent = {
-  title: 'Resolution',
-  body: 'How many pixels are painted for each pixel of the figure on screen. Two is right for a slide, three or four for print. An SVG carries no resolution of its own, so it is saved sharp at every size.',
-  example: {
-    code: '2×',
-    note: 'A figure 640 pixels wide on screen is saved 1280 pixels wide.',
-  },
-};
-
 /**
  * The multiples offered, each saying what it would actually produce.
  *
@@ -155,6 +154,8 @@ function scaleChoices(
  * @param scale - The multiple it is painted at.
  * @param failure - What went wrong last time, if anything.
  * @param rasterSvg - Whether the SVG embeds a rendered picture.
+ * @param t - The chrome's formatter, so the sentence is in the language of
+ * the page.
  * @returns The sentence.
  */
 function hintOf(
@@ -163,14 +164,19 @@ function hintOf(
   scale: number,
   failure: string | null,
   rasterSvg: boolean,
+  t: Translate<ChromeKey>,
 ): string {
   if (failure !== null) return failure;
-  if (size === null) return 'There is no figure on the page to save yet.';
+  if (size === null) return t('download.noFigure');
   if (format === 'svg' && rasterSvg) {
-    return `An SVG holding a picture of ${formatFigurePixels(figurePixels(size, scale))}: a 3D scene has no vector form.`;
+    return t('download.hintRasterSvg', {
+      pixels: formatFigurePixels(figurePixels(size, scale)),
+    });
   }
   if (format === 'svg') {
-    return `An SVG stays sharp at any size, so the resolution does not apply. Drawn ${formatFigurePixels(size)}.`;
+    return t('download.hintSvg', { pixels: formatFigurePixels(size) });
   }
-  return `Saved ${formatFigurePixels(figurePixels(size, scale))}.`;
+  return t('download.hintPng', {
+    pixels: formatFigurePixels(figurePixels(size, scale)),
+  });
 }

package/src/ecosystem/ui/EcosystemButton.tsx

@@ -1,5 +1,6 @@
 import type { ReactElement } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import type { HeaderButtonProps } from '../../shared/ui/MenuButton.tsx';
 import { MenuButton } from '../../shared/ui/MenuButton.tsx';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
@@ -17,7 +18,7 @@ export interface EcosystemButtonProps extends HeaderButtonProps {
   /**
    * Text of the button. In a compact bar it is not written, but it stays what
    * the pointer and a screen reader are told.
-   * @default 'Tools'
+   * @default the chrome's own word for it, in the language of the page
    */
   label?: string;
   /**
@@ -34,14 +35,15 @@ export interface EcosystemButtonProps extends HeaderButtonProps {
  * @returns The button and its menu.
  */
 export function EcosystemButton(props: EcosystemButtonProps): ReactElement {
-  const { currentSiteId, label = 'Tools', className, ...rest } = props;
+  const { currentSiteId, label, className, ...rest } = props;
+  const t = useChromeT();
 
   return (
     <MenuButton
       {...rest}
       className={joinClassNames('ecosystem-button', className)}
       icon="grid-view"
-      label={label}
+      label={label ?? t('ecosystem.tools')}
       menu={<EcosystemMenu currentSiteId={currentSiteId} />}
     />
   );

package/src/ecosystem/ui/EcosystemLinks.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactElement } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { useSiteLanguage } from '../../language/ui/siteLanguageContext.ts';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
@@ -60,7 +61,7 @@ export interface EcosystemLinksProps {
   currentSiteId?: SiteId;
   /**
    * What introduces the section.
-   * @default 'Our other tools'
+   * @default the chrome's own line, in the language of the page
    */
   heading?: string;
   /**
@@ -89,27 +90,26 @@ export interface EcosystemLinksProps {
  */
 export function EcosystemLinks(props: EcosystemLinksProps): ReactElement {
   const language = useSiteLanguage();
-  const {
-    className,
-    currentSiteId,
-    heading = 'Our other tools',
-    layout = 'grid',
-  } = props;
+  const { className, currentSiteId, heading, layout = 'grid' } = props;
+  const t = useChromeT();
+  const title = heading ?? t('ecosystem.otherTools');
 
   return (
     <nav
       className={joinClassNames('ecosystem-links', className)}
       style={SECTION_STYLE}
-      aria-label={heading}
+      aria-label={title}
     >
-      <h2 style={ECOSYSTEM_HEADING_STYLE}>{heading}</h2>
+      <h2 style={ECOSYSTEM_HEADING_STYLE}>{title}</h2>
       {layout === 'grid' ? (
         <SiteGroupGrid currentSiteId={currentSiteId} />
       ) : (
         <div style={ROWS_STYLE}>
           {groupedSites().map(({ group, sites }) => (
             <div key={group.id} style={ROW_STYLE}>
-              <span style={ROW_LABEL_STYLE}>{group.label}</span>
+              <span style={ROW_LABEL_STYLE}>
+                {t.or(`ecosystem.group.${group.id}.label`, group.label)}
+              </span>
               {sites.map((site) =>
                 site.id === currentSiteId ? (
                   <span key={site.id} style={CURRENT_STYLE}>

package/src/ecosystem/ui/EcosystemMenu.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactElement } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 import type { SiteId } from '../core/sites.ts';
 
@@ -44,13 +45,14 @@ export interface EcosystemMenuProps {
  */
 export function EcosystemMenu(props: EcosystemMenuProps): ReactElement {
   const { className, currentSiteId } = props;
+  const t = useChromeT();
 
   return (
     <div
       className={joinClassNames('ecosystem-menu', className)}
       style={PANEL_STYLE}
     >
-      <div style={ECOSYSTEM_HEADING_STYLE}>Our tools, all in the browser</div>
+      <div style={ECOSYSTEM_HEADING_STYLE}>{t('ecosystem.menuHeading')}</div>
       <SiteGroupGrid currentSiteId={currentSiteId} lit newTab />
     </div>
   );

package/src/ecosystem/ui/SiteGroupSection.tsx

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 import { useId } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import type { SiteGroup } from '../core/groups.ts';
 
@@ -50,14 +51,17 @@ interface SiteGroupSectionProps {
  */
 export function SiteGroupSection(props: SiteGroupSectionProps): ReactElement {
   const { group, children } = props;
+  const t = useChromeT();
   const headingId = `${useId()}ecosystem-${group.id}`;
 
   return (
     <section style={SECTION_STYLE} aria-labelledby={headingId}>
       <h3 id={headingId} style={LABEL_STYLE}>
-        {group.label}
+        {t.or(`ecosystem.group.${group.id}.label`, group.label)}
       </h3>
-      <p style={BLURB_STYLE}>{group.blurb}</p>
+      <p style={BLURB_STYLE}>
+        {t.or(`ecosystem.group.${group.id}.blurb`, group.blurb)}
+      </p>
       <div style={BODY_STYLE}>{children}</div>
     </section>
   );

package/src/ecosystem/ui/SiteTile.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactElement } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { useSiteLanguage } from '../../language/ui/siteLanguageContext.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import { siteNameColors } from '../core/nameColors.ts';
@@ -95,6 +96,7 @@ export function SiteTile(props: SiteTileProps): ReactElement {
     onHover,
     newTab = false,
   } = props;
+  const t = useChromeT();
   const lit = isHovered && !isCurrent;
   const colors = siteNameColors(site);
 
@@ -119,11 +121,13 @@ export function SiteTile(props: SiteTileProps): ReactElement {
           </span>
           {isCurrent ? (
             <span style={{ ...HERE_STYLE, color: site.brandAlt }}>
-              you are here
+              {t('ecosystem.youAreHere')}
             </span>
           ) : null}
         </div>
-        <div style={TAGLINE_STYLE}>{site.tagline}</div>
+        <div style={TAGLINE_STYLE}>
+          {t.or(`site.${site.id}.tagline`, site.tagline)}
+        </div>
       </div>
     </>
   );

package/src/error/ui/ErrorFallback.tsx

@@ -1,6 +1,8 @@
 import { Button, NonIdealState } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
 /** What the page shows in place of the part that failed. */
 export interface ErrorFallbackProps {
   /** What was thrown, whose message is what the visitor is told. */
@@ -13,12 +15,12 @@ export interface ErrorFallbackProps {
   onRetry?: () => void;
   /**
    * First line, above the message.
-   * @default 'Something went wrong'
+   * @default the chrome's own line, in the language of the page
    */
   title?: string;
   /**
    * Text of the retry button.
-   * @default 'Try again'
+   * @default the chrome's own words for it, in the language of the page
    */
   retryLabel?: string;
   /**
@@ -38,27 +40,26 @@ export interface ErrorFallbackProps {
  * @returns The non-ideal state.
  */
 export function ErrorFallback(props: ErrorFallbackProps): ReactElement {
-  const {
-    error,
-    onRetry,
-    title = 'Something went wrong',
-    retryLabel = 'Try again',
-    className,
-  } = props;
+  const { error, onRetry, title, retryLabel, className } = props;
+  const t = useChromeT();
 
   return (
     <NonIdealState
       className={className}
       icon="error"
-      title={title}
+      title={title ?? t('error.title')}
       description={
         <span className="error-fallback__message">
-          {error.message === '' ? 'No message was given.' : error.message}
+          {error.message === '' ? t('error.noMessage') : error.message}
         </span>
       }
       action={
         onRetry === undefined ? undefined : (
-          <Button icon="refresh" text={retryLabel} onClick={onRetry} />
+          <Button
+            icon="refresh"
+            text={retryLabel ?? t('error.tryAgain')}
+            onClick={onRetry}
+          />
         )
       }
     />

package/src/help/ui/HelpBody.tsx

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 
 /** A worked example under a piece of help: the construct, and what it does. */
@@ -72,6 +73,7 @@ export interface HelpBodyProps {
  */
 export function HelpBody(props: HelpBodyProps): ReactElement {
   const { className, content, width = DEFAULT_WIDTH } = props;
+  const t = useChromeT();
   const { title, body, example, link } = content;
 
   return (
@@ -86,7 +88,7 @@ export function HelpBody(props: HelpBodyProps): ReactElement {
           <code style={CODE_STYLE}>{item.code}</code>
           {item.input === undefined ? null : (
             <div style={INPUT_STYLE}>
-              on <code style={CODE_STYLE}>{item.input}</code>
+              {t('help.on')} <code style={CODE_STYLE}>{item.input}</code>
             </div>
           )}
           {item.note === undefined ? null : (
@@ -101,7 +103,7 @@ export function HelpBody(props: HelpBodyProps): ReactElement {
           rel="noopener noreferrer"
           style={LINK_STYLE}
         >
-          Learn more
+          {t('help.learnMore')}
         </a>
       )}
     </div>

package/src/help/ui/HelpIcon.tsx

@@ -2,6 +2,7 @@ import type { IconName } from '@blueprintjs/core';
 import { Icon } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 
 import type { HelpContent } from './HelpBody.tsx';
@@ -17,7 +18,8 @@ export interface HelpIconProps {
   content: HelpContent;
   /**
    * What a screen reader calls the glyph.
-   * @default the help's title, or `'Help'` when it has none
+   * @default the help's title, or the chrome's own word for help when it has
+   * none
    */
   label?: string;
   /**
@@ -54,12 +56,13 @@ export interface HelpIconProps {
 export function HelpIcon(props: HelpIconProps): ReactElement {
   const {
     content,
-    label = helpName(content),
+    label,
     icon = 'help',
     size = 13,
     placement = 'right',
     className,
   } = props;
+  const t = useChromeT();
 
   return (
     <HelpTooltip content={content} placement={placement}>
@@ -67,7 +70,7 @@ export function HelpIcon(props: HelpIconProps): ReactElement {
         icon={icon}
         size={size}
         tabIndex={0}
-        aria-label={label}
+        aria-label={label ?? helpName(content, t)}
         className={joinClassNames('help-icon', className)}
       />
     </HelpTooltip>

package/src/help/ui/HelpToolbarButton.tsx

@@ -2,6 +2,8 @@ import type { IconName } from '@blueprintjs/core';
 import { Button } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
 import type { HelpContent } from './HelpBody.tsx';
 import { HelpTooltip } from './HelpTooltip.tsx';
 import { helpName } from './helpName.ts';
@@ -56,6 +58,7 @@ export function HelpToolbarButton(props: HelpToolbarButtonProps): ReactElement {
     small = false,
     className,
   } = props;
+  const t = useChromeT();
 
   return (
     <HelpTooltip content={content} placement="bottom">
@@ -64,7 +67,7 @@ export function HelpToolbarButton(props: HelpToolbarButtonProps): ReactElement {
         size={small ? 'small' : 'medium'}
         icon={icon}
         text={label}
-        aria-label={label ?? helpName(content)}
+        aria-label={label ?? helpName(content, t)}
         className={className}
         onClick={onClick}
       />

package/src/help/ui/helpName.ts

@@ -1,11 +1,19 @@
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { Translate } from '../../i18n/ui/useT.ts';
+
 import type { HelpContent } from './HelpBody.tsx';
 
 /**
  * The name a glyph or a button carries for a screen reader: the help's own
  * title, or a plain "Help" when the help has none.
  * @param content - The help being named.
+ * @param t - The chrome's formatter, so the plain name is in the language of
+ * the page.
  * @returns The accessible name.
  */
-export function helpName(content: HelpContent): string {
-  return content.title ?? 'Help';
+export function helpName(
+  content: HelpContent,
+  t: Translate<ChromeKey>,
+): string {
+  return content.title ?? t('help.label');
 }

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;
+}