react-cheminfo 0.2.0 → 0.4.0

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

package/src/delimited/ui/DelimitedTextDialog.tsx

@@ -0,0 +1,49 @@
+import { Button, Dialog, DialogBody, DialogFooter } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { DelimitedTextPanelProps } from './DelimitedTextPanel.tsx';
+import { DelimitedTextPanel } from './DelimitedTextPanel.tsx';
+
+/** What the dialog hands over, and how. */
+export interface DelimitedTextDialogProps extends DelimitedTextPanelProps {
+  /** Whether the dialog is open. */
+  isOpen: boolean;
+  /** Called when the dialog is dismissed. */
+  onClose: () => void;
+  /**
+   * Title of the dialog.
+   * @default 'Copy the table'
+   */
+  title?: string;
+}
+
+/**
+ * The dialog every site rebuilt to hand a table over: the text, a choice of
+ * separator, and a way to copy or save it.
+ * @param props - See {@link DelimitedTextDialogProps}.
+ * @returns The dialog.
+ */
+export function DelimitedTextDialog(
+  props: DelimitedTextDialogProps,
+): ReactElement {
+  const { isOpen, onClose, title = 'Copy the table', ...panel } = props;
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onClose={onClose}
+      title={title}
+      icon="th"
+      style={DIALOG_STYLE}
+    >
+      <DialogBody>
+        <DelimitedTextPanel {...panel} label={panel.label ?? title} />
+      </DialogBody>
+      <DialogFooter actions={<Button text="Close" onClick={onClose} />} />
+    </Dialog>
+  );
+}
+
+const DIALOG_STYLE = {
+  width: 'min(900px, 92vw)',
+} as const satisfies CSSProperties;

package/src/delimited/ui/DelimitedTextPanel.tsx

@@ -0,0 +1,161 @@
+import { Button, Callout, SegmentedControl } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { useMemo, useState } from 'react';
+
+import { CopyButton } from '../../clipboard/ui/CopyButton.tsx';
+import { downloadText } from '../../download/core/downloadText.ts';
+import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+import type { DelimiterId } from '../core/delimiters.ts';
+import { DELIMITER_CHOICES, delimiterChoice } from '../core/delimiters.ts';
+import { toDelimited } from '../core/toDelimited.ts';
+
+/** What a table handed over as text needs. */
+export interface DelimitedTextPanelProps {
+  /** The cells, one array per line. */
+  rows: ReadonlyArray<readonly string[]>;
+  /**
+   * Column names, written as the first line.
+   * @default undefined — the table is handed over without a header line
+   */
+  header?: readonly string[];
+  /**
+   * What the visitor is told above the text. A sentence naming what the table
+   * holds beats the generic one, which only counts the rows.
+   * @default a line saying how many rows there are and what to do with them
+   */
+  description?: ReactNode;
+  /**
+   * Base name of the saved file, without the extension — the extension follows
+   * the chosen separator.
+   * @default 'table'
+   */
+  fileName?: string;
+  /**
+   * Which separator the panel opens on.
+   * @default 'tab'
+   */
+  defaultDelimiter?: DelimiterId;
+  /**
+   * Whether a save button is offered beside the copy one.
+   * @default true
+   */
+  downloadable?: boolean;
+  /**
+   * What the text area is called, for a screen reader reaching it.
+   * @default 'The table, as text'
+   */
+  label?: string;
+  /**
+   * Height of the text area, in pixels.
+   * @default 320
+   */
+  height?: number;
+}
+
+/**
+ * A whole table as text: read it, copy it, or save it.
+ *
+ * The text is shown rather than only downloaded, because a visitor can read
+ * what is being copied and because a page framed in a course site often cannot
+ * start a download at all. Every cell is escaped for the separator in force, so
+ * the file a spreadsheet opens holds the columns the page shows.
+ * @param props - See {@link DelimitedTextPanelProps}.
+ * @returns The panel.
+ */
+export function DelimitedTextPanel(
+  props: DelimitedTextPanelProps,
+): ReactElement {
+  const {
+    rows,
+    header,
+    description,
+    fileName = 'table',
+    defaultDelimiter = 'tab',
+    downloadable = true,
+    label = 'The table, as text',
+    height = 320,
+  } = props;
+  const [delimiterId, setDelimiterId] = useState<string>(defaultDelimiter);
+
+  const choice = delimiterChoice(delimiterId);
+  const text = useMemo(
+    () => toDelimited(rows, { delimiter: choice.delimiter, header }),
+    [rows, header, choice.delimiter],
+  );
+
+  return (
+    <div className="delimited-text">
+      <Callout intent="primary" compact icon="info-sign">
+        {description ?? defaultDescription(rows.length)}
+      </Callout>
+      <div style={CONTROLS_STYLE}>
+        <span style={LABEL_STYLE}>Separator</span>
+        <SegmentedControl
+          size="small"
+          options={DELIMITER_CHOICES.map((option) => ({
+            label: option.label,
+            value: option.id,
+          }))}
+          value={choice.id}
+          onValueChange={setDelimiterId}
+        />
+        <span style={SPACER_STYLE} />
+        {downloadable ? (
+          <Button
+            icon="download"
+            text="Save"
+            size="small"
+            onClick={() =>
+              downloadText(
+                text,
+                `${sanitizeFileName(fileName, 'table')}.${choice.extension}`,
+                `${choice.mimeType};charset=utf-8`,
+              )
+            }
+          />
+        ) : null}
+        <CopyButton content={text} label="Copy" icon="clipboard" small />
+      </div>
+      <textarea
+        readOnly
+        value={text}
+        spellCheck={false}
+        aria-label={label}
+        className="bp6-input"
+        style={{ ...TEXT_STYLE, height }}
+        onFocus={(event) => event.currentTarget.select()}
+      />
+    </div>
+  );
+}
+
+function defaultDescription(rowCount: number): string {
+  const rows = rowCount === 1 ? '1 row' : `${rowCount.toLocaleString()} rows`;
+  return `${rows}, one per line. Copy them, then paste into a spreadsheet.`;
+}
+
+const CONTROLS_STYLE = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 8,
+  marginTop: 12,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  color: '#5f6b7c',
+  fontSize: 12,
+} as const satisfies CSSProperties;
+
+const SPACER_STYLE = { flex: 1 } as const satisfies CSSProperties;
+
+const TEXT_STYLE = {
+  width: '100%',
+  marginTop: 12,
+  boxSizing: 'border-box',
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+  fontSize: 12,
+  overflowX: 'auto',
+  overflowWrap: 'normal',
+  whiteSpace: 'pre',
+} as const satisfies CSSProperties;

package/src/delimited/ui/index.ts

@@ -0,0 +1,4 @@
+export type { DelimitedTextDialogProps } from './DelimitedTextDialog.tsx';
+export { DelimitedTextDialog } from './DelimitedTextDialog.tsx';
+export type { DelimitedTextPanelProps } from './DelimitedTextPanel.tsx';
+export { DelimitedTextPanel } from './DelimitedTextPanel.tsx';

package/src/disclosure/ui/CollapsibleSection.tsx

@@ -0,0 +1,150 @@
+import type { IconName } from '@blueprintjs/core';
+import { Collapse, Icon } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { useState } from 'react';
+
+/** What a titled section that folds away needs. */
+export interface CollapsibleSectionProps {
+  /** The heading, which is also what opens and closes the section. */
+  title: ReactNode;
+  /** The body, shown only while the section is open. */
+  children: ReactNode;
+  /**
+   * Glyph before the title.
+   * @default undefined — only the chevron is drawn
+   */
+  icon?: IconName;
+  /**
+   * Whether the section starts open, when the caller does not drive it.
+   * @default true
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controls beside the heading — a count, a copy button, a menu. They sit
+   * outside the heading button, so pressing one does not fold the section.
+   * @default undefined
+   */
+  rightElement?: ReactNode;
+  /**
+   * Whether the section is open, when a parent drives it — which is what an
+   * "expand all" button, or a badge that opens and scrolls to a section, needs.
+   * @default undefined — the section keeps its own state
+   */
+  isOpen?: boolean;
+  /**
+   * Called when the heading is pressed while a parent drives the section.
+   * @default undefined
+   */
+  onToggle?: () => void;
+  /**
+   * Identifier of the section element, so a link can jump to it.
+   * @default undefined
+   */
+  id?: string;
+  /**
+   * Class the section carries, in addition to `collapsible-section`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * A titled block of a page that folds away when its heading is pressed.
+ *
+ * It works on its own or under a parent: pass `isOpen` and `onToggle` and the
+ * caller owns the state, which is what a page needs to open every section at
+ * once.
+ * @param props - See {@link CollapsibleSectionProps}.
+ * @returns The section.
+ */
+export function CollapsibleSection(
+  props: CollapsibleSectionProps,
+): ReactElement {
+  const {
+    title,
+    children,
+    icon,
+    defaultOpen = true,
+    rightElement,
+    isOpen: openProp,
+    onToggle,
+    id,
+    className,
+  } = props;
+  const [openState, setOpenState] = useState(defaultOpen);
+
+  const isControlled = openProp !== undefined;
+  const isOpen = isControlled ? openProp : openState;
+
+  function toggle(): void {
+    if (isControlled) onToggle?.();
+    else setOpenState((shown) => !shown);
+  }
+
+  return (
+    <section
+      id={id}
+      className={
+        className === undefined
+          ? 'collapsible-section'
+          : `collapsible-section ${className}`
+      }
+    >
+      <div style={HEADER_STYLE}>
+        <button
+          type="button"
+          style={BUTTON_STYLE}
+          aria-expanded={isOpen}
+          onClick={toggle}
+        >
+          <Icon icon={isOpen ? 'chevron-down' : 'chevron-right'} size={14} />
+          {icon === undefined ? null : <Icon icon={icon} size={14} />}
+          <span style={TITLE_STYLE}>{title}</span>
+        </button>
+        {rightElement === undefined ? null : (
+          <div style={RIGHT_STYLE}>{rightElement}</div>
+        )}
+      </div>
+      <Collapse isOpen={isOpen}>
+        <div style={BODY_STYLE}>{children}</div>
+      </Collapse>
+    </section>
+  );
+}
+
+const HEADER_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const BUTTON_STYLE = {
+  display: 'flex',
+  flex: '1 1 auto',
+  minWidth: 0,
+  alignItems: 'center',
+  padding: '4px 0',
+  border: 0,
+  background: 'none',
+  color: 'inherit',
+  font: 'inherit',
+  fontWeight: 600,
+  gap: 6,
+  textAlign: 'left',
+  cursor: 'pointer',
+} as const satisfies CSSProperties;
+
+const TITLE_STYLE = {
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+} as const satisfies CSSProperties;
+
+const RIGHT_STYLE = {
+  display: 'flex',
+  flex: '0 0 auto',
+  alignItems: 'center',
+  gap: 4,
+} as const satisfies CSSProperties;
+
+const BODY_STYLE = { paddingTop: 4 } as const satisfies CSSProperties;

package/src/disclosure/ui/index.ts

@@ -0,0 +1,4 @@
+export type { CollapsibleSectionProps } from './CollapsibleSection.tsx';
+export { CollapsibleSection } from './CollapsibleSection.tsx';
+export type { Disclosure } from './useDisclosure.ts';
+export { useDisclosure } from './useDisclosure.ts';

package/src/disclosure/ui/useDisclosure.ts

@@ -0,0 +1,35 @@
+import { useCallback, useMemo, useState } from 'react';
+
+/** Something that is either shown or not, and the three ways to change that. */
+export interface Disclosure {
+  /** Whether the thing is currently shown. */
+  isOpen: boolean;
+  /** Show it, whatever it was doing. */
+  open: () => void;
+  /** Hide it, whatever it was doing. */
+  close: () => void;
+  /** Show it when it is hidden, hide it when it is shown. */
+  toggle: () => void;
+}
+
+/**
+ * The open state of a dialog, a menu, a panel or a section.
+ *
+ * The three actions keep the same identity for the life of the component, so
+ * passing `close` to a dialog or a keyboard handler does not re-subscribe it on
+ * every render.
+ * @param initialOpen - Whether it starts out shown.
+ * @returns The state and the three actions.
+ */
+export function useDisclosure(initialOpen = false): Disclosure {
+  const [isOpen, setIsOpen] = useState(initialOpen);
+
+  const open = useCallback(() => setIsOpen(true), []);
+  const close = useCallback(() => setIsOpen(false), []);
+  const toggle = useCallback(() => setIsOpen((shown) => !shown), []);
+
+  return useMemo(
+    () => ({ isOpen, open, close, toggle }),
+    [isOpen, open, close, toggle],
+  );
+}

package/src/download/core/downloadBlob.ts

@@ -0,0 +1,19 @@
+/**
+ * Hand a blob to the browser as a file the visitor saves.
+ *
+ * The object URL is released as soon as the click is dispatched, so nothing a
+ * page ever downloads is kept alive in memory behind it.
+ * @param blob - The bytes to save.
+ * @param fileName - Name the browser gives the saved file, extension included.
+ */
+export function downloadBlob(blob: Blob, fileName: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = fileName;
+  // Some browsers ignore a click on an anchor that is not in the document.
+  document.body.append(anchor);
+  anchor.click();
+  anchor.remove();
+  URL.revokeObjectURL(url);
+}

package/src/download/core/downloadText.ts

@@ -0,0 +1,19 @@
+import { downloadBlob } from './downloadBlob.ts';
+
+/** What a file of text is taken to be when the caller does not say. */
+const DEFAULT_MIME_TYPE = 'text/plain;charset=utf-8';
+
+/**
+ * Hand a piece of text to the browser as a file the visitor saves.
+ * @param text - The content of the file.
+ * @param fileName - Name the browser gives the saved file, extension included.
+ * @param mimeType - What the content is, so the system opens it with the right
+ *   application.
+ */
+export function downloadText(
+  text: string,
+  fileName: string,
+  mimeType: string = DEFAULT_MIME_TYPE,
+): void {
+  downloadBlob(new Blob([text], { type: mimeType }), fileName);
+}

package/src/download/core/index.ts

@@ -0,0 +1,3 @@
+export { downloadBlob } from './downloadBlob.ts';
+export { downloadText } from './downloadText.ts';
+export { sanitizeFileName } from './sanitizeFileName.ts';

package/src/download/core/sanitizeFileName.ts

@@ -0,0 +1,33 @@
+// Windows refuses these outright, and they read as syntax in a shell.
+const RESERVED = /["*:<>?|]/gu;
+const PATH_SEPARATOR = /[/\\]/gu;
+// Control characters that are not whitespace: a newline is folded into a space
+// below rather than dropped, so a pasted two-line name stays readable.
+const CONTROL = /[^\P{Cc}\s]/gu;
+const WHITESPACE = /\s+/gu;
+const LEADING = /^[\s.-]+/u;
+const TRAILING = /[\s.]+$/u;
+
+/**
+ * Turn whatever a molecule, a list or a page is called into a name a file
+ * system takes.
+ *
+ * The name usually comes from something the visitor typed or from a record
+ * that was downloaded, so it may carry a path, a newline, or nothing at all.
+ * Path separators become hyphens rather than disappearing, so the parts of the
+ * name stay readable, and a name left empty falls back rather than saving a
+ * file with no name at all.
+ * @param name - What the file should be called.
+ * @param fallback - Name used when nothing usable is left.
+ * @returns A file name safe to pass to a download.
+ */
+export function sanitizeFileName(name: string, fallback = 'download'): string {
+  const cleaned = name
+    .replaceAll(CONTROL, '')
+    .replaceAll(PATH_SEPARATOR, '-')
+    .replaceAll(RESERVED, '')
+    .replaceAll(WHITESPACE, ' ')
+    .replace(LEADING, '')
+    .replace(TRAILING, '');
+  return cleaned === '' ? fallback : cleaned;
+}