react-cheminfo 0.3.0 → 0.4.0

package/lib/worker/core/workerChannel.js

@@ -0,0 +1,121 @@
+import { CancelledRequestError, RequestTimeoutError } from "./errors.js";
+/**
+ * Turn a worker into something a page can await.
+ *
+ * Several requests may be in flight at once; each one is tagged with an
+ * identifier the answer echoes, so replies are matched to callers whatever
+ * order they arrive in. A request that rejects — cancelled, timed out, or
+ * failed — drops out of the pending map at that moment, so a page that fires
+ * one job per keystroke never accumulates them.
+ *
+ * The worker is the caller's: the channel posts to it and terminates it when
+ * asked, but never creates one, which is what lets a site keep its own lazy
+ * construction and its own in-process fallback.
+ * @param worker - The worker to talk to, or anything that speaks its three calls.
+ * @param options - See {@link WorkerChannelOptions}.
+ * @returns The channel.
+ */
+export function createWorkerChannel(worker, options = {}) {
+    const name = options.name ?? 'worker';
+    const defaultTimeoutMs = positiveMilliseconds(options.defaultTimeoutMs, DEFAULT_TIMEOUT_MS);
+    const pending = new Map();
+    let nextId = 0;
+    let terminated = false;
+    function settle(id) {
+        const entry = pending.get(id);
+        if (entry === undefined)
+            return undefined;
+        pending.delete(id);
+        entry.dispose();
+        return entry;
+    }
+    function rejectAll(error) {
+        for (const entry of pending.values()) {
+            entry.dispose();
+            entry.reject(error);
+        }
+        pending.clear();
+    }
+    worker.addEventListener('message', (event) => {
+        const message = event.data;
+        if (!isResponseMessage(message))
+            return;
+        const entry = settle(message.id);
+        if (entry === undefined)
+            return;
+        if (message.ok)
+            entry.resolve(message.response);
+        else
+            entry.reject(new Error(message.message));
+    });
+    worker.addEventListener('error', (event) => {
+        const detail = event.message ?? '';
+        rejectAll(new Error(detail === '' ? `${name} failed` : `${name} failed: ${detail}`));
+    });
+    return {
+        get pendingCount() {
+            return pending.size;
+        },
+        request: (payload, requestOptions = {}) => {
+            const { signal, timeoutMs } = requestOptions;
+            if (terminated) {
+                return Promise.reject(new CancelledRequestError(`${name} was terminated`));
+            }
+            if (signal?.aborted === true) {
+                return Promise.reject(new CancelledRequestError(`${name} request was cancelled`));
+            }
+            nextId += 1;
+            const id = nextId;
+            const budget = positiveMilliseconds(timeoutMs, defaultTimeoutMs);
+            return new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    settle(id)?.reject(new RequestTimeoutError(`${name} request ${id} timed out after ${budget} ms`));
+                }, budget);
+                const onAbort = () => {
+                    settle(id)?.reject(new CancelledRequestError(`${name} request ${id} was cancelled`));
+                };
+                signal?.addEventListener('abort', onAbort);
+                pending.set(id, {
+                    resolve,
+                    reject,
+                    dispose: () => {
+                        clearTimeout(timeout);
+                        signal?.removeEventListener('abort', onAbort);
+                    },
+                });
+                const message = {
+                    id,
+                    request: payload,
+                };
+                try {
+                    worker.postMessage(message);
+                }
+                catch (error) {
+                    settle(id);
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        },
+        terminate: () => {
+            terminated = true;
+            rejectAll(new CancelledRequestError(`${name} was terminated`));
+            worker.terminate();
+        },
+    };
+}
+const DEFAULT_TIMEOUT_MS = 120_000;
+function isResponseMessage(message) {
+    if (typeof message !== 'object' || message === null)
+        return false;
+    const candidate = message;
+    if (typeof candidate.id !== 'number' || typeof candidate.ok !== 'boolean') {
+        return false;
+    }
+    return candidate.ok || typeof candidate.message === 'string';
+}
+function positiveMilliseconds(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? value
+        : fallback;
+}
+//# sourceMappingURL=workerChannel.js.map

package/lib/worker/core/workerChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerChannel.js","sourceRoot":"","sources":["../../../src/worker/core/workerChannel.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "Assembled React components shared by the cheminfo sites: a Cite button and an ecosystem menu",
   "author": "Luc Patiny",
@@ -14,11 +14,14 @@
   "exports": {
     "./core": "./lib/core.js",
     "./orbital": "./lib/orbital.js",
-    "./ui": "./lib/ui.js"
+    "./structure": "./lib/structure.js",
+    "./ui": "./lib/ui.js",
+    "./styles/*.css": "./styles/*.css"
   },
   "files": [
     "lib",
-    "src"
+    "src",
+    "styles"
   ],
   "scripts": {
     "build-storybook": "storybook build",
@@ -54,9 +57,11 @@
     "eslint-config-cheminfo-react": "^20.1.0",
     "eslint-config-cheminfo-typescript": "^22.1.0",
     "molstar": "^5.11.0",
+    "openchemlib": "^9.25.0",
     "prettier": "^3.9.6",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
+    "react-ocl": "^8.7.2",
     "react-science": "^23.0.0",
     "rimraf": "^6.1.3",
     "storybook": "^10.5.8",
@@ -66,10 +71,12 @@
   },
   "peerDependencies": {
     "@blueprintjs/core": "^6.18.0",
+    "molstar": "^5.11.0",
+    "openchemlib": "^9.24.0",
     "react": "^18.3.1 || >=19",
     "react-dom": "^18.3.1 || >=19",
-    "react-science": "^20.6.2 || ^21.0.0 || ^22.0.0 || ^23.0.0",
-    "molstar": "^5.11.0"
+    "react-ocl": "^8.7.1",
+    "react-science": "^20.6.2 || ^21.0.0 || ^22.0.0 || ^23.0.0"
   },
   "repository": {
     "type": "git",
@@ -82,6 +89,12 @@
   "peerDependenciesMeta": {
     "molstar": {
       "optional": true
+    },
+    "openchemlib": {
+      "optional": true
+    },
+    "react-ocl": {
+      "optional": true
     }
   }
 }

package/src/capsule/ui/CapsuleFilter.tsx

@@ -0,0 +1,119 @@
+import type { Intent } from '@blueprintjs/core';
+import { Tag } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+/** One capsule of a {@link CapsuleFilter} row. */
+export interface CapsuleOption<TValue extends string = string> {
+  /** What picking this capsule selects. */
+  value: TValue;
+  /** What the capsule reads. */
+  label: string;
+  /**
+   * How many rows the capsule keeps, written after the label.
+   * @default undefined — the capsule carries no count
+   */
+  count?: number;
+  /**
+   * Colour of the capsule, which says what the outcome means rather than
+   * whether it is selected.
+   * @default 'none'
+   */
+  intent?: Intent;
+  /**
+   * What the pointer is told when it rests on the capsule.
+   * @default undefined
+   */
+  title?: string;
+}
+
+/** What a row of filter capsules needs. */
+export interface CapsuleFilterProps<TValue extends string = string> {
+  /** One entry per capsule, in the order they are drawn. */
+  options: ReadonlyArray<CapsuleOption<TValue>>;
+  /** The selected capsule. */
+  value: TValue;
+  /** Called with the newly picked value. */
+  onChange: (value: TValue) => void;
+  /**
+   * What the group is called, for a screen reader reaching the row.
+   * @default 'Filter'
+   */
+  label?: string;
+  /**
+   * How a count is written.
+   * @default the number in the reader's locale, e.g. `1,204`
+   */
+  formatCount?: (count: number) => string;
+  /**
+   * Class the row carries, in addition to `capsule-filter`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The row of capsules that narrows a table to one outcome.
+ *
+ * Every capsule keeps its semantic colour whether or not it is selected, so
+ * what a status means stays learnable — the filled shape is what encodes the
+ * selection. Each is a real interactive tag, so the row is reachable by tab and
+ * a capsule answers to Enter and Space.
+ * @param props - See {@link CapsuleFilterProps}.
+ * @returns The capsule row.
+ */
+export function CapsuleFilter<TValue extends string = string>(
+  props: CapsuleFilterProps<TValue>,
+): ReactElement {
+  const {
+    options,
+    value,
+    onChange,
+    label = 'Filter',
+    formatCount = defaultFormatCount,
+    className,
+  } = props;
+
+  return (
+    <div
+      role="group"
+      aria-label={label}
+      className={
+        className === undefined
+          ? 'capsule-filter'
+          : `capsule-filter ${className}`
+      }
+      style={ROW_STYLE}
+    >
+      {options.map((option) => {
+        const selected = option.value === value;
+        return (
+          <Tag
+            key={option.value}
+            interactive
+            round
+            minimal={!selected}
+            intent={option.intent}
+            aria-pressed={selected}
+            htmlTitle={option.title}
+            onClick={() => onChange(option.value)}
+          >
+            {option.count === undefined
+              ? option.label
+              : `${option.label} (${formatCount(option.count)})`}
+          </Tag>
+        );
+      })}
+    </div>
+  );
+}
+
+function defaultFormatCount(count: number): string {
+  return count.toLocaleString();
+}
+
+const ROW_STYLE = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 6,
+} as const satisfies CSSProperties;

package/src/capsule/ui/index.ts

@@ -0,0 +1,2 @@
+export type { CapsuleFilterProps, CapsuleOption } from './CapsuleFilter.tsx';
+export { CapsuleFilter } from './CapsuleFilter.tsx';

package/src/chrome/ui/NavLink.tsx

@@ -0,0 +1,88 @@
+import { Icon } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+
+import type { NavItem } from './navItem.ts';
+import { isModifiedClick } from './navItem.ts';
+
+export interface NavLinkProps {
+  /** The entry being drawn. */
+  item: NavItem;
+  /**
+   * Whether this is the page on show, which is the one thing in the bar the
+   * brand tint is spent on.
+   * @default false
+   */
+  active?: boolean;
+  /**
+   * Extra class names, for a site reaching one entry of its own bar.
+   * `nav-link` is always carried as well.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * One entry of a site header, as a link when it has an address and as a button
+ * otherwise. Both carry `nav-link`, so the row reads as one menu rather than as
+ * a button dropped among addresses.
+ * @param props - The entry, whether it is the page on show, and extra classes.
+ * @returns The entry.
+ */
+export function NavLink(props: NavLinkProps): ReactElement {
+  const { item, active = false, className } = props;
+  const { href, external = false, onSelect, title } = item;
+
+  const classes = [
+    'nav-link',
+    active ? 'nav-link--active' : null,
+    className ?? null,
+  ]
+    .filter((part) => part !== null)
+    .join(' ');
+
+  if (href === undefined) {
+    return (
+      <button
+        type="button"
+        className={classes}
+        title={title}
+        aria-label={title}
+        onClick={onSelect}
+      >
+        <NavLinkBody item={item} />
+      </button>
+    );
+  }
+
+  return (
+    <a
+      className={classes}
+      href={href}
+      title={title}
+      aria-label={title}
+      target={external ? '_blank' : undefined}
+      rel={external ? 'noreferrer' : undefined}
+      onClick={(event) => {
+        if (onSelect === undefined || external || isModifiedClick(event)) {
+          return;
+        }
+        event.preventDefault();
+        onSelect();
+      }}
+    >
+      <NavLinkBody item={item} />
+    </a>
+  );
+}
+
+function NavLinkBody(props: { item: NavItem }): ReactNode {
+  const { icon, label, after } = props.item;
+
+  return (
+    <>
+      {icon === undefined ? null : <Icon icon={icon} size={14} />}
+      {label}
+      {after}
+    </>
+  );
+}

package/src/chrome/ui/NavMenuButton.tsx

@@ -0,0 +1,95 @@
+import type { IconName, PopoverNextProps } from '@blueprintjs/core';
+import { Icon, Menu, MenuItem, PopoverNext } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+
+import type { NavItem } from './navItem.ts';
+import { isModifiedClick } from './navItem.ts';
+
+export interface NavMenuButtonProps {
+  /** Text of the trigger, which is also what a screen reader is told. */
+  label: string;
+  /** The pages the menu holds, in the order it lists them. */
+  items: readonly NavItem[];
+  /**
+   * Which page is on show, named by its `id`. The trigger takes the brand tint
+   * when the menu is the one holding it.
+   * @default undefined
+   */
+  activeId?: string;
+  /**
+   * Glyph before the label.
+   * @default undefined
+   */
+  icon?: IconName;
+  /**
+   * Side the menu opens on.
+   * @default 'bottom-start'
+   */
+  placement?: PopoverNextProps['placement'];
+  /**
+   * What the menu adds under the pages — a divider and an action, typically.
+   * @default undefined
+   */
+  children?: ReactNode;
+}
+
+/**
+ * The pages that do not need a place of their own in the bar, folded into one
+ * menu. The trigger is dressed as a `nav-link`, so it reads as one of the
+ * entries beside it rather than as a button dropped among them.
+ * @param props - The label, the pages, the page on show, and how the menu
+ * opens.
+ * @returns The trigger and its menu.
+ */
+export function NavMenuButton(props: NavMenuButtonProps): ReactElement {
+  const {
+    label,
+    items,
+    activeId,
+    icon,
+    placement = 'bottom-start',
+    children,
+  } = props;
+
+  const holdsActive = items.some((item) => item.id === activeId);
+
+  return (
+    <PopoverNext
+      placement={placement}
+      content={
+        <Menu className="nav-menu">
+          {items.map((item) => (
+            <MenuItem
+              key={item.id}
+              icon={item.icon}
+              text={item.label}
+              // A real address, so a crawler reaching the menu can follow it
+              // and a middle click opens a tab of its own.
+              href={item.href}
+              target={item.external ? '_blank' : undefined}
+              active={item.id === activeId}
+              onClick={(event) => {
+                if (item.onSelect === undefined || isModifiedClick(event)) {
+                  return;
+                }
+                event.preventDefault();
+                item.onSelect();
+              }}
+            />
+          ))}
+          {children}
+        </Menu>
+      }
+    >
+      <button
+        type="button"
+        className={holdsActive ? 'nav-link nav-link--active' : 'nav-link'}
+        aria-label={label}
+      >
+        {icon === undefined ? null : <Icon icon={icon} size={14} />}
+        {label}
+        <Icon icon="caret-down" size={14} />
+      </button>
+    </PopoverNext>
+  );
+}

package/src/chrome/ui/SiteFooter.tsx

@@ -0,0 +1,65 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import { EcosystemLinks } from '../../ecosystem/ui/EcosystemLinks.tsx';
+
+export interface SiteFooterProps {
+  /** The site the footer sits on, which is written but never linked. */
+  siteId: SiteId;
+  /**
+   * How much of each sibling site is written. `grid` gives every one its mark,
+   * its name and the line saying what it does; `row` writes the names only.
+   * @default 'grid'
+   */
+  layout?: 'grid' | 'row';
+  /**
+   * What introduces the family.
+   * @default undefined
+   */
+  heading?: string;
+  /**
+   * Whether the page is framed in another site, in which case no footer is
+   * drawn at all.
+   * @default false
+   */
+  embedded?: boolean;
+  /**
+   * What the site adds under the family — a licence line, a version, a link to
+   * the sources.
+   * @default undefined
+   */
+  children?: ReactNode;
+}
+
+/**
+ * The strip under every page of the family: each sibling site as a plain link,
+ * so a crawler — and a reader with no patience for menus — walks from one of
+ * our tools to the next. It carries `no-print`, because it is chrome.
+ * @param props - The site it sits on, how much of each sibling is written, and
+ * whatever the site adds below.
+ * @returns The footer, or nothing at all on an embedded page.
+ */
+export function SiteFooter(props: SiteFooterProps): ReactElement | null {
+  const {
+    siteId,
+    layout = 'grid',
+    heading,
+    embedded = false,
+    children,
+  } = props;
+
+  if (embedded) return null;
+
+  return (
+    <footer className="app-footer no-print">
+      <div className="app-footer__inner">
+        <EcosystemLinks
+          currentSiteId={siteId}
+          layout={layout}
+          heading={heading}
+        />
+        {children}
+      </div>
+    </footer>
+  );
+}

package/src/chrome/ui/SiteHeader.tsx

@@ -0,0 +1,119 @@
+import type { ReactElement, ReactNode } from 'react';
+import { Fragment } from 'react';
+
+import { siteById } from '../../ecosystem/core/lookup.ts';
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import { Wordmark } from '../../ecosystem/ui/Wordmark.tsx';
+import { SiteMark } from '../../ecosystem/ui/marks.tsx';
+
+import { NavLink } from './NavLink.tsx';
+import type { NavItem } from './navItem.ts';
+import { isModifiedClick } from './navItem.ts';
+
+export interface SiteHeaderProps {
+  /** The site the bar belongs to, which draws its mark and writes its name. */
+  siteId: SiteId;
+  /** The pages, in the order the bar lists them. */
+  nav: readonly NavItem[];
+  /**
+   * Which of the pages is on show, named by its `id`.
+   * @default undefined
+   */
+  activeId?: string;
+  /**
+   * The utilities pushed to the right edge — Cite, Tools, Share, sign in. They
+   * arrive dressed as bar items, so a plain `nav-link` and a `CiteButton` read
+   * alike beside each other.
+   * @default undefined
+   */
+  actions?: ReactNode;
+  /**
+   * Draws one page the site's own way, for a bar whose entries need a tooltip
+   * or a wrapper of their own.
+   * @default undefined
+   */
+  renderNavItem?: (item: NavItem, isActive: boolean) => ReactNode;
+  /**
+   * Whether the page is framed in another site, in which case no bar is drawn
+   * at all — what a host page frames already carries its own navigation.
+   * @default false
+   */
+  embedded?: boolean;
+  /**
+   * Where the brand leads.
+   * @default '/'
+   */
+  homeHref?: string;
+  /**
+   * What the site does when the brand is picked, for a page that routes in
+   * place. A modified click is left to the browser.
+   * @default undefined
+   */
+  onHome?: () => void;
+  /**
+   * Edge of the site's mark, in pixels.
+   * @default 28
+   */
+  markSize?: number;
+}
+
+/**
+ * The bar every site of the family carries: the brand linking home at the left,
+ * the pages next to it, and the utilities pushed to the right edge by the
+ * spacer.
+ * @param props - The site, its pages, its utilities, and whether the page is
+ * framed in another site.
+ * @returns The bar, or nothing at all on an embedded page.
+ */
+export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
+  const {
+    siteId,
+    nav,
+    activeId,
+    actions,
+    renderNavItem,
+    embedded = false,
+    homeHref = '/',
+    onHome,
+    markSize = 28,
+  } = props;
+
+  if (embedded) return null;
+
+  const site = siteById(siteId);
+
+  return (
+    <header className="app-header no-print">
+      <div className="app-header__inner">
+        <a
+          className="brand"
+          href={homeHref}
+          title={site.host}
+          onClick={(event) => {
+            if (onHome === undefined || isModifiedClick(event)) return;
+            event.preventDefault();
+            onHome();
+          }}
+        >
+          <SiteMark siteId={siteId} size={markSize} />
+          <Wordmark siteId={siteId} />
+        </a>
+        <nav className="app-header-nav">
+          {nav.map((item) => (
+            <Fragment key={item.id}>
+              {renderNavItem === undefined ? (
+                <NavLink item={item} active={item.id === activeId} />
+              ) : (
+                renderNavItem(item, item.id === activeId)
+              )}
+            </Fragment>
+          ))}
+        </nav>
+        <span className="spacer" />
+        {actions === undefined ? null : (
+          <div className="app-header-actions">{actions}</div>
+        )}
+      </div>
+    </header>
+  );
+}