react-cheminfo 0.6.0 → 0.7.0

package/src/periodic/core/layout.ts

@@ -0,0 +1,183 @@
+/**
+ * Where every element is drawn.
+ *
+ * The group and the period place the main block, but not the lanthanoids and
+ * the actinoids: those have no group, and are drawn on the two rows underneath.
+ * The grid is therefore 18 columns by 10 rows — seven periods, a blank spacer,
+ * and the two inner-transition rows.
+ *
+ * The cells here are the *logical* ones, so column 1 is group 1 and row 1 is
+ * period 1. A table drawn with the group and period header strips offsets them
+ * by one; nothing in this module needs to know that.
+ */
+
+import type { ElementCategory, PeriodicElement } from './elements.ts';
+import { PERIODIC_ELEMENTS, elementBySymbol } from './elements.ts';
+
+/** A whole run of the table: one group, or one period. */
+export interface ElementRange {
+  kind: 'group' | 'period';
+  value: number;
+}
+
+/** A cell of the grid, one-based as CSS grid lines are. */
+export interface Cell {
+  column: number;
+  row: number;
+}
+
+/** Columns of the table. */
+export const COLUMN_COUNT = 18;
+
+/** Rows of the table, the blank spacer between the blocks included. */
+export const ROW_COUNT = 10;
+
+/** Row the lanthanoids are drawn on, and the actinoids on the one below. */
+const INNER_TRANSITION_ROW = 9;
+
+/** Atomic number the lanthanoids and the actinoids start at. */
+const INNER_TRANSITION_STARTS = [57, 89] as const;
+
+/** How many elements each inner-transition series holds. */
+const INNER_TRANSITION_LENGTH = 15;
+
+/** Column the inner-transition rows start at, under the d block. */
+const INNER_TRANSITION_COLUMN = 3;
+
+/**
+ * The cell an element occupies.
+ * @param element - Element to place.
+ * @returns Its column and row, both one-based.
+ */
+export function cellOf(element: PeriodicElement): Cell {
+  const inner = innerTransitionCell(element);
+  if (inner !== null) return inner;
+  return { column: element.group ?? 1, row: element.period };
+}
+
+/**
+ * Every element with the cell it occupies, in reading order.
+ * @returns One entry per element, ordered by row then column, so a keyboard
+ * walk over the list moves the way the eye does.
+ */
+export function placedElements(): ReadonlyArray<{
+  element: PeriodicElement;
+  cell: Cell;
+}> {
+  PLACED ??= PERIODIC_ELEMENTS.map((element) => ({
+    element,
+    cell: cellOf(element),
+  })).toSorted((first, second) =>
+    first.cell.row === second.cell.row
+      ? first.cell.column - second.cell.column
+      : first.cell.row - second.cell.row,
+  );
+  return PLACED;
+}
+
+let PLACED: ReadonlyArray<{ element: PeriodicElement; cell: Cell }> | null =
+  null;
+
+/**
+ * The two cells the lanthanoids and the actinoids were lifted out of.
+ *
+ * Without them the main block has a hole in it and the two rows underneath
+ * belong nowhere; with them the reader can see where each series was taken
+ * from.
+ */
+export const INNER_TRANSITION_MARKERS: ReadonlyArray<{
+  cell: Cell;
+  label: string;
+  category: ElementCategory;
+}> = [
+  { cell: { column: 3, row: 6 }, label: '57–71', category: 'lanthanoid' },
+  { cell: { column: 3, row: 7 }, label: '89–103', category: 'actinoid' },
+];
+
+/** The period each inner-transition row belongs to, for its row label. */
+export const INNER_TRANSITION_ROWS: ReadonlyArray<{
+  row: number;
+  period: number;
+}> = [
+  { row: INNER_TRANSITION_ROW, period: 6 },
+  { row: INNER_TRANSITION_ROW + 1, period: 7 },
+];
+
+/**
+ * The element an arrow key walks to.
+ *
+ * The walk follows the grid, not the atomic number: down from carbon is
+ * silicon, the cell underneath it, and a step of 18 protons would instead be
+ * chromium because period 2 holds only eight elements. Left and right follow
+ * reading order, so the end of a period continues at the start of the next one
+ * and the two inner-transition rows come after the main block.
+ * @param key - The pressed key, as `KeyboardEvent.key` reports it.
+ * @param from - Symbol the walk starts at; any arrow lands on hydrogen when it names no element.
+ * @returns The element to move to, or `null` when the key is not an arrow or the table has no cell that way.
+ */
+export function elementByArrowKey(
+  key: string,
+  from: string | undefined,
+): PeriodicElement | null {
+  const direction = ARROW_DIRECTIONS[key];
+  if (direction === undefined) return null;
+
+  const placed = placedElements();
+  const start = from === undefined ? undefined : elementBySymbol(from);
+  if (start === undefined) return placed[0]?.element ?? null;
+
+  if (direction.column !== 0) {
+    const index = readingOrderIndex().get(start.symbol);
+    if (index === undefined) return null;
+    return placed[index + direction.column]?.element ?? null;
+  }
+
+  const cell = cellOf(start);
+  return byCell().get(cellKey(cell.column, cell.row + direction.row)) ?? null;
+}
+
+/** Which way each arrow key moves, in grid cells. */
+const ARROW_DIRECTIONS: Record<string, { column: number; row: number }> = {
+  ArrowRight: { column: 1, row: 0 },
+  ArrowLeft: { column: -1, row: 0 },
+  ArrowDown: { column: 0, row: 1 },
+  ArrowUp: { column: 0, row: -1 },
+};
+
+function readingOrderIndex(): Map<string, number> {
+  READING_ORDER ??= new Map(
+    placedElements().map(({ element }, index) => [element.symbol, index]),
+  );
+  return READING_ORDER;
+}
+
+let READING_ORDER: Map<string, number> | null = null;
+
+function byCell(): Map<string, PeriodicElement> {
+  BY_CELL ??= new Map(
+    placedElements().map(({ element, cell }) => [
+      cellKey(cell.column, cell.row),
+      element,
+    ]),
+  );
+  return BY_CELL;
+}
+
+let BY_CELL: Map<string, PeriodicElement> | null = null;
+
+function cellKey(column: number, row: number): string {
+  return `${String(column)}:${String(row)}`;
+}
+
+function innerTransitionCell(element: PeriodicElement): Cell | null {
+  for (const [index, start] of INNER_TRANSITION_STARTS.entries()) {
+    const offset = element.atomicNumber - start;
+    if (offset >= 0 && offset < INNER_TRANSITION_LENGTH) {
+      return {
+        column: INNER_TRANSITION_COLUMN + offset,
+        row: INNER_TRANSITION_ROW + index,
+      };
+    }
+  }
+  return null;
+}

package/src/periodic/ui/CategoryLegend.tsx

@@ -0,0 +1,105 @@
+/**
+ * The key to the family colours, under the table.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+
+import {
+  CATEGORY_LABELS,
+  CATEGORY_ORDER,
+  categorySwatch,
+} from '../core/categories.ts';
+import type { ElementCategory } from '../core/elements.ts';
+
+/** What {@link CategoryLegend} needs. */
+export interface CategoryLegendProps {
+  /**
+   * Called with the family whose swatch was clicked. Without it the legend is
+   * a key rather than a control, and nothing in it is focusable.
+   * @default undefined
+   */
+  onSelect?: (category: ElementCategory) => void;
+  /**
+   * The family drawn as the active one.
+   * @default undefined — none is
+   */
+  selected?: ElementCategory;
+}
+
+/**
+ * The ten families, each with its colour.
+ * @param props - See {@link CategoryLegendProps}.
+ * @returns The legend.
+ */
+export function CategoryLegend(props: CategoryLegendProps): ReactElement {
+  const { onSelect, selected } = props;
+
+  return (
+    <div style={legendStyle}>
+      {CATEGORY_ORDER.map((category) => {
+        const swatch = categorySwatch(category);
+        const label = CATEGORY_LABELS[category];
+        const mark = (
+          <span style={{ ...swatchStyle, background: swatch.background }} />
+        );
+        if (onSelect === undefined) {
+          return (
+            <span key={category} style={itemStyle}>
+              {mark}
+              {label}
+            </span>
+          );
+        }
+        return (
+          <button
+            key={category}
+            type="button"
+            aria-pressed={category === selected}
+            onClick={() => {
+              onSelect(category);
+            }}
+            style={{
+              ...itemStyle,
+              ...buttonStyle,
+              fontWeight: category === selected ? 700 : 400,
+            }}
+          >
+            {mark}
+            {label}
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+const legendStyle = {
+  color: 'rgb(95 107 124)',
+  display: 'flex',
+  flexWrap: 'wrap',
+  fontSize: 11,
+  gap: '2px 10px',
+} as const satisfies CSSProperties;
+
+const itemStyle = {
+  alignItems: 'center',
+  display: 'inline-flex',
+  gap: 4,
+} as const satisfies CSSProperties;
+
+const buttonStyle = {
+  background: 'none',
+  border: 'none',
+  color: 'inherit',
+  cursor: 'pointer',
+  font: 'inherit',
+  padding: 0,
+} as const satisfies CSSProperties;
+
+const swatchStyle = {
+  border: '1px solid rgb(255 255 255 / 0.55)',
+  borderRadius: 2,
+  display: 'inline-block',
+  height: 10,
+  width: 10,
+} as const satisfies CSSProperties;

package/src/periodic/ui/ElementCell.tsx

@@ -0,0 +1,137 @@
+/**
+ * One cell of the periodic table: the atomic number, the symbol, and whatever
+ * the tool asked to be written under it.
+ *
+ * A cell is a real `<button>`, so Tab reaches it, Enter and Space activate it,
+ * and a screen reader reads the element's name rather than its symbol.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { Swatch } from '../../color/core/scale.ts';
+
+/** What {@link ElementCell} needs to draw one element. */
+export interface ElementCellProps {
+  /** Atomic number, written small in the corner. */
+  atomicNumber: number;
+  /** Chemical symbol, the largest thing in the cell. */
+  symbol: string;
+  /** Full name, which is what the cell is announced as. */
+  name: string;
+  /** Background, and the ink that stays readable on it. */
+  swatch: Swatch;
+  /** Column of the grid, one-based. */
+  column: number;
+  /** Row of the grid, one-based. */
+  row: number;
+  onSelect: (symbol: string) => void;
+  /**
+   * Third line, under the symbol: the value the tool is showing.
+   * @default '' — nothing is written
+   */
+  detail?: string;
+  /**
+   * Whether the cell is the one the tools are pointed at.
+   * @default false
+   */
+  isSelected?: boolean;
+  /**
+   * Whether the cell is inside the set the tool is showing. Everything outside
+   * it is dimmed rather than removed, so the table keeps its shape.
+   * @default true
+   */
+  isIncluded?: boolean;
+  /**
+   * Called on pointer enter with the symbol, and on leave with `null`.
+   * @default undefined
+   */
+  onHover?: (symbol: string | null) => void;
+}
+
+/**
+ * A single element of the table.
+ * @param props - See {@link ElementCellProps}.
+ * @returns The cell.
+ */
+export function ElementCell(props: ElementCellProps): ReactElement {
+  const {
+    atomicNumber,
+    symbol,
+    name,
+    swatch,
+    column,
+    row,
+    onSelect,
+    detail = '',
+    isSelected = false,
+    isIncluded = true,
+    onHover,
+  } = props;
+
+  return (
+    <button
+      type="button"
+      data-testid={`element-${symbol}`}
+      data-symbol={symbol}
+      aria-label={`${name} (${symbol}, Z = ${String(atomicNumber)})`}
+      aria-pressed={isSelected}
+      onClick={() => {
+        onSelect(symbol);
+      }}
+      onPointerEnter={() => onHover?.(symbol)}
+      onPointerLeave={() => onHover?.(null)}
+      style={{
+        ...cellStyle,
+        gridColumn: column,
+        gridRow: row,
+        background: swatch.background,
+        color: swatch.foreground,
+        opacity: isIncluded ? 1 : 0.28,
+        // An outline rather than a fill: a table coloured by a property must
+        // keep saying what the value is while a cell is selected.
+        outline: isSelected ? `2px solid ${swatch.foreground}` : 'none',
+        outlineOffset: -3,
+      }}
+    >
+      <span style={numberStyle}>{atomicNumber}</span>
+      <span style={symbolStyle}>{symbol}</span>
+      {detail === '' ? null : <span style={detailStyle}>{detail}</span>}
+    </button>
+  );
+}
+
+const cellStyle = {
+  alignItems: 'center',
+  border: '1px solid rgb(255 255 255 / 0.55)',
+  borderRadius: 3,
+  cursor: 'pointer',
+  display: 'flex',
+  flexDirection: 'column',
+  font: 'inherit',
+  justifyContent: 'center',
+  lineHeight: 1.05,
+  minWidth: 0,
+  overflow: 'hidden',
+  padding: 1,
+  transition: 'opacity 120ms ease',
+} as const satisfies CSSProperties;
+
+const numberStyle = {
+  alignSelf: 'flex-start',
+  fontSize: 'clamp(0.34rem, 1.6cqw, 0.5rem)',
+  opacity: 0.8,
+  paddingLeft: 2,
+} as const satisfies CSSProperties;
+
+const symbolStyle = {
+  fontSize: 'clamp(0.55rem, 3.3cqw, 1.05rem)',
+  fontWeight: 700,
+} as const satisfies CSSProperties;
+
+const detailStyle = {
+  fontSize: 'clamp(0.34rem, 1.6cqw, 0.5rem)',
+  maxWidth: '100%',
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+} as const satisfies CSSProperties;

package/src/periodic/ui/PeriodicTable.tsx

@@ -0,0 +1,226 @@
+/**
+ * The periodic table.
+ *
+ * It knows nothing about what it is showing: the caller says what colour each
+ * cell takes and what is written in it, and gets back which element was
+ * clicked. That is what lets the same grid be an element picker, a property
+ * map, and a chart's selection control.
+ *
+ * Everything site-specific arrives through a callback keyed on the element, so
+ * a site's own richer element record never has to cross into this component.
+ */
+
+import type { CSSProperties, KeyboardEvent, ReactElement } from 'react';
+import { useEffect, useRef } from 'react';
+
+import type { Swatch } from '../../color/core/scale.ts';
+import { categorySwatch } from '../core/categories.ts';
+import type { PeriodicElement } from '../core/elements.ts';
+import type { ElementRange } from '../core/layout.ts';
+import {
+  COLUMN_COUNT,
+  elementByArrowKey,
+  placedElements,
+} from '../core/layout.ts';
+
+import { CategoryLegend } from './CategoryLegend.tsx';
+import { ElementCell } from './ElementCell.tsx';
+import {
+  HeaderStrips,
+  InnerTransitionMarkers,
+} from './PeriodicTableChrome.tsx';
+
+/** What {@link 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.
+   * @default undefined — the table is a figure rather than a control
+   */
+  onSelect?: (symbol: string) => 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;
+  /**
+   * 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;
+  /**
+   * Whether to draw the group and period strips.
+   * @default false
+   */
+  headers?: boolean;
+  /**
+   * Called when a whole group or period header is clicked. Without it the
+   * strips are labels rather than buttons.
+   * @default undefined
+   */
+  onSelectRange?: (range: ElementRange) => 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 table by atomic number.
+   * @default true
+   */
+  keyboard?: boolean;
+  /**
+   * Called on pointer enter with the symbol, and on leave with `null`.
+   * @default undefined
+   */
+  onHover?: (symbol: string | null) => void;
+}
+
+/**
+ * The 118 elements, laid out as the table.
+ * @param props - See {@link PeriodicTableProps}.
+ * @returns The grid, its optional chrome, and its optional legend.
+ */
+export function PeriodicTable(props: PeriodicTableProps): ReactElement {
+  const {
+    selected,
+    onSelect,
+    swatchOf = defaultSwatchOf,
+    detailOf,
+    nameOf = defaultNameOf,
+    isIncluded,
+    headers = false,
+    onSelectRange,
+    legend = false,
+    markers = true,
+    keyboard = true,
+    onHover,
+  } = props;
+
+  const gridRef = useRef<HTMLDivElement>(null);
+  const cameFromKeyRef = useRef(false);
+  const offset = headers ? 1 : 0;
+
+  useEffect(() => {
+    if (!cameFromKeyRef.current) return;
+    cameFromKeyRef.current = false;
+    const cell = gridRef.current?.querySelector<HTMLButtonElement>(
+      `[data-symbol="${CSS.escape(selected ?? '')}"]`,
+    );
+    cell?.focus();
+    cell?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+  }, [selected]);
+
+  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>): void {
+    if (!keyboard || onSelect === undefined) return;
+    const next = elementByArrowKey(event.key, selected);
+    if (next === null) return;
+    event.preventDefault();
+    cameFromKeyRef.current = true;
+    onSelect(next.symbol);
+  }
+
+  return (
+    <div style={rootStyle}>
+      <div
+        ref={gridRef}
+        role="grid"
+        aria-label="Periodic table"
+        data-testid="periodic-table"
+        style={headers ? gridWithHeadersStyle : gridStyle}
+        onKeyDown={handleKeyDown}
+      >
+        {headers ? <HeaderStrips onSelectRange={onSelectRange} /> : null}
+        {markers ? <InnerTransitionMarkers offset={offset} /> : null}
+        {placedElements().map(({ element, cell }) => (
+          <ElementCell
+            key={element.symbol}
+            atomicNumber={element.atomicNumber}
+            symbol={element.symbol}
+            name={nameOf(element)}
+            detail={detailOf?.(element)}
+            swatch={swatchOf(element)}
+            isSelected={element.symbol === selected}
+            isIncluded={isIncluded?.(element)}
+            column={cell.column + offset}
+            row={cell.row + offset}
+            onSelect={onSelect ?? noop}
+            onHover={onHover}
+          />
+        ))}
+      </div>
+      {legend ? <CategoryLegend /> : null}
+    </div>
+  );
+}
+
+function defaultSwatchOf(element: PeriodicElement): Swatch {
+  return categorySwatch(element.category);
+}
+
+function defaultNameOf(element: PeriodicElement): string {
+  return element.name;
+}
+
+function noop(): void {
+  // A table with no `onSelect` is a figure; its cells stay buttons so the
+  // keyboard and a screen reader still reach every element.
+}
+
+const rootStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const baseGridStyle = {
+  display: 'grid',
+  gap: 2,
+  width: '100%',
+  // The cells size their type against this box rather than against the page,
+  // so the same table reads at 320px beside a chart and at 900px on its own.
+  containerType: 'inline-size',
+} as const satisfies CSSProperties;
+
+const gridStyle = {
+  ...baseGridStyle,
+  // The eighth row is the gap the inner-transition series are lifted out into.
+  gridTemplateColumns: `repeat(${String(COLUMN_COUNT)}, minmax(0, 1fr))`,
+  gridTemplateRows:
+    'repeat(7, minmax(0, 1fr)) 0.5rem repeat(2, minmax(0, 1fr))',
+  aspectRatio: `${String(COLUMN_COUNT)} / 9.7`,
+  minWidth: 280,
+} as const satisfies CSSProperties;
+
+const gridWithHeadersStyle = {
+  ...baseGridStyle,
+  // A leading column and a leading row hold the period and group numbers.
+  gridTemplateColumns: `1.4rem repeat(${String(COLUMN_COUNT)}, minmax(0, 1fr))`,
+  gridTemplateRows:
+    '1rem repeat(7, minmax(0, 1fr)) 0.5rem repeat(2, minmax(0, 1fr))',
+  aspectRatio: `${String(COLUMN_COUNT + 1.2)} / 10.6`,
+  minWidth: 280,
+} as const satisfies CSSProperties;