react-cheminfo 0.3.0 → 0.4.0

package/src/clipboard/ui/CopyButton.tsx

@@ -0,0 +1,111 @@
+import type { IconName } from '@blueprintjs/core';
+import { Button } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import {
+  DEFAULT_COPY_RESET_AFTER,
+  useCopyToClipboard,
+} from './useCopyToClipboard.ts';
+
+export interface CopyButtonProps {
+  /**
+   * What to copy. A function is called when the button is pressed, which is
+   * what a whole list has to be: writing ten thousand structures out on every
+   * render, for a button nobody may press, is a page that stutters as it is
+   * scrolled.
+   */
+  content: string | (() => string);
+  /**
+   * Text of the button. Left out for an icon-only button, which is what a
+   * dense row of them needs.
+   * @default undefined — the button is reduced to its icon
+   */
+  label?: string;
+  /**
+   * Text shown while the copy is being confirmed, when there is a label.
+   * @default 'Copied'
+   */
+  copiedLabel?: string;
+  /**
+   * Whether the button drops its background, for a toolbar or a code block.
+   * @default false
+   */
+  minimal?: boolean;
+  /**
+   * Whether the button is the small size.
+   * @default false
+   */
+  small?: boolean;
+  /**
+   * Glyph shown at rest. A tick replaces it while the copy is confirmed.
+   * @default 'duplicate'
+   */
+  icon?: IconName;
+  /**
+   * Whether there is nothing to copy.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * How long the button says it copied, in milliseconds.
+   * @default 1500
+   */
+  resetAfter?: number;
+  /**
+   * What the pointer and a screen reader are told.
+   * @default 'Copy to clipboard'
+   */
+  title?: string;
+  /**
+   * Class the button carries, so a site can reach it from its stylesheet.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * A button that puts a piece of text on the clipboard and says so.
+ * @param props - What to copy, what the button reads, and how it looks.
+ * @returns The copy button.
+ */
+export function CopyButton(props: CopyButtonProps): ReactElement {
+  const {
+    content,
+    label,
+    copiedLabel = 'Copied',
+    minimal = false,
+    small = false,
+    icon = 'duplicate',
+    disabled = false,
+    resetAfter = DEFAULT_COPY_RESET_AFTER,
+    title = 'Copy to clipboard',
+    className,
+  } = props;
+  const { copied, copy } = useCopyToClipboard(resetAfter);
+
+  return (
+    <Button
+      className={className}
+      variant={minimal ? 'minimal' : 'solid'}
+      size={small ? 'small' : 'medium'}
+      icon={copied ? 'tick' : icon}
+      intent={copied ? 'success' : 'none'}
+      text={buttonText(label, copiedLabel, copied)}
+      disabled={disabled}
+      title={title}
+      aria-label={label ?? title}
+      onClick={() => {
+        void copy(typeof content === 'function' ? content() : content);
+      }}
+    />
+  );
+}
+
+function buttonText(
+  label: string | undefined,
+  copiedLabel: string,
+  copied: boolean,
+): string | undefined {
+  if (label === undefined) return undefined;
+  return copied ? copiedLabel : label;
+}

package/src/clipboard/ui/index.ts

@@ -0,0 +1,9 @@
+export type { CodeBlockProps, CodeBlockTone } from './CodeBlock.tsx';
+export { CodeBlock } from './CodeBlock.tsx';
+export type { CopyButtonProps } from './CopyButton.tsx';
+export { CopyButton } from './CopyButton.tsx';
+export type { CopyToClipboard } from './useCopyToClipboard.ts';
+export {
+  DEFAULT_COPY_RESET_AFTER,
+  useCopyToClipboard,
+} from './useCopyToClipboard.ts';

package/src/clipboard/ui/useCopyToClipboard.ts

@@ -0,0 +1,57 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { writeToClipboard } from '../core/writeToClipboard.ts';
+
+/** How long a copy is confirmed for, in milliseconds, unless asked otherwise. */
+export const DEFAULT_COPY_RESET_AFTER = 1500;
+
+/** A clipboard write and the confirmation it leaves behind for a moment. */
+export interface CopyToClipboard {
+  /** Whether the last copy worked and is still being confirmed. */
+  copied: boolean;
+  /**
+   * Put text on the clipboard and confirm it.
+   * @param text - What to copy.
+   * @returns Whether the clipboard took it.
+   */
+  copy: (text: string) => Promise<boolean>;
+}
+
+/**
+ * Copy text and say so for a moment afterwards.
+ *
+ * The confirmation timer is cleared when the component goes away, and a copy
+ * that lands after that confirms nothing, so a button unmounted mid-copy — a
+ * row leaving a list, a menu closing — leaves no timer behind.
+ * @param resetAfter - How long the confirmation lasts, in milliseconds.
+ * @returns The confirmation flag and the copy action.
+ */
+export function useCopyToClipboard(
+  resetAfter = DEFAULT_COPY_RESET_AFTER,
+): CopyToClipboard {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const isMounted = useRef(true);
+
+  useEffect(() => {
+    isMounted.current = true;
+    return () => {
+      isMounted.current = false;
+      clearTimeout(timer.current);
+    };
+  }, []);
+
+  const copy = useCallback(
+    async (text: string) => {
+      const written = await writeToClipboard(text);
+      if (!written || !isMounted.current) return written;
+      setCopied(true);
+      clearTimeout(timer.current);
+      timer.current = setTimeout(() => setCopied(false), resetAfter);
+      return true;
+    },
+    [resetAfter],
+  );
+
+  return { copied, copy };
+}

package/src/color/core/contrast.ts

@@ -0,0 +1,85 @@
+import { parseHexColor } from './hex.ts';
+
+const RED_WEIGHT = 0.2126;
+const GREEN_WEIGHT = 0.7152;
+const BLUE_WEIGHT = 0.0722;
+const LINEAR_THRESHOLD = 0.039_28;
+
+/** The ink written on a light background. */
+const DARK_INK = '#182026';
+/** The ink written on a dark background. */
+const LIGHT_INK = '#ffffff';
+
+/** Which two inks {@link readableInk} chooses between. */
+export interface ReadableInkOptions {
+  /**
+   * The ink for a light background.
+   * @default '#182026'
+   */
+  dark?: string;
+  /**
+   * The ink for a dark background.
+   * @default '#ffffff'
+   */
+  light?: string;
+}
+
+/**
+ * The relative luminance of a colour, as WCAG 2 defines it.
+ * @param color - A `#rgb` or `#rrggbb` colour.
+ * @returns Its luminance, from 0 for black to 1 for white.
+ * @throws {Error} When the string is not a hex colour.
+ */
+export function relativeLuminance(color: string): number {
+  const { red, green, blue } = parseHexColor(color);
+  return (
+    RED_WEIGHT * linearize(red) +
+    GREEN_WEIGHT * linearize(green) +
+    BLUE_WEIGHT * linearize(blue)
+  );
+}
+
+/**
+ * The WCAG contrast ratio between two colours, whichever way round they come.
+ *
+ * Body text needs 4.5, large text and interface parts need 3.
+ * @param first - A `#rgb` or `#rrggbb` colour.
+ * @param second - The colour it is read against.
+ * @returns A ratio from 1 for two identical colours to 21 for black on white.
+ * @throws {Error} When either string is not a hex colour.
+ */
+export function contrastRatio(first: string, second: string): number {
+  const one = relativeLuminance(first);
+  const other = relativeLuminance(second);
+  const lighter = Math.max(one, other);
+  const darker = Math.min(one, other);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * The ink that stays readable on a background.
+ *
+ * The two candidates are compared by contrast ratio rather than by a lightness
+ * threshold, so the choice is the one WCAG would make and a mid-tone
+ * background gets the ink it actually reads better against.
+ * @param background - The `#rgb` or `#rrggbb` colour written on.
+ * @param options - See {@link ReadableInkOptions}.
+ * @returns Whichever of the two inks reaches the higher contrast.
+ * @throws {Error} When any of the colours is not a hex colour.
+ */
+export function readableInk(
+  background: string,
+  options: ReadableInkOptions = {},
+): string {
+  const { dark = DARK_INK, light = LIGHT_INK } = options;
+  return contrastRatio(background, dark) >= contrastRatio(background, light)
+    ? dark
+    : light;
+}
+
+function linearize(channel: number): number {
+  const value = channel / 255;
+  return value <= LINEAR_THRESHOLD
+    ? value / 12.92
+    : ((value + 0.055) / 1.055) ** 2.4;
+}

package/src/color/core/hex.ts

@@ -0,0 +1,57 @@
+const HEX_COLOR = /^#(?:[\da-f]{3}|[\da-f]{6})$/i;
+const SHORT_LENGTH = 3;
+const MAXIMUM_CHANNEL = 255;
+
+/** The three channels of a colour, each from 0 to 255. */
+export interface RgbColor {
+  /** Red channel. */
+  red: number;
+  /** Green channel. */
+  green: number;
+  /** Blue channel. */
+  blue: number;
+}
+
+/**
+ * Read a `#rgb` or `#rrggbb` colour into its three channels.
+ * @param color - A hex colour with its leading `#`, in either the short or the long form.
+ * @returns The three channels, each from 0 to 255.
+ * @throws {Error} When the string is not a hex colour, naming the value that was read.
+ */
+export function parseHexColor(color: string): RgbColor {
+  const text = typeof color === 'string' ? color.trim() : '';
+  if (!HEX_COLOR.test(text)) {
+    throw new Error(`not a hex colour: ${color}`);
+  }
+  const digits = text.slice(1);
+  const size = digits.length === SHORT_LENGTH ? 1 : 2;
+  return {
+    red: channelAt(digits, 0, size),
+    green: channelAt(digits, 1, size),
+    blue: channelAt(digits, 2, size),
+  };
+}
+
+/**
+ * Write three channels back as a `#rrggbb` colour.
+ *
+ * Each channel is rounded and held inside 0..255, so the result of an
+ * interpolation is always a colour a browser accepts.
+ * @param color - The three channels.
+ * @returns The lower-case six-digit hex colour.
+ */
+export function toHexColor(color: RgbColor): string {
+  return `#${channelHex(color.red)}${channelHex(color.green)}${channelHex(color.blue)}`;
+}
+
+function channelAt(digits: string, index: number, size: number): number {
+  const part = digits.slice(index * size, index * size + size);
+  return Number.parseInt(size === 1 ? `${part}${part}` : part, 16);
+}
+
+function channelHex(value: number): string {
+  const safe = Number.isFinite(value)
+    ? Math.min(MAXIMUM_CHANNEL, Math.max(0, Math.round(value)))
+    : 0;
+  return safe.toString(16).padStart(2, '0');
+}

package/src/color/core/index.ts

@@ -0,0 +1,4 @@
+export type { ReadableInkOptions } from './contrast.ts';
+export { contrastRatio, readableInk, relativeLuminance } from './contrast.ts';
+export type { PositionInRangeOptions, Swatch } from './scale.ts';
+export { VIRIDIS_SCALE, positionInRange, swatchFromScale } from './scale.ts';

package/src/color/core/scale.ts

@@ -0,0 +1,132 @@
+import type { ReadableInkOptions } from './contrast.ts';
+import { readableInk } from './contrast.ts';
+import { parseHexColor, toHexColor } from './hex.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.
+ */
+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;
+}
+
+/** How {@link positionInRange} places a value. */
+export interface PositionInRangeOptions {
+  /**
+   * Whether to place the value on a base-10 logarithmic scale, for a quantity
+   * — an abundance, a density, a concentration — spread over so many decades
+   * that a linear placement gives all but a couple of values the same colour.
+   * @default false
+   */
+  logarithmic?: boolean;
+}
+
+/**
+ * Where a value sits between two bounds.
+ * @param value - The value to place.
+ * @param min - The smallest value the range holds.
+ * @param max - The largest value it holds.
+ * @param options - See {@link PositionInRangeOptions}.
+ * @returns A fraction clamped to 0..1; the middle when the range holds a single value, and 0 when any of the three numbers is not finite.
+ */
+export function positionInRange(
+  value: number,
+  min: number,
+  max: number,
+  options: PositionInRangeOptions = {},
+): number {
+  const { logarithmic = false } = options;
+  if (
+    !Number.isFinite(value) ||
+    !Number.isFinite(min) ||
+    !Number.isFinite(max)
+  ) {
+    return 0;
+  }
+  if (max === min) return 0.5;
+  if (!logarithmic) return clampUnit((value - min) / (max - min));
+
+  const floor = Math.max(min, smallestPositive(min, max));
+  const span = Math.log10(max) - Math.log10(floor);
+  if (span === 0) return 0.5;
+  return clampUnit(
+    (Math.log10(Math.max(value, floor)) - Math.log10(floor)) / span,
+  );
+}
+
+/**
+ * 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.
+ * @returns The colour at that position, as `#rrggbb`.
+ * @throws {Error} When the scale has no stops, or a stop 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,
+  });
+}
+
+/**
+ * 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.
+ * @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.
+ */
+export function swatchFromScale(
+  stops: readonly string[],
+  position: number,
+  options: ReadableInkOptions = {},
+): Swatch {
+  const background = colorFromScale(stops, position);
+  return { background, foreground: readableInk(background, options) };
+}
+
+function clampUnit(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+function smallestPositive(min: number, max: number): number {
+  if (min > 0) return min;
+  if (max <= 0) return 1;
+  return max * 1e-12;
+}

package/src/color/ui/ColorScaleLegend.tsx

@@ -0,0 +1,144 @@
+import type { CSSProperties, ReactElement } from 'react';
+import { useId } from 'react';
+
+import { formatTrimmed } from '../../format/core/numbers.ts';
+
+const FALLBACK_STOPS: readonly string[] = ['#e4e8ee'];
+const BAR_HEIGHT = 12;
+const BAR_WIDTH = 100;
+
+/** What {@link ColorScaleLegend} needs to draw a scale. */
+export interface ColorScaleLegendProps {
+  /** The scale's colours, from its low end to its high end. */
+  stops: readonly string[];
+  /** The value the low end stands for. */
+  min: number;
+  /** The value the high end stands for. */
+  max: number;
+  /**
+   * Unit written after each end value, e.g. `g/mol`.
+   * @default '' — no unit is written
+   */
+  unit?: string;
+  /**
+   * What the scale measures, written before it.
+   * @default '' — no label is written
+   */
+  label?: string;
+  /**
+   * How an end value is written.
+   * @default a rounding to three decimals with the trailing zeros dropped
+   */
+  formatValue?: (value: number) => string;
+}
+
+/**
+ * The key to a sequential colour scale: its two end values, and the ramp
+ * between them.
+ *
+ * The ramp is a real gradient rather than a row of buckets, and both ends
+ * carry their value, so a figure lifted out of the page still says what it is
+ * measuring. It is drawn as an SVG, which keeps it crisp in a print and in an
+ * exported image.
+ * @param props - See {@link ColorScaleLegendProps}.
+ * @returns The labelled gradient strip.
+ */
+export function ColorScaleLegend(props: ColorScaleLegendProps): ReactElement {
+  const {
+    stops,
+    min,
+    max,
+    unit = '',
+    label = '',
+    formatValue = defaultFormatValue,
+  } = props;
+  const gradientId = useId();
+
+  const scale = stops.length === 0 ? FALLBACK_STOPS : stops;
+  const low = withUnit(formatValue(min), unit);
+  const high = withUnit(formatValue(max), unit);
+
+  return (
+    <div style={ROW_STYLE}>
+      {label === '' ? null : <span style={LABEL_STYLE}>{label}</span>}
+      <span style={VALUE_STYLE}>{low}</span>
+      <svg
+        style={BAR_STYLE}
+        viewBox={`0 0 ${BAR_WIDTH} ${BAR_HEIGHT}`}
+        preserveAspectRatio="none"
+        role="img"
+        aria-label={`${label === '' ? 'Colour scale' : label} from ${low} to ${high}`}
+      >
+        <defs>
+          <linearGradient id={gradientId} x1="0" y1="0" x2="1" y2="0">
+            {gradientStops(scale).map((stop) => (
+              <stop
+                key={stop.offset}
+                offset={stop.offset}
+                stopColor={stop.color}
+              />
+            ))}
+          </linearGradient>
+        </defs>
+        <rect
+          x="0"
+          y="0"
+          width={BAR_WIDTH}
+          height={BAR_HEIGHT}
+          rx="2"
+          fill={`url(#${gradientId})`}
+        />
+      </svg>
+      <span style={VALUE_STYLE}>{high}</span>
+    </div>
+  );
+}
+
+function gradientStops(
+  stops: readonly string[],
+): Array<{ offset: number; color: string }> {
+  const last = stops.length - 1;
+  const rendered: Array<{ offset: number; color: string }> = [];
+  for (let index = 0; index < stops.length; index++) {
+    const color = stops[index];
+    if (color === undefined) continue;
+    rendered.push({ offset: last === 0 ? index : index / last, color });
+  }
+  if (rendered.length === 1) {
+    const only = rendered[0];
+    if (only !== undefined) rendered.push({ offset: 1, color: only.color });
+  }
+  return rendered;
+}
+
+function defaultFormatValue(value: number): string {
+  return formatTrimmed(value, 3);
+}
+
+function withUnit(value: string, unit: string): string {
+  return unit === '' ? value : `${value} ${unit}`;
+}
+
+const ROW_STYLE = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  color: 'rgb(95 107 124)',
+  fontSize: 12,
+} as const satisfies CSSProperties;
+
+const VALUE_STYLE = {
+  fontSize: 12,
+  fontVariantNumeric: 'tabular-nums',
+} as const satisfies CSSProperties;
+
+const BAR_STYLE = {
+  display: 'inline-block',
+  flex: '1 1 160px',
+  maxWidth: 320,
+  height: BAR_HEIGHT,
+} as const satisfies CSSProperties;

package/src/color/ui/index.ts

@@ -0,0 +1,2 @@
+export type { ColorScaleLegendProps } from './ColorScaleLegend.tsx';
+export { ColorScaleLegend } from './ColorScaleLegend.tsx';

package/src/core.ts

@@ -1,3 +1,14 @@
 export * from './citation/core/index.ts';
+export * from './clipboard/core/index.ts';
+export * from './color/core/index.ts';
+export * from './credits/core/index.ts';
+export * from './delimited/core/index.ts';
+export * from './download/core/index.ts';
 export * from './ecosystem/core/index.ts';
+export * from './format/core/index.ts';
 export * from './orbital/core/index.ts';
+export * from './pedagogy/core/index.ts';
+export * from './router/core/index.ts';
+export * from './seo/core/index.ts';
+export * from './share/core/index.ts';
+export * from './worker/core/index.ts';