react-cheminfo 0.29.0 → 0.30.0

package/src/chrome/ui/AccountButton.tsx

@@ -0,0 +1,185 @@
+import { Menu, MenuDivider, MenuItem, PopoverNext } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
+import { NavLink } from './NavLink.tsx';
+import type { NavItem } from './navItem.ts';
+import { isModifiedClick } from './navItem.ts';
+
+/** Who the site is answering to. */
+export interface AccountIdentity {
+  /** What the person is called on screen. */
+  name: string;
+  /**
+   * What tells the account apart under that name — the address it is held at,
+   * the handle it was opened with.
+   * @default undefined
+   */
+  detail?: string;
+  /**
+   * The letters the mark is drawn with.
+   * @default the first letter of each of the first two words of `name`
+   */
+  initials?: string;
+}
+
+export interface AccountButtonProps {
+  /** Who is signed in, or `null` when nobody is. */
+  identity: AccountIdentity | null;
+  /**
+   * Whether the site has not heard back yet. Neither state is drawn until it
+   * has: a bar that offers to sign in and then turns into a name has told the
+   * visitor something false, and it is the state they act on first.
+   * @default false
+   */
+  loading?: boolean;
+  /**
+   * The address signing in happens at, for a site with a page of its own for
+   * it. Writing it keeps the entry a real link, so a middle click opens a tab.
+   * @default undefined
+   */
+  signInHref?: string;
+  /**
+   * What the site does when the invitation is picked — route to that page, or
+   * open a credentials dialog for a site that has no page.
+   * @default undefined
+   */
+  onSignIn?: () => void;
+  /**
+   * What the site does when Sign out is picked.
+   * @default undefined
+   */
+  onSignOut?: () => void;
+  /**
+   * What the invitation reads, for a site whose accounts are for one kind of
+   * person — "Teacher sign in". Two words: it is written out in the bar rather
+   * than folded into a glyph.
+   * @default the chrome's own word for it, in the language of the page
+   */
+  signInLabel?: string;
+  /**
+   * The account's own pages, listed above Sign out — a profile, a settings
+   * page.
+   * @default undefined
+   */
+  items?: readonly NavItem[];
+}
+
+/**
+ * The one utility of the bar that says who the site is answering to: an
+ * invitation when nobody is signed in, and the account's mark when somebody is.
+ *
+ * The two states are told apart by whether an identity is on screen, never by
+ * the direction of an arrow. Blueprint's `log-in` and `log-out` are the same
+ * arrow either side of the same door, and at 14 px among four other monochrome
+ * glyphs nobody reads which side it is on — a site drawing one reports the
+ * visitor as signed in while they are signed out. So the invitation is the
+ * words `Sign in`, which no mark can be mistaken for, and being signed in is
+ * the person's own initials.
+ * @param props - Who is signed in, what signing in and out do, and the pages
+ * the account's menu lists.
+ * @returns The entry, or nothing while the site is still asking.
+ */
+export function AccountButton(props: AccountButtonProps): ReactElement | null {
+  const {
+    identity,
+    loading = false,
+    signInHref,
+    onSignIn,
+    onSignOut,
+    signInLabel,
+    items = [],
+  } = props;
+  const t = useChromeT();
+
+  if (loading) {
+    // The width of the mark, so the bar does not jump when the answer lands.
+    return <span className="account-button__pending" aria-hidden="true" />;
+  }
+
+  if (identity === null) {
+    return (
+      <NavLink
+        className="account-button account-button--out"
+        item={{
+          id: 'account',
+          label: signInLabel ?? t('account.signIn'),
+          href: signInHref,
+          onSelect: onSignIn,
+        }}
+      />
+    );
+  }
+
+  const { name, detail, initials = initialsOf(name) } = identity;
+
+  return (
+    <PopoverNext
+      placement="bottom-end"
+      content={
+        <Menu className="nav-menu account-menu">
+          <li className="account-menu__identity">
+            <span className="account-menu__name">{name}</span>
+            {detail === undefined ? null : (
+              <span className="account-menu__detail">{detail}</span>
+            )}
+          </li>
+          <MenuDivider />
+          {items.map((item) => (
+            <MenuItem
+              key={item.id}
+              icon={item.icon}
+              text={item.label}
+              href={item.href}
+              target={item.external ? '_blank' : undefined}
+              onClick={(event) => {
+                if (item.onSelect === undefined || isModifiedClick(event)) {
+                  return;
+                }
+                event.preventDefault();
+                item.onSelect();
+              }}
+            />
+          ))}
+          {items.length === 0 ? null : <MenuDivider />}
+          <MenuItem
+            icon="log-out"
+            text={t('account.signOut')}
+            onClick={onSignOut}
+          />
+        </Menu>
+      }
+    >
+      <button
+        type="button"
+        className="nav-link nav-link--icon account-button account-button--in"
+        title={t('account.signedInAs', { name })}
+        aria-label={t('account.signedInAs', { name })}
+      >
+        <span className="account-mark">{initials}</span>
+      </button>
+    </PopoverNext>
+  );
+}
+
+/**
+ * The letters a name is marked with: the first of each of its first two words,
+ * or the first two letters of a name written as one word.
+ * @param name - What the person is called.
+ * @returns One or two letters, in capitals.
+ */
+function initialsOf(name: string): string {
+  const [first, second] = name.split(/\s+/).filter((word) => word !== '');
+  if (first === undefined) return '?';
+  if (second === undefined) return firstWordInitials(first);
+  return `${first.charAt(0)}${second.charAt(0)}`.toUpperCase();
+}
+
+// A single word is usually a handle or an address, where the two letters say
+// more than one does — but never the part after the `@`, which every account
+// on the same domain would share.
+function firstWordInitials(word: string): string {
+  const [local = ''] = word.split('@');
+  return (local === '' ? word : local).slice(0, 2).toUpperCase();
+}

package/src/chrome/ui/index.ts

@@ -1,3 +1,5 @@
+export type { AccountButtonProps, AccountIdentity } from './AccountButton.tsx';
+export { AccountButton } from './AccountButton.tsx';
 export type { HeaderToggleOption, HeaderToggleProps } from './HeaderToggle.tsx';
 export { HeaderToggle } from './HeaderToggle.tsx';
 export type { NavItem } from './navItem.ts';

package/src/clipboard/ui/ClickToCopy.tsx

@@ -71,6 +71,12 @@ export interface ClickToCopyProps {
    * @default undefined
    */
   style?: CSSProperties;
+  /**
+   * `data-testid` the element carries, so an end-to-end suite can select the
+   * value without depending on the text inside it.
+   * @default undefined
+   */
+  testId?: string;
 }
 
 /** Past this length the value is left out of the title: a molfile is no tooltip. */
@@ -106,13 +112,14 @@ export function ClickToCopy(props: ClickToCopyProps): ReactElement {
     disabled = false,
     className,
     style,
+    testId,
   } = props;
   const t = useChromeT();
   const { copied, failed, copy } = useCopyToClipboard();
 
   if (disabled) {
     return (
-      <Element className={className} style={style}>
+      <Element className={className} style={style} data-testid={testId}>
         {children}
       </Element>
     );
@@ -138,6 +145,7 @@ export function ClickToCopy(props: ClickToCopyProps): ReactElement {
         className,
       )}
       style={style}
+      data-testid={testId}
       role={focusable && !CELLS.has(Element) ? 'button' : undefined}
       tabIndex={focusable ? 0 : undefined}
       title={title ?? copyTitle(value, label, t)}

package/src/locales/de.json

@@ -1,6 +1,9 @@
 {
   "language.label": "Sprache",
   "chrome.pages": "Seiten",
+  "account.signIn": "Anmelden",
+  "account.signOut": "Abmelden",
+  "account.signedInAs": "Angemeldet als {name}",
   "ecosystem.tools": "Werkzeuge",
   "ecosystem.menuHeading": "Unsere Werkzeuge, alle im Browser",
   "ecosystem.otherTools": "Unsere weiteren Werkzeuge",

package/src/locales/en.json

@@ -1,6 +1,9 @@
 {
   "language.label": "Language",
   "chrome.pages": "Pages",
+  "account.signIn": "Sign in",
+  "account.signOut": "Sign out",
+  "account.signedInAs": "Signed in as {name}",
   "ecosystem.tools": "Tools",
   "ecosystem.menuHeading": "Our tools, all in the browser",
   "ecosystem.otherTools": "Our other tools",

package/src/locales/es.json

@@ -1,6 +1,9 @@
 {
   "language.label": "Idioma",
   "chrome.pages": "Páginas",
+  "account.signIn": "Iniciar sesión",
+  "account.signOut": "Cerrar sesión",
+  "account.signedInAs": "Sesión iniciada como {name}",
   "ecosystem.tools": "Herramientas",
   "ecosystem.menuHeading": "Nuestras herramientas, todas en el navegador",
   "ecosystem.otherTools": "Nuestras otras herramientas",

package/src/locales/fr.json

@@ -1,6 +1,9 @@
 {
   "language.label": "Langue",
   "chrome.pages": "Pages",
+  "account.signIn": "Se connecter",
+  "account.signOut": "Se déconnecter",
+  "account.signedInAs": "Connecté comme {name}",
   "ecosystem.tools": "Outils",
   "ecosystem.menuHeading": "Nos outils, tous dans le navigateur",
   "ecosystem.otherTools": "Nos autres outils",

package/src/structure/core/conformerBoltzmann.ts

@@ -0,0 +1,102 @@
+/**
+ * How a set of conformers divides itself between its minima at a temperature.
+ *
+ * Each conformer in the list is one minimum of the surface, so the share of
+ * molecules sitting in it is its Boltzmann factor over the sum of them all.
+ * Mirror-image conformers are separate entries and therefore counted twice,
+ * which is right: they are two distinct microstates, and that is what makes
+ * butane two-thirds gauche at room temperature rather than one-half.
+ *
+ * What this is not: a free energy. The weights come from a single energy per
+ * conformer, with no vibrational entropy, no zero-point energy and no solvent,
+ * so a share is the shape of the answer rather than the answer. It is also only
+ * as good as the energies handed to it — see {@link boltzmannConfidence}, which
+ * is what a table showing these shares says out loud.
+ */
+
+/** Room temperature, in kelvin, and what a share is quoted at unless asked otherwise. */
+export const ROOM_TEMPERATURE = 300;
+
+/**
+ * The gas constant in kcal/(mol·K), matching MMFF94's own energy unit.
+ *
+ * At {@link ROOM_TEMPERATURE} this makes RT 0.596 kcal/mol, so a conformer one
+ * kcal/mol up is populated about a fifth as much as the lowest.
+ */
+export const GAS_CONSTANT = 0.001_987_204_259;
+
+/**
+ * The share of molecules in each conformer at thermal equilibrium.
+ *
+ * The energies are taken relative to whichever is lowest, so they may be
+ * absolute or already relative. A conformer whose energy is unknown takes no
+ * share and is left out of the sum: it cannot be placed on the surface, and
+ * spreading the remainder over the others is a smaller lie than inventing a
+ * weight for it.
+ * @param energies - One energy per conformer in kcal/mol, `null` where unknown.
+ * @param temperature - Temperature in kelvin.
+ * @default ROOM_TEMPERATURE
+ * @returns One share per conformer, from 0 to 1 and summing to 1 over the ones
+ * that have an energy; `null` wherever the energy was `null`.
+ */
+export function boltzmannShares(
+  energies: ReadonlyArray<number | null>,
+  temperature: number = ROOM_TEMPERATURE,
+): Array<number | null> {
+  const shares: Array<number | null> = new Array(energies.length).fill(null);
+  if (energies.length === 0) return shares;
+
+  let lowest = Number.POSITIVE_INFINITY;
+  for (const energy of energies) {
+    if (energy !== null && Number.isFinite(energy) && energy < lowest) {
+      lowest = energy;
+    }
+  }
+  if (lowest === Number.POSITIVE_INFINITY) return shares;
+
+  // Measured from the lowest, so every exponent is at most zero and the sum
+  // cannot overflow however far apart the energies are.
+  const rt = GAS_CONSTANT * temperature;
+  if (!(rt > 0)) return shares;
+
+  const factors: Array<number | null> = new Array(energies.length).fill(null);
+  let total = 0;
+  for (let index = 0; index < energies.length; index++) {
+    const energy = energies[index] ?? null;
+    if (energy === null || !Number.isFinite(energy)) continue;
+    const factor = Math.exp(-(energy - lowest) / rt);
+    factors[index] = factor;
+    total += factor;
+  }
+  if (total === 0) return shares;
+
+  for (let index = 0; index < factors.length; index++) {
+    const factor = factors[index] ?? null;
+    if (factor !== null) shares[index] = factor / total;
+  }
+  return shares;
+}
+
+/**
+ * The factor a share is uncertain by, given how well the energies behind it are
+ * known.
+ *
+ * A population is exponential in the energy gap, so an error in a relative
+ * energy is an error in a share by `exp(error / RT)` — and RT is 0.596 kcal/mol
+ * at {@link ROOM_TEMPERATURE}. A force field that ranks conformers to within
+ * about 1.5 kcal/mol therefore places a population to within a factor of
+ * roughly twelve, which is why a share read off one is a shape and not a
+ * number.
+ * @param energyError - The typical error of a relative energy, kcal/mol.
+ * @param temperature - Temperature in kelvin.
+ * @default ROOM_TEMPERATURE
+ * @returns The multiplicative factor, at least 1.
+ */
+export function boltzmannConfidence(
+  energyError: number,
+  temperature: number = ROOM_TEMPERATURE,
+): number {
+  const rt = GAS_CONSTANT * temperature;
+  if (!(rt > 0) || !Number.isFinite(energyError) || energyError <= 0) return 1;
+  return Math.exp(energyError / rt);
+}

package/src/structure/core/conformerEnergy.ts

@@ -0,0 +1,97 @@
+/**
+ * Which energy of a conformer a reader is being shown.
+ *
+ * A refined conformer carries two of everything — what the force field said and
+ * what the better method said afterwards — and a table that mixes them is a
+ * ranking of nothing. So every column reads through one of these, and they all
+ * take the same ranking.
+ */
+
+// Type-only, so nothing here pulls the generator — or openchemlib — into
+// `react-cheminfo/core`, which every page loads.
+import type { ConformerRanking } from './conformers.ts';
+
+/**
+ * What a refinement has to say for an energy column to read it.
+ *
+ * The structural minimum rather than the whole `ConformerRefinement`, so a site
+ * that carries its conformers in a shape of its own — positions instead of a
+ * molfile, say — can still be read by the same helpers and drawn by the same
+ * table.
+ */
+export interface ConformerRowRefinement {
+  /** The rank this conformer held before the refinement reordered the set. */
+  forceFieldId: number;
+  /** Total energy at the relaxed geometry, kcal/mol. */
+  energy: number;
+  /** Energy above the most stable refined conformer, kcal/mol. */
+  relativeEnergy: number;
+}
+
+/**
+ * The least a conformer must carry to be ranked and drawn.
+ *
+ * `Conformer` from `react-cheminfo/conformers` satisfies it, and so does any
+ * per-site record that keeps the same three numbers.
+ */
+export interface ConformerRow {
+  /** 1-based rank in the set, most stable first. */
+  id: number;
+  /** Total force-field energy in kcal/mol, `null` when not computed. */
+  energy: number | null;
+  /** Energy above the most stable conformer, `null` without an energy. */
+  relativeEnergy: number | null;
+  /**
+   * What a better method said, once the set has been refined.
+   * @default null
+   */
+  refinement?: ConformerRowRefinement | null;
+}
+
+/**
+ * The energy above the most stable conformer, in the ranking asked for.
+ * @param conformer - The conformer to read.
+ * @param ranking - Which method's energies to read.
+ * @default 'force-field'
+ * @returns kcal/mol above the lowest, or `null` when that method produced none.
+ */
+export function relativeEnergyOf(
+  conformer: ConformerRow,
+  ranking: ConformerRanking = 'force-field',
+): number | null {
+  return ranking === 'refined'
+    ? (conformer.refinement?.relativeEnergy ?? null)
+    : conformer.relativeEnergy;
+}
+
+/**
+ * The total energy, in the ranking asked for, so the two columns of a row
+ * describe one method.
+ * @param conformer - The conformer to read.
+ * @param ranking - Which method's energies to read.
+ * @default 'force-field'
+ * @returns kcal/mol, or `null` when that method produced none.
+ */
+export function totalEnergyOf(
+  conformer: ConformerRow,
+  ranking: ConformerRanking = 'force-field',
+): number | null {
+  return ranking === 'refined'
+    ? (conformer.refinement?.energy ?? null)
+    : conformer.energy;
+}
+
+/**
+ * The ranking a set should be read in: refined once anything has been refined,
+ * the force field's until then.
+ * @param conformers - The set to inspect.
+ * @returns `'refined'` when at least one conformer carries a refinement.
+ */
+export function bestRanking(
+  conformers: readonly ConformerRow[],
+): ConformerRanking {
+  for (const conformer of conformers) {
+    if (conformer.refinement != null) return 'refined';
+  }
+  return 'force-field';
+}

package/src/structure/core/index.ts

@@ -1,5 +1,20 @@
 export type { AtomLabelPlacement, LabelledMolecule } from './atomLabels.ts';
 export { applyAtomLabels, customAtomLabel } from './atomLabels.ts';
+export {
+  GAS_CONSTANT,
+  ROOM_TEMPERATURE,
+  boltzmannConfidence,
+  boltzmannShares,
+} from './conformerBoltzmann.ts';
+export type {
+  ConformerRow,
+  ConformerRowRefinement,
+} from './conformerEnergy.ts';
+export {
+  bestRanking,
+  relativeEnergyOf,
+  totalEnergyOf,
+} from './conformerEnergy.ts';
 export type {
   EditorGesture,
   EditorGuideKey,