react-cheminfo 0.9.0 → 0.11.0

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;
+}

package/src/color/ui/ColorScaleBar.tsx

@@ -0,0 +1,73 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import { colorScaleGradient } from '../core/gradient.ts';
+import type { ColorScale } from '../core/interpolate.ts';
+
+const DEFAULT_HEIGHT = 10;
+const DEFAULT_SAMPLES = 24;
+
+/** What {@link ColorScaleBar} draws. */
+export interface ColorScaleBarProps {
+  /** The scale to draw, from its low end at the left. */
+  scale: ColorScale;
+  /**
+   * How tall the strip is, in pixels.
+   * @default 10
+   */
+  height?: number;
+  /**
+   * How many colours the gradient is written from. A scale that turns around
+   * the colour wheel needs more of them than one that mixes three channels,
+   * because the browser can only interpolate the straight line between two.
+   * @default 24
+   */
+  samples?: number;
+  /**
+   * What a screen reader is told the strip shows.
+   * @default '' — the strip is decoration, and is hidden from the reader
+   */
+  label?: string;
+  /**
+   * Anything the caller has to set on the strip itself, a width above all.
+   * @default {}
+   */
+  style?: CSSProperties;
+}
+
+/**
+ * A colour scale as one strip of colour.
+ *
+ * The picker, the editor and any caller who has to show a ramp without its end
+ * values draw the same strip, so a scale looks the same wherever it is offered.
+ * @param props - See {@link ColorScaleBarProps}.
+ * @returns The strip.
+ */
+export function ColorScaleBar(props: ColorScaleBarProps): ReactElement {
+  const {
+    scale,
+    height = DEFAULT_HEIGHT,
+    samples = DEFAULT_SAMPLES,
+    label = '',
+    style = {},
+  } = props;
+
+  return (
+    <span
+      role={label === '' ? undefined : 'img'}
+      aria-label={label === '' ? undefined : label}
+      aria-hidden={label === '' ? true : undefined}
+      style={{
+        ...BAR_STYLE,
+        height,
+        backgroundImage: colorScaleGradient(scale, samples),
+        ...style,
+      }}
+    />
+  );
+}
+
+const BAR_STYLE = {
+  display: 'block',
+  width: '100%',
+  borderRadius: 3,
+} as const satisfies CSSProperties;

package/src/color/ui/ColorScaleEditor.tsx

@@ -0,0 +1,243 @@
+import { Button, HTMLSelect } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { parseHexColor, toHexColor } from '../core/hex.ts';
+import type {
+  ColorInterpolation,
+  ColorScale,
+  ColorStop,
+} from '../core/interpolate.ts';
+import { colorAt } from '../core/interpolate.ts';
+import { MAXIMUM_CUSTOM_STOPS } from '../core/scaleText.ts';
+
+import { ColorScaleBar } from './ColorScaleBar.tsx';
+
+const MINIMUM_STOPS = 2;
+const POSITION_STEP = 0.01;
+const PREVIEW_HEIGHT = 16;
+const PREVIEW_SAMPLES = 48;
+
+/** What each path between two anchors is called. */
+const INTERPOLATION_LABELS: Array<{
+  value: ColorInterpolation;
+  label: string;
+}> = [
+  { value: 'rgb', label: 'RGB — mix the channels' },
+  { value: 'hsv', label: 'HSV — turn the short way' },
+  { value: 'hsv-long', label: 'HSV — turn the long way' },
+];
+
+/** What {@link ColorScaleEditor} edits. */
+export interface ColorScaleEditorProps {
+  /** The scale being edited; every anchor is a `#rgb` or `#rrggbb` colour. */
+  value: ColorScale;
+  /** Called with the edited scale on every change. */
+  onChange: (scale: ColorScale) => void;
+}
+
+/**
+ * A colour scale of the reader's own: the colours it passes through, where
+ * each one sits, and the path it takes between them.
+ *
+ * A colour is anchored rather than typed into a list, so two anchors and the
+ * HSV path already describe a whole rainbow, and an anchor never crosses its
+ * neighbours — the scale it draws is always the one the strip above shows.
+ * @param props - See {@link ColorScaleEditorProps}.
+ * @returns The preview, the anchors, and the picker of the path between them.
+ */
+export function ColorScaleEditor(props: ColorScaleEditorProps): ReactElement {
+  const { value, onChange } = props;
+  const stops = value.stops;
+
+  function write(next: readonly ColorStop[]): void {
+    onChange({ stops: next, interpolation: value.interpolation });
+  }
+
+  return (
+    <div style={PANEL_STYLE}>
+      <ColorScaleBar
+        scale={value}
+        height={PREVIEW_HEIGHT}
+        samples={PREVIEW_SAMPLES}
+        label="The scale being edited"
+      />
+
+      <div style={ROWS_STYLE}>
+        {stops.map((stop, index) => (
+          <div key={`${String(index)}-${stop.color}`} style={ROW_STYLE}>
+            <input
+              type="color"
+              aria-label={`Colour of anchor ${String(index + 1)}`}
+              value={normalizeColor(stop.color)}
+              style={SWATCH_STYLE}
+              onChange={(event) => {
+                write(replace(stops, index, { color: event.target.value }));
+              }}
+            />
+            <input
+              type="range"
+              aria-label={`Position of anchor ${String(index + 1)}`}
+              min={0}
+              max={1}
+              step={POSITION_STEP}
+              value={stop.position}
+              style={SLIDER_STYLE}
+              onChange={(event) => {
+                write(
+                  replace(stops, index, {
+                    position: hold(stops, index, event.target.valueAsNumber),
+                  }),
+                );
+              }}
+            />
+            <span style={POSITION_STYLE}>{stop.position.toFixed(2)}</span>
+            <Button
+              icon="cross"
+              variant="minimal"
+              size="small"
+              aria-label={`Remove anchor ${String(index + 1)}`}
+              disabled={stops.length <= MINIMUM_STOPS}
+              onClick={() => {
+                write(stops.filter((_, at) => at !== index));
+              }}
+            />
+          </div>
+        ))}
+      </div>
+
+      <div style={FOOTER_STYLE}>
+        <Button
+          icon="plus"
+          size="small"
+          text="Add a colour"
+          disabled={stops.length >= MAXIMUM_CUSTOM_STOPS}
+          onClick={() => {
+            write(withAddedStop(value));
+          }}
+        />
+        <HTMLSelect
+          aria-label="Path between two anchors"
+          value={value.interpolation}
+          options={INTERPOLATION_LABELS}
+          onChange={(event) => {
+            onChange({
+              stops,
+              interpolation: event.currentTarget.value as ColorInterpolation,
+            });
+          }}
+        />
+      </div>
+    </div>
+  );
+}
+
+function replace(
+  stops: readonly ColorStop[],
+  index: number,
+  patch: Partial<ColorStop>,
+): ColorStop[] {
+  return stops.map((stop, at) => (at === index ? { ...stop, ...patch } : stop));
+}
+
+/**
+ * A position an anchor may take: never past either of its neighbours, so the
+ * rows never reorder under a dragging finger.
+ * @param stops - The anchors as they stand.
+ * @param index - Which of them is being moved.
+ * @param position - Where it is being moved to.
+ * @returns The position it is allowed to take.
+ */
+function hold(
+  stops: readonly ColorStop[],
+  index: number,
+  position: number,
+): number {
+  if (!Number.isFinite(position)) return stops[index]?.position ?? 0;
+  const low = stops[index - 1]?.position ?? 0;
+  const high = stops[index + 1]?.position ?? 1;
+  return Math.min(high, Math.max(low, position));
+}
+
+/**
+ * The anchors with one more, dropped in the widest gap and taking the colour
+ * the scale already has there — so adding one changes nothing until it is moved.
+ * @param scale - The scale being edited.
+ * @returns Its anchors, with the new one among them.
+ */
+function withAddedStop(scale: ColorScale): ColorStop[] {
+  const stops = [...scale.stops];
+  let widest = 0;
+  let at = 1;
+  for (let index = 1; index < stops.length; index++) {
+    const span =
+      (stops[index]?.position ?? 0) - (stops[index - 1]?.position ?? 0);
+    if (span > widest) {
+      widest = span;
+      at = index;
+    }
+  }
+  const position =
+    ((stops[at]?.position ?? 1) + (stops[at - 1]?.position ?? 0)) / 2;
+  stops.splice(at, 0, { position, color: colorAt(scale, position) });
+  return stops;
+}
+
+/**
+ * A colour a `type="color"` input reads: it takes six digits and nothing else,
+ * so a short hex is spelled out first.
+ * @param color - The anchor's colour, `#rgb` or `#rrggbb`.
+ * @returns The same colour, in six digits.
+ */
+function normalizeColor(color: string): string {
+  return toHexColor(parseHexColor(color));
+}
+
+const PANEL_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 10,
+  padding: 12,
+  minWidth: 280,
+} as const satisfies CSSProperties;
+
+const ROWS_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+} as const satisfies CSSProperties;
+
+const ROW_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const SWATCH_STYLE = {
+  width: 32,
+  height: 24,
+  padding: 0,
+  border: 0,
+  background: 'none',
+  cursor: 'pointer',
+} as const satisfies CSSProperties;
+
+const SLIDER_STYLE = {
+  flex: '1 1 auto',
+  minWidth: 90,
+  accentColor: 'var(--accent, currentColor)',
+} as const satisfies CSSProperties;
+
+const POSITION_STYLE = {
+  fontSize: 12,
+  fontVariantNumeric: 'tabular-nums',
+  width: 30,
+  textAlign: 'right',
+} as const satisfies CSSProperties;
+
+const FOOTER_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  flexWrap: 'wrap',
+  gap: 8,
+  justifyContent: 'space-between',
+} as const satisfies CSSProperties;