react-cheminfo 0.9.0 → 0.10.0

package/src/overlay/core/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a floating control sits over a figure, and how big it is.
+ *
+ * The geometry lives apart from the components that use it so it can be
+ * reasoned about and tested without a browser: which corner of a scatter is
+ * emptiest, whether a panel has room for a labelled strip or only a gear, and
+ * where a card must flip so it stays on screen.
+ */
+
+export type { EmptiestCornerOptions } from './emptiestCorner.ts';
+export { emptiestCorner } from './emptiestCorner.ts';
+export { shouldCollapseOverlay } from './overlayCollapse.ts';
+export type { OverlayMarkShape } from './overlayMarks.ts';
+export { OVERLAY_MARK_SHAPES, isFilledMark } from './overlayMarks.ts';
+export type {
+  OverlayDensity,
+  OverlayMetrics,
+  OverlayPointerKind,
+} from './overlayMetrics.ts';
+export { overlayMetrics } from './overlayMetrics.ts';
+export type {
+  OverlayCorner,
+  OverlayCornerStyle,
+  OverlayPlacement,
+} from './overlayPlacement.ts';
+export { overlayCornerStyle } from './overlayPlacement.ts';
+export type { OverlayTierRoom, OverlayTierSetting } from './overlayTierRoom.ts';
+export type { OverlayTier, OverlayTierWidths } from './overlayTiers.ts';
+export { overlayTier, overlayTierWidths } from './overlayTiers.ts';
+export type {
+  OverlayCardPlacement,
+  OverlayCardPlacementOptions,
+} from './placeOverlayCard.ts';
+export { placeOverlayCard } from './placeOverlayCard.ts';

package/src/overlay/core/overlayCollapse.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether a floating card folds into a single button at this figure width.
+ *
+ * A width of zero — which is what a figure reports before it has been measured,
+ * and what a server render always reports — keeps the card expanded, so the
+ * string-rendering tests and the first paint both see the real controls. A
+ * threshold that is not a real number is read the same way, so a missing
+ * breakpoint never silently hides every control on the figure.
+ * @param width - Width of the figure, in pixels.
+ * @param collapseBelow - The width under which the card folds.
+ * @returns Whether it folds.
+ */
+export function shouldCollapseOverlay(
+  width: number,
+  collapseBelow: number,
+): boolean {
+  if (!Number.isFinite(width) || width <= 0) return false;
+  if (!Number.isFinite(collapseBelow)) return false;
+  return width < collapseBelow;
+}

package/src/overlay/core/overlayMarks.ts

@@ -0,0 +1,43 @@
+/**
+ * The marks a legend entry, a reference point or a series can be drawn with.
+ *
+ * It lives in the framework-free half although only a component ever draws
+ * one, because the data that names a mark is written far from the drawing: a
+ * k-means centroid says it is a cross while it is still a plain object, long
+ * before any of it reaches React. Keeping the union here is what lets a result
+ * describe its own marks without a `core` module reaching into a `ui` one.
+ */
+
+/** Which mark a legend entry, a marker or a series stands for. */
+export type OverlayMarkShape =
+  'dot' | 'ring' | 'square' | 'line' | 'dashed' | 'cross';
+
+/**
+ * Every mark, in the order a picker offers them.
+ *
+ * The first three separate one filled thing from another by colour alone; the
+ * last three carry a second meaning on one figure — a line for a component
+ * beside dots for the samples — which is what keeps a figure readable when the
+ * colours run out or the reader does not separate two of them.
+ */
+export const OVERLAY_MARK_SHAPES: readonly OverlayMarkShape[] = [
+  'dot',
+  'ring',
+  'square',
+  'line',
+  'dashed',
+  'cross',
+];
+
+/**
+ * Whether a mark is drawn as a solid area rather than as a stroke.
+ *
+ * A solid mark takes its colour as a fill and a stroked one as a stroke, which
+ * is the one thing every renderer of a mark has to know and the one thing that
+ * is easy to get wrong in each of them separately.
+ * @param shape - The mark.
+ * @returns `true` for the filled marks, `false` for the drawn ones.
+ */
+export function isFilledMark(shape: OverlayMarkShape): boolean {
+  return shape === 'dot' || shape === 'square';
+}

package/src/overlay/core/overlayMetrics.ts

@@ -0,0 +1,112 @@
+/** How tightly a floating card packs its controls. */
+export type OverlayDensity = 'compact' | 'comfortable';
+
+/**
+ * What kind of pointer the reader has.
+ *
+ * A finger cannot hover and cannot aim at a twenty-four pixel target, so a
+ * coarse pointer overrides the density outright rather than nudging it.
+ */
+export type OverlayPointerKind = 'fine' | 'coarse';
+
+/** Every measurement a floating card and its controls are drawn from. */
+export interface OverlayMetrics {
+  /** Height of a control, in pixels. */
+  controlHeight: number;
+  /** Space between two controls, and between a caption and its control. */
+  gap: number;
+  /** Space inside the card, left and right. */
+  paddingX: number;
+  /** Space inside the card, top and bottom. */
+  paddingY: number;
+  /** Size of the text a control says. */
+  fontSize: number;
+  /** Size of the caption in front of a control. */
+  labelSize: number;
+  /** Corner radius of a control; the card itself uses `--radius`. */
+  controlRadius: number;
+  /** Space kept between the card and the edge of the figure. */
+  inset: number;
+  /** Side of the square button the card collapses to. */
+  buttonSize: number;
+  /** The size Blueprint's own controls are asked for. */
+  blueprintSize: 'small' | 'medium' | 'large';
+}
+
+/**
+ * The measurements a card is drawn from.
+ * @param density - How tightly the caller asked for the controls to be packed.
+ * @param pointer - What the reader is pointing with. Defaults to `'fine'`.
+ * @returns The measurements. A coarse pointer always gets the largest set,
+ * whatever the density says.
+ */
+export function overlayMetrics(
+  density: OverlayDensity,
+  pointer: OverlayPointerKind = 'fine',
+): OverlayMetrics {
+  if (pointer === 'coarse') return COARSE_METRICS;
+  return density === 'compact' ? COMPACT_METRICS : COMFORTABLE_METRICS;
+}
+
+/**
+ * The set a figure embedded in somebody else's page is drawn from.
+ *
+ * A figure that is a guest on a page it does not own has to spend as little of
+ * that page as it can, so every measurement here is the smallest one that is
+ * still honest. The control stays at twenty-four pixels — the floor a mouse
+ * can be aimed at, and the reason nothing below it is offered at all — while
+ * the room around it goes: a four pixel gap, a three pixel band above and
+ * below, and a six pixel inset from the figure's edge. A bar built from these
+ * stands thirty pixels tall, which is one line of the host's own text.
+ *
+ * The type steps down a size with it. Eleven pixels is what a control says and
+ * ten is what its caption says, because the caption is read once to find the
+ * control and the control's own words are read every time it is used.
+ */
+const COMPACT_METRICS: OverlayMetrics = {
+  controlHeight: 24,
+  gap: 4,
+  paddingX: 6,
+  paddingY: 3,
+  fontSize: 11,
+  labelSize: 10,
+  controlRadius: 5,
+  inset: 6,
+  buttonSize: 24,
+  blueprintSize: 'small',
+};
+
+/** The everyday set: room to read the captions without crowding the figure. */
+const COMFORTABLE_METRICS: OverlayMetrics = {
+  controlHeight: 30,
+  gap: 8,
+  paddingX: 8,
+  paddingY: 6,
+  fontSize: 12,
+  labelSize: 11,
+  controlRadius: 6,
+  inset: 8,
+  buttonSize: 30,
+  blueprintSize: 'medium',
+};
+
+/**
+ * Forty pixels is the smallest target a fingertip hits reliably, and the type
+ * grows with it because a phone is held further from the eye than a screen.
+ *
+ * Nothing here follows the density down. A finger does not become smaller
+ * because the figure was embedded, so a compact chart on a phone is a compact
+ * chart whose controls are still forty pixels across.
+ */
+const COARSE_METRICS: OverlayMetrics = {
+  controlHeight: 40,
+  gap: 10,
+  paddingX: 10,
+  paddingY: 8,
+  fontSize: 13,
+  labelSize: 12,
+  controlRadius: 8,
+  inset: 10,
+  buttonSize: 40,
+  blueprintSize: 'large',
+};

package/src/overlay/core/overlayPlacement.ts

@@ -0,0 +1,80 @@
+/** Which corner of a figure a floating card sits in. */
+export type OverlayCorner =
+  'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+/**
+ * Where a floating card sits: over one of the figure's corners, or docked
+ * outside the picture entirely.
+ *
+ * The three docked forms are the escape hatch for a figure whose data reaches
+ * all four corners. A chart that cannot spare a corner should move its
+ * controls out rather than cover the one cluster the reader came for.
+ *
+ * `stretch` is the one that spans the whole width rather than sitting at one
+ * end of the row: the settings bar of a figure embedded in somebody else's
+ * page, which is chrome above the picture and not a card floating on it. It is
+ * deliberately not offered as a floating placement — a full-width strip over a
+ * figure covers the very data it is there to explain.
+ */
+export type OverlayPlacement = OverlayCorner | 'above' | 'below' | 'stretch';
+
+/**
+ * The offsets a placement gives a card.
+ *
+ * Written out as a plain object of numbers rather than borrowed from React, so
+ * the whole of this entry point stays free of the framework that eventually
+ * spreads it onto a `style` prop. Only the two edges a corner is actually
+ * measured from are present: a key carrying `undefined` would still win over
+ * an offset the caller had merged in underneath it.
+ */
+export interface OverlayCornerStyle {
+  /** Whether the card is lifted out of the flow, or left in it and docked. */
+  position: 'absolute' | 'static';
+  /**
+   * Distance from the figure's top edge, in pixels.
+   * @default undefined — absent unless the card sits in a top corner
+   */
+  top?: number;
+  /**
+   * Distance from the figure's right edge, in pixels.
+   * @default undefined — absent unless the card sits in a right corner
+   */
+  right?: number;
+  /**
+   * Distance from the figure's bottom edge, in pixels.
+   * @default undefined — absent unless the card sits in a bottom corner
+   */
+  bottom?: number;
+  /**
+   * Distance from the figure's left edge, in pixels.
+   * @default undefined — absent unless the card sits in a left corner
+   */
+  left?: number;
+}
+
+/**
+ * The positioning a placement gives a card.
+ * @param placement - Where the card sits.
+ * @param inset - Distance kept between the card and the figure's edge, in pixels.
+ * @returns The style to spread onto the card. Every docked placement returns
+ * `position: 'static'`, so the same component lays out in the flow without a
+ * second code path.
+ */
+export function overlayCornerStyle(
+  placement: OverlayPlacement,
+  inset: number,
+): OverlayCornerStyle {
+  if (placement === 'top-left') {
+    return { position: 'absolute', top: inset, left: inset };
+  }
+  if (placement === 'top-right') {
+    return { position: 'absolute', top: inset, right: inset };
+  }
+  if (placement === 'bottom-left') {
+    return { position: 'absolute', bottom: inset, left: inset };
+  }
+  if (placement === 'bottom-right') {
+    return { position: 'absolute', bottom: inset, right: inset };
+  }
+  return { position: 'static' };
+}

package/src/overlay/core/overlayTierRoom.ts

@@ -0,0 +1,199 @@
+/**
+ * What a bar of controls is holding, and how much room each part of it needs.
+ *
+ * Every width here is an estimate of laid-out type rather than a measurement.
+ * Measuring the real labels would mean putting them in the document and
+ * reading their boxes back, which costs a layout pass on every render of every
+ * embedded figure on the page — and the answer would still arrive one frame
+ * after the width that prompted it. The estimate is deliberately generous: a
+ * bar that folds a word early costs the reader a caret, while one that folds
+ * late runs its controls off the edge of the figure.
+ *
+ * The geometry is restated here rather than read off the styles that draw it,
+ * because those styles are React's and this has to answer on a server, before
+ * anything exists to measure. Being an estimate is the point — it is allowed
+ * to be a few pixels out, and it is not allowed to need a browser.
+ */
+
+import type { OverlayMetrics } from './overlayMetrics.ts';
+
+/** One setting at the far end of a bar, for the room needed to write it. */
+export interface OverlayTierSetting {
+  /**
+   * The word written in front of the value where there is room — `Outlines`,
+   * `Colour`. It is the first thing dropped, because the name of a setting is
+   * read once and its value is read every time.
+   */
+  key: string;
+  /** What the setting currently reads: `Species`, `95%`. */
+  value: string;
+  /**
+   * Whether a row of the figure's own colours rides in front of the words.
+   * @default false
+   */
+  swatches?: boolean;
+}
+
+/** What a bar is holding, for the widths it needs to hold it. */
+export interface OverlayTierRoom {
+  /** What each tab reads. Empty for a figure with a single view. */
+  tabs: readonly string[];
+  /**
+   * The short form of each tab, in the same order — `Explains` for `How much
+   * each explains`. A tab with no short form keeps its long one, so shortening
+   * the two labels that are long does not blank the two that are not.
+   * @default the tabs themselves, which shortens nothing
+   */
+  shortTabs?: readonly string[];
+  /** The settings at the far end, in the order they are written. */
+  settings: readonly OverlayTierSetting[];
+  /**
+   * How many bare glyphs ride at the end: the `?` and the cog.
+   * @default 2
+   */
+  glyphs?: number;
+}
+
+/**
+ * The tab strip, sunken track and all.
+ * @param labels - What each tab reads.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels; `0` where there is no strip at all.
+ */
+export function overlayStripWidth(
+  labels: readonly string[],
+  metrics: OverlayMetrics,
+): number {
+  if (labels.length === 0) return 0;
+  const segment = 2 * (metrics.paddingX + 2) + OVERLAY_TRACK_PADDING;
+  let total = OVERLAY_TRACK_PADDING * 2;
+  for (const label of labels) {
+    total += overlayTextWidth(label, metrics) + segment;
+  }
+  return total;
+}
+
+/**
+ * The settings, each written as a value button of its own.
+ * @param settings - What the bar holds at its far end.
+ * @param withKeys - Whether each value still carries its key word.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels, the gaps between the buttons included.
+ */
+export function overlaySettingsWidth(
+  settings: readonly OverlayTierSetting[],
+  withKeys: boolean,
+  metrics: OverlayMetrics,
+): number {
+  let total = 0;
+  for (let index = 0; index < settings.length; index++) {
+    const setting = settings[index];
+    if (setting === undefined) continue;
+    const written = withKeys
+      ? `${setting.key} ${setting.value}`
+      : setting.value;
+    total += controlWidth(written, setting.swatches === true, metrics);
+    if (index > 0) total += metrics.gap;
+  }
+  return total;
+}
+
+/**
+ * Every setting gathered into one chip.
+ *
+ * What the chip saves is one button's worth of padding and one caret per
+ * setting it swallows — never the words themselves, which are the whole reason
+ * the reader is given a chip rather than a cog.
+ * @param settings - What the bar holds at its far end.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels.
+ */
+export function overlayChipRoom(
+  settings: readonly OverlayTierSetting[],
+  metrics: OverlayMetrics,
+): number {
+  let written = '';
+  let swatches = false;
+  let separators = 0;
+  for (let index = 0; index < settings.length; index++) {
+    const setting = settings[index];
+    if (setting === undefined) continue;
+    written += setting.value;
+    if (setting.swatches === true) swatches = true;
+    if (index > 0) separators++;
+  }
+  return (
+    controlWidth(written, swatches, metrics) +
+    separators * OVERLAY_CHIP_SEPARATOR
+  );
+}
+
+/**
+ * The bare glyphs at the very end of the bar, with the bar's own padding.
+ *
+ * One extra gap is counted for the space between the two ends of the row,
+ * which is what a bar spanning the figure pushes its ends apart with.
+ * @param glyphs - How many bare glyphs ride at the end.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels.
+ */
+export function overlayTailWidth(
+  glyphs: number,
+  metrics: OverlayMetrics,
+): number {
+  const count = Number.isFinite(glyphs) ? Math.max(0, Math.floor(glyphs)) : 0;
+  const buttons = count * (metrics.buttonSize + metrics.gap);
+  return buttons + 2 * metrics.paddingX + metrics.gap;
+}
+
+/**
+ * The room a run of words takes.
+ * @param text - The words.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels.
+ */
+function overlayTextWidth(text: string, metrics: OverlayMetrics): number {
+  return text.length * metrics.fontSize * OVERLAY_CHARACTER_RATIO;
+}
+
+/**
+ * What one character of a label takes, as a fraction of the type size.
+ *
+ * A mixed-case interface sans averages a little over half its size per
+ * character. This sits above that average on purpose: the labels that decide a
+ * fold are the long ones, and a long label of wide letters is the case where
+ * being wrong runs the row off the figure rather than merely folding it early.
+ */
+const OVERLAY_CHARACTER_RATIO = 0.58;
+
+/** The band of sunken track showing around a segment, on every side. */
+const OVERLAY_TRACK_PADDING = 2;
+
+/** How many colours the swatch glyph draws before the last becomes a count. */
+const OVERLAY_SWATCH_DOTS = 4;
+
+/** What sits between two settings inside a chip, hairline and margins. */
+const OVERLAY_CHIP_SEPARATOR = 9;
+
+/**
+ * One button carrying words, a caret, and possibly a row of colours.
+ * @param written - The words on it.
+ * @param swatches - Whether the figure's colours ride in front of them.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels, never under the button's own floor.
+ */
+function controlWidth(
+  written: string,
+  swatches: boolean,
+  metrics: OverlayMetrics,
+): number {
+  const dot = Math.max(4, Math.round(metrics.buttonSize / 6));
+  const glyph = swatches
+    ? OVERLAY_SWATCH_DOTS * dot + (OVERLAY_SWATCH_DOTS - 1) * 2 + 4
+    : 0;
+  const room = 2 * metrics.paddingX + metrics.fontSize;
+  return Math.max(
+    metrics.buttonSize,
+    overlayTextWidth(written, metrics) + glyph + room,
+  );
+}

package/src/overlay/core/overlayTiers.ts

@@ -0,0 +1,130 @@
+/**
+ * How much of itself a bar of controls writes, at the width it actually has.
+ *
+ * An embedded figure has no idea how wide the page around it is; it only knows
+ * its own box, which is why this answers from a measured component width and
+ * why there is no media query anywhere in the domain. A figure four hundred
+ * pixels wide in a wide page and the same figure filling a phone are the same
+ * problem, and a rule written against the viewport gets one of the two wrong.
+ *
+ * The ladder never *hides* a control. Each rung writes less of one: the key
+ * word in front of a value goes, then the long form of a tab label, then the
+ * settings gather into a single chip that still reads the configuration. That
+ * chip is the point of the whole ladder — a cog tells the reader nothing about
+ * how the figure is drawn, where `Species · 95%` answers the question they
+ * actually have without being opened at all.
+ */
+
+import type { OverlayMetrics } from './overlayMetrics.ts';
+import type { OverlayTierRoom } from './overlayTierRoom.ts';
+import {
+  overlayChipRoom,
+  overlaySettingsWidth,
+  overlayStripWidth,
+  overlayTailWidth,
+} from './overlayTierRoom.ts';
+
+/**
+ * How much of itself a bar writes.
+ *
+ * `full` writes every word. `condensed` drops the key word in front of each
+ * setting's value. `short` shortens the tab labels with it. `chip` gathers
+ * every setting into one chip that still reads the configuration. `tiny` keeps
+ * that chip and lets the tab strip scroll rather than shrink any further, so
+ * the strip is never clipped down to a row of initials.
+ */
+export type OverlayTier = 'full' | 'condensed' | 'short' | 'chip' | 'tiny';
+
+/** The width each rung of the ladder needs, in pixels. */
+export interface OverlayTierWidths {
+  /** Every word: full tab labels, and a key word in front of every value. */
+  full: number;
+  /** Full tab labels, values written without their key words. */
+  condensed: number;
+  /** Short tab labels, values written without their key words. */
+  short: number;
+  /** Short tab labels, every setting gathered into one chip. */
+  chip: number;
+}
+
+/**
+ * Which rung of the ladder a bar holding this content is on at this width.
+ *
+ * An unmeasured bar — a width of zero, which is what a component reports
+ * before its first layout and what a server render always reports — is given
+ * the roomiest tier. Folded is the answer that costs the reader something, so
+ * it is never the answer given on a guess; a bar that opened folded and sprang
+ * open a frame later would flicker on every page that embeds the figure.
+ * @param width - Width of the bar itself, in pixels, never of the page.
+ * @param room - See {@link OverlayTierRoom}.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The tier.
+ */
+export function overlayTier(
+  width: number,
+  room: OverlayTierRoom,
+  metrics: OverlayMetrics,
+): OverlayTier {
+  if (!Number.isFinite(width) || width <= 0) return 'full';
+  const widths = overlayTierWidths(room, metrics);
+  if (width >= widths.full) return 'full';
+  if (width >= widths.condensed) return 'condensed';
+  if (width >= widths.short) return 'short';
+  if (width >= widths.chip) return 'chip';
+  return 'tiny';
+}
+
+/**
+ * The width each rung needs, for this content at these measurements.
+ *
+ * Nothing here is a number a caller has to know: a viewer with two tabs stays
+ * roomy far longer than one with six, and a site that has translated the tab
+ * names has changed exactly these widths. That is why the content goes in and
+ * the thresholds come out, rather than the other way round.
+ *
+ * The rungs are forced to descend even where the writing saves nothing — a bar
+ * holding one setting has a chip exactly as wide as the value button it
+ * replaces — because a lower rung asking for more room than the rung above it
+ * would step the bar *down* into a tier that does not fit.
+ * @param room - See {@link OverlayTierRoom}.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns See {@link OverlayTierWidths}.
+ */
+export function overlayTierWidths(
+  room: OverlayTierRoom,
+  metrics: OverlayMetrics,
+): OverlayTierWidths {
+  const { tabs, shortTabs = tabs, settings, glyphs = 2 } = room;
+  const long = overlayStripWidth(tabs, metrics);
+  const brief = overlayStripWidth(shortened(tabs, shortTabs), metrics);
+  const tail = overlayTailWidth(glyphs, metrics);
+  const keyed = overlaySettingsWidth(settings, true, metrics);
+  const bare = overlaySettingsWidth(settings, false, metrics);
+
+  const full = long + keyed + tail;
+  const condensed = Math.min(full, long + bare + tail);
+  const short = Math.min(condensed, brief + bare + tail);
+  const chip = Math.min(
+    short,
+    brief + overlayChipRoom(settings, metrics) + tail,
+  );
+  return { full, condensed, short, chip };
+}
+
+/**
+ * The tab labels as they read once shortened.
+ * @param tabs - What each tab reads in full.
+ * @param shortTabs - The short forms, in the same order.
+ * @returns The labels to lay out.
+ */
+function shortened(
+  tabs: readonly string[],
+  shortTabs: readonly string[],
+): readonly string[] {
+  if (shortTabs === tabs) return tabs;
+  const labels: string[] = [];
+  for (let index = 0; index < tabs.length; index++) {
+    labels.push(shortTabs[index] ?? tabs[index] ?? '');
+  }
+  return labels;
+}