react-cheminfo 0.11.0 → 0.13.0

package/src/scatter3d/ui/scatterCloudProps.ts

@@ -1,27 +1,22 @@
 /**
  * What a caller hands a `ScatterCloud`.
  *
- * The types live beside the component rather than inside it because the
- * component's own file would otherwise be mostly prose, exactly as the flat
- * scatter's are.
+ * What the cloud shares with the flat map — groups, labels, selection, hover
+ * and double click — is declared once in `scatterFigureProps.ts`; this adds
+ * the three axes, the shells, and the camera only a box has.
  */
 
-import type { ReactNode } from 'react';
-
 import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
-import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
 import type {
-  ScatterGroup,
-  ScatterPointOpen,
-} from '../../scatter/ui/scatterPlotProps.ts';
-import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
+  ScatterGroupProps,
+  ScatterInteractionProps,
+} from '../../scatter/ui/scatterFigureProps.ts';
 import type { CloudGesture } from '../core/cloudGesture.ts';
 import type { OrbitCamera } from '../core/orbitCamera.ts';
 
-export type { CloudGesture } from '../core/cloudGesture.ts';
-
 /** What a `ScatterCloud` needs. */
-export interface ScatterCloudProps {
+export interface ScatterCloudProps
+  extends ScatterGroupProps, ScatterInteractionProps {
   /** Where every sample sits along the axis that runs left to right, in data units. */
   x: ArrayLike<number>;
   /** Along the axis that runs bottom to top, in the same order. */
@@ -38,23 +33,6 @@ export interface ScatterCloudProps {
   yLabel: string;
   /** What the axis running away from the reader is called. */
   zLabel: string;
-  /**
-   * Which group each sample belongs to, as an index into `groups`. A sample
-   * with `-1`, or an index outside the range, is drawn in the muted ink and
-   * left out of every shell.
-   * @default undefined — every sample is one crowd
-   */
-  groupOf?: ArrayLike<number>;
-  /**
-   * The groups, in the order they are coloured and listed.
-   * @default undefined
-   */
-  groups?: readonly ScatterGroup[];
-  /**
-   * Which groups are drawn faint, by id — what a legend entry switches.
-   * @default undefined — every group is drawn in full
-   */
-  mutedGroups?: ReadonlySet<string>;
   /**
    * How large the group shells are, or `null` for none. A share is read in
    * three dimensions here, so the same share gives a wider shell than the same
@@ -70,35 +48,10 @@ export interface ScatterCloudProps {
    */
   ellipsoidMinimumPoints?: number;
   /**
-   * How solid the glass is; `0` draws no shells at all.
-   * @default SHELL_FILL_OPACITY
+   * How solid one wall of the glass is; `0` draws no shells at all.
+   * @default 0.1
    */
   ellipsoidFillOpacity?: number;
-  /**
-   * Whether each group's name is written once, over the middle of its own
-   * shell. It needs `groups`, since it is their names it writes.
-   * @default false
-   */
-  showGroupLabels?: boolean;
-  /**
-   * What each sample is called, written beside its own dot. A sample whose
-   * entry is `undefined` is left unnamed.
-   * @default undefined — no sample is named
-   */
-  pointLabels?: ReadonlyArray<string | undefined>;
-  /**
-   * Radius of a dot at the middle of the box, in pixels. One at the front is
-   * drawn larger and one at the back smaller, about this.
-   * @default 3.5
-   */
-  pointRadius?: number;
-  /**
-   * The index from which samples are drawn as outlines rather than filled,
-   * which is how one the model was fitted on is told from one placed into it
-   * afterwards.
-   * @default undefined — every sample is filled
-   */
-  outlinedFrom?: number;
   /**
    * What a drag does. The cloud never changes it on its own, because the
    * control belongs in the bar above the figure rather than on top of the
@@ -135,57 +88,4 @@ export interface ScatterCloudProps {
    * @default true
    */
   wheelZoom?: boolean;
-  /**
-   * The selected rows. Present, the caller owns the selection.
-   * @default undefined — the cloud keeps its own
-   */
-  selected?: readonly number[];
-  /**
-   * The rows selected before the reader touches anything.
-   * @default undefined
-   */
-  defaultSelected?: readonly number[];
-  /**
-   * Called when a lasso is released or a dot is tapped — never while a lasso
-   * is being drawn, and never while the box is being turned.
-   * @default undefined
-   */
-  onSelectionChange?: (change: SelectionChange) => void;
-  /**
-   * What a gesture with no modifier held does to the selection. Shift always
-   * adds and Alt always removes, exactly as on the map.
-   * @default 'replace'
-   */
-  selectMode?: ScatterSelectionMode;
-  /**
-   * Called with the row under the pointer, or `-1`.
-   * @default undefined
-   */
-  onHoverChange?: (index: number) => void;
-  /**
-   * Called when the reader double-clicks a sample, exactly as on the flat map:
-   * the gesture for "tell me more about this one", or "let me change it".
-   *
-   * It fires whichever gesture a drag is set to, because a double click is not
-   * a drag — a reader turning the box must not have to switch to Select to
-   * open a sample. The sample is selected first, since a double click is also
-   * two clicks; the map says why, and the two behave alike on purpose.
-   * @default undefined
-   */
-  onPointDoubleClick?: (point: ScatterPointOpen) => void;
-  /**
-   * What floats over the figure — a bar, a key, a caption, a card.
-   * @default undefined
-   */
-  overlay?: ReactNode;
-  /**
-   * What a screen reader is told the figure shows.
-   * @default a sentence built from the three axis names and the sample count
-   */
-  label?: string;
-  /**
-   * Value of the `data-testid` attribute of the wrapper.
-   * @default undefined
-   */
-  testId?: string;
 }

package/src/scatter3d/ui/useOrbitDrag.ts

@@ -1,18 +1,26 @@
 import type { PointerEvent as ReactPointerEvent } from 'react';
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
 
 import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
 import type { ScatterSurfaceProps } from '../../scatter/ui/lassoGesture.ts';
 import {
-  capturePointer,
-  dropFrame,
   modifierMode,
-  scheduleFrame,
   surfacePosition,
 } from '../../scatter/ui/lassoGesture.ts';
+import { useCapturedPointer } from '../../scatter/ui/useCapturedPointer.ts';
 import type { OrbitCamera } from '../core/orbitCamera.ts';
 import { orbitByDrag } from '../core/orbitCamera.ts';
 
+import type { OrbitDragTrack } from './orbitDragTrack.ts';
+import {
+  createOrbitDragTrack,
+  followOrbitDrag,
+  hoverOrbitDrag,
+  isOrbitTap,
+  pressOrbitDrag,
+  takePendingTurn,
+} from './orbitDragTrack.ts';
+
 /** What {@link useOrbitDrag} needs. */
 export interface OrbitDragOptions {
   /**
@@ -58,15 +66,15 @@ export interface OrbitDrag {
 /**
  * Turning the box with the pointer.
  *
- * It is the lasso's twin and is built the same way — the pointer is captured
- * on the way down so a drag that wanders off the figure keeps turning it, all
- * three ways a capture can end lead to one function, and moves are coalesced
- * to one a frame because a pointer emits many per frame and each one that
- * reaches the caller repaints every dot and every face.
+ * It is the lasso's twin and stands on the same `useCapturedPointer`, so a
+ * drag that wanders off the figure keeps turning it and every way a capture
+ * can end leads to one place. A finger is always claimed: a box whose one
+ * gesture is turning cannot be turned on a phone that scrolls instead.
  *
  * A press that goes nowhere is a tap rather than a turn of no degrees, because
  * nobody presses a mouse button without moving it a pixel or two and a reader
  * who meant to pick a sample must not have to hold their hand still to do it.
+ * The arithmetic of that decision is in `orbitDragTrack`.
  * @param options - See {@link OrbitDragOptions}.
  * @returns The drag. See {@link OrbitDrag}.
  */
@@ -80,141 +88,71 @@ export function useOrbitDrag(options: OrbitDragOptions): OrbitDrag {
     mode: restingMode = 'replace',
   } = options;
 
-  const pointerRef = useRef<number | null>(null);
-  const lastRef = useRef({ x: 0, y: 0 });
-  const travelRef = useRef(0);
-  const frameRef = useRef<number | null>(null);
-  const pendingRef = useRef<PendingTurn | null>(null);
+  const trackRef = useRef<OrbitDragTrack>(createOrbitDragTrack());
   const [turning, setTurning] = useState(false);
 
-  const flush = useCallback(() => {
-    frameRef.current = null;
-    const next = pendingRef.current;
-    pendingRef.current = null;
-    if (next === null) return;
-    if (pointerRef.current === null) {
-      onMove?.(next.x, next.y);
-      return;
-    }
-    onOrbit((camera) => orbitByDrag(camera, next.dx, next.dy));
-  }, [onMove, onOrbit]);
-
-  const end = useCallback(
-    (event: ReactPointerEvent<Element>, commit: boolean) => {
-      if (event.pointerId !== pointerRef.current) return;
-      pointerRef.current = null;
-      pendingRef.current = null;
-      dropFrame(frameRef);
-      setTurning(false);
-      if (!commit || travelRef.current > TAP_SLACK) return;
-      const at = surfacePosition(event, 0, 0);
-      onTap?.(at.x, at.y, modifierMode(event, restingMode));
-    },
-    [onTap, restingMode],
-  );
-
-  const handleDown = useCallback((event: ReactPointerEvent<Element>) => {
-    if (pointerRef.current !== null || event.button > 0) return;
-    pointerRef.current = event.pointerId;
-    lastRef.current = { x: event.clientX, y: event.clientY };
-    travelRef.current = 0;
+  const press = useCallback((event: ReactPointerEvent<Element>) => {
+    pressOrbitDrag(trackRef.current, event.clientX, event.clientY);
     setTurning(true);
-    capturePointer(event);
+    return true;
   }, []);
 
-  const handleMove = useCallback(
-    (event: ReactPointerEvent<Element>) => {
-      const active = pointerRef.current;
-      if (active === null) {
+  const follow = useCallback(
+    (event: ReactPointerEvent<Element>, claimed: boolean) => {
+      if (!claimed) {
         const at = surfacePosition(event, 0, 0);
-        pendingRef.current = { x: at.x, y: at.y, dx: 0, dy: 0 };
-        scheduleFrame(frameRef, flush);
-        return;
+        hoverOrbitDrag(trackRef.current, at.x, at.y);
+        return true;
       }
-      if (event.pointerId !== active) return;
-      const last = lastRef.current;
-      const dx = event.clientX - last.x;
-      const dy = event.clientY - last.y;
-      lastRef.current = { x: event.clientX, y: event.clientY };
-      travelRef.current += Math.abs(dx) + Math.abs(dy);
-      if (!enabled) return;
-      const waiting = pendingRef.current;
-      pendingRef.current = {
-        x: 0,
-        y: 0,
-        dx: (waiting?.dx ?? 0) + dx,
-        dy: (waiting?.dy ?? 0) + dy,
-      };
-      scheduleFrame(frameRef, flush);
+      return followOrbitDrag(
+        trackRef.current,
+        event.clientX,
+        event.clientY,
+        enabled,
+      );
     },
-    [enabled, flush],
+    [enabled],
   );
 
-  const handleUp = useCallback(
-    (event: ReactPointerEvent<Element>) => {
-      end(event, true);
+  const flush = useCallback(
+    (claimed: boolean) => {
+      const next = takePendingTurn(trackRef.current);
+      if (next === null) return;
+      if (!claimed) {
+        onMove?.(next.x, next.y);
+        return;
+      }
+      onOrbit((camera) => orbitByDrag(camera, next.dx, next.dy));
     },
-    [end],
+    [onMove, onOrbit],
   );
 
-  const handleAbandon = useCallback(
-    (event: ReactPointerEvent<Element>) => {
-      end(event, false);
+  const finish = useCallback(
+    (event: ReactPointerEvent<Element> | null, commit: boolean) => {
+      const track = trackRef.current;
+      takePendingTurn(track);
+      setTurning(false);
+      if (event === null || !commit || !isOrbitTap(track)) return;
+      const at = surfacePosition(event, 0, 0);
+      onTap?.(at.x, at.y, modifierMode(event, restingMode));
     },
-    [end],
+    [onTap, restingMode],
   );
 
-  const handleLeave = useCallback(() => {
-    if (pointerRef.current !== null) return;
-    pendingRef.current = null;
+  const forget = useCallback(() => {
+    takePendingTurn(trackRef.current);
     onLeave?.();
   }, [onLeave]);
 
-  const surface = useMemo<ScatterSurfaceProps>(
-    () => ({
-      onPointerDown: handleDown,
-      onPointerMove: handleMove,
-      onPointerUp: handleUp,
-      onPointerCancel: handleAbandon,
-      onLostPointerCapture: handleAbandon,
-      onPointerLeave: handleLeave,
-      style: {
-        cursor: enabled ? (turning ? 'grabbing' : 'grab') : 'default',
-        touchAction: 'none',
-      },
-    }),
-    [
-      enabled,
-      handleAbandon,
-      handleDown,
-      handleLeave,
-      handleMove,
-      handleUp,
-      turning,
-    ],
-  );
+  const { surface } = useCapturedPointer({
+    touch: true,
+    cursor: enabled ? (turning ? 'grabbing' : 'grab') : 'default',
+    onPress: press,
+    onMove: follow,
+    onFrame: flush,
+    onRelease: finish,
+    onLeave: forget,
+  });
 
   return { turning, surface };
 }
-
-/**
- * How far a press may travel and still be a tap, in pixels of total travel.
- *
- * Generous on purpose: a mouse moves a pixel or two under the click of its own
- * button, and a finger moves rather more, so a stricter number turns "pick
- * this sample" into "turn the box by nothing at all" for anybody whose hand is
- * not steady.
- */
-const TAP_SLACK = 5;
-
-/** What the pointer has done since the last frame, waiting for the next. */
-interface PendingTurn {
-  /** Where it is, for a move that is not turning anything. */
-  x: number;
-  /** Where it is. */
-  y: number;
-  /** How far it has moved across since the last frame. */
-  dx: number;
-  /** How far it has moved down. */
-  dy: number;
-}

package/src/seo/core/documentMeta.ts

@@ -1,3 +1,5 @@
+import { withoutQueryOrFragment } from '../../router/core/address.ts';
+
 /**
  * Keep the head in step with the page on screen after an in-app move.
  *
@@ -35,7 +37,7 @@ export function documentTitle(title: string): void {
  */
 export function canonicalLink(href: string): void {
   if (typeof document === 'undefined') return;
-  const address = withoutQuery(href);
+  const address = withoutQueryOrFragment(href);
   if (address === '') return;
 
   const existing = document.querySelector<HTMLLinkElement>(
@@ -85,8 +87,3 @@ function metaDescription(content: string): void {
   document.head.append(meta);
   meta.content = content;
 }
-
-function withoutQuery(href: string): string {
-  const cut = href.search(/[?#]/);
-  return cut === -1 ? href : href.slice(0, cut);
-}

package/src/seo/core/index.ts

@@ -1,9 +1,5 @@
 export type { DocumentMeta } from './documentMeta.ts';
-export {
-  canonicalLink,
-  documentTitle,
-  writeDocumentMeta,
-} from './documentMeta.ts';
+export { writeDocumentMeta } from './documentMeta.ts';
 export type {
   NoscriptEcosystem,
   NoscriptHrefs,
@@ -14,16 +10,12 @@ export type {
 export { noscriptIndex } from './noscript.ts';
 export type { PageMetaOptions } from './pageMeta.ts';
 export { injectPageMeta, pageDocumentMeta, pageHeadTags } from './pageMeta.ts';
+export type { PlainDescriptionOptions } from './plainDescription.ts';
+export { plainDescription, plainProse } from './plainDescription.ts';
 export type { RobotsDisallow } from './robots.ts';
 export { robotsTxt } from './robots.ts';
 export type { RouteMeta } from './routes.ts';
-export {
-  assertRoutes,
-  homeRoute,
-  pageMetaFor,
-  routeFor,
-  trimTrailingSlash,
-} from './routes.ts';
+export { assertRoutes, homeRoute, pageMetaFor, routeFor } from './routes.ts';
 export type { SiteFilesOptions } from './siteFiles.ts';
 export { sitemapXml } from './siteFiles.ts';
 export type { StartDocumentMetaOptions } from './startDocumentMeta.ts';
@@ -31,3 +23,4 @@ export { startDocumentMeta } from './startDocumentMeta.ts';
 export type { StructuredDataOptions } from './structuredData.ts';
 export { structuredDataScript } from './structuredData.ts';
 export { PAGE_BODY_MARKER, PAGE_HEAD_MARKER, fill } from './template.ts';
+export { injectTrackingScript } from './trackingScript.ts';

package/src/seo/core/noscript.ts

@@ -189,7 +189,9 @@ ${items.join('\n')}
   </ul>`;
 }
 
-function familySites(sites: readonly SiteId[] | undefined): EcosystemSite[] {
-  if (sites === undefined) return [...ECOSYSTEM_SITES];
+function familySites(
+  sites: readonly SiteId[] | undefined,
+): readonly EcosystemSite[] {
+  if (sites === undefined) return ECOSYSTEM_SITES;
   return sites.map((id) => siteById(id));
 }

package/src/seo/core/plainDescription.ts

@@ -0,0 +1,107 @@
+import type { InlineSegment } from '../../pedagogy/core/inlineMarks.ts';
+import { parseInlineMarks } from '../../pedagogy/core/inlineMarks.ts';
+
+/** The room a search result gives a description. */
+export interface PlainDescriptionOptions {
+  /**
+   * The longest description, ellipsis included: longer is a sentence cut off
+   * in the result itself.
+   * @default 160
+   */
+  maxLength?: number;
+  /**
+   * The shortest description whole sentences may stop at: shorter is a snippet
+   * half used, so the prose carries on, cut on a word.
+   * @default 110
+   */
+  minLength?: number;
+}
+
+/**
+ * Fit a page's authored prose into the description of its route.
+ *
+ * The markup is resolved first — a `[[term]]` or `[[term|text]]` marker to the
+ * words it shows, a code span to its text, strong and emphasis to their words —
+ * and the whitespace collapsed. Prose that fits is kept whole. Otherwise as many
+ * whole sentences as fit are kept, and when they fall short of `minLength` the
+ * prose is cut on a word instead, without ending on a comma or a joining word.
+ * A dot followed by no space — `C(=O)O`, `\ce{...}` — ends no sentence.
+ * @param prose - The page's own prose, markup and all.
+ * @param options - The room the description has.
+ * @returns The description.
+ */
+export function plainDescription(
+  prose: string,
+  options: PlainDescriptionOptions = {},
+): string {
+  const maxLength = options.maxLength ?? 160;
+  const minLength = options.minLength ?? 110;
+  const text = plainProse(prose);
+  if (text.length <= maxLength) return text;
+  const whole = wholeSentences(text, maxLength);
+  if (whole.length >= minLength) return whole;
+  return clipped(text, maxLength);
+}
+
+/**
+ * Authored prose as plain text: glossary markers, code spans, strong and
+ * emphasis resolved to the words they show, and the whitespace collapsed.
+ * @param prose - The prose, markup and all.
+ * @returns The same words, unmarked.
+ */
+export function plainProse(prose: string): string {
+  const segments = parseInlineMarks(prose, { glossaryMarkers: true });
+  return textOf(segments).replaceAll(/\s+/g, ' ').trim();
+}
+
+// What a cut must not end on: punctuation, or a word joining two. Each pattern
+// holds a single quantifier anchored at the end, never a repeated group of
+// them, so a long run of dashes cannot make the engine backtrack exponentially.
+const TRAILING_PUNCTUATION = /[\s,:;–—-]+$/;
+const TRAILING_JOINING_WORD =
+  /\s(?:a|an|and|as|at|but|by|for|from|in|into|of|on|or|so|the|to|with)$/i;
+
+function textOf(segments: readonly InlineSegment[]): string {
+  let text = '';
+  for (const segment of segments) {
+    if ('children' in segment) {
+      text += textOf(segment.children);
+    } else {
+      text += segment.text;
+    }
+  }
+  return text;
+}
+
+function wholeSentences(text: string, limit: number): string {
+  const terminator = /[!.?](?=\s|$)/g;
+  let end = 0;
+  for (
+    let match = terminator.exec(text);
+    match !== null;
+    match = terminator.exec(text)
+  ) {
+    if (match.index >= limit) break;
+    end = match.index + 1;
+  }
+  return text.slice(0, end);
+}
+
+function clipped(text: string, limit: number): string {
+  const cut = text.slice(0, limit - 1);
+  const space = cut.lastIndexOf(' ');
+  const words = space > limit / 2 ? cut.slice(0, space) : cut;
+  return `${withoutDanglingEnd(words)}…`;
+}
+
+function withoutDanglingEnd(words: string): string {
+  let text = words;
+  let previous = '';
+  while (text !== previous) {
+    previous = text;
+    text = text
+      .replace(TRAILING_PUNCTUATION, '')
+      .replace(TRAILING_JOINING_WORD, '');
+  }
+  return text;
+}