react-cheminfo 0.3.0 → 0.4.0

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

package/src/ecosystem/core/index.ts

@@ -1,3 +1,5 @@
+export { renderEcosystemLinksHtml } from './links.ts';
+export { findSiteByHost, siteById } from './lookup.ts';
 export type {
   EcosystemSite,
   SiteId,
@@ -5,3 +7,4 @@ export type {
   SiteName,
 } from './sites.ts';
 export { ECOSYSTEM_SITES, siteUrl } from './sites.ts';
+export { siteThemeColor, siteTokensCss } from './tokens.ts';

package/src/ecosystem/core/links.ts

@@ -0,0 +1,29 @@
+import { ECOSYSTEM_SITES, siteUrl } from './sites.ts';
+
+/**
+ * Every site of the family as a plain list of links, for the `<noscript>` of a
+ * page whose body is an empty root element.
+ *
+ * A crawler that runs no script sees nothing else of the page, so this is the
+ * only path it has from one of our tools to the next — and each entry carries
+ * the line saying what it opens, as real text.
+ * @returns The `<ul>`, for the caller to place inside its own `<noscript>`.
+ */
+export function renderEcosystemLinksHtml(): string {
+  let html = '<ul class="ecosystem-links">\n';
+  for (const site of ECOSYSTEM_SITES) {
+    const href = escapeHtml(siteUrl(site));
+    const host = escapeHtml(site.host);
+    const tagline = escapeHtml(site.tagline);
+    html += `<li><a href="${href}">${host}</a> — ${tagline}</li>\n`;
+  }
+  return `${html}</ul>\n`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}

package/src/ecosystem/core/lookup.ts

@@ -0,0 +1,41 @@
+import type { EcosystemSite, SiteId } from './sites.ts';
+import { ECOSYSTEM_SITES } from './sites.ts';
+
+/**
+ * One site of the family, by the identifier its entry carries.
+ * @param id - The site being asked for.
+ * @returns The site.
+ * @throws {Error} When no site of the family carries that identifier.
+ */
+export function siteById(id: SiteId): EcosystemSite {
+  for (const site of ECOSYSTEM_SITES) {
+    if (site.id === id) return site;
+  }
+  throw new Error(`unknown ecosystem site: ${id}`);
+}
+
+/**
+ * The site a page is being served from, so a header can mark itself as the
+ * current one without being told which site it belongs to.
+ *
+ * The host is whatever the browser reports, so it may carry a port and may or
+ * may not carry the `www.` two of our sites are written with. Neither changes
+ * which site it is, and a host belonging to nobody — a development server, a
+ * preview deployment — is simply not one of ours.
+ * @param host - What `location.host` reads, or any host-shaped string.
+ * @returns The site served from that host, or undefined for any other host.
+ */
+export function findSiteByHost(host: string): EcosystemSite | undefined {
+  const wanted = normalizeHost(host);
+  if (wanted === '') return undefined;
+
+  for (const site of ECOSYSTEM_SITES) {
+    if (normalizeHost(site.host) === wanted) return site;
+  }
+  return undefined;
+}
+
+function normalizeHost(host: string): string {
+  const withoutPort = host.trim().toLowerCase().split(':', 1)[0] ?? '';
+  return withoutPort.startsWith('www.') ? withoutPort.slice(4) : withoutPort;
+}