react-cheminfo 0.27.0 → 0.29.0

package/src/panel/ui/DocumentationDialogFrame.tsx

@@ -0,0 +1,86 @@
+/**
+ * The dialog an editor answers "how do I use this" in.
+ *
+ * Documentation that lives on a website is documentation nobody reads with a
+ * structure half drawn, so each viewer ships its own — but only the words are
+ * its own. The dialog, the width, the way the sections are stacked and the way
+ * out are the same in all of them, and are written here once.
+ */
+
+import { Button, Dialog, DialogBody, DialogFooter } from '@blueprintjs/core';
+import type { ReactNode } from 'react';
+
+import { Section } from './Section.tsx';
+import { useConfirmOnEnter } from './useConfirmOnEnter.ts';
+
+/** One part of what a viewer has to say about itself. */
+export interface DocumentationSection {
+  /** Stable key, so a section keeps its place as the list grows. */
+  id: string;
+  /** What the section is called. */
+  title: string;
+  /** What it says. */
+  body: ReactNode;
+}
+
+/** What the documentation dialog is given. */
+export interface DocumentationDialogFrameProps {
+  /** Whether the dialog is showing. */
+  isOpen: boolean;
+  /** Called when it is dismissed. */
+  onClose: () => void;
+  /** The sections, in reading order. */
+  sections: readonly DocumentationSection[];
+  /**
+   * What the title bar reads.
+   * @default 'Documentation'
+   */
+  title?: string;
+}
+
+/**
+ * Draw the documentation of one viewer.
+ * @param props - The sections and how the dialog is opened and closed.
+ * @returns The dialog.
+ */
+export function DocumentationDialogFrame(
+  props: DocumentationDialogFrameProps,
+): ReactNode {
+  const { isOpen, onClose, sections, title = 'Documentation' } = props;
+  useConfirmOnEnter(isOpen, onClose);
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      title={title}
+      icon="help"
+      style={dialogStyle}
+      onClose={onClose}
+    >
+      <DialogBody>
+        <div style={bodyStyle}>
+          {sections.map((section) => (
+            <Section key={section.id} title={section.title}>
+              {section.body}
+            </Section>
+          ))}
+        </div>
+      </DialogBody>
+      <DialogFooter
+        actions={
+          <Button intent="primary" onClick={onClose}>
+            Close
+          </Button>
+        }
+      />
+    </Dialog>
+  );
+}
+
+const dialogStyle = { width: 640, maxWidth: '92vw' } as const;
+
+const bodyStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 20,
+} as const;

package/src/panel/ui/FilterInput.tsx

@@ -0,0 +1,60 @@
+import { InputGroup } from '@blueprintjs/core';
+
+import { ClearButton } from './ClearButton.tsx';
+
+export interface FilterInputProps {
+  /** What the user typed. */
+  value: string;
+  /** Called with what the user typed, and with `''` when the cross is clicked. */
+  onValueChange: (value: string) => void;
+  /** What the box says while it is empty. */
+  placeholder: string;
+  /**
+   * Whether the box takes the caret as it appears, for the times it is revealed
+   * by a click on a toolbar item somewhere else.
+   * @default false
+   */
+  autoFocus?: boolean;
+}
+
+/**
+ * The box a list is filtered through, with a cross to empty it again.
+ *
+ * A filter left behind hides entries that are still there, and a peak table is
+ * exactly where that goes unnoticed — a spectrum with three peaks in it looks
+ * like a spectrum with three peaks in it. So every list that offers a filter
+ * also offers one click back to the whole of it rather than a held backspace.
+ *
+ * Every correction the browser offers is turned off: a formula, an m/z and a
+ * residue name are neither words nor sentences, and a mobile keyboard
+ * capitalising `mNa+` or autocorrecting `Hex` is how a query stops matching
+ * anything.
+ * @param props - Component props.
+ * @returns The box.
+ */
+export function FilterInput(props: FilterInputProps) {
+  const { value, onValueChange, placeholder, autoFocus = false } = props;
+
+  return (
+    <InputGroup
+      autoFocus={autoFocus}
+      leftIcon="search"
+      size="small"
+      value={value}
+      placeholder={placeholder}
+      spellCheck={false}
+      autoCapitalize="off"
+      autoCorrect="off"
+      autoComplete="off"
+      rightElement={
+        value.length > 0 ? (
+          <ClearButton
+            label="Clear the filter"
+            onClick={() => onValueChange('')}
+          />
+        ) : undefined
+      }
+      onValueChange={onValueChange}
+    />
+  );
+}

package/src/panel/ui/HelpLabel.tsx

@@ -0,0 +1,43 @@
+import type { HelpText } from '../../help/ui/HelpBody.tsx';
+import { HelpIcon } from '../../help/ui/HelpIcon.tsx';
+import { labelStyle } from '../core/panelStyles.ts';
+
+/** What the label names, and what its question mark answers. */
+export interface HelpLabelProps {
+  /** What the value is, written small and quiet above it. */
+  label: string;
+  /** The sentences the question mark carries, one string per paragraph. */
+  help: HelpText;
+}
+
+/**
+ * A panel label with a question mark beside it.
+ *
+ * The label is the half that has to be read at a glance — it names the field
+ * under it — so it stays plain, and everything that would otherwise be a
+ * paragraph of instructions under the control hangs off the glyph beside it.
+ *
+ * The help opens to the side rather than above, and that is not a preference:
+ * these glyphs sit in a panel beside the very thing they explain — a picture, a
+ * chart, a spectrum — and a tooltip placed over the top of a control covers the
+ * subject of its own first sentence.
+ * @param props - Component props.
+ * @returns The label row.
+ */
+export function HelpLabel(props: HelpLabelProps) {
+  const { label, help } = props;
+
+  return (
+    <div style={rowStyle}>
+      <span style={labelStyle}>{label}</span>
+      <HelpIcon
+        content={{ body: help }}
+        label={`What ${label} means`}
+        placement="left"
+        size={12}
+      />
+    </div>
+  );
+}
+
+const rowStyle = { display: 'flex', alignItems: 'center', gap: 4 } as const;

package/src/panel/ui/PanelMessage.tsx

@@ -0,0 +1,64 @@
+import type { IconName } from '@blueprintjs/core';
+import { Callout } from '@blueprintjs/core';
+import type { ReactNode } from 'react';
+
+import { panelEmptyStyle } from '../core/panelStyles.ts';
+
+/** What a panel says when it cannot show what it is for. */
+export type PanelMessageIntent = 'none' | 'warning' | 'danger';
+
+export interface PanelMessageProps {
+  /**
+   * How much is in the way: `danger` for something the editor refused,
+   * `warning` for something it could only do in part, `none` for a remark.
+   * @default 'warning'
+   */
+  intent?: PanelMessageIntent;
+  /**
+   * The icon, when the one the intent carries is not the one meant — a lookup
+   * that found nothing is a search that came back empty, not a warning.
+   * @default the icon of the intent
+   */
+  icon?: IconName;
+  /** What to say, in the terms the drawing is in. */
+  children: ReactNode;
+}
+
+/**
+ * Why a panel is showing this instead of what it is for.
+ *
+ * A refusal, a limitation and a remark are told apart by colour rather than by
+ * wording, and they are told apart the same way in every panel — which is what
+ * this is for: eight places said the same thing in three spellings before.
+ * @param props - Component props.
+ * @returns The callout.
+ */
+export function PanelMessage(props: PanelMessageProps) {
+  const { intent = 'warning', icon = INTENT_ICONS[intent], children } = props;
+
+  return (
+    <Callout intent={intent} compact icon={icon}>
+      {children}
+    </Callout>
+  );
+}
+
+export interface PanelEmptyProps {
+  /** What there is instead of the list, in a few words. */
+  children: ReactNode;
+}
+
+/**
+ * The quiet line a panel shows in place of a list it has nothing to fill.
+ * @param props - Component props.
+ * @returns The line.
+ */
+export function PanelEmpty(props: PanelEmptyProps) {
+  return <div style={panelEmptyStyle}>{props.children}</div>;
+}
+
+const INTENT_ICONS: Record<PanelMessageIntent, IconName> = {
+  none: 'info-sign',
+  warning: 'warning-sign',
+  danger: 'error',
+};

package/src/panel/ui/PanelRail.tsx

@@ -0,0 +1,64 @@
+/**
+ * The column of icons down the right edge, which opens and shuts the panels.
+ *
+ * Only the bar and its icons: each editor keeps the element it hangs the rail
+ * in, because where the rail sits — outside the split, so the icons stay against
+ * the edge while the panel beside them is resized — is a decision about that
+ * editor's layout rather than about the rail.
+ */
+
+import type { IconName, MaybeElement } from '@blueprintjs/core';
+import type { ReactNode } from 'react';
+import { ActivityBar } from 'react-science/ui';
+
+/**
+ * One panel the rail can open.
+ *
+ * Generic in its own id, because each editor names its panels in a union of its
+ * own and hands the rail the very function that opens them — a rail that took
+ * plain strings would refuse every one of those functions.
+ */
+export interface RailPanel<TId extends string = string> {
+  /** Which panel, matching what the editor's state calls it. */
+  id: TId;
+  /** The Blueprint icon it is known by. */
+  icon: IconName | MaybeElement;
+  /** What the tooltip reads. */
+  title: string;
+}
+
+/** What the rail is given. */
+export interface PanelRailProps<TId extends string = string> {
+  /** The panels offered, in the order they are shown. */
+  panels: ReadonlyArray<RailPanel<TId>>;
+  /** Which of them are open. */
+  openIds: readonly string[];
+  /** Called with the panel an icon was clicked for. */
+  onToggle: (id: TId) => void;
+}
+
+/**
+ * Draw the rail.
+ * @param props - The panels, which are open, and what to do about a click.
+ * @returns The rail.
+ */
+export function PanelRail<TId extends string>(
+  props: PanelRailProps<TId>,
+): ReactNode {
+  const { panels, openIds, onToggle } = props;
+
+  return (
+    <ActivityBar>
+      {panels.map((panel) => (
+        <ActivityBar.Item
+          key={panel.id}
+          id={panel.id}
+          icon={panel.icon}
+          tooltip={panel.title}
+          active={openIds.includes(panel.id)}
+          onClick={() => onToggle(panel.id)}
+        />
+      ))}
+    </ActivityBar>
+  );
+}

package/src/panel/ui/Section.tsx

@@ -0,0 +1,66 @@
+import type { ReactNode } from 'react';
+
+export interface SectionProps {
+  /** What the block is about, written above it. */
+  title: string;
+  /** The block. */
+  children: ReactNode;
+}
+
+/**
+ * One titled block of a dialog.
+ * @param props - Component props.
+ * @returns The section.
+ */
+export function Section(props: SectionProps) {
+  const { title, children } = props;
+  return (
+    <div style={sectionStyle}>
+      <div style={sectionTitleStyle}>{title}</div>
+      {children}
+    </div>
+  );
+}
+
+export interface LinkProps {
+  href: string;
+  children: ReactNode;
+}
+
+/**
+ * A link out of a dialog, opened away from the editor so a drawing in progress
+ * or a spectrum being read is never lost to a click.
+ * @param props - Component props.
+ * @returns The link.
+ */
+export function Link(props: LinkProps) {
+  const { href, children } = props;
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer" style={linkStyle}>
+      {children}
+    </a>
+  );
+}
+
+const sectionStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+} as const;
+
+const sectionTitleStyle = {
+  fontSize: 11,
+  fontWeight: 600,
+  textTransform: 'uppercase',
+  letterSpacing: '0.04em',
+  opacity: 0.6,
+} as const;
+
+// Spelled out rather than left to the page: nothing says a host application
+// styles its anchors, and a credit nobody can tell is a link is not a credit.
+const linkStyle = {
+  // The site's own accent, and the inherited ink on a page that declares none —
+  // the underline is what makes it a link either way.
+  color: 'var(--accent, inherit)',
+  textDecoration: 'underline',
+} as const;

package/src/panel/ui/SidePanelStack.tsx

@@ -0,0 +1,109 @@
+import type { ReactNode } from 'react';
+import type { ActivityBarItemProps } from 'react-science/ui';
+import { Accordion, AccordionProvider, Button } from 'react-science/ui';
+
+/** What a rail reads about one panel, wherever that rail is drawn. */
+export interface PanelDescriptor {
+  /** Identity, as the activity bar and the list of open panels address it. */
+  id: string;
+  /** What the header says, and what the icon's tooltip reads. */
+  title: string;
+  /** The icon stacked in the rail. */
+  icon: ActivityBarItemProps['icon'];
+}
+
+export interface SidePanelStackProps<TPanel extends PanelDescriptor> {
+  /** Every panel on offer, in the order their icons are stacked. */
+  panels: readonly TPanel[];
+  /** Which of them are open, named as each editor's own view names them. */
+  openPanelIds: readonly string[];
+  /**
+   * Called with the panel whose close cross was pressed. It is the id of one of
+   * `panels` rather than any string, so an editor whose panels are a fixed set
+   * hands its own `togglePanel` straight in.
+   * @param id - Identity of that panel.
+   */
+  onClose: (id: TPanel['id']) => void;
+  /**
+   * What to draw inside one panel.
+   * @param panel - The panel to draw.
+   * @returns Its body.
+   */
+  children: (panel: TPanel) => ReactNode;
+}
+
+/**
+ * The panels that are open, stacked one under the other down the side.
+ *
+ * Every open panel gets a share of the height rather than a turn: the things
+ * they hold are read together — which spectrum is selected and what its peaks
+ * are, the residues to pick from and what the drawing adds up to — so closing
+ * one to see the other would be a step backwards. A header click still folds a
+ * single panel away, and shift-click folds every other one.
+ *
+ * They are drawn in the order the rail stacks their icons rather than the order
+ * they were switched on, so a panel always comes back where it was.
+ *
+ * The header carries the shell's own two gestures and nothing about what the
+ * panel holds: the chevron that folds it away and the cross that closes it.
+ * What a panel switches on and off is a toolbar at the top of its own body, so
+ * it travels with the panel when it is folded, reordered or lent to another
+ * editor, and every header in every editor reads the same — which is the reason
+ * this is one component rather than one per editor.
+ *
+ * The chevron is there because nothing else says which panels are folded. The
+ * accordion draws every header identically and hides only the body, so a side
+ * of four closed panels and a side of four open ones differ by white space, and
+ * a reader looking for a panel that is already open reaches for its icon and
+ * closes it. It is a real button rather than a glyph because the header's own
+ * click never reaches the toolbar — clicks there are stopped so the close cross
+ * does not also fold the panel — so a chevron that did nothing when pressed
+ * would be an affordance that lies.
+ * @param props - Component props.
+ * @returns The stack.
+ */
+export function SidePanelStack<TPanel extends PanelDescriptor>(
+  props: SidePanelStackProps<TPanel>,
+) {
+  const { panels, openPanelIds, onClose, children } = props;
+  const open = panels.filter((panel) => openPanelIds.includes(panel.id));
+
+  return (
+    <AccordionProvider>
+      <Accordion>
+        {open.map((panel) => (
+          <Accordion.Item
+            key={panel.id}
+            id={panel.id}
+            title={panel.title}
+            defaultOpen
+            renderToolbar={({ isOpen, controls }) => (
+              <>
+                <Button
+                  variant="minimal"
+                  icon={isOpen ? 'chevron-down' : 'chevron-right'}
+                  data-panel-open={isOpen}
+                  aria-expanded={isOpen}
+                  aria-label={`${isOpen ? 'Fold' : 'Unfold'} the ${panel.title.toLowerCase()} panel`}
+                  tooltipProps={{
+                    content: isOpen ? 'Fold this panel away' : 'Unfold it',
+                  }}
+                  onClick={() => controls.toggle()}
+                />
+                <Button
+                  variant="minimal"
+                  icon="cross"
+                  tooltipProps={{ content: 'Close this panel' }}
+                  aria-label={`Close the ${panel.title.toLowerCase()} panel`}
+                  onClick={() => onClose(panel.id)}
+                />
+              </>
+            )}
+          >
+            {children(panel)}
+          </Accordion.Item>
+        ))}
+      </Accordion>
+    </AccordionProvider>
+  );
+}

package/src/panel/ui/SpectrumColorSwatch.tsx

@@ -0,0 +1,119 @@
+import { PopoverNext } from '@blueprintjs/core';
+import { useState } from 'react';
+
+import {
+  EXTRA_SPECTRUM_COLORS,
+  SPECTRUM_COLORS,
+} from '../../chart/core/spectrumColor.ts';
+
+export interface SpectrumColorSwatchProps {
+  /** The colour the spectrum is drawn in. */
+  color: string;
+  /** What the list calls it, for the labels a screen reader reads out. */
+  name: string;
+  /** Called with the colour that was picked. */
+  onPick: (color: string) => void;
+}
+
+/**
+ * The chip that says what colour a spectrum is drawn in, and changes it.
+ *
+ * The palette is what `spectrumColor.ts` holds and nothing else: a free colour
+ * picker would let two spectra be set to the same blue, or to a hue that
+ * disappears against the chart, and telling the traces apart is the whole job
+ * the colour has.
+ *
+ * Its two tiers are drawn as two rows, in that order and unlabelled. A row is
+ * enough: the top one is what the chart uses by itself, so a reader who never
+ * looks below it is already right, and one who does is choosing deliberately —
+ * which is the only way a colour that asks more of its reader's eyes should
+ * ever be picked. A legend explaining the difference would be read once and be
+ * in the way afterwards; `spectrumColor.ts` is where the difference is written
+ * down.
+ *
+ * One component for every viewer rather than one per package: a swatch that
+ * opens a picker in the mass panel and walks the palette in the infrared one is
+ * two different controls wearing the same chip, and whichever a reader learned
+ * first is the wrong one in the other editor.
+ * @param props - Component props.
+ * @returns The chip.
+ */
+export function SpectrumColorSwatch(props: SpectrumColorSwatchProps) {
+  const { color, name, onPick } = props;
+  const [isOpen, setIsOpen] = useState(false);
+
+  function offer(offered: string) {
+    return (
+      <button
+        key={offered}
+        type="button"
+        title={offered}
+        aria-label={`Draw ${name} in ${offered}`}
+        style={{
+          ...(offered === color ? activeSwatchStyle : swatchStyle),
+          background: offered,
+        }}
+        onClick={() => {
+          onPick(offered);
+          setIsOpen(false);
+        }}
+      />
+    );
+  }
+
+  return (
+    <PopoverNext
+      // A handful of chips need no arrow pointing back at a chip of the same
+      // size.
+      arrow={false}
+      isOpen={isOpen}
+      placement="bottom-start"
+      onInteraction={setIsOpen}
+      content={
+        <div style={paletteStyle}>
+          <div style={paletteRowStyle}>{SPECTRUM_COLORS.map(offer)}</div>
+          <div style={paletteRowStyle}>{EXTRA_SPECTRUM_COLORS.map(offer)}</div>
+        </div>
+      }
+    >
+      <button
+        type="button"
+        title="Draw this spectrum in another colour"
+        aria-label={`Colour of ${name}`}
+        style={{ ...swatchStyle, background: color }}
+      />
+    </PopoverNext>
+  );
+}
+
+/**
+ * A round chip rather than a square one: it is the mark the chart's own
+ * tooltip uses for a series, so the row and the chart name the same spectrum
+ * the same way.
+ */
+const swatchStyle = {
+  flex: 'none',
+  width: 14,
+  height: 14,
+  padding: 0,
+  borderRadius: '50%',
+  border: '1px solid rgba(17, 20, 24, 0.2)',
+  cursor: 'pointer',
+} as const;
+
+const activeSwatchStyle = {
+  ...swatchStyle,
+  border: '2px solid rgb(17 20 24)',
+} as const;
+
+const paletteStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  padding: 8,
+} as const;
+
+const paletteRowStyle = {
+  display: 'flex',
+  gap: 6,
+} as const;

package/src/panel/ui/index.ts

@@ -0,0 +1,47 @@
+/**
+ * The parts an editor is assembled from: its panels, its dialogs and the rail
+ * they are opened from.
+ *
+ * Every one of them is handed what it shows and reports what was pressed, so
+ * none of them reads a store and none of them knows which editor it is in.
+ * That is what lets the same panel stack carry a spectrum, a chromatogram and
+ * a drawing.
+ */
+
+export type { AboutDialogFrameProps } from './AboutDialogFrame.tsx';
+export { AboutDialogFrame } from './AboutDialogFrame.tsx';
+export type { ClearButtonProps } from './ClearButton.tsx';
+export { ClearButton } from './ClearButton.tsx';
+export type {
+  DocumentationDialogFrameProps,
+  DocumentationSection,
+} from './DocumentationDialogFrame.tsx';
+export { DocumentationDialogFrame } from './DocumentationDialogFrame.tsx';
+export type { FilterInputProps } from './FilterInput.tsx';
+export { FilterInput } from './FilterInput.tsx';
+export type { HelpLabelProps } from './HelpLabel.tsx';
+export { HelpLabel } from './HelpLabel.tsx';
+export type {
+  PanelEmptyProps,
+  PanelMessageIntent,
+  PanelMessageProps,
+} from './PanelMessage.tsx';
+export { PanelEmpty, PanelMessage } from './PanelMessage.tsx';
+export type { PanelRailProps, RailPanel } from './PanelRail.tsx';
+export { PanelRail } from './PanelRail.tsx';
+export type { LinkProps, SectionProps } from './Section.tsx';
+export { Link, Section } from './Section.tsx';
+export type {
+  PanelDescriptor,
+  SidePanelStackProps,
+} from './SidePanelStack.tsx';
+export { SidePanelStack } from './SidePanelStack.tsx';
+export type { SpectrumColorSwatchProps } from './SpectrumColorSwatch.tsx';
+export { SpectrumColorSwatch } from './SpectrumColorSwatch.tsx';
+export { useConfirmOnEnter } from './useConfirmOnEnter.ts';
+export type { FilterBox } from './useFilterBox.ts';
+export { useFilterBox } from './useFilterBox.ts';
+export type { VirtualRows } from './useVirtualRows.ts';
+export { useVirtualRows } from './useVirtualRows.ts';
+export type { VirtualWindowRows } from './useVirtualWindowRows.ts';
+export { useVirtualWindowRows } from './useVirtualWindowRows.ts';