react-cheminfo 0.3.0 → 0.4.1

package/src/error/ui/toError.ts

@@ -0,0 +1,33 @@
+/**
+ * Turn whatever a component threw into an `Error`.
+ *
+ * A `throw` is not required to carry an `Error` — a rejected fetch, a worker
+ * message or a library can throw a string, an object or `undefined` — and the
+ * boundary still has to name what happened.
+ * @param thrown - The value that came out of the render.
+ * @returns The value itself when it is an error, otherwise one describing it.
+ */
+export function toError(thrown: unknown): Error {
+  if (thrown instanceof Error) return thrown;
+  if (typeof thrown === 'string' && thrown !== '') return new Error(thrown);
+  return new Error(describe(thrown));
+}
+
+const UNPRINTABLE = 'an unprintable value was thrown';
+
+function describe(thrown: unknown): string {
+  if (thrown === null) return 'null was thrown';
+  if (thrown === undefined) return 'undefined was thrown';
+  if (
+    typeof thrown === 'number' ||
+    typeof thrown === 'boolean' ||
+    typeof thrown === 'bigint'
+  ) {
+    return String(thrown);
+  }
+  try {
+    return JSON.stringify(thrown) ?? UNPRINTABLE;
+  } catch {
+    return UNPRINTABLE;
+  }
+}

package/src/format/core/index.ts

@@ -0,0 +1,9 @@
+export { MISSING_VALUE } from './missing.ts';
+export {
+  formatCompact,
+  formatDecimal,
+  formatInteger,
+  formatTrimmed,
+} from './numbers.ts';
+export { formatBytes, formatDuration } from './units.ts';
+export { pluralize } from './words.ts';

package/src/format/core/missing.ts

@@ -0,0 +1,6 @@
+/**
+ * What every formatter of this module writes when it has nothing to show — a
+ * missing value, or one that is not a finite number. An en dash, so an empty
+ * cell of a table still reads as a cell.
+ */
+export const MISSING_VALUE = '–';

package/src/format/core/numbers.ts

@@ -0,0 +1,84 @@
+import { MISSING_VALUE } from './missing.ts';
+
+const INTEGER_FORMATTER = new Intl.NumberFormat('en-US', {
+  maximumFractionDigits: 0,
+});
+
+const COMPACT_FORMATTER = new Intl.NumberFormat('en-US', {
+  notation: 'compact',
+  maximumFractionDigits: 1,
+});
+
+const MAXIMUM_DIGITS = 20;
+const DEFAULT_DIGITS = 2;
+
+const decimalFormatters = new Map<number, Intl.NumberFormat>();
+
+/**
+ * A whole number, grouped in thousands: `1,234,567`.
+ *
+ * Anything after the decimal point is rounded away. The locale is fixed to
+ * `en-US`, so the same page reads the same way wherever it is opened.
+ * @param value - The number to write.
+ * @returns The grouped number, or the missing marker when it is not finite.
+ */
+export function formatInteger(value: number): string {
+  if (!Number.isFinite(value)) return MISSING_VALUE;
+  return INTEGER_FORMATTER.format(value);
+}
+
+/**
+ * A number grouped in thousands and held to a fixed number of decimals:
+ * `1,234.50`.
+ *
+ * The digits are kept even when they are zeros, which is what a column of
+ * figures wants; use {@link formatTrimmed} for a label that should not carry
+ * them.
+ * @param value - The number to write.
+ * @param digits - Decimals to show. Defaults to `2`; a count outside 0..20 is clamped into it, and one that is not a number falls back to the default.
+ * @returns The formatted number, or the missing marker when it is not finite.
+ */
+export function formatDecimal(value: number, digits = DEFAULT_DIGITS): string {
+  if (!Number.isFinite(value)) return MISSING_VALUE;
+  const safeDigits = clampDigits(digits);
+  let formatter = decimalFormatters.get(safeDigits);
+  if (formatter === undefined) {
+    formatter = new Intl.NumberFormat('en-US', {
+      minimumFractionDigits: safeDigits,
+      maximumFractionDigits: safeDigits,
+    });
+    decimalFormatters.set(safeDigits, formatter);
+  }
+  return formatter.format(value);
+}
+
+/**
+ * A number rounded to `digits` decimals with the trailing zeros dropped:
+ * `1.5`, `2`, `0.125`.
+ *
+ * The thousands are not grouped, so the result stays a number a reader can
+ * type back in — this is the form an axis tick, a chip or an exported cell
+ * takes.
+ * @param value - The number to write.
+ * @param digits - Decimals to round to. Defaults to `2`; a count outside 0..20 is clamped into it, and one that is not a number falls back to the default.
+ * @returns The rounded number, or the missing marker when it is not finite.
+ */
+export function formatTrimmed(value: number, digits = DEFAULT_DIGITS): string {
+  if (!Number.isFinite(value)) return MISSING_VALUE;
+  return Number.parseFloat(value.toFixed(clampDigits(digits))).toString();
+}
+
+/**
+ * A number shortened for a cramped axis or a badge: `999`, `1.2K`, `3.4M`.
+ * @param value - The number to write.
+ * @returns The shortened number, or the missing marker when it is not finite.
+ */
+export function formatCompact(value: number): string {
+  if (!Number.isFinite(value)) return MISSING_VALUE;
+  return COMPACT_FORMATTER.format(value);
+}
+
+function clampDigits(digits: number): number {
+  if (!Number.isFinite(digits)) return DEFAULT_DIGITS;
+  return Math.min(MAXIMUM_DIGITS, Math.max(0, Math.trunc(digits)));
+}

package/src/format/core/units.ts

@@ -0,0 +1,60 @@
+import { MISSING_VALUE } from './missing.ts';
+
+const BYTE_UNITS = ['B', 'kB', 'MB', 'GB', 'TB', 'PB'] as const;
+const BYTES_PER_UNIT = 1024;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+
+/**
+ * A byte count in the largest unit that keeps it under a thousand: `512 B`,
+ * `1.5 kB`, `240 MB`.
+ *
+ * Bytes are whole; every larger unit keeps one decimal until the number
+ * reaches a hundred, where the decimal stops carrying information.
+ * @param bytes - The size in bytes.
+ * @returns The size and its unit, or the missing marker when there is no finite, non-negative size.
+ */
+export function formatBytes(bytes: number | undefined): string {
+  if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0) {
+    return MISSING_VALUE;
+  }
+  let value = bytes;
+  let unitIndex = 0;
+  while (value >= BYTES_PER_UNIT && unitIndex < BYTE_UNITS.length - 1) {
+    value /= BYTES_PER_UNIT;
+    unitIndex += 1;
+  }
+  const digits = unitIndex === 0 || value >= 100 ? 0 : 1;
+  return `${value.toFixed(digits)} ${BYTE_UNITS[unitIndex] ?? 'B'}`;
+}
+
+/**
+ * A duration written with its two largest units: `45s`, `3m 20s`, `2h 05m`.
+ * @param milliseconds - The duration in milliseconds.
+ * @returns The duration, or the missing marker when there is no finite, non-negative duration.
+ */
+export function formatDuration(milliseconds: number | undefined): string {
+  if (
+    milliseconds === undefined ||
+    !Number.isFinite(milliseconds) ||
+    milliseconds < 0
+  ) {
+    return MISSING_VALUE;
+  }
+  const seconds = Math.round(milliseconds / 1000);
+  if (seconds < SECONDS_PER_MINUTE) return `${seconds}s`;
+
+  const minutes = Math.floor(seconds / SECONDS_PER_MINUTE);
+  const remainingSeconds = seconds % SECONDS_PER_MINUTE;
+  if (minutes < MINUTES_PER_HOUR) {
+    return `${minutes}m ${pad(remainingSeconds)}s`;
+  }
+
+  const hours = Math.floor(minutes / MINUTES_PER_HOUR);
+  const remainingMinutes = minutes % MINUTES_PER_HOUR;
+  return `${hours}h ${pad(remainingMinutes)}m`;
+}
+
+function pad(value: number): string {
+  return value.toString().padStart(2, '0');
+}

package/src/format/core/words.ts

@@ -0,0 +1,17 @@
+/**
+ * The noun that agrees with a count.
+ *
+ * Only the noun comes back, never the number, so the caller decides how the
+ * count itself is written: `${formatInteger(n)} ${pluralize(n, 'structure')}`.
+ * @param count - How many there are.
+ * @param singular - The noun for exactly one.
+ * @param plural - The noun for any other count. Defaults to the singular with an `s`.
+ * @returns The singular for a count of one, the plural otherwise.
+ */
+export function pluralize(
+  count: number,
+  singular: string,
+  plural = `${singular}s`,
+): string {
+  return count === 1 ? singular : plural;
+}

package/src/help/ui/HelpBody.tsx

@@ -0,0 +1,130 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+/** A worked example under a piece of help: the construct, and what it does. */
+export interface HelpExample {
+  /** The construct itself, shown in monospace. */
+  code: string;
+  /**
+   * What the construct is applied to, when showing it alone is half a
+   * demonstration.
+   * @default undefined
+   */
+  input?: string;
+  /**
+   * One line saying what the example demonstrates.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/** Everything a piece of help says, wherever it is shown. */
+export interface HelpContent {
+  /** First line, in bold: what the thing is, not what its label already says. */
+  title: string;
+  /** The explanation, one or two sentences. */
+  body: ReactNode;
+  /**
+   * A concrete case, because a definition without one is what makes a reader
+   * give up.
+   * @default undefined
+   */
+  example?: HelpExample;
+  /**
+   * Where the full documentation lives, offered as a "Learn more" link.
+   * @default undefined
+   */
+  link?: string;
+}
+
+/** What {@link HelpBody} draws. */
+export interface HelpBodyProps {
+  /** The help to render. */
+  content: HelpContent;
+  /**
+   * How wide the body is allowed to be, in pixels. A tooltip needs a cap; a
+   * dialog does not.
+   * @default 280
+   */
+  width?: number;
+}
+
+/**
+ * The one rendering of a piece of help.
+ *
+ * A tooltip, a glyph and a toolbar button all draw this, so a construct
+ * documented once reads identically wherever it is referenced and cannot drift
+ * between two of its mentions.
+ * @param props - See {@link HelpBodyProps}.
+ * @returns The help body.
+ */
+export function HelpBody(props: HelpBodyProps): ReactElement {
+  const { content, width = DEFAULT_WIDTH } = props;
+  const { title, body, example, link } = content;
+
+  return (
+    <div className="help-body" style={{ ...BODY_STYLE, maxWidth: width }}>
+      <div style={TITLE_STYLE}>{title}</div>
+      <div style={TEXT_STYLE}>{body}</div>
+      {example === undefined ? null : (
+        <div style={EXAMPLE_STYLE}>
+          <code style={CODE_STYLE}>{example.code}</code>
+          {example.input === undefined ? null : (
+            <div style={INPUT_STYLE}>
+              on <code style={CODE_STYLE}>{example.input}</code>
+            </div>
+          )}
+          {example.note === undefined ? null : (
+            <div style={NOTE_STYLE}>{example.note}</div>
+          )}
+        </div>
+      )}
+      {link === undefined ? null : (
+        <a
+          href={link}
+          target="_blank"
+          rel="noopener noreferrer"
+          style={LINK_STYLE}
+        >
+          Learn more
+        </a>
+      )}
+    </div>
+  );
+}
+
+/** How wide a piece of help is drawn when the caller does not say. */
+const DEFAULT_WIDTH = 280;
+
+const BODY_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+} as const satisfies CSSProperties;
+
+const TITLE_STYLE = { fontWeight: 600 } as const satisfies CSSProperties;
+
+const TEXT_STYLE = {
+  fontWeight: 400,
+  lineHeight: 1.45,
+} as const satisfies CSSProperties;
+
+const EXAMPLE_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2,
+  fontWeight: 400,
+} as const satisfies CSSProperties;
+
+const CODE_STYLE = {
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+  fontSize: 12,
+} as const satisfies CSSProperties;
+
+const INPUT_STYLE = { fontSize: 12 } as const satisfies CSSProperties;
+
+const NOTE_STYLE = {
+  fontSize: 12,
+  fontStyle: 'italic',
+} as const satisfies CSSProperties;
+
+const LINK_STYLE = { fontWeight: 400 } as const satisfies CSSProperties;

package/src/help/ui/HelpIcon.tsx

@@ -0,0 +1,53 @@
+import { Icon } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import type { HelpContent } from './HelpBody.tsx';
+import { HelpTooltip } from './HelpTooltip.tsx';
+
+/** What {@link HelpIcon} explains, and how big the glyph is. */
+export interface HelpIconProps {
+  /** The help the glyph reveals. */
+  content: HelpContent;
+  /**
+   * Size of the glyph in pixels, so it sits on the line of the label it
+   * follows.
+   * @default 13
+   */
+  size?: number;
+  /**
+   * Which side the help opens on.
+   * @default 'right'
+   */
+  placement?: 'top' | 'right' | 'bottom' | 'left';
+  /**
+   * Class the glyph carries, in addition to `help-icon`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The small question mark that sits beside a field label.
+ *
+ * It is reachable by tab, so the explanation is not reserved to whoever is
+ * holding a pointer.
+ * @param props - See {@link HelpIconProps}.
+ * @returns The glyph and its help.
+ */
+export function HelpIcon(props: HelpIconProps): ReactElement {
+  const { content, size = 13, placement = 'right', className } = props;
+
+  return (
+    <HelpTooltip content={content} placement={placement}>
+      <Icon
+        icon="help"
+        size={size}
+        tabIndex={0}
+        aria-label={content.title}
+        className={
+          className === undefined ? 'help-icon' : `help-icon ${className}`
+        }
+      />
+    </HelpTooltip>
+  );
+}

package/src/help/ui/HelpToolbarButton.tsx

@@ -0,0 +1,72 @@
+import type { IconName } from '@blueprintjs/core';
+import { Button } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import type { HelpContent } from './HelpBody.tsx';
+import { HelpTooltip } from './HelpTooltip.tsx';
+
+/** What {@link HelpToolbarButton} explains, and what pressing it does. */
+export interface HelpToolbarButtonProps {
+  /** The help the button reveals on hover. */
+  content: HelpContent;
+  /**
+   * What pressing the button does — usually opening the guide the tooltip
+   * summarises. Left out for a button that only explains itself.
+   * @default undefined — the button does nothing when pressed
+   */
+  onClick?: () => void;
+  /**
+   * Text beside the glyph. Left out for a toolbar that has run out of room.
+   * @default undefined — the button is reduced to its glyph
+   */
+  label?: string;
+  /**
+   * Glyph of the button.
+   * @default 'help'
+   */
+  icon?: IconName;
+  /**
+   * Whether the button is the small size a dense toolbar needs.
+   * @default false
+   */
+  small?: boolean;
+  /**
+   * Class the button carries.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The help entry of a toolbar: a glyph that explains itself on hover and opens
+ * the full guide when pressed.
+ *
+ * It shows the same body as the glyph beside a field and as any other mention
+ * of that help, so a construct is documented in one place.
+ * @param props - See {@link HelpToolbarButtonProps}.
+ * @returns The toolbar button and its help.
+ */
+export function HelpToolbarButton(props: HelpToolbarButtonProps): ReactElement {
+  const {
+    content,
+    onClick,
+    label,
+    icon = 'help',
+    small = false,
+    className,
+  } = props;
+
+  return (
+    <HelpTooltip content={content} placement="bottom">
+      <Button
+        variant="minimal"
+        size={small ? 'small' : 'medium'}
+        icon={icon}
+        text={label}
+        aria-label={label ?? content.title}
+        className={className}
+        onClick={onClick}
+      />
+    </HelpTooltip>
+  );
+}

package/src/help/ui/HelpTooltip.tsx

@@ -0,0 +1,72 @@
+import type { TooltipProps } from '@blueprintjs/core';
+import { Tooltip } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+
+import type { HelpContent } from './HelpBody.tsx';
+import { HelpBody } from './HelpBody.tsx';
+
+/** What {@link HelpTooltip} wraps, and what it says about it. */
+export interface HelpTooltipProps {
+  /** The help shown when the pointer rests on the target. */
+  content: HelpContent;
+  /** What the help is about. */
+  children: ReactNode;
+  /**
+   * Which side the tooltip opens on.
+   * @default 'top'
+   */
+  placement?: TooltipProps['placement'];
+  /**
+   * How wide the body is allowed to be, in pixels.
+   * @default 280
+   */
+  width?: number;
+  /**
+   * Class the tooltip popover carries, in addition to `help-tooltip`.
+   * @default undefined
+   */
+  popoverClassName?: string;
+}
+
+/**
+ * A piece of help attached to whatever it explains.
+ *
+ * The delay before it opens is long enough that sweeping the pointer across a
+ * row of controls opens nothing, and help carrying a link stays open long
+ * enough for the pointer to reach the link.
+ * @param props - See {@link HelpTooltipProps}.
+ * @returns The target, with its help.
+ */
+export function HelpTooltip(props: HelpTooltipProps): ReactElement {
+  const {
+    content,
+    children,
+    placement = 'top',
+    width,
+    popoverClassName,
+  } = props;
+  const hasLink = content.link !== undefined;
+
+  return (
+    <Tooltip
+      content={<HelpBody content={content} width={width} />}
+      placement={placement}
+      hoverOpenDelay={HOVER_OPEN_DELAY}
+      hoverCloseDelay={hasLink ? HOVER_CLOSE_DELAY : 0}
+      interactionKind={hasLink ? 'hover' : 'hover-target'}
+      targetTagName="span"
+      popoverClassName={
+        popoverClassName === undefined
+          ? 'help-tooltip'
+          : `help-tooltip ${popoverClassName}`
+      }
+    >
+      {children}
+    </Tooltip>
+  );
+}
+
+// Long enough that sweeping the pointer across a row of controls opens nothing.
+const HOVER_OPEN_DELAY = 250;
+// Help carrying a link has to outlive the pointer leaving its target.
+const HOVER_CLOSE_DELAY = 300;

package/src/help/ui/index.ts

@@ -0,0 +1,8 @@
+export type { HelpBodyProps, HelpContent, HelpExample } from './HelpBody.tsx';
+export { HelpBody } from './HelpBody.tsx';
+export type { HelpIconProps } from './HelpIcon.tsx';
+export { HelpIcon } from './HelpIcon.tsx';
+export type { HelpToolbarButtonProps } from './HelpToolbarButton.tsx';
+export { HelpToolbarButton } from './HelpToolbarButton.tsx';
+export type { HelpTooltipProps } from './HelpTooltip.tsx';
+export { HelpTooltip } from './HelpTooltip.tsx';

package/src/hooks/ui/index.ts

@@ -0,0 +1,6 @@
+export { useContainerSize } from './useContainerSize.ts';
+export { useDebouncedValue } from './useDebouncedValue.ts';
+export type { ListKeyboardNavigationOptions } from './useListKeyboardNavigation.ts';
+export { useListKeyboardNavigation } from './useListKeyboardNavigation.ts';
+export type { ElementSize } from './useResizeObserver.ts';
+export { useResizeObserver } from './useResizeObserver.ts';

package/src/hooks/ui/listNavigation.ts

@@ -0,0 +1,116 @@
+/** The default number of entries `PageUp` and `PageDown` move by. */
+export const DEFAULT_PAGE_STEP = 10;
+
+/** How a list stands when a key reaches it. */
+export interface ListNavigationOptions {
+  /** Number of entries currently displayed. */
+  length: number;
+  /** Index of the selected entry, or `-1` when nothing is selected. */
+  selectedIndex: number;
+  /**
+   * How many entries `PageUp` and `PageDown` move by. A value below one, or
+   * one that is not a number, falls back to the default.
+   * @default 10
+   */
+  pageStep?: number;
+}
+
+/** The subset of a keyboard event list navigation reads. */
+export interface ListNavigationKeyEvent {
+  /** The key that was pressed. */
+  key: string;
+  /** What the event was aimed at, used to leave typing alone. */
+  target?: EventTarget | null;
+  /** Stops the browser scrolling the page under the list. */
+  preventDefault: () => void;
+}
+
+/** What {@link handleListNavigationKey} needs on top of the list's shape. */
+export interface ListNavigationHandlerOptions extends ListNavigationOptions {
+  /** Called with the index the key moved the selection to. */
+  onSelect: (index: number) => void;
+}
+
+/**
+ * The entry a navigation key selects.
+ *
+ * `ArrowDown` and `ArrowUp` move one step, `PageDown` and `PageUp` move
+ * `pageStep`, `Home` and `End` jump to the ends, and every result is clamped
+ * into the list. With nothing selected, moving down enters at the top and
+ * moving up enters at the bottom.
+ * @param key - The `key` of the keyboard event.
+ * @param options - See {@link ListNavigationOptions}.
+ * @returns The index to select — which may be the current one — or `null` when
+ *   the key means nothing to a list.
+ */
+export function nextSelectedIndex(
+  key: string,
+  options: ListNavigationOptions,
+): number | null {
+  const { length, selectedIndex, pageStep } = options;
+  if (!Number.isFinite(length) || length <= 0) return null;
+  const step =
+    typeof pageStep === 'number' && Number.isFinite(pageStep) && pageStep >= 1
+      ? Math.floor(pageStep)
+      : DEFAULT_PAGE_STEP;
+  const current =
+    selectedIndex >= 0 && selectedIndex < length ? selectedIndex : -1;
+
+  let target: number;
+  switch (key) {
+    case 'ArrowDown':
+      target = current === -1 ? 0 : current + 1;
+      break;
+    case 'ArrowUp':
+      target = current === -1 ? length - 1 : current - 1;
+      break;
+    case 'PageDown':
+      target = Math.max(current, 0) + step;
+      break;
+    case 'PageUp':
+      target = (current === -1 ? length - 1 : current) - step;
+      break;
+    case 'Home':
+      target = 0;
+      break;
+    case 'End':
+      target = length - 1;
+      break;
+    default:
+      return null;
+  }
+
+  return Math.min(length - 1, Math.max(0, target));
+}
+
+/**
+ * Move a list's selection from a keyboard event.
+ *
+ * A key that reaches a text field, a select or an editable region is left
+ * alone, so typing a filter inside the list never moves the selection. A key
+ * the list acts on has its default suppressed even when the selection does not
+ * move, so the page never scrolls out from under the last entry.
+ * @param event - The keyboard event, synthetic or native.
+ * @param options - See {@link ListNavigationHandlerOptions}.
+ */
+export function handleListNavigationKey(
+  event: ListNavigationKeyEvent,
+  options: ListNavigationHandlerOptions,
+): void {
+  if (isTextEntryTarget(event.target)) return;
+  const next = nextSelectedIndex(event.key, options);
+  if (next === null) return;
+  event.preventDefault();
+  if (next !== options.selectedIndex) options.onSelect(next);
+}
+
+const TEXT_ENTRY_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+
+function isTextEntryTarget(target: EventTarget | null | undefined): boolean {
+  if (target === null || target === undefined) return false;
+  const element = target as { tagName?: unknown; isContentEditable?: unknown };
+  if (element.isContentEditable === true) return true;
+  return (
+    typeof element.tagName === 'string' && TEXT_ENTRY_TAGS.has(element.tagName)
+  );
+}