react-cheminfo 0.37.0 → 0.38.0

package/src/range/ui/RangeValue.tsx

@@ -0,0 +1,166 @@
+import type { KeyboardEvent, ReactElement } from 'react';
+import { useEffect, useRef, useState } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { NumberInput } from '../../number/ui/NumberInput.tsx';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+
+/** What one end of a range slider's row of values needs. */
+export interface RangeValueProps {
+  /** Which end this is. */
+  side: 'min' | 'max';
+  /** The bound on this side, or `null` when the side is open. */
+  bound: number | null;
+  /** The end of the track on this side, shown faint while the side is open. */
+  end: number;
+  /** The quantity the slider bounds, for a screen reader. */
+  label: string;
+  /** How a number is written. */
+  format: (value: number) => string;
+  /** The bound on the other side, which a typed value may not cross. */
+  limit: number | null;
+  /** What one press of an arrow key adds in the box. */
+  step: number;
+  /** Whether only whole numbers are wanted. */
+  integer: boolean;
+  /** Whether the value can be edited. */
+  disabled: boolean;
+  /** Whether the box is open for typing. */
+  editing: boolean;
+  /** Open the box. */
+  onEdit: () => void;
+  /**
+   * Close the box, with what it holds — `undefined` for an emptied box — and
+   * whether Escape closed it, in which case nothing typed is kept.
+   */
+  onDone: (value: number | undefined, cancelled: boolean) => void;
+}
+
+/**
+ * One end of a range, written under the track: a bound, or the end of the
+ * track in faint ink when the side is open. A click turns it into a box, so a
+ * value the handles cannot land on is still one click and a few keystrokes
+ * away.
+ * @param props - See {@link RangeValueProps}.
+ * @returns The value, or the box it is typed into.
+ */
+export function RangeValue(props: RangeValueProps): ReactElement {
+  const { side, bound, end, label, format, disabled, editing, onEdit } = props;
+  const t = useChromeT();
+  if (editing) {
+    const { limit, step, integer, onDone } = props;
+    return (
+      <RangeValueEditor
+        side={side}
+        bound={bound}
+        end={end}
+        label={label}
+        format={format}
+        limit={limit}
+        step={step}
+        integer={integer}
+        onDone={onDone}
+      />
+    );
+  }
+
+  const open = bound === null;
+  const shown = open ? end : bound;
+  const text = Number.isFinite(shown) ? format(shown) : '–';
+  const name = open
+    ? t(side === 'min' ? 'range.noLowerBound' : 'range.noUpperBound', {
+        label,
+      })
+    : t(side === 'min' ? 'range.lowestIs' : 'range.highestIs', {
+        label,
+        value: text,
+      });
+
+  return (
+    <button
+      type="button"
+      className={joinClassNames(
+        'range-slider__value',
+        open && 'range-slider__value--open',
+      )}
+      disabled={disabled}
+      title={t('range.typeValue')}
+      aria-label={name}
+      onClick={onEdit}
+    >
+      {text}
+    </button>
+  );
+}
+
+/** What the box a value is typed into needs. */
+type RangeValueEditorProps = Omit<
+  RangeValueProps,
+  'disabled' | 'editing' | 'onEdit'
+>;
+
+/**
+ * The box a value is typed into. Enter or leaving it keeps what it holds;
+ * Escape drops it.
+ * @param props - See {@link RangeValueEditorProps}.
+ * @returns The box, focused and selected.
+ */
+function RangeValueEditor(props: RangeValueEditorProps): ReactElement {
+  const { side, bound, end, label, format, limit, step, integer } = props;
+  const { onDone } = props;
+  const t = useChromeT();
+  const [typed, setTyped] = useState<number | undefined>(bound ?? undefined);
+  // The box settles its number — rounded, held inside its bounds — as it is
+  // left, and that happens in the same blur this wrapper hears afterwards,
+  // before any re-render: refs are what carry it across.
+  const latest = useRef(typed);
+  const cancelled = useRef(false);
+  const host = useRef<HTMLSpanElement>(null);
+
+  useEffect(() => {
+    const input = host.current?.querySelector('input');
+    input?.focus();
+    input?.select();
+  }, []);
+
+  function press(event: KeyboardEvent<HTMLSpanElement>) {
+    if (event.key !== 'Enter' && event.key !== 'Escape') return;
+    event.preventDefault();
+    // An Escape that closes the box must not also close a dialog around it.
+    event.stopPropagation();
+    cancelled.current = event.key === 'Escape';
+    if (event.target instanceof HTMLElement) event.target.blur();
+  }
+
+  return (
+    <span
+      ref={host}
+      className={joinClassNames(
+        'range-slider__editor',
+        `range-slider__editor--${side}`,
+      )}
+      onKeyDown={press}
+      onBlur={() => onDone(latest.current, cancelled.current)}
+    >
+      <NumberInput
+        allowEmpty
+        size="small"
+        buttons={false}
+        fill
+        value={typed}
+        step={step}
+        integer={integer}
+        min={side === 'max' ? (limit ?? undefined) : undefined}
+        max={side === 'min' ? (limit ?? undefined) : undefined}
+        placeholder={Number.isFinite(end) ? format(end) : undefined}
+        ariaLabel={t(side === 'min' ? 'range.lowest' : 'range.highest', {
+          label,
+        })}
+        onChange={(next) => {
+          latest.current = next;
+          setTyped(next);
+        }}
+      />
+    </span>
+  );
+}

package/src/range/ui/index.ts

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

package/src/seo/core/documentMeta.ts

@@ -15,6 +15,22 @@ export function writeDocumentMeta(meta: DocumentMeta): void {
   if (meta.title) documentTitle(meta.title);
   if (meta.description) metaDescription(meta.description);
   if (meta.canonical) canonicalLink(meta.canonical);
+  if (meta.language) documentLanguage(meta.language);
+}
+
+/**
+ * Say which language the page on screen is in.
+ *
+ * The file the build wrote already says it, and a click that switches language
+ * has to move it with the rest of the head: a page whose `lang` lies is read
+ * aloud wrong by a screen reader and offered to the wrong reader by a search
+ * engine, and nothing on screen shows it.
+ * @param language - The language tag, e.g. `fr`.
+ */
+export function documentLanguage(language: string): void {
+  if (typeof document === 'undefined') return;
+  const root = document.documentElement;
+  if (root) root.lang = language;
 }
 
 /**
@@ -71,6 +87,12 @@ export interface DocumentMeta {
    * @default undefined
    */
   canonical?: string;
+  /**
+   * The language the page is written in, for `<html lang>`. Left out, the one
+   * the page was served with stays as it is.
+   * @default undefined
+   */
+  language?: string;
 }
 
 function metaDescription(content: string): void {

package/src/seo/core/index.ts

@@ -1,3 +1,5 @@
+export type { AlternateOptions } from './alternates.ts';
+export { alternateLinkTags } from './alternates.ts';
 export type { DocumentMeta } from './documentMeta.ts';
 export { writeDocumentMeta } from './documentMeta.ts';
 export type {
@@ -9,7 +11,12 @@ export type {
 } from './noscript.ts';
 export { noscriptIndex } from './noscript.ts';
 export type { PageMetaOptions } from './pageMeta.ts';
-export { injectPageMeta, pageDocumentMeta, pageHeadTags } from './pageMeta.ts';
+export {
+  injectPageMeta,
+  pageDocumentMeta,
+  pageHeadTags,
+  pageLanguage,
+} from './pageMeta.ts';
 export type { PageContent, PageSection, PageTable } from './pageProse.ts';
 export { pageProseHtml } from './pageProse.ts';
 export type { PlainDescriptionOptions } from './plainDescription.ts';

package/src/seo/core/noscript.ts

@@ -9,6 +9,9 @@
 import { siteById, siteDisplayName } from '../../ecosystem/core/lookup.ts';
 import type { EcosystemSite, SiteId } from '../../ecosystem/core/sites.ts';
 import { ECOSYSTEM_SITES, siteUrl } 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 { joinBasePath } from '../../router/core/basePath.ts';
 import { escapeAttribute, escapeText } from '../../share/core/escape.ts';
 
@@ -70,6 +73,13 @@ export interface NoscriptText {
    * @default false
    */
   ecosystem?: boolean | NoscriptEcosystem;
+  /**
+   * The language the block is written in, which is what the family list's own
+   * heading is translated into. The site's own prose is passed already written;
+   * this is only for the words that belong to the chrome.
+   * @default the default language
+   */
+  language?: Language;
   /**
    * How the site's own addresses are written. `'absolute'` writes them from the
    * root of the host, under the mount the origin names. `'relative'` writes
@@ -119,6 +129,7 @@ export interface NoscriptOptions
  */
 export function noscriptIndex(options: NoscriptOptions): string {
   const site = resolveSite(options.site);
+  const language = options.language ?? DEFAULT_LANGUAGE;
   const hrefs = options.hrefs ?? 'absolute';
   const mount = hrefs === 'absolute' ? mountPathOf(options) : '';
   const content = options.content;
@@ -135,7 +146,7 @@ export function noscriptIndex(options: NoscriptOptions): string {
 
   return `<noscript>
   <h1>${heading}</h1>${prose}
-  <p>${intro}</p>${pageList(options.routes, mount, hrefs, '  ')}${familyList(site.id, options.ecosystem)}
+  <p>${intro}</p>${pageList(options.routes, mount, hrefs, '  ')}${familyList(site.id, options.ecosystem, language)}
 </noscript>`;
 }
 
@@ -185,6 +196,7 @@ function labelOf(route: NoscriptRoute): string {
 function familyList(
   current: string,
   ecosystem: boolean | NoscriptEcosystem | undefined,
+  language: Language,
 ): string {
   if (ecosystem === undefined || ecosystem === false) return '';
   const listed = ecosystem === true ? {} : ecosystem;
@@ -198,8 +210,14 @@ function familyList(
     );
   }
   if (items.length === 0) return '';
+  // The chrome's own words, so one translation in this package writes the crawl
+  // path of every site of the family rather than eighteen catalogs carrying the
+  // same two words.
+  const heading = escapeText(
+    CHROME_CATALOG.translate('ecosystem.otherTools', language),
+  );
   return `
-  <h2>Our other tools</h2>
+  <h2>${heading}</h2>
   <ul>
 ${items.join('\n')}
   </ul>`;

package/src/seo/core/pageMeta.ts

@@ -38,8 +38,16 @@ const ABSOLUTE_URL = /^[a-z][\d+.a-z-]*:\/\//i;
 export interface PageMetaOptions {
   /** 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, exactly as `cheminfoPrerender`
+   * takes it: the language is read off the address first, and that language's
+   * table is what the page is titled from. Passed as a value by a site whose
+   * prose is per-language, a language switch would leave the title and the
+   * description in whichever language the table was built in.
+   */
+  routes: readonly RouteMeta[] | ((language: Language) => readonly RouteMeta[]);
   /**
    * The address being written, query string included: a path, or the absolute
    * address an app reads off the page it is on.
@@ -148,10 +156,12 @@ export function pageDocumentMeta(
 ): Required<DocumentMeta> {
   const site = resolveSite(options.site);
   const meta = routeMetaOf(options);
+  const language = pageLanguage(options);
   return {
     title: `${meta.title} — ${siteDisplayName(site)}`,
     description: meta.description,
-    canonical: `${originOf(options)}${withLanguagePath(pageLanguage(options), meta.path)}`,
+    canonical: `${originOf(options)}${withLanguagePath(language, meta.path)}`,
+    language,
   };
 }
 
@@ -173,8 +183,22 @@ export function pageLanguage(options: PageMetaOptions): Language {
 // route table is written from the site's own root, so the mount the origin
 // carries is taken off it before the table is read.
 function routeMetaOf(options: PageMetaOptions): RouteMeta {
-  const { path } = readLanguagePath(ownPath(options), languagesOf(options));
-  return pageMetaFor(options.routes, path);
+  const { language, path } = readLanguagePath(
+    ownPath(options),
+    languagesOf(options),
+  );
+  return pageMetaFor(tableOf(options, language), path);
+}
+
+// The table the page is titled from: the one the site passed, or the one its
+// function returns for the language the address names.
+function tableOf(
+  options: PageMetaOptions,
+  language: Language,
+): readonly RouteMeta[] {
+  return typeof options.routes === 'function'
+    ? options.routes(language)
+    : options.routes;
 }
 
 // The address from the site's own root, the mount taken off, with the query

package/src/seo/core/siteFiles.ts

@@ -11,6 +11,9 @@
 
 import { siteById } from '../../ecosystem/core/lookup.ts';
 import type { SiteId, SiteRecord } from '../../ecosystem/core/sites.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 { basePathOf } from '../../router/core/basePath.ts';
 import { escapeText } from '../../share/core/escape.ts';
@@ -22,8 +25,27 @@ import type { RouteMeta } from './routes.ts';
 // parses, with `localhost:` as its scheme and `3000` as its path.
 const HTTP_ORIGIN = /^https?:\/\//i;
 
+/**
+ * Which site is being served, and where.
+ *
+ * The half of the options that says nothing about the pages, so the helpers
+ * that only resolve an address take this rather than the whole record — a
+ * caller whose `routes` is a function of the language is then still one of
+ * these.
+ */
+export interface SiteOrigin {
+  /** The site, named or passed. */
+  site: SiteRecord | SiteId;
+  /**
+   * Where the site is served, mount path included, e.g.
+   * `https://learn.cheminfo.org/surge`.
+   * @default `https://<the site's host>`
+   */
+  origin?: string;
+}
+
 /** What a crawler is told about the site as a whole. */
-export interface SiteFilesOptions {
+export interface SiteFilesOptions extends SiteOrigin {
   /** The site, named or passed. */
   site: SiteRecord | SiteId;
   /** Every address it answers. */
@@ -35,6 +57,16 @@ export interface SiteFilesOptions {
    * @default `https://<the site's host>`
    */
   origin?: string;
+  /**
+   * Every language the site is written in, the default one included.
+   *
+   * A translated page is a page per language, so the sitemap lists every one of
+   * them: a variant it leaves out is a variant nothing points a crawler at, and
+   * the translation may as well not have been written. The `hreflang` set in
+   * each page's head is what then ties them back together.
+   * @default [the default language]
+   */
+  languages?: readonly Language[];
 }
 
 /**
@@ -53,13 +85,16 @@ export function sitemapXml(options: SiteFilesOptions): string {
   if (options.routes.every((route) => route.indexed === false)) {
     throw new Error('a sitemap lists at least one address');
   }
-  const entries = options.routes
-    .filter((route) => route.indexed !== false)
-    .map(
-      (route) =>
-        `  <url><loc>${escapeText(`${origin}${route.path}`)}</loc></url>`,
-    )
-    .join('\n');
+  const languages = options.languages ?? [DEFAULT_LANGUAGE];
+  const lines: string[] = [];
+  for (const route of options.routes) {
+    if (route.indexed === false) continue;
+    for (const language of languages) {
+      const address = `${origin}${withLanguagePath(language, route.path)}`;
+      lines.push(`  <url><loc>${escapeText(address)}</loc></url>`);
+    }
+  }
+  const entries = lines.join('\n');
   return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
 ${entries}
@@ -91,7 +126,7 @@ export function resolveSite(site: SiteRecord | SiteId): SiteRecord {
  * @throws {Error} When the deployment named something that is not an absolute
  * `http` or `https` address.
  */
-export function originOf(options: SiteFilesOptions): string {
+export function originOf(options: SiteOrigin): string {
   const origin = options.origin ?? `https://${resolveSite(options.site).host}`;
   if (!HTTP_ORIGIN.test(origin) || !URL.canParse(origin)) {
     throw new Error(
@@ -108,6 +143,6 @@ export function originOf(options: SiteFilesOptions): string {
  * @throws {Error} When the deployment named something that is not an absolute
  * address, so there is no path to read off it.
  */
-export function mountPathOf(options: SiteFilesOptions): string {
+export function mountPathOf(options: SiteOrigin): string {
   return basePathOf(originOf(options));
 }

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 {