react-cheminfo 0.9.0 → 0.11.0

package/src/overlay/ui/OverlayLegend.tsx

@@ -0,0 +1,228 @@
+import type { CSSProperties, ReactElement } from 'react';
+import { useId } from 'react';
+
+import type { OverlayMarkShape } from '../core/overlayMarks.ts';
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+import type { OverlayPlacement } from '../core/overlayPlacement.ts';
+
+import { OverlayLegendMark } from './OverlayLegendMark.tsx';
+import {
+  OVERLAY_LEGEND_ENTRY_STYLE,
+  overlayLegendStyle,
+  overlayLegendTitleStyle,
+} from './overlayFigureStyles.ts';
+import { overlayCardStyle, overlayGroundStyle } from './overlayStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** One entry of an {@link OverlayLegend}. */
+export interface OverlayLegendEntry {
+  /** A stable id, used as the key and handed back by `onToggle`. */
+  id: string;
+  /** What the mark means, in the reader's own words. */
+  label: string;
+  /** The colour the mark carries on the figure. */
+  color: string;
+  /**
+   * Which mark it is. The shape channel is what lets one figure carry two
+   * meanings at once — filled dots for the samples, lines for the components.
+   * @default 'dot'
+   */
+  shape?: OverlayMarkShape;
+  /**
+   * How many samples it covers, written after the label.
+   * @default undefined — no count is written
+   */
+  count?: number;
+  /**
+   * Whether it is currently drawn faint on the figure, which is what a
+   * switched-off entry looks like.
+   * @default false
+   */
+  muted?: boolean;
+  /**
+   * One line saying why this entry is not drawn in full — a group with too few
+   * samples to outline, say.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/** What {@link OverlayLegend} needs. */
+export interface OverlayLegendProps {
+  /**
+   * The sentence over the entries, naming what the colour means on this
+   * figure: `Colour = species`, `Colour = component`. It has no default on
+   * purpose — a legend that does not name its encoding is how a reader carries
+   * the wrong meaning from one tab to the next.
+   */
+  title: string;
+  /** The entries, in the order they are drawn. */
+  entries: readonly OverlayLegendEntry[];
+  /**
+   * Where it sits.
+   * @default 'bottom-left'
+   */
+  placement?: OverlayPlacement;
+  /**
+   * Called with an entry's id when it is pressed, which is what makes the
+   * legend a filter. Left out, the entries are text rather than buttons.
+   * @default undefined
+   */
+  onToggle?: (id: string) => void;
+  /**
+   * The most entries written before the rest fold into `+ 7 more`.
+   * @default 8
+   */
+  maxEntries?: number;
+  /**
+   * Value of the `data-testid` attribute of the card.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The card that says what colour and shape mean on a figure.
+ * @param props - See {@link OverlayLegendProps}.
+ * @returns The legend.
+ */
+export function OverlayLegend(props: OverlayLegendProps): ReactElement {
+  const {
+    title,
+    entries,
+    placement = 'bottom-left',
+    onToggle,
+    maxEntries = 8,
+    testId,
+  } = props;
+  const { metrics, awake, busy } = useOverlaySurface();
+  const titleId = useId();
+
+  const room = Math.max(1, maxEntries);
+  const folded = entries.length > room ? entries.length - (room - 1) : 0;
+  const written = folded === 0 ? entries : entries.slice(0, room - 1);
+
+  return (
+    <div
+      style={overlayCardStyle(placement, metrics)}
+      // The key is chrome, since its entries are pressed, but it is part of
+      // the picture all the same: the export redraws it into the saved file.
+      data-figure="legend"
+      data-testid={testId}
+    >
+      <div style={overlayGroundStyle(awake ? 1 : RESTING_OPACITY, busy)} />
+      <div
+        role="group"
+        aria-labelledby={titleId}
+        style={overlayLegendStyle(metrics)}
+      >
+        <div id={titleId} style={overlayLegendTitleStyle(metrics)}>
+          {title}
+        </div>
+        {written.map((entry) => (
+          <LegendEntry key={entry.id} entry={entry} onToggle={onToggle} />
+        ))}
+        {folded === 0 ? null : (
+          <span style={foldStyle(metrics)}>{`+ ${folded} more`}</span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface LegendEntryProps {
+  entry: OverlayLegendEntry;
+  onToggle: ((id: string) => void) | undefined;
+}
+
+/**
+ * A legend with no `onToggle` is a key: making its entries buttons would put
+ * every one of them in the tab order on the way to nothing.
+ * @param props - The entry, and what pressing it does.
+ * @returns The entry.
+ */
+function LegendEntry(props: LegendEntryProps): ReactElement {
+  const { entry, onToggle } = props;
+  const muted = entry.muted ?? false;
+  const style: CSSProperties = {
+    ...OVERLAY_LEGEND_ENTRY_STYLE,
+    alignItems: entry.note === undefined ? 'center' : 'flex-start',
+  };
+  const body = (
+    <>
+      <OverlayLegendMark
+        color={entry.color}
+        shape={entry.shape}
+        muted={muted}
+      />
+      <span style={TEXT_STYLE}>
+        <span style={muted ? MUTED_LABEL_STYLE : LABEL_STYLE}>
+          {entryLabel(entry)}
+        </span>
+        {entry.note === undefined ? null : (
+          <span style={NOTE_STYLE}>{entry.note}</span>
+        )}
+      </span>
+    </>
+  );
+
+  if (onToggle === undefined) return <span style={style}>{body}</span>;
+  return (
+    <button
+      type="button"
+      aria-pressed={!muted}
+      style={{ ...style, cursor: 'pointer' }}
+      onClick={() => {
+        onToggle(entry.id);
+      }}
+    >
+      {body}
+    </button>
+  );
+}
+
+function entryLabel(entry: OverlayLegendEntry): string {
+  if (entry.count === undefined) return entry.label;
+  return `${entry.label} (${entry.count.toLocaleString()})`;
+}
+
+function foldStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    color: 'var(--text-muted)',
+    paddingLeft: metrics.gap + 12,
+  };
+}
+
+/**
+ * Only the ground fades while nothing is pointing at the figure. A legend
+ * whose words fade with it stops being readable exactly when the reader is
+ * looking at the picture rather than at the chrome.
+ */
+const RESTING_OPACITY = 0.74;
+
+const TEXT_STYLE = {
+  display: 'inline-flex',
+  flexDirection: 'column',
+  gap: 1,
+  minWidth: 0,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  color: 'var(--text)',
+} as const satisfies CSSProperties;
+
+/**
+ * A switched-off entry has to be legible as switched off in a screenshot, in a
+ * greyscale print and to a reader who does not separate two of the colours, so
+ * the state is written into the shape of the words as well as into their
+ * strength.
+ */
+const MUTED_LABEL_STYLE = {
+  color: 'var(--text-faint)',
+  textDecoration: 'line-through',
+} as const satisfies CSSProperties;
+
+const NOTE_STYLE = {
+  color: 'var(--text-faint)',
+  fontSize: '0.9em',
+} as const satisfies CSSProperties;

package/src/overlay/ui/OverlayLegendMark.tsx

@@ -0,0 +1,95 @@
+import type { ReactElement } from 'react';
+
+import type { OverlayMarkShape } from '../core/overlayMarks.ts';
+import { isFilledMark } from '../core/overlayMarks.ts';
+
+/** What {@link OverlayLegendMark} draws. */
+export interface OverlayLegendMarkProps {
+  /** The colour the mark carries on the figure. */
+  color: string;
+  /**
+   * Which mark it is.
+   * @default 'dot'
+   */
+  shape?: OverlayMarkShape;
+  /**
+   * Side of the square the mark is drawn in, in pixels.
+   * @default 12
+   */
+  size?: number;
+  /**
+   * Whether it is drawn faint, which is what a switched-off entry looks like.
+   * @default false
+   */
+  muted?: boolean;
+}
+
+/**
+ * The small picture of a mark, in front of what the mark means.
+ *
+ * The strokes are heavier than the geometry would suggest: a hairline rule
+ * beside a filled dot of the same width reads as a paler colour rather than as
+ * a different shape, and a reader comparing the two then believes the series
+ * is drawn in two colours. It carries no label of its own — the entry beside it
+ * is the label — so a screen reader is told to skip it rather than to announce
+ * an image with no name.
+ * @param props - See {@link OverlayLegendMarkProps}.
+ * @returns The mark.
+ */
+export function OverlayLegendMark(props: OverlayLegendMarkProps): ReactElement {
+  const { color, shape = 'dot', size = 12, muted = false } = props;
+  const filled = isFilledMark(shape);
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 12 12"
+      aria-hidden="true"
+      focusable="false"
+      style={{
+        display: 'block',
+        flex: 'none',
+        opacity: muted ? MUTED_OPACITY : 1,
+      }}
+    >
+      <g
+        fill={filled ? color : 'none'}
+        stroke={filled ? 'none' : color}
+        strokeLinecap="round"
+      >
+        {MARK_GEOMETRY[shape]}
+      </g>
+    </svg>
+  );
+}
+
+/**
+ * Each mark once, at module level: the geometry never depends on the colour —
+ * the group above it carries that — so one element per shape is shared by every
+ * legend on the page rather than rebuilt per entry per render.
+ */
+const MARK_GEOMETRY: Record<OverlayMarkShape, ReactElement> = {
+  dot: <circle cx="6" cy="6" r="4.2" />,
+  ring: <circle cx="6" cy="6" r="3.4" strokeWidth="2.2" />,
+  square: <rect x="2" y="2" width="8" height="8" rx="1.5" />,
+  line: <line x1="0.5" y1="6" x2="11.5" y2="6" strokeWidth="2.8" />,
+  dashed: (
+    <line
+      x1="0.5"
+      y1="6"
+      x2="11.5"
+      y2="6"
+      strokeWidth="2.8"
+      strokeDasharray="3.4 2.6"
+    />
+  ),
+  cross: <path d="M2.2 2.2 L9.8 9.8 M9.8 2.2 L2.2 9.8" strokeWidth="2.4" />,
+};
+
+/**
+ * Faint enough to read as switched off at a glance, dark enough that the
+ * colour is still identifiable — a reader turning a group back on has to
+ * recognise which one it was.
+ */
+const MUTED_OPACITY = 0.35;

package/src/overlay/ui/OverlayNumber.tsx

@@ -0,0 +1,160 @@
+import type { KeyboardEvent, ReactElement } from 'react';
+
+import type { OverlayControlProps } from './OverlayRow.tsx';
+import { OverlayRow } from './OverlayRow.tsx';
+import {
+  overlayNumberValueStyle,
+  overlayStepperButtonStyle,
+  overlayStepperStyle,
+} from './overlayStepperStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayNumber} needs. */
+export interface OverlayNumberProps extends OverlayControlProps {
+  /** The current value. */
+  value: number;
+  /** The smallest it may be. */
+  min: number;
+  /** The largest it may be. */
+  max: number;
+  /** Called with the new value, already held inside the range. */
+  onChange: (value: number) => void;
+  /**
+   * How much one press, or one arrow key, moves it.
+   * @default 1
+   */
+  step?: number;
+  /**
+   * Decimals the value is written with, so the control does not resize as the
+   * reader steps through it.
+   * @default 0
+   */
+  digits?: number;
+  /**
+   * Written after the value, e.g. `px`.
+   * @default '' — no unit is written
+   */
+  unit?: string;
+}
+
+/**
+ * A value the reader nudges up and down.
+ *
+ * It is two buttons around a number rather than a field, because over a figure
+ * the reader is not typing a value, they are hunting for the one that makes
+ * the picture read — and on a phone a text field raises a keyboard that covers
+ * the very picture the value is being chosen against. The end of the range is
+ * shown by the button going dead rather than by a value that refuses to move,
+ * so the reader can see where the limit is before pressing into it.
+ * @param props - See {@link OverlayNumberProps}.
+ * @returns The stepper.
+ */
+export function OverlayNumber(props: OverlayNumberProps): ReactElement {
+  const {
+    value,
+    min,
+    max,
+    onChange,
+    label,
+    help,
+    hideLabel = false,
+    disabled = false,
+    testId,
+    step = 1,
+    digits = 0,
+    unit = '',
+  } = props;
+  const { metrics } = useOverlaySurface();
+
+  function move(steps: number): void {
+    const next = clamp(value + steps * step, min, max);
+    if (next !== value) onChange(next);
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLElement>): void {
+    const steps = STEPS_BY_KEY.get(event.key);
+    if (steps === undefined || disabled) return;
+    event.preventDefault();
+    move(steps);
+  }
+
+  return (
+    <OverlayRow
+      label={label}
+      help={help}
+      hideLabel={hideLabel}
+      disabled={disabled}
+    >
+      <span style={overlayStepperStyle(metrics)} data-testid={testId}>
+        <button
+          type="button"
+          style={overlayStepperButtonStyle(metrics, disabled || value <= min)}
+          disabled={disabled || value <= min}
+          aria-label={`Decrease ${label}`}
+          onClick={() => move(-1)}
+          onKeyDown={onKeyDown}
+        >
+          −
+        </button>
+        <span
+          style={overlayNumberValueStyle(metrics, widestValue(props))}
+          aria-live="polite"
+        >
+          {`${value.toFixed(digits)}${unit}`}
+        </span>
+        <button
+          type="button"
+          style={overlayStepperButtonStyle(metrics, disabled || value >= max)}
+          disabled={disabled || value >= max}
+          aria-label={`Increase ${label}`}
+          onClick={() => move(1)}
+          onKeyDown={onKeyDown}
+        >
+          +
+        </button>
+      </span>
+    </OverlayRow>
+  );
+}
+
+/**
+ * How long the longest value of a stepper is, in characters.
+ *
+ * Both ends of the range are measured rather than the value in hand: reserving
+ * room for what is currently written is reserving the wrong room the moment
+ * the reader presses a button.
+ * @param props - See {@link OverlayNumberProps}.
+ * @returns The character count.
+ */
+function widestValue(props: OverlayNumberProps): number {
+  const { min, max, digits = 0, unit = '' } = props;
+  const ends = Math.max(min.toFixed(digits).length, max.toFixed(digits).length);
+  return ends + unit.length;
+}
+
+/**
+ * Where a step lands, held inside the range and rounded back onto the grid.
+ *
+ * Adding a fractional step to a float drifts — ten presses of `0.1` land on
+ * `0.9999999999999999` — and a value that arrives at the caller one part in a
+ * quadrillion off its own limit is a value the caller's own clamp rejects.
+ * @param value - Where the step landed.
+ * @param min - The smallest it may be.
+ * @param max - The largest it may be.
+ * @returns The value the caller is handed.
+ */
+function clamp(value: number, min: number, max: number): number {
+  const rounded = Math.round(value * FLOAT_GRID) / FLOAT_GRID;
+  if (rounded < min) return min;
+  if (rounded > max) return max;
+  return rounded;
+}
+
+const FLOAT_GRID = 1e10;
+
+const STEPS_BY_KEY = new Map([
+  ['ArrowUp', 1],
+  ['ArrowRight', 1],
+  ['ArrowDown', -1],
+  ['ArrowLeft', -1],
+]);

package/src/overlay/ui/OverlayPanel.tsx

@@ -0,0 +1,162 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useId, useMemo, useState } from 'react';
+
+import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import { HelpIcon } from '../../help/ui/HelpIcon.tsx';
+
+import type { OverlayPanelShape } from './overlayPanelContext.ts';
+import { OverlayPanelContext } from './overlayPanelContext.ts';
+import {
+  overlayPanelBodyStyle,
+  overlayPanelFooterStyle,
+  overlayPanelHeaderStyle,
+  overlayPanelHintStyle,
+  overlayPanelResetStyle,
+  overlayPanelSurfaceStyle,
+  overlayPanelTitleStyle,
+} from './overlayPanelStyles.ts';
+import { overlayNameColumnWidth } from './overlayRowStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayPanel} holds. */
+export interface OverlayPanelProps {
+  /**
+   * Which figure these settings belong to: `Map`, `What differs`. A viewer
+   * shows four figures behind one cog, and a panel that never names itself
+   * leaves the reader guessing which of them they are about to change.
+   */
+  title: string;
+  /** The rows and sections, each an {@link OverlayRow} or an {@link OverlayGroup}. */
+  children: ReactNode;
+  /**
+   * Called when the reader asks for the settings the figure came with. There
+   * has to be a way back from a configuration nobody understands any more.
+   * @default undefined — no way back is offered
+   */
+  onReset?: () => void;
+  /**
+   * What that way back reads.
+   * @default 'Reset'
+   */
+  resetLabel?: string;
+  /**
+   * What the whole figure is, in a sentence, behind a question mark beside the
+   * title. This is the one glyph the domain still allows, because the figure
+   * has no name of its own in the panel to hang its explanation off — every
+   * control below does, and none of them may have one.
+   * @default undefined
+   */
+  help?: HelpContent;
+  /**
+   * What the figure can be *told to do*, drawn at the foot under a hairline —
+   * `Clear selection`, `Zoom to selection`, each an {@link OverlayAction}.
+   *
+   * Commands are not settings and must never be given a row. A row says what
+   * the figure currently is; a command changes it once and leaves nothing
+   * behind, and a reader running down a column of settings takes anything in
+   * that column for one — which is how `Clear selection` gets pressed by
+   * somebody who was only reading.
+   * @default undefined — no footer is drawn
+   */
+  actions?: ReactNode;
+  /**
+   * The line at the foot of the body that teaches the convention. Nothing in
+   * the panel says that the dotted names are offering anything, so one
+   * sentence says it once. Pass `''` for a panel whose names carry no help at
+   * all, where the line would be a promise the panel does not keep.
+   * @default 'Hover a name for what it does.'
+   */
+  hint?: string;
+  /**
+   * Width of the name column, in pixels. Widen it here rather than per row,
+   * for a panel whose names are longer than eight characters.
+   * @default derived from the type size — 88 at the compact size
+   */
+  nameWidth?: number;
+  /**
+   * Value of the `data-testid` attribute of the panel.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The settings behind a figure's cog.
+ *
+ * The four panels of a viewer cannot be allowed to drift apart, so the parts
+ * that are the same in all of them — the title, the way back, the grid the
+ * rows sit in, the sentence teaching the help convention, the commands kept
+ * out of the settings — are settled once here rather than assembled per
+ * figure. What a panel is handed is its rows; everything around them it draws
+ * itself.
+ *
+ * It brings its own padding, so it belongs in a popover or a card that has
+ * none. Nested inside a padded surface its header rule stops short of both
+ * edges, which reads as a mis-drawn line rather than as a header.
+ * @param props - See {@link OverlayPanelProps}.
+ * @returns The panel.
+ */
+export function OverlayPanel(props: OverlayPanelProps): ReactElement {
+  const { title, children, onReset, resetLabel = 'Reset', help } = props;
+  const { actions, hint = DEFAULT_HINT, nameWidth, testId } = props;
+  const { metrics } = useOverlaySurface();
+  const titleId = useId();
+  const [resetHovered, setResetHovered] = useState(false);
+
+  const width = nameWidth ?? overlayNameColumnWidth(metrics);
+  const shape = useMemo<OverlayPanelShape>(
+    () => ({ nameWidth: width }),
+    [width],
+  );
+
+  return (
+    <div
+      role="group"
+      aria-labelledby={titleId}
+      data-testid={testId}
+      style={overlayPanelSurfaceStyle(metrics)}
+    >
+      <div style={overlayPanelHeaderStyle(metrics)}>
+        <span style={overlayPanelTitleStyle(metrics)}>
+          <span id={titleId}>{title}</span>
+          {help === undefined ? null : (
+            <HelpIcon content={help} size={metrics.fontSize} />
+          )}
+        </span>
+        {onReset === undefined ? null : (
+          <button
+            type="button"
+            style={overlayPanelResetStyle(metrics, resetHovered)}
+            onClick={onReset}
+            onPointerEnter={() => setResetHovered(true)}
+            onPointerLeave={() => setResetHovered(false)}
+            onFocus={() => setResetHovered(true)}
+            onBlur={() => setResetHovered(false)}
+          >
+            {resetLabel}
+          </button>
+        )}
+      </div>
+      <div style={overlayPanelBodyStyle(metrics)}>
+        <OverlayPanelContext.Provider value={shape}>
+          {children}
+        </OverlayPanelContext.Provider>
+        {hint === '' ? null : (
+          <p style={overlayPanelHintStyle(metrics)}>{hint}</p>
+        )}
+      </div>
+      {actions === undefined ? null : (
+        <div style={overlayPanelFooterStyle(metrics)}>{actions}</div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The sentence that teaches the convention.
+ *
+ * It names the gesture rather than the mark, because a reader who has noticed
+ * the dotted underlines has already asked this question and one who has not
+ * would not recognise a description of them.
+ */
+const DEFAULT_HINT = 'Hover a name for what it does.';