react-cheminfo 0.3.0 → 0.4.0

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

package/src/hooks/ui/useContainerSize.ts

@@ -0,0 +1,32 @@
+import type { RefObject } from 'react';
+import { useState } from 'react';
+
+import type { ElementSize } from './useResizeObserver.ts';
+import { useResizeObserver } from './useResizeObserver.ts';
+
+const EMPTY_SIZE: ElementSize = { width: 0, height: 0 };
+
+/**
+ * The current content-box size of an element, as state.
+ *
+ * The state form of {@link useResizeObserver}, for a chart or a canvas that
+ * has to be laid out from the measurement rather than told about it. Both
+ * numbers are zero until the element is first measured, and the state is left
+ * untouched when a resize reports the same numbers, so a component that sizes
+ * itself from the value cannot loop.
+ * @param ref - Ref holding the element to measure.
+ * @returns Its width and height in CSS pixels.
+ */
+export function useContainerSize(ref: RefObject<Element | null>): ElementSize {
+  const [size, setSize] = useState<ElementSize>(EMPTY_SIZE);
+
+  useResizeObserver(ref, (next) => {
+    setSize((current) =>
+      current.width === next.width && current.height === next.height
+        ? current
+        : next,
+    );
+  });
+
+  return size;
+}

package/src/hooks/ui/useDebouncedValue.ts

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * A debounced echo of a fast-changing value.
+ *
+ * The returned value only catches up once the source has been still for
+ * `delayMs`, so a memo, a request or a canvas redraw downstream runs when the
+ * user pauses instead of on every keystroke or slider step.
+ * @param value - The live value to follow.
+ * @param delayMs - Quiet period, in milliseconds, before the value settles. Defaults to `250`.
+ * @returns The value as it stood `delayMs` after the last change.
+ */
+export function useDebouncedValue<TValue>(
+  value: TValue,
+  delayMs = 250,
+): TValue {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const handle = setTimeout(() => {
+      setDebounced(value);
+    }, delayMs);
+    return () => {
+      clearTimeout(handle);
+    };
+  }, [value, delayMs]);
+
+  return debounced;
+}

package/src/hooks/ui/useListKeyboardNavigation.ts

@@ -0,0 +1,37 @@
+import type { KeyboardEvent } from 'react';
+import { useCallback } from 'react';
+
+import type { ListNavigationHandlerOptions } from './listNavigation.ts';
+import { handleListNavigationKey } from './listNavigation.ts';
+
+/** See {@link ListNavigationHandlerOptions}. */
+export type ListKeyboardNavigationOptions = ListNavigationHandlerOptions;
+
+/**
+ * Keyboard navigation for a list or a table whose selection lives outside it.
+ *
+ * Put the returned handler on the scrolling container — which needs a
+ * `tabIndex` so it can hold the focus — and `ArrowUp` / `ArrowDown` move one
+ * entry, `PageUp` / `PageDown` move `pageStep`, and `Home` / `End` jump to the
+ * ends. Nothing is stored in the hook: the selection stays wherever the page
+ * already keeps it, and `onSelect` fires only when the index actually changes.
+ * @param options - See {@link ListNavigationHandlerOptions}.
+ * @returns The `onKeyDown` handler for the container.
+ */
+export function useListKeyboardNavigation(
+  options: ListKeyboardNavigationOptions,
+): (event: KeyboardEvent<HTMLElement>) => void {
+  const { length, selectedIndex, onSelect, pageStep } = options;
+
+  return useCallback(
+    (event: KeyboardEvent<HTMLElement>) => {
+      handleListNavigationKey(event, {
+        length,
+        selectedIndex,
+        onSelect,
+        pageStep,
+      });
+    },
+    [length, selectedIndex, onSelect, pageStep],
+  );
+}

package/src/hooks/ui/useResizeObserver.ts

@@ -0,0 +1,50 @@
+import type { RefObject } from 'react';
+import { useEffect, useRef } from 'react';
+
+/** The content-box size of an element, in CSS pixels. */
+export interface ElementSize {
+  /** Content-box width. */
+  width: number;
+  /** Content-box height. */
+  height: number;
+}
+
+/**
+ * Call `callback` whenever the observed element's content box changes size.
+ *
+ * The callback is read through a ref, so an inline arrow function may be
+ * passed on every render without tearing the observer down and setting it up
+ * again. Nothing is observed where `ResizeObserver` is missing — a server
+ * render, or a test rendering to a string — so the hook is safe to call there.
+ * @param ref - Ref holding the element to watch.
+ * @param callback - Receives the new content-box size.
+ */
+export function useResizeObserver(
+  ref: RefObject<Element | null>,
+  callback: (size: ElementSize) => void,
+): void {
+  const callbackRef = useRef(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  useEffect(() => {
+    const element = ref.current;
+    const Observer = globalThis.ResizeObserver as
+      typeof ResizeObserver | undefined;
+    if (element === null || Observer === undefined) return;
+    const observer = new Observer((entries) => {
+      const entry = entries.at(-1);
+      if (entry === undefined) return;
+      callbackRef.current({
+        width: entry.contentRect.width,
+        height: entry.contentRect.height,
+      });
+    });
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+    };
+  }, [ref]);
+}