react-cheminfo 0.8.0 → 0.10.0

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

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