react-cheminfo 0.6.0 → 0.8.0

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;

package/src/periodic/ui/PeriodicTableChrome.tsx

@@ -0,0 +1,170 @@
+/**
+ * The furniture around the cells: the group and period strips, and the two
+ * markers the inner-transition series were lifted out of.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { ElementRange } from '../core/layout.ts';
+import {
+  COLUMN_COUNT,
+  INNER_TRANSITION_MARKERS,
+  INNER_TRANSITION_ROWS,
+} from '../core/layout.ts';
+
+/** What {@link HeaderStrips} needs. */
+export interface HeaderStripsProps {
+  /**
+   * Called with the run whose header was clicked. Without it the strips are
+   * labels rather than buttons.
+   * @default undefined
+   */
+  onSelectRange?: (range: ElementRange) => void;
+}
+
+/**
+ * The 1–18 strip along the top and the 1–7 strip down the left.
+ *
+ * They are buttons when the table takes a range: "plot period 3" is one click
+ * there and eight on the cells.
+ * @param props - See {@link HeaderStripsProps}.
+ * @returns The two strips, placed on the grid.
+ */
+export function HeaderStrips(props: HeaderStripsProps): ReactElement {
+  const { onSelectRange } = props;
+  const groups: ReactElement[] = [];
+  for (let group = 1; group <= COLUMN_COUNT; group++) {
+    groups.push(
+      <HeaderCell
+        key={`group-${String(group)}`}
+        label={String(group)}
+        title={`Group ${String(group)}`}
+        column={group + 1}
+        row={1}
+        onClick={
+          onSelectRange &&
+          (() => {
+            onSelectRange({ kind: 'group', value: group });
+          })
+        }
+      />,
+    );
+  }
+  const periods: ReactElement[] = [];
+  for (let period = 1; period <= 7; period++) {
+    periods.push(
+      <HeaderCell
+        key={`period-${String(period)}`}
+        label={String(period)}
+        title={`Period ${String(period)}`}
+        column={1}
+        row={period + 1}
+        onClick={
+          onSelectRange &&
+          (() => {
+            onSelectRange({ kind: 'period', value: period });
+          })
+        }
+      />,
+    );
+  }
+
+  return (
+    <>
+      {groups}
+      {periods}
+      {INNER_TRANSITION_ROWS.map(({ row, period }) => (
+        <div
+          key={`inner-${String(row)}`}
+          style={{ ...headerStyle, gridColumn: 1, gridRow: row + 1 }}
+        >
+          {period}
+        </div>
+      ))}
+    </>
+  );
+}
+
+/** What {@link InnerTransitionMarkers} needs. */
+export interface InnerTransitionMarkersProps {
+  /** 1 when the table draws its header strips, 0 otherwise. */
+  offset: number;
+}
+
+/**
+ * The two cells the lanthanoids and the actinoids were lifted out of.
+ * @param props - See {@link InnerTransitionMarkersProps}.
+ * @returns The markers, placed on the grid.
+ */
+export function InnerTransitionMarkers(
+  props: InnerTransitionMarkersProps,
+): ReactElement {
+  const { offset } = props;
+  return (
+    <>
+      {INNER_TRANSITION_MARKERS.map(({ cell, label, category }) => (
+        <div
+          key={category}
+          aria-hidden="true"
+          style={{
+            ...markerStyle,
+            gridColumn: cell.column + offset,
+            gridRow: cell.row + offset,
+          }}
+        >
+          {label}
+        </div>
+      ))}
+    </>
+  );
+}
+
+interface HeaderCellProps {
+  label: string;
+  title: string;
+  column: number;
+  row: number;
+  onClick?: (() => void) | undefined;
+}
+
+function HeaderCell(props: HeaderCellProps): ReactElement {
+  const { label, title, column, row, onClick } = props;
+  const style = { ...headerStyle, gridColumn: column, gridRow: row };
+  if (onClick === undefined) return <div style={style}>{label}</div>;
+  return (
+    <button
+      type="button"
+      aria-label={title}
+      onClick={onClick}
+      style={{ ...style, ...headerButtonStyle }}
+    >
+      {label}
+    </button>
+  );
+}
+
+const headerStyle = {
+  alignItems: 'center',
+  color: 'rgb(95 107 124)',
+  display: 'flex',
+  fontSize: 'clamp(0.4rem, 1.9cqw, 0.62rem)',
+  justifyContent: 'center',
+  padding: 0,
+} as const satisfies CSSProperties;
+
+const headerButtonStyle = {
+  background: 'none',
+  border: 'none',
+  cursor: 'pointer',
+  font: 'inherit',
+} as const satisfies CSSProperties;
+
+const markerStyle = {
+  alignItems: 'center',
+  border: '1px dashed rgb(182 191 204)',
+  borderRadius: 3,
+  color: 'rgb(95 107 124)',
+  display: 'flex',
+  fontSize: 'clamp(0.36rem, 1.7cqw, 0.55rem)',
+  justifyContent: 'center',
+} as const satisfies CSSProperties;

package/src/periodic/ui/index.ts

@@ -0,0 +1,6 @@
+export type { CategoryLegendProps } from './CategoryLegend.tsx';
+export { CategoryLegend } from './CategoryLegend.tsx';
+export type { ElementCellProps } from './ElementCell.tsx';
+export { ElementCell } from './ElementCell.tsx';
+export type { PeriodicTableProps } from './PeriodicTable.tsx';
+export { PeriodicTable } from './PeriodicTable.tsx';

package/src/ui.ts

@@ -11,6 +11,7 @@ export * from './error/ui/index.ts';
 export * from './help/ui/index.ts';
 export * from './hooks/ui/index.ts';
 export * from './pedagogy/ui/index.ts';
+export * from './periodic/ui/index.ts';
 export * from './share/ui/index.ts';
 export * from './shared/ui/index.ts';
 export * from './state/ui/index.ts';