react-cheminfo 0.46.0 → 0.48.0

package/src/taxonomy/ui/TaxonLineage.tsx

@@ -0,0 +1,183 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import { isModifiedClick } from '../../chrome/ui/navItem.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+import type { Taxon, TaxonLineage as Lineage } from '../core/lineage.ts';
+import { genusOrBelow, principalLineage } from '../core/lineage.ts';
+import { ncbiTaxonomyUrl } from '../core/ncbi.ts';
+
+import { OrganismName } from './OrganismName.tsx';
+import { rankLabel } from './rankLabel.ts';
+
+/** What a {@link TaxonLineage} needs. */
+export interface TaxonLineageProps {
+  /** The lineage, from the top of the tree down to the taxon it leads to. */
+  lineage: Lineage;
+  /**
+   * Whether only the principal ranks are shown — domain, kingdom, phylum,
+   * class, order, family, genus, species — with the last taxon kept whatever
+   * its rank. Off, every taxon is shown, the clades included.
+   * @default true
+   */
+  principal?: boolean;
+  /**
+   * The address of a taxon's page on the site. A taxon it answers `undefined`
+   * for is written as plain text, and so is every taxon without it.
+   * @default undefined
+   */
+  taxonHref?: (taxon: Taxon) => string | undefined;
+  /**
+   * What the site does when a taxon's link is followed with a plain click —
+   * move to its page without a reload. A modified click is left to the
+   * browser, so a taxon still opens in a tab of its own.
+   * @default undefined
+   */
+  onTaxonSelect?: (taxon: Taxon) => void;
+  /**
+   * Whether each taxon carries its rank as a small label over its name.
+   * Without it the rank is the taxon's tooltip, and is read to a screen reader
+   * after the name.
+   * @default false
+   */
+  showRanks?: boolean;
+  /**
+   * Whether a link to the last taxon's page in the NCBI Taxonomy Browser
+   * follows the lineage, when that taxon has an id.
+   * @default false
+   */
+  ncbiLink?: boolean;
+  /**
+   * Whether the last taxon is the page being read: it is then marked as the
+   * current page and is never a link.
+   * @default false
+   */
+  current?: boolean;
+  /**
+   * What names the breadcrumb to a screen reader.
+   * @default the catalog's "Lineage"
+   */
+  label?: string;
+  /**
+   * Class names added to the root element.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * A lineage as a breadcrumb: the taxa from the top of the tree down, each
+ * named with its rank, the last one emphasised.
+ *
+ * The names under a genus are set in italics as nomenclature sets them, by
+ * {@link OrganismName}; the ranks are the chrome's words, translated with it.
+ * @param props - See {@link TaxonLineageProps}.
+ * @returns The breadcrumb, or nothing for an empty lineage.
+ */
+export function TaxonLineage(props: TaxonLineageProps): ReactElement | null {
+  const {
+    lineage,
+    principal = true,
+    taxonHref,
+    onTaxonSelect,
+    showRanks = false,
+    ncbiLink = false,
+    current = false,
+    label,
+    className,
+  } = props;
+  const t = useChromeT();
+  const shown = principal ? principalLineage(lineage) : lineage;
+  if (shown.length === 0) return null;
+  const italic = genusOrBelow(shown);
+
+  const steps: ReactNode[] = [];
+  for (let index = 0; index < shown.length; index++) {
+    const taxon = shown[index] as Taxon;
+    const last = index === shown.length - 1;
+    const rank = rankLabel(t, taxon.rank);
+    const name = italic[index] ? (
+      <OrganismName name={taxon.name} />
+    ) : (
+      taxon.name
+    );
+    const isCurrent = last && current;
+    const href = isCurrent ? undefined : taxonHref?.(taxon);
+
+    steps.push(
+      <li
+        key={`${taxon.taxId ?? ''}:${taxon.rank}:${taxon.name}`}
+        className={joinClassNames(
+          'taxon-lineage__taxon',
+          last && 'taxon-lineage__taxon--leaf',
+        )}
+        title={showRanks ? undefined : rank}
+      >
+        <span className="taxon-lineage__step">
+          {showRanks && <span className="taxon-lineage__rank">{rank}</span>}
+          {href === undefined ? (
+            <span
+              className="taxon-lineage__name"
+              aria-current={isCurrent ? 'page' : undefined}
+            >
+              {name}
+            </span>
+          ) : (
+            <a
+              className="taxon-lineage__name"
+              href={href}
+              onClick={
+                onTaxonSelect === undefined
+                  ? undefined
+                  : (event) => {
+                      if (isModifiedClick(event) || event.button !== 0) return;
+                      event.preventDefault();
+                      onTaxonSelect(taxon);
+                    }
+              }
+            >
+              {name}
+            </a>
+          )}
+          {!showRanks && (
+            <span className="taxon-lineage__spoken">
+              {' '}
+              {t('taxonomy.rankNote', { rank })}
+            </span>
+          )}
+        </span>
+        {last ? (
+          ncbiLink &&
+          taxon.taxId !== undefined && (
+            <a
+              className="taxon-lineage__ncbi"
+              href={ncbiTaxonomyUrl(taxon.taxId)}
+              target="_blank"
+              rel="noreferrer"
+              title={t('taxonomy.ncbiTitle', { name: taxon.name })}
+            >
+              {t('taxonomy.ncbi')}
+            </a>
+          )
+        ) : (
+          <span className="taxon-lineage__separator" aria-hidden="true">
+            ›
+          </span>
+        )}
+      </li>,
+    );
+  }
+
+  return (
+    <nav
+      className={joinClassNames(
+        'taxon-lineage',
+        showRanks && 'taxon-lineage--ranks',
+        className,
+      )}
+      aria-label={label ?? t('taxonomy.lineage')}
+    >
+      <ol className="taxon-lineage__list">{steps}</ol>
+    </nav>
+  );
+}

package/src/taxonomy/ui/index.ts

@@ -0,0 +1,5 @@
+export type { OrganismNameProps } from './OrganismName.tsx';
+export { OrganismName } from './OrganismName.tsx';
+export type { TaxonLineageProps } from './TaxonLineage.tsx';
+export { TaxonLineage } from './TaxonLineage.tsx';
+export { useRankLabel } from './rankLabel.ts';

package/src/taxonomy/ui/rankLabel.ts

@@ -0,0 +1,81 @@
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { Translate } from '../../i18n/ui/useT.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
+// Each rank NCBI writes, with the key its label is translated under. Written
+// out rather than built from the rank, so a key the catalog lacks fails the
+// type check instead of rendering raw.
+const RANK_KEYS: Readonly<Record<string, ChromeKey>> = {
+  realm: 'taxonomy.rank.realm',
+  domain: 'taxonomy.rank.domain',
+  superkingdom: 'taxonomy.rank.superkingdom',
+  kingdom: 'taxonomy.rank.kingdom',
+  subkingdom: 'taxonomy.rank.subkingdom',
+  superphylum: 'taxonomy.rank.superphylum',
+  phylum: 'taxonomy.rank.phylum',
+  subphylum: 'taxonomy.rank.subphylum',
+  superclass: 'taxonomy.rank.superclass',
+  class: 'taxonomy.rank.class',
+  subclass: 'taxonomy.rank.subclass',
+  infraclass: 'taxonomy.rank.infraclass',
+  cohort: 'taxonomy.rank.cohort',
+  subcohort: 'taxonomy.rank.subcohort',
+  superorder: 'taxonomy.rank.superorder',
+  order: 'taxonomy.rank.order',
+  suborder: 'taxonomy.rank.suborder',
+  infraorder: 'taxonomy.rank.infraorder',
+  parvorder: 'taxonomy.rank.parvorder',
+  superfamily: 'taxonomy.rank.superfamily',
+  family: 'taxonomy.rank.family',
+  subfamily: 'taxonomy.rank.subfamily',
+  tribe: 'taxonomy.rank.tribe',
+  subtribe: 'taxonomy.rank.subtribe',
+  genus: 'taxonomy.rank.genus',
+  subgenus: 'taxonomy.rank.subgenus',
+  section: 'taxonomy.rank.section',
+  subsection: 'taxonomy.rank.subsection',
+  series: 'taxonomy.rank.series',
+  subseries: 'taxonomy.rank.subseries',
+  'species group': 'taxonomy.rank.speciesGroup',
+  'species subgroup': 'taxonomy.rank.speciesSubgroup',
+  species: 'taxonomy.rank.species',
+  'forma specialis': 'taxonomy.rank.formaSpecialis',
+  subspecies: 'taxonomy.rank.subspecies',
+  varietas: 'taxonomy.rank.varietas',
+  subvariety: 'taxonomy.rank.subvariety',
+  forma: 'taxonomy.rank.forma',
+  pathogroup: 'taxonomy.rank.pathogroup',
+  serogroup: 'taxonomy.rank.serogroup',
+  serotype: 'taxonomy.rank.serotype',
+  biotype: 'taxonomy.rank.biotype',
+  genotype: 'taxonomy.rank.genotype',
+  morph: 'taxonomy.rank.morph',
+  strain: 'taxonomy.rank.strain',
+  isolate: 'taxonomy.rank.isolate',
+  'no rank': 'taxonomy.rank.noRank',
+  clade: 'taxonomy.rank.clade',
+  'cellular root': 'taxonomy.rank.cellularRoot',
+  'acellular root': 'taxonomy.rank.acellularRoot',
+};
+
+/**
+ * A rank as the reader's language names it.
+ * @param t - The chrome's formatter.
+ * @param rank - The rank, as NCBI writes it.
+ * @returns Its label, or the rank itself when the catalog has none for it.
+ */
+export function rankLabel(t: Translate<ChromeKey>, rank: string): string {
+  const key = Object.hasOwn(RANK_KEYS, rank) ? RANK_KEYS[rank] : undefined;
+  return key === undefined ? rank : t(key);
+}
+
+/**
+ * The label of a rank in the reader's language, for a site writing a rank
+ * beside the lineage — a taxon's heading, a list of its children.
+ * @returns `label(rank)`: the rank as NCBI writes it, named the way the chrome
+ * names it; a rank the catalog does not know is returned as it is.
+ */
+export function useRankLabel(): (rank: string) => string {
+  const t = useChromeT();
+  return (rank) => rankLabel(t, rank);
+}

package/src/ui.ts

@@ -31,6 +31,7 @@ export * from './scatter3d/ui/index.ts';
 export * from './share/ui/index.ts';
 export * from './shared/ui/index.ts';
 export * from './split/ui/index.ts';
+export * from './taxonomy/ui/index.ts';
 // The conformer table, from the structure module's file rather than its
 // barrel: `structure/ui/index.ts` is the door that must never reach react-ocl,
 // and this component does not, but `react-cheminfo/conformers` is imported by

package/styles/chrome.css

@@ -1059,6 +1059,112 @@ select,
   text-align: right;
 }
 
+/* ── Taxonomy ────────────────────────────────────────────────────────────── */
+
+/* A breadcrumb that wraps between its taxa, never inside one, so a lineage in
+   a table cell stays as narrow as its longest name. The size and the link
+   colour are the page's. */
+.taxon-lineage {
+  display: flex;
+  min-width: 0;
+  flex-wrap: wrap;
+  align-items: baseline;
+  column-gap: 0.6em;
+}
+
+.taxon-lineage__list {
+  display: flex;
+  min-width: 0;
+  flex-wrap: wrap;
+  align-items: baseline;
+  padding: 0;
+  margin: 0;
+  list-style: none;
+  row-gap: 0.1em;
+}
+
+.taxon-lineage__taxon {
+  display: inline-flex;
+  align-items: baseline;
+}
+
+.taxon-lineage__step {
+  display: inline-flex;
+  flex-direction: column;
+}
+
+/* A taxon the site has no page for is read, not followed. */
+span.taxon-lineage__name {
+  color: var(--text-muted);
+}
+
+.taxon-lineage__taxon--leaf .taxon-lineage__name {
+  font-weight: 600;
+}
+
+.taxon-lineage__taxon--leaf span.taxon-lineage__name {
+  color: var(--text);
+}
+
+.taxon-lineage__separator {
+  margin: 0 0.35em;
+  color: var(--text-faint);
+}
+
+.taxon-lineage__rank {
+  color: var(--text-faint);
+  font-size: 0.75em;
+  line-height: 1.2;
+}
+
+/* The rank a tooltip shows the pointer, said to a screen reader; never copied
+   with the names. */
+.taxon-lineage__spoken {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  user-select: none;
+  white-space: nowrap;
+}
+
+/* With its rank over each name, the separators sit on the line of the names. */
+.taxon-lineage--ranks .taxon-lineage__taxon {
+  align-items: flex-end;
+}
+
+/* A rank wider than its name runs on over the separator rather than pushing
+   the separator away from the name it follows. */
+.taxon-lineage--ranks .taxon-lineage__rank {
+  width: 0;
+  overflow: visible;
+  white-space: nowrap;
+}
+
+.taxon-lineage__ncbi {
+  margin-left: 0.75em;
+  font-size: 0.85em;
+  white-space: nowrap;
+}
+
+/* Upright again inside italic text, so a name in a caption still sets its
+   genus apart. */
+.organism-name {
+  font-style: normal;
+}
+
+.organism-name i {
+  font-style: italic;
+}
+
+@media print {
+  .taxon-lineage a {
+    color: inherit;
+    text-decoration: none;
+  }
+}
+
 /* ── Help ────────────────────────────────────────────────────────────────── */
 
 /*
@@ -1176,21 +1282,35 @@ select,
 /* ── The splitter ───────────────────────────────────────────────────────── */
 
 /*
-  The bar between the two figures of a `<SplitRow>` is react-science's, and it
-  keeps react-science's look — the pale track with the grip written on it that
-  NMRium and every other tool of ours is divided by. It is barely visible on
-  purpose: what is read is the two figures, and the bar is found by the pointer
-  that changes over it rather than by the eye.
+  The bar between the two figures of a `<SplitRow>` or a `<SplitColumn>` is
+  react-science's, and it keeps react-science's look — the pale track with the
+  grip written on it that NMRium and every other tool of ours is divided by. It
+  is barely visible on purpose: what is read is the two figures, and the bar is
+  found by the pointer that changes over it rather than by the eye.
 
   All this says is that eleven pixels is more gutter than two figures need.
   `:nth-child(2)` is the bar: a split is only mounted with a pane on each side
   of it, so the three children are always side, bar, side.
+
+  **Which measurement is the seven pixels is the direction's, so each direction
+  says it for itself.** A row's bar is a column of pixels, and narrowing it is
+  narrowing its width; a column's bar is that same line turned a quarter, so
+  there the seven pixels are its height and the width is left to run the width
+  of the pane. One rule for both — the width one, which is what this was — turns
+  a column's bar into a seven-by-ten nub against the left edge of the pane:
+  addressable, draggable, and invisible. The whole argument for a splitter is a
+  line a reader can see, so a bar that renders as a dot is no splitter at all.
 */
-.split-row > div > div:nth-child(2) {
+.split-row:not(.split-row--down) > div > div:nth-child(2) {
   width: 7px;
   min-width: 7px;
 }
 
+.split-row--down > div > div:nth-child(2) {
+  height: 7px;
+  min-height: 7px;
+}
+
 /* ── Printing ────────────────────────────────────────────────────────────── */
 
 /*
@@ -1218,4 +1338,13 @@ select,
   .click-to-copy__icon.click-to-copy__icon.click-to-copy__icon {
     display: none !important;
   }
+
+  /*
+    The bar is a control, and nothing is dragged on paper: all it leaves there
+    is a grey line nobody drew. The panes keep the shares the reader left them
+    at — that is the layout being printed — and simply meet.
+  */
+  .split-row > div > div:nth-child(2) {
+    display: none !important;
+  }
 }