react-cheminfo 0.33.0 → 0.35.0

package/src/about/ui/AboutVersion.tsx

@@ -14,17 +14,11 @@ import {
   buildLabel,
   buildStamp,
   buildSummary,
-  releasedVersion,
 } from '../../build/core/buildInfo.ts';
-import { githubSources } from '../core/repository.ts';
 
 export interface AboutVersionProps {
   /** What the build published about itself, or `undefined` when it published none. */
   build: BuildInfo | undefined;
-  /** Where the sources live, which is what the badge links into. */
-  repository: string;
-  /** Whether a visitor can open that repository, and so whether it is linked. */
-  publicRepository: boolean;
 }
 
 /**
@@ -34,53 +28,24 @@ export interface AboutVersionProps {
  * @returns The badge, or `null` when the build says nothing worth showing.
  */
 export function AboutVersion(props: AboutVersionProps): ReactElement | null {
-  const { build, repository, publicRepository } = props;
+  const { build } = props;
   const label = buildLabel(build);
   if (build === undefined || label === undefined) return null;
-  const href = publicRepository ? addressOf(build, repository) : undefined;
-  const summary = buildSummary(build);
   // The instant belongs on the badge rather than in its hover: a version
   // nobody can date says nothing about how old the page they read is.
   const badge = `${label} · ${buildStamp(build.builtAt)}`;
-  if (href === undefined) {
-    return (
-      <span style={BADGE_STYLE} className="about-version" title={summary}>
-        {badge}
-      </span>
-    );
-  }
 
   return (
-    <a
+    <span
+      style={BADGE_STYLE}
       className="about-version"
-      href={href}
-      title={summary}
-      target="_blank"
-      rel="noopener noreferrer"
-      style={LINK_BADGE_STYLE}
+      title={buildSummary(build)}
     >
       {badge}
-    </a>
+    </span>
   );
 }
 
-/**
- * What the badge opens: the release it names, or the commit it was built from.
- * @param build - What the build published about itself.
- * @param repository - Where the sources live.
- * @returns The address, or `undefined` when nothing inside the repository can
- * be addressed.
- */
-function addressOf(build: BuildInfo, repository: string): string | undefined {
-  const sources = githubSources(repository);
-  if (sources === undefined) return undefined;
-  const version = releasedVersion(build);
-  if (version !== undefined) return `${sources}/releases/tag/v${version}`;
-  return build.commit === undefined
-    ? undefined
-    : `${sources}/commit/${build.commit}`;
-}
-
 const BADGE_STYLE = {
   flex: '0 0 auto',
   fontFamily: 'var(--font-mono, ui-monospace, monospace)',
@@ -88,8 +53,3 @@ const BADGE_STYLE = {
   color: 'var(--text-muted)',
   whiteSpace: 'nowrap',
 } as const satisfies CSSProperties;
-
-const LINK_BADGE_STYLE = {
-  ...BADGE_STYLE,
-  color: 'var(--accent)',
-} as const satisfies CSSProperties;

package/src/axis/core/axisMarks.ts

@@ -0,0 +1,114 @@
+/**
+ * Where a figure's marks land inside its box, so something else can count them.
+ *
+ * `emptiestCorner` picks the corner a floating card can sit in without covering
+ * the cluster the reader came for, and it needs screen positions to do it. A
+ * chart drawn by a library builds its scales during its own render, where a
+ * caller cannot reach them, so the positions are worked out here from the same
+ * values and the same two transforms the axes use.
+ *
+ * It is an estimate, which is all a corner needs: the plot area is inset from
+ * the box by the margins, and a mark a few pixels from a corner counts for that
+ * corner either way.
+ */
+
+import type { AxisScale } from './axisScale.ts';
+
+/** A point of the figure, in the quantities its axes carry. */
+export interface AxisPoint {
+  x: number;
+  y: number;
+}
+
+/** Pixel positions of every mark, as `emptiestCorner` reads them. */
+export interface AxisMarkPositions {
+  x: Float64Array;
+  y: Float64Array;
+}
+
+/** What {@link axisMarkPositions} needs beyond the points and the box. */
+export interface AxisMarkPositionsOptions {
+  /**
+   * Width of the linear region of a logarithmic axis — d3's symmetric-log
+   * `constant`. Pass `0` for a true logarithmic axis.
+   * @default 1
+   */
+  constant?: number;
+}
+
+/**
+ * Place every point in the box the figure is drawn in.
+ * @param points - The points the figure draws.
+ * @param box - Its size, in pixels, normally from `useContainerSize`.
+ * @param box.width - How wide the figure is drawn.
+ * @param box.height - How tall it is drawn.
+ * @param scale - The scale each axis is drawn on, which the positions have to
+ *   follow to land where the marks do.
+ * @param scale.y - How the vertical axis is read.
+ * @param scale.x - How the horizontal axis is read.
+ * @param options - See {@link AxisMarkPositionsOptions}.
+ * @returns One position per point, in the order they were given.
+ */
+export function axisMarkPositions(
+  points: readonly AxisPoint[],
+  box: { width: number; height: number },
+  scale: { x: AxisScale; y: AxisScale },
+  options: AxisMarkPositionsOptions = {},
+): AxisMarkPositions {
+  const { constant = 1 } = options;
+  const x = new Float64Array(points.length);
+  const y = new Float64Array(points.length);
+
+  place(points, 'x', scale.x === 'log', constant, box.width, x);
+  place(points, 'y', scale.y === 'log', constant, box.height, y);
+  // The vertical axis grows upwards while the box is measured from its top.
+  for (let index = 0; index < y.length; index++) {
+    y[index] = box.height - (y[index] as number);
+  }
+  return { x, y };
+}
+
+function place(
+  points: readonly AxisPoint[],
+  axis: 'x' | 'y',
+  logarithmic: boolean,
+  constant: number,
+  extent: number,
+  into: Float64Array,
+): void {
+  let min = Infinity;
+  let max = -Infinity;
+  for (let index = 0; index < points.length; index++) {
+    const value = transform(
+      (points[index] as AxisPoint)[axis],
+      logarithmic,
+      constant,
+    );
+    into[index] = value;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+
+  const span = max - min;
+  for (let index = 0; index < into.length; index++) {
+    const value = (into[index] as number) - min;
+    into[index] = span === 0 ? extent / 2 : (value / span) * extent;
+  }
+}
+
+/**
+ * d3's symmetric log, which is the one a genuine zero survives.
+ * @param value - The value to place.
+ * @param logarithmic - Whether the axis is read logarithmically at all.
+ * @param constant - Width of its linear region.
+ * @returns The value in the units the axis is spaced in.
+ */
+function transform(
+  value: number,
+  logarithmic: boolean,
+  constant: number,
+): number {
+  if (!logarithmic) return value;
+  const width = constant > 0 ? constant : 1;
+  return Math.sign(value) * Math.log1p(Math.abs(value) / width);
+}

package/src/axis/core/axisScale.ts

@@ -0,0 +1,41 @@
+/**
+ * Which of the two scales a quantity is read on, and who decided.
+ *
+ * Every quantity has a scale it is usually read on — a concentration spanning
+ * ten decades is read logarithmically, a first ionisation energy linearly — and
+ * a reader may overrule it. The two are kept apart rather than collapsed into
+ * one boolean, because a figure that forgets which it is holding gets both of
+ * the following wrong: picking another quantity has to bring that quantity's
+ * own scale rather than carry the last one over, and a link has to stay silent
+ * about a scale nobody chose, so that it keeps opening the way the quantity is
+ * read even after the usual scale is reconsidered.
+ */
+
+/** The two scales an axis is drawn on. */
+export type AxisScale = 'linear' | 'log';
+
+/** A reader's choice, or `null` while they have not made one. */
+export type AxisScaleChoice = AxisScale | null;
+
+/**
+ * The scale an axis is actually drawn on.
+ * @param usual - How the quantity on the axis is normally read.
+ * @param chosen - What the reader asked for, or `null` to leave it to the
+ *   quantity.
+ * @returns The scale to draw.
+ */
+export function resolveAxisScale(
+  usual: AxisScale,
+  chosen: AxisScaleChoice,
+): AxisScale {
+  return chosen ?? usual;
+}
+
+/**
+ * Narrow an arbitrary string — one off a query parameter — to a scale.
+ * @param value - Candidate scale.
+ * @returns True when it is one of the two.
+ */
+export function isAxisScale(value: string): value is AxisScale {
+  return value === 'linear' || value === 'log';
+}

package/src/axis/core/index.ts

@@ -0,0 +1,20 @@
+/**
+ * How an axis is read: linearly or logarithmically, who decided, where it
+ * starts and ends, and where its marks land.
+ *
+ * It is a domain of its own rather than part of any chart, because the library
+ * draws figures with three different renderers and the sites draw more with
+ * libraries of their own — and the two things that go wrong on a logarithmic
+ * axis go wrong the same way in all of them.
+ */
+
+export type {
+  AxisMarkPositions,
+  AxisMarkPositionsOptions,
+  AxisPoint,
+} from './axisMarks.ts';
+export { axisMarkPositions } from './axisMarks.ts';
+export type { AxisScale, AxisScaleChoice } from './axisScale.ts';
+export { isAxisScale, resolveAxisScale } from './axisScale.ts';
+export type { LogAxisBounds, LogAxisBoundsOptions } from './logAxisBounds.ts';
+export { logAxisBounds } from './logAxisBounds.ts';

package/src/axis/core/logAxisBounds.ts

@@ -0,0 +1,198 @@
+/**
+ * The ends of a logarithmic axis, and the values it is graduated at.
+ *
+ * Both have to be stated rather than left to the charting library, and for two
+ * separate reasons.
+ *
+ * The ends, because a library that finds them itself may not look at every
+ * value. nivo is the measured case: it sorts and takes a true minimum and
+ * maximum only for a linear axis, and on a log or symmetric-log one `'auto'`
+ * resolves to the first value the data carries and the last — so the domain
+ * comes out in plotting order, upside down whenever the first point outweighs
+ * the last, and cutting off everything past the last point drawn.
+ *
+ * The graduations, because d3 rules a symmetric-log axis at evenly *spaced*
+ * values while placing them logarithmically, so the top of a wide axis collects
+ * every graduation it has into one unreadable line. Ruling it by decade spreads
+ * them evenly, which is also how such a quantity is read.
+ */
+
+/** What {@link logAxisBounds} answers. */
+export interface LogAxisBounds {
+  /** The low end of the axis. */
+  min: number;
+  /** The high end. */
+  max: number;
+  /**
+   * The values to rule it at, or `undefined` for an axis spanning too few
+   * decades to be worth ruling by them — there the library's own linear
+   * graduations read better, and there is no pile-up to undo.
+   */
+  tickValues?: number[];
+}
+
+/** What {@link logAxisBounds} needs beyond the values. */
+export interface LogAxisBoundsOptions {
+  /**
+   * Width of the linear region at the bottom of a symmetric-log axis — d3's
+   * `constant`. Everything smaller than it is placed almost on the zero line,
+   * so no graduation is written below it; a graduation there would land on top
+   * of the one before it, which is the pile-up this exists to prevent.
+   *
+   * Pass `0` for a true logarithmic axis, which has no such region — and which
+   * cannot place a zero or a negative at all, so those values are then left out
+   * of the ends rather than dragging them to nothing.
+   * @default 1
+   */
+  constant?: number;
+  /**
+   * Whether the ends are rounded outwards to whole powers of ten. An axis that
+   * ends on its own extreme values reads as though those were round numbers;
+   * one that ends on decades says what it is. Worth it on a true logarithmic
+   * axis, where every graduation is a decade anyway.
+   * @default false — the ends are the data's own
+   */
+  snapToDecades?: boolean;
+  /**
+   * How many decades the axis may span at most, counted down from its top. A
+   * quantity that reaches zero asymptotically has no meaningful bottom, and an
+   * axis given one spends most of its height on values nobody is reading.
+   * Only consulted with `snapToDecades`.
+   * @default Infinity — the axis spans whatever the data does
+   */
+  maxDecades?: number;
+  /**
+   * How many graduations the axis may carry. More than this is a smear however
+   * they are spread, so the decades are stepped over rather than written out.
+   * @default 10
+   */
+  mostTicks?: number;
+}
+
+/** Under this many decades the library's own graduations read better. */
+const RULE_PAST_DECADES = 3;
+
+/**
+ * Where a logarithmic axis starts and ends, and where it is graduated.
+ * @param values - Every value plotted on the axis. Anything not finite is
+ *   ignored, so a sheet's gaps need not be filtered out first.
+ * @param options - See {@link LogAxisBoundsOptions}.
+ * @returns The ends and the graduations, or `null` when no value can be drawn
+ *   and the caller should leave the axis to its library.
+ */
+export function logAxisBounds(
+  values: Iterable<number>,
+  options: LogAxisBoundsOptions = {},
+): LogAxisBounds | null {
+  const { constant = 1, snapToDecades = false } = options;
+  const { maxDecades = Infinity, mostTicks = 10 } = options;
+  // A true logarithmic axis has no room for a zero or a negative, so they are
+  // not what its bottom end is taken from.
+  const positiveOnly = constant === 0;
+
+  let min = Infinity;
+  let max = -Infinity;
+  for (const value of values) {
+    if (!Number.isFinite(value)) continue;
+    if (positiveOnly && value <= 0) continue;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  if (min > max) return null;
+
+  if (snapToDecades) {
+    const top = Math.ceil(Math.log10(Math.abs(max) || 1));
+    const bottom = Math.max(
+      Math.floor(Math.log10(Math.abs(min) || 1)),
+      top - maxDecades,
+    );
+    return withTicks(decade(bottom), decade(top), constant, mostTicks);
+  }
+
+  // A lone value, or a column of identical ones, spans nothing: reach to the
+  // origin so it is read against a zero rather than filling the axis.
+  if (min === max) {
+    if (min === 0) return { min: -1, max: 1 };
+    return { min: Math.min(min, 0), max: Math.max(max, 0) };
+  }
+
+  return withTicks(min, max, constant, mostTicks);
+}
+
+/**
+ * The ends, with the graduations when they are worth writing.
+ * @param min
+ * @param max
+ * @param constant
+ * @param mostTicks
+ */
+function withTicks(
+  min: number,
+  max: number,
+  constant: number,
+  mostTicks: number,
+): LogAxisBounds {
+  const ticks = decadesBetween(min, max, constant, mostTicks);
+  return ticks === undefined ? { min, max } : { min, max, tickValues: ticks };
+}
+
+/**
+ * Zero, and the powers of ten the axis both reaches and can separate.
+ * @param min - The low end of the axis.
+ * @param max - Its high end.
+ * @param constant - Width of the linear region; see the options.
+ * @param mostTicks - How many graduations the axis may carry.
+ * @returns The values to rule it at, or nothing to leave it to the library.
+ */
+function decadesBetween(
+  min: number,
+  max: number,
+  constant: number,
+  mostTicks: number,
+): number[] | undefined {
+  const largest = Math.max(Math.abs(min), Math.abs(max));
+  if (largest === 0) return undefined;
+
+  // Below the linear region every decade lands on the same pixel, so the axis
+  // is ruled from there up rather than from its smallest value.
+  const floor = constant > 0 ? Math.log10(constant) : smallestDecade(min, max);
+  const bottom = Math.ceil(floor);
+  const top = Math.floor(Math.log10(largest));
+  // Under a few decades the library's own graduations read better — but only
+  // where it has linear ones to offer. On a true logarithmic axis every
+  // graduation is a decade, so a short one is still ruled by decade.
+  if (constant > 0 && top - bottom + 1 < RULE_PAST_DECADES) return undefined;
+
+  const step = Math.ceil((top - bottom + 1) / mostTicks);
+  const ticks = min <= 0 && max >= 0 ? [0] : [];
+  for (let power = bottom; power <= top; power += step) {
+    const tick = decade(power);
+    if (tick >= min && tick <= max) ticks.push(tick);
+  }
+  if (constant === 0) return ticks;
+  return ticks.length < RULE_PAST_DECADES ? undefined : ticks;
+}
+
+/**
+ * A whole power of ten.
+ * @param power - The exponent, a whole number.
+ * @returns Ten to that power, the same bits on every engine.
+ */
+function decade(power: number): number {
+  // Read as a decimal rather than computed: `10 ** power` goes through pow,
+  // which is not bit-exact across V8 versions — node 22 answers
+  // 0.00009999999999999999 for -4 and 1.0000000000000001e-20 for -20 — while a
+  // decimal literal is the correctly-rounded double everywhere.
+  return Number(`1e${power}`);
+}
+
+/**
+ * The decade of the smaller end, for an axis with no linear region.
+ * @param min - The low end of the axis.
+ * @param max - Its high end.
+ * @returns The base-ten logarithm of the smaller end that is not zero.
+ */
+function smallestDecade(min: number, max: number): number {
+  const ends = [Math.abs(min), Math.abs(max)].filter((end) => end > 0);
+  return Math.log10(Math.min(...ends));
+}

package/src/axis/ui/AxisScaleControl.tsx

@@ -0,0 +1,103 @@
+/**
+ * The control that moves one axis between its two scales.
+ *
+ * It belongs on the figure rather than in the page around it: the scale is not
+ * a property of the page but of the picture, a reader decides to change it
+ * while looking at the picture, and a figure handed out on its own — embedded
+ * in a course page, pasted into a deck — takes its controls with it. So it is
+ * written as a control of an `OverlayBar`, floating in whichever corner the
+ * marks leave emptiest.
+ *
+ * Its two segments are named here rather than by each site, because `Linear`
+ * and `Log` are chrome: one translation reaches every figure in the family.
+ */
+
+import type { ReactElement } from 'react';
+
+import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import type { AxisScale } from '../core/axisScale.ts';
+
+/** Which axis a control belongs to, which is how it names itself. */
+export type AxisScaleAxis = 'x' | 'y';
+
+/** What {@link AxisScaleControl} needs. */
+export interface AxisScaleControlProps {
+  /** The scale in force — what `resolveAxisScale` answered, not the choice. */
+  value: AxisScale;
+  /** Called with the scale the reader picked. */
+  onChange: (scale: AxisScale) => void;
+  /**
+   * Which axis it sets, which names it `X scale` or `Y scale`. Leave it out on
+   * a figure where only one axis offers the choice: the control is then simply
+   * `Scale`, because naming the axis is only worth the width when there are two
+   * of them to tell apart.
+   * @default undefined — the control is named `Scale`
+   */
+  axis?: AxisScaleAxis;
+  /**
+   * What it is called, overriding both of the above. For a figure whose axis
+   * has a name the reader already knows it by.
+   * @default the chrome's own word, in the language of the page
+   */
+  label?: string;
+  /**
+   * What the two scales do, in a sentence.
+   * @default the chrome's own explanation
+   */
+  help?: HelpContent;
+  /**
+   * Whether the name is announced but not written.
+   * @default false
+   */
+  hideLabel?: boolean;
+  /**
+   * Whether the control is greyed and unreachable.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Value of the `data-testid` attribute.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The two scales, the one in force pressed.
+ * @param props - See {@link AxisScaleControlProps}.
+ * @returns The named pair of segments.
+ */
+export function AxisScaleControl(props: AxisScaleControlProps): ReactElement {
+  const { value, onChange, axis, label, help, testId } = props;
+  const { hideLabel = false, disabled = false } = props;
+  const t = useChromeT();
+
+  const options: ReadonlyArray<OverlayOption<AxisScale>> = [
+    { value: 'linear', label: t('axis.linear') },
+    { value: 'log', label: t('axis.logarithmic') },
+  ];
+
+  return (
+    <OverlaySegmented<AxisScale>
+      label={label ?? t(nameOf(axis))}
+      help={help ?? { title: t('axis.scale'), body: t('axis.scaleHelp') }}
+      hideLabel={hideLabel}
+      disabled={disabled}
+      value={value}
+      options={options}
+      onChange={onChange}
+      testId={testId}
+    />
+  );
+}
+
+function nameOf(
+  axis: AxisScaleAxis | undefined,
+): 'axis.scale' | 'axis.xScale' | 'axis.yScale' {
+  if (axis === 'x') return 'axis.xScale';
+  if (axis === 'y') return 'axis.yScale';
+  return 'axis.scale';
+}

package/src/axis/ui/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The controls that say how an axis is read.
+ */
+
+export type {
+  AxisScaleAxis,
+  AxisScaleControlProps,
+} from './AxisScaleControl.tsx';
+export { AxisScaleControl } from './AxisScaleControl.tsx';

package/src/core.ts

@@ -1,4 +1,5 @@
 export * from './about/core/index.ts';
+export * from './axis/core/index.ts';
 export * from './build/core/index.ts';
 export * from './chart/core/index.ts';
 export * from './citation/core/index.ts';

package/src/delimited/core/index.ts

@@ -8,3 +8,5 @@ export type { ReadDelimitedOptions } from './readDelimited.ts';
 export { detectDelimiter, readDelimited } from './readDelimited.ts';
 export type { ToDelimitedOptions } from './toDelimited.ts';
 export { escapeCell, toDelimited } from './toDelimited.ts';
+export type { TableRecord, TableRows, TableRowsOptions } from './tableRows.ts';
+export { columnsOf, tableRows } from './tableRows.ts';

package/src/delimited/core/tableRows.ts

@@ -0,0 +1,93 @@
+/**
+ * Turning a list of records into the cells a table is handed over as.
+ *
+ * Most pages hold their data as one object per row — a query result, a list of
+ * peaks, a row of properties — while a delimited table is cells. Every site
+ * that exports such a list wrote the same two loops, so they are here once.
+ */
+
+/** One record, as a page holds it before it becomes a row of cells. */
+export type TableRecord = Record<string, unknown>;
+
+/** How a record becomes cells. */
+export interface TableRowsOptions {
+  /**
+   * The columns to write, in order. A column no record carries comes out
+   * empty, which is what lets one caller pin the order of a table whose first
+   * record happens to be missing a field.
+   * @default the keys of the first record, in the order it declares them
+   */
+  columns?: readonly string[];
+  /**
+   * How a value becomes a cell.
+   * @default `String(value)`, with `null` and `undefined` written as nothing
+   */
+  format?: (value: unknown, column: string) => string;
+}
+
+/** The columns, and the cells under them. */
+export interface TableRows {
+  /** Column names, in the order the cells are written. */
+  header: string[];
+  /** One array of cells per record. */
+  rows: string[][];
+}
+
+/**
+ * The records as the header and cells of a table.
+ * @param records - The records, in the order they are shown.
+ * @param options - See {@link TableRowsOptions}.
+ * @returns See {@link TableRows}.
+ */
+export function tableRows(
+  records: readonly TableRecord[],
+  options: TableRowsOptions = {},
+): TableRows {
+  const { columns, format = defaultCell } = options;
+  const header = [...(columns ?? columnsOf(records))];
+  const rows: string[][] = [];
+  for (const record of records) {
+    const cells: string[] = [];
+    for (const column of header) cells.push(format(record[column], column));
+    rows.push(cells);
+  }
+  return { header, rows };
+}
+
+/**
+ * Every column the records carry, each named once, in the order first seen.
+ *
+ * Every record is read rather than only the first, because a list whose later
+ * records carry a field the first one happens to lack would otherwise be
+ * handed over with that column silently missing.
+ * @param records - The records.
+ * @returns The column names.
+ */
+export function columnsOf(records: readonly TableRecord[]): string[] {
+  const columns: string[] = [];
+  const seen = new Set<string>();
+  for (const record of records) {
+    for (const column of Object.keys(record)) {
+      if (seen.has(column)) continue;
+      seen.add(column);
+      columns.push(column);
+    }
+  }
+  return columns;
+}
+
+function defaultCell(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (
+    typeof value === 'number' ||
+    typeof value === 'bigint' ||
+    typeof value === 'boolean'
+  ) {
+    return String(value);
+  }
+  // Anything else left in a cell has no honest text form, and `[object Object]`
+  // is the one answer a spreadsheet can do nothing with. JSON at least says
+  // what was there; a caller who wants better passes `format`.
+  return JSON.stringify(value) ?? '';
+}