react-cheminfo 0.11.0 → 0.13.0

package/src/clipboard/ui/CopyButton.tsx

@@ -1,4 +1,4 @@
-import type { IconName } from '@blueprintjs/core';
+import type { IconName, Intent } from '@blueprintjs/core';
 import { Button } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 
@@ -7,6 +7,7 @@ import {
   useCopyToClipboard,
 } from './useCopyToClipboard.ts';
 
+/** What {@link CopyButton} copies, and how it reads. */
 export interface CopyButtonProps {
   /**
    * What to copy. A function is called when the button is pressed, which is
@@ -26,6 +27,11 @@ export interface CopyButtonProps {
    * @default 'Copied'
    */
   copiedLabel?: string;
+  /**
+   * Text shown while a refused copy is being reported, when there is a label.
+   * @default 'Copy failed'
+   */
+  failedLabel?: string;
   /**
    * Whether the button drops its background, for a toolbar or a code block.
    * @default false
@@ -64,7 +70,8 @@ export interface CopyButtonProps {
 }
 
 /**
- * A button that puts a piece of text on the clipboard and says so.
+ * A button that puts a piece of text on the clipboard and says so — with a
+ * tick when it worked, and a cross when the browser refused it.
  * @param props - What to copy, what the button reads, and how it looks.
  * @returns The copy button.
  */
@@ -73,6 +80,7 @@ export function CopyButton(props: CopyButtonProps): ReactElement {
     content,
     label,
     copiedLabel = 'Copied',
+    failedLabel = 'Copy failed',
     minimal = false,
     small = false,
     icon = 'duplicate',
@@ -81,16 +89,24 @@ export function CopyButton(props: CopyButtonProps): ReactElement {
     title = 'Copy to clipboard',
     className,
   } = props;
-  const { copied, copy } = useCopyToClipboard(resetAfter);
+  const { copied, failed, copy } = useCopyToClipboard(resetAfter);
+  const look = buttonLook({
+    copied,
+    failed,
+    icon,
+    label,
+    copiedLabel,
+    failedLabel,
+  });
 
   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)}
+      icon={look.icon}
+      intent={look.intent}
+      text={look.text}
       disabled={disabled}
       title={title}
       aria-label={label ?? title}
@@ -101,11 +117,35 @@ export function CopyButton(props: CopyButtonProps): ReactElement {
   );
 }
 
-function buttonText(
-  label: string | undefined,
-  copiedLabel: string,
-  copied: boolean,
-): string | undefined {
-  if (label === undefined) return undefined;
-  return copied ? copiedLabel : label;
+interface ButtonLookInput {
+  copied: boolean;
+  failed: boolean;
+  icon: IconName;
+  label: string | undefined;
+  copiedLabel: string;
+  failedLabel: string;
+}
+
+function buttonLook(input: ButtonLookInput): {
+  icon: IconName;
+  intent: Intent;
+  text: string | undefined;
+} {
+  const { copied, failed, icon, label, copiedLabel, failedLabel } = input;
+  const hasLabel = label !== undefined;
+  if (copied) {
+    return {
+      icon: 'tick',
+      intent: 'success',
+      text: hasLabel ? copiedLabel : undefined,
+    };
+  }
+  if (failed) {
+    return {
+      icon: 'cross',
+      intent: 'danger',
+      text: hasLabel ? failedLabel : undefined,
+    };
+  }
+  return { icon, intent: 'none', text: label };
 }

package/src/clipboard/ui/CopyableValue.tsx

@@ -0,0 +1,138 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import { MISSING_VALUE } from '../../format/core/missing.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
+import { CopyButton } from './CopyButton.tsx';
+
+const DEFAULT_BLOCK_HEIGHT = 160;
+
+/** What {@link CopyableValue} names, shows and copies. */
+export interface CopyableValueProps {
+  /** What the value is, written above it, e.g. `InChIKey`. */
+  label: string;
+  /** The value itself, which is also what the button copies. */
+  value: string;
+  /**
+   * A longer explanation of the label, shown on hover.
+   * @default undefined — the label carries no hover text
+   */
+  hint?: string;
+  /**
+   * Whether the value keeps its line breaks and scrolls past `maxHeight`, for
+   * a molfile or any other multi-line notation.
+   * @default false
+   */
+  block?: boolean;
+  /**
+   * Height past which a block value scrolls on its own.
+   * @default 160
+   */
+  maxHeight?: number | string;
+  /**
+   * What the pointer and a screen reader are told the button does.
+   * @default `Copy the ${label}`
+   */
+  copyTitle?: string;
+  /**
+   * What goes under the value: the links an identifier leads to, a note on it.
+   * @default undefined
+   */
+  children?: ReactNode;
+  /**
+   * Class the row carries, in addition to `copyable-value`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * One read-only value, named, with the button that copies it.
+ *
+ * A derived notation — a SMILES, an InChIKey, an accession — is only useful
+ * somewhere else, so it is shown with the single click that puts it on the
+ * clipboard, and selecting the value by hand takes all of it at once. An empty
+ * value reads as the missing marker and offers nothing to copy.
+ * @param props - See {@link CopyableValueProps}.
+ * @returns The labelled value and its copy button.
+ */
+export function CopyableValue(props: CopyableValueProps): ReactElement {
+  const {
+    label,
+    value,
+    hint,
+    block = false,
+    maxHeight = DEFAULT_BLOCK_HEIGHT,
+    copyTitle = `Copy the ${label}`,
+    children,
+    className,
+  } = props;
+  const isEmpty = value === '';
+
+  return (
+    <div
+      className={
+        className === undefined
+          ? 'copyable-value'
+          : `copyable-value ${className}`
+      }
+    >
+      <div style={HEADER_STYLE}>
+        <span
+          className="copyable-value__label"
+          style={hint === undefined ? LABEL_STYLE : HINTED_LABEL_STYLE}
+          title={hint}
+        >
+          {label}
+        </span>
+        <CopyButton
+          content={value}
+          title={copyTitle}
+          disabled={isEmpty}
+          minimal
+          small
+        />
+      </div>
+      <code
+        className="copyable-value__value"
+        style={block ? { ...BLOCK_VALUE_STYLE, maxHeight } : VALUE_STYLE}
+      >
+        {isEmpty ? MISSING_VALUE : value}
+      </code>
+      {children}
+    </div>
+  );
+}
+
+const HEADER_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  color: TOKEN.textMuted,
+  fontSize: 12,
+  fontWeight: 600,
+} as const satisfies CSSProperties;
+
+const HINTED_LABEL_STYLE = {
+  ...LABEL_STYLE,
+  cursor: 'help',
+} as const satisfies CSSProperties;
+
+const VALUE_STYLE = {
+  display: 'block',
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+  fontSize: 12,
+  overflowWrap: 'anywhere',
+  userSelect: 'all',
+} as const satisfies CSSProperties;
+
+const BLOCK_VALUE_STYLE = {
+  ...VALUE_STYLE,
+  whiteSpace: 'pre',
+  overflowWrap: 'normal',
+  overflow: 'auto',
+} as const satisfies CSSProperties;

package/src/clipboard/ui/copyFeedback.ts

@@ -0,0 +1,68 @@
+/** How the last copy went: taken by the clipboard, or refused. */
+type CopyOutcome = 'copied' | 'failed';
+
+/** What a copy leaves on screen for a moment. */
+export interface CopyFeedbackState {
+  /** How the last copy went, or `undefined` once its moment has passed. */
+  outcome: CopyOutcome | undefined;
+  /** The key the last copy was made under, so one entry of several shows it. */
+  key: string | undefined;
+}
+
+/** The state before anything was copied, and after the confirmation fades. */
+export const IDLE_COPY_FEEDBACK: CopyFeedbackState = {
+  outcome: undefined,
+  key: undefined,
+};
+
+/** The timer behind a copy confirmation. */
+export interface CopyFeedback {
+  /**
+   * Show how a copy went, replacing whatever was shown, for `resetAfter`.
+   * @param written - Whether the clipboard took it.
+   * @param key - Which of several copy actions it was.
+   */
+  announce: (written: boolean, key?: string) => void;
+  /**
+   * Stop the timer for good and clear an outcome still shown; later
+   * announcements show nothing.
+   */
+  dispose: () => void;
+}
+
+/**
+ * The confirmation a copy leaves behind, and the one timer that clears it.
+ *
+ * Kept apart from React so every copy action of the family — a button, a
+ * citation menu entry, a row of notations — confirms for the same time and
+ * leaves no timer behind once its component is gone.
+ * @param resetAfter - How long an outcome is shown, in milliseconds.
+ * @param onChange - Called with each new state.
+ * @returns The controller.
+ */
+export function createCopyFeedback(
+  resetAfter: number,
+  onChange: (state: CopyFeedbackState) => void,
+): CopyFeedback {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let disposed = false;
+
+  return {
+    announce: (written, key) => {
+      if (disposed) return;
+      clearTimeout(timer);
+      onChange({ outcome: written ? 'copied' : 'failed', key });
+      timer = setTimeout(() => {
+        timer = undefined;
+        onChange(IDLE_COPY_FEEDBACK);
+      }, resetAfter);
+    },
+    dispose: () => {
+      disposed = true;
+      if (timer === undefined) return;
+      clearTimeout(timer);
+      timer = undefined;
+      onChange(IDLE_COPY_FEEDBACK);
+    },
+  };
+}

package/src/clipboard/ui/index.ts

@@ -1,8 +1,10 @@
 export type { CodeBlockProps, CodeBlockTone } from './CodeBlock.tsx';
 export { CodeBlock } from './CodeBlock.tsx';
+export type { CopyableValueProps } from './CopyableValue.tsx';
+export { CopyableValue } from './CopyableValue.tsx';
 export type { CopyButtonProps } from './CopyButton.tsx';
 export { CopyButton } from './CopyButton.tsx';
-export type { CopyToClipboard } from './useCopyToClipboard.ts';
+export type { CopyContent, CopyToClipboard } from './useCopyToClipboard.ts';
 export {
   DEFAULT_COPY_RESET_AFTER,
   useCopyToClipboard,

package/src/clipboard/ui/useCopyToClipboard.ts

@@ -1,57 +1,85 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
+import type { ClipboardContent } from '../core/writeToClipboard.ts';
 import { writeToClipboard } from '../core/writeToClipboard.ts';
 
+import type { CopyFeedback, CopyFeedbackState } from './copyFeedback.ts';
+import { IDLE_COPY_FEEDBACK, createCopyFeedback } from './copyFeedback.ts';
+
 /** How long a copy is confirmed for, in milliseconds, unless asked otherwise. */
 export const DEFAULT_COPY_RESET_AFTER = 1500;
 
+/**
+ * What a copy puts on the clipboard: text, text with its HTML, or a write of
+ * the caller's own — `() => writeBlobToClipboard(png)` for an image. A write
+ * function is called at once, still inside the click that started it.
+ */
+export type CopyContent = ClipboardContent | (() => Promise<boolean>);
+
 /** 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;
+  /** Whether the last copy was refused and that is still being shown. */
+  failed: boolean;
   /**
-   * Put text on the clipboard and confirm it.
-   * @param text - What to copy.
+   * The key the last copy was made under while its outcome is shown, so a
+   * menu of several copy actions confirms on the one that was used.
+   */
+  key: string | undefined;
+  /**
+   * Put content on the clipboard and confirm how it went.
+   * @param content - What to copy.
+   * @param key - Which of several copy actions this is.
    * @returns Whether the clipboard took it.
    */
-  copy: (text: string) => Promise<boolean>;
+  copy: (content: CopyContent, key?: string) => Promise<boolean>;
 }
 
 /**
- * Copy text and say so for a moment afterwards.
+ * Copy, and say how it went 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.
+ * row leaving a list, a menu closing — leaves no timer behind. A refused copy
+ * is shown too, for as long, so the reader is told the clipboard is empty.
+ * @param resetAfter - How long the outcome is shown, in milliseconds.
+ * @returns The outcome flags, the key they belong to, 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);
+  const [state, setState] = useState<CopyFeedbackState>(IDLE_COPY_FEEDBACK);
+  const feedback = useRef<CopyFeedback | null>(null);
 
   useEffect(() => {
-    isMounted.current = true;
+    const controller = createCopyFeedback(resetAfter, setState);
+    feedback.current = controller;
     return () => {
-      isMounted.current = false;
-      clearTimeout(timer.current);
+      controller.dispose();
+      feedback.current = null;
     };
+  }, [resetAfter]);
+
+  const copy = useCallback(async (content: CopyContent, key?: string) => {
+    const written = await write(content);
+    feedback.current?.announce(written, key);
+    return written;
   }, []);
 
-  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 };
+  return {
+    copied: state.outcome === 'copied',
+    failed: state.outcome === 'failed',
+    key: state.key,
+    copy,
+  };
+}
+
+async function write(content: CopyContent): Promise<boolean> {
+  if (typeof content !== 'function') return writeToClipboard(content);
+  try {
+    return await content();
+  } catch {
+    return false;
+  }
 }

package/src/color/core/hex.ts

@@ -1,3 +1,5 @@
+import { clamp } from '../../format/core/clamp.ts';
+
 const HEX_COLOR = /^#(?:[\da-f]{3}|[\da-f]{6})$/i;
 const SHORT_LENGTH = 3;
 const MAXIMUM_CHANNEL = 255;
@@ -44,14 +46,28 @@ export function toHexColor(color: RgbColor): string {
   return `#${channelHex(color.red)}${channelHex(color.green)}${channelHex(color.blue)}`;
 }
 
+/**
+ * A colour written by hand, carried by a link or read from storage, in the one
+ * form two colours can be compared in: lower-case `#rrggbb`.
+ *
+ * It is also the only form a `type="color"` input accepts, so a short `#fff`
+ * from a shared link is spelled out rather than silently replaced.
+ * @param value - Anything; a `#rgb` or `#rrggbb` string in either case, spaces around it allowed.
+ * @returns The six-digit lower-case colour, or `null` when the value is not a hex colour.
+ */
+export function normalizeHexColor(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  if (!HEX_COLOR.test(text)) return null;
+  return toHexColor(parseHexColor(text));
+}
+
 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;
+  const safe = clamp(Math.round(value), 0, MAXIMUM_CHANNEL);
   return safe.toString(16).padStart(2, '0');
 }

package/src/color/core/hsv.ts

@@ -1,3 +1,5 @@
+import { clamp } from '../../format/core/clamp.ts';
+
 import type { RgbColor } from './hex.ts';
 
 const TURN = 360;
@@ -48,8 +50,8 @@ export function rgbToHsv(color: RgbColor): HsvColor {
  */
 export function hsvToRgb(color: HsvColor): RgbColor {
   const hue = wrapHue(color.hue) / SECTOR;
-  const saturation = unit(color.saturation);
-  const value = unit(color.value);
+  const saturation = clamp(color.saturation, 0, 1);
+  const value = clamp(color.value, 0, 1);
   const sector = Math.floor(hue) % 6;
   const offset = hue - Math.floor(hue);
   const low = value * (1 - saturation);
@@ -102,11 +104,5 @@ function scale(red: number, green: number, blue: number): RgbColor {
 }
 
 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));
+  return clamp(value / MAXIMUM_CHANNEL, 0, 1);
 }

package/src/color/core/index.ts

@@ -1,7 +1,7 @@
 export type { ReadableInkOptions } from './contrast.ts';
 export { contrastRatio, readableInk, relativeLuminance } from './contrast.ts';
 export type { RgbColor } from './hex.ts';
-export { parseHexColor, toHexColor } from './hex.ts';
+export { normalizeHexColor, parseHexColor, toHexColor } from './hex.ts';
 export { colorScaleGradient } from './gradient.ts';
 export type { HsvColor } from './hsv.ts';
 export { hsvToRgb, rgbToHsv, wrapHue } from './hsv.ts';
@@ -13,12 +13,7 @@ export type {
 } 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 { positionInRange } from './scale.ts';
 export type { ColorScaleKind, NamedColorScale } from './scales.ts';
 export {
   COLOR_SCALES,

package/src/color/core/interpolate.ts

@@ -1,3 +1,5 @@
+import { clamp } from '../../format/core/clamp.ts';
+
 import type { ReadableInkOptions } from './contrast.ts';
 import { readableInk } from './contrast.ts';
 import { parseHexColor, toHexColor } from './hex.ts';
@@ -76,7 +78,7 @@ export function colorAt(scale: ColorScale, position: number): string {
   if (stops.length === 0) {
     throw new Error('a colour scale needs at least one stop');
   }
-  const at = clampUnit(position);
+  const at = clamp(position, 0, 1);
   const first = stops[0];
   const last = stops.at(-1);
   if (first === undefined || last === undefined) {
@@ -172,8 +174,3 @@ function hueStep(
   // 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,18 +1,4 @@
-import type { ReadableInkOptions } from './contrast.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[] = VIRIDIS_COLORS;
+import { clamp } from '../../format/core/clamp.ts';
 
 /** How {@link positionInRange} places a value. */
 export interface PositionInRangeOptions {
@@ -48,51 +34,18 @@ export function positionInRange(
     return 0;
   }
   if (max === min) return 0.5;
-  if (!logarithmic) return clampUnit((value - min) / (max - min));
+  if (!logarithmic) return clamp((value - min) / (max - min), 0, 1);
 
   const floor = Math.max(min, smallestPositive(min, max));
   const span = Math.log10(max) - Math.log10(floor);
   if (span === 0) return 0.5;
-  return clampUnit(
+  return clamp(
     (Math.log10(Math.max(value, floor)) - Math.log10(floor)) / span,
+    0,
+    1,
   );
 }
 
-/**
- * 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 list is empty, or a colour is not a hex colour.
- */
-export function colorFromScale(
-  stops: readonly string[],
-  position: number,
-): string {
-  return colorAt(evenScale(stops), position);
-}
-
-/**
- * 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 list is empty, or a colour is not a hex colour.
- */
-export function swatchFromScale(
-  stops: readonly string[],
-  position: number,
-  options: ReadableInkOptions = {},
-): Swatch {
-  return swatchAt(evenScale(stops), position, 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;

package/src/color/core/scaleText.ts

@@ -1,3 +1,6 @@
+import { clamp } from '../../format/core/clamp.ts';
+import { formatTrimmed } from '../../format/core/numbers.ts';
+
 import type {
   ColorInterpolation,
   ColorScale,
@@ -117,7 +120,7 @@ function parseStop(piece: string): ColorStop | null {
   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}` };
+  return { position: clamp(position, 0, 1), color: `#${color}` };
 }
 
 function isInterpolation(value: string): value is ColorInterpolation {
@@ -128,7 +131,5 @@ function isInterpolation(value: string): value is ColorInterpolation {
 }
 
 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)));
+  return formatTrimmed(clamp(position, 0, 1), POSITION_DECIMALS);
 }