react-cheminfo 0.8.0 → 0.10.0

package/src/scatter/ui/useScatterSelection.ts

@@ -0,0 +1,189 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+import {
+  mergeScatterSelection,
+  scatterSelectedIndices,
+  scatterSelectionMask,
+} from '../core/scatterSelection.ts';
+
+/** What a gesture did to a scatter's selection. */
+export interface SelectionChange {
+  /** The selected rows, ascending, as indices into the arrays the caller passed. */
+  indices: readonly number[];
+  /** Whether the gesture replaced the previous selection, added to it, or cut from it. */
+  mode: ScatterSelectionMode;
+  /** Which gesture produced it. */
+  source: 'lasso' | 'point' | 'keyboard' | 'clear' | 'all';
+}
+
+/** What {@link useScatterSelection} needs. */
+export interface ScatterSelectionOptions {
+  /** How many points the cloud holds. */
+  count: number;
+  /**
+   * The selected rows when the caller owns them. Present, it wins over
+   * anything the reader has done here — see {@link useScatterSelection} for
+   * what that means for a caller that stops passing it.
+   * @default undefined — the hook keeps the selection itself
+   */
+  selected?: readonly number[];
+  /**
+   * The rows selected before the reader touches anything, for the uncontrolled
+   * case. It is read once; changing it later moves nothing.
+   * @default undefined — nothing is selected
+   */
+  defaultSelected?: readonly number[];
+  /**
+   * Called once per settled gesture, never while a lasso is being drawn.
+   * @default undefined
+   */
+  onSelectionChange?: (change: SelectionChange) => void;
+}
+
+/** A scatter's selection, and the four ways a gesture changes it. */
+export interface ScatterSelectionApi {
+  /**
+   * One entry per point, `1` for selected. It includes whatever a lasso is
+   * currently previewing, so the dots under a half-drawn ring already look
+   * picked.
+   */
+  mask: Uint8Array;
+  /** The same, as ascending indices. */
+  indices: number[];
+  /** How many points that is, without walking the list again. */
+  selectedCount: number;
+  /** Whether a lasso is showing what it would do rather than having done it. */
+  previewing: boolean;
+  /** Settle a new selection from a list of rows. */
+  select: (
+    rows: Iterable<number>,
+    mode?: ScatterSelectionMode,
+    source?: SelectionChange['source'],
+  ) => void;
+  /** Settle one from a mask, which is the shape a lasso hands back. */
+  selectMask: (
+    hits: Uint8Array,
+    mode?: ScatterSelectionMode,
+    source?: SelectionChange['source'],
+  ) => void;
+  /** Show what a gesture would do without settling it; `null` clears it. */
+  preview: (hits: Uint8Array | null, mode?: ScatterSelectionMode) => void;
+  /** Empty the selection. */
+  clear: () => void;
+  /** Select every point. */
+  selectAll: () => void;
+}
+
+/**
+ * The set of points a scatter has picked out, controlled or not.
+ *
+ * A caller may own the selection and pass it back through `selected`, or leave
+ * it here and only listen. Both work through one hook, and the controlled
+ * value wins on every render: a parent that answers a change by passing
+ * something else — a filter that keeps only the rows still on screen — sees
+ * what it asked for and not what the gesture asked for. The hook keeps its own
+ * copy up to date all the same, so a caller that stops passing `selected`
+ * carries on from where the reader left off rather than from nothing.
+ *
+ * A preview is deliberately not a change. What a half-drawn lasso would catch
+ * is merged in for the render and never reported, which is what lets a
+ * controlled parent stay out of a drag it would otherwise be re-rendered by
+ * sixty times a second.
+ * @param options - See {@link ScatterSelectionOptions}.
+ * @returns The selection. See {@link ScatterSelectionApi}.
+ */
+export function useScatterSelection(
+  options: ScatterSelectionOptions,
+): ScatterSelectionApi {
+  const { count, selected, defaultSelected, onSelectionChange } = options;
+
+  const [own, setOwn] = useState<readonly number[]>(defaultSelected ?? EMPTY);
+  const [draft, setDraft] = useState<SelectionDraft | null>(null);
+  const committed = selected ?? own;
+
+  const mask = useMemo(() => {
+    const base = scatterSelectionMask(committed, count);
+    if (draft === null) return base;
+    return mergeScatterSelection(base, draft.hits, draft.mode, base);
+  }, [committed, count, draft]);
+
+  const indices = useMemo(() => scatterSelectedIndices(mask), [mask]);
+
+  const commit = useCallback(
+    (
+      rows: number[],
+      mode: ScatterSelectionMode,
+      source: SelectionChange['source'],
+    ) => {
+      setDraft(null);
+      setOwn(rows);
+      onSelectionChange?.({ indices: rows, mode, source });
+    },
+    [onSelectionChange],
+  );
+
+  const selectMask = useCallback(
+    (
+      hits: Uint8Array,
+      mode: ScatterSelectionMode = 'replace',
+      source: SelectionChange['source'] = 'lasso',
+    ) => {
+      const base = scatterSelectionMask(committed, count);
+      const merged = mergeScatterSelection(base, hits, mode, base);
+      commit(scatterSelectedIndices(merged), mode, source);
+    },
+    [commit, committed, count],
+  );
+
+  const select = useCallback(
+    (
+      rows: Iterable<number>,
+      mode: ScatterSelectionMode = 'replace',
+      source: SelectionChange['source'] = 'point',
+    ) => {
+      selectMask(scatterSelectionMask(rows, count), mode, source);
+    },
+    [count, selectMask],
+  );
+
+  const preview = useCallback(
+    (hits: Uint8Array | null, mode: ScatterSelectionMode = 'replace') => {
+      setDraft(hits === null ? null : { hits, mode });
+    },
+    [],
+  );
+
+  const clear = useCallback(() => {
+    commit([], 'replace', 'clear');
+  }, [commit]);
+
+  const selectAll = useCallback(() => {
+    const rows = new Array<number>(Math.max(0, count));
+    for (let index = 0; index < rows.length; index++) rows[index] = index;
+    commit(rows, 'replace', 'all');
+  }, [commit, count]);
+
+  return {
+    mask,
+    indices,
+    selectedCount: indices.length,
+    previewing: draft !== null,
+    select,
+    selectMask,
+    preview,
+    clear,
+    selectAll,
+  };
+}
+
+/** Shared, so an uncontrolled scatter with nothing picked allocates nothing. */
+const EMPTY: readonly number[] = [];
+
+/** What a lasso is showing it would do, before it has been released. */
+interface SelectionDraft {
+  /** The points the half-drawn gesture is over. */
+  hits: Uint8Array;
+  /** What releasing would do with them. */
+  mode: ScatterSelectionMode;
+}

package/src/seo/vite/ogCard.ts

@@ -1,3 +1,4 @@
+// tokens-ok: file — the card is an image built outside any page, so it has no tokens to read.
 /**
  * The 1200×630 card a link to a site unfurls into, as a page to screenshot.
  *

package/src/share/core/query.ts

@@ -26,10 +26,16 @@ export function parseQuery(search: string): QueryEntry[] {
 }
 
 /**
- * Write pairs back into a query string, keeping the two characters a reader
- * of these links cares about legible: a comma stays a comma rather than
- * `%2C`, and a plus stays a plus rather than `%2B`. Both parse back
- * identically through {@link parseQuery}.
+ * Write pairs back into a query string, keeping the comma legible — `hide=a,b`
+ * rather than `hide=a%2Cb` — because a teacher has to read these links, and a
+ * comma has only one reading.
+ *
+ * A plus is written `%2B`, even though {@link parseQuery} would read a literal
+ * one back. We are liberal in what we accept and strict in what we write: a
+ * bare `+` in a query string is read as a space by `URLSearchParams`,
+ * `query-string` and every server-side parser, so `ionizations=H+` comes back
+ * as `H ` and `smiles=CC[N+](C)(C)C` as a different molecule — silently,
+ * anywhere the link is read by something other than {@link parseQuery}.
  * @param entries - The pairs to write, in the order they should appear.
  * @returns The query string, without its leading `?`.
  */
@@ -66,7 +72,5 @@ function decodeComponent(value: string): string {
 }
 
 function encodeComponent(value: string): string {
-  return encodeURIComponent(value)
-    .replaceAll('%2C', ',')
-    .replaceAll('%2B', '+');
+  return encodeURIComponent(value).replaceAll('%2C', ',');
 }

package/src/share/ui/ShareDialogContent.tsx

@@ -28,7 +28,10 @@ import type { ShareDialogProps, ShareDraft } from './ShareDialog.tsx';
 import { SharePartOptions } from './SharePartOptions.tsx';
 import { withPart } from './draft.ts';
 
-const LEAD_STYLE: CSSProperties = { marginTop: 0, color: '#5b6875' };
+const LEAD_STYLE: CSSProperties = {
+  marginTop: 0,
+  color: 'var(--text-muted, #5b6875)',
+};
 const SECTION_STYLE: CSSProperties = { marginBottom: 18 };
 const ACTIONS_STYLE: CSSProperties = {
   display: 'flex',
@@ -39,7 +42,7 @@ const ACTIONS_STYLE: CSSProperties = {
 const HINT_STYLE: CSSProperties = {
   display: 'block',
   marginLeft: 26,
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: 12,
 };
 

package/src/share/ui/SharePartOptions.tsx

@@ -8,7 +8,7 @@ const OPTION_STYLE: CSSProperties = { marginBottom: 8 };
 const DESCRIPTION_STYLE: CSSProperties = {
   display: 'block',
   marginLeft: 26,
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: 12,
 };
 

package/src/slides/core/demoLinks.ts

@@ -0,0 +1,113 @@
+/**
+ * The links a slide hands over to the live tool.
+ *
+ * A demo link is a paragraph that is exactly one Markdown link to an in-app
+ * route. It is parsed by hand rather than by a Markdown library because the
+ * labels are chemistry — `[M+H]⁺` opens a bracket the label closes itself, and
+ * a formula such as `H(OCH2CH2)10` puts parentheses inside the URL — and both
+ * defeat a naive `\[(.*)\]\((.*)\)` pattern.
+ */
+
+/** One link a slide offers as a live demo. */
+export interface DemoLinkSpec {
+  /** The link text, which may itself contain balanced brackets. */
+  label: string;
+  /** Where it goes; a demo link always targets an in-app route. */
+  href: string;
+}
+
+/**
+ * Read a paragraph that is exactly one Markdown link `[label](url)` and nothing
+ * else, counting brackets so a label may hold its own pair, and accepting the
+ * angle-bracketed URL form `[label](<url>)` for a URL holding parentheses.
+ * @param text - The paragraph text.
+ * @returns The link, or `null` when the paragraph is anything else.
+ */
+export function parseSingleLink(text: string): DemoLinkSpec | null {
+  const source = text.trim();
+  if (!source.startsWith('[')) return null;
+
+  let depth = 0;
+  let labelEnd = -1;
+  for (let index = 0; index < source.length; index++) {
+    const char = source[index];
+    if (char === '[') {
+      depth++;
+    } else if (char === ']') {
+      depth--;
+      if (depth === 0) {
+        labelEnd = index;
+        break;
+      }
+    }
+  }
+  if (labelEnd === -1 || source[labelEnd + 1] !== '(') return null;
+
+  const label = source.slice(1, labelEnd);
+  let rest = source.slice(labelEnd + 2);
+  let href: string;
+
+  if (rest.startsWith('<')) {
+    const close = rest.indexOf('>');
+    if (close === -1 || rest[close + 1] !== ')') return null;
+    href = rest.slice(1, close);
+    rest = rest.slice(close + 2);
+  } else {
+    let parenDepth = 1;
+    let urlEnd = -1;
+    for (let index = 0; index < rest.length; index++) {
+      const char = rest[index];
+      if (char === '(') {
+        parenDepth++;
+      } else if (char === ')') {
+        parenDepth--;
+        if (parenDepth === 0) {
+          urlEnd = index;
+          break;
+        }
+      }
+    }
+    if (urlEnd === -1) return null;
+    href = rest.slice(0, urlEnd);
+    rest = rest.slice(urlEnd + 1);
+  }
+
+  if (rest.trim() !== '') return null;
+  return { label, href };
+}
+
+/**
+ * Split a slide body into its Markdown and the run of demo links that closes
+ * it. External links and ordinary paragraphs stay in the body, so a slide that
+ * merely cites a URL keeps it where the author wrote it.
+ * @param body - The slide Markdown body.
+ * @returns The body without its trailing demo links, and those links in order.
+ */
+export function splitDemoLinks(body: string): {
+  body: string;
+  demos: DemoLinkSpec[];
+} {
+  const blocks = body.split(/\n{2,}/);
+  let firstDemo = blocks.length;
+  const demos: DemoLinkSpec[] = [];
+  for (let index = blocks.length - 1; index >= 0; index--) {
+    const link = parseSingleLink(blocks[index] ?? '');
+    if (!link?.href.startsWith('/')) break;
+    demos.unshift(link);
+    firstDemo = index;
+  }
+  return { body: blocks.slice(0, firstDemo).join('\n\n').trim(), demos };
+}
+
+/**
+ * The displayed form of a demo link label: the `Demo:` prefix an author writes
+ * to mark the paragraph is dropped, and the first character is uppercased.
+ * @param label - The raw link label.
+ * @returns What the button shows.
+ */
+export function demoLabel(label: string): string {
+  const text = label.replace(DEMO_PREFIX, '');
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+const DEMO_PREFIX = /^Demo:\s*/i;

package/src/slides/core/index.ts

@@ -0,0 +1,22 @@
+export type { DemoLinkSpec } from './demoLinks.ts';
+export { demoLabel, parseSingleLink, splitDemoLinks } from './demoLinks.ts';
+export type { SectionHeading } from './sectionHeading.ts';
+export { parseSectionHeading } from './sectionHeading.ts';
+export type { SlideAction } from './slideNavigation.ts';
+export { clampSlideIndex, slideActionForKey } from './slideNavigation.ts';
+export type { Slide, Talk, TalkMeta } from './talk.ts';
+export { parseTalk } from './talk.ts';
+export type { TalkManifest, TalkSummary } from './talkManifest.ts';
+export {
+  buildTalkManifest,
+  parseTalkManifest,
+  talkSourceUrl,
+  talkSummary,
+} from './talkManifest.ts';
+export type { TalkOrigin } from './talkOrigin.ts';
+export {
+  TALK_ORIGIN_PARAM,
+  formatTalkOrigin,
+  parseTalkOrigin,
+  withTalkOrigin,
+} from './talkOrigin.ts';

package/src/slides/core/sectionHeading.ts

@@ -0,0 +1,29 @@
+/** The parts of a section divider's heading. */
+export interface SectionHeading {
+  /** The section number, as written; empty when the heading carries none. */
+  number: string;
+  /** The section title, without its number; empty when the heading carries none. */
+  title: string;
+  /** Whatever the body holds besides that heading. */
+  rest: string;
+}
+
+/**
+ * Split a section-divider body into its leading number, its title and the rest
+ * of the Markdown, so a template can set the number apart from the title.
+ * `·`, `.`, `:`, `—` and `-` all separate the two.
+ * @param body - Markdown body, normally starting with `# N · Title`.
+ * @returns The parsed heading; a body with no numbered heading keeps all of
+ *   itself in `rest`, leaving `number` and `title` empty.
+ */
+export function parseSectionHeading(body: string): SectionHeading {
+  const match = HEAD_RE.exec(body);
+  const number = match?.groups?.number;
+  const title = match?.groups?.title;
+  if (match === null || number === undefined || title === undefined) {
+    return { number: '', title: '', rest: body.trim() };
+  }
+  return { number, title, rest: body.replace(match[0], '').trim() };
+}
+
+const HEAD_RE = /^#\s+(?<number>\d+)\s*[.:·—-]\s*(?<title>.+?)\s*$/m;

package/src/slides/core/slideNavigation.ts

@@ -0,0 +1,77 @@
+/**
+ * What a key does during a presentation, decided without a DOM.
+ *
+ * The current slide lives in the address, so it arrives as whatever a link
+ * carried — a missing number, a negative one, one past the end of a talk that
+ * has since been shortened. Every move is therefore clamped here rather than
+ * trusted, and the player only ever renders a slide that exists.
+ */
+
+/**
+ * The slide a requested index resolves to.
+ * @param index - The index asked for, from a link or a keystroke.
+ * @param total - How many slides the talk holds.
+ * @returns A zero-based index that exists, or `0` for a talk with no slides.
+ */
+export function clampSlideIndex(index: number, total: number): number {
+  if (!Number.isFinite(total) || total < 1) return 0;
+  if (Number.isNaN(index) || index < 0) return 0;
+  const last = total - 1;
+  return index > last ? last : Math.trunc(index);
+}
+
+/** What a key press asks the player to do. */
+export type SlideAction =
+  | { kind: 'go'; index: number }
+  | { kind: 'blank'; color: 'black' | 'white' }
+  | { kind: 'fullscreen' }
+  | { kind: 'notes' }
+  | null;
+
+/**
+ * The action a key press means, with every move already clamped: stepping past
+ * the last slide, or back from the first, stays on the slide it is on rather
+ * than leaving the talk.
+ * @param key - The `key` of the keyboard event.
+ * @param index - Which slide is showing.
+ * @param total - How many slides the talk holds.
+ * @returns The action, or `null` when the key means nothing here.
+ */
+export function slideActionForKey(
+  key: string,
+  index: number,
+  total: number,
+): SlideAction {
+  switch (key) {
+    case 'ArrowRight':
+    case 'ArrowDown':
+    case 'PageDown':
+    case ' ':
+      return { kind: 'go', index: clampSlideIndex(index + 1, total) };
+    case 'ArrowLeft':
+    case 'ArrowUp':
+    case 'PageUp':
+      return { kind: 'go', index: clampSlideIndex(index - 1, total) };
+    case 'Home':
+      return { kind: 'go', index: 0 };
+    case 'End':
+      return { kind: 'go', index: clampSlideIndex(total - 1, total) };
+    default:
+      return letterAction(key);
+  }
+}
+
+function letterAction(key: string): SlideAction {
+  switch (key.toLowerCase()) {
+    case 'f':
+      return { kind: 'fullscreen' };
+    case 'b':
+      return { kind: 'blank', color: 'black' };
+    case 'w':
+      return { kind: 'blank', color: 'white' };
+    case 'n':
+      return { kind: 'notes' };
+    default:
+      return null;
+  }
+}