react-cheminfo 0.9.0 → 0.11.0

package/src/chrome/ui/SiteHeader.tsx

@@ -55,6 +55,17 @@ export interface SiteHeaderProps {
    * @default 28
    */
   markSize?: number;
+  /**
+   * How wide the bar's contents run.
+   *
+   * `page` caps them at `--page-max` and centres them, so the brand sits over
+   * the first word of a page that is capped the same way — which is what a
+   * site of reading matter wants. `full` runs them to both edges, for a tool
+   * that fills the window: there the cap leaves the brand floating inwards
+   * with the tool running past it on both sides, and reads as a fault.
+   * @default 'page'
+   */
+  width?: 'page' | 'full';
 }
 
 /**
@@ -76,6 +87,7 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
     homeHref = '/',
     onHome,
     markSize = 28,
+    width = 'page',
   } = props;
 
   if (embedded) return null;
@@ -84,7 +96,7 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
 
   return (
     <header className="app-header no-print">
-      <div className="app-header__inner">
+      <div className={INNER_CLASS[width]}>
         <a
           className="brand"
           href={homeHref}
@@ -117,3 +129,9 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
     </header>
   );
 }
+
+/** The two widths the bar's contents run at, as the classes that set them. */
+const INNER_CLASS = {
+  page: 'app-header__inner',
+  full: 'app-header__inner app-header__inner--full',
+} as const;

package/src/chrome/ui/navItem.ts

@@ -47,6 +47,18 @@ export interface NavItem {
    * @default undefined
    */
   after?: ReactNode;
+  /**
+   * Whether the page cannot be opened yet — a view that needs data the site
+   * has not been given.
+   *
+   * It is greyed rather than left out, because a bar that grows entries as a
+   * reader works is a bar they have to keep re-reading, and a page they cannot
+   * see is a page they conclude the site does not have. `title` is where the
+   * reason goes; without one the entry is dead and says nothing, which is the
+   * one thing worse than leaving it out.
+   * @default false
+   */
+  disabled?: boolean;
 }
 
 /**

package/src/color/core/gradient.ts

@@ -0,0 +1,29 @@
+import type { ColorScale } from './interpolate.ts';
+import { sampleScale } from './interpolate.ts';
+
+const PERCENT = 100;
+const DECIMALS = 2;
+
+/**
+ * A colour scale written as the CSS gradient that draws it.
+ *
+ * The scale is sampled rather than handed over as its anchors, because a
+ * browser only interpolates the straight line between two colours: a scale
+ * that turns around the colour wheel would otherwise be drawn as the grey
+ * shortcut across it.
+ * @param scale - The scale to draw, from its low end at the left.
+ * @param samples - How many colours to write out; more of them for a scale that turns.
+ * @returns The `linear-gradient(…)` value.
+ * @throws {Error} When the scale has no anchor, or one of them is not a hex colour.
+ */
+export function colorScaleGradient(scale: ColorScale, samples: number): string {
+  const colors = sampleScale(scale, samples);
+  const last = colors.length - 1;
+  const stops: string[] = [];
+  for (let index = 0; index < colors.length; index++) {
+    const color = colors[index];
+    if (color === undefined) continue;
+    stops.push(`${color} ${((index / last) * PERCENT).toFixed(DECIMALS)}%`);
+  }
+  return `linear-gradient(to right, ${stops.join(', ')})`;
+}

package/src/color/core/hsv.ts

@@ -0,0 +1,112 @@
+import type { RgbColor } from './hex.ts';
+
+const TURN = 360;
+const SECTOR = 60;
+const MAXIMUM_CHANNEL = 255;
+
+/**
+ * A colour in the HSV model — HSB in a drawing program, the same three numbers.
+ *
+ * It is the model a scale is customised in: hue says which colour, and the two
+ * others say how strong and how bright it is, so an author moves along the
+ * wheel without having to think in red, green and blue at once.
+ */
+export interface HsvColor {
+  /** Where it sits on the wheel, in degrees from 0 to 360. Zero on a grey. */
+  hue: number;
+  /** How far it is from grey, from 0 to 1. */
+  saturation: number;
+  /** How bright it is, from 0 for black to 1. */
+  value: number;
+}
+
+/**
+ * Read three channels as a hue, a saturation and a value.
+ * @param color - The three channels, each from 0 to 255.
+ * @returns The same colour in the HSV model.
+ */
+export function rgbToHsv(color: RgbColor): HsvColor {
+  const red = channel(color.red);
+  const green = channel(color.green);
+  const blue = channel(color.blue);
+  const value = Math.max(red, green, blue);
+  const chroma = value - Math.min(red, green, blue);
+  return {
+    hue: hueOf(red, green, blue, value, chroma),
+    saturation: value === 0 ? 0 : chroma / value,
+    value,
+  };
+}
+
+/**
+ * Write a hue, a saturation and a value back as three channels.
+ *
+ * The hue is wrapped rather than clamped, so a scale may run past 360 or below
+ * zero and still land on the colour that turn of the wheel names.
+ * @param color - The colour in the HSV model.
+ * @returns The three channels, each from 0 to 255.
+ */
+export function hsvToRgb(color: HsvColor): RgbColor {
+  const hue = wrapHue(color.hue) / SECTOR;
+  const saturation = unit(color.saturation);
+  const value = unit(color.value);
+  const sector = Math.floor(hue) % 6;
+  const offset = hue - Math.floor(hue);
+  const low = value * (1 - saturation);
+  const falling = value * (1 - saturation * offset);
+  const rising = value * (1 - saturation * (1 - offset));
+
+  if (sector === 0) return scale(value, rising, low);
+  if (sector === 1) return scale(falling, value, low);
+  if (sector === 2) return scale(low, value, rising);
+  if (sector === 3) return scale(low, falling, value);
+  if (sector === 4) return scale(rising, low, value);
+  return scale(value, low, falling);
+}
+
+/**
+ * A hue brought inside one turn of the wheel.
+ * @param hue - Any angle in degrees, negative or past 360.
+ * @returns The same angle, from 0 up to but not including 360.
+ */
+export function wrapHue(hue: number): number {
+  if (!Number.isFinite(hue)) return 0;
+  return ((hue % TURN) + TURN) % TURN;
+}
+
+function hueOf(
+  red: number,
+  green: number,
+  blue: number,
+  value: number,
+  chroma: number,
+): number {
+  if (chroma === 0) return 0;
+  let hue: number;
+  if (value === red) {
+    hue = (green - blue) / chroma;
+  } else if (value === green) {
+    hue = 2 + (blue - red) / chroma;
+  } else {
+    hue = 4 + (red - green) / chroma;
+  }
+  return wrapHue(hue * SECTOR);
+}
+
+function scale(red: number, green: number, blue: number): RgbColor {
+  return {
+    red: red * MAXIMUM_CHANNEL,
+    green: green * MAXIMUM_CHANNEL,
+    blue: blue * MAXIMUM_CHANNEL,
+  };
+}
+
+function channel(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value / MAXIMUM_CHANNEL));
+}
+
+function unit(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}

package/src/color/core/index.ts

@@ -1,9 +1,35 @@
 export type { ReadableInkOptions } from './contrast.ts';
 export { contrastRatio, readableInk, relativeLuminance } from './contrast.ts';
-export type { PositionInRangeOptions, Swatch } from './scale.ts';
+export type { RgbColor } from './hex.ts';
+export { parseHexColor, toHexColor } from './hex.ts';
+export { colorScaleGradient } from './gradient.ts';
+export type { HsvColor } from './hsv.ts';
+export { hsvToRgb, rgbToHsv, wrapHue } from './hsv.ts';
+export type {
+  ColorInterpolation,
+  ColorScale,
+  ColorStop,
+  Swatch,
+} from './interpolate.ts';
+export { colorAt, evenScale, sampleScale, swatchAt } from './interpolate.ts';
+export type { PositionInRangeOptions } from './scale.ts';
 export {
   VIRIDIS_SCALE,
   colorFromScale,
   positionInRange,
   swatchFromScale,
 } from './scale.ts';
+export type { ColorScaleKind, NamedColorScale } from './scales.ts';
+export {
+  COLOR_SCALES,
+  COLOR_SCALE_KIND_LABELS,
+  DEFAULT_COLOR_SCALE_ID,
+  colorScaleById,
+} from './scales.ts';
+export type { ResolvedColorScale } from './scaleText.ts';
+export {
+  MAXIMUM_CUSTOM_STOPS,
+  formatColorScale,
+  parseColorScale,
+  resolveColorScale,
+} from './scaleText.ts';

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',
+];