@classytic/stage 0.3.0 → 0.4.0

package/dist/atomic/emission.d.mts

@@ -0,0 +1,112 @@
+//#region src/atomic/emission.d.ts
+/**
+ * What an element emits when it is heated, as wavelengths rather than as a colour word.
+ *
+ * ## Why a spectrum and not a swatch
+ *
+ * A flame test is usually taught as a table of colour names: sodium golden yellow, barium apple
+ * green, potassium lilac. Those names are the end of the explanation rather than the start of one,
+ * and they cannot be checked. An electron falling between two levels emits a photon of a definite
+ * wavelength, and the colour is what the eye makes of the wavelengths that arrive. So this file
+ * holds the wavelengths, and the colour engine turns them into something to draw with. Neither
+ * file knows about the other: {@link emissionSpectrum} returns a plain function of wavelength,
+ * which is exactly the shape the colour engine already consumes.
+ *
+ * That also means the flame in a lab is the colour the element really emits, and a learner can be
+ * shown the lines that produced it.
+ *
+ * ## Not every flame colour is atomic, and pretending otherwise is wrong
+ *
+ * Sodium, lithium, potassium, rubidium and caesium glow from transitions in the free ATOM. The
+ * alkaline earths do not. Calcium, strontium and barium owe their flame colours largely to bands
+ * from the monohydroxide molecules CaOH, SrOH and BaOH formed in the flame, which is why their
+ * emission is broad where sodium's is a razor-thin pair of lines. Each entry records which it is,
+ * because "barium is green" and "a barium compound puts BaOH into the flame and that is green" are
+ * different statements and only the second explains anything.
+ *
+ * ## The lines you cannot see are the interesting ones
+ *
+ * Potassium's strongest emission is a pair of lines at 766 and 770 nm, which is infrared: the eye
+ * cannot see them at all. What is seen is a much weaker violet line at 404 nm, which is why
+ * potassium reads as a pale lilac rather than as the blazing colour its line strengths suggest.
+ * Caesium is the same story with its main output at 852 and 894 nm and a blue line at 455 nm doing
+ * all the visible work. Those lines are kept in the data with their real strengths, so the
+ * calculation has to discard them the way an eye does rather than having them quietly removed.
+ *
+ * Wavelengths are the standard measured values for these transitions. Relative strengths are
+ * approximate and are there to weight the mixture, not to be read as photometry.
+ *
+ * Pure: no React, no pixels. No dependency on the colour engine.
+ */
+/** Where a line comes from, because it changes what the flame test is evidence of. */
+type EmitterKind = 'atom' | 'molecule';
+interface EmissionLine {
+  /** Wavelength in nanometres. */
+  readonly nm: number;
+  /** Relative strength within this element's own spectrum, largest 1. */
+  readonly strength: number;
+  /**
+   * How wide the feature is, in nanometres.
+   *
+   * An atomic line is essentially a single wavelength and is given a nominal width so it can be
+   * integrated; a molecular band is genuinely broad, and drawing it as a line would misrepresent it.
+   */
+  readonly widthNm: number;
+}
+interface FlameEmitter {
+  readonly element: string;
+  /** The species that actually emits: the free atom, or the molecule formed in the flame. */
+  readonly emitter: string;
+  readonly kind: EmitterKind;
+  readonly lines: readonly EmissionLine[];
+  /** What the flame is conventionally called, kept so a computed colour can be compared with it. */
+  readonly describedAs: string;
+}
+/**
+ * The elements a flame test identifies.
+ *
+ * Keyed by the metal, since that is what the test detects: the anion plays no part, which is why
+ * sodium chloride and sodium carbonate give the same flame.
+ */
+declare const FLAME_EMITTERS: readonly FlameEmitter[];
+/** The flame emitter for a metal, or undefined if this engine has no data for it. */
+declare const flameEmitterFor: (element: string) => FlameEmitter | undefined;
+/**
+ * A set of lines as a continuous spectrum: intensity against wavelength.
+ *
+ * Each line is a Gaussian of its own width, so an atomic line comes out narrow and a molecular band
+ * broad. The return type is a plain function of wavelength, which is deliberately the same shape
+ * the colour engine takes, so the two compose without either importing the other.
+ */
+declare function emissionSpectrum(lines: readonly EmissionLine[]): (nm: number) => number;
+/** The spectrum of a metal's flame, ready to hand to the colour engine. */
+declare function flameSpectrum(element: string): (nm: number) => number;
+/**
+ * The range a line has to fall in to contribute anything a viewer can see, in nanometres.
+ *
+ * Deliberately narrower than the 380 to 780 often quoted as "the visible spectrum". The eye does
+ * not stop at a cliff: its response tails away, and by 700 nm it is under half a per cent of its
+ * peak. A line at 766 nm is inside the quoted range and contributes nothing whatsoever, so treating
+ * that range as a yes-or-no test called potassium's brightest lines visible when the whole point of
+ * them is that they are not.
+ *
+ * This is a threshold for a boolean question. The colour calculation does not use it at all: there
+ * the CIE curves weight every wavelength by how strongly the eye actually responds, which is the
+ * proper treatment and needs no cutoff.
+ */
+declare const VISIBLE_RANGE: {
+  readonly minNm: 380;
+  readonly maxNm: 700;
+};
+/** Whether a line lies in the range the eye responds to. */
+declare const isVisible: (line: EmissionLine) => boolean;
+/**
+ * The fraction of an element's emitted strength that the eye can see at all.
+ *
+ * Small for potassium and caesium, whose strongest output is infrared. Worth having as a number
+ * because "most of what potassium emits is invisible" is the explanation for why its flame looks
+ * so much fainter than its line strengths suggest.
+ */
+declare function visibleFraction(element: string): number;
+//#endregion
+export { EmissionLine, EmitterKind, FLAME_EMITTERS, FlameEmitter, VISIBLE_RANGE, emissionSpectrum, flameEmitterFor, flameSpectrum, isVisible, visibleFraction };

package/dist/atomic/emission.mjs

@@ -0,0 +1,179 @@
+//#region src/atomic/emission.ts
+const atom = (nm, strength) => ({
+	nm,
+	strength,
+	widthNm: 2
+});
+const band = (nm, strength, widthNm = 18) => ({
+	nm,
+	strength,
+	widthNm
+});
+/**
+* The elements a flame test identifies.
+*
+* Keyed by the metal, since that is what the test detects: the anion plays no part, which is why
+* sodium chloride and sodium carbonate give the same flame.
+*/
+const FLAME_EMITTERS = [
+	{
+		element: "Li",
+		emitter: "Li",
+		kind: "atom",
+		lines: [atom(670.8, 1), atom(610.4, .15)],
+		describedAs: "crimson"
+	},
+	{
+		element: "Na",
+		emitter: "Na",
+		kind: "atom",
+		lines: [atom(589, 1), atom(589.6, .9)],
+		describedAs: "golden yellow"
+	},
+	{
+		element: "K",
+		emitter: "K",
+		kind: "atom",
+		lines: [
+			atom(766.5, 1),
+			atom(769.9, .5),
+			atom(404.4, .06),
+			atom(404.7, .03)
+		],
+		describedAs: "lilac"
+	},
+	{
+		element: "Rb",
+		emitter: "Rb",
+		kind: "atom",
+		lines: [
+			atom(780, 1),
+			atom(794.8, .5),
+			atom(420.2, .05),
+			atom(421.6, .03)
+		],
+		describedAs: "red violet"
+	},
+	{
+		element: "Cs",
+		emitter: "Cs",
+		kind: "atom",
+		lines: [
+			atom(852.1, 1),
+			atom(894.3, .5),
+			atom(455.5, .05),
+			atom(459.3, .03)
+		],
+		describedAs: "blue"
+	},
+	{
+		element: "Ca",
+		emitter: "CaOH",
+		kind: "molecule",
+		lines: [
+			band(622, 1),
+			band(554, .7),
+			atom(422.7, .4)
+		],
+		describedAs: "brick red"
+	},
+	{
+		element: "Sr",
+		emitter: "SrOH",
+		kind: "molecule",
+		lines: [
+			band(682, 1, 22),
+			band(661, .8),
+			band(606, .5),
+			atom(460.7, .3)
+		],
+		describedAs: "crimson"
+	},
+	{
+		element: "Ba",
+		emitter: "BaOH",
+		kind: "molecule",
+		lines: [
+			band(524, 1, 20),
+			band(514, .8),
+			band(487, .3),
+			atom(553.5, .5)
+		],
+		describedAs: "apple green"
+	},
+	{
+		element: "Cu",
+		emitter: "CuCl",
+		kind: "molecule",
+		lines: [
+			band(535, 1, 24),
+			band(515, .8),
+			atom(510.6, .4),
+			atom(578.2, .3)
+		],
+		describedAs: "blue green"
+	}
+];
+const BY_ELEMENT = new Map(FLAME_EMITTERS.map((e) => [e.element, e]));
+/** The flame emitter for a metal, or undefined if this engine has no data for it. */
+const flameEmitterFor = (element) => BY_ELEMENT.get(element);
+/**
+* A set of lines as a continuous spectrum: intensity against wavelength.
+*
+* Each line is a Gaussian of its own width, so an atomic line comes out narrow and a molecular band
+* broad. The return type is a plain function of wavelength, which is deliberately the same shape
+* the colour engine takes, so the two compose without either importing the other.
+*/
+function emissionSpectrum(lines) {
+	return (nm) => {
+		let total = 0;
+		for (const line of lines) {
+			const sigma = line.widthNm / 2.3548;
+			const offset = (nm - line.nm) / sigma;
+			total += line.strength * Math.exp(-.5 * offset * offset);
+		}
+		return total;
+	};
+}
+/** The spectrum of a metal's flame, ready to hand to the colour engine. */
+function flameSpectrum(element) {
+	const emitter = flameEmitterFor(element);
+	if (!emitter) throw new Error(`no flame emission data for ${element}`);
+	return emissionSpectrum(emitter.lines);
+}
+/**
+* The range a line has to fall in to contribute anything a viewer can see, in nanometres.
+*
+* Deliberately narrower than the 380 to 780 often quoted as "the visible spectrum". The eye does
+* not stop at a cliff: its response tails away, and by 700 nm it is under half a per cent of its
+* peak. A line at 766 nm is inside the quoted range and contributes nothing whatsoever, so treating
+* that range as a yes-or-no test called potassium's brightest lines visible when the whole point of
+* them is that they are not.
+*
+* This is a threshold for a boolean question. The colour calculation does not use it at all: there
+* the CIE curves weight every wavelength by how strongly the eye actually responds, which is the
+* proper treatment and needs no cutoff.
+*/
+const VISIBLE_RANGE = {
+	minNm: 380,
+	maxNm: 700
+};
+/** Whether a line lies in the range the eye responds to. */
+const isVisible = (line) => line.nm >= VISIBLE_RANGE.minNm && line.nm <= VISIBLE_RANGE.maxNm;
+/**
+* The fraction of an element's emitted strength that the eye can see at all.
+*
+* Small for potassium and caesium, whose strongest output is infrared. Worth having as a number
+* because "most of what potassium emits is invisible" is the explanation for why its flame looks
+* so much fainter than its line strengths suggest.
+*/
+function visibleFraction(element) {
+	const emitter = flameEmitterFor(element);
+	if (!emitter) throw new Error(`no flame emission data for ${element}`);
+	const total = emitter.lines.reduce((sum, l) => sum + l.strength, 0);
+	const seen = emitter.lines.filter(isVisible).reduce((sum, l) => sum + l.strength, 0);
+	return total === 0 ? 0 : seen / total;
+}
+
+//#endregion
+export { FLAME_EMITTERS, VISIBLE_RANGE, emissionSpectrum, flameEmitterFor, flameSpectrum, isVisible, visibleFraction };

package/dist/atomic/index.d.mts

@@ -0,0 +1,8 @@
+import { ELECTRONS_PER_ORBITAL, QuantumNumbers, SUBSHELL_LETTERS, Shell, Subshell, SubshellLetter, isPauliValid, isValidQuantumNumbers, magneticNumbers, orbitalsInSubshell, orbitalsOf, quantumNumbersRefusal, shell, shellCapacity, shellLetter, subshell, subshellCapacity, subshellLetter, subshellsOf } from "./shells.mjs";
+import { ANOMALIES, Anomaly, Configuration, Occupancy, OrbitalBox, anomalyFor, aufbauConfiguration, condensedConfiguration, configurationOf, fillingOrder, formatConfiguration, ionConfigurationOf, occupancyLabel, orbitalDiagram, unpairedElectrons } from "./aufbau.mjs";
+import { Block, Family, GROUP_3_NOTE, Placement, TransitionVerdict, blockOf, familyOf, groupOf, isTransitionElement, periodOf, placementOf, romanGroupOf, transitionVerdict, valenceElectronsOf } from "./periodic.mjs";
+import { ELEMENTS, ElementRecord, MASS_INVERSIONS, elementByName, elementBySymbol, elementOf, symbolOf } from "./elements.mjs";
+import { EmissionLine, EmitterKind, FLAME_EMITTERS, FlameEmitter, VISIBLE_RANGE, emissionSpectrum, flameEmitterFor, flameSpectrum, isVisible, visibleFraction } from "./emission.mjs";
+import { ElementProperties, FIRST_ELECTRON_AFFINITY, NOBLE_GAS_RADIUS_NOTE, PROPERTIES, SUCCESSIVE_IONISATION_ENERGIES, covalentRadius, electronegativity, firstIonisationEnergy, propertiesOf } from "./properties.mjs";
+import { BondCharacter, DataPoint, Direction, IONISATION_ANOMALIES, IonisationAnomaly, PropertyName, ShellEvidence, Trend, acrossPeriod, bondBetween, bondCharacter, compareIonisationEnergy, downGroup, electronegativityGap, ionicCharacter, ionisationAnomalyFor, outerElectronsFromIonisation, outerElectronsOf, trendOf } from "./trends.mjs";
+export { ANOMALIES, type Anomaly, type Block, type BondCharacter, type Configuration, type DataPoint, type Direction, ELECTRONS_PER_ORBITAL, ELEMENTS, type ElementProperties, type ElementRecord, type EmissionLine, type EmitterKind, FIRST_ELECTRON_AFFINITY, FLAME_EMITTERS, type Family, type FlameEmitter, GROUP_3_NOTE, IONISATION_ANOMALIES, type IonisationAnomaly, MASS_INVERSIONS, NOBLE_GAS_RADIUS_NOTE, type Occupancy, type OrbitalBox, PROPERTIES, type Placement, type PropertyName, type QuantumNumbers, SUBSHELL_LETTERS, SUCCESSIVE_IONISATION_ENERGIES, type Shell, type ShellEvidence, type Subshell, type SubshellLetter, type TransitionVerdict, type Trend, VISIBLE_RANGE, acrossPeriod, anomalyFor, aufbauConfiguration, blockOf, bondBetween, bondCharacter, compareIonisationEnergy, condensedConfiguration, configurationOf, covalentRadius, downGroup, electronegativity, electronegativityGap, elementByName, elementBySymbol, elementOf, emissionSpectrum, familyOf, fillingOrder, firstIonisationEnergy, flameEmitterFor, flameSpectrum, formatConfiguration, groupOf, ionConfigurationOf, ionicCharacter, ionisationAnomalyFor, isPauliValid, isTransitionElement, isValidQuantumNumbers, isVisible, magneticNumbers, occupancyLabel, orbitalDiagram, orbitalsInSubshell, orbitalsOf, outerElectronsFromIonisation, outerElectronsOf, periodOf, placementOf, propertiesOf, quantumNumbersRefusal, romanGroupOf, shell, shellCapacity, shellLetter, subshell, subshellCapacity, subshellLetter, subshellsOf, symbolOf, transitionVerdict, trendOf, unpairedElectrons, valenceElectronsOf, visibleFraction };

package/dist/atomic/index.mjs

@@ -0,0 +1,9 @@
+import { ELECTRONS_PER_ORBITAL, SUBSHELL_LETTERS, isPauliValid, isValidQuantumNumbers, magneticNumbers, orbitalsInSubshell, orbitalsOf, quantumNumbersRefusal, shell, shellCapacity, shellLetter, subshell, subshellCapacity, subshellLetter, subshellsOf } from "./shells.mjs";
+import { ANOMALIES, anomalyFor, aufbauConfiguration, condensedConfiguration, configurationOf, fillingOrder, formatConfiguration, ionConfigurationOf, occupancyLabel, orbitalDiagram, unpairedElectrons } from "./aufbau.mjs";
+import { GROUP_3_NOTE, blockOf, familyOf, groupOf, isTransitionElement, periodOf, placementOf, romanGroupOf, transitionVerdict, valenceElectronsOf } from "./periodic.mjs";
+import { ELEMENTS, MASS_INVERSIONS, elementByName, elementBySymbol, elementOf, symbolOf } from "./elements.mjs";
+import { FLAME_EMITTERS, VISIBLE_RANGE, emissionSpectrum, flameEmitterFor, flameSpectrum, isVisible, visibleFraction } from "./emission.mjs";
+import { FIRST_ELECTRON_AFFINITY, NOBLE_GAS_RADIUS_NOTE, PROPERTIES, SUCCESSIVE_IONISATION_ENERGIES, covalentRadius, electronegativity, firstIonisationEnergy, propertiesOf } from "./properties.mjs";
+import { IONISATION_ANOMALIES, acrossPeriod, bondBetween, bondCharacter, compareIonisationEnergy, downGroup, electronegativityGap, ionicCharacter, ionisationAnomalyFor, outerElectronsFromIonisation, outerElectronsOf, trendOf } from "./trends.mjs";
+
+export { ANOMALIES, ELECTRONS_PER_ORBITAL, ELEMENTS, FIRST_ELECTRON_AFFINITY, FLAME_EMITTERS, GROUP_3_NOTE, IONISATION_ANOMALIES, MASS_INVERSIONS, NOBLE_GAS_RADIUS_NOTE, PROPERTIES, SUBSHELL_LETTERS, SUCCESSIVE_IONISATION_ENERGIES, VISIBLE_RANGE, acrossPeriod, anomalyFor, aufbauConfiguration, blockOf, bondBetween, bondCharacter, compareIonisationEnergy, condensedConfiguration, configurationOf, covalentRadius, downGroup, electronegativity, electronegativityGap, elementByName, elementBySymbol, elementOf, emissionSpectrum, familyOf, fillingOrder, firstIonisationEnergy, flameEmitterFor, flameSpectrum, formatConfiguration, groupOf, ionConfigurationOf, ionicCharacter, ionisationAnomalyFor, isPauliValid, isTransitionElement, isValidQuantumNumbers, isVisible, magneticNumbers, occupancyLabel, orbitalDiagram, orbitalsInSubshell, orbitalsOf, outerElectronsFromIonisation, outerElectronsOf, periodOf, placementOf, propertiesOf, quantumNumbersRefusal, romanGroupOf, shell, shellCapacity, shellLetter, subshell, subshellCapacity, subshellLetter, subshellsOf, symbolOf, transitionVerdict, trendOf, unpairedElectrons, valenceElectronsOf, visibleFraction };

package/dist/atomic/periodic.d.mts

@@ -0,0 +1,82 @@
+import { Configuration } from "./aufbau.mjs";
+
+//#region src/atomic/periodic.d.ts
+type Block = 's' | 'p' | 'd' | 'f';
+/** The disagreement about group 3, carried as text so a lesson can show it. */
+declare const GROUP_3_NOTE = "Group 3 is unsettled. Deriving it from the filling order puts lutetium and lawrencium there, which agrees with a 2021 IUPAC provisional recommendation and makes the f-block a clean fourteen elements wide. Most syllabuses and wall charts print lanthanum and actinium there instead. Both arrangements are defended in the literature, so a lesson should show the disagreement rather than teach one as settled.";
+/**
+ * The period, which is the ROW of the table rather than the highest occupied shell.
+ *
+ * Those two are not the same, and taking the shell was the first version's bug. Palladium is
+ * [Kr] 4d¹⁰ with nothing at all in its fifth shell, yet it sits in period 5: a d subshell is filled
+ * one row below its own shell number, and an f subshell two rows below. So the row is n for an s or
+ * p subshell, n+1 for a d, and n+2 for an f, which is exactly the offset that makes the table's
+ * blocks line up.
+ */
+declare function periodOf(Z: number): number;
+/**
+ * The block, from the subshell the last electron enters.
+ *
+ * Read off the FILLING order, not the written order: potassium's last electron goes into 4s even
+ * though 3d is written before 4s for later elements, so potassium is s-block.
+ */
+declare function blockOf(Z: number): Block;
+/**
+ * The group, in the modern 1 to 18 numbering.
+ *
+ * f-block elements are all reported as group 3, which is the convention: they sit in the same
+ * column of the main table and are drawn out beneath it.
+ */
+declare function groupOf(Z: number): number;
+/**
+ * The older group label still used by many syllabuses: IA, IIA, VIIB, VIII, 0.
+ *
+ * Kept because a learner meeting "group VIII" in a past paper and "group 8" in a data booklet needs
+ * to know they are the same column. Groups 8, 9 and 10 share the single label VIII, which is why
+ * the old system ran out of numbers and was replaced.
+ */
+declare function romanGroupOf(Z: number): string;
+interface TransitionVerdict {
+  readonly isTransition: boolean;
+  /** The reason, in the terms the definition is written in. */
+  readonly reason: string;
+}
+/**
+ * Whether an element is a transition element, and why.
+ *
+ * Returns the reasoning because "why is zinc not a transition element" and "why is copper one
+ * despite a full d subshell" are the questions this definition exists to answer, and a boolean
+ * answers neither.
+ */
+declare function transitionVerdict(Z: number): TransitionVerdict;
+/** Whether an element is a transition element by the IUPAC definition. */
+declare const isTransitionElement: (Z: number) => boolean;
+type Family = 'alkali metal' | 'alkaline earth metal' | 'transition element' | 'lanthanide' | 'actinide' | 'halogen' | 'noble gas' | 'other metal' | 'other nonmetal';
+/**
+ * The family an element belongs to.
+ *
+ * Hydrogen is reported as a nonmetal rather than an alkali metal: it sits above group 1 because it
+ * has one s electron, and it behaves nothing like sodium.
+ */
+declare function familyOf(Z: number): Family;
+interface Placement {
+  readonly Z: number;
+  readonly period: number;
+  readonly group: number;
+  /** The older label: IA, VIII, 0. */
+  readonly romanGroup: string;
+  readonly block: Block;
+  readonly family: Family;
+  readonly configuration: Configuration;
+}
+/** Everything about where an element sits, from its proton number alone. */
+declare function placementOf(Z: number): Placement;
+/**
+ * The valence electrons: those outside the noble-gas core that take part in bonding.
+ *
+ * For a d-block element this counts the d electrons too, because they are close enough in energy to
+ * be lost, which is why iron has both a +2 and a +3 state and sodium has only +1.
+ */
+declare function valenceElectronsOf(Z: number): number;
+//#endregion
+export { Block, Family, GROUP_3_NOTE, Placement, TransitionVerdict, blockOf, familyOf, groupOf, isTransitionElement, periodOf, placementOf, romanGroupOf, transitionVerdict, valenceElectronsOf };

package/dist/atomic/periodic.mjs

@@ -0,0 +1,231 @@
+import { subshellLetter } from "./shells.mjs";
+import { aufbauConfiguration, configurationOf, fillingOrder, occupancyLabel } from "./aufbau.mjs";
+
+//#region src/atomic/periodic.ts
+/**
+* Where an element sits in the periodic table, worked out from its electrons.
+*
+* ## Nothing here is looked up
+*
+* Block, group, period and classification are printed in every book as a coloured chart to be read
+* off. They are not data. They are consequences of the electron configuration, which the aufbau
+* engine already computes, so this file stores no table and answers for any proton number:
+*
+*     period  = the highest occupied shell
+*     block   = the subshell the LAST electron entered, in filling order
+*     group   = counted from the electrons outside the noble-gas core
+*
+* The group rule is one line per block and is worth stating because it is usually left implicit.
+* An s-block element's group is its number of ns electrons. A p-block element's is 10 + its outer
+* s and p electrons, which is why carbon (2s² 2p²) is group 14. A d-block element's is its d
+* electrons plus its s electrons, which is why iron (3d⁶ 4s²) is group 8, and why chromium is still
+* group 6 despite its anomalous 3d⁵ 4s¹.
+*
+* ## The transition-element definition, applied properly
+*
+* IUPAC defines a transition element as one whose atom has an incomplete d subshell, OR which can
+* give rise to a cation with an incomplete d subshell. That second clause is the whole substance of
+* it and is usually dropped:
+*
+*   copper's atom is 3d¹⁰ 4s¹, a COMPLETE d subshell, yet Cu²⁺ is 3d⁹, so copper is a transition
+*   element, which is why its compounds are coloured;
+*
+*   zinc's atom is 3d¹⁰ 4s² and its only common ion, Zn²⁺, is also 3d¹⁰, so zinc is NOT one, which
+*   is why zinc compounds are white.
+*
+* So the test is applied to the ions as well as the atom, and group 12 is named as the exception it
+* is, with the reason, rather than silently special-cased.
+*
+* ## Where group 3 is contested, and this says so
+*
+* Whether lanthanum or lutetium belongs in group 3 is genuinely unsettled. Deriving it from the
+* filling order lands on lutetium and lawrencium, which is IUPAC's 2021 provisional recommendation;
+* most syllabuses and wall charts print lanthanum and actinium there instead. The derivation is not
+* adjusted to match the more common chart, because an engine that quietly agrees with whichever
+* answer is expected is no use for showing that the question is open. {@link GROUP_3_NOTE} carries
+* the disagreement so a lesson can put both arrangements in front of a learner.
+*
+* Pure: no React, no pixels.
+*/
+/** The disagreement about group 3, carried as text so a lesson can show it. */
+const GROUP_3_NOTE = "Group 3 is unsettled. Deriving it from the filling order puts lutetium and lawrencium there, which agrees with a 2021 IUPAC provisional recommendation and makes the f-block a clean fourteen elements wide. Most syllabuses and wall charts print lanthanum and actinium there instead. Both arrangements are defended in the literature, so a lesson should show the disagreement rather than teach one as settled.";
+/**
+* The subshell the last electron enters, by the UNPERTURBED filling order.
+*
+* The plain aufbau prediction is used here, not the anomalous ground state, because block and
+* period are about which column and row an element occupies and those do not move when one electron
+* shifts. Chromium is in the same column as molybdenum whether or not its 4s electron has hopped
+* into 3d, and cerium is a lanthanide even though its real configuration has a 5d electron in it.
+*/
+function lastSubshellFilled(Z) {
+	if (Z < 1) throw new Error(`proton number must be at least 1, got ${Z}`);
+	const held = new Map(aufbauConfiguration(Z).map((o) => [occupancyLabel(o), o.electrons]));
+	let last;
+	let counted = 0;
+	for (const candidate of fillingOrder()) {
+		const electrons = held.get(occupancyLabel(candidate)) ?? 0;
+		if (electrons === 0) continue;
+		counted += electrons;
+		last = candidate;
+		if (counted >= Z) break;
+	}
+	if (!last) throw new Error(`no configuration for Z=${Z}`);
+	return last;
+}
+/**
+* The period, which is the ROW of the table rather than the highest occupied shell.
+*
+* Those two are not the same, and taking the shell was the first version's bug. Palladium is
+* [Kr] 4d¹⁰ with nothing at all in its fifth shell, yet it sits in period 5: a d subshell is filled
+* one row below its own shell number, and an f subshell two rows below. So the row is n for an s or
+* p subshell, n+1 for a d, and n+2 for an f, which is exactly the offset that makes the table's
+* blocks line up.
+*/
+function periodOf(Z) {
+	const { n, l } = lastSubshellFilled(Z);
+	return n + (l >= 2 ? l - 1 : 0);
+}
+/**
+* The block, from the subshell the last electron enters.
+*
+* Read off the FILLING order, not the written order: potassium's last electron goes into 4s even
+* though 3d is written before 4s for later elements, so potassium is s-block.
+*/
+function blockOf(Z) {
+	return subshellLetter(lastSubshellFilled(Z).l);
+}
+/** Outer-shell electrons: those in the highest occupied shell. */
+function outerElectrons(configuration, period) {
+	return configuration.filter((o) => o.n === period).reduce((total, o) => total + o.electrons, 0);
+}
+/** Electrons in the d subshell one shell below the outermost, which is what a d-block element has. */
+function dElectrons(configuration, period) {
+	return configuration.find((o) => o.n === period - 1 && o.l === 2)?.electrons ?? 0;
+}
+/**
+* The group, in the modern 1 to 18 numbering.
+*
+* f-block elements are all reported as group 3, which is the convention: they sit in the same
+* column of the main table and are drawn out beneath it.
+*/
+function groupOf(Z) {
+	const configuration = configurationOf(Z);
+	const period = periodOf(Z);
+	const block = blockOf(Z);
+	if (Z === 2) return 18;
+	if (block === "f") return 3;
+	if (block === "s") return outerElectrons(configuration, period);
+	if (block === "p") return 10 + outerElectrons(configuration, period);
+	return dElectrons(configuration, period) + outerElectrons(configuration, period);
+}
+/**
+* The older group label still used by many syllabuses: IA, IIA, VIIB, VIII, 0.
+*
+* Kept because a learner meeting "group VIII" in a past paper and "group 8" in a data booklet needs
+* to know they are the same column. Groups 8, 9 and 10 share the single label VIII, which is why
+* the old system ran out of numbers and was replaced.
+*/
+function romanGroupOf(Z) {
+	const group = groupOf(Z);
+	if (group === 18) return "0";
+	if (group >= 8 && group <= 10) return "VIII";
+	const numeral = [
+		"I",
+		"II",
+		"III",
+		"IV",
+		"V",
+		"VI",
+		"VII"
+	];
+	if (group <= 2) return `${numeral[group - 1]}A`;
+	if (group <= 7) return `${numeral[group - 3]}B`;
+	if (group === 11) return "IB";
+	if (group === 12) return "IIB";
+	return `${numeral[group - 11]}A`;
+}
+/**
+* d-block groups whose elements are NOT transition elements, with the reason.
+*
+* Listed rather than derived, for the same reason the aufbau anomalies are: it rests on which ions
+* actually form, which the electron-filling rules do not predict. Group 12 loses only its two s
+* electrons, so every common compound of zinc, cadmium and mercury has a full d subshell.
+*/
+const NON_TRANSITION_GROUPS = { 12: "its only common ions lose the two s electrons and keep a full d¹⁰ subshell, so no ordinary compound of it has a partly filled d subshell, which is why these compounds are white rather than coloured" };
+/**
+* Whether an element is a transition element, and why.
+*
+* Returns the reasoning because "why is zinc not a transition element" and "why is copper one
+* despite a full d subshell" are the questions this definition exists to answer, and a boolean
+* answers neither.
+*/
+function transitionVerdict(Z) {
+	const block = blockOf(Z);
+	if (block !== "d") return {
+		isTransition: false,
+		reason: `it is a ${block}-block element and has no d subshell being filled`
+	};
+	const period = periodOf(Z);
+	const atomD = dElectrons(configurationOf(Z), period);
+	const excluded = NON_TRANSITION_GROUPS[groupOf(Z)];
+	if (excluded) return {
+		isTransition: false,
+		reason: excluded
+	};
+	if (atomD >= 1 && atomD <= 9) return {
+		isTransition: true,
+		reason: `its atom has a partly filled d subshell, d${atomD}`
+	};
+	return {
+		isTransition: true,
+		reason: "its atom has a full d¹⁰ subshell, but it forms an ion with a partly filled d subshell, which is what the definition asks for and is why its compounds are coloured"
+	};
+}
+/** Whether an element is a transition element by the IUPAC definition. */
+const isTransitionElement = (Z) => transitionVerdict(Z).isTransition;
+/**
+* The family an element belongs to.
+*
+* Hydrogen is reported as a nonmetal rather than an alkali metal: it sits above group 1 because it
+* has one s electron, and it behaves nothing like sodium.
+*/
+function familyOf(Z) {
+	if (Z === 1) return "other nonmetal";
+	const block = blockOf(Z);
+	const group = groupOf(Z);
+	if (group === 18) return "noble gas";
+	if (block === "f") return periodOf(Z) === 6 ? "lanthanide" : "actinide";
+	if (block === "d") return isTransitionElement(Z) ? "transition element" : "other metal";
+	if (group === 1) return "alkali metal";
+	if (group === 2) return "alkaline earth metal";
+	if (group === 17) return "halogen";
+	return (configurationOf(Z).find((o) => o.n === periodOf(Z) && o.l === 1)?.electrons ?? 0) <= periodOf(Z) - 2 ? "other metal" : "other nonmetal";
+}
+/** Everything about where an element sits, from its proton number alone. */
+function placementOf(Z) {
+	return {
+		Z,
+		period: periodOf(Z),
+		group: groupOf(Z),
+		romanGroup: romanGroupOf(Z),
+		block: blockOf(Z),
+		family: familyOf(Z),
+		configuration: configurationOf(Z)
+	};
+}
+/**
+* The valence electrons: those outside the noble-gas core that take part in bonding.
+*
+* For a d-block element this counts the d electrons too, because they are close enough in energy to
+* be lost, which is why iron has both a +2 and a +3 state and sodium has only +1.
+*/
+function valenceElectronsOf(Z) {
+	const configuration = configurationOf(Z);
+	const period = periodOf(Z);
+	const block = blockOf(Z);
+	const outer = outerElectrons(configuration, period);
+	return block === "d" ? outer + dElectrons(configuration, period) : outer;
+}
+
+//#endregion
+export { GROUP_3_NOTE, blockOf, familyOf, groupOf, isTransitionElement, periodOf, placementOf, romanGroupOf, transitionVerdict, valenceElectronsOf };