react-cheminfo 0.3.0 → 0.4.0

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;
+}

package/src/delimited/core/rowsToDelimited.ts

@@ -0,0 +1,135 @@
+import { DEFAULT_DELIMITER } from './delimiters.ts';
+import { toDelimited } from './toDelimited.ts';
+
+/** One column of a table written from objects. */
+export interface DelimitedColumn {
+  /** Property of each object this column reads. */
+  key: string;
+  /**
+   * What the column is called in the header line.
+   * @default the key
+   */
+  label?: string;
+  /**
+   * How a value of this column is written.
+   * @default {@link formatCell}
+   */
+  format?: (value: unknown) => string;
+}
+
+/** How a table of objects is written out. */
+export interface RowsToDelimitedOptions {
+  /**
+   * What separates two cells.
+   * @default '\t'
+   */
+  delimiter?: string;
+  /**
+   * Whether the column names are written as the first line.
+   * @default true
+   */
+  header?: boolean;
+  /**
+   * What ends a line.
+   * @default '\n'
+   */
+  newline?: string;
+}
+
+/**
+ * Write a list of objects out as delimited text, one column per named field.
+ *
+ * The columns are what makes the file readable: they fix the order, they name
+ * the header, and they are the only fields written — a row carrying more is not
+ * silently widened, and one carrying less gets an empty cell rather than
+ * shifting every column after it.
+ * @param rows - The objects, one per line.
+ * @param columns - The columns, in order; a plain string names a column that
+ *   reads the property of the same name.
+ * @param options - See {@link RowsToDelimitedOptions}.
+ * @returns The text.
+ */
+export function rowsToDelimited(
+  rows: ReadonlyArray<Readonly<Record<string, unknown>>>,
+  columns: ReadonlyArray<string | DelimitedColumn>,
+  options: RowsToDelimitedOptions = {},
+): string {
+  const {
+    delimiter = DEFAULT_DELIMITER,
+    header = true,
+    newline = '\n',
+  } = options;
+  const resolved = resolveColumns(columns);
+
+  const cells: string[][] = [];
+  for (const row of rows) {
+    const line: string[] = [];
+    for (const { key, format } of resolved) {
+      line.push(format(row[key]));
+    }
+    cells.push(line);
+  }
+
+  return toDelimited(cells, {
+    delimiter,
+    newline,
+    header: header ? resolved.map((column) => column.label) : undefined,
+  });
+}
+
+/**
+ * Write one value the way a spreadsheet reads it.
+ *
+ * Nothing at all — `undefined`, `null`, or a number that is not one — becomes
+ * an empty cell, which is what a spreadsheet means by a missing value; a date
+ * becomes its ISO form, a list becomes its entries separated by `; `, and
+ * anything else becomes its JSON, which at least says what was there.
+ * @param value - The value.
+ * @returns The cell.
+ */
+export function formatCell(value: unknown): string {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? String(value) : '';
+  }
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'bigint') return value.toString();
+  if (Array.isArray(value)) {
+    const parts: string[] = [];
+    for (const entry of value) {
+      parts.push(formatCell(entry));
+    }
+    return parts.join('; ');
+  }
+  try {
+    return JSON.stringify(value) ?? '';
+  } catch {
+    return '';
+  }
+}
+
+interface ResolvedColumn {
+  key: string;
+  label: string;
+  format: (value: unknown) => string;
+}
+
+function resolveColumns(
+  columns: ReadonlyArray<string | DelimitedColumn>,
+): ResolvedColumn[] {
+  const resolved: ResolvedColumn[] = [];
+  for (const column of columns) {
+    if (typeof column === 'string') {
+      resolved.push({ key: column, label: column, format: formatCell });
+    } else {
+      resolved.push({
+        key: column.key,
+        label: column.label ?? column.key,
+        format: column.format ?? formatCell,
+      });
+    }
+  }
+  return resolved;
+}

package/src/delimited/core/toDelimited.ts

@@ -0,0 +1,69 @@
+import { DEFAULT_DELIMITER } from './delimiters.ts';
+
+/** How a table is written out. */
+export interface ToDelimitedOptions {
+  /**
+   * What separates two cells.
+   * @default '\t'
+   */
+  delimiter?: string;
+  /**
+   * Column names, written as the first line.
+   * @default undefined — the table is written without a header line
+   */
+  header?: readonly string[];
+  /**
+   * What ends a line.
+   * @default '\n'
+   */
+  newline?: string;
+}
+
+/**
+ * Write a table out as delimited text.
+ *
+ * Every cell is escaped, whatever the separator: a value holding the separator,
+ * a quote or a newline is quoted and its quotes doubled, per RFC 4180. Joining
+ * on a tab and hoping no cell holds one is what silently corrupts a file the
+ * day a compound name carries a comma or a source a line break.
+ * @param rows - The cells, one array per line.
+ * @param options - See {@link ToDelimitedOptions}.
+ * @returns The text, header line first when there is one.
+ */
+export function toDelimited(
+  rows: ReadonlyArray<readonly string[]>,
+  options: ToDelimitedOptions = {},
+): string {
+  const { delimiter = DEFAULT_DELIMITER, header, newline = '\n' } = options;
+
+  const lines: string[] = [];
+  if (header !== undefined) lines.push(writeLine(header, delimiter));
+  for (const row of rows) {
+    lines.push(writeLine(row, delimiter));
+  }
+  return lines.join(newline);
+}
+
+/**
+ * Write one cell so reading it back gives exactly what went in.
+ * @param value - The cell.
+ * @param delimiter - What separates two cells in this file.
+ * @returns The cell, quoted when it has to be.
+ */
+export function escapeCell(value: string, delimiter: string): string {
+  const mustQuote =
+    value.includes(delimiter) ||
+    value.includes('"') ||
+    value.includes('\n') ||
+    value.includes('\r');
+  if (!mustQuote) return value;
+  return `"${value.replaceAll('"', '""')}"`;
+}
+
+function writeLine(cells: readonly string[], delimiter: string): string {
+  const escaped: string[] = [];
+  for (const cell of cells) {
+    escaped.push(escapeCell(cell, delimiter));
+  }
+  return escaped.join(delimiter);
+}