react-cheminfo 0.2.0 → 0.4.0

package/src/ecosystem/ui/marks.tsx

@@ -1,7 +1,10 @@
-import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import type { CSSProperties, ReactElement } from 'react';
 
+import { siteById } from '../core/lookup.ts';
 import type { EcosystemSite, SiteId } from '../core/sites.ts';
 
+import { GLYPHS } from './glyphs.tsx';
+
 // Every mark is drawn in the same 32×32 box, on a plate of the site's own
 // colour, so every mark of the family still reads as one row. Each keeps the
 // geometry of that site's own logo where it has one, and carries the site's
@@ -10,22 +13,58 @@ import type { EcosystemSite, SiteId } from '../core/sites.ts';
 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
@@ -36,215 +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>
   );
 }
-
-/** Every mark, keyed by site, drawn on top of its plate. */
-const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
-  // A hexagon with a tail: the structure, and the string it hashes into.
-  inchi: (alt) => (
-    <g
-      fill="none"
-      stroke={alt}
-      strokeWidth="2.4"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <polygon points="13,6.5 7.7,9.6 7.7,15.7 13,18.8 18.3,15.7 18.3,9.6" />
-      <path d="M16.4 16.2 25.2 25" />
-    </g>
-  ),
-  // The core carrying three R groups, which is what this tool combines.
-  vcl: (alt) => (
-    <>
-      <g
-        fill="none"
-        stroke="#ffffff"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-      >
-        <path d="M16 9.5 10.8 12.5 10.8 18.5 16 21.5 21.2 18.5 21.2 12.5Z" />
-        <path d="M16 9.5 16 5.5M21.2 18.5 24.8 20.6M10.8 18.5 7.2 20.6" />
-      </g>
-      <circle cx="16" cy="4.6" r="2.6" fill={alt} />
-      <circle cx="25.6" cy="21.2" r="2.6" fill={alt} />
-      <circle cx="6.4" cy="21.2" r="2.6" fill={alt} />
-    </>
-  ),
-  // A ring over the line of characters that writes it down.
-  smiles: (alt) => (
-    <>
-      <path
-        d="M16 7.5 22.1 11.1 22.1 18.3 16 21.9 9.9 18.3 9.9 11.1Z"
-        fill="none"
-        stroke="#ffffff"
-        strokeWidth="2.2"
-        strokeLinejoin="round"
-      />
-      <path
-        d="M5.5 25.5h21"
-        fill="none"
-        stroke={alt}
-        strokeWidth="3"
-        strokeLinecap="round"
-      />
-    </>
-  ),
-  // An isotopic pattern: the answer this one is asked for most.
-  chemcalc: (alt) => (
-    <g strokeLinecap="round" strokeWidth="3.4" fill="none">
-      <path d="M9 24V15" stroke="#ffffff" />
-      <path d="M16 24V7" stroke={alt} />
-      <path d="M23 24V18" stroke="#ffffff" />
-    </g>
-  ),
-  // The official NMRium symbol, from `Logo.tsx` of the NMRium sources: the
-  // orange half is theirs, and the half their logo sets in plum is set in white
-  // here because the plate already is that plum.
-  nmrium: (accent) => (
-    <g fillRule="evenodd" transform="translate(5.25 6.25) scale(0.088)">
-      <path
-        fill={accent}
-        d="M.64,31.7A31.67,31.67,0,0,1,54.72,9.29l0,0A31.66,31.66,0,0,1,64,31.7V190a13.39,13.39,0,0,0,26.77,0V54a31.7,31.7,0,0,1,31.7-31.7V40.58A13.38,13.38,0,0,0,109.13,54V190a31.71,31.71,0,0,1-63.41,0V31.7a13.29,13.29,0,0,0-3.88-9.46l0,0A13.41,13.41,0,0,0,19,31.7V164.82H.64Z"
-      />
-      <path
-        fill="#ffffff"
-        d="M154.21,54v68.17a13.34,13.34,0,0,0,3.89,9.47h0A13.39,13.39,0,0,0,181,122.14V99.32h-.06a31.63,31.63,0,0,1,9.29-22.38l0,0a31.65,31.65,0,0,1,44.8,0l0,0a31.58,31.58,0,0,1,9.3,22.39V118H226V99.32a13.3,13.3,0,0,0-3.89-9.46h0a13.44,13.44,0,0,0-18.93,0l0,0a13.3,13.3,0,0,0-3.83,8.19v24.09a31.7,31.7,0,0,1-54.11,22.42v0a31.66,31.66,0,0,1-9.3-22.4V54Z"
-      />
-    </g>
-  ),
-  // One formula branching into every structure it can be.
-  surge: (alt) => (
-    <>
-      <g
-        fill="none"
-        stroke="#ffffff"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-      >
-        <path d="M7 16h6" />
-        <path d="M13 16 25 8.5M13 16h12M13 16 25 23.5" />
-      </g>
-      <circle cx="25" cy="8.5" r="3" fill={alt} />
-      <circle cx="25" cy="16" r="3" fill={alt} />
-      <circle cx="25" cy="23.5" r="3" fill={alt} />
-    </>
-  ),
-  // A radical over its radicand: a formula being set.
-  tex: (alt) => (
-    <>
-      <rect x="18.5" y="12" width="8.5" height="8.5" rx="1.6" fill={alt} />
-      <path
-        d="M4.5 15.5h3l3.6 8.2L16.8 7.5h10.4"
-        fill="none"
-        stroke="#ffffff"
-        strokeWidth="2.4"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-      />
-    </>
-  ),
-  // The site's own favicon: two lobes of opposite phase overlapping end-on,
-  // the simplest sigma bond, in the phase palette its viewer renders with.
-  lcao: (alt) => (
-    <>
-      <path
-        d="M16 16C16 10.2 13.3 5 9 5S2 10.2 2 16s2.7 11 7 11 7-5.2 7-11z"
-        fill="#1565c0"
-      />
-      <path
-        d="M16 16c0 5.8 2.7 11 7 11s7-5.2 7-11-2.7-11-7-11-7 5.2-7 11z"
-        fill={alt}
-      />
-      <circle cx="16" cy="16" r="2.25" fill="#37474f" />
-    </>
-  ),
-  // The pattern that matches anything, which is where everyone starts.
-  regexp: (alt) => (
-    <text
-      x="50%"
-      y="53%"
-      dominantBaseline="central"
-      textAnchor="middle"
-      fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace"
-      fontSize="18"
-      fontWeight="700"
-      fill={alt}
-    >
-      .*
-    </text>
-  ),
-  // Three residues of a chain, one of them the ligand you came for.
-  pdb: (alt) => (
-    <>
-      <g
-        stroke="#ffffff"
-        strokeWidth="1.9"
-        strokeLinecap="round"
-        fill="none"
-        opacity="0.85"
-      >
-        <path d="M9.2 12.4 22 15.4 15.6 23Z" />
-      </g>
-      <circle cx="9.2" cy="12.4" r="3.1" fill="#ffffff" />
-      <circle cx="22" cy="15.4" r="3.1" fill="#ffffff" />
-      <circle cx="15.6" cy="23" r="3.1" fill={alt} />
-    </>
-  ),
-  // The site's own favicon: a spectrum, and the one signal being assigned.
-  elucidation: (alt) => (
-    <>
-      <path
-        d="M5 24h4l2-11 2 11h4l2-15 2 15h3l1.5-7 1.5 7"
-        fill="none"
-        stroke="#ffffff"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-      />
-      <circle cx="19" cy="9" r="3" fill={alt} />
-    </>
-  ),
-  // The site's own favicon: the double harpoon, one direction per colour.
-  equilibrium: (alt) => (
-    <g
-      fill="none"
-      strokeWidth="2.5"
-      strokeLinecap="round"
-      strokeLinejoin="round"
-    >
-      <path d="M6.5 12.5h17l-4-4" stroke="#ffffff" />
-      <path d="M25.5 19.5h-17l4 4" stroke={alt} />
-    </g>
-  ),
-  // A chain of monomers, one of them the comonomer written into it.
-  polycarp: (alt) => (
-    <>
-      <path
-        d="M6.5 20 12.5 12 19.5 20 25.5 12"
-        fill="none"
-        stroke="#ffffff"
-        strokeWidth="2"
-        strokeLinecap="round"
-        strokeLinejoin="round"
-      />
-      <circle cx="6.5" cy="20" r="3" fill="#ffffff" />
-      <circle cx="12.5" cy="12" r="3" fill="#ffffff" />
-      <circle cx="19.5" cy="20" r="3" fill={alt} />
-      <circle cx="25.5" cy="12" r="3" fill="#ffffff" />
-    </>
-  ),
-};

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

package/src/format/core/units.ts

@@ -0,0 +1,60 @@
+import { MISSING_VALUE } from './missing.ts';
+
+const BYTE_UNITS = ['B', 'kB', 'MB', 'GB', 'TB', 'PB'] as const;
+const BYTES_PER_UNIT = 1024;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+
+/**
+ * A byte count in the largest unit that keeps it under a thousand: `512 B`,
+ * `1.5 kB`, `240 MB`.
+ *
+ * Bytes are whole; every larger unit keeps one decimal until the number
+ * reaches a hundred, where the decimal stops carrying information.
+ * @param bytes - The size in bytes.
+ * @returns The size and its unit, or the missing marker when there is no finite, non-negative size.
+ */
+export function formatBytes(bytes: number | undefined): string {
+  if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0) {
+    return MISSING_VALUE;
+  }
+  let value = bytes;
+  let unitIndex = 0;
+  while (value >= BYTES_PER_UNIT && unitIndex < BYTE_UNITS.length - 1) {
+    value /= BYTES_PER_UNIT;
+    unitIndex += 1;
+  }
+  const digits = unitIndex === 0 || value >= 100 ? 0 : 1;
+  return `${value.toFixed(digits)} ${BYTE_UNITS[unitIndex] ?? 'B'}`;
+}
+
+/**
+ * A duration written with its two largest units: `45s`, `3m 20s`, `2h 05m`.
+ * @param milliseconds - The duration in milliseconds.
+ * @returns The duration, or the missing marker when there is no finite, non-negative duration.
+ */
+export function formatDuration(milliseconds: number | undefined): string {
+  if (
+    milliseconds === undefined ||
+    !Number.isFinite(milliseconds) ||
+    milliseconds < 0
+  ) {
+    return MISSING_VALUE;
+  }
+  const seconds = Math.round(milliseconds / 1000);
+  if (seconds < SECONDS_PER_MINUTE) return `${seconds}s`;
+
+  const minutes = Math.floor(seconds / SECONDS_PER_MINUTE);
+  const remainingSeconds = seconds % SECONDS_PER_MINUTE;
+  if (minutes < MINUTES_PER_HOUR) {
+    return `${minutes}m ${pad(remainingSeconds)}s`;
+  }
+
+  const hours = Math.floor(minutes / MINUTES_PER_HOUR);
+  const remainingMinutes = minutes % MINUTES_PER_HOUR;
+  return `${hours}h ${pad(remainingMinutes)}m`;
+}
+
+function pad(value: number): string {
+  return value.toString().padStart(2, '0');
+}

package/src/format/core/words.ts

@@ -0,0 +1,17 @@
+/**
+ * The noun that agrees with a count.
+ *
+ * Only the noun comes back, never the number, so the caller decides how the
+ * count itself is written: `${formatInteger(n)} ${pluralize(n, 'structure')}`.
+ * @param count - How many there are.
+ * @param singular - The noun for exactly one.
+ * @param plural - The noun for any other count. Defaults to the singular with an `s`.
+ * @returns The singular for a count of one, the plural otherwise.
+ */
+export function pluralize(
+  count: number,
+  singular: string,
+  plural = `${singular}s`,
+): string {
+  return count === 1 ? singular : plural;
+}