react-cheminfo 0.2.0 → 0.4.0

package/src/citation/ui/useCopyFeedback.ts

@@ -0,0 +1,76 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { copyCitations } from '../core/clipboard.ts';
+import type { CitationFormatId } from '../core/formats.ts';
+import type { Reference } from '../core/reference.ts';
+import type { CitationStyleId } from '../core/segments.ts';
+
+import type { CopyState } from './entries.tsx';
+
+// How long the tick replaces the clipboard glyph of an entry after a copy.
+const FEEDBACK_MS = 1500;
+
+/** Copying, with the feedback the entry that was clicked then shows. */
+export interface CopyFeedback {
+  /** The feedback showing on the entry known as `key`, if any. */
+  stateOf: (key: string) => CopyState | null;
+  /**
+   * Copy the references, and announce the outcome on the entry known as `key`.
+   */
+  copy: (
+    key: string,
+    references: readonly Reference[],
+    format: CitationFormatId,
+    style?: CitationStyleId,
+  ) => void;
+}
+
+/**
+ * Hold which entry of a citation menu was clicked last and how it went, so the
+ * tick — or the cross a denied clipboard leaves — shows on that entry alone.
+ * @returns The copy action, and the feedback of the entry that used it.
+ */
+export function useCopyFeedback(): CopyFeedback {
+  const [copied, setCopied] = useState<string | null>(null);
+  const [hasFailed, setHasFailed] = useState(false);
+  const timeout = useRef<number | null>(null);
+
+  useEffect(() => {
+    return () => {
+      if (timeout.current !== null) window.clearTimeout(timeout.current);
+    };
+  }, []);
+
+  function announce(key: string, failed: boolean): void {
+    setCopied(key);
+    setHasFailed(failed);
+    if (timeout.current !== null) window.clearTimeout(timeout.current);
+    timeout.current = window.setTimeout(() => {
+      setCopied(null);
+      setHasFailed(false);
+    }, FEEDBACK_MS);
+  }
+
+  return {
+    stateOf: (key) => (copied === key ? feedback(hasFailed) : null),
+    copy: (key, references, format, style) => {
+      copyCitations(references, format, style).then(
+        () => {
+          announce(key, false);
+        },
+        () => {
+          // A denied clipboard permission is the usual cause, and the menu is
+          // the only place the user can be told about it.
+          announce(key, true);
+        },
+      );
+    },
+  };
+}
+
+function feedback(failed: boolean): CopyState {
+  if (failed) {
+    return { icon: 'cross', intent: 'danger', label: 'copy failed' };
+  }
+  return { icon: 'tick', intent: 'success', label: 'copied' };
+}

package/src/clipboard/core/index.ts

@@ -0,0 +1 @@
+export { writeToClipboard } from './writeToClipboard.ts';

package/src/clipboard/core/writeToClipboard.ts

@@ -0,0 +1,47 @@
+/**
+ * Put a piece of text on the clipboard, without ever throwing at the caller.
+ *
+ * The async Clipboard API is tried first and a hidden textarea is the fallback,
+ * which is what a page served over plain HTTP, an older Safari, or a browser
+ * that refused the permission is left with. A refusal is an outcome the caller
+ * shows rather than an error it has to catch, so both paths resolve.
+ * @param text - What to put on the clipboard.
+ * @returns Whether the clipboard now holds the text.
+ */
+export async function writeToClipboard(text: string): Promise<boolean> {
+  const clipboard = globalThis.navigator?.clipboard;
+  if (clipboard) {
+    try {
+      await clipboard.writeText(text);
+      return true;
+    } catch {
+      // A denied permission, or a call the browser no longer considers to come
+      // from a user gesture. The textarea below still works in both cases.
+    }
+  }
+  return writeWithTextArea(text);
+}
+
+function writeWithTextArea(text: string): boolean {
+  if (typeof document === 'undefined') return false;
+
+  const textArea = document.createElement('textarea');
+  textArea.value = text;
+  textArea.setAttribute('readonly', '');
+  // Off the screen rather than hidden: a `display: none` element selects
+  // nothing, and a visible one scrolls the page as it is focused.
+  textArea.style.position = 'fixed';
+  textArea.style.top = '-9999px';
+  textArea.style.opacity = '0';
+  document.body.append(textArea);
+  textArea.select();
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-deprecated -- the deprecated command is what the fallback is
+    return document.execCommand('copy');
+  } catch {
+    return false;
+  } finally {
+    textArea.remove();
+  }
+}

package/src/clipboard/ui/CodeBlock.tsx

@@ -0,0 +1,110 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import { CopyButton } from './CopyButton.tsx';
+
+/** How a code block sits on the page it is shown in. */
+export type CodeBlockTone = 'default' | 'muted' | 'dark';
+
+const HOLDER_STYLE: CSSProperties = { position: 'relative' };
+const COPY_STYLE: CSSProperties = { position: 'absolute', top: 4, right: 4 };
+
+const BASE_PRE_STYLE: CSSProperties = {
+  margin: 0,
+  padding: '8px 10px',
+  borderRadius: 4,
+  fontSize: 12,
+  whiteSpace: 'pre-wrap',
+  overflowWrap: 'anywhere',
+};
+
+const TONE_STYLE: Record<CodeBlockTone, CSSProperties> = {
+  default: {},
+  muted: { background: '#f6f7f9', border: '1px solid #d3d8de' },
+  dark: {
+    background: '#1e293b',
+    border: '1px solid #1e293b',
+    color: '#e2e8f0',
+  },
+};
+
+export interface CodeBlockProps {
+  /** The text shown, and what the copy button hands over. */
+  code: string;
+  /**
+   * What is drawn in place of the plain text — syntax coloured spans, for
+   * instance. The code itself is still what gets copied.
+   * @default undefined — the code is shown as it is
+   */
+  children?: ReactNode;
+  /**
+   * How the block is painted: nothing of its own, a light grey panel, or a
+   * dark one.
+   * @default 'default'
+   */
+  tone?: CodeBlockTone;
+  /**
+   * Whether a copy button sits in the corner of the block.
+   * @default false
+   */
+  copyable?: boolean;
+  /**
+   * Height past which the block scrolls on its own rather than pushing what
+   * follows it down the page.
+   * @default undefined — the block is as tall as its content
+   */
+  maxHeight?: number | string;
+  /**
+   * Class the holder carries, in addition to `code-block`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * A block of text to hand over: the address of a page, the markup that frames
+ * it, or a sample meant to be pasted into an editor and run.
+ * @param props - The code, how it is painted, and whether it can be copied.
+ * @returns The code block.
+ */
+export function CodeBlock(props: CodeBlockProps): ReactElement {
+  const {
+    code,
+    children,
+    tone = 'default',
+    copyable = false,
+    maxHeight,
+    className,
+  } = props;
+
+  return (
+    <div className={holderClassName(tone, className)} style={HOLDER_STYLE}>
+      <pre style={preStyle(tone, copyable, maxHeight)}>{children ?? code}</pre>
+      {copyable ? (
+        <span style={COPY_STYLE}>
+          <CopyButton content={code} minimal small />
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+function holderClassName(tone: CodeBlockTone, className?: string): string {
+  const names = ['code-block'];
+  if (tone !== 'default') names.push(`code-block--${tone}`);
+  if (className !== undefined) names.push(className);
+  return names.join(' ');
+}
+
+function preStyle(
+  tone: CodeBlockTone,
+  copyable: boolean,
+  maxHeight: number | string | undefined,
+): CSSProperties {
+  return {
+    ...BASE_PRE_STYLE,
+    ...TONE_STYLE[tone],
+    // The button floats over the corner, so the text stops before it.
+    ...(copyable ? { paddingRight: 42 } : {}),
+    ...(maxHeight === undefined ? {} : { maxHeight, overflowY: 'auto' }),
+  };
+}

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