react-cheminfo 0.8.0 → 0.10.0

package/src/overlay/ui/overlayPanelStyles.ts

@@ -0,0 +1,235 @@
+/**
+ * The rules a settings panel is drawn with.
+ *
+ * A panel is the one surface in this domain the reader stops and reads rather
+ * than glances at, and everything here follows from that. It says at the top
+ * which figure it belongs to, because a panel that opens behind a cog and
+ * never names itself leaves the reader guessing which of four pictures they
+ * are about to change. It offers a way back, because a configuration nobody
+ * understands any more is worse than the default it replaced. And it keeps its
+ * commands at the foot rather than among its rows, since a button that clears
+ * a selection is not a setting and reading as one costs the reader a mistake.
+ *
+ * The panel 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 and reads as a mis-drawn line rather than as a header.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+import { OVERLAY_HELP_NAME_STYLE } from './overlayRowStyles.ts';
+
+/**
+ * The panel itself: a header, a body, and whatever the figure can be told to
+ * do at the foot.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The panel's rules.
+ */
+export function overlayPanelSurfaceStyle(
+  metrics: OverlayMetrics,
+): CSSProperties {
+  return {
+    display: 'flex',
+    flexDirection: 'column',
+    minWidth: OVERLAY_PANEL_MIN_WIDTH,
+    color: 'var(--text)',
+    fontSize: metrics.fontSize,
+    lineHeight: 1.2,
+  };
+}
+
+/**
+ * The band across the top holding the title and the way back.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The header's rules.
+ */
+export function overlayPanelHeaderStyle(
+  metrics: OverlayMetrics,
+): CSSProperties {
+  return {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: metrics.gap,
+    padding: `${metrics.gap + 5}px ${metrics.gap + 8}px ${metrics.gap + 4}px`,
+    borderBottom: '1px solid var(--border)',
+  };
+}
+
+/**
+ * What the panel is called.
+ *
+ * Full strength and half a step heavier than the rows under it, which is the
+ * least that separates a title from one more caption.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The title's rules.
+ */
+export function overlayPanelTitleStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 4,
+    minWidth: 0,
+    color: 'var(--text)',
+    fontSize: metrics.fontSize,
+    fontWeight: 600,
+    whiteSpace: 'nowrap',
+  };
+}
+
+/**
+ * The way back to the settings the figure came with.
+ *
+ * Plain text rather than a button: it is the one thing in the header that is
+ * not the title, and drawing an outline around it would make it compete with
+ * the settings it undoes. It is faint until pointed at, then the accent, so a
+ * reader who is not looking for it never sees it and one who is finds it where
+ * every other panel keeps it.
+ * @param metrics - The measurements the card is drawn from.
+ * @param hovered - Whether the pointer is over it or the keyboard is on it.
+ * @returns The button's rules.
+ */
+export function overlayPanelResetStyle(
+  metrics: OverlayMetrics,
+  hovered: boolean,
+): CSSProperties {
+  return {
+    flex: 'none',
+    padding: 0,
+    border: 'none',
+    background: 'transparent',
+    color: hovered ? 'var(--accent)' : 'var(--text-faint)',
+    font: 'inherit',
+    fontSize: Math.max(10, metrics.labelSize + 1),
+    lineHeight: 1,
+    textDecoration: hovered ? 'underline' : 'none',
+    cursor: 'pointer',
+  };
+}
+
+/**
+ * The rows themselves, and the sections they are gathered into.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The body's rules.
+ */
+export function overlayPanelBodyStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: metrics.gap + 3,
+    padding: `${metrics.gap + 4}px ${metrics.gap + 8}px ${metrics.gap + 7}px`,
+  };
+}
+
+/**
+ * The one line at the foot that teaches the convention.
+ *
+ * Every name in the panel carries its own explanation and nothing says so; one
+ * sentence, once, is what turns a column of dotted underlines from a rendering
+ * oddity into an offer.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The line's rules.
+ */
+export function overlayPanelHintStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    margin: 0,
+    paddingTop: metrics.paddingY,
+    color: 'var(--text-faint)',
+    fontSize: Math.max(10, metrics.labelSize),
+    lineHeight: 1.45,
+  };
+}
+
+/**
+ * What the figure can be told to do, under a hairline.
+ *
+ * Below the rows and separated from them, because a command among the settings
+ * is a command the reader takes for a setting — and `Clear selection` read as
+ * a setting is a click nobody meant to make.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The footer's rules.
+ */
+export function overlayPanelFooterStyle(
+  metrics: OverlayMetrics,
+): CSSProperties {
+  return {
+    display: 'flex',
+    flexWrap: 'wrap',
+    alignItems: 'center',
+    gap: metrics.gap,
+    padding: `${metrics.gap + 4}px ${metrics.gap + 8}px ${metrics.gap + 5}px`,
+    borderTop: '1px solid var(--border)',
+  };
+}
+
+/**
+ * One section of a panel: its heading and the rows under it.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The section's rules.
+ */
+export function overlaySectionStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: metrics.gap + 3,
+  };
+}
+
+/** How a section heading stands. */
+export interface OverlaySectionLook {
+  /**
+   * Whether a hairline is drawn above it. The first heading of a panel takes
+   * none: a rule immediately under the header's own rule reads as a doubled
+   * line rather than as a division.
+   * @default true
+   */
+  divider?: boolean;
+  /**
+   * Whether the heading carries the section's explanation.
+   * @default false
+   */
+  help?: boolean;
+}
+
+/**
+ * What a section of a panel is called.
+ *
+ * Small capitals in the faintest ink the family has, over a hairline: the
+ * heading has to give the eye somewhere to rest without being read as one more
+ * setting, and anything that looks like the names under it is taken for one.
+ * @param metrics - The measurements the card is drawn from.
+ * @param look - See {@link OverlaySectionLook}.
+ * @returns The heading's rules.
+ */
+export function overlaySectionHeadingStyle(
+  metrics: OverlayMetrics,
+  look: OverlaySectionLook,
+): CSSProperties {
+  const { divider = true, help = false } = look;
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 4,
+    marginTop: divider ? metrics.paddingY : 0,
+    paddingTop: divider ? metrics.gap + 5 : 0,
+    borderTop: divider ? '1px solid var(--border)' : undefined,
+    color: 'var(--text-faint)',
+    fontSize: Math.max(10, metrics.labelSize - 1),
+    fontWeight: 700,
+    letterSpacing: '0.07em',
+    textTransform: 'uppercase',
+    whiteSpace: 'nowrap',
+    ...(help ? OVERLAY_HELP_NAME_STYLE : undefined),
+  };
+}
+
+/**
+ * How narrow a panel is allowed to get.
+ *
+ * The name column and a segmented pair beside it, which is the widest row a
+ * panel routinely holds; below this the segments wrap and the grid stops being
+ * a grid.
+ */
+const OVERLAY_PANEL_MIN_WIDTH = 208;

package/src/overlay/ui/overlayPillKeys.ts

@@ -0,0 +1,45 @@
+/**
+ * How a keyboard moves along a row of pills.
+ *
+ * A pill group is a list laid out sideways, so the arrows that mean something
+ * to the reader are the horizontal ones — and the shared list navigation is
+ * written for a column. Rather than a second key handler that would drift from
+ * it, the two horizontal keys are read as the vertical ones and everything
+ * else is handed straight over: `Home` and `End` reach the two ends, the
+ * selection is clamped at both, and a key the list has no use for is left to
+ * the page.
+ */
+
+import type {
+  ListNavigationHandlerOptions,
+  ListNavigationKeyEvent,
+} from '../../hooks/ui/listNavigation.ts';
+import { handleListNavigationKey } from '../../hooks/ui/listNavigation.ts';
+
+/**
+ * Move a pill group's selection from a keyboard event.
+ * @param event - The keyboard event, synthetic or native.
+ * @param options - See {@link ListNavigationHandlerOptions}.
+ */
+export function handleOverlayPillKey(
+  event: ListNavigationKeyEvent,
+  options: ListNavigationHandlerOptions,
+): void {
+  handleListNavigationKey(
+    {
+      key: SIDEWAYS_KEYS[event.key] ?? event.key,
+      target: event.target,
+      // Written out rather than spread from the event: `preventDefault` lives
+      // on the event's prototype, and a copy made by spreading arrives without
+      // it — at which point the page scrolls under every arrow key.
+      preventDefault: () => event.preventDefault(),
+    },
+    options,
+  );
+}
+
+/** The keys a sideways list is walked with, in the terms a column is. */
+const SIDEWAYS_KEYS: Readonly<Record<string, string>> = {
+  ArrowLeft: 'ArrowUp',
+  ArrowRight: 'ArrowDown',
+};

package/src/overlay/ui/overlayPillStyles.ts

@@ -0,0 +1,190 @@
+/**
+ * The rules the package's one segmented control is drawn with.
+ *
+ * A sunken track with the choice in force lifted out of it: the same device
+ * whether it is moving between a figure's views or picking one setting inside
+ * a card, and it is written here rather than in either component so the two
+ * cannot drift into looking like two different controls.
+ *
+ * Nothing here is filled with the site's accent. The strongest colour on the
+ * page belongs to the data, and a saturated block of it in the chrome above a
+ * scatter pulls the eye off the picture the reader came for — so the choice in
+ * force is told apart by being *raised* rather than by being coloured.
+ *
+ * The raising is said three ways at once — a lighter ground, darker ink, a
+ * heavier weight, and only then a shadow — because a reader who has asked the
+ * operating system for high contrast is shown no shadow at all, and a control
+ * whose one signal was the shadow then says nothing about which choice is in
+ * force.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+/**
+ * How big a segmented group is drawn.
+ *
+ * `strip` is the figure's own tab bar, at the full height of a control.
+ * `setting` is one question inside a card, a little smaller so it reads as
+ * something the figure is set with rather than as a second tab bar.
+ */
+export type OverlaySegmentedSize = 'strip' | 'setting';
+
+/** How one segment stands among the others. */
+export interface OverlayPillLook {
+  /** Whether it is the choice in force. */
+  selected: boolean;
+  /**
+   * Whether it cannot be picked.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Which of the two sizes the group is drawn at.
+   * @default 'strip'
+   */
+  size?: OverlaySegmentedSize;
+}
+
+/**
+ * The sunken track the segments sit in.
+ *
+ * It carries no outline. A hairline around a group that is already a shade
+ * darker than the card is a fourth container edge in a bar that has room for
+ * one, and the sinking alone is what tells the reader the segments belong
+ * together.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param size - Which of the two sizes it is drawn at.
+ * @returns The track's rules.
+ */
+export function overlayPillGroupStyle(
+  metrics: OverlayMetrics,
+  size: OverlaySegmentedSize = 'strip',
+): CSSProperties {
+  return {
+    boxSizing: 'border-box',
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: OVERLAY_TRACK_GAP,
+    height: trackHeight(metrics, size),
+    padding: OVERLAY_TRACK_PADDING,
+    borderRadius: trackRadius(metrics),
+    background: 'var(--surface-sunken)',
+  };
+}
+
+/**
+ * One segment.
+ *
+ * Its height is the track's less the band of track left showing above and
+ * below it, so the choice in force reads as a tile lying *in* the track rather
+ * than as a block that has covered it over.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayPillLook}.
+ * @returns The segment's rules.
+ */
+export function overlayPillStyle(
+  metrics: OverlayMetrics,
+  look: OverlayPillLook,
+): CSSProperties {
+  const { selected, disabled = false, size = 'strip' } = look;
+  return {
+    boxSizing: 'border-box',
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 4,
+    height: trackHeight(metrics, size) - OVERLAY_TRACK_PADDING * 2,
+    padding: `0 ${segmentPaddingX(metrics, size)}px`,
+    border: 'none',
+    borderRadius: trackRadius(metrics) - OVERLAY_TRACK_PADDING,
+    background: selected ? 'var(--surface)' : 'transparent',
+    color: selected ? 'var(--text)' : 'var(--text-muted)',
+    boxShadow: selected ? 'var(--shadow-sm)' : undefined,
+    font: 'inherit',
+    fontSize: metrics.fontSize,
+    fontWeight: selected ? 600 : 500,
+    lineHeight: 1,
+    whiteSpace: 'nowrap',
+    cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.6 : 1,
+  };
+}
+
+/**
+ * The count after a segment's label.
+ *
+ * The digits are tabular, so a row of counts does not shuffle the labels
+ * sideways as the numbers behind them change.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param selected - Whether it is on the choice in force.
+ * @returns The count's rules.
+ */
+export function overlayPillCountStyle(
+  metrics: OverlayMetrics,
+  selected: boolean,
+): CSSProperties {
+  return {
+    fontSize: Math.max(9, metrics.labelSize - 1),
+    fontVariantNumeric: 'tabular-nums',
+    fontWeight: 500,
+    opacity: selected ? 0.85 : 0.75,
+  };
+}
+
+/**
+ * The band of track showing around a segment, on every side.
+ *
+ * Two pixels: enough that the lifted tile is read as sitting inside something,
+ * and little enough that the group still stands as tall as the controls beside
+ * it.
+ */
+const OVERLAY_TRACK_PADDING = 2;
+
+/** What is left between two segments, which is the track showing through. */
+const OVERLAY_TRACK_GAP = 2;
+
+/**
+ * How tall the track stands.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param size - Which of the two sizes it is drawn at.
+ * @returns The height in pixels.
+ */
+function trackHeight(
+  metrics: OverlayMetrics,
+  size: OverlaySegmentedSize,
+): number {
+  if (size === 'strip') return metrics.controlHeight;
+  return Math.max(20, metrics.controlHeight - 4);
+}
+
+/**
+ * The track's corner.
+ *
+ * Two pixels rounder than a control of the same height, because the segment
+ * inside it takes that pair back and a tile with a square corner in a rounded
+ * track reads as a misfit rather than as a lift.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The radius in pixels.
+ */
+function trackRadius(metrics: OverlayMetrics): number {
+  return metrics.controlRadius + 2;
+}
+
+/**
+ * The room each side of a segment's label.
+ *
+ * The type does not shrink with the smaller size — a control that is quieter
+ * should take less room, not become harder to read — so only the room around
+ * the words goes.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param size - Which of the two sizes it is drawn at.
+ * @returns The padding in pixels.
+ */
+function segmentPaddingX(
+  metrics: OverlayMetrics,
+  size: OverlaySegmentedSize,
+): number {
+  return size === 'strip' ? metrics.paddingX + 2 : metrics.paddingX;
+}

package/src/overlay/ui/overlayRowStyles.ts

@@ -0,0 +1,166 @@
+/**
+ * The rules one caption-and-control pair is drawn with.
+ *
+ * A row is the unit both a bar and a settings panel are built from, and the
+ * two want different geometry out of it. On a bar the caption sits against its
+ * control and the pair hugs its own width, because the bar is a line of
+ * separate things. In a panel every control has to start at the same x, or the
+ * reader has no column to run their eye down and the panel has to be read
+ * rather than scanned. Both shapes are written here so that a row cannot end
+ * up half one and half the other.
+ *
+ * The name is also where a row's help lives. A panel that hangs a question
+ * mark off every control stacks a column of glyphs down its left edge, and the
+ * eye reads that column before it reads any of the words; a dotted underline
+ * on the name says the same thing with no ink of its own, and leaves the words
+ * the widest thing in the panel.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+/**
+ * One caption-and-control pair on a bar.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The row's rules.
+ */
+export function overlayRowStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: Math.max(4, metrics.gap - 2),
+    minHeight: metrics.controlHeight,
+  };
+}
+
+/**
+ * One caption-and-control pair in a settings panel.
+ *
+ * Two columns of fixed width rather than a flexible line: the whole complaint
+ * a panel of ragged rows draws is that every control starts at a different x,
+ * and a name column that is only as wide as the words in it is a column that
+ * moves from panel to panel.
+ * @param metrics - The measurements the card is drawn from.
+ * @param nameWidth - Width of the name column, in pixels.
+ * @returns The row's rules.
+ */
+export function overlayGridRowStyle(
+  metrics: OverlayMetrics,
+  nameWidth: number,
+): CSSProperties {
+  return {
+    display: 'grid',
+    gridTemplateColumns: `${nameWidth}px minmax(0, 1fr)`,
+    alignItems: 'center',
+    columnGap: Math.max(10, metrics.gap + 2),
+    minHeight: metrics.controlHeight,
+    width: '100%',
+  };
+}
+
+/**
+ * How wide the name column is.
+ *
+ * Eight characters of the caption's own type plus the room a descender needs:
+ * enough for `Bar order` and `Averages` without wrapping, and derived from the
+ * type size rather than fixed, so a panel a reader has asked for at a larger
+ * size widens its column with its words instead of breaking them.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The width, in pixels.
+ */
+export function overlayNameColumnWidth(metrics: OverlayMetrics): number {
+  return metrics.labelSize * 8 + 8;
+}
+
+/** The control's own cell of a panel row. */
+export const OVERLAY_GRID_CELL_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  minWidth: 0,
+} as const satisfies CSSProperties;
+
+/** How a row's name stands. */
+export interface OverlayNameLook {
+  /**
+   * Whether the name carries the control's explanation.
+   * @default false
+   */
+  help?: boolean;
+  /**
+   * Whether the control it names cannot be reached.
+   * @default false
+   */
+  disabled?: boolean;
+}
+
+/**
+ * The name of a control.
+ *
+ * It never wraps: a name breaking over two lines makes the row taller than the
+ * control it names, which reads as a fault in the layout rather than as a long
+ * word. When it carries help it is underlined with dots and takes the help
+ * cursor, which is the one convention that lets every question mark leave the
+ * panel — and it fades with its control, because a name at full strength over
+ * a greyed control reads as half broken rather than as unavailable.
+ * @param metrics - The measurements the card is drawn from.
+ * @param look - See {@link OverlayNameLook}.
+ * @returns The name's rules.
+ */
+export function overlayNameStyle(
+  metrics: OverlayMetrics,
+  look: OverlayNameLook,
+): CSSProperties {
+  const { help = false, disabled = false } = look;
+  return {
+    color: 'var(--text-muted)',
+    fontSize: metrics.labelSize,
+    fontWeight: 500,
+    whiteSpace: 'nowrap',
+    userSelect: 'none',
+    ...(help ? OVERLAY_HELP_NAME_STYLE : undefined),
+    ...(disabled ? OVERLAY_FADED_NAME_STYLE : undefined),
+  };
+}
+
+/**
+ * What any name gains when it is the thing carrying the explanation.
+ *
+ * Written apart from {@link overlayNameStyle} because a section heading is a
+ * name too, and the reader has to be taught the convention once rather than
+ * per kind of label.
+ */
+export const OVERLAY_HELP_NAME_STYLE = {
+  textDecoration: 'underline dotted var(--border-strong)',
+  textUnderlineOffset: 3,
+  cursor: 'help',
+} as const satisfies CSSProperties;
+
+/**
+ * What a name gains when its control cannot be reached.
+ *
+ * A control that does not apply is greyed rather than removed, because one
+ * that vanishes teaches the reader nothing about why it went.
+ */
+export const OVERLAY_FADED_NAME_STYLE = {
+  opacity: 0.6,
+} as const satisfies CSSProperties;
+
+/**
+ * One caption-and-control pair whose caption sits above the control.
+ *
+ * Reached once the captions are long enough that writing them in front of
+ * their controls would push the card past a third of the figure — at which
+ * point the chrome is hiding more of the picture than the captions are worth.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The stacked row's rules.
+ */
+export function overlayStackedRowStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'inline-flex',
+    flexDirection: 'column',
+    alignItems: 'flex-start',
+    gap: 2,
+    minHeight: metrics.controlHeight,
+  };
+}