react-cheminfo 0.47.0 → 0.48.0

package/src/periodic/ui/SelectAllCorner.tsx

@@ -0,0 +1,65 @@
+import type { FocusEvent, ReactElement } from 'react';
+import { useState } from 'react';
+
+import { headerButtonStyle, headerStyle } from './headerStyles.ts';
+
+/** What {@link SelectAllCorner} needs. */
+interface SelectAllCornerProps {
+  /** What it does, for the pointer and for a screen reader. */
+  title: string;
+  /** Called when it is clicked. */
+  onClick: () => void;
+}
+
+/**
+ * The corner where the two header strips meet, which takes the whole table.
+ *
+ * It is a control and nothing else, so it stays out of sight until it is
+ * pointed at or reached from the keyboard, and it is left off a print and out
+ * of a saved figure. The glyph points into the grid it takes, as a
+ * spreadsheet's does; it is a mark rather than a word because the corner is a
+ * seventeenth of the table's width, and the word differs in every language the
+ * chrome speaks.
+ * @param props - See {@link SelectAllCornerProps}.
+ * @returns The corner.
+ */
+export function SelectAllCorner(props: SelectAllCornerProps): ReactElement {
+  const { title, onClick } = props;
+  const [pointed, setPointed] = useState(false);
+  const [focused, setFocused] = useState(false);
+
+  return (
+    <button
+      type="button"
+      aria-label={title}
+      title={title}
+      onClick={onClick}
+      style={{
+        ...headerStyle,
+        gridColumn: 1,
+        gridRow: 1,
+        ...headerButtonStyle,
+        opacity: pointed || focused ? 1 : 0,
+        transition: 'opacity 120ms ease',
+      }}
+      className="no-print"
+      data-figure="chrome"
+      onPointerEnter={() => {
+        setPointed(true);
+      }}
+      onPointerLeave={() => {
+        setPointed(false);
+      }}
+      // Only a focus the keyboard gave it: a click focuses it too, and the
+      // glyph would otherwise stay up after the pointer has gone.
+      onFocus={(event: FocusEvent<HTMLButtonElement>) => {
+        setFocused(event.currentTarget.matches(':focus-visible'));
+      }}
+      onBlur={() => {
+        setFocused(false);
+      }}
+    >
+      ◢
+    </button>
+  );
+}

package/src/periodic/ui/headerStyles.ts

@@ -0,0 +1,23 @@
+import type { CSSProperties } from 'react';
+
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
+import { ofWidth } from './unit.ts';
+
+/** A group or period number, and the corner where the two strips meet. */
+export const headerStyle = {
+  alignItems: 'center',
+  color: TOKEN.textMuted,
+  display: 'flex',
+  fontSize: `max(0.45rem, ${ofWidth(1.35)})`,
+  justifyContent: 'center',
+  padding: 0,
+} as const satisfies CSSProperties;
+
+/** The same, when it is a button: the type and the ground stay the strip's. */
+export const headerButtonStyle = {
+  background: 'none',
+  border: 'none',
+  cursor: 'pointer',
+  font: 'inherit',
+} as const satisfies CSSProperties;

package/src/periodic/ui/periodicTableProps.ts

@@ -0,0 +1,117 @@
+/**
+ * What a caller hands a `PeriodicTable`.
+ *
+ * The props live beside the component rather than inside it, so a reader
+ * looking for what the table does does not scroll past a page of options.
+ */
+
+import type { ReactNode } from 'react';
+
+import type { Swatch } from '../../color/core/interpolate.ts';
+import type { PeriodicElement } from '../core/elements.ts';
+import type { ElementPick, ElementRange } from '../core/layout.ts';
+
+/** What `PeriodicTable` needs. */
+export interface PeriodicTableProps {
+  /**
+   * Symbol of the element the tools are pointed at.
+   * @default undefined — none is
+   */
+  selected?: string;
+  /**
+   * Called with the symbol of the element that was clicked, and by the arrow
+   * keys. The pick says whether the click was additive — Cmd or Ctrl held — so
+   * a tool whose plain click already reads one element into a card can let the
+   * same table build a set of them.
+   * @default undefined — the table is a figure rather than a control
+   */
+  onSelect?: (symbol: string, pick: ElementPick) => void;
+  /**
+   * The colour each cell takes.
+   * @default the family colour
+   */
+  swatchOf?: (element: PeriodicElement) => Swatch;
+  /**
+   * What is written under the symbol; an empty string writes nothing.
+   * @default nothing is written
+   */
+  detailOf?: (element: PeriodicElement) => string;
+  /**
+   * How an element is named, for the label a screen reader reads. The hook a
+   * site translating the table writes its own names through.
+   * @default the English name
+   */
+  nameOf?: (element: PeriodicElement) => string;
+  /**
+   * Electrons in each shell of an element, innermost first, written down the
+   * right-hand edge of its cell. The energy levels, which a table is also read
+   * for: none of ours knows them, so the tool that does says so here.
+   * @default undefined — no cell writes any
+   */
+  shellsOf?: (element: PeriodicElement) => readonly number[] | undefined;
+  /**
+   * Whether an element is inside the set the tool is showing. Everything
+   * outside it is dimmed rather than removed, so the table keeps its shape.
+   * @default every element is
+   */
+  isIncluded?: (element: PeriodicElement) => boolean;
+  /**
+   * What is written in the block the table leaves empty — columns 3 to 12 of
+   * the first three periods, in the middle of the top edge. A tool that reads
+   * one element off the table puts what it says about it there, where the eye
+   * already is, rather than under the grid.
+   *
+   * It is sized against the table, like everything else in the grid, so give
+   * it type in `em` and it scales with the drawing.
+   * @default undefined — the block stays empty
+   */
+  inset?: ReactNode;
+  /**
+   * Whether to draw the group and period strips.
+   * @default false
+   */
+  headers?: boolean;
+  /**
+   * Called when a whole group or period header is clicked. The run says
+   * whether the click was additive — Cmd or Ctrl held — so a tool can let a
+   * reader put two periods on one chart. Without it the strips are labels
+   * rather than buttons.
+   * @default undefined
+   */
+  onSelectRange?: (range: ElementRange) => void;
+  /**
+   * Called when the corner where the two header strips meet is clicked, which
+   * is how a reader takes the whole table back. The corner shows its glyph only
+   * while it is pointed at or reached from the keyboard. Without it the corner
+   * stays empty.
+   * @default undefined
+   */
+  onSelectAll?: () => void;
+  /**
+   * Whether to draw the family legend under the grid.
+   * @default false
+   */
+  legend?: boolean;
+  /**
+   * Whether the dashed markers stand where the two inner-transition series were
+   * lifted out of the main block.
+   * @default true
+   */
+  markers?: boolean;
+  /**
+   * Whether the arrow keys walk the grid: down from carbon is silicon, and
+   * right from the end of a period is the start of the next.
+   * @default true
+   */
+  keyboard?: boolean;
+  /**
+   * Called on pointer enter with the symbol, and on leave with `null`.
+   * @default undefined
+   */
+  onHover?: (symbol: string | null) => void;
+  /**
+   * Class of the outermost element.
+   * @default undefined
+   */
+  className?: string;
+}

package/src/periodic/ui/tableLayout.ts

@@ -0,0 +1,96 @@
+/**
+ * How the table is laid out: the box it measures, the grid its cells sit on,
+ * and the block a caller may write in.
+ */
+
+import type { CSSProperties } from 'react';
+
+import { COLUMN_COUNT, EMPTY_BLOCK } from '../core/layout.ts';
+
+import { ROW_SHARE } from './cellType.ts';
+import { ofWidth } from './unit.ts';
+
+/**
+ * Where what the caller writes in the empty block is placed.
+ * @param offset - 1 when the table draws its header strips, 0 otherwise.
+ * @returns The style of the slot.
+ */
+export function insetStyle(offset: number): CSSProperties {
+  return {
+    alignItems: 'center',
+    display: 'flex',
+    // A column of air on each side, so the writing reads as sitting in the
+    // block rather than as running into the cells beside it.
+    padding: `0 ${ofWidth(2.4)}`,
+    gridColumn: `${String(EMPTY_BLOCK.column + offset)} / span ${String(EMPTY_BLOCK.columnSpan)}`,
+    gridRow: `${String(EMPTY_BLOCK.row + offset)} / span ${String(EMPTY_BLOCK.rowSpan)}`,
+    // A share of the table, with a floor, exactly as a cell sizes its symbol:
+    // the block holds the same three rows at every width, so what is written
+    // in it has to shrink with them.
+    fontSize: `max(0.6rem, ${ofWidth(1.8)})`,
+    lineHeight: 1.35,
+    minWidth: 0,
+    overflow: 'hidden',
+  };
+}
+
+/** Narrowest the table is ever drawn; under it the type stops being readable. */
+const MIN_WIDTH = 280;
+
+/**
+ * How tall one row of elements is, as a share of the table's width.
+ *
+ * A column is about 5.2% of that width, so a cell is a third taller than it is
+ * wide — the proportion of a wall chart, and the room the three bands of a
+ * cell need to be read from the back of a room. It is the same height in every
+ * table: a cell keeps the band it writes a value in whether or not that table
+ * writes one.
+ */
+const ROW_HEIGHT = ofWidth(ROW_SHARE);
+
+/** The band the two inner-transition series were lifted out across. */
+const SERIES_GAP = `max(6px, ${ofWidth(1.1)})`;
+
+export const rootStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 8,
+  minWidth: MIN_WIDTH,
+  // Everything inside — the height of a row as much as the type in a cell — is
+  // a share of this box rather than of the page, so the same table reads at
+  // 280px beside a chart and fills a lecture-hall screen at twice that. The
+  // share is measured (see `unit.ts`); the container is what the `1cqw`
+  // fallback and a site's own `@container` rules are answered by, and it keeps
+  // this box's width independent of what is written inside it.
+  containerType: 'inline-size',
+} as const satisfies CSSProperties;
+
+const baseGridStyle = {
+  display: 'grid',
+  gap: 2,
+  minWidth: MIN_WIDTH,
+  width: '100%',
+} as const satisfies CSSProperties;
+
+/**
+ * The grid the cells are placed on.
+ * @param headers - Whether a leading column and row hold the period and group
+ * numbers.
+ * @returns The style of the grid.
+ */
+export function gridStyle(headers: boolean): CSSProperties {
+  // The eighth row is the gap the inner-transition series are lifted out into.
+  const rows = `repeat(7, ${ROW_HEIGHT}) ${SERIES_GAP} repeat(2, ${ROW_HEIGHT})`;
+  if (!headers) {
+    return {
+      ...baseGridStyle,
+      gridTemplateColumns: `repeat(${String(COLUMN_COUNT)}, minmax(0, 1fr))`,
+      gridTemplateRows: rows,
+    };
+  }
+  return {
+    ...baseGridStyle,
+    gridTemplateColumns: `max(14px, ${ofWidth(2.4)}) repeat(${String(COLUMN_COUNT)}, minmax(0, 1fr))`,
+    gridTemplateRows: `max(12px, ${ofWidth(2)}) ${rows}`,
+  };
+}

package/src/split/ui/SplitColumn.tsx

@@ -26,7 +26,6 @@ export type SplitColumnProps = SplitPanesProps;
  * no height to divide, it measures nothing, says nothing about it, and simply
  * stacks the two panes with no splitter, which is what an ordinary page wanted
  * anyway.
- *
  * @param props - See {@link SplitColumnProps}.
  * @returns The two panes with the splitter between them, the two stacked where
  * there is no height to divide, or whichever one a link left, alone.

package/src/split/ui/SplitRow.tsx

@@ -24,7 +24,6 @@ export type SplitRowProps = SplitPanesProps;
  * of forms dragged past about half the row does not grow: the labels stay put
  * and the fields stretch to a width nobody types into, so the room becomes
  * empty card. The figure beside it is what the drag exists to enlarge.
- *
  * @param props - See {@link SplitRowProps}.
  * @returns The two panes with the splitter between them, the two stacked on a
  * narrow screen, or whichever one a link left on the page, alone.

package/src/split/ui/splitPanes.tsx

@@ -13,6 +13,18 @@
  * everything one pane holds leaves the other the whole of it rather than a
  * share.
  *
+ * **Several bars on one page make a grid, and a grid has to read as one.** Three
+ * panes are one of these nested inside the other, and the shares are numbered in
+ * reading order — `split` for the first bar a reader meets going left to right
+ * and then down, `split2` for the next. Two rules keep that from coming apart:
+ * **at most two bars on a page**, because a third is a window manager rather
+ * than a tool and every bar is one more thing to understand before the page can
+ * be used; and **never a bar across two columns of the same row**, because two
+ * of them at independent heights do not read as a grid, they read as a page that
+ * has come apart. Divide the column that holds the figures and leave its
+ * neighbours whole — or, where both genuinely want the same line, give them one
+ * share and one parameter so it runs straight across.
+ *
  * The bar itself is react-science's `SplitPane`, and it keeps react-science's
  * look — barely visible on purpose, found by the pointer that changes over it
  * rather than by the eye. All `chrome.css` says about it is that eleven pixels
@@ -73,7 +85,6 @@ interface InternalProps extends SplitPanesProps {
 
 /**
  * The two panes, divided where the address says.
- *
  * @param props - See {@link SplitPanesProps}.
  * @returns The panes with the splitter between them, the two stacked where
  * there is no room for both, or whichever one a link left, alone.
@@ -142,8 +153,15 @@ export function SplitPanes(props: InternalProps): ReactElement | null {
 
   return (
     // `split-row` is what `chrome.css` reaches the bar through: it is
-    // react-science's own element and carries no class of ours.
-    <div ref={box} className="split-row" style={across ? undefined : FILL}>
+    // react-science's own element and carries no class of ours. A column says
+    // which way it divides as well, because its bar is that same line turned a
+    // quarter: there it is the height that is narrowed, and the width that is
+    // left to run the pane.
+    <div
+      ref={box}
+      className={across ? 'split-row' : 'split-row split-row--down'}
+      style={across ? undefined : FILL}
+    >
       <SplitPane
         direction={direction}
         controlledSide="start"
@@ -175,7 +193,6 @@ export function SplitPanes(props: InternalProps): ReactElement | null {
 
 /**
  * The share a splitter asked for.
- *
  * @param asked - What it reported, a percentage because that is what it was
  * given.
  * @param current - The share in force, kept when the report is not a number.
@@ -196,7 +213,6 @@ function shareOf(
  * measured. Reading it rather than starting at zero is what keeps a wide page
  * from laying itself out stacked and splitting a frame later, which would build
  * both figures twice on every load.
- *
  * @param across - Whether the box is divided across or down.
  * @param fallback - What to answer where there is no window to read — a test,
  * or a page rendered to a string.

package/src/taxonomy/core/index.ts

@@ -0,0 +1,20 @@
+export type { Taxon, TaxonLineage, TaxonNode } from './lineage.ts';
+export {
+  genusOrBelow,
+  isPlaceholderTaxon,
+  lineageFromNodes,
+  lineageFromRanks,
+  principalLineage,
+} from './lineage.ts';
+export { ncbiTaxonomyUrl } from './ncbi.ts';
+export type { OrganismNamePart } from './organismName.ts';
+export { splitOrganismName } from './organismName.ts';
+export type { TaxonRank } from './ranks.ts';
+export {
+  PRINCIPAL_RANKS,
+  TAXON_RANKS,
+  isAboveGenus,
+  isGenusOrBelow,
+  isPrincipalRank,
+  rankOrder,
+} from './ranks.ts';

package/src/taxonomy/core/lineage.ts

@@ -0,0 +1,161 @@
+/**
+ * A lineage: the taxa from the top of the tree of life down to one of them.
+ *
+ * It is read three ways, because the family meets it in three shapes: a map of
+ * NCBI nodes each pointing at its parent (what a database built on the NCBI
+ * dump answers), a record of names by rank (what octochemdb stores), or a list
+ * already in order.
+ */
+
+import {
+  TAXON_RANKS,
+  isGenusOrBelow,
+  isPrincipalRank,
+  rankOrder,
+} from './ranks.ts';
+
+/** One taxon of a lineage. */
+export interface Taxon {
+  /** The rank, as NCBI writes it: `genus`, `no rank`, `clade`… */
+  rank: string;
+  /** The scientific name. */
+  name: string;
+  /**
+   * The NCBI Taxonomy id.
+   * @default undefined — the taxon is known by its name alone
+   */
+  taxId?: number;
+}
+
+/** The taxa from the top of the tree down to one of them, in that order. */
+export type TaxonLineage = readonly Taxon[];
+
+/** A taxon of the NCBI tree, as a map of nodes holds it. */
+export interface TaxonNode {
+  /** The scientific name. */
+  name: string;
+  /** The rank, as NCBI writes it. */
+  rank: string;
+  /** The id of the taxon above; the root is its own parent. */
+  parentId: number;
+}
+
+/**
+ * The taxa a lineage is summarised by: those of a principal rank (domain,
+ * kingdom, phylum, class, order, family, genus, species), and the last one
+ * whatever its rank, since it is the taxon the lineage leads to.
+ *
+ * An NCBI placeholder for an unidentified species ('Streptomyces sp.') says
+ * no more than its genus, so it is left out and the genus is the leaf. The
+ * root, 'cellular organisms', the clades and the steps of no rank above the
+ * leaf never show.
+ * @param lineage - The lineage, from the top down.
+ * @returns The taxa kept, in the same order.
+ */
+export function principalLineage(lineage: TaxonLineage): Taxon[] {
+  const kept: Taxon[] = [];
+  let last = lineage.length - 1;
+  if (last > 0 && isPlaceholderTaxon(lineage[last] as Taxon)) {
+    // The genus becomes the leaf, past 'unclassified Streptomyces'.
+    last--;
+    while (last > 0 && !isPrincipalRank((lineage[last] as Taxon).rank)) last--;
+  }
+  for (let index = 0; index <= last; index++) {
+    const taxon = lineage[index] as Taxon;
+    if (index < last && isPlaceholderTaxon(taxon)) continue;
+    if (index === last || isPrincipalRank(taxon.rank)) kept.push(taxon);
+  }
+  return kept;
+}
+
+/**
+ * Whether a taxon is an NCBI placeholder for an unidentified species of a
+ * genus: a species named the genus and 'sp.', such as 'Streptomyces sp.'.
+ * One named for a strain ('Streptomyces sp. CNQ-509') is a taxon of its own.
+ * @param taxon - The taxon.
+ * @returns Whether it is one.
+ */
+export function isPlaceholderTaxon(taxon: Taxon): boolean {
+  return taxon.rank === 'species' && /\ssp\.$/.test(taxon.name);
+}
+
+/**
+ * The lineage of a taxon, walked up a map of NCBI nodes to the root.
+ * @param nodes - The nodes, by id: a record keyed by the id written as a
+ * string, as JSON delivers it, or a map keyed by the number.
+ * @param taxId - The taxon to start from.
+ * @returns Every taxon from the root down to it, each with its id; empty when
+ * the map does not hold the taxon.
+ */
+export function lineageFromNodes(
+  nodes: Readonly<Record<string, TaxonNode>> | ReadonlyMap<number, TaxonNode>,
+  taxId: number,
+): Taxon[] {
+  const read =
+    nodes instanceof Map
+      ? (id: number) => nodes.get(id)
+      : (id: number) =>
+          (nodes as Readonly<Record<string, TaxonNode>>)[String(id)];
+  const upward: Taxon[] = [];
+  const seen = new Set<number>();
+  let id = taxId;
+  while (!seen.has(id)) {
+    const node = read(id);
+    if (node === undefined) break;
+    seen.add(id);
+    upward.push({ rank: node.rank, name: node.name, taxId: id });
+    id = node.parentId;
+  }
+  return upward.toReversed();
+}
+
+/**
+ * The lineage written by a record of names by rank, the shape octochemdb
+ * stores (`{ kingdom: 'Fungi', genus: 'Penicillium', … }`).
+ *
+ * A key is matched whatever its case, so `superKingdom` reads as
+ * `superkingdom`; a key that names no rank, and an empty name, are left out.
+ * @param ranks - The names, by rank.
+ * @returns The taxa, from the top down.
+ */
+export function lineageFromRanks(
+  ranks: Readonly<Record<string, string | null | undefined>>,
+): Taxon[] {
+  const byRank = new Map<string, string>();
+  for (const key of Object.keys(ranks)) {
+    const name = ranks[key]?.trim();
+    if (name === undefined || name === '') continue;
+    const rank = key.toLowerCase();
+    if (rankOrder(rank) !== undefined) byRank.set(rank, name);
+  }
+  const lineage: Taxon[] = [];
+  for (const rank of TAXON_RANKS) {
+    const name = byRank.get(rank);
+    if (name !== undefined) lineage.push({ rank, name });
+  }
+  return lineage;
+}
+
+/**
+ * Which taxa of a lineage sit at the genus or under it — the ones whose names
+ * nomenclature sets in italics.
+ *
+ * A taxon with no rank (a clade, a strain NCBI left unranked) takes the place
+ * of the taxa above it: under a genus it is one of the genus's, above it it is
+ * a clade like Embryophyta, written upright.
+ * @param lineage - The lineage, from the top down.
+ * @returns One flag per taxon.
+ */
+export function genusOrBelow(lineage: TaxonLineage): boolean[] {
+  const flags: boolean[] = [];
+  let below = false;
+  for (const taxon of lineage) {
+    if (isGenusOrBelow(taxon.rank)) {
+      below = true;
+    } else if (rankOrder(taxon.rank) !== undefined) {
+      below = false;
+    }
+    flags.push(below);
+  }
+  return flags;
+}

package/src/taxonomy/core/ncbi.ts

@@ -0,0 +1,9 @@
+/**
+ * The page of a taxon in the NCBI Taxonomy Browser.
+ * @param taxId - The NCBI Taxonomy id.
+ * @returns Its address, e.g.
+ * `https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=5076`.
+ */
+export function ncbiTaxonomyUrl(taxId: number): string {
+  return `https://www.ncbi.nlm.nih.gov/Taxonomy/Browser/wwwtax.cgi?id=${encodeURIComponent(String(taxId))}`;
+}