react-cheminfo 0.9.0 → 0.10.0

package/src/overlay/ui/overlayStepperStyles.ts

@@ -0,0 +1,112 @@
+/**
+ * What a stepper is drawn with: one sunken track holding two square buttons
+ * and the value between them.
+ *
+ * They are their own module because the three rules are read together — the
+ * track's padding, the button's side and the value's width have to add up to
+ * the control height the rest of the card is built on, and a change to one of
+ * them that is not a change to the others is a bug.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+/**
+ * The two buttons of a stepper and the value between them.
+ *
+ * They are packed tighter than the card's own gap so the three read as one
+ * control rather than as two buttons that happen to sit beside a number.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The stepper's rules.
+ */
+export function overlayStepperStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 0,
+    height: metrics.controlHeight,
+    padding: 2,
+    borderRadius: metrics.controlRadius,
+    background: 'var(--surface-sunken)',
+  };
+}
+
+/**
+ * One of a stepper's two buttons.
+ *
+ * Square and unpadded, because a stepper's job is to be pressed repeatedly and
+ * the two buttons should sit within a thumb's width of each other. Blueprint's
+ * own button carries the padding of a button that holds a word, which is what
+ * made `− 2 +` measure ninety-six pixels for a single digit.
+ *
+ * At the end of its range the button fades and stops offering the pointer a
+ * hand. A `disabled` attribute alone stops the click but says nothing before
+ * it: the reader presses `+` on a four-component model, nothing happens, and
+ * the only reading available to them is that the control is broken.
+ * @param metrics - The measurements the card is drawn from.
+ * @param spent - Whether the range has no more room in this direction.
+ * @returns The button's rules.
+ */
+export function overlayStepperButtonStyle(
+  metrics: OverlayMetrics,
+  spent: boolean,
+): CSSProperties {
+  const side = metrics.controlHeight - 4;
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: side,
+    height: side,
+    padding: 0,
+    border: 'none',
+    borderRadius: Math.max(3, metrics.controlRadius - 2),
+    background: 'transparent',
+    color: spent ? 'var(--text-faint)' : 'var(--text-muted)',
+    font: 'inherit',
+    fontSize: metrics.fontSize + 1,
+    lineHeight: 1,
+    cursor: spent ? 'default' : 'pointer',
+    opacity: spent ? 0.45 : 1,
+  };
+}
+
+/**
+ * The value a stepper is showing.
+ *
+ * The digits are tabular and the box is held at the width of the longest value
+ * the range can produce, because a value that changes width as the reader
+ * steps through it drags the buttons out from under the pointer that is
+ * pressing them — and stepping from 9 to 10 is exactly when the reader is
+ * pressing the same button repeatedly.
+ * @param metrics - The measurements the card is drawn from.
+ * @param widest - How many characters the longest value writes.
+ * @returns The value's rules.
+ */
+export function overlayNumberValueStyle(
+  metrics: OverlayMetrics,
+  widest: number,
+): CSSProperties {
+  return {
+    minWidth: Math.max(
+      metrics.fontSize,
+      Math.ceil(widest * metrics.fontSize * CHARACTER_WIDTH),
+    ),
+    padding: '0 3px',
+    color: 'var(--text)',
+    fontSize: metrics.fontSize,
+    fontVariantNumeric: 'tabular-nums',
+    textAlign: 'center',
+    userSelect: 'none',
+  };
+}
+
+/**
+ * How wide one tabular digit is, as a fraction of the type size.
+ *
+ * Six tenths of an em is what the interface faces of every platform the family
+ * runs on set their figures at; a unit written in letters is narrower than
+ * that, so the reserved width errs wide and the buttons never move.
+ */
+const CHARACTER_WIDTH = 0.6;

package/src/overlay/ui/overlayStyles.ts

@@ -0,0 +1,222 @@
+/**
+ * Every rule the floating chrome is drawn with.
+ *
+ * The domain's one design decision is here rather than spread over sixteen
+ * components: a card floating over a figure is a *quiet* surface. It is
+ * translucent so the reader can see that there is a picture underneath it, it
+ * is separated from the picture by a hairline rather than a shadow the eye
+ * reads as a dialog, and at rest only its ground fades — never its text.
+ *
+ * That last point is why the ground is a layer of its own instead of an
+ * `opacity` on the card. Fading the whole card fades the words with it, and a
+ * label at three-quarters strength over a busy scatter is unreadable exactly
+ * when the reader needs it. So the ground fades to `restingOpacity` and the
+ * content sits above it at full strength.
+ *
+ * Every colour is a family token. Nothing here writes a literal, so a card
+ * over a chart on any site of the family is the site's own grey.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+import type { OverlayPlacement } from '../core/overlayPlacement.ts';
+import { overlayCornerStyle } from '../core/overlayPlacement.ts';
+
+/** The inert layer covering a figure, which every pointer event passes through. */
+export const OVERLAY_LAYER_STYLE = {
+  position: 'absolute',
+  inset: 0,
+  pointerEvents: 'none',
+  overflow: 'hidden',
+} as const satisfies CSSProperties;
+
+/**
+ * Where one card sits over the figure.
+ *
+ * The card takes the pointer back from the layer, so a control can be clicked
+ * while a drag started anywhere else still reaches the figure underneath.
+ *
+ * A docked card is laid out in the flow but is still made `relative`, because
+ * its ground is an absolutely positioned sibling of its content and has to be
+ * held by the card rather than by whatever is positioned further up. Left
+ * `static`, the ground escapes to the nearest positioned ancestor — the figure
+ * — and paints the whole picture in opaque white, and because the ground takes
+ * no pointer events, nothing under it reports being covered. That holds for
+ * the stretched bar too, which is docked in exactly the same way.
+ * @param placement - Which corner it sits in, or whether it is docked outside.
+ * @param metrics - The measurements it is drawn from.
+ * @returns The positioning rules.
+ */
+export function overlayCardStyle(
+  placement: OverlayPlacement,
+  metrics: OverlayMetrics,
+): CSSProperties {
+  if (placement === 'stretch') return OVERLAY_STRETCHED_CARD_STYLE;
+  const corner = overlayCornerStyle(placement, metrics.inset);
+  return {
+    ...corner,
+    position: corner.position === 'absolute' ? 'absolute' : 'relative',
+    display: 'inline-flex',
+    maxWidth: `calc(100% - ${metrics.inset * 2}px)`,
+    borderRadius: 'var(--radius)',
+    pointerEvents: 'auto',
+    isolation: 'isolate',
+  };
+}
+
+/**
+ * The translucent ground behind a card's content.
+ *
+ * The blur is dropped while the figure is repainting: a backdrop filter is
+ * recomputed every time the pixels behind it change, which during a lasso drag
+ * is every frame, and the flat fill is indistinguishable at these opacities.
+ * @param opacity - How opaque the ground is, 0 to 1.
+ * @param busy - Whether the figure underneath is repainting.
+ * @returns The ground's rules.
+ */
+export function overlayGroundStyle(
+  opacity: number,
+  busy: boolean,
+): CSSProperties {
+  return {
+    position: 'absolute',
+    inset: 0,
+    borderRadius: 'var(--radius)',
+    border: '1px solid var(--border)',
+    background: 'var(--surface)',
+    boxShadow: 'var(--shadow-sm)',
+    backdropFilter: busy ? undefined : 'blur(8px) saturate(1.4)',
+    opacity,
+    transition: 'opacity 120ms ease-out',
+    pointerEvents: 'none',
+  };
+}
+
+/**
+ * The row of controls inside a card, above its ground.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The content's rules.
+ */
+export function overlayContentStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    position: 'relative',
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    gap: metrics.gap,
+    padding: `${metrics.paddingY}px ${metrics.paddingX}px`,
+    color: 'var(--text)',
+    fontSize: metrics.fontSize,
+    lineHeight: 1.2,
+  };
+}
+
+/**
+ * The controls a card's button opens, behind the strip.
+ *
+ * A column where the strip is a wrapping row, because a card folds exactly
+ * when the figure is narrow, and a row of controls in a popover over a narrow
+ * figure is a row that reaches past the edge of the screen.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The panel's rules.
+ */
+export function overlayPanelStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    ...overlayContentStyle(metrics),
+    flexWrap: 'nowrap',
+    flexDirection: 'column',
+    alignItems: 'stretch',
+    minWidth: 168,
+  };
+}
+
+/**
+ * A bar that spans the whole width of the figure.
+ *
+ * It takes the width rather than hugging its contents, since the two ends are
+ * only pushed apart once there is width between them to push into. It carries
+ * no corner radius of its own: a rounded strip flush against the top of a
+ * figure leaves two slivers of the page showing through its corners, which
+ * reads as a gap in the chrome rather than as a rounded card.
+ */
+const OVERLAY_STRETCHED_CARD_STYLE = {
+  position: 'relative',
+  display: 'flex',
+  width: '100%',
+  maxWidth: '100%',
+  pointerEvents: 'auto',
+  isolation: 'isolate',
+} as const satisfies CSSProperties;
+
+/**
+ * How opaque a card's ground is drawn while nothing is pointing at the figure.
+ *
+ * Floored whatever the caller asks for: under about six tenths the card is a
+ * ghost over a busy scatter, and a control the reader cannot find is worse
+ * than one that costs a little of the picture.
+ * @param asked - The opacity the caller asked for.
+ * @returns The opacity the ground is drawn at.
+ */
+export function overlayRestingOpacity(asked: number): number {
+  if (!Number.isFinite(asked)) return OVERLAY_RESTING_OPACITY;
+  return Math.min(1, Math.max(0.6, asked));
+}
+
+/** What a card's ground fades to when the caller does not say. */
+export const OVERLAY_RESTING_OPACITY = 0.74;
+
+/**
+ * The ground behind a bar that spans the whole width of the figure.
+ *
+ * Solid, unblurred and never faded, where a floating card is translucent: a
+ * strip across the full width is chrome the figure is mounted in rather than
+ * something laid on top of it, and a blurred translucent band over the top of
+ * an embedded figure reads as a rendering fault. The hairline is at the foot
+ * alone, so the bar is separated from the picture it introduces without being
+ * boxed off from the page that is hosting it.
+ */
+export const OVERLAY_BAR_GROUND_STYLE = {
+  position: 'absolute',
+  inset: 0,
+  borderBottom: '1px solid var(--border)',
+  background: 'var(--surface)',
+  pointerEvents: 'none',
+} as const satisfies CSSProperties;
+
+/**
+ * The row inside a stretched bar, whose two ends are pushed apart.
+ *
+ * It never wraps. A bar that wrapped would change the figure's height as the
+ * page around it resized, and an embedded figure that moves the host's layout
+ * while it is being read is worse than one whose second-tier controls have
+ * folded away into the button at its end.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The row's rules.
+ */
+export function overlayBarContentStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    ...overlayContentStyle(metrics),
+    flexWrap: 'nowrap',
+    justifyContent: 'space-between',
+    width: '100%',
+    minWidth: 0,
+  };
+}
+
+/**
+ * One end of a stretched bar.
+ *
+ * Both ends are drawn from the same rule, so the pills at the start and the
+ * controls at the end keep one rhythm across the width between them.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The end's rules.
+ */
+export function overlayBarSideStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'flex',
+    alignItems: 'center',
+    gap: metrics.gap,
+    minWidth: 0,
+  };
+}

package/src/overlay/ui/overlaySurface.ts

@@ -0,0 +1,120 @@
+/**
+ * What the floating chrome over one figure agrees on.
+ *
+ * Two cards over the same scatter that disagree about how tightly to pack
+ * their controls, or about whether the figure is repainting, read as two
+ * pieces of software sitting on one picture. So the measurements are settled
+ * once by the layer, and every card reads them back from here rather than
+ * deciding for itself.
+ */
+
+import { createContext, useContext, useSyncExternalStore } from 'react';
+
+import type {
+  OverlayMetrics,
+  OverlayPointerKind,
+} from '../core/overlayMetrics.ts';
+import { overlayMetrics } from '../core/overlayMetrics.ts';
+
+/** What every control inside an {@link OverlayLayer} reads from it. */
+export interface OverlaySurface {
+  /** The measurements every card and control is drawn from. */
+  metrics: OverlayMetrics;
+  /** Whether the cards are at full strength rather than resting. */
+  awake: boolean;
+  /**
+   * Whether the figure is repainting. While it is, a card drops its backdrop
+   * blur for a flat fill, because a blur is recomputed every time the pixels
+   * behind it change — which during a lasso drag is every frame.
+   */
+  busy: boolean;
+  /** Width of the figure, in pixels; `0` before it has been measured. */
+  width: number;
+  /** What the reader is pointing with. */
+  pointer: OverlayPointerKind;
+}
+
+/**
+ * The surface a floating control is sitting on.
+ *
+ * A control rendered with no {@link OverlayLayer} above it gets a comfortable,
+ * awake, unmeasured surface, so every component in this domain is usable on
+ * its own and renders correctly to a string.
+ * @returns The surface.
+ */
+export function useOverlaySurface(): OverlaySurface {
+  return useContext(OverlaySurfaceContext);
+}
+
+/**
+ * Whether the pointer on this page is a finger.
+ *
+ * Returns `false` where `matchMedia` is missing, which is what keeps the
+ * string-rendering tests working — the same guard `useResizeObserver` applies
+ * to a missing `ResizeObserver`.
+ * @returns Whether the pointer is coarse.
+ */
+export function useCoarsePointer(): boolean {
+  return useSyncExternalStore(
+    subscribeToPointerKind,
+    readPointerKind,
+    readFinePointer,
+  );
+}
+
+/**
+ * What a control gets when there is no layer above it.
+ *
+ * Awake rather than resting: a card with nobody watching the pointer on its
+ * behalf would otherwise sit at three-quarters strength for ever, with no way
+ * for the reader to bring it up.
+ */
+const UNWRAPPED_SURFACE: OverlaySurface = {
+  metrics: overlayMetrics('comfortable', 'fine'),
+  awake: true,
+  busy: false,
+  width: 0,
+  pointer: 'fine',
+};
+
+/**
+ * The surface an {@link OverlayLayer} hands down to the cards inside it.
+ *
+ * Published for the layer alone. A control reaches it through
+ * {@link useOverlaySurface}, which is what leaves it with real measurements
+ * when nobody wrapped it in a layer at all.
+ */
+export const OverlaySurfaceContext =
+  createContext<OverlaySurface>(UNWRAPPED_SURFACE);
+
+function subscribeToPointerKind(onChange: () => void): () => void {
+  if (typeof globalThis.matchMedia !== 'function') return doNothing;
+  const query = globalThis.matchMedia(COARSE_POINTER_QUERY);
+  query.addEventListener('change', onChange);
+  return () => {
+    query.removeEventListener('change', onChange);
+  };
+}
+
+function readPointerKind(): boolean {
+  if (typeof globalThis.matchMedia !== 'function') return false;
+  return globalThis.matchMedia(COARSE_POINTER_QUERY).matches;
+}
+
+/**
+ * What a server render is told the pointer is.
+ *
+ * Nothing can be asked about the pointer while the markup is being written,
+ * and guessing a finger would hand the largest controls to every reader whose
+ * first paint comes from the server.
+ * @returns Always `false`.
+ */
+function readFinePointer(): boolean {
+  return false;
+}
+
+function doNothing(): void {
+  // Nothing was subscribed to, so there is nothing to unsubscribe from.
+}
+
+const COARSE_POINTER_QUERY = '(pointer: coarse)';

package/src/overlay/ui/overlaySwitchStyles.ts

@@ -0,0 +1,136 @@
+/**
+ * The rules a switch is drawn with.
+ *
+ * A panel's booleans are the settings whose state has to be readable without
+ * touching them: `One scale for all` drawn as a grey chip answers the reader's
+ * only question about it — is it on? — with nothing at all. So on and off are
+ * said twice over, by the colour of the track and by which end the knob is at,
+ * and the target the reader aims at is kept larger than the switch they see.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+/** Every measurement a switch is drawn from. */
+export interface OverlaySwitchTrack {
+  /** Width of the track, in pixels. */
+  width: number;
+  /** Height of the track, in pixels. */
+  height: number;
+  /** Side of the knob, in pixels. */
+  knob: number;
+  /** Room between the knob and the edge of the track, in pixels. */
+  inset: number;
+  /** How far the knob slides when it is turned on, in pixels. */
+  travel: number;
+}
+
+/**
+ * How big a switch is drawn.
+ *
+ * Three quarters of a control's height, held even so that the knob is centred
+ * on a whole pixel, and half again as wide as it is tall — thirty by eighteen
+ * at the compact size. It follows the control height rather than a constant,
+ * which is what makes it grow with everything else on a phone: a switch a
+ * finger cannot hit is a setting that cannot be changed.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The switch's measurements.
+ */
+export function overlaySwitchTrack(
+  metrics: OverlayMetrics,
+): OverlaySwitchTrack {
+  const height = Math.round((metrics.controlHeight * 0.75) / 2) * 2;
+  const width = Math.round((height * 5) / 3);
+  const inset = 2;
+  const knob = height - inset * 2;
+  return { width, height, knob, inset, travel: width - knob - inset * 2 };
+}
+
+/**
+ * The button a switch is, which is bigger than the switch drawn on it.
+ *
+ * The track is eighteen pixels tall and the target is the card's full control
+ * height, so the thing the reader aims at is forty pixels on a phone even
+ * though the thing they see never grows past thirty.
+ * @param metrics - The measurements the card is drawn from.
+ * @param track - The switch's measurements.
+ * @param disabled - Whether it cannot be pressed.
+ * @returns The button's rules.
+ */
+export function overlaySwitchStyle(
+  metrics: OverlayMetrics,
+  track: OverlaySwitchTrack,
+  disabled: boolean,
+): CSSProperties {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    minWidth: track.width,
+    height: metrics.controlHeight,
+    padding: 0,
+    border: 'none',
+    background: 'transparent',
+    cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.6 : 1,
+  };
+}
+
+/**
+ * The track a switch's knob sits in.
+ *
+ * On and off are told apart by the ground rather than by the position of the
+ * knob alone, because a fourteen-pixel dot twelve pixels to the left of where
+ * it was is not a difference anybody reads across a panel of six settings.
+ * @param track - The switch's measurements.
+ * @param checked - Whether it is on.
+ * @returns The track's rules.
+ */
+export function overlaySwitchTrackStyle(
+  track: OverlaySwitchTrack,
+  checked: boolean,
+): CSSProperties {
+  return {
+    position: 'relative',
+    display: 'inline-block',
+    width: track.width,
+    height: track.height,
+    borderRadius: 999,
+    background: checked ? 'var(--accent)' : 'var(--border-strong)',
+    transition: `background ${OVERLAY_SWITCH_TRANSITION}ms ease`,
+  };
+}
+
+/**
+ * The knob a switch slides.
+ *
+ * It slides rather than jumping, so the reader who pressed it sees which of
+ * the two ends it went to instead of only finding the panel changed.
+ * @param track - The switch's measurements.
+ * @param checked - Whether it is on.
+ * @returns The knob's rules.
+ */
+export function overlaySwitchKnobStyle(
+  track: OverlaySwitchTrack,
+  checked: boolean,
+): CSSProperties {
+  return {
+    position: 'absolute',
+    top: track.inset,
+    left: checked ? track.inset + track.travel : track.inset,
+    width: track.knob,
+    height: track.knob,
+    borderRadius: '50%',
+    background: 'var(--surface)',
+    boxShadow: 'var(--shadow-sm)',
+    transition: `left ${OVERLAY_SWITCH_TRANSITION}ms ease`,
+  };
+}
+
+/**
+ * How long the knob takes to cross.
+ *
+ * Long enough to be seen as a movement and short enough that a reader turning
+ * three settings on in a row never waits for the animation.
+ */
+const OVERLAY_SWITCH_TRANSITION = 150;