react-cheminfo 0.49.0 → 0.51.0

package/src/color/core/interpolate.ts

@@ -3,6 +3,7 @@ import { clamp } from '../../format/core/clamp.ts';
 import type { ReadableInkOptions } from './contrast.ts';
 import { readableInk } from './contrast.ts';
 import { parseHexColor, toHexColor } from './hex.ts';
+import type { HsvColor } from './hsv.ts';
 import { hsvToRgb, rgbToHsv, wrapHue } from './hsv.ts';
 
 const HALF_TURN = 180;
@@ -33,8 +34,10 @@ export interface ColorStop {
  * - `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.
+ * - `hsv-long` turns the whole scale one way round the wheel: the long way
+ *   between its two ends, which is how two anchors draw a rainbow. Each anchor
+ *   in between is reached by turning that same way, never by a turn of its own,
+ *   so adding one where the scale already has its colour changes nothing.
  */
 export type ColorInterpolation = 'rgb' | 'hsv' | 'hsv-long';
 
@@ -94,7 +97,11 @@ export function colorAt(scale: ColorScale, position: number): string {
     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 mix(start.color, end.color, ratio, {
+      interpolation,
+      turn: longTurn(first.color, last.color),
+      whole: stops.length === MINIMUM_SAMPLES,
+    });
   }
   return toHexColor(parseHexColor(last.color));
 }
@@ -134,15 +141,18 @@ export function sampleScale(scale: ColorScale, count: number): string[] {
   return colors;
 }
 
-function mix(
-  start: string,
-  end: string,
-  ratio: number,
-  interpolation: ColorInterpolation,
-): string {
+interface HuePath {
+  interpolation: ColorInterpolation;
+  /** The way the long path turns: 1 up the wheel, -1 down it. */
+  turn: number;
+  /** Whether the two anchors are the whole scale, so one hue on both is a full turn. */
+  whole: boolean;
+}
+
+function mix(start: string, end: string, ratio: number, path: HuePath): string {
   const from = parseHexColor(start);
   const to = parseHexColor(end);
-  if (interpolation === 'rgb') {
+  if (path.interpolation === 'rgb') {
     return toHexColor({
       red: from.red + (to.red - from.red) * ratio,
       green: from.green + (to.green - from.green) * ratio,
@@ -152,7 +162,8 @@ function mix(
 
   const one = rgbToHsv(from);
   const other = rgbToHsv(to);
-  const hue = one.hue + hueStep(one.hue, other.hue, interpolation) * ratio;
+  const [fromHue, toHue] = pairHues(one, other);
+  const hue = fromHue + hueStep(fromHue, toHue, path) * ratio;
   return toHexColor(
     hsvToRgb({
       hue: wrapHue(hue),
@@ -162,15 +173,33 @@ function mix(
   );
 }
 
-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;
+// A grey, black or white has no hue of its own, so it takes the other one's:
+// the path then fades to it instead of sweeping through red on the way.
+function pairHues(one: HsvColor, other: HsvColor): [number, number] {
+  if (one.saturation === 0) return [other.hue, other.hue];
+  if (other.saturation === 0) return [one.hue, one.hue];
+  return [one.hue, other.hue];
+}
+
+function hueStep(from: number, to: number, path: HuePath): number {
+  if (path.interpolation !== 'hsv-long') return shortestStep(from, to);
+  const step = path.turn > 0 ? upStep(from, to) : -upStep(to, from);
+  return step === 0 && path.whole ? path.turn * TURN : step;
+}
+
+function longTurn(first: string, last: string): number {
+  const [from, to] = pairHues(
+    rgbToHsv(parseHexColor(first)),
+    rgbToHsv(parseHexColor(last)),
+  );
+  // Two ends of one hue are a full turn apart, taken up the wheel.
+  return shortestStep(from, to) > 0 ? -1 : 1;
+}
+
+function shortestStep(from: number, to: number): number {
+  return ((((to - from) % TURN) + TURN + HALF_TURN) % TURN) - HALF_TURN;
+}
+
+function upStep(from: number, to: number): number {
+  return (((to - from) % TURN) + TURN) % TURN;
 }

package/src/color/core/stops.ts

@@ -0,0 +1,98 @@
+import { clamp } from '../../format/core/clamp.ts';
+
+import type { ColorScale, ColorStop } from './interpolate.ts';
+import { colorAt } from './interpolate.ts';
+import { MAXIMUM_CUSTOM_STOPS } from './scaleText.ts';
+
+/** How few anchors a scale may have: one at each end of what it draws. */
+export const MINIMUM_CUSTOM_STOPS = 2;
+
+// A link writes three decimals, so an anchor is held where the link puts it.
+const POSITION_FACTOR = 1000;
+
+/** The anchors after an edit, and where the edited one now stands among them. */
+export interface EditedStops {
+  /** The anchors, from the low end. */
+  stops: ColorStop[];
+  /** The index of the anchor that was added or moved. */
+  index: number;
+}
+
+/**
+ * Add an anchor where the reader clicked, in the colour the scale already has
+ * there — so adding one changes nothing until it is moved or recoloured.
+ * @param scale - The scale being edited.
+ * @param position - Where to add it, from 0 at the low end to 1 at the high end.
+ * @returns The anchors with the new one, or `null` when the scale already holds as many as a link may carry.
+ */
+export function addColorStop(
+  scale: ColorScale,
+  position: number,
+): EditedStops | null {
+  if (scale.stops.length >= MAXIMUM_CUSTOM_STOPS) return null;
+  const at = roundPosition(position);
+  const added: ColorStop = { position: at, color: colorAt(scale, at) };
+  return sortAround([...scale.stops, added], added);
+}
+
+/**
+ * Move an anchor. It may pass its neighbours: the anchors are kept in order,
+ * and the returned index follows the one that moved.
+ * @param stops - The anchors, from the low end.
+ * @param index - Which of them moves.
+ * @param position - Where to, clamped to the scale.
+ * @returns The anchors in their new order, and where the moved one landed.
+ */
+export function moveColorStop(
+  stops: readonly ColorStop[],
+  index: number,
+  position: number,
+): EditedStops {
+  const stop = stops[index];
+  if (stop === undefined || !Number.isFinite(position)) {
+    return { stops: [...stops], index };
+  }
+  const moved: ColorStop = { ...stop, position: roundPosition(position) };
+  return sortAround(
+    stops.map((other, at) => (at === index ? moved : other)),
+    moved,
+  );
+}
+
+/**
+ * Remove an anchor, unless the scale would be left with fewer than two.
+ * @param stops - The anchors, from the low end.
+ * @param index - Which of them to remove.
+ * @returns The remaining anchors, or the same ones when none may go.
+ */
+export function removeColorStop(
+  stops: readonly ColorStop[],
+  index: number,
+): ColorStop[] {
+  if (stops.length <= MINIMUM_CUSTOM_STOPS) return [...stops];
+  return stops.filter((_, at) => at !== index);
+}
+
+/**
+ * Recolour an anchor.
+ * @param stops - The anchors, from the low end.
+ * @param index - Which of them to recolour.
+ * @param color - Its new colour.
+ * @returns The anchors, with that one recoloured.
+ */
+export function recolorColorStop(
+  stops: readonly ColorStop[],
+  index: number,
+  color: string,
+): ColorStop[] {
+  return stops.map((stop, at) => (at === index ? { ...stop, color } : stop));
+}
+
+function roundPosition(position: number): number {
+  return Math.round(clamp(position, 0, 1) * POSITION_FACTOR) / POSITION_FACTOR;
+}
+
+function sortAround(stops: ColorStop[], edited: ColorStop): EditedStops {
+  const sorted = stops.toSorted((one, other) => one.position - other.position);
+  return { stops: sorted, index: sorted.indexOf(edited) };
+}

package/src/color/core/tone.ts

@@ -0,0 +1,79 @@
+import { clamp } from '../../format/core/clamp.ts';
+
+import { parseHexColor, toHexColor } from './hex.ts';
+import type { HsvColor } from './hsv.ts';
+import { hsvToRgb, rgbToHsv } from './hsv.ts';
+import type { ColorStop } from './interpolate.ts';
+
+/** How strong and how bright a scale's colours are, taken over all its anchors. */
+export interface ScaleTone {
+  /** How far the anchors are from grey, from 0 to 1. */
+  saturation: number;
+  /** How bright they are, from 0 for black to 1. */
+  value: number;
+}
+
+/**
+ * The saturation and the brightness of a scale's anchors, averaged: what a
+ * control setting both for the whole scale opens on.
+ * @param stops - The anchors.
+ * @returns Their mean saturation and mean value; both 0 when there is no anchor.
+ */
+export function scaleTone(stops: readonly ColorStop[]): ScaleTone {
+  const colors = toHsv(stops);
+  if (colors.length === 0) return { saturation: 0, value: 0 };
+  let saturation = 0;
+  let value = 0;
+  for (const color of colors) {
+    saturation += color.saturation;
+    value += color.value;
+  }
+  return {
+    saturation: saturation / colors.length,
+    value: value / colors.length,
+  };
+}
+
+/**
+ * Give every anchor the same saturation, the same brightness, or both, keeping
+ * each one's hue — so the scale then only turns round the wheel. A grey anchor
+ * has no hue of its own and takes the hue of the nearest one that has.
+ * @param stops - The anchors.
+ * @param tone - What to set; a field left out keeps each anchor's own.
+ * @returns The recoloured anchors, in the same order.
+ */
+export function setScaleTone(
+  stops: readonly ColorStop[],
+  tone: Partial<ScaleTone>,
+): ColorStop[] {
+  const colors = toHsv(stops);
+  const result: ColorStop[] = [];
+  for (let index = 0; index < stops.length; index++) {
+    const stop = stops[index];
+    const color = colors[index];
+    if (stop === undefined || color === undefined) continue;
+    const toned = hsvToRgb({
+      hue: hueNear(colors, index),
+      saturation: clamp(tone.saturation ?? color.saturation, 0, 1),
+      value: clamp(tone.value ?? color.value, 0, 1),
+    });
+    result.push({ ...stop, color: toHexColor(toned) });
+  }
+  return result;
+}
+
+function toHsv(stops: readonly ColorStop[]): HsvColor[] {
+  const colors: HsvColor[] = [];
+  for (const stop of stops) colors.push(rgbToHsv(parseHexColor(stop.color)));
+  return colors;
+}
+
+function hueNear(colors: readonly HsvColor[], index: number): number {
+  for (let distance = 0; distance < colors.length; distance++) {
+    const before = colors[index - distance];
+    if (before !== undefined && before.saturation > 0) return before.hue;
+    const after = colors[index + distance];
+    if (after !== undefined && after.saturation > 0) return after.hue;
+  }
+  return 0;
+}

package/src/color/core/uniform.ts

@@ -0,0 +1,67 @@
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
+import { readableInk } from './contrast.ts';
+import { normalizeHexColor } from './hex.ts';
+import type { Swatch } from './interpolate.ts';
+
+/**
+ * What a colour-scale picker offering one colour writes for it, and a link
+ * carries: every value the same colour, so the figure needs no key. Followed by
+ * `-` and a hex colour, e.g. `uniform-1c6e42`, it names that colour.
+ */
+export const UNIFORM_COLOR_SCALE_ID = 'uniform';
+
+/**
+ * The one colour of a uniform scale that names none: the family's border grey
+ * rather than white, so a cell still stands out from a white page and from the
+ * white ground of a saved figure.
+ */
+export const UNIFORM_SWATCH: Swatch = {
+  background: TOKEN.border,
+  foreground: TOKEN.text,
+};
+
+const PREFIX = `${UNIFORM_COLOR_SCALE_ID}-`;
+
+/**
+ * Whether a scale text asks for one colour.
+ * @param text - A scale id or a custom scale, as a link carries it.
+ * @returns `true` for {@link UNIFORM_COLOR_SCALE_ID}, with or without a colour.
+ */
+export function isUniformColorScale(text: string | undefined): boolean {
+  const wanted = (text ?? '').trim().toLowerCase();
+  return wanted === UNIFORM_COLOR_SCALE_ID || wanted.startsWith(PREFIX);
+}
+
+/**
+ * The colour a uniform scale text names, and the ink to write on it.
+ *
+ * A colour with a typo in it falls back to the grey rather than failing, so a
+ * link written by hand still opens the figure.
+ * @param text - A scale text, e.g. `uniform` or `uniform-1c6e42`.
+ * @returns The swatch it names, or {@link UNIFORM_SWATCH}.
+ */
+export function uniformSwatch(text: string | undefined): Swatch {
+  const color = uniformColor(text);
+  if (color === null) return UNIFORM_SWATCH;
+  return { background: color, foreground: readableInk(color) };
+}
+
+/**
+ * Write one colour as the scale text a link carries; the `#` is dropped, since
+ * a query string is cut in two at the first one.
+ * @param color - The colour, as `#rgb` or `#rrggbb`.
+ * @returns E.g. `uniform-1c6e42`, or {@link UNIFORM_COLOR_SCALE_ID} when the colour is not a hex colour.
+ */
+export function formatUniformColorScale(color: string): string {
+  const normalized = normalizeHexColor(color);
+  return normalized === null
+    ? UNIFORM_COLOR_SCALE_ID
+    : `${PREFIX}${normalized.slice(1)}`;
+}
+
+function uniformColor(text: string | undefined): string | null {
+  const wanted = (text ?? '').trim().toLowerCase();
+  if (!wanted.startsWith(PREFIX)) return null;
+  return normalizeHexColor(`#${wanted.slice(PREFIX.length)}`);
+}