react-cheminfo 0.3.0 → 0.4.0

package/src/ecosystem/core/sites.ts

@@ -35,6 +35,8 @@ export interface EcosystemSite {
   name: SiteName;
   /** Where the site lives, written the way it is typed. */
   host: string;
+  /** Where the sources live, and what a Source link opens. */
+  repository: string;
   /** One line on what the site does. */
   tagline: string;
   /** The colour the first half of the name is set in. */
@@ -71,6 +73,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'inchi',
     name: { lead: 'inchi', alt: 'cheminfo', dot: true },
     host: 'inchi.cheminfo.org',
+    repository: 'https://github.com/cheminfo/inchi.cheminfo.org',
     tagline: 'InChI and InChIKey from a structure, in the browser.',
     brand: '#5b21b6',
     brandAlt: '#a16207',
@@ -80,6 +83,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'vcl',
     name: { lead: 'vcl', alt: 'cheminfo', dot: true },
     host: 'vcl.cheminfo.org',
+    repository: 'https://github.com/cheminfo/vcl.cheminfo.org',
     tagline: 'Combine a core and fragments into a screened library.',
     brand: '#2d72d2',
     brandAlt: '#9a3412',
@@ -89,6 +93,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'smiles',
     name: { lead: 'smiles', alt: 'cheminfo', dot: true },
     host: 'smiles.cheminfo.org',
+    repository: 'https://github.com/cheminfo/smiles.cheminfo.org',
     tagline: 'Draw a structure, read its SMILES, learn the notation.',
     brand: '#1c6e42',
     brandAlt: '#9a3412',
@@ -98,6 +103,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'chemcalc',
     name: { lead: 'Chem', alt: 'Calc' },
     host: 'www.chemcalc.org',
+    repository: 'https://github.com/cheminfo/chemcalc.org',
     tagline: 'Molecular formula, exact mass and isotopic distribution.',
     brand: '#5b52e0',
     brandAlt: '#0d9488',
@@ -107,6 +113,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'nmrium',
     name: { lead: 'NMR', alt: 'ium' },
     host: 'www.nmrium.org',
+    repository: 'https://github.com/cheminfo/nmrium',
     tagline: 'Process and assign NMR spectra in the browser.',
     brand: '#ea580c',
     brandAlt: '#2b143e',
@@ -116,6 +123,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'surge',
     name: { lead: 'surge', alt: 'cheminfo', dot: true },
     host: 'surge.cheminfo.org',
+    repository: 'https://github.com/cheminfo/surge.cheminfo.org',
     tagline: 'Every constitutional isomer of a molecular formula.',
     brand: '#4338ca',
     brandAlt: '#be123c',
@@ -125,6 +133,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'tex',
     name: { lead: 'tex', alt: 'cheminfo', dot: true },
     host: 'tex.cheminfo.org',
+    repository: 'https://github.com/cheminfo/tex.cheminfo.org',
     tagline: 'LaTeX formulas rendered to SVG or PNG from a URL.',
     brand: '#a21caf',
     brandAlt: '#a16207',
@@ -134,6 +143,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'lcao',
     name: { lead: 'lcao', alt: 'cheminfo', dot: true },
     host: 'lcao.cheminfo.org',
+    repository: 'https://github.com/cheminfo/lcao.cheminfo.org',
     tagline: 'Combine atomic orbitals into molecular ones.',
     brand: '#1565c0',
     brandAlt: '#c62828',
@@ -143,6 +153,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'regexp',
     name: { lead: 'regexp', alt: 'cheminfo', dot: true },
     host: 'regexp.cheminfo.org',
+    repository: 'https://github.com/cheminfo/regexp.cheminfo.org',
     tagline: 'Learn regular expressions in a live playground.',
     brand: '#1e3a8a',
     brandAlt: '#a16207',
@@ -152,6 +163,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'pdb',
     name: { lead: 'pdb', alt: 'cheminfo', dot: true },
     host: 'pdb.cheminfo.org',
+    repository: 'https://github.com/cheminfo/pdb.cheminfo.org',
     tagline: 'A fast look at any Protein Data Bank entry.',
     brand: '#2563eb',
     brandAlt: '#b45309',
@@ -161,6 +173,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'elucidation',
     name: { lead: 'elucidation', alt: 'cheminfo', dot: true },
     host: 'elucidation.cheminfo.org',
+    repository: 'https://github.com/cheminfo/elucidation.cheminfo.org',
     tagline: 'A structure from a 1H NMR spectrum and a formula.',
     brand: '#7e22ce',
     brandAlt: '#b45309',
@@ -170,6 +183,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'equilibrium',
     name: { lead: 'Equi', alt: 'Librium' },
     host: 'equilibrium.cheminfo.org',
+    repository: 'https://github.com/cheminfo/equilibrium.cheminfo.org',
     tagline: 'Chemical equilibria: pH, speciation and titration curves.',
     brand: '#0b5754',
     brandAlt: '#a56600',
@@ -179,6 +193,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'polycarp',
     name: { lead: 'Poly', alt: 'Carp' },
     host: 'polycarp.cheminfo.org',
+    repository: 'https://github.com/cheminfo/polycarp.cheminfo.org',
     tagline: 'Predict the microstructure of a radical copolymerisation.',
     brand: '#0d1d37',
     brandAlt: '#0c9ba3',
@@ -188,6 +203,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: '3d',
     name: { lead: '3d', alt: 'cheminfo', dot: true },
     host: '3d.cheminfo.org',
+    repository: 'https://github.com/cheminfo/3d.cheminfo.org',
     tagline: 'Conformers in 3D from a structure you draw.',
     brand: '#155e75',
     brandAlt: '#b45309',
@@ -197,6 +213,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     id: 'pt',
     name: { lead: 'pt', alt: 'cheminfo', dot: true },
     host: 'pt.cheminfo.org',
+    repository: 'https://github.com/cheminfo/pt.cheminfo.org',
     tagline: 'The periodic table, coloured, plotted and taken apart.',
     brand: '#15803d',
     brandAlt: '#a16207',

package/src/ecosystem/core/tokens.ts

@@ -0,0 +1,47 @@
+import { siteById } from './lookup.ts';
+import type { EcosystemSite, SiteId } from './sites.ts';
+
+/**
+ * The custom properties a site of the family sets on `:root`: the two colours
+ * it owns, the readable form of the second one when that is needed, and the
+ * accent bound to the first.
+ *
+ * It is a complete rule rather than a list of declarations, so it drops into a
+ * `<style>` of a prerendered page as it is.
+ * @param id - The site whose palette is wanted.
+ * @returns The `:root` rule, ending in a newline.
+ */
+export function siteTokensCss(id: SiteId): string {
+  const site = siteById(id);
+  const answering = answeringColor(site);
+  const declarations = [
+    `--brand: ${site.brand};`,
+    `--brand-alt: ${answering};`,
+  ];
+
+  // The answering colour of several sites is a yellow or an amber that sits
+  // around 2:1 on white, so text set in it needs the darkened form instead.
+  if (site.brandAlt !== answering) {
+    declarations.push(`--brand-alt-text: ${site.brandAlt};`);
+  }
+  declarations.push('--accent: var(--brand);');
+
+  return `:root {\n  ${declarations.join('\n  ')}\n}\n`;
+}
+
+/**
+ * What a browser paints its own chrome with on that site — the address bar on
+ * Android, the title bar of an installed page — which is the site's leading
+ * colour.
+ * @param id - The site whose colour is wanted.
+ * @returns The colour, as the `<meta name="theme-color">` content.
+ */
+export function siteThemeColor(id: SiteId): string {
+  return siteById(id).brand;
+}
+
+// The second colour as the site's mark draws it: on the accent element, unless
+// the mark inverts the pair and gives the plate the answering colour instead.
+function answeringColor(site: EcosystemSite): string {
+  return site.mark.accent === site.brand ? site.mark.plate : site.mark.accent;
+}

package/src/ecosystem/ui/SiteTheme.tsx

@@ -0,0 +1,23 @@
+import type { ReactElement } from 'react';
+
+import type { SiteId } from '../core/sites.ts';
+import { siteTokensCss } from '../core/tokens.ts';
+
+export interface SiteThemeProps {
+  /** The site whose palette the page takes. */
+  siteId: SiteId;
+}
+
+/**
+ * The two colours a site owns, put on the page as custom properties.
+ *
+ * Everything of the family that reads `--brand`, `--brand-alt` or `--accent` —
+ * a mark drawn in token colours, a current menu item, a focus ring — follows
+ * from here, so a site declares its palette once and never repeats a hex code
+ * in a component.
+ * @param props - The site whose palette is injected.
+ * @returns The rule, as a style element that applies wherever it is rendered.
+ */
+export function SiteTheme(props: SiteThemeProps): ReactElement {
+  return <style>{siteTokensCss(props.siteId)}</style>;
+}

package/src/ecosystem/ui/Wordmark.tsx

@@ -0,0 +1,65 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import { siteById } from '../core/lookup.ts';
+import type { SiteId } from '../core/sites.ts';
+
+export interface WordmarkProps {
+  /** The site whose name is written. */
+  siteId: SiteId;
+  /**
+   * Size of the name, in pixels. The weight comes from the surrounding
+   * context, so the same wordmark suits a header bar and a heading.
+   * @default 17
+   */
+  size?: number;
+  /**
+   * Extra class names, for spacing at the place it is used. `wordmark` is
+   * always carried as well.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The name of a site, written in the two colours it owns.
+ *
+ * A name that splits on itself — `ChemCalc`, `EquiLibrium`, `PolyCarp` —
+ * carries no domain and no dot; a one-word name takes `.cheminfo` after a faint
+ * dot. The `.org` is never written, because the name is the site rather than
+ * its address.
+ * @param props - The site, the size of the name, and extra class names.
+ * @returns The name, as one inline element that never wraps mid-address.
+ */
+export function Wordmark(props: WordmarkProps): ReactElement {
+  const { siteId, size = 17, className } = props;
+  const site = siteById(siteId);
+
+  return (
+    <span
+      className={className ? `wordmark ${className}` : 'wordmark'}
+      style={{ ...WORDMARK_STYLE, fontSize: size }}
+    >
+      <span className="wordmark__lead" style={{ color: site.brand }}>
+        {site.name.lead}
+      </span>
+      {site.name.dot ? (
+        <span className="wordmark__dot" style={{ color: DOT_COLOR }}>
+          .
+        </span>
+      ) : null}
+      <span className="wordmark__alt" style={{ color: site.brandAlt }}>
+        {site.name.alt}
+      </span>
+    </span>
+  );
+}
+
+// The separating dot is neutral so the two coloured halves read as the name
+// rather than as three equal parts, and it takes the family's own token when
+// the page defines one.
+const DOT_COLOR = 'var(--text-faint, #8a96a3)';
+
+const WORDMARK_STYLE: CSSProperties = {
+  letterSpacing: '-0.01em',
+  whiteSpace: 'nowrap',
+};

package/src/ecosystem/ui/index.ts

@@ -6,5 +6,9 @@ export type { EcosystemMenuProps } from './EcosystemMenu.tsx';
 export { EcosystemMenu } from './EcosystemMenu.tsx';
 export type { SiteMarkProps } from './marks.tsx';
 export { SiteMark } from './marks.tsx';
+export type { SiteThemeProps } from './SiteTheme.tsx';
+export { SiteTheme } from './SiteTheme.tsx';
 export type { SiteTileProps } from './SiteTile.tsx';
 export { SiteTile } from './SiteTile.tsx';
+export type { WordmarkProps } from './Wordmark.tsx';
+export { Wordmark } from './Wordmark.tsx';

package/src/ecosystem/ui/marks.tsx

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactElement } from 'react';
 
-import type { EcosystemSite } from '../core/sites.ts';
+import { siteById } from '../core/lookup.ts';
+import type { EcosystemSite, SiteId } from '../core/sites.ts';
 
 import { GLYPHS } from './glyphs.tsx';
 
@@ -12,22 +13,58 @@ import { GLYPHS } from './glyphs.tsx';
 const MARK_STYLE: CSSProperties = { display: 'block', flex: 'none' };
 
 export interface SiteMarkProps {
-  /** The site whose mark is drawn, with the two colours it owns. */
-  site: EcosystemSite;
+  /**
+   * The site whose mark is drawn, with the two colours it owns. One of `site`
+   * and `siteId` is required.
+   * @default undefined
+   */
+  site?: EcosystemSite;
+  /**
+   * The same site, named rather than passed, for a header that knows only
+   * which site it is.
+   * @default undefined
+   */
+  siteId?: SiteId;
   /**
    * Edge of the square the mark is drawn in, in pixels.
    * @default 28
    */
   size?: number;
+  /**
+   * Whether the drawing sits on the site's rounded plate. Several marks are
+   * drawn in the plate's negative space, so dropping it suits a mark already
+   * standing on a surface of the site's own colour.
+   * @default true
+   */
+  plate?: boolean;
+  /**
+   * Whether the two colours are written out or read from the page. `tokens`
+   * draws the plate in `var(--brand)` and the answering element in
+   * `var(--brand-alt)`, so a site retuning its pair retunes its mark; it is
+   * therefore for the site's own mark rather than for another site's.
+   * @default 'literal'
+   */
+  colors?: 'literal' | 'tokens';
 }
 
 /**
  * The little logo of one site of the family.
- * @param props - The site and the size of its mark.
+ * @param props - Which site, how big, and where its colours come from.
  * @returns The mark, as an inline SVG.
+ * @throws {Error} When neither `site` nor `siteId` is given.
  */
 export function SiteMark(props: SiteMarkProps): ReactElement {
-  const { site, size = 28 } = props;
+  const { site, siteId, size = 28, plate = true, colors = 'literal' } = props;
+
+  const drawn = site ?? (siteId === undefined ? undefined : siteById(siteId));
+  if (drawn === undefined) {
+    throw new Error('SiteMark needs one of its `site` and `siteId` props');
+  }
+
+  const usesTokens = colors === 'tokens';
+  const plateFill = usesTokens ? 'var(--brand)' : drawn.mark.plate;
+  const accent = usesTokens ? 'var(--brand-alt)' : drawn.mark.accent;
+  const edge = drawn.mark.edge;
 
   return (
     <svg
@@ -38,16 +75,18 @@ export function SiteMark(props: SiteMarkProps): ReactElement {
       aria-hidden="true"
       focusable="false"
     >
-      <rect
-        x={site.mark.edge ? 0.5 : 0}
-        y={site.mark.edge ? 0.5 : 0}
-        width={site.mark.edge ? 31 : 32}
-        height={site.mark.edge ? 31 : 32}
-        rx={site.mark.edge ? 6.5 : 7}
-        fill={site.mark.plate}
-        stroke={site.mark.edge}
-      />
-      {GLYPHS[site.id](site.mark.accent)}
+      {plate ? (
+        <rect
+          x={edge ? 0.5 : 0}
+          y={edge ? 0.5 : 0}
+          width={edge ? 31 : 32}
+          height={edge ? 31 : 32}
+          rx={edge ? 6.5 : 7}
+          fill={plateFill}
+          stroke={edge}
+        />
+      ) : null}
+      {GLYPHS[drawn.id](accent)}
     </svg>
   );
 }

package/src/error/ui/ErrorBoundary.tsx

@@ -0,0 +1,94 @@
+import type { ErrorInfo, ReactNode } from 'react';
+import { Component } from 'react';
+
+import { ErrorFallback } from './ErrorFallback.tsx';
+import { toError } from './toError.ts';
+
+/** What {@link ErrorBoundary} wraps, and what it does when that part fails. */
+export interface ErrorBoundaryProps {
+  /** The part of the page whose failures are caught here. */
+  children: ReactNode;
+  /**
+   * What is drawn in place of the children once one of them has thrown. The
+   * reset closes the boundary again, so a retry re-renders the children.
+   * @default a non-ideal state naming the error, with a retry button
+   */
+  fallback?: (error: Error, reset: () => void) => ReactNode;
+  /**
+   * Called once with the error and the stack of components it came through, so
+   * a site can report it. Anything it throws is ignored: a failing reporter
+   * must not replace the failure the visitor is already looking at.
+   * @default undefined — the failure is not reported anywhere
+   */
+  onError?: (error: Error, componentStack: string) => void;
+  /**
+   * First line of the default fallback.
+   * @default 'Something went wrong'
+   */
+  title?: string;
+}
+
+/** Whether the boundary is holding an error, and which one. */
+export interface ErrorBoundaryState {
+  /** The error the boundary caught, or `null` while nothing has failed. */
+  error: Error | null;
+}
+
+/**
+ * Keep one failing part of the page from taking the whole page with it.
+ *
+ * A viewer that cannot start, a worker that dies, a structure that will not
+ * parse: without a boundary any of these leaves a blank page carrying the
+ * right title, which reads as a routing or a build defect and is neither.
+ */
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  /**
+   * Move the boundary into its failed state, whatever was thrown.
+   * @param thrown - The value a child threw.
+   * @returns The state holding it.
+   */
+  static getDerivedStateFromError(thrown: unknown): ErrorBoundaryState {
+    return { error: toError(thrown) };
+  }
+
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  /**
+   * Hand the failure to the site's reporter, if it has one.
+   * @param thrown - The value a child threw.
+   * @param info - Where it came from.
+   */
+  override componentDidCatch(thrown: unknown, info: ErrorInfo): void {
+    const { onError } = this.props;
+    if (onError === undefined) return;
+    try {
+      onError(toError(thrown), info.componentStack ?? '');
+    } catch {
+      // A reporter that fails must not replace the error being shown.
+    }
+  }
+
+  /** Forget the error and render the children again. */
+  reset = (): void => {
+    this.setState({ error: null });
+  };
+
+  /**
+   * The children, or what stands in for them once one has failed.
+   * @returns The rendered tree.
+   */
+  override render(): ReactNode {
+    const { children, fallback, title } = this.props;
+    const { error } = this.state;
+
+    if (error === null) return children;
+    if (fallback !== undefined) return fallback(error, this.reset);
+    return <ErrorFallback error={error} title={title} onRetry={this.reset} />;
+  }
+}

package/src/error/ui/ErrorFallback.tsx

@@ -0,0 +1,64 @@
+import { Button, NonIdealState } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+/** 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. */
+  error: Error;
+  /**
+   * Called when the visitor asks for another attempt. Left out when there is
+   * nothing sensible to retry, and then no button is drawn.
+   * @default undefined — no retry button
+   */
+  onRetry?: () => void;
+  /**
+   * First line, above the message.
+   * @default 'Something went wrong'
+   */
+  title?: string;
+  /**
+   * Text of the retry button.
+   * @default 'Try again'
+   */
+  retryLabel?: string;
+  /**
+   * Class the holder carries, so a site can reach it from its stylesheet.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The default face of a failure: what happened, and a way out of it.
+ *
+ * The message is written out rather than swallowed, because a visitor who
+ * reports "it says nothing" cannot be helped, whereas one who reports the
+ * sentence can.
+ * @param props - See {@link ErrorFallbackProps}.
+ * @returns The non-ideal state.
+ */
+export function ErrorFallback(props: ErrorFallbackProps): ReactElement {
+  const {
+    error,
+    onRetry,
+    title = 'Something went wrong',
+    retryLabel = 'Try again',
+    className,
+  } = props;
+
+  return (
+    <NonIdealState
+      className={className}
+      icon="error"
+      title={title}
+      description={
+        error.message === '' ? 'No message was given.' : error.message
+      }
+      action={
+        onRetry === undefined ? undefined : (
+          <Button icon="refresh" text={retryLabel} onClick={onRetry} />
+        )
+      }
+    />
+  );
+}

package/src/error/ui/index.ts

@@ -0,0 +1,4 @@
+export type { ErrorBoundaryProps } from './ErrorBoundary.tsx';
+export { ErrorBoundary } from './ErrorBoundary.tsx';
+export type { ErrorFallbackProps } from './ErrorFallback.tsx';
+export { ErrorFallback } from './ErrorFallback.tsx';

package/src/error/ui/toError.ts

@@ -0,0 +1,33 @@
+/**
+ * Turn whatever a component threw into an `Error`.
+ *
+ * A `throw` is not required to carry an `Error` — a rejected fetch, a worker
+ * message or a library can throw a string, an object or `undefined` — and the
+ * boundary still has to name what happened.
+ * @param thrown - The value that came out of the render.
+ * @returns The value itself when it is an error, otherwise one describing it.
+ */
+export function toError(thrown: unknown): Error {
+  if (thrown instanceof Error) return thrown;
+  if (typeof thrown === 'string' && thrown !== '') return new Error(thrown);
+  return new Error(describe(thrown));
+}
+
+const UNPRINTABLE = 'an unprintable value was thrown';
+
+function describe(thrown: unknown): string {
+  if (thrown === null) return 'null was thrown';
+  if (thrown === undefined) return 'undefined was thrown';
+  if (
+    typeof thrown === 'number' ||
+    typeof thrown === 'boolean' ||
+    typeof thrown === 'bigint'
+  ) {
+    return String(thrown);
+  }
+  try {
+    return JSON.stringify(thrown) ?? UNPRINTABLE;
+  } catch {
+    return UNPRINTABLE;
+  }
+}

package/src/format/core/index.ts

@@ -0,0 +1,9 @@
+export { MISSING_VALUE } from './missing.ts';
+export {
+  formatCompact,
+  formatDecimal,
+  formatInteger,
+  formatTrimmed,
+} from './numbers.ts';
+export { formatBytes, formatDuration } from './units.ts';
+export { pluralize } from './words.ts';

package/src/format/core/missing.ts

@@ -0,0 +1,6 @@
+/**
+ * What every formatter of this module writes when it has nothing to show — a
+ * missing value, or one that is not a finite number. An en dash, so an empty
+ * cell of a table still reads as a cell.
+ */
+export const MISSING_VALUE = '–';

package/src/format/core/numbers.ts

@@ -0,0 +1,84 @@
+import { MISSING_VALUE } from './missing.ts';
+
+const INTEGER_FORMATTER = new Intl.NumberFormat('en-US', {
+  maximumFractionDigits: 0,
+});
+
+const COMPACT_FORMATTER = new Intl.NumberFormat('en-US', {
+  notation: 'compact',
+  maximumFractionDigits: 1,
+});
+
+const MAXIMUM_DIGITS = 20;
+const DEFAULT_DIGITS = 2;
+
+const decimalFormatters = new Map<number, Intl.NumberFormat>();
+
+/**
+ * A whole number, grouped in thousands: `1,234,567`.
+ *
+ * Anything after the decimal point is rounded away. The locale is fixed to
+ * `en-US`, so the same page reads the same way wherever it is opened.
+ * @param value - The number to write.
+ * @returns The grouped number, or the missing marker when it is not finite.
+ */
+export function formatInteger(value: number): string {
+  if (!Number.isFinite(value)) return MISSING_VALUE;
+  return INTEGER_FORMATTER.format(value);
+}
+
+/**
+ * A number grouped in thousands and held to a fixed number of decimals:
+ * `1,234.50`.
+ *
+ * The digits are kept even when they are zeros, which is what a column of
+ * figures wants; use {@link formatTrimmed} for a label that should not carry
+ * them.
+ * @param value - The number to write.
+ * @param digits - Decimals to show. Defaults to `2`; a count outside 0..20 is clamped into it, and one that is not a number falls back to the default.
+ * @returns The formatted number, or the missing marker when it is not finite.
+ */
+export function formatDecimal(value: number, digits = DEFAULT_DIGITS): string {
+  if (!Number.isFinite(value)) return MISSING_VALUE;
+  const safeDigits = clampDigits(digits);
+  let formatter = decimalFormatters.get(safeDigits);
+  if (formatter === undefined) {
+    formatter = new Intl.NumberFormat('en-US', {
+      minimumFractionDigits: safeDigits,
+      maximumFractionDigits: safeDigits,
+    });
+    decimalFormatters.set(safeDigits, formatter);
+  }
+  return formatter.format(value);
+}
+
+/**
+ * A number rounded to `digits` decimals with the trailing zeros dropped:
+ * `1.5`, `2`, `0.125`.
+ *
+ * The thousands are not grouped, so the result stays a number a reader can
+ * type back in — this is the form an axis tick, a chip or an exported cell
+ * takes.
+ * @param value - The number to write.
+ * @param digits - Decimals to round to. Defaults to `2`; a count outside 0..20 is clamped into it, and one that is not a number falls back to the default.
+ * @returns The rounded number, or the missing marker when it is not finite.
+ */
+export function formatTrimmed(value: number, digits = DEFAULT_DIGITS): string {
+  if (!Number.isFinite(value)) return MISSING_VALUE;
+  return Number.parseFloat(value.toFixed(clampDigits(digits))).toString();
+}
+
+/**
+ * A number shortened for a cramped axis or a badge: `999`, `1.2K`, `3.4M`.
+ * @param value - The number to write.
+ * @returns The shortened number, or the missing marker when it is not finite.
+ */
+export function formatCompact(value: number): string {
+  if (!Number.isFinite(value)) return MISSING_VALUE;
+  return COMPACT_FORMATTER.format(value);
+}
+
+function clampDigits(digits: number): number {
+  if (!Number.isFinite(digits)) return DEFAULT_DIGITS;
+  return Math.min(MAXIMUM_DIGITS, Math.max(0, Math.trunc(digits)));
+}