react-cheminfo 0.28.0 → 0.29.0

package/src/panel/ui/useConfirmOnEnter.ts

@@ -0,0 +1,68 @@
+/**
+ * Enter as the answer to whatever a dialog is asking.
+ */
+
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+/**
+ * Run a dialog's primary action when Enter is pressed while it is open.
+ *
+ * On the document rather than on the dialog's own subtree, because an open
+ * overlay holds the focus on a container above the content, so a press never
+ * reaches a handler put on the body. Esc needs nothing of the sort: Blueprint
+ * closes an overlay on it already.
+ *
+ * A press that something else has a use for is left alone — a button under the
+ * focus is activated by Enter on its own, and a newline typed into a text area
+ * is a newline — so the shortcut never fires twice or eats what was typed.
+ * @param isOpen - Whether the dialog is showing.
+ * @param onConfirm - Its primary action, the one the footer button runs.
+ */
+export function useConfirmOnEnter(
+  isOpen: boolean,
+  onConfirm: () => void,
+): void {
+  // Held in a ref so a caller passing a fresh closure on every render does not
+  // have the listener taken down and put back up.
+  const current = useRef(onConfirm);
+  useLayoutEffect(() => {
+    current.current = onConfirm;
+  });
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key !== 'Enter' || event.defaultPrevented) return;
+      if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) {
+        return;
+      }
+      if (activatesOnEnter(event.target) || takesNewlines(event.target)) return;
+      event.preventDefault();
+      current.current();
+    }
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen]);
+}
+
+/**
+ * Whether Enter is already the way to work what the press was delivered to.
+ * @param target - What the event was delivered to.
+ * @returns Whether it runs itself on Enter.
+ */
+function activatesOnEnter(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return false;
+  return target.closest('a[href], button, summary, [role="button"]') !== null;
+}
+
+/**
+ * Whether the press is a newline being typed rather than an answer.
+ * @param target - What the event was delivered to.
+ * @returns Whether it should be left alone.
+ */
+function takesNewlines(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  return target.isContentEditable || target.tagName === 'TEXTAREA';
+}

package/src/panel/ui/useFilterBox.ts

@@ -0,0 +1,35 @@
+import { useState } from 'react';
+
+/** The filter box of a panel, and the toolbar item that reveals it. */
+export interface FilterBox {
+  /** What the user typed, empty while nothing is filtered out. */
+  filter: string;
+  /** Called with what the user typed. */
+  setFilter: (filter: string) => void;
+  /** Whether the box is showing. */
+  showFilter: boolean;
+  /** Reveals the box, or hides it and drops what was typed. */
+  toggleFilter: () => void;
+}
+
+/**
+ * A filter box that is out of the way until it is asked for.
+ *
+ * Closing it drops what was typed, because a box that is out of sight can no
+ * longer explain why half the list is missing — which is the one rule every
+ * panel offering a filter has to keep, so it is kept here rather than in each
+ * of them.
+ * @param defaultShowFilter - Whether the box is open to begin with.
+ * @returns The state of the box, and the toggle a toolbar item calls.
+ */
+export function useFilterBox(defaultShowFilter = false): FilterBox {
+  const [filter, setFilter] = useState('');
+  const [showFilter, setShowFilter] = useState(defaultShowFilter);
+
+  function toggleFilter() {
+    if (showFilter) setFilter('');
+    setShowFilter(!showFilter);
+  }
+
+  return { filter, setFilter, showFilter, toggleFilter };
+}

package/src/panel/ui/useVirtualRows.ts

@@ -0,0 +1,82 @@
+import { useVirtualizer } from '@tanstack/react-virtual';
+import type { RefObject } from 'react';
+
+import type { RowSpacers } from '../core/rowSpacers.ts';
+import { rowSpacers } from '../core/rowSpacers.ts';
+
+/** Which rows a scrolled table draws, and the empty room around them. */
+export interface VirtualRows extends RowSpacers {
+  /** The indices of the rows to draw, in the order they are listed. */
+  indices: number[];
+  /**
+   * What a drawn row reports its height through, as its `ref`. A row also has
+   * to carry `data-index`, which is how the measurement finds its way back to
+   * the row it was taken from.
+   *
+   * Any element, not a `<tr>`: a peak table's rows are table rows, while a
+   * fragment list's are `<div>`s carrying a drawing, and both are measured the
+   * same way.
+   */
+  measure: (node: HTMLElement | null) => void;
+}
+
+/**
+ * Draw only the rows the scroll region is showing, however long the list is.
+ *
+ * A peak table is a few hundred rows at rest and several thousand once the
+ * window is opened onto the whole spectrum, and every one of those rows is four
+ * cells the browser lays out, styles and keeps — a cost paid on the sort, on the
+ * filter, and on every zoom, for rows nobody is looking at. Drawing the twenty
+ * or so in view and standing two empty rows in for the rest makes that cost the
+ * size of the panel rather than the size of the spectrum.
+ *
+ * The rows are measured rather than assumed: a row is a line of text, so its
+ * height follows the font the page is rendered at and a hard-coded one would
+ * put the end of a five thousand row list several screens away from the bottom
+ * of the scrollbar. `estimatedRowHeight` is only what the list is worth before
+ * a single row has been drawn.
+ *
+ * The table header scrolls inside the same region and is not part of the list,
+ * so the rows really sit one header lower than this reckons. It is left that
+ * way deliberately: the overscan already draws more rows than are in view, on
+ * both sides, and it absorbs a header's worth of offset without the extra
+ * measurement — and without the render that measuring it would cost on the way
+ * to the same picture.
+ * @param scrollRef - The region the rows scroll in.
+ * @param count - How many rows the list holds.
+ * @param estimatedRowHeight - What one row is worth until one has been drawn.
+ * @returns The rows to draw and the spacers standing in for the others.
+ */
+export function useVirtualRows(
+  scrollRef: RefObject<HTMLDivElement | null>,
+  count: number,
+  estimatedRowHeight: number,
+): VirtualRows {
+  const virtualizer = useVirtualizer({
+    count,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => estimatedRowHeight,
+    overscan: OVERSCAN,
+  });
+
+  const drawn = virtualizer.getVirtualItems();
+  const indices = new Array<number>(drawn.length);
+  for (let position = 0; position < drawn.length; position++) {
+    indices[position] = (drawn[position] as { index: number }).index;
+  }
+
+  return {
+    indices,
+    ...rowSpacers(drawn, virtualizer.getTotalSize()),
+    measure: virtualizer.measureElement,
+  };
+}
+
+/**
+ * How many rows are drawn beyond each end of the region.
+ *
+ * Enough that a wheel gesture or a drag of the scrollbar never reaches the edge
+ * of what was drawn before the next render has run, and enough to cover the
+ * header the list is offset by.
+ */
+const OVERSCAN = 12;

package/src/panel/ui/useVirtualWindowRows.ts

@@ -0,0 +1,86 @@
+/**
+ * Drawing only the rows the page is showing, for a list that scrolls with it.
+ *
+ * `useVirtualRows` measures a scroll region of its own, which is what a panel
+ * beside a chart has. A table filling a tab has none: it flows down the document
+ * and the browser window is what scrolls it, so giving the list its own
+ * `overflow` would grow a second scrollbar inside the first and cap the table at
+ * whatever height it was handed — a layout change made to serve the virtualiser
+ * rather than the reader.
+ */
+
+import { useWindowVirtualizer } from '@tanstack/react-virtual';
+import { useCallback, useState } from 'react';
+
+import { rowSpacers } from '../core/rowSpacers.ts';
+
+import type { VirtualRows } from './useVirtualRows.ts';
+
+/** The rows to draw, and what the list reports its own position through. */
+export interface VirtualWindowRows extends VirtualRows {
+  /**
+   * What the element holding the rows reports its position through, as its
+   * `ref`. Without it every offset is reckoned from the top of the document and
+   * the wrong rows are drawn, by however tall whatever sits above the list is.
+   */
+  measureList: (node: HTMLElement | null) => void;
+}
+
+/**
+ * Draw only the rows the page is showing, however long the list is.
+ *
+ * The rows are measured against the window, so the list only has to say how far
+ * down the page it begins — which is what the virtualiser calls its scroll
+ * margin, and what `measureList` reports.
+ *
+ * That position is read in a ref callback rather than in an effect, which is
+ * how `useChartSize` reads a box for the same reason: the node is the only
+ * thing the measurement needs, so it is taken the moment React has one and
+ * taken again whenever it hands over another. A filter that cuts a thousand
+ * rows to fifty changes how tall the list is and not where it starts, so there
+ * is nothing to remeasure when the count moves.
+ * @param count - How many rows the list holds.
+ * @param estimatedRowHeight - What one row is worth until one has been drawn.
+ * @returns The rows to draw, the spacers standing in for the others, and the
+ * ref the list reports its position through.
+ */
+export function useVirtualWindowRows(
+  count: number,
+  estimatedRowHeight: number,
+): VirtualWindowRows {
+  const [scrollMargin, setScrollMargin] = useState(0);
+
+  const measureList = useCallback((node: HTMLElement | null) => {
+    if (node === null) return;
+    setScrollMargin(node.getBoundingClientRect().top + window.scrollY);
+  }, []);
+
+  const virtualizer = useWindowVirtualizer({
+    count,
+    estimateSize: () => estimatedRowHeight,
+    overscan: OVERSCAN,
+    scrollMargin,
+  });
+
+  const drawn = virtualizer.getVirtualItems();
+  const indices = new Array<number>(drawn.length);
+  for (let position = 0; position < drawn.length; position++) {
+    indices[position] = (drawn[position] as { index: number }).index;
+  }
+
+  return {
+    indices,
+    ...rowSpacers(drawn, virtualizer.getTotalSize()),
+    measure: virtualizer.measureElement,
+    measureList,
+  };
+}
+
+/**
+ * How many rows are drawn beyond each end of the window.
+ *
+ * The same reasoning as `useVirtualRows`, and the same number: enough that a
+ * wheel gesture never reaches the edge of what was drawn before the next render
+ * has run.
+ */
+const OVERSCAN = 12;

package/src/ui.ts

@@ -17,6 +17,7 @@ export * from './hooks/ui/index.ts';
 export * from './i18n/ui/index.ts';
 export * from './language/ui/index.ts';
 export * from './overlay/ui/index.ts';
+export * from './panel/ui/index.ts';
 export * from './parallel/ui/index.ts';
 export * from './pedagogy/ui/index.ts';
 export * from './periodic/ui/index.ts';