react-cheminfo 0.2.0 → 0.4.0

package/src/state/ui/mergeStored.ts

@@ -0,0 +1,87 @@
+/**
+ * Merge what came out of storage over the defaults it was stored against.
+ *
+ * A field the defaults name and the payload does not keeps its default, so a
+ * field added after the last save lands as its default rather than as
+ * `undefined`. A field whose stored value no longer has the shape of its
+ * default — a number where a string is expected, an object where an array is —
+ * is discarded, because a payload written by an older version of a page must
+ * never reach the interface as the wrong type. A key the defaults do not name
+ * is kept, so a bucket whose default is an empty dictionary keeps everything
+ * that was ever put in it.
+ *
+ * The result shares no object and no array with `defaults`, so a caller may
+ * write into it.
+ * @param defaults - What every missing or unusable field falls back to.
+ * @param stored - Whatever `JSON.parse` gave back, trusted for nothing.
+ * @returns The defaults, with whatever was stored and is usable on top.
+ */
+export function mergeStored<T extends object>(defaults: T, stored: unknown): T {
+  const source = isPlainRecord(stored) ? stored : {};
+  return mergeRecord(defaults as Record<string, unknown>, source) as T;
+}
+
+/**
+ * Whether a value is a plain object — the shape the JSON payload of a bucket
+ * takes — rather than an array, a primitive or null.
+ * @param value - Value to inspect.
+ * @returns True for a plain object.
+ */
+export function isPlainRecord(
+  value: unknown,
+): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function mergeRecord(
+  defaults: Record<string, unknown>,
+  stored: Record<string, unknown>,
+): Record<string, unknown> {
+  const merged: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(defaults)) {
+    merged[name] = cloneValue(value);
+  }
+  for (const [name, value] of Object.entries(stored)) {
+    if (value === undefined) continue;
+    merged[name] = Object.hasOwn(defaults, name)
+      ? mergeValue(defaults[name], value)
+      : value;
+  }
+  return merged;
+}
+
+function mergeValue(defaultValue: unknown, storedValue: unknown): unknown {
+  if (isPlainRecord(defaultValue) && isPlainRecord(storedValue)) {
+    return mergeRecord(defaultValue, storedValue);
+  }
+  return hasSameShape(defaultValue, storedValue)
+    ? storedValue
+    : cloneValue(defaultValue);
+}
+
+// A default that is `null` or absent accepts anything, since it names no shape
+// of its own.
+function hasSameShape(defaultValue: unknown, storedValue: unknown): boolean {
+  if (defaultValue === null || defaultValue === undefined) return true;
+  if (storedValue === null) return false;
+  if (Array.isArray(defaultValue) !== Array.isArray(storedValue)) return false;
+  return typeof defaultValue === typeof storedValue;
+}
+
+function cloneValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    const copy = new Array<unknown>(value.length);
+    for (let index = 0; index < value.length; index++) {
+      copy[index] = cloneValue(value[index]);
+    }
+    return copy;
+  }
+  if (isPlainRecord(value)) {
+    const copy: Record<string, unknown> = {};
+    for (const [name, item] of Object.entries(value)) {
+      copy[name] = cloneValue(item);
+    }
+    return copy;
+  }
+  return value;
+}

package/src/state/ui/persistBucket.ts

@@ -0,0 +1,147 @@
+import { isPlainRecord, mergeStored } from './mergeStored.ts';
+
+/**
+ * A bucket of preferences kept in `localStorage` under one versioned key.
+ *
+ * Everything here is best effort. In a page framed by a course, third-party
+ * storage is partitioned in Chrome and blocked in Safari, so a read may find
+ * nothing, a write may be refused, and touching the store may throw before it
+ * is even reached — none of which may ever reach the interface. A visitor whose
+ * quota is full still gets a working site, with their preferences lasting only
+ * as long as the tab.
+ * @param options - See {@link PersistBucketOptions}.
+ * @returns The three ways to use the bucket: read it, write it, forget it.
+ */
+export function persistBucket<T extends object>(
+  options: PersistBucketOptions<T>,
+): PersistedBucket<T> {
+  const { key, version = 1, defaults, onQuotaExceeded } = options;
+  const storageKey = `${key}:v${version}`;
+
+  return {
+    storageKey,
+    read: () => {
+      const stored = readEntry(storageKey);
+      return {
+        value: mergeStored(defaults, stored),
+        firstRun: stored === undefined,
+      };
+    },
+    write: (value: T) => {
+      writeEntry(storageKey, value, onQuotaExceeded);
+    },
+    clear: () => {
+      try {
+        globalThis.localStorage?.removeItem(storageKey);
+      } catch {
+        // An unavailable store has nothing to forget.
+      }
+    },
+  };
+}
+
+/** How a bucket is named, versioned and filled in. */
+export interface PersistBucketOptions<T extends object> {
+  /**
+   * Name of the bucket, namespaced by the site, e.g. `smiles:exercises`. The
+   * version is appended to it, so this never carries one itself.
+   */
+  key: string;
+  /**
+   * Schema version, appended to the key as `:v<version>`. Raise it when a new
+   * shape cannot be reconciled with the old one field by field, and every entry
+   * written by the previous shape is then ignored rather than migrated.
+   * @default 1
+   */
+  version?: number;
+  /**
+   * What a visitor who has stored nothing gets, and what every missing or
+   * unusable field of a stored payload falls back to. Must be JSON
+   * serialisable, since that is how it is stored.
+   */
+  defaults: T;
+  /**
+   * Called when a write was refused because the store is full, with the error
+   * the store threw. The write is swallowed either way; this only exists so a
+   * page can tell its visitor that what they are doing is no longer being kept.
+   * @default undefined
+   */
+  onQuotaExceeded?: (error: unknown) => void;
+}
+
+/** The three ways a page uses its bucket. */
+export interface PersistedBucket<T extends object> {
+  /** The versioned key the bucket occupies, e.g. `smiles:exercises:v1`. */
+  readonly storageKey: string;
+  /** What was stored, merged over the defaults. */
+  read: () => BucketRead<T>;
+  /** Store the bucket as it now stands, replacing what was there. */
+  write: (value: T) => void;
+  /** Forget the bucket, leaving whatever the page holds in memory untouched. */
+  clear: () => void;
+}
+
+/** What one read of a bucket found. */
+export interface BucketRead<T> {
+  /** The stored payload merged over the defaults, ready to be used as is. */
+  value: T;
+  /**
+   * True when nothing usable was there: no entry, an unreadable store, or a
+   * payload that is not an object. It tells a first visit from a visitor who
+   * chose exactly the defaults, which is what decides whether a page opens on
+   * its welcome state or writes the bucket straight back.
+   */
+  firstRun: boolean;
+}
+
+function readEntry(storageKey: string): unknown {
+  let raw: string | null;
+  try {
+    raw = globalThis.localStorage?.getItem(storageKey) ?? null;
+  } catch {
+    return undefined;
+  }
+  if (raw === null) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return isPlainRecord(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeEntry(
+  storageKey: string,
+  value: unknown,
+  onQuotaExceeded: ((error: unknown) => void) | undefined,
+): void {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    // A value that cannot be serialised is a bug in the caller, never a reason
+    // to take the page down with it.
+    return;
+  }
+  try {
+    globalThis.localStorage?.setItem(storageKey, serialized);
+  } catch (error) {
+    if (!isQuotaExceeded(error) || onQuotaExceeded === undefined) return;
+    try {
+      onQuotaExceeded(error);
+    } catch {
+      // A callback that throws must not turn a lost preference into a crash.
+    }
+  }
+}
+
+function isQuotaExceeded(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  const { name, code } = error as { name?: unknown; code?: unknown };
+  return (
+    name === 'QuotaExceededError' ||
+    name === 'NS_ERROR_DOM_QUOTA_REACHED' ||
+    code === 22 ||
+    code === 1014
+  );
+}

package/src/structure/core/editorValue.ts

@@ -0,0 +1,116 @@
+import { looksLikeMolfile } from './molfile.ts';
+
+/** One structure of an editor's value, with whatever was written next to it. */
+export interface EditorLine {
+  /**
+   * The structure. On a line-oriented value this is the first blank-separated
+   * token, because a line notation never holds a blank; on a molfile it is the
+   * whole file.
+   */
+  structure: string;
+  /**
+   * What followed the structure on its line, which a Daylight `.smi` file uses
+   * as a name. Empty when nothing did.
+   */
+  label: string;
+  /** 1-based line the structure starts on, so an error can point back at it. */
+  line: number;
+}
+
+/** An editor's value, classified and cut into the structures it holds. */
+export interface EditorValue {
+  /** How the value is written; `empty` when it holds no structure at all. */
+  kind: 'molfile' | 'smiles' | 'empty';
+  /**
+   * The molfile, exactly as it arrived, when `kind` is `molfile`. Empty
+   * otherwise — a molfile's fixed-width header does not survive being trimmed.
+   */
+  molfile: string;
+  /**
+   * Every structure the value holds, in order: one per meaningful line for a
+   * line-oriented value, a single entry for a molfile, none for an empty one.
+   */
+  entries: EditorLine[];
+}
+
+/**
+ * Take an editor's value apart.
+ *
+ * A structure box is handed whatever the chemist had: one molfile pasted out
+ * of another tool, or a run of line notations one per line, possibly with a
+ * name after each and with blank and `#` comment lines in between. Both are
+ * read here so a page can take either without asking which it was given.
+ * @param text - The editor's value, as typed, pasted or dropped.
+ * @returns The notation, the molfile when it is one, and the structures.
+ */
+export function splitEditorValue(text: string): EditorValue {
+  if (text.trim() === '') return { kind: 'empty', molfile: '', entries: [] };
+  if (looksLikeMolfile(text)) {
+    return {
+      kind: 'molfile',
+      molfile: text,
+      entries: [{ structure: text, label: '', line: 1 }],
+    };
+  }
+  const entries = splitLines(text);
+  return entries.length === 0
+    ? { kind: 'empty', molfile: '', entries: [] }
+    : { kind: 'smiles', molfile: '', entries };
+}
+
+/** An idCode and, when the writer emitted one, the atom layout beside it. */
+export interface IdCodeValue {
+  idCode: string;
+  /** Absent when the value carried no coordinates. */
+  coordinates?: string;
+}
+
+/**
+ * Take an idCode apart.
+ *
+ * A drawing editor appends the atom coordinates after a space, which
+ * `Molecule.fromIDCode` takes as a second argument rather than as part of the
+ * first, and which two drawings of the same structure differ by.
+ * @param value - The editor value, coordinates included or not.
+ * @returns The idCode and the coordinates, the idCode empty for a blank value.
+ */
+export function splitIdCode(value: string): IdCodeValue {
+  const [idCode = '', coordinates] = value.trim().split(' ');
+  return coordinates === undefined ? { idCode } : { idCode, coordinates };
+}
+
+/**
+ * Whether an idCode describes nothing.
+ *
+ * Erasing a canvas does not leave the editor with an empty string: it leaves
+ * the idCode of the empty molecule, or of the empty fragment in query mode.
+ * Treating either as a structure keeps a filter alive with nothing drawn.
+ * @param value - The editor value, coordinates included or not.
+ * @returns True when there is nothing on the canvas.
+ */
+export function isEmptyIdCode(value: string): boolean {
+  return EMPTY_ID_CODES.has(splitIdCode(value).idCode);
+}
+
+/** What openchemlib writes for a structure with no atoms: molecule, fragment. */
+const EMPTY_ID_CODES = new Set(['', 'd@', 'dH']);
+
+function splitLines(text: string): EditorLine[] {
+  const entries: EditorLine[] = [];
+  const lines = text.split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    const line = (lines[index] ?? '').trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const blank = line.search(/\s/);
+    entries.push(
+      blank === -1
+        ? { structure: line, label: '', line: index + 1 }
+        : {
+            structure: line.slice(0, blank),
+            label: line.slice(blank).trim(),
+            line: index + 1,
+          },
+    );
+  }
+  return entries;
+}

package/src/structure/core/fragmentQuery.ts

@@ -0,0 +1,50 @@
+import { isEmptyIdCode } from './editorValue.ts';
+import type { StructureKind } from './readStructure.ts';
+import { readStructure } from './readStructure.ts';
+
+/** What a substructure field is currently filtering on. */
+export interface FragmentQuery {
+  /** The notation the query should be read as. */
+  kind: StructureKind;
+  /** The query, ready to hand a parser. Empty when nothing is filtered on. */
+  value: string;
+  /**
+   * True when the field filters on nothing — a blank box, or the idCode an
+   * erased canvas leaves behind.
+   */
+  isEmpty: boolean;
+}
+
+/**
+ * Read what a substructure field holds.
+ *
+ * A filter is fed from two places that disagree about what "nothing" is: a
+ * text box hands back the empty string, while a drawing canvas hands back the
+ * idCode of the empty molecule. Both mean the filter is off, and a filter that
+ * stays on with nothing drawn quietly hides every result.
+ * @param text - The field's value: an idCode, a molfile or a line notation.
+ * @returns The notation, the query, and whether anything is being filtered on.
+ */
+export function fragmentQuery(text: string): FragmentQuery {
+  if (isEmptyIdCode(text)) return { kind: 'empty', value: '', isEmpty: true };
+  const read = readStructure(text);
+  return {
+    kind: read.kind,
+    value: read.value,
+    isEmpty: read.kind === 'empty',
+  };
+}
+
+/**
+ * Whether two field values describe the same query, so a search is not run
+ * again for a value that only changed by its surrounding blanks.
+ * @param left - One field value.
+ * @param right - The other field value.
+ * @returns True when both would be read as the same query.
+ */
+export function sameFragmentQuery(left: string, right: string): boolean {
+  const first = fragmentQuery(left);
+  const second = fragmentQuery(right);
+  if (first.isEmpty || second.isEmpty) return first.isEmpty === second.isEmpty;
+  return first.kind === second.kind && first.value === second.value;
+}

package/src/structure/core/index.ts

@@ -0,0 +1,13 @@
+export type { EditorLine, EditorValue } from './editorValue.ts';
+export { splitEditorValue } from './editorValue.ts';
+export type { FragmentQuery } from './fragmentQuery.ts';
+export { fragmentQuery, sameFragmentQuery } from './fragmentQuery.ts';
+export type { MolfileClassification, MolfileVersion } from './molfile.ts';
+export { classifyMolfile, molfileAtomCount } from './molfile.ts';
+export type { ReadStructureResult, StructureKind } from './readStructure.ts';
+export { looksLikeSmarts, readStructure } from './readStructure.ts';
+export type {
+  StructureSource,
+  StructureSourceInput,
+} from './structureSource.ts';
+export { structureSource } from './structureSource.ts';

package/src/structure/core/molfile.ts

@@ -0,0 +1,90 @@
+/** Which connection-table dialect a molfile is written in. */
+export type MolfileVersion = 'v2000' | 'v3000' | 'unknown';
+
+/** What a molfile's counts line says about it. */
+export interface MolfileClassification {
+  /** The dialect, `unknown` when the text carries no version stamp. */
+  version: MolfileVersion;
+  /**
+   * Atoms the counts line declares, `0` when there is no counts line to read.
+   */
+  atomCount: number;
+}
+
+/**
+ * Read a molfile's version and its declared atom count.
+ *
+ * The two dialects write their counts in unrelated places: V2000 packs them
+ * into the fixed-width fields of the line ending in `V2000`, while a V3000
+ * file leaves those fields at zero and declares the real counts on an
+ * `M  V30 COUNTS` line further down. Reading a V3000 file with the V2000 rule
+ * therefore answers zero atoms without failing, which is what makes a viewer
+ * render an empty scene and report nothing.
+ * @param text - A molfile, or any text that may not be one.
+ * @returns The dialect and the declared atom count.
+ */
+export function classifyMolfile(text: string): MolfileClassification {
+  if (V3000_STAMP.test(text)) {
+    return { version: 'v3000', atomCount: countIn(text, V3000_COUNTS) };
+  }
+  if (V2000_STAMP.test(text)) {
+    return { version: 'v2000', atomCount: countIn(text, V2000_COUNTS) };
+  }
+  return { version: 'unknown', atomCount: 0 };
+}
+
+/**
+ * How many atoms a molfile declares, whichever dialect it is written in.
+ * @param text - A molfile, or any text that may not be one.
+ * @returns The declared atom count, `0` when the text declares none.
+ */
+export function molfileAtomCount(text: string): number {
+  return classifyMolfile(text).atomCount;
+}
+
+/**
+ * Whether a piece of text should be read as a molfile rather than as a line
+ * notation.
+ *
+ * A line notation is a single line and can never carry a version stamp, so a
+ * text holding a header, a counts line and at least one atom line is the one
+ * that is a molfile.
+ * @param text - The structure, as typed, pasted or dropped.
+ * @returns True when it should be read as a molfile.
+ */
+export function looksLikeMolfile(text: string): boolean {
+  if (countLines(text) < 4) return false;
+  return classifyMolfile(text).version !== 'unknown';
+}
+
+/**
+ * The version stamp closes a line whose every other field is a number, so a
+ * data field or a sentence mentioning the dialect is not mistaken for one.
+ */
+const V2000_STAMP = /^[\d ]+V2000[^\S\n]*$/m;
+const V3000_STAMP = /^[\d ]+V3000[^\S\n]*$/m;
+
+/**
+ * The V2000 counts line is fixed-width: three characters for the atoms, three
+ * for the bonds. A writer that trims the padding still lands inside the same
+ * six characters for any count a V2000 file can hold.
+ */
+const V2000_COUNTS = /^(?<atoms>[\d ]{3})[\d ]*V2000[^\S\n]*$/m;
+const V3000_COUNTS = /^M {2}V30 COUNTS +(?<atoms>\d+)/m;
+
+function countIn(text: string, pattern: RegExp): number {
+  const atoms = pattern.exec(text)?.groups?.atoms;
+  if (atoms === undefined) return 0;
+  const count = Number.parseInt(atoms.trim(), 10);
+  return Number.isFinite(count) && count > 0 ? count : 0;
+}
+
+function countLines(text: string): number {
+  let lines = 1;
+  let index = text.indexOf('\n');
+  while (index !== -1) {
+    lines++;
+    index = text.indexOf('\n', index + 1);
+  }
+  return lines;
+}

package/src/structure/core/readStructure.ts

@@ -0,0 +1,73 @@
+import { looksLikeMolfile } from './molfile.ts';
+
+/** How a piece of structure text turned out to be written. */
+export type StructureKind = 'molfile' | 'smiles' | 'smarts' | 'empty';
+
+/** A piece of structure text, and the notation it should be read as. */
+export interface ReadStructureResult {
+  kind: StructureKind;
+  /**
+   * The text to hand a parser. A line notation is trimmed; a molfile is left
+   * exactly as it arrived, because its first three lines are a fixed-width
+   * header whose title line is very often blank — trimming shifts every line
+   * up and the counts line is then read as an atom.
+   */
+  value: string;
+}
+
+/**
+ * Decide what a piece of text is, without parsing it.
+ *
+ * Nothing is asked of the user, because the answer is in the text: a molfile
+ * carries a version stamp and several lines, a query carries syntax that only
+ * exists in SMARTS, and whatever is left is a SMILES. Text that holds nothing
+ * is the third answer, so a field can tell "not typed yet" from "typed
+ * something wrong" and only complain about the second.
+ * @param text - The structure, as typed, pasted or dropped.
+ * @returns The notation and the text to read it with.
+ */
+export function readStructure(text: string): ReadStructureResult {
+  const trimmed = text.trim();
+  if (trimmed === '') return { kind: 'empty', value: '' };
+  if (looksLikeMolfile(text)) return { kind: 'molfile', value: text };
+  if (looksLikeSmarts(trimmed)) return { kind: 'smarts', value: trimmed };
+  return { kind: 'smiles', value: trimmed };
+}
+
+/**
+ * Whether a line notation uses syntax that exists in SMARTS and not in SMILES.
+ *
+ * Only the inside of a bracket atom is inspected for the primitives, because
+ * `#` is a triple bond outside one and `D`, `X`, `R`, `v` and `h` are the
+ * start of real element symbols. `~`, `&`, `,`, `;`, `!` and `$(` are SMARTS
+ * anywhere they appear.
+ * @param text - The line notation, already trimmed.
+ * @returns True when it can only be a query.
+ */
+export function looksLikeSmarts(text: string): boolean {
+  if (/[~&;,!]/.test(text) || text.includes('$(')) return true;
+  for (const match of text.matchAll(BRACKET_ATOM)) {
+    if (QUERY_PRIMITIVE.test(match.groups?.atom ?? '')) return true;
+  }
+  return BARE_WILDCARD.test(text.replaceAll(BRACKET_ATOM, ''));
+}
+
+const BRACKET_ATOM = /\[(?<atom>[^\]]*)\]/g;
+
+/**
+ * `#6` (atomic number), `X3` / `D2` / `R1` / `r5` / `v4` / `h1` / `x2`
+ * (counts), and the `a` / `A` wildcards. A digit is required after the letter,
+ * so `[Xe]` and `[Rn]` stay elements. The wildcard is anchored to the start of
+ * the atom, after an optional isotope: unanchored it matches the `a` of
+ * `[Na+]`, and every bracketed element holding a lowercase a — Na, Ca, Ba, La,
+ * Ta — would then read as a query rather than as the atom it is.
+ */
+const QUERY_PRIMITIVE = /#\d|[DXRrvhx]\d|^\*|^\d*[aA](?![a-z])/;
+
+/**
+ * Outside a bracket the wildcard has to stand on its own: a letter on either
+ * side and it is part of a word, not a pattern. Widening this to any `a` or
+ * `A` reads the header `CAS` as the three-atom SMARTS `C`,`A`,`S`, and a
+ * spreadsheet's header row stops being recognised as one.
+ */
+const BARE_WILDCARD = /(?:^|[^A-Za-z])[aA](?![a-z])/;

package/src/structure/core/structureSource.ts

@@ -0,0 +1,57 @@
+import { isEmptyIdCode, splitIdCode } from './editorValue.ts';
+import { molfileAtomCount } from './molfile.ts';
+
+/** Every notation a read-only depiction may be handed. */
+export interface StructureSourceInput {
+  /** A canonical openchemlib idCode, coordinates included or not. */
+  idCode?: string;
+  /** Encoded 2D coordinates, when they did not travel with the idCode. */
+  coordinates?: string;
+  /** A molfile, V2000 or V3000. */
+  molfile?: string;
+  /** A SMILES. */
+  smiles?: string;
+}
+
+/** The one notation a depiction should be drawn from. */
+export interface StructureSource {
+  /** Which notation was picked; `empty` when none of them holds a structure. */
+  kind: 'idcode' | 'molfile' | 'smiles' | 'empty';
+  /** The text to draw, empty when there is nothing to draw. */
+  value: string;
+  /** Encoded 2D coordinates, only ever set beside an idCode. */
+  coordinates?: string;
+}
+
+/**
+ * Pick the notation a depiction is drawn from when several were supplied.
+ *
+ * The most exact one wins: an idCode says precisely which structure, a molfile
+ * additionally carries the layout its author chose, and a SMILES leaves the
+ * layout to be invented. A notation that describes nothing — a blank string, a
+ * molfile with an empty atom block, the idCode an erased canvas leaves behind
+ * — is skipped rather than drawn, which is what turns a broken box into the
+ * next best picture, or into an honest placeholder.
+ * @param input - Whatever notations the caller has.
+ * @returns The notation to draw, and the text to draw it from.
+ */
+export function structureSource(input: StructureSourceInput): StructureSource {
+  const { idCode, coordinates, molfile, smiles } = input;
+
+  if (idCode !== undefined && !isEmptyIdCode(idCode)) {
+    const split = splitIdCode(idCode);
+    const layout = split.coordinates ?? coordinates;
+    return layout === undefined || layout === ''
+      ? { kind: 'idcode', value: split.idCode }
+      : { kind: 'idcode', value: split.idCode, coordinates: layout };
+  }
+
+  if (molfile !== undefined && molfileAtomCount(molfile) > 0) {
+    return { kind: 'molfile', value: molfile };
+  }
+
+  const line = smiles?.trim() ?? '';
+  if (line !== '') return { kind: 'smiles', value: line };
+
+  return { kind: 'empty', value: '' };
+}

package/src/structure/core/toolbarFloor.ts

@@ -0,0 +1,31 @@
+/** The two 1px borders of a container that sizes itself border-box. */
+export const TOOLBAR_BORDERS = 2;
+
+/**
+ * The smallest height a drawing editor's container may take.
+ *
+ * The editor's toolbar is a canvas of a fixed height, drawn from a sprite of a
+ * fixed number of buttons: a container any shorter than that does not scroll,
+ * it simply cuts the last buttons off. So the floor is whichever is taller,
+ * the height the caller asked for or the toolbar plus the borders around it.
+ * @param toolbarHeight - Height the toolbar was measured at, in pixels.
+ * @param minHeight - Smallest height the caller asked for, in pixels.
+ * @param borders - Borders the container adds around the toolbar, in pixels.
+ * @returns The height to give the container, in pixels.
+ */
+export function toolbarFloorHeight(
+  toolbarHeight: number,
+  minHeight: number,
+  borders: number = TOOLBAR_BORDERS,
+): number {
+  const asked = positive(minHeight);
+  const measured = positive(toolbarHeight);
+  // A toolbar with no layout yet measures zero, and a floor of two pixels of
+  // border would collapse the editor before it has had a chance to draw.
+  if (measured === 0) return asked;
+  return Math.max(asked, measured + positive(borders));
+}
+
+function positive(value: number): number {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}