react-cheminfo 0.28.0 → 0.29.0

package/src/panel/core/index.ts

@@ -0,0 +1,47 @@
+/**
+ * The chrome an editor is laid out with, below the components that wear it.
+ *
+ * A panel, a status bar and a dialog look the same in every editor of the
+ * family, and they have to: a reader who has learnt one editor has learnt the
+ * others, and that only holds while the parts are literally the same parts.
+ * What is here is the half that draws nothing — the style objects each part is
+ * built from, the questions the DOM is asked before a shortcut fires, and the
+ * sentences a reader is given when a file goes wrong.
+ */
+
+export { listStyle, paragraphStyle } from './dialogStyles.ts';
+export { isEditingField } from './isEditingField.ts';
+export {
+  inlineLabelStyle,
+  labelRowStyle,
+  labelStyle,
+  panelBodyStyle,
+  panelCapsuleGroupStyle,
+  panelCapsuleRowStyle,
+  panelCapsulesStyle,
+  panelCellStyle,
+  panelColumnButtonStyle,
+  panelEmptyStyle,
+  panelHeaderCellStyle,
+  panelHeadingStyle,
+  panelNumberCellStyle,
+  panelScrollAreaStyle,
+  panelStickyHeaderStyle,
+  panelStyle,
+  panelTableStyle,
+  panelToolbarCountStyle,
+  panelToolbarStyle,
+  shortPanelStyle,
+  smallCapsuleStyle,
+} from './panelStyles.ts';
+export type { RowPlacement, RowSpacers } from './rowSpacers.ts';
+export { rowSpacers } from './rowSpacers.ts';
+export {
+  countLabel,
+  statusBarStyle,
+  statusItemStyle,
+  statusMutedStyle,
+  statusSpacerStyle,
+} from './statusBar.ts';
+export { filterNeedle, matchesNeedle } from './textFilter.ts';
+export { yieldToPainting } from './yieldToPainting.ts';

package/src/panel/core/isEditingField.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether an event belongs to something the user is typing in.
+ *
+ * An editor listens on the document for shortcuts and for pastes, so both have
+ * to keep their hands off every field on the page: an `f` typed into a mass box,
+ * a row filter or a sequence field is part of what is being written, not a chart
+ * being fitted or a glycan being drawn.
+ *
+ * `isContentEditable` is asked as well as the tag, because a rich text box is a
+ * `div` and swallowing its keys is the same mistake made less visibly. Two of
+ * the three copies this replaces had lost that line — one of them while keeping
+ * the sentence claiming it.
+ * @param target - What the event was delivered to.
+ * @returns Whether it should be left alone.
+ */
+export function isEditingField(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  return EDITING_TAGS.has(target.tagName);
+}
+
+/** Elements an event belongs to rather than to the editor around them. */
+const EDITING_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);

package/src/panel/core/panelStyles.ts

@@ -0,0 +1,248 @@
+/**
+ * What every side panel is built out of, in every editor.
+ *
+ * A panel is the same three parts each time — the box it fills, a toolbar of
+ * its own actions under the header, and the body that scrolls — and the reason
+ * one file holds the measurements rather than each package holding its own is
+ * that a page shows the editors together: a glycan drawn beside its spectrum
+ * stacks panels from two packages in one accordion, and a panel that padded
+ * itself differently reads as a step in the column.
+ *
+ * Three copies of this file had already drifted — one had renamed half of it,
+ * one had lost a border, and their toolbars stood at two different heights — so
+ * the divergence is not hypothetical.
+ */
+
+/** The box a panel fills: it takes the height it is given and never overflows it. */
+export const panelStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 1px',
+  minHeight: 0,
+} as const;
+
+/**
+ * A panel that only holds what it holds, and is as tall as that.
+ *
+ * The stack gives it the height its content asks for rather than a share of the
+ * side, which is what a panel of a few rows wants.
+ */
+export const shortPanelStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  padding: 8,
+} as const;
+
+/**
+ * The row of a panel's own actions, directly under its header.
+ *
+ * The header carries shell chrome only, so what a panel switches on and off
+ * travels with the panel instead. No padding of its own: what sits in it is a
+ * `Toolbar`, which spaces its own items, and a row that padded them again stood
+ * taller than the same row in the editor next door.
+ */
+export const panelToolbarStyle = {
+  display: 'flex',
+  borderBottom: '1px solid rgb(217 223 230)',
+} as const;
+
+/**
+ * How much of a list is left, at the far end of the panel's toolbar row.
+ *
+ * What a filter left is read while reaching for the filter rather than while
+ * reading the rows, so it belongs beside the actions; and at the end of the row,
+ * where it stays put as actions are added beside them.
+ */
+export const panelToolbarCountStyle = {
+  marginLeft: 'auto',
+  display: 'flex',
+  alignItems: 'center',
+  padding: '0 8px',
+  fontSize: 11,
+  opacity: 0.7,
+} as const;
+
+/** What is under the toolbar: the panel's content, scrolling within its share. */
+export const panelBodyStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  padding: 8,
+  flex: '1 1 1px',
+  minHeight: 0,
+  overflow: 'auto',
+} as const;
+
+/**
+ * A list inside a panel body that scrolls on its own.
+ *
+ * A table with a sticky header cannot share the body's scroll, because a scroll
+ * container's padding is inside what it clips: the rows leaving the top show in
+ * the eight pixels above a header pinned to `top: 0`, so the list appears to run
+ * behind its own header instead of stopping at it. Scrolling the rows in a
+ * region with no padding of its own pins the header to the top of what is
+ * actually moving, and leaves whatever the panel wrote above the table — the
+ * count, the filter box — where it can still be read at the thousandth row.
+ */
+export const panelScrollAreaStyle = {
+  flex: '1 1 1px',
+  minHeight: 0,
+  overflow: 'auto',
+} as const;
+
+/** A table of rows filling the width of the panel it is read in. */
+export const panelTableStyle = {
+  width: '100%',
+  borderCollapse: 'collapse',
+  fontSize: 11,
+  fontVariantNumeric: 'tabular-nums',
+} as const;
+
+/**
+ * A heading cell that stays put while the rows scroll under it.
+ *
+ * It pads nothing, because what it holds is a button that pads itself: a
+ * heading that sorts has to be clickable across the whole cell, and padding the
+ * cell instead would leave a dead border around the target.
+ */
+export const panelStickyHeaderStyle = {
+  position: 'sticky',
+  top: 0,
+  zIndex: 1,
+  background: 'rgb(255 255 255)',
+  textAlign: 'left',
+  padding: 0,
+  borderBottom: '1px solid rgb(217 223 230)',
+} as const;
+
+/** The same heading when it is plain text, which has to pad itself. */
+export const panelHeaderCellStyle = {
+  ...panelStickyHeaderStyle,
+  padding: '2px 6px',
+  whiteSpace: 'nowrap',
+} as const;
+
+/**
+ * A column heading, which is also how the table is reordered.
+ *
+ * The headers sort rather than a select box above the table, because which order
+ * a table is read in changes with every question asked of it, and a select costs
+ * two clicks and a menu for what a column heading answers in one.
+ */
+export const panelColumnButtonStyle = {
+  all: 'unset',
+  display: 'block',
+  width: '100%',
+  padding: '3px 4px',
+  cursor: 'pointer',
+  fontSize: 10,
+  fontWeight: 600,
+  textTransform: 'uppercase',
+  letterSpacing: '0.04em',
+  opacity: 0.6,
+} as const;
+
+/** An ordinary cell of such a table. */
+export const panelCellStyle = {
+  padding: '1px 6px',
+  borderBottom: '1px solid rgb(238 241 245)',
+  whiteSpace: 'nowrap',
+} as const;
+
+/** A cell holding a number, read down the column against its neighbours. */
+export const panelNumberCellStyle = {
+  ...panelCellStyle,
+  textAlign: 'right',
+} as const;
+
+/** What a value is, written small and quiet above it. */
+export const labelStyle = {
+  fontSize: 11,
+  fontWeight: 600,
+  textTransform: 'uppercase',
+  letterSpacing: '0.04em',
+  opacity: 0.6,
+} as const;
+
+/** A label with whatever acts on the value it names pushed to the far end. */
+export const labelRowStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 4,
+} as const;
+
+/** A row of capsules under such a label, wrapping when it runs out of width. */
+export const panelCapsulesStyle = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 4,
+  marginTop: 4,
+} as const;
+
+/**
+ * The same label written beside what it names rather than above it.
+ *
+ * A label costs a whole line of the panel where it stands on its own, and a
+ * choice of two or three capsules does not fill the line it is then given. Set
+ * beside them the label reads as the question the capsules answer, and two such
+ * questions fit in the height one used to take.
+ */
+export const inlineLabelStyle = {
+  ...labelStyle,
+  fontSize: 10,
+  flex: '0 0 auto',
+} as const;
+
+/** One inline label and the capsules that answer it, kept on one line. */
+export const panelCapsuleGroupStyle = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 4,
+} as const;
+
+/**
+ * Several such groups on one line, wrapping group by group.
+ *
+ * The wider gap between groups than within one is what keeps them legible as
+ * separate questions once they share a line: capsules four pixels apart belong
+ * to the label on their left, and the group after it starts a hand's width
+ * further along.
+ */
+export const panelCapsuleRowStyle = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: '4px 12px',
+} as const;
+
+/**
+ * A capsule sized for such a row.
+ *
+ * Blueprint's tag has no size below its medium one, so the smaller capsule is
+ * asked for here rather than through a prop. Written as a style so a capsule
+ * carrying a colour of its own can spread it over this one.
+ */
+export const smallCapsuleStyle = {
+  minHeight: 0,
+  minWidth: 0,
+  padding: '1px 5px',
+  fontSize: 10,
+  lineHeight: '14px',
+} as const;
+
+/** The name of one group of a list, with the room a group needs above it. */
+export const panelHeadingStyle = {
+  ...labelStyle,
+  padding: '6px 4px 2px',
+} as const;
+
+/** What a panel says instead of a list, when it has nothing to list. */
+export const panelEmptyStyle = {
+  padding: 8,
+  fontSize: 12,
+  opacity: 0.7,
+} as const;

package/src/panel/core/rowSpacers.ts

@@ -0,0 +1,50 @@
+/**
+ * The empty room a virtualised table leaves around the rows it actually drew.
+ *
+ * A table that draws twenty of five thousand rows must still be five thousand
+ * rows tall, or the scrollbar would say the list is a screenful long and the
+ * rows would jump under the thumb. Two empty rows carry that height — one above
+ * the drawn ones, one below — which keeps every cell in the column layout the
+ * browser computes for a real table, where absolutely positioning the rows
+ * would not.
+ */
+
+/** Where one drawn row sits in the list, in pixels from the top of it. */
+export interface RowPlacement {
+  /** Its top edge. */
+  start: number;
+  /** Its bottom edge. */
+  end: number;
+}
+
+/** The two empty rows standing in for everything that was not drawn. */
+export interface RowSpacers {
+  /** How tall the one above the drawn rows is, in pixels. */
+  before: number;
+  /** How tall the one below them is. */
+  after: number;
+}
+
+/**
+ * The height of the empty row above the drawn rows and of the one below.
+ *
+ * With nothing drawn — the first render, before the scroll region has been
+ * measured, and every render of an empty table — the whole list becomes the
+ * lower spacer. That is what gives the region a scrollbar of the right length
+ * on the render before it knows which rows are in view, instead of a table that
+ * measures nothing because it is showing nothing.
+ * @param drawn - The rows being drawn, in order.
+ * @param total - How tall the whole list is, in pixels.
+ * @returns The height of each spacer.
+ */
+export function rowSpacers(
+  drawn: readonly RowPlacement[],
+  total: number,
+): RowSpacers {
+  const first = drawn[0];
+  const last = drawn.at(-1);
+  if (first === undefined || last === undefined) {
+    return { before: 0, after: Math.max(0, total) };
+  }
+  return { before: first.start, after: Math.max(0, total - last.end) };
+}

package/src/panel/core/statusBar.ts

@@ -0,0 +1,48 @@
+/**
+ * The strip along the foot of an editor, which every one of them writes alike.
+ *
+ * A status bar says what is open and what is under the pointer, in one line of
+ * small type over a rule. The geometry is the same in every viewer — that is
+ * what makes it read as one application rather than three — so it lives here,
+ * and each viewer adds only the items it has to write and whatever colour one
+ * of them needs.
+ */
+
+/** The strip itself: one row, a rule above it, nothing wrapping. */
+export const statusBarStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 16,
+  padding: '4px 10px',
+  minHeight: 30,
+  borderTop: '1px solid rgb(217 223 230)',
+  fontSize: 13,
+  whiteSpace: 'nowrap',
+} as const;
+
+/** One thing the bar says, icon and text on one line. */
+export const statusItemStyle = {
+  display: 'inline-flex',
+  alignItems: 'center',
+} as const;
+
+/** An item that is context rather than an answer. */
+export const statusMutedStyle = { ...statusItemStyle, opacity: 0.6 } as const;
+
+/** What pushes the items after it to the far end of the bar. */
+export const statusSpacerStyle = { flex: 1 } as const;
+
+/**
+ * A count with the noun it counts, singular where it has to be.
+ * @param count - How many.
+ * @param singular - What one of them is called.
+ * @param plural - What several are called.
+ * @returns The phrase, e.g. `1 peak` or `412 peaks`.
+ */
+export function countLabel(
+  count: number,
+  singular: string,
+  plural: string,
+): string {
+  return `${count} ${count === 1 ? singular : plural}`;
+}

package/src/panel/core/textFilter.ts

@@ -0,0 +1,33 @@
+/**
+ * Read what the user typed into a filter box.
+ * @param filter - What was typed.
+ * @returns It trimmed and lowercased, which is what a match is made against.
+ * @example
+ * filterNeedle('  GlcNAc '); // 'glcnac'
+ */
+export function filterNeedle(filter: string): string {
+  return filter.trim().toLowerCase();
+}
+
+/**
+ * Whether any of the things an entry is known by carries what was typed.
+ *
+ * Every list the editor filters is filtered the same way — case-insensitively,
+ * on a substring, across the few fields an entry is recognised by — so a
+ * residue, a template and a symbol all answer to the same test.
+ * @param needle - The filter, already through `filterNeedle`.
+ * @param values - What the entry is known by; an absent one never matches.
+ * @returns Whether the entry is worth showing, always true for an empty filter.
+ * @example
+ * matchesNeedle('nac', 'GlcNAc', 'N-acetylglucosamine'); // true
+ */
+export function matchesNeedle(
+  needle: string,
+  ...values: ReadonlyArray<string | undefined>
+): boolean {
+  if (needle === '') return true;
+  for (const value of values) {
+    if (value?.toLowerCase().includes(needle)) return true;
+  }
+  return false;
+}

package/src/panel/core/yieldToPainting.ts

@@ -0,0 +1,20 @@
+/**
+ * Give the browser a turn, in the middle of work that would otherwise hold it.
+ *
+ * A long read that reports its progress reports it into a page that never gets
+ * to draw: awaiting a value already in hand queues a microtask, and the browser
+ * paints between tasks, not between microtasks. So a loop over a run held in
+ * memory can walk twenty-six million peaks announcing each percent and leave
+ * the screen showing the percent it was at when the loop began.
+ *
+ * `setTimeout` and not `requestAnimationFrame`, for two reasons: these packages
+ * are tested without a DOM, so work that only advanced inside a browser could
+ * not be tested at all; and a tab in the background stops painting frames
+ * altogether, which would stop a read its owner is waiting for.
+ * @returns When the browser has had its turn.
+ */
+export function yieldToPainting(): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+}

package/src/panel/ui/AboutDialogFrame.tsx

@@ -0,0 +1,100 @@
+/**
+ * The shape an editor's About dialog takes, so every viewer wears the same one.
+ *
+ * What differs between them is what they are and whose work they are built on;
+ * what does not is the frame — the mark beside the title, the mark again at
+ * full size beside a one-paragraph statement of what the editor does, then the
+ * sections crediting the parts, then a way out. A viewer hands over its words
+ * and its logo and writes none of that geometry itself.
+ */
+
+import { Button, Dialog, DialogBody, DialogFooter } from '@blueprintjs/core';
+import type { ReactNode } from 'react';
+
+import { useConfirmOnEnter } from './useConfirmOnEnter.ts';
+
+/** What an About dialog is given. */
+export interface AboutDialogFrameProps {
+  /** Whether the dialog is showing. */
+  isOpen: boolean;
+  /** Called when it is dismissed. */
+  onClose: () => void;
+  /** What the title bar reads. */
+  title: string;
+  /** The editor's mark, at title size. */
+  mark: ReactNode;
+  /** The same mark, at the size the header shows it. */
+  logo: ReactNode;
+  /** What the editor is called, beside the logo. */
+  name: string;
+  /** One paragraph on what it does. */
+  intro: ReactNode;
+  /** The sections under it: credits, licence, whatever else is owed. */
+  children: ReactNode;
+}
+
+/**
+ * Draw an About dialog around a viewer's own words.
+ * @param props - The words, the mark, and how the dialog is opened and closed.
+ * @returns The dialog.
+ */
+export function AboutDialogFrame(props: AboutDialogFrameProps): ReactNode {
+  const { isOpen, onClose, title, mark, logo, name, intro, children } = props;
+  useConfirmOnEnter(isOpen, onClose);
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      title={title}
+      icon={<span style={titleLogoStyle}>{mark}</span>}
+      style={dialogStyle}
+      onClose={onClose}
+    >
+      <DialogBody>
+        <div style={bodyStyle}>
+          <div style={headerStyle}>
+            <div style={logoStyle}>{logo}</div>
+            <div>
+              <div style={nameStyle}>{name}</div>
+              {intro}
+            </div>
+          </div>
+          {children}
+        </div>
+      </DialogBody>
+      <DialogFooter
+        actions={
+          <Button intent="primary" onClick={onClose}>
+            Close
+          </Button>
+        }
+      />
+    </Dialog>
+  );
+}
+
+const dialogStyle = { width: 480, maxWidth: '92vw' } as const;
+
+const bodyStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 16,
+} as const;
+
+const headerStyle = { display: 'flex', alignItems: 'center', gap: 16 } as const;
+
+/** A fixed size, not a share of the row: a flex item gives up its width first. */
+const logoStyle = { flexShrink: 0 } as const;
+
+/** The header spaces a Blueprint icon off the title; the mark is not one. */
+const titleLogoStyle = {
+  display: 'inline-flex',
+  flexShrink: 0,
+  marginRight: 10,
+} as const;
+
+const nameStyle = {
+  fontSize: 16,
+  fontWeight: 600,
+  marginBottom: 4,
+} as const;

package/src/panel/ui/ClearButton.tsx

@@ -0,0 +1,42 @@
+import { Button } from '@blueprintjs/core';
+
+export interface ClearButtonProps {
+  /**
+   * What emptying the box does, said as the thing it achieves rather than as
+   * "clear" — a screen reader and a hovering pointer both get this one line,
+   * and `Leave green out` says what `Clear` does not.
+   */
+  label: string;
+  /** Called when it is clicked, with the box left for the caller to empty. */
+  onClick: () => void;
+}
+
+/**
+ * The cross that empties a box, worn inside it as Blueprint's `rightElement`.
+ *
+ * Blueprint has no clearable input of its own; what it has is the slot, and a
+ * minimal cross button in it is the shape its own examples use. Which is why
+ * this carries no `size`: the input group sizes whatever is put in the slot
+ * from its own size class — 20 square inside a small box, 24 inside a medium
+ * one — so a button that stated a size of its own would only be able to
+ * disagree with the box it is in.
+ *
+ * One component rather than eight lines repeated at each box, because the
+ * cross has to be the same size, the same colour and in the same place
+ * everywhere or it reads as a different control each time.
+ * @param props - What clearing achieves, and what to do about it.
+ * @returns The button, for an `InputGroup`'s `rightElement`.
+ */
+export function ClearButton(props: ClearButtonProps) {
+  const { label, onClick } = props;
+
+  return (
+    <Button
+      variant="minimal"
+      icon="cross"
+      aria-label={label}
+      title={label}
+      onClick={onClick}
+    />
+  );
+}