react-cheminfo 0.9.0 → 0.10.0

package/src/color/core/interpolate.ts

@@ -0,0 +1,179 @@
+import type { ReadableInkOptions } from './contrast.ts';
+import { readableInk } from './contrast.ts';
+import { parseHexColor, toHexColor } from './hex.ts';
+import { hsvToRgb, rgbToHsv, wrapHue } from './hsv.ts';
+
+const HALF_TURN = 180;
+const TURN = 360;
+const MINIMUM_SAMPLES = 2;
+
+/** A colour, and the ink that stays readable on it. */
+export interface Swatch {
+  /** The colour behind the value. */
+  background: string;
+  /** The ink to write the value in. */
+  foreground: string;
+}
+
+/** One anchor of a colour scale: a colour, and where it sits. */
+export interface ColorStop {
+  /** Where it sits on the scale, from 0 for its low end to 1 for its high end. */
+  position: number;
+  /** The colour there, as `#rgb` or `#rrggbb`. */
+  color: string;
+}
+
+/**
+ * The path a scale takes from one anchor to the next.
+ *
+ * - `rgb` mixes the three channels, which is what a browser gradient does and
+ *   what a perceptual map such as viridis is sampled for.
+ * - `hsv` turns along the colour wheel the short way round, so two anchors
+ *   already describe a ramp that keeps its saturation instead of fading
+ *   through the grey in the middle of the straight line between them.
+ * - `hsv-long` turns the other way round, which is how two anchors of the same
+ *   hue draw a full rainbow.
+ */
+export type ColorInterpolation = 'rgb' | 'hsv' | 'hsv-long';
+
+/** A colour scale: its anchors, and how it moves between them. */
+export interface ColorScale {
+  /** The anchors, in ascending position order. */
+  stops: readonly ColorStop[];
+  /** How it moves from one anchor to the next. */
+  interpolation: ColorInterpolation;
+}
+
+/**
+ * A scale whose colours are spread evenly from one end to the other.
+ * @param colors - The colours, from the low end to the high end.
+ * @param interpolation - The path between them.
+ * @returns The scale they describe.
+ */
+export function evenScale(
+  colors: readonly string[],
+  interpolation: ColorInterpolation = 'rgb',
+): ColorScale {
+  const stops: ColorStop[] = [];
+  const last = colors.length - 1;
+  for (let index = 0; index < colors.length; index++) {
+    const color = colors[index];
+    if (color === undefined) continue;
+    stops.push({ position: last <= 0 ? 0 : index / last, color });
+  }
+  return { stops, interpolation };
+}
+
+/**
+ * The colour a scale takes at a position.
+ * @param scale - The scale to read, its anchors in ascending position order.
+ * @param position - Where to read it, from 0 to 1; anything outside is clamped.
+ * @returns The colour there, as `#rrggbb`.
+ * @throws {Error} When the scale has no anchor, or one of them is not a hex colour.
+ */
+export function colorAt(scale: ColorScale, position: number): string {
+  const { stops, interpolation } = scale;
+  if (stops.length === 0) {
+    throw new Error('a colour scale needs at least one stop');
+  }
+  const at = clampUnit(position);
+  const first = stops[0];
+  const last = stops.at(-1);
+  if (first === undefined || last === undefined) {
+    throw new Error(`no colour at position ${String(position)}`);
+  }
+  if (at <= first.position) return toHexColor(parseHexColor(first.color));
+  if (at >= last.position) return toHexColor(parseHexColor(last.color));
+
+  for (let index = 1; index < stops.length; index++) {
+    const start = stops[index - 1];
+    const end = stops[index];
+    if (start === undefined || end === undefined) continue;
+    if (at > end.position) continue;
+    const span = end.position - start.position;
+    const ratio = span <= 0 ? 0 : (at - start.position) / span;
+    return mix(start.color, end.color, ratio, interpolation);
+  }
+  return toHexColor(parseHexColor(last.color));
+}
+
+/**
+ * The colour a scale takes at a position, with the ink to write on it.
+ * @param scale - The scale to read.
+ * @param position - Where to read it, from 0 to 1; anything outside is clamped.
+ * @param options - See {@link ReadableInkOptions}.
+ * @returns The background and the readable ink.
+ * @throws {Error} When the scale has no anchor, or one of them is not a hex colour.
+ */
+export function swatchAt(
+  scale: ColorScale,
+  position: number,
+  options: ReadableInkOptions = {},
+): Swatch {
+  const background = colorAt(scale, position);
+  return { background, foreground: readableInk(background, options) };
+}
+
+/**
+ * A scale read at evenly spaced positions, for a gradient or a legend.
+ * @param scale - The scale to read.
+ * @param count - How many colours to take, both ends included; fewer than two is read as two.
+ * @returns The colours, from the low end to the high end.
+ * @throws {Error} When the scale has no anchor, or one of them is not a hex colour.
+ */
+export function sampleScale(scale: ColorScale, count: number): string[] {
+  const total = Number.isFinite(count)
+    ? Math.max(MINIMUM_SAMPLES, Math.floor(count))
+    : MINIMUM_SAMPLES;
+  const colors: string[] = [];
+  for (let index = 0; index < total; index++) {
+    colors.push(colorAt(scale, index / (total - 1)));
+  }
+  return colors;
+}
+
+function mix(
+  start: string,
+  end: string,
+  ratio: number,
+  interpolation: ColorInterpolation,
+): string {
+  const from = parseHexColor(start);
+  const to = parseHexColor(end);
+  if (interpolation === 'rgb') {
+    return toHexColor({
+      red: from.red + (to.red - from.red) * ratio,
+      green: from.green + (to.green - from.green) * ratio,
+      blue: from.blue + (to.blue - from.blue) * ratio,
+    });
+  }
+
+  const one = rgbToHsv(from);
+  const other = rgbToHsv(to);
+  const hue = one.hue + hueStep(one.hue, other.hue, interpolation) * ratio;
+  return toHexColor(
+    hsvToRgb({
+      hue: wrapHue(hue),
+      saturation: one.saturation + (other.saturation - one.saturation) * ratio,
+      value: one.value + (other.value - one.value) * ratio,
+    }),
+  );
+}
+
+function hueStep(
+  from: number,
+  to: number,
+  interpolation: ColorInterpolation,
+): number {
+  const short = (((to - from) % TURN) + TURN + HALF_TURN) % TURN;
+  const shortest = short - HALF_TURN;
+  if (interpolation !== 'hsv-long') return shortest;
+  // Two anchors of the same hue are a full turn apart the long way round,
+  // which is what draws a rainbow from one colour back to itself.
+  return shortest > 0 ? shortest - TURN : shortest + TURN;
+}
+
+function clampUnit(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}

package/src/color/core/scale.ts

@@ -1,32 +1,18 @@
 import type { ReadableInkOptions } from './contrast.ts';
-import { readableInk } from './contrast.ts';
-import { parseHexColor, toHexColor } from './hex.ts';
+import type { Swatch } from './interpolate.ts';
+import { colorAt, evenScale, swatchAt } from './interpolate.ts';
+import { VIRIDIS_COLORS } from './scaleData.ts';
+
+export type { Swatch } from './interpolate.ts';
 
 /**
  * Viridis, sampled at nine stops.
  *
  * It stays readable under the common colour deficiencies and is monotone in
  * lightness, so a greyscale print of the same figure still orders the values.
+ * It is the default of `COLOR_SCALES`, which is where the others are.
  */
-export const VIRIDIS_SCALE: readonly string[] = [
-  '#440154',
-  '#482878',
-  '#3e4a89',
-  '#31688e',
-  '#26828e',
-  '#1f9e89',
-  '#35b779',
-  '#6dcd59',
-  '#b4de2c',
-];
-
-/** A colour, and the ink that stays readable on it. */
-export interface Swatch {
-  /** The colour behind the value. */
-  background: string;
-  /** The ink to write the value in. */
-  foreground: string;
-}
+export const VIRIDIS_SCALE: readonly string[] = VIRIDIS_COLORS;
 
 /** How {@link positionInRange} places a value. */
 export interface PositionInRangeOptions {
@@ -73,51 +59,33 @@ export function positionInRange(
 }
 
 /**
- * The colour a scale takes at a position, interpolated between its stops.
- * @param stops - The scale's colours, from its low end to its high end, as `#rgb` or `#rrggbb`.
- * @param position - Where on the scale to read, from 0 to 1; anything outside is clamped.
+ * The colour a list of evenly spread colours takes at a position.
+ * @param stops - The colours, from the low end to the high end, as `#rgb` or `#rrggbb`.
+ * @param position - Where to read, from 0 to 1; anything outside is clamped.
  * @returns The colour at that position, as `#rrggbb`.
- * @throws {Error} When the scale has no stops, or a stop is not a hex colour.
+ * @throws {Error} When the list is empty, or a colour is not a hex colour.
  */
 export function colorFromScale(
   stops: readonly string[],
   position: number,
 ): string {
-  if (stops.length === 0) {
-    throw new Error('a colour scale needs at least one stop');
-  }
-  const scaled = clampUnit(position) * (stops.length - 1);
-  const lowerIndex = Math.floor(scaled);
-  const start = stops[lowerIndex];
-  const end = stops[Math.min(lowerIndex + 1, stops.length - 1)];
-  if (start === undefined || end === undefined) {
-    throw new Error(`no colour at position ${String(position)}`);
-  }
-  const from = parseHexColor(start);
-  const to = parseHexColor(end);
-  const ratio = scaled - lowerIndex;
-  return toHexColor({
-    red: from.red + (to.red - from.red) * ratio,
-    green: from.green + (to.green - from.green) * ratio,
-    blue: from.blue + (to.blue - from.blue) * ratio,
-  });
+  return colorAt(evenScale(stops), position);
 }
 
 /**
- * The colour a scale takes at a position, together with the ink to write on it.
- * @param stops - The scale's colours, from its low end to its high end.
- * @param position - Where on the scale to read, from 0 to 1; anything outside is clamped.
+ * The colour a list of evenly spread colours takes, with the ink to write on it.
+ * @param stops - The colours, from the low end to the high end.
+ * @param position - Where to read, from 0 to 1; anything outside is clamped.
  * @param options - See {@link ReadableInkOptions}.
  * @returns The background and the readable ink.
- * @throws {Error} When the scale has no stops, or a stop is not a hex colour.
+ * @throws {Error} When the list is empty, or a colour is not a hex colour.
  */
 export function swatchFromScale(
   stops: readonly string[],
   position: number,
   options: ReadableInkOptions = {},
 ): Swatch {
-  const background = colorFromScale(stops, position);
-  return { background, foreground: readableInk(background, options) };
+  return swatchAt(evenScale(stops), position, options);
 }
 
 function clampUnit(value: number): number {

package/src/color/core/scaleData.ts

@@ -0,0 +1,128 @@
+/*
+ * The colours of the maps the family reads a quantity with, each sampled at
+ * nine evenly spaced stops.
+ *
+ * They are values rather than code: viridis, magma, inferno, plasma and
+ * cividis come from matplotlib (CC0), turbo from Google (Apache-2.0) and the
+ * diverging pair from ColorBrewer (Apache-2.0), all sampled through
+ * `d3-scale-chromatic`. Nine stops interpolated in sRGB reproduce each map
+ * closely enough that no eye separates the two, and keeps a scale a plain list
+ * a legend and a CSS gradient can both be written from.
+ */
+
+/** Viridis: the default, monotone in lightness and safe under colour deficiency. */
+export const VIRIDIS_COLORS: readonly string[] = [
+  '#440154',
+  '#472d7b',
+  '#3b528b',
+  '#2c728e',
+  '#21918c',
+  '#28ae80',
+  '#5ec962',
+  '#addc30',
+  '#fde725',
+];
+
+/** Plasma: purple to yellow, brighter than viridis at the bottom. */
+export const PLASMA_COLORS: readonly string[] = [
+  '#0d0887',
+  '#4c02a1',
+  '#7e03a8',
+  '#aa2395',
+  '#cc4778',
+  '#e66c5c',
+  '#f89540',
+  '#fdc527',
+  '#f0f921',
+];
+
+/** Magma: black to cream through violet and orange. */
+export const MAGMA_COLORS: readonly string[] = [
+  '#000004',
+  '#1d1147',
+  '#51127c',
+  '#832681',
+  '#b73779',
+  '#e75263',
+  '#fc8961',
+  '#fec488',
+  '#fcfdbf',
+];
+
+/** Inferno: black to pale yellow through red, the warmest of the five. */
+export const INFERNO_COLORS: readonly string[] = [
+  '#000004',
+  '#210c4a',
+  '#57106e',
+  '#8a226a',
+  '#bc3754',
+  '#e45a31',
+  '#f98e09',
+  '#f9cb35',
+  '#fcffa4',
+];
+
+/** Cividis: blue to yellow, built to read the same to a deuteranope. */
+export const CIVIDIS_COLORS: readonly string[] = [
+  '#002051',
+  '#11366c',
+  '#3c4d6e',
+  '#62646f',
+  '#7f7c75',
+  '#9a9478',
+  '#bbaf71',
+  '#e2cb5c',
+  '#fdea45',
+];
+
+/** Turbo: the colours of a rainbow, ordered so the lightness still climbs. */
+export const TURBO_COLORS: readonly string[] = [
+  '#23171b',
+  '#4569ee',
+  '#26bce1',
+  '#3ff393',
+  '#95fb51',
+  '#ecd12e',
+  '#ff821d',
+  '#cb2f0d',
+  '#900c00',
+];
+
+/** Greys: light to black, for a figure that will be printed or photocopied. */
+export const GREYS_COLORS: readonly string[] = [
+  '#ebebeb',
+  '#d7d7d7',
+  '#bebebe',
+  '#a0a0a0',
+  '#818181',
+  '#646464',
+  '#444444',
+  '#202020',
+  '#000000',
+];
+
+/** Cool to warm: blue through pale yellow to red, for a quantity with a middle. */
+export const COOL_WARM_COLORS: readonly string[] = [
+  '#313695',
+  '#5382bb',
+  '#90c2dd',
+  '#d1ebef',
+  '#faf8c1',
+  '#fed284',
+  '#f88d52',
+  '#dd4030',
+  '#a50026',
+];
+
+/** Blue to red through white, the diverging map with the palest middle. */
+export const BLUE_RED_COLORS: readonly string[] = [
+  '#053061',
+  '#2a71ae',
+  '#6bacd0',
+  '#bfdceb',
+  '#f2efee',
+  '#faccb4',
+  '#e48268',
+  '#b82d35',
+  '#67001f',
+];

package/src/color/core/scaleText.ts

@@ -0,0 +1,134 @@
+import type {
+  ColorInterpolation,
+  ColorScale,
+  ColorStop,
+} from './interpolate.ts';
+import type { NamedColorScale } from './scales.ts';
+import {
+  COLOR_SCALES,
+  DEFAULT_COLOR_SCALE_ID,
+  colorScaleById,
+} from './scales.ts';
+
+/** How many anchors a link may spell out. */
+export const MAXIMUM_CUSTOM_STOPS = 12;
+
+const HEX_DIGITS = /^(?:[\da-f]{3}|[\da-f]{6})$/;
+const POSITION_DECIMALS = 3;
+const INTERPOLATIONS: readonly ColorInterpolation[] = [
+  'rgb',
+  'hsv',
+  'hsv-long',
+];
+
+/** The scale a piece of text names, whether it named one of ours or spelled out its own. */
+export interface ResolvedColorScale {
+  /** The registry entry it named, or `null` when the text spelled out its own scale. */
+  id: string | null;
+  /** What to call it. */
+  label: string;
+  /** The ramp itself. */
+  scale: ColorScale;
+}
+
+/**
+ * The scale a link, a stored preference or a picker asks for.
+ *
+ * Nothing here throws and nothing is rejected outright: a scale renamed since
+ * the link was written, a colour with a typo in it, a position out of range —
+ * each falls back to the scale the site reads by default, because a link
+ * handed out in a course two years ago must still open the tool.
+ * @param text - A scale id, e.g. `plasma`, or a custom scale as {@link formatColorScale} writes it, e.g. `hsv-long,0-0000ff,1-ff0000`.
+ * @param fallbackId - The scale to read when the text names none.
+ * @returns The scale, and the id when it was one of ours.
+ */
+export function resolveColorScale(
+  text: string | undefined,
+  fallbackId: string = DEFAULT_COLOR_SCALE_ID,
+): ResolvedColorScale {
+  const wanted = (text ?? '').trim().toLowerCase();
+  const named = colorScaleById(wanted);
+  if (named !== undefined) return fromNamed(named);
+
+  const custom = parseColorScale(wanted);
+  if (custom !== null) return { id: null, label: 'Custom', scale: custom };
+
+  const fallback = colorScaleById(fallbackId) ?? COLOR_SCALES[0];
+  if (fallback === undefined) {
+    throw new Error('no colour scale is registered');
+  }
+  return fromNamed(fallback);
+}
+
+/**
+ * Read a custom scale out of the text a link carries.
+ *
+ * Everything in it is comma-separated, and a browser escapes none of it, so
+ * the link a teacher hands out stays the one they can read and retype.
+ * @param text - The path, then the anchors, e.g. `hsv-long,0-0000ff,1-ff0000`. The path may be left out, and is then `rgb`.
+ * @returns The scale, or `null` when the text does not spell out at least two usable anchors.
+ */
+export function parseColorScale(text: string): ColorScale | null {
+  const pieces = text.split(',');
+  const first = (pieces[0] ?? '').trim().toLowerCase();
+  const named = isInterpolation(first);
+
+  const stops: ColorStop[] = [];
+  for (const piece of named ? pieces.slice(1) : pieces) {
+    const stop = parseStop(piece);
+    if (stop !== null) stops.push(stop);
+  }
+  if (stops.length < 2) return null;
+
+  stops.sort((one, other) => one.position - other.position);
+  return {
+    stops: stops.slice(0, MAXIMUM_CUSTOM_STOPS),
+    interpolation: named ? first : 'rgb',
+  };
+}
+
+/**
+ * Write a custom scale as the text a link carries.
+ *
+ * The `#` of each colour is dropped: a query string that carries one is cut in
+ * two at the first of them, and everything after it never reaches the site.
+ * @param scale - The scale to write.
+ * @returns Its text, e.g. `hsv-long,0-0000ff,1-ff0000`.
+ */
+export function formatColorScale(scale: ColorScale): string {
+  const pieces: string[] = [scale.interpolation];
+  for (const stop of scale.stops) {
+    const color = stop.color.trim().toLowerCase().replace('#', '');
+    if (!HEX_DIGITS.test(color)) continue;
+    pieces.push(`${formatPosition(stop.position)}-${color}`);
+  }
+  return pieces.join(',');
+}
+
+function fromNamed(named: NamedColorScale): ResolvedColorScale {
+  return { id: named.id, label: named.label, scale: named.scale };
+}
+
+function parseStop(piece: string): ColorStop | null {
+  const text = piece.trim().toLowerCase();
+  const separator = text.lastIndexOf('-');
+  if (separator <= 0) return null;
+  const position = Number.parseFloat(text.slice(0, separator));
+  if (!Number.isFinite(position)) return null;
+  const color = text.slice(separator + 1).replace('#', '');
+  if (!HEX_DIGITS.test(color)) return null;
+  return { position: Math.min(1, Math.max(0, position)), color: `#${color}` };
+}
+
+function isInterpolation(value: string): value is ColorInterpolation {
+  for (const interpolation of INTERPOLATIONS) {
+    if (interpolation === value) return true;
+  }
+  return false;
+}
+
+function formatPosition(position: number): string {
+  const inside = Math.min(1, Math.max(0, position));
+  if (!Number.isFinite(inside)) return '0';
+  return String(Number(inside.toFixed(POSITION_DECIMALS)));
+}

package/src/color/core/scales.ts

@@ -0,0 +1,148 @@
+import type { ColorScale } from './interpolate.ts';
+import { evenScale } from './interpolate.ts';
+import {
+  BLUE_RED_COLORS,
+  CIVIDIS_COLORS,
+  COOL_WARM_COLORS,
+  GREYS_COLORS,
+  INFERNO_COLORS,
+  MAGMA_COLORS,
+  PLASMA_COLORS,
+  TURBO_COLORS,
+  VIRIDIS_COLORS,
+} from './scaleData.ts';
+
+/**
+ * What a scale is for, which is what the picker groups it under.
+ *
+ * A `sequential` one climbs from a low end to a high end; a `diverging` one
+ * reads away from a middle in both directions; a `cyclic` one turns around the
+ * colour wheel and orders nothing, so it is offered for the reader who wants
+ * the rainbow their course used and never chosen for them.
+ */
+export type ColorScaleKind = 'sequential' | 'diverging' | 'cyclic';
+
+/** One of the scales the family reads a quantity with. */
+export interface NamedColorScale {
+  /** The word a link and the picker carry, e.g. `viridis`. */
+  id: string;
+  /** What it is called in the picker. */
+  label: string;
+  /** What it is for. */
+  kind: ColorScaleKind;
+  /** One line on when to reach for it. */
+  description: string;
+  /** The ramp itself. */
+  scale: ColorScale;
+}
+
+/** What the picker calls each kind. */
+export const COLOR_SCALE_KIND_LABELS: Record<ColorScaleKind, string> = {
+  sequential: 'Low to high',
+  diverging: 'Away from a middle',
+  cyclic: 'Around the wheel',
+};
+
+/** The scale a site reads a quantity with unless a link says otherwise. */
+export const DEFAULT_COLOR_SCALE_ID = 'viridis';
+
+/**
+ * Every scale the picker offers, in the order it lists them.
+ *
+ * Viridis leads because it is the only one of them that survives every way a
+ * figure is read: printed in grey, projected, and seen by the one student in
+ * twelve who does not separate red from green.
+ */
+export const COLOR_SCALES: readonly NamedColorScale[] = [
+  {
+    id: 'viridis',
+    label: 'Viridis',
+    kind: 'sequential',
+    description: 'Purple to yellow. Prints in grey and reads colour-blind.',
+    scale: evenScale(VIRIDIS_COLORS),
+  },
+  {
+    id: 'plasma',
+    label: 'Plasma',
+    kind: 'sequential',
+    description: 'Blue to yellow through magenta, brighter than viridis.',
+    scale: evenScale(PLASMA_COLORS),
+  },
+  {
+    id: 'magma',
+    label: 'Magma',
+    kind: 'sequential',
+    description: 'Black to cream through violet and orange.',
+    scale: evenScale(MAGMA_COLORS),
+  },
+  {
+    id: 'inferno',
+    label: 'Inferno',
+    kind: 'sequential',
+    description: 'Black to pale yellow through red.',
+    scale: evenScale(INFERNO_COLORS),
+  },
+  {
+    id: 'cividis',
+    label: 'Cividis',
+    kind: 'sequential',
+    description: 'Blue to yellow, built to read the same to a deuteranope.',
+    scale: evenScale(CIVIDIS_COLORS),
+  },
+  {
+    id: 'turbo',
+    label: 'Turbo',
+    kind: 'sequential',
+    description: 'Rainbow colours, ordered so the lightness still climbs.',
+    scale: evenScale(TURBO_COLORS),
+  },
+  {
+    id: 'greys',
+    label: 'Greys',
+    kind: 'sequential',
+    description: 'Light to black, for a figure that will be photocopied.',
+    scale: evenScale(GREYS_COLORS),
+  },
+  {
+    id: 'cool-warm',
+    label: 'Cool to warm',
+    kind: 'diverging',
+    description: 'Blue through pale yellow to red.',
+    scale: evenScale(COOL_WARM_COLORS),
+  },
+  {
+    id: 'blue-red',
+    label: 'Blue to red',
+    kind: 'diverging',
+    description: 'Blue to red through white, the palest middle.',
+    scale: evenScale(BLUE_RED_COLORS),
+  },
+  {
+    id: 'rainbow',
+    label: 'Rainbow',
+    kind: 'cyclic',
+    description:
+      'Blue through green and yellow to red. Orders nothing in grey.',
+    // Two anchors and the long way round the wheel: the whole rainbow, and the
+    // shortest thing in this file that shows what the HSV model buys.
+    scale: {
+      stops: [
+        { position: 0, color: '#0000ff' },
+        { position: 1, color: '#ff0000' },
+      ],
+      interpolation: 'hsv-long',
+    },
+  },
+];
+
+/**
+ * The scale a link names.
+ * @param id - The word a link carries, e.g. `plasma`.
+ * @returns Its entry, or `undefined` when no scale is called that.
+ */
+export function colorScaleById(id: string): NamedColorScale | undefined {
+  for (const scale of COLOR_SCALES) {
+    if (scale.id === id) return scale;
+  }
+  return undefined;
+}