react-cheminfo 0.9.0 → 0.10.0

package/src/overlay/ui/OverlayPills.tsx

@@ -0,0 +1,157 @@
+import type { ReactElement } from 'react';
+import { useId, useRef } from 'react';
+
+import type { OverlayOption } from './OverlayRow.tsx';
+import { handleOverlayPillKey } from './overlayPillKeys.ts';
+import type { OverlaySegmentedSize } from './overlayPillStyles.ts';
+import {
+  overlayPillCountStyle,
+  overlayPillGroupStyle,
+  overlayPillStyle,
+} from './overlayPillStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** One choice offered by an {@link OverlayPills}. */
+export interface OverlayPillOption<
+  TValue extends string = string,
+> extends OverlayOption<TValue> {
+  /**
+   * How many things this choice covers, written small after its label — the
+   * number of samples in a group, of components in a view.
+   * @default undefined — no count is written
+   */
+  count?: number;
+}
+
+/** What {@link OverlayPills} needs. */
+export interface OverlayPillsProps<TValue extends string = string> {
+  /** The current choice. */
+  value: TValue;
+  /** What may be chosen, in the order offered. */
+  options: ReadonlyArray<OverlayPillOption<TValue>>;
+  /** Called with the new choice. */
+  onChange: (value: TValue) => void;
+  /** What the group is called, for a reader arriving by keyboard. */
+  label: string;
+  /**
+   * What the group is: a strip moving between the views of one figure, or a
+   * set of choices for one setting. The look is the same either way — it is
+   * the announcement and the shape of the keyboard that differ.
+   * @default 'tablist'
+   */
+  role?: 'tablist' | 'radiogroup';
+  /**
+   * How big it is drawn: the figure's own tab bar, or one question inside a
+   * card, which is a little smaller.
+   * @default 'strip'
+   */
+  size?: OverlaySegmentedSize;
+  /**
+   * The `id` of the panel a tab strip drives, so a screen reader can walk from
+   * a tab to what it shows. One panel is normally shared, since only the tab
+   * in force is ever rendered.
+   * @default undefined
+   */
+  panelId?: string;
+  /**
+   * Stem of the `id` every tab carries, for a panel that names the tab it
+   * belongs to. Left out, one is generated.
+   * @default undefined — a generated id
+   */
+  baseId?: string;
+  /**
+   * Whether the whole group is greyed and unreachable.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Value of the `data-testid` attribute of the group.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * A row of choices in a sunken track, the one in force lifted out of it.
+ *
+ * It is the package's one segmented control, used both as a figure's tab strip
+ * and as a setting inside a card, because a reader who has learned to press
+ * one of them has learned to press the other. Only one segment is in the tab
+ * order — the one in force — and the arrows move between them from there, so
+ * a strip of six views costs a reader walking the page one stop rather than
+ * six.
+ * @param props - See {@link OverlayPillsProps}.
+ * @returns The group.
+ */
+export function OverlayPills<TValue extends string = string>(
+  props: OverlayPillsProps<TValue>,
+): ReactElement {
+  const { value, options, onChange, label, role = 'tablist' } = props;
+  const { panelId, baseId, size = 'strip', disabled = false, testId } = props;
+  const { metrics } = useOverlaySurface();
+  const generatedId = useId();
+  const pills = useRef<Array<HTMLButtonElement | null>>([]);
+
+  const tabs = role === 'tablist';
+  const stem = baseId ?? generatedId;
+  let selectedIndex = -1;
+  for (let index = 0; index < options.length; index++) {
+    if (options[index]?.value === value) selectedIndex = index;
+  }
+
+  return (
+    <div
+      role={role}
+      aria-label={label}
+      data-testid={testId}
+      style={overlayPillGroupStyle(metrics, size)}
+      onKeyDown={(event) => {
+        handleOverlayPillKey(event, {
+          length: options.length,
+          selectedIndex,
+          onSelect: (index) => {
+            const option = options[index];
+            if (option === undefined || option.disabled === true) return;
+            pills.current[index]?.focus();
+            onChange(option.value);
+          },
+        });
+      }}
+    >
+      {options.map((option, index) => {
+        const selected = option.value === value;
+        const unreachable = disabled || option.disabled === true;
+        return (
+          <button
+            key={option.value}
+            ref={(element) => {
+              pills.current[index] = element;
+            }}
+            type="button"
+            role={tabs ? 'tab' : 'radio'}
+            id={tabs ? `${stem}-${option.value}` : undefined}
+            aria-selected={tabs ? selected : undefined}
+            aria-checked={tabs ? undefined : selected}
+            aria-controls={tabs ? panelId : undefined}
+            title={option.title}
+            disabled={unreachable}
+            tabIndex={index === Math.max(selectedIndex, 0) ? 0 : -1}
+            style={overlayPillStyle(metrics, {
+              selected,
+              disabled: unreachable,
+              size,
+            })}
+            onClick={() => onChange(option.value)}
+          >
+            {option.label}
+            {option.count === undefined ? null : (
+              <span style={overlayPillCountStyle(metrics, selected)}>
+                {option.count}
+              </span>
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/overlay/ui/OverlayReadout.tsx

@@ -0,0 +1,247 @@
+import type { CSSProperties, ReactElement } from 'react';
+import { useRef } from 'react';
+import { Button } from 'react-science/ui';
+
+import { useContainerSize } from '../../hooks/ui/useContainerSize.ts';
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+import { placeOverlayCard } from '../core/placeOverlayCard.ts';
+
+import { overlayReadoutStyle } from './overlayFigureStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** One line of an {@link OverlayReadout}. */
+export interface OverlayReadoutRow {
+  /** What the value is. */
+  label: string;
+  /** The value, already written out — the readout never formats a number itself. */
+  value: string;
+  /**
+   * A colour chip before the label, for a row belonging to one series.
+   * @default undefined
+   */
+  color?: string;
+}
+
+/** What {@link OverlayReadout} shows, and where. */
+export interface OverlayReadoutProps {
+  /** Where the pointer is, in pixels from the figure's left. */
+  x: number;
+  /** Where the pointer is, in pixels from the figure's top. */
+  y: number;
+  /** Width of the figure, so the card can be flipped rather than clipped. */
+  boxWidth: number;
+  /** Height of the figure. */
+  boxHeight: number;
+  /** The first line, in bold — normally what the reader pointed at. */
+  title: string;
+  /** Everything the caller knows about it, in the caller's own order. */
+  rows: readonly OverlayReadoutRow[];
+  /**
+   * The most rows shown before a `+ 7 more — click to keep this open` footer.
+   * A card taller than the figure is a fault, not a feature.
+   * @default 12
+   */
+  maxRows?: number;
+  /**
+   * Whether the card stays until it is dismissed, in which case it scrolls its
+   * own rows and lets the reader select their text.
+   * @default false
+   */
+  pinned?: boolean;
+  /**
+   * Called when the reader dismisses a pinned card.
+   * @default undefined
+   */
+  onUnpin?: () => void;
+  /**
+   * Value of the `data-testid` attribute of the card.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The card that follows the pointer and says everything known about the mark
+ * under it.
+ *
+ * It follows the pointer rather than anchoring to the mark, because a
+ * nearest-within-radius hit test changes which mark it names while the pointer
+ * keeps moving, and an anchored card would then teleport. Pinned, it stops
+ * following and becomes readable and selectable.
+ * @param props - See {@link OverlayReadoutProps}.
+ * @returns The card.
+ */
+export function OverlayReadout(props: OverlayReadoutProps): ReactElement {
+  const {
+    x,
+    y,
+    boxWidth,
+    boxHeight,
+    title,
+    rows,
+    maxRows = 12,
+    pinned = false,
+    onUnpin,
+    testId,
+  } = props;
+  const { metrics } = useOverlaySurface();
+  const card = useRef<HTMLDivElement>(null);
+  const measured = useContainerSize(card);
+
+  const room = Math.max(1, maxRows);
+  const hidden = pinned ? 0 : Math.max(0, rows.length - room);
+  const written = hidden === 0 ? rows : rows.slice(0, room);
+  const lines = written.length + (hidden === 0 ? 1 : 2);
+  const place = placeOverlayCard({
+    pointerX: x,
+    pointerY: y,
+    cardWidth: measured.width > 0 ? measured.width : ESTIMATED_WIDTH,
+    cardHeight: measured.height > 0 ? measured.height : estimatedHeight(lines),
+    boxWidth,
+    boxHeight,
+  });
+
+  return (
+    <div
+      ref={card}
+      data-testid={testId}
+      role={pinned ? 'group' : 'tooltip'}
+      aria-label={pinned ? title : undefined}
+      style={{
+        ...overlayReadoutStyle(metrics),
+        left: place.left,
+        top: place.top,
+        ...(pinned ? pinnedStyle(boxHeight, metrics) : null),
+      }}
+    >
+      <div style={TITLE_STYLE}>
+        <span>{title}</span>
+        {pinned && onUnpin !== undefined ? (
+          <Button
+            variant="minimal"
+            size="small"
+            icon="cross"
+            aria-label="Dismiss"
+            onClick={onUnpin}
+          />
+        ) : null}
+      </div>
+      {readoutLines(written)}
+      {hidden === 0 ? null : (
+        <div style={FOOTER_STYLE}>
+          {`+ ${hidden} more — click to keep this open`}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The rows, each keyed by what it says rather than by where it sits, so a card
+ * that gains a line above an existing one leaves the lines below it alone.
+ *
+ * A label can legitimately repeat — the same axis drawn on both sides of a map
+ * writes its name twice — so a repeat is counted and carries that count.
+ * @param rows - The lines to write, in the caller's order.
+ * @returns One element per row.
+ */
+function readoutLines(rows: readonly OverlayReadoutRow[]): ReactElement[] {
+  const lines: ReactElement[] = [];
+  const seen = new Map<string, number>();
+  for (const row of rows) {
+    const repeat = seen.get(row.label) ?? 0;
+    seen.set(row.label, repeat + 1);
+    lines.push(
+      <div
+        key={repeat === 0 ? row.label : `${row.label} ${String(repeat)}`}
+        style={ROW_STYLE}
+      >
+        {row.color === undefined ? null : (
+          <span style={{ ...CHIP_STYLE, background: row.color }} />
+        )}
+        <span style={LABEL_STYLE}>{row.label}</span>
+        <span style={VALUE_STYLE}>{row.value}</span>
+      </div>,
+    );
+  }
+  return lines;
+}
+
+/**
+ * The card is placed from an estimate until it has been measured once, and the
+ * estimate errs wide on purpose: a card that flips a few pixels early is still
+ * read where the reader is looking, while one that flips late is cut off by
+ * the edge of the figure.
+ * @param lines - How many lines the card is about to hold, its title included.
+ * @returns Its likely height in pixels.
+ */
+function estimatedHeight(lines: number): number {
+  return ESTIMATED_PADDING + lines * ESTIMATED_LINE_HEIGHT;
+}
+
+/**
+ * A pinned card takes the pointer back, so its rows can be selected and its
+ * dismiss button pressed, and it never grows past the figure it belongs to.
+ * @param boxHeight - Height of the figure.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns What pinning changes.
+ */
+function pinnedStyle(
+  boxHeight: number,
+  metrics: OverlayMetrics,
+): CSSProperties {
+  return {
+    pointerEvents: 'auto',
+    userSelect: 'text',
+    maxHeight: Math.max(MINIMUM_PINNED_HEIGHT, boxHeight - metrics.inset * 2),
+    overflowY: 'auto',
+  };
+}
+
+const ESTIMATED_WIDTH = 220;
+const ESTIMATED_LINE_HEIGHT = 18;
+const ESTIMATED_PADDING = 16;
+const MINIMUM_PINNED_HEIGHT = 80;
+
+const TITLE_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
+  fontWeight: 600,
+} as const satisfies CSSProperties;
+
+const ROW_STYLE = {
+  display: 'flex',
+  alignItems: 'baseline',
+  gap: 6,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  color: 'var(--text-muted)',
+} as const satisfies CSSProperties;
+
+/**
+ * The values line up on their own column and share one digit width, so a
+ * column of numbers can be compared down the card rather than read one by one.
+ */
+const VALUE_STYLE = {
+  marginLeft: 'auto',
+  fontVariantNumeric: 'tabular-nums',
+  whiteSpace: 'nowrap',
+} as const satisfies CSSProperties;
+
+const CHIP_STYLE = {
+  alignSelf: 'center',
+  flex: 'none',
+  width: 8,
+  height: 8,
+  borderRadius: 2,
+} as const satisfies CSSProperties;
+
+const FOOTER_STYLE = {
+  marginTop: 2,
+  paddingTop: 2,
+  borderTop: '1px solid var(--border)',
+  color: 'var(--text-faint)',
+} as const satisfies CSSProperties;

package/src/overlay/ui/OverlayRow.tsx

@@ -0,0 +1,200 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useId } from 'react';
+
+import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import { HelpTooltip } from '../../help/ui/HelpTooltip.tsx';
+
+import { useOverlayPanelShape } from './overlayPanelContext.ts';
+import {
+  OVERLAY_GRID_CELL_STYLE,
+  overlayGridRowStyle,
+  overlayNameColumnWidth,
+  overlayNameStyle,
+  overlayRowStyle,
+  overlayStackedRowStyle,
+} from './overlayRowStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** One choice offered by an {@link OverlaySelect} or an {@link OverlaySegmented}. */
+export interface OverlayOption<TValue extends string = string> {
+  /** What picking it means. */
+  value: TValue;
+  /**
+   * What it reads. Write the answer rather than the jargon — `95% of samples`,
+   * never `2 SD`, because the second is meaningless to a reader who has not
+   * met it and is misread as 95% by everyone who has.
+   */
+  label: string;
+  /**
+   * What the pointer is told about this one choice, when the control's own
+   * help does not cover a surprising consequence.
+   * @default undefined
+   */
+  title?: string;
+  /**
+   * Whether it can be picked. A choice that does not apply is greyed rather
+   * than removed, so the control keeps its shape and the reader learns that
+   * the option exists at all.
+   * @default false
+   */
+  disabled?: boolean;
+}
+
+/** How a row arranges its name and its control. */
+export type OverlayRowLayout = 'row' | 'grid';
+
+/** What every control inside an {@link OverlayBar} carries. */
+export interface OverlayControlProps {
+  /**
+   * The words in front of the control, phrased as the question the reader
+   * already has: `Colour by`, `Group outlines`, `Dot size`.
+   *
+   * Required, and deliberately so. A row with no name is a row whose only
+   * identification is the help glyph beside it, which is how a panel ends up
+   * with a column of question marks standing in for its words — and it is the
+   * name that a screen reader is given, that the help hangs off, and that
+   * fills the panel's left column.
+   */
+  label: string;
+  /**
+   * What the control does, in a sentence. It hangs off the name, which is
+   * underlined with dots to say so — never off a glyph of its own. A control
+   * floating over a figure has no room to explain itself, and a reader who has
+   * to guess what it does picks nothing at all, so every control should carry
+   * one.
+   * @default undefined — the name is written plainly
+   */
+  help?: HelpContent;
+  /**
+   * Whether the name is written or only announced. Hide it for a control whose
+   * own words already say what it is — a button that reads `Zoom to selection`
+   * — and never for one whose choices are bare numbers. It is honoured on a
+   * bar alone: in a panel the name is the left column, and an empty cell there
+   * is the ragged panel the grid exists to prevent.
+   * @default false
+   */
+  hideLabel?: boolean;
+  /**
+   * Whether the control is greyed and unreachable.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Value of the `data-testid` attribute of the control.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/** What {@link OverlayRow} lays out. Exported so a caller's own control gets the same name, help and geometry as the built-in ones. */
+export interface OverlayRowProps extends OverlayControlProps {
+  /** The control itself. */
+  children: ReactNode;
+  /**
+   * Whether the name sits in front of the control or above it. Above once the
+   * names are long enough to push the card past a third of the figure. Only
+   * consulted on a bar; a panel row is always two columns.
+   * @default 'inline'
+   */
+  labelPlacement?: 'inline' | 'above';
+  /**
+   * Whether the row is a line on a bar or a cell in a panel's grid.
+   * @default `'grid'` inside an {@link OverlayPanel}, `'row'` anywhere else
+   */
+  layout?: OverlayRowLayout;
+}
+
+/**
+ * A name, its help, and the control they belong to.
+ *
+ * Every control of this domain is one of these, which is the whole reason a
+ * picker and a stepper standing side by side in a card line up on the same
+ * baseline and answer to the same measurements. A caller writing a control
+ * this package does not have reaches for it too, rather than approximating the
+ * geometry and landing half a pixel out.
+ *
+ * The help hangs off the name rather than off a question mark beside it. Five
+ * controls each with a glyph put five question marks in a column down the left
+ * edge of a panel, and the eye reads that column before it reads a single
+ * word; a dotted underline says the same thing and costs nothing. The name is
+ * reachable by tab for the same reason the glyph was, so the explanation is
+ * not reserved to whoever is holding a pointer, and it carries the class
+ * `help-name` — the counterpart of the glyph's `help-icon` — so that whatever
+ * used to look for the glyph has something to look for. In a panel the name
+ * also names its row out loud, since a name a whole column away from its
+ * control is not associated with it by proximity alone.
+ * @param props - See {@link OverlayRowProps}.
+ * @returns The row.
+ */
+export function OverlayRow(props: OverlayRowProps): ReactElement {
+  const {
+    children,
+    label,
+    help,
+    hideLabel = false,
+    disabled = false,
+    testId,
+    labelPlacement = 'inline',
+  } = props;
+  const { metrics } = useOverlaySurface();
+  const panel = useOverlayPanelShape();
+  const layout = props.layout ?? (panel === undefined ? 'row' : 'grid');
+  const nameId = useId();
+
+  const written = layout === 'grid' || !hideLabel;
+  const name = written ? (
+    <span
+      id={layout === 'grid' ? nameId : undefined}
+      className={help === undefined ? undefined : 'help-name'}
+      tabIndex={help === undefined ? undefined : 0}
+      style={overlayNameStyle(metrics, { help: help !== undefined, disabled })}
+    >
+      {label}
+    </span>
+  ) : null;
+  const explained =
+    help === undefined ? (
+      name
+    ) : (
+      <HelpTooltip content={help}>{name}</HelpTooltip>
+    );
+  // A control whose name is not written keeps the help on its own words, so
+  // that dropping the name never quietly drops the explanation with it.
+  const control =
+    help === undefined || written ? (
+      children
+    ) : (
+      <HelpTooltip content={help}>{children}</HelpTooltip>
+    );
+
+  if (layout === 'grid') {
+    const width = panel?.nameWidth ?? overlayNameColumnWidth(metrics);
+    return (
+      <div
+        role="group"
+        aria-labelledby={nameId}
+        data-testid={testId}
+        style={overlayGridRowStyle(metrics, width)}
+      >
+        {explained}
+        <span style={OVERLAY_GRID_CELL_STYLE}>{control}</span>
+      </div>
+    );
+  }
+
+  if (labelPlacement === 'above') {
+    return (
+      <div data-testid={testId} style={overlayStackedRowStyle(metrics)}>
+        {explained}
+        {control}
+      </div>
+    );
+  }
+
+  return (
+    <div data-testid={testId} style={overlayRowStyle(metrics)}>
+      {explained}
+      {control}
+    </div>
+  );
+}

package/src/overlay/ui/OverlaySegmented.tsx

@@ -0,0 +1,67 @@
+import type { ReactElement } from 'react';
+
+import { OverlayPills } from './OverlayPills.tsx';
+import type { OverlayControlProps, OverlayOption } from './OverlayRow.tsx';
+import { OverlayRow } from './OverlayRow.tsx';
+
+/** What {@link OverlaySegmented} needs. Use it for two to four choices. */
+export interface OverlaySegmentedProps<
+  TValue extends string = string,
+> extends OverlayControlProps {
+  /** The current choice. */
+  value: TValue;
+  /** What may be chosen, in the order offered. */
+  options: ReadonlyArray<OverlayOption<TValue>>;
+  /** Called with the new choice. */
+  onChange: (value: TValue) => void;
+}
+
+/**
+ * The row of segments a card uses while every choice still fits on one line.
+ *
+ * Its choices are readable without being opened, which is worth the width up
+ * to about four of them: a reader who can see that a second view exists asks
+ * for it, and a reader looking at a closed picker does not.
+ *
+ * It is the same sunken track a figure's tab strip is made of, one size down,
+ * so a reader meets one device in a viewer rather than two that happen to both
+ * be rows of choices. The segments carry the caption's own name, because a
+ * bare row of buttons over a figure is announced as nothing at all to a reader
+ * arriving by keyboard.
+ * @param props - See {@link OverlaySegmentedProps}.
+ * @returns The caption, its help, and the segments.
+ */
+export function OverlaySegmented<TValue extends string = string>(
+  props: OverlaySegmentedProps<TValue>,
+): ReactElement {
+  const {
+    value,
+    options,
+    onChange,
+    label,
+    help,
+    hideLabel = false,
+    disabled = false,
+    testId,
+  } = props;
+
+  return (
+    <OverlayRow
+      label={label}
+      help={help}
+      hideLabel={hideLabel}
+      disabled={disabled}
+    >
+      <OverlayPills
+        role="radiogroup"
+        size="setting"
+        label={label}
+        value={value}
+        options={options}
+        disabled={disabled}
+        testId={testId}
+        onChange={onChange}
+      />
+    </OverlayRow>
+  );
+}