react-cheminfo 0.3.0 → 0.4.1

package/src/ecosystem/core/index.ts

@@ -1,3 +1,5 @@
+export { renderEcosystemLinksHtml } from './links.ts';
+export { findSiteByHost, siteById, siteDisplayName } from './lookup.ts';
 export type {
   EcosystemSite,
   SiteId,
@@ -5,3 +7,4 @@ export type {
   SiteName,
 } from './sites.ts';
 export { ECOSYSTEM_SITES, siteUrl } from './sites.ts';
+export { siteThemeColor, siteTokensCss } from './tokens.ts';

package/src/ecosystem/core/links.ts

@@ -0,0 +1,29 @@
+import { ECOSYSTEM_SITES, siteUrl } from './sites.ts';
+
+/**
+ * Every site of the family as a plain list of links, for the `<noscript>` of a
+ * page whose body is an empty root element.
+ *
+ * A crawler that runs no script sees nothing else of the page, so this is the
+ * only path it has from one of our tools to the next — and each entry carries
+ * the line saying what it opens, as real text.
+ * @returns The `<ul>`, for the caller to place inside its own `<noscript>`.
+ */
+export function renderEcosystemLinksHtml(): string {
+  let html = '<ul class="ecosystem-links">\n';
+  for (const site of ECOSYSTEM_SITES) {
+    const href = escapeHtml(siteUrl(site));
+    const host = escapeHtml(site.host);
+    const tagline = escapeHtml(site.tagline);
+    html += `<li><a href="${href}">${host}</a> — ${tagline}</li>\n`;
+  }
+  return `${html}</ul>\n`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}

package/src/ecosystem/core/lookup.ts

@@ -0,0 +1,57 @@
+import type { EcosystemSite, SiteId } from './sites.ts';
+import { ECOSYSTEM_SITES } from './sites.ts';
+
+/**
+ * One site of the family, by the identifier its entry carries.
+ * @param id - The site being asked for.
+ * @returns The site.
+ * @throws {Error} When no site of the family carries that identifier.
+ */
+export function siteById(id: SiteId): EcosystemSite {
+  for (const site of ECOSYSTEM_SITES) {
+    if (site.id === id) return site;
+  }
+  throw new Error(`unknown ecosystem site: ${id}`);
+}
+
+/**
+ * The site's name as prose, for a page title, a card or a citation.
+ *
+ * An address-shaped name is written as the address it is — `3d` and `cheminfo`
+ * are two halves of `3d.cheminfo.org`, and joining them would read `3dcheminfo`
+ * — while a product-shaped one is its two halves run together, as its wordmark
+ * sets them.
+ * @param site - The site being named.
+ * @returns What the site is called, in one string.
+ */
+export function siteDisplayName(site: EcosystemSite): string {
+  return site.name.dot === true
+    ? site.host
+    : `${site.name.lead}${site.name.alt}`;
+}
+
+/**
+ * The site a page is being served from, so a header can mark itself as the
+ * current one without being told which site it belongs to.
+ *
+ * The host is whatever the browser reports, so it may carry a port and may or
+ * may not carry the `www.` two of our sites are written with. Neither changes
+ * which site it is, and a host belonging to nobody — a development server, a
+ * preview deployment — is simply not one of ours.
+ * @param host - What `location.host` reads, or any host-shaped string.
+ * @returns The site served from that host, or undefined for any other host.
+ */
+export function findSiteByHost(host: string): EcosystemSite | undefined {
+  const wanted = normalizeHost(host);
+  if (wanted === '') return undefined;
+
+  for (const site of ECOSYSTEM_SITES) {
+    if (normalizeHost(site.host) === wanted) return site;
+  }
+  return undefined;
+}
+
+function normalizeHost(host: string): string {
+  const withoutPort = host.trim().toLowerCase().split(':', 1)[0] ?? '';
+  return withoutPort.startsWith('www.') ? withoutPort.slice(4) : withoutPort;
+}

package/src/ecosystem/core/sites.ts

@@ -14,7 +14,7 @@ export type SiteId =
   | 'equilibrium'
   | 'polycarp'
   | '3d'
-  | 'pt';
+  | 'periodic-table';
 
 export interface SiteName {
   /** First half of the name, set in the site's leading colour. */
@@ -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,15 +203,17 @@ 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',
     mark: { plate: '#155e75', accent: '#f97316' },
   },
   {
-    id: 'pt',
-    name: { lead: 'pt', alt: 'cheminfo', dot: true },
-    host: 'pt.cheminfo.org',
+    id: 'periodic-table',
+    name: { lead: 'Periodic', alt: 'Table' },
+    host: 'periodic-table.cheminfo.org',
+    repository: 'https://github.com/cheminfo/periodic-table.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/glyphs.tsx

@@ -214,7 +214,7 @@ export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
   // The stepped corner of the table, with the one cell a visitor has picked
   // carrying the accent — which is what every tool of that site is: the table,
   // and one element read off it.
-  pt: (alt) => (
+  'periodic-table': (alt) => (
     <>
       <g fill="#ffffff" opacity="0.55">
         <rect x="5" y="6" width="5" height="5" rx="1" />

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';