react-cheminfo 0.2.0 → 0.4.0

package/src/color/ui/ColorScaleLegend.tsx

@@ -0,0 +1,144 @@
+import type { CSSProperties, ReactElement } from 'react';
+import { useId } from 'react';
+
+import { formatTrimmed } from '../../format/core/numbers.ts';
+
+const FALLBACK_STOPS: readonly string[] = ['#e4e8ee'];
+const BAR_HEIGHT = 12;
+const BAR_WIDTH = 100;
+
+/** What {@link ColorScaleLegend} needs to draw a scale. */
+export interface ColorScaleLegendProps {
+  /** The scale's colours, from its low end to its high end. */
+  stops: readonly string[];
+  /** The value the low end stands for. */
+  min: number;
+  /** The value the high end stands for. */
+  max: number;
+  /**
+   * Unit written after each end value, e.g. `g/mol`.
+   * @default '' — no unit is written
+   */
+  unit?: string;
+  /**
+   * What the scale measures, written before it.
+   * @default '' — no label is written
+   */
+  label?: string;
+  /**
+   * How an end value is written.
+   * @default a rounding to three decimals with the trailing zeros dropped
+   */
+  formatValue?: (value: number) => string;
+}
+
+/**
+ * The key to a sequential colour scale: its two end values, and the ramp
+ * between them.
+ *
+ * The ramp is a real gradient rather than a row of buckets, and both ends
+ * carry their value, so a figure lifted out of the page still says what it is
+ * measuring. It is drawn as an SVG, which keeps it crisp in a print and in an
+ * exported image.
+ * @param props - See {@link ColorScaleLegendProps}.
+ * @returns The labelled gradient strip.
+ */
+export function ColorScaleLegend(props: ColorScaleLegendProps): ReactElement {
+  const {
+    stops,
+    min,
+    max,
+    unit = '',
+    label = '',
+    formatValue = defaultFormatValue,
+  } = props;
+  const gradientId = useId();
+
+  const scale = stops.length === 0 ? FALLBACK_STOPS : stops;
+  const low = withUnit(formatValue(min), unit);
+  const high = withUnit(formatValue(max), unit);
+
+  return (
+    <div style={ROW_STYLE}>
+      {label === '' ? null : <span style={LABEL_STYLE}>{label}</span>}
+      <span style={VALUE_STYLE}>{low}</span>
+      <svg
+        style={BAR_STYLE}
+        viewBox={`0 0 ${BAR_WIDTH} ${BAR_HEIGHT}`}
+        preserveAspectRatio="none"
+        role="img"
+        aria-label={`${label === '' ? 'Colour scale' : label} from ${low} to ${high}`}
+      >
+        <defs>
+          <linearGradient id={gradientId} x1="0" y1="0" x2="1" y2="0">
+            {gradientStops(scale).map((stop) => (
+              <stop
+                key={stop.offset}
+                offset={stop.offset}
+                stopColor={stop.color}
+              />
+            ))}
+          </linearGradient>
+        </defs>
+        <rect
+          x="0"
+          y="0"
+          width={BAR_WIDTH}
+          height={BAR_HEIGHT}
+          rx="2"
+          fill={`url(#${gradientId})`}
+        />
+      </svg>
+      <span style={VALUE_STYLE}>{high}</span>
+    </div>
+  );
+}
+
+function gradientStops(
+  stops: readonly string[],
+): Array<{ offset: number; color: string }> {
+  const last = stops.length - 1;
+  const rendered: Array<{ offset: number; color: string }> = [];
+  for (let index = 0; index < stops.length; index++) {
+    const color = stops[index];
+    if (color === undefined) continue;
+    rendered.push({ offset: last === 0 ? index : index / last, color });
+  }
+  if (rendered.length === 1) {
+    const only = rendered[0];
+    if (only !== undefined) rendered.push({ offset: 1, color: only.color });
+  }
+  return rendered;
+}
+
+function defaultFormatValue(value: number): string {
+  return formatTrimmed(value, 3);
+}
+
+function withUnit(value: string, unit: string): string {
+  return unit === '' ? value : `${value} ${unit}`;
+}
+
+const ROW_STYLE = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  color: 'rgb(95 107 124)',
+  fontSize: 12,
+} as const satisfies CSSProperties;
+
+const VALUE_STYLE = {
+  fontSize: 12,
+  fontVariantNumeric: 'tabular-nums',
+} as const satisfies CSSProperties;
+
+const BAR_STYLE = {
+  display: 'inline-block',
+  flex: '1 1 160px',
+  maxWidth: 320,
+  height: BAR_HEIGHT,
+} as const satisfies CSSProperties;

package/src/color/ui/index.ts

@@ -0,0 +1,2 @@
+export type { ColorScaleLegendProps } from './ColorScaleLegend.tsx';
+export { ColorScaleLegend } from './ColorScaleLegend.tsx';

package/src/core.ts

@@ -1,2 +1,14 @@
 export * from './citation/core/index.ts';
+export * from './clipboard/core/index.ts';
+export * from './color/core/index.ts';
+export * from './credits/core/index.ts';
+export * from './delimited/core/index.ts';
+export * from './download/core/index.ts';
 export * from './ecosystem/core/index.ts';
+export * from './format/core/index.ts';
+export * from './orbital/core/index.ts';
+export * from './pedagogy/core/index.ts';
+export * from './router/core/index.ts';
+export * from './seo/core/index.ts';
+export * from './share/core/index.ts';
+export * from './worker/core/index.ts';

package/src/credits/core/credits.ts

@@ -0,0 +1,183 @@
+/** One borrowed work a site credits. */
+export interface CreditEntry {
+  /** How a site names the work in its own list. */
+  id: string;
+  /** What the work is called, spelled the way its authors spell it. */
+  name: string;
+  /** Where the work lives. */
+  href: string;
+  /** What it does for the site, in one line. */
+  description: string;
+  /**
+   * Licence it is distributed under.
+   * @default undefined — the work carries no licence of its own here
+   */
+  license?: string;
+}
+
+/** An id the registry answers to. */
+export type CreditId = (typeof CREDITS)[number]['id'];
+
+/**
+ * The borrowed works a site names, in the order it names them.
+ *
+ * An About dialog lists what the page stands on, and every site had been
+ * writing that list itself — which is how two of them came to credit the same
+ * project to two different organisations. One registry, one answer.
+ * @param ids - Which works to list, in display order.
+ * @returns The entries, in that order.
+ * @throws {Error} When an id is not in the registry: a credits list that
+ *   silently drops a work credits nobody.
+ */
+export function credits(ids: readonly CreditId[]): CreditEntry[] {
+  const listed: CreditEntry[] = [];
+  for (const id of ids) {
+    const entry = creditOf(id);
+    if (entry === undefined) {
+      throw new Error(`unknown credit: ${id}`);
+    }
+    listed.push(entry);
+  }
+  return listed;
+}
+
+/**
+ * One borrowed work of the registry, for a site checking whether it holds one.
+ * @param id - Which work.
+ * @returns Its entry, or `undefined` when the registry does not hold it.
+ */
+export function creditOf(id: string): CreditEntry | undefined {
+  return CREDITS.find((candidate) => candidate.id === id);
+}
+
+/**
+ * Every work our sites borrow, with the organisation that actually publishes
+ * it — checked against the package each site installs, not against habit.
+ */
+export const CREDITS = [
+  {
+    id: 'openchemlib',
+    name: 'OpenChemLib',
+    href: 'https://github.com/cheminfo/openchemlib-js',
+    description:
+      'reads and writes structures, and computes their properties in the browser.',
+    license: 'BSD-3-Clause',
+  },
+  {
+    id: 'openchemlib-utils',
+    name: 'openchemlib-utils',
+    href: 'https://github.com/cheminfo/openchemlib-utils',
+    description: 'the structure helpers built on top of OpenChemLib.',
+    license: 'MIT',
+  },
+  {
+    id: 'react-ocl',
+    name: 'react-ocl',
+    href: 'https://github.com/zakodium-oss/react-ocl',
+    description: 'the structure editor you draw in, and the 2D renderer.',
+    license: 'MIT',
+  },
+  {
+    id: 'react-mf',
+    name: 'react-mf',
+    href: 'https://github.com/zakodium-oss/react-mf',
+    description:
+      'typesets a molecular formula, subscripts, isotopes and charges included.',
+    license: 'MIT',
+  },
+  {
+    id: 'mass-tools',
+    name: 'mass-tools',
+    href: 'https://github.com/cheminfo/mass-tools',
+    description:
+      'parses molecular formulas and computes masses and isotopic distributions.',
+    license: 'MIT',
+  },
+  {
+    id: 'chem-equilibrium',
+    name: 'chem-equilibrium',
+    href: 'https://github.com/cheminfo/chem-equilibrium',
+    description:
+      'builds the mass-balance system of a solution and finds its root.',
+    license: 'MIT',
+  },
+  {
+    id: 'ml-matrix',
+    name: 'ml-matrix',
+    href: 'https://github.com/mljs/matrix',
+    description: 'the linear algebra behind the numbers on the page.',
+    license: 'MIT',
+  },
+  {
+    id: 'ml-spectra-processing',
+    name: 'ml-spectra-processing',
+    href: 'https://github.com/mljs/spectra-processing',
+    description: 'the array and spectrum operations the data goes through.',
+    license: 'MIT',
+  },
+  {
+    id: 'molstar',
+    name: 'Mol*',
+    href: 'https://molstar.org/',
+    description: 'the 3D viewer, its representations and its surfaces.',
+    license: 'MIT',
+  },
+  {
+    id: 'blueprint',
+    name: 'Blueprint',
+    href: 'https://blueprintjs.com/',
+    description:
+      'the interface components — cards, dialogs, inputs, tables and tags.',
+    license: 'Apache-2.0',
+  },
+  {
+    id: 'react-science',
+    name: 'react-science',
+    href: 'https://github.com/zakodium-oss/react-science',
+    description:
+      'the scientific application shell this family of sites shares.',
+    license: 'MIT',
+  },
+  {
+    id: 'react-cheminfo',
+    name: 'react-cheminfo',
+    href: 'https://github.com/cheminfo/react-cheminfo',
+    description: 'the shared chrome and conventions of the cheminfo sites.',
+    license: 'MIT',
+  },
+  {
+    id: 'cheminfo-font',
+    name: 'cheminfo-font',
+    href: 'https://github.com/cheminfo/font',
+    description: 'the chemistry glyphs the toolbars are drawn with.',
+    license: 'CC-BY-4.0',
+  },
+  {
+    id: 'nivo',
+    name: 'nivo',
+    href: 'https://nivo.rocks/',
+    description: 'draws the charts — the curves, the diagrams and the axes.',
+    license: 'MIT',
+  },
+  {
+    id: 'mathjax',
+    name: 'MathJax',
+    href: 'https://www.mathjax.org/',
+    description: 'typesets the mathematics, from LaTeX to what you read.',
+    license: 'Apache-2.0',
+  },
+  {
+    id: 'react',
+    name: 'React',
+    href: 'https://react.dev/',
+    description: 'the component model the pages are written in.',
+    license: 'MIT',
+  },
+  {
+    id: 'vite',
+    name: 'Vite',
+    href: 'https://vite.dev/',
+    description: 'builds and serves the static site.',
+    license: 'MIT',
+  },
+] as const satisfies readonly CreditEntry[];

package/src/credits/core/index.ts

@@ -0,0 +1,2 @@
+export type { CreditEntry, CreditId } from './credits.ts';
+export { CREDITS, creditOf, credits } from './credits.ts';

package/src/credits/ui/CreditsList.tsx

@@ -0,0 +1,82 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { CreditEntry } from '../core/credits.ts';
+
+/** What a credits list draws. */
+export interface CreditsListProps {
+  /** The works, in the order they are listed. */
+  entries: readonly CreditEntry[];
+  /**
+   * Whether each work's licence is written after its name.
+   * @default true
+   */
+  showLicense?: boolean;
+  /**
+   * Class the list carries, in addition to `credits-list`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The Credits section of an About dialog: every borrowed work, what it does
+ * here, and under which licence.
+ *
+ * Naming the licence beside the work is what makes the list a credit rather
+ * than a list of links, and it is the part a site is most likely to leave out
+ * when it writes its own.
+ * @param props - See {@link CreditsListProps}.
+ * @returns The list.
+ */
+export function CreditsList(props: CreditsListProps): ReactElement {
+  const { entries, showLicense = true, className } = props;
+
+  return (
+    <ul
+      className={
+        className === undefined ? 'credits-list' : `credits-list ${className}`
+      }
+      style={LIST_STYLE}
+    >
+      {entries.map((entry) => (
+        <li key={entry.id} style={ITEM_STYLE}>
+          <a
+            href={entry.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            style={NAME_STYLE}
+          >
+            {entry.name}
+          </a>
+          {showLicense && entry.license !== undefined ? (
+            <span style={LICENSE_STYLE}>{entry.license}</span>
+          ) : (
+            ' '
+          )}
+          <span>{entry.description}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+const LIST_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  margin: 0,
+  paddingLeft: 18,
+} as const satisfies CSSProperties;
+
+const ITEM_STYLE = {
+  fontSize: 13,
+  lineHeight: 1.4,
+} as const satisfies CSSProperties;
+
+const NAME_STYLE = { fontWeight: 600 } as const satisfies CSSProperties;
+
+const LICENSE_STYLE = {
+  color: '#5f6b7c',
+  fontSize: 11,
+  margin: '0 6px',
+} as const satisfies CSSProperties;

package/src/credits/ui/index.ts

@@ -0,0 +1,2 @@
+export type { CreditsListProps } from './CreditsList.tsx';
+export { CreditsList } from './CreditsList.tsx';

package/src/delimited/core/delimiters.ts

@@ -0,0 +1,64 @@
+/** The separators a table can be written with. */
+export type DelimiterId = 'tab' | 'comma' | 'semicolon';
+
+/** One separator, and everything a file written with it needs. */
+export interface DelimiterChoice {
+  /** How the choice is named in a link and in a dialog. */
+  id: DelimiterId;
+  /** What the choice reads in the interface. */
+  label: string;
+  /** The character itself. */
+  delimiter: string;
+  /** Extension a file written with it takes, without the dot. */
+  extension: string;
+  /** What such a file is, so the system opens it with a spreadsheet. */
+  mimeType: string;
+}
+
+/**
+ * The separator a choice stands for, whatever a link or a stored preference
+ * carries.
+ *
+ * An unknown id falls back to the tab rather than throwing: this value comes
+ * out of an address or a stored setting, and a link written two years ago must
+ * still open.
+ * @param id - The named choice.
+ * @returns The choice, or the tab one when the name is not known.
+ */
+export function delimiterChoice(id: string | undefined): DelimiterChoice {
+  for (const choice of DELIMITER_CHOICES) {
+    if (choice.id === id) return choice;
+  }
+  return TAB_CHOICE;
+}
+
+/** The tab, which is what a table is written with unless asked otherwise. */
+const TAB_CHOICE: DelimiterChoice = {
+  id: 'tab',
+  label: 'Tab',
+  delimiter: '\t',
+  extension: 'tsv',
+  mimeType: 'text/tab-separated-values',
+};
+
+/** Every separator offered, in the order a dialog lists them. */
+export const DELIMITER_CHOICES: readonly DelimiterChoice[] = [
+  TAB_CHOICE,
+  {
+    id: 'comma',
+    label: 'Comma',
+    delimiter: ',',
+    extension: 'csv',
+    mimeType: 'text/csv',
+  },
+  {
+    id: 'semicolon',
+    label: 'Semicolon',
+    delimiter: ';',
+    extension: 'csv',
+    mimeType: 'text/csv',
+  },
+];
+
+/** The separator used when a caller does not name one. */
+export const DEFAULT_DELIMITER = '\t';

package/src/delimited/core/index.ts

@@ -0,0 +1,11 @@
+export type { DelimiterChoice, DelimiterId } from './delimiters.ts';
+export { DEFAULT_DELIMITER, DELIMITER_CHOICES } from './delimiters.ts';
+export type { ReadDelimitedOptions } from './readDelimited.ts';
+export { detectDelimiter, readDelimited } from './readDelimited.ts';
+export type {
+  DelimitedColumn,
+  RowsToDelimitedOptions,
+} from './rowsToDelimited.ts';
+export { rowsToDelimited } from './rowsToDelimited.ts';
+export type { ToDelimitedOptions } from './toDelimited.ts';
+export { toDelimited } from './toDelimited.ts';

package/src/delimited/core/readDelimited.ts

@@ -0,0 +1,132 @@
+import { DEFAULT_DELIMITER } from './delimiters.ts';
+
+/** How a table is read back. */
+export interface ReadDelimitedOptions {
+  /**
+   * What separates two cells. Left out, the separator is guessed from the text.
+   * @default undefined — the separator is detected
+   */
+  delimiter?: string;
+}
+
+/**
+ * Read delimited text back into rows.
+ *
+ * Quoting is honoured, so a cell holding the separator, a newline or a doubled
+ * quote comes back as it went in. A byte-order mark is dropped, `\r\n` and `\n`
+ * both end a line, and a blank line — the trailing one included — is skipped
+ * rather than read as a row carrying one empty cell.
+ * @param text - The file, as text.
+ * @param options - See {@link ReadDelimitedOptions}.
+ * @returns The rows, each an array of cells.
+ */
+export function readDelimited(
+  text: string,
+  options: ReadDelimitedOptions = {},
+): string[][] {
+  const content = text.codePointAt(0) === 0xfe_ff ? text.slice(1) : text;
+  if (content === '') return [];
+  const delimiter = options.delimiter ?? detectDelimiter(content);
+
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let cell = '';
+  let quoted = false;
+
+  for (let index = 0; index < content.length; index++) {
+    const character = content.charAt(index);
+
+    if (quoted) {
+      if (character !== '"') {
+        cell += character;
+      } else if (content[index + 1] === '"') {
+        cell += '"';
+        index++;
+      } else {
+        quoted = false;
+      }
+      continue;
+    }
+
+    if (character === '"' && cell === '') {
+      quoted = true;
+    } else if (character === delimiter) {
+      row.push(cell);
+      cell = '';
+    } else if (character === '\n' || character === '\r') {
+      if (character === '\r' && content[index + 1] === '\n') index++;
+      row.push(cell);
+      if (!isBlank(row)) rows.push(row);
+      row = [];
+      cell = '';
+    } else {
+      cell += character;
+    }
+  }
+
+  row.push(cell);
+  if (!isBlank(row)) rows.push(row);
+  return rows;
+}
+
+/**
+ * Guess what separates the cells of a piece of delimited text.
+ *
+ * The candidates are counted outside quotes over the first few lines, so a
+ * comma inside a compound name does not win against the tabs actually
+ * separating the columns.
+ * @param text - The file, as text.
+ * @returns The separator, falling back to the tab when nothing separates
+ *   anything.
+ */
+export function detectDelimiter(text: string): string {
+  let best = DEFAULT_DELIMITER;
+  let bestCount = 0;
+  for (const candidate of CANDIDATES) {
+    const count = countOutsideQuotes(text, candidate);
+    if (count > bestCount) {
+      best = candidate;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+
+function isBlank(row: readonly string[]): boolean {
+  return row.length === 1 && row[0] === '';
+}
+
+/** The separators a file we read is allowed to use, in order of preference. */
+const CANDIDATES: readonly string[] = ['\t', ',', ';'];
+
+/** How many lines of the file the guess is made from. */
+const SAMPLED_LINES = 10;
+
+function countOutsideQuotes(text: string, delimiter: string): number {
+  let count = 0;
+  let lines = 0;
+  let quoted = false;
+
+  for (let index = 0; index < text.length; index++) {
+    const character = text.charAt(index);
+    if (quoted) {
+      if (character === '"') {
+        if (text[index + 1] === '"') {
+          index++;
+        } else {
+          quoted = false;
+        }
+      }
+      continue;
+    }
+    if (character === '"') {
+      quoted = true;
+    } else if (character === delimiter) {
+      count++;
+    } else if (character === '\n') {
+      lines++;
+      if (lines >= SAMPLED_LINES) break;
+    }
+  }
+  return count;
+}