react-cheminfo 0.64.0 → 0.65.0

package/src/shell/ui/SiteShell.tsx

@@ -0,0 +1,297 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import type { AboutContent } from '../../about/core/about.ts';
+import type { NavItem } from '../../chrome/ui/navItem.ts';
+import type { CitedWork } from '../../citation/core/works.ts';
+import type { SiteId, SiteRecord } from '../../ecosystem/core/sites.ts';
+import { writeRoute } from '../../router/core/history.ts';
+import type { TabRouter } from '../../router/core/tabRouter.ts';
+import { useTabRoute } from '../../router/ui/useTabRoute.ts';
+import type { ShareParamCodecs } from '../../share/core/index.ts';
+
+import type { ShareControlProps } from './ShareControl.tsx';
+import { ShellFrame } from './ShellFrame.tsx';
+
+/**
+ * A slot of the bar: an element, or a function handed whether the bar has run
+ * out of room, so a site's own entries fold with the shared ones.
+ */
+export type ShellSlot = ReactNode | ((compact: boolean) => ReactNode);
+
+/** The site's About: the record, and where it is served. */
+export interface ShellAbout {
+  /** What the site says about itself; its works also feed the Cite button. */
+  content: AboutContent;
+  /**
+   * The About address.
+   * @default the router's address of the About tab, or `/about` without one
+   */
+  href?: string;
+  /**
+   * Whether the About is the page on show, in which case it is what the main
+   * area draws.
+   * @default whether the router's tab is the About tab, `false` without one
+   */
+  active?: boolean;
+  /**
+   * What the site does when the entry is picked, for a page that routes in
+   * place.
+   * @default a move to the About tab with a router, the plain link without
+   */
+  onSelect?: () => void;
+  /**
+   * What the active entry is named by.
+   * @default 'about'
+   */
+  id?: string;
+  /**
+   * What the entry reads.
+   * @default the chrome's own word for it
+   */
+  label?: string;
+  /**
+   * What the pointer is told.
+   * @default the chrome's own sentence
+   */
+  title?: string;
+  /**
+   * The page itself, for a site whose About carries more than its record — a
+   * section of its own, a sign-in, a mark.
+   * @default `<AboutPage content={content} />`
+   */
+  page?: ReactNode;
+}
+
+/** The strip under the page. */
+export interface ShellFooter {
+  /**
+   * The site the footer sits on, for a shell given a `site` record rather
+   * than a `siteId`.
+   * @default the shell's `siteId`, and no footer without one
+   */
+  siteId?: SiteId;
+  /**
+   * What introduces the family.
+   * @default undefined
+   */
+  heading?: string;
+  /**
+   * How much of each sibling is written.
+   * @default 'grid'
+   */
+  layout?: 'grid' | 'row';
+  /**
+   * One line under the family, set as the footer's note.
+   * @default undefined
+   */
+  note?: ReactNode;
+  /**
+   * Anything else under the family.
+   * @default undefined
+   */
+  children?: ReactNode;
+}
+
+/** What {@link SiteShell} needs. */
+export interface SiteShellProps<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+  Tab extends string = string,
+> {
+  /**
+   * The site, named. One of `site` and `siteId` is required.
+   * @default undefined
+   */
+  siteId?: SiteId;
+  /**
+   * The site, passed rather than named, for one outside the family's registry.
+   * @default undefined
+   */
+  site?: SiteRecord;
+  /**
+   * The site's own mark, for a site the shared glyphs do not hold.
+   * @default the family's mark for the site
+   */
+  mark?: ReactNode;
+  /**
+   * Edge of the mark, in pixels.
+   * @default 28
+   */
+  markSize?: number;
+  /**
+   * The site's router. With it the shell follows the address itself: the
+   * page on show is the tab it names, and the About tab is served as the About
+   * page.
+   * @default undefined — the page says which entry is active
+   */
+  router?: TabRouter<Tab>;
+  /**
+   * The tab the About is served at.
+   * @default 'about'
+   */
+  aboutTab?: Tab;
+  /** The pages, in the order the bar lists them; About is not one of them. */
+  nav: readonly NavItem[];
+  /**
+   * Which of the pages is on show.
+   * @default the router's tab, or none without a router
+   */
+  activeId?: string;
+  /**
+   * Where the brand leads.
+   * @default '/'
+   */
+  homeHref?: string;
+  /**
+   * What the site does when the brand is picked.
+   * @default undefined
+   */
+  onHome?: () => void;
+  /**
+   * Draws one page the site's own way.
+   * @default undefined
+   */
+  renderNavItem?: (item: NavItem, isActive: boolean) => ReactNode;
+  /**
+   * The part a link hides the pages with; the bar then lists none.
+   * @default 'tabs'
+   */
+  navPart?: string;
+  /**
+   * How wide the bar, the page and the footer run, all three alike.
+   * @default 'page'
+   */
+  width?: 'page' | 'full';
+  /**
+   * Whether the page is framed in another site: no bar, no footer, and the
+   * frame as the margin.
+   * @default false
+   */
+  embedded?: boolean;
+  /**
+   * The parts the link switches off, provided to every `PagePart` below.
+   * @default undefined — no provider; the page brings its own
+   */
+  hidden?: readonly string[];
+  /**
+   * The About entry and page; `false` leaves both out.
+   * @default false
+   */
+  about?: ShellAbout | false;
+  /**
+   * The works the Cite button offers; `false` leaves it out.
+   * @default the About's works, and no button when it has none
+   */
+  cite?: readonly CitedWork[] | false;
+  /**
+   * Whether the Tools menu of the family is in the bar.
+   * @default true
+   */
+  ecosystem?: boolean;
+  /**
+   * Entries between About and Cite — an API link, a version.
+   * @default undefined
+   */
+  actionsAfterAbout?: ShellSlot;
+  /**
+   * Entries between Cite and Tools — a feedback form, a specification.
+   * @default undefined
+   */
+  actionsAfterCite?: ShellSlot;
+  /**
+   * Entries after Tools — a unit picker, an admin action.
+   * @default undefined
+   */
+  actions?: ShellSlot;
+  /**
+   * The language switcher, after the site's own entries.
+   * @default undefined
+   */
+  language?: ShellSlot;
+  /**
+   * Who is signed in, at the right end.
+   * @default undefined
+   */
+  account?: ReactNode;
+  /**
+   * The Share entry: what `ShareControl` is given, the shell passing it the
+   * site and the compact state, or a control of the site's own.
+   * @default undefined — no Share entry
+   */
+  share?: ShareControlProps<Codecs> | ReactElement;
+  /**
+   * The contact form of the Contact entry, or `false` to leave it out.
+   * @default the family's form
+   */
+  contact?: string | false;
+  /**
+   * What sits between the bar and the page — a tagline, a banner — dropped
+   * with the bar when the page is framed.
+   * @default undefined
+   */
+  belowHeader?: ReactNode;
+  /**
+   * Classes the main area carries beside the shell's own.
+   * @default undefined
+   */
+  mainClassName?: string;
+  /**
+   * `data-testid` of the main area.
+   * @default undefined
+   */
+  mainTestId?: string;
+  /**
+   * The strip under the page, or `false` for none on this page.
+   * @default the family's links alone
+   */
+  footer?: ShellFooter | false;
+  /** The page the address names. */
+  children: ReactNode;
+}
+
+/**
+ * The chrome every site of the family carries, around its page: the theme,
+ * the bar with About · Cite · Tools · Contact · Share at its right, the page,
+ * and the footer linking every sibling. A framed page gets the page alone.
+ *
+ * Everything the bar holds is the shared components, in the family's order; a
+ * site fills the slots between them and never re-orders them. With a router,
+ * the shell also follows the address: it marks the tab on show and serves the
+ * About tab as the shared About page.
+ * @param props - See {@link SiteShellProps}.
+ * @returns The page in its chrome.
+ */
+export function SiteShell<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+  Tab extends string = string,
+>(props: SiteShellProps<Codecs, Tab>): ReactElement {
+  const { router } = props;
+  if (router === undefined) return <ShellFrame {...props} />;
+  return <RoutedShell {...props} router={router} />;
+}
+
+function RoutedShell<Codecs extends ShareParamCodecs, Tab extends string>(
+  props: SiteShellProps<Codecs, Tab> & { router: TabRouter<Tab> },
+): ReactElement {
+  const { router, aboutTab = 'about' as Tab, about, activeId } = props;
+  const route = useTabRoute(router);
+  const routedAbout: ShellAbout | false =
+    about === undefined || about === false
+      ? false
+      : {
+          ...about,
+          href: about.href ?? router.format({ tab: aboutTab }),
+          active: about.active ?? route.tab === aboutTab,
+          onSelect:
+            about.onSelect ??
+            (() => {
+              writeRoute(router, { tab: aboutTab });
+            }),
+        };
+  return (
+    <ShellFrame
+      {...props}
+      about={routedAbout}
+      activeId={activeId ?? route.tab}
+    />
+  );
+}

package/src/shell/ui/index.ts

@@ -0,0 +1,9 @@
+export type { ShareControlProps } from './ShareControl.tsx';
+export { ShareControl } from './ShareControl.tsx';
+export type {
+  ShellAbout,
+  ShellFooter,
+  ShellSlot,
+  SiteShellProps,
+} from './SiteShell.tsx';
+export { SiteShell } from './SiteShell.tsx';

package/src/state/core/index.ts

@@ -1,3 +1,4 @@
+export type { LegacyStorageKey } from './legacyEntries.ts';
 export type {
   BucketRead,
   PersistBucketOptions,

package/src/state/core/legacyEntries.ts

@@ -0,0 +1,76 @@
+import {
+  readStorageText,
+  removeStorageEntry,
+  writeStorageEntry,
+  writeStorageText,
+} from './storageEntry.ts';
+
+/**
+ * An entry a bucket was kept under before it took its versioned key: the full
+ * storage key, as written, or the key with a function turning its payload into
+ * the bucket's current shape.
+ */
+export type LegacyStorageKey =
+  | string
+  | {
+      /** The full storage key, e.g. `storage` or `mixonat:preferences`. */
+      key: string;
+      /**
+       * Turn the old payload, as `JSON.parse` read it, into what the bucket
+       * stores now. Answering `undefined`, or throwing, adopts nothing.
+       */
+      migrate: (stored: unknown) => unknown;
+    };
+
+/**
+ * Carry a returning visitor's entry over to the versioned key a bucket now
+ * uses, once.
+ *
+ * The first legacy key holding something is copied — as it is, or through its
+ * `migrate` — and only while the versioned entry does not exist, so it never
+ * overwrites what the bucket has written since. With `forget`, every legacy
+ * entry found is removed afterwards, adopted or not, so a bucket cleared later
+ * is not filled again from the old key on the next visit. Best effort, like
+ * every access to the store: one that cannot be reached adopts nothing.
+ * @param storageKey - The versioned key the bucket occupies.
+ * @param legacyKeys - The older entries, the preferred one first.
+ * @param forget - Whether to remove the legacy entries once read.
+ */
+export function adoptLegacyEntries(
+  storageKey: string,
+  legacyKeys: readonly LegacyStorageKey[],
+  forget: boolean,
+): void {
+  if (legacyKeys.length === 0) return;
+  let adopted = readStorageText(storageKey) !== null;
+  for (const legacy of legacyKeys) {
+    const key = typeof legacy === 'string' ? legacy : legacy.key;
+    if (key === storageKey) continue;
+    const text = readStorageText(key);
+    if (text === null) continue;
+    if (!adopted) {
+      adopted =
+        typeof legacy === 'string'
+          ? writeStorageText(storageKey, text)
+          : writeMigrated(storageKey, text, legacy.migrate);
+    }
+    if (forget) removeStorageEntry(key);
+  }
+}
+
+function writeMigrated(
+  storageKey: string,
+  text: string,
+  migrate: (stored: unknown) => unknown,
+): boolean {
+  let value: unknown;
+  try {
+    value = migrate(JSON.parse(text));
+  } catch {
+    // A payload nobody can read any more is left to the defaults.
+    return false;
+  }
+  if (value === undefined) return false;
+  writeStorageEntry(storageKey, value);
+  return readStorageText(storageKey) !== null;
+}

package/src/state/core/persistBucket.ts

@@ -1,3 +1,5 @@
+import type { LegacyStorageKey } from './legacyEntries.ts';
+import { adoptLegacyEntries } from './legacyEntries.ts';
 import { isPlainRecord, mergeStored } from './mergeStored.ts';
 import {
   readStorageEntry,
@@ -16,30 +18,46 @@ import {
  * quota is full still gets a working site, with their preferences lasting only
  * as long as the tab.
  * @param options - See {@link PersistBucketOptions}.
- * @returns The three ways to use the bucket: read it, write it, forget it.
+ * @returns The ways to use the bucket: read it, write it, forget it, and
+ * hear another tab write it.
  */
 export function persistBucket<T extends object>(
   options: PersistBucketOptions<T>,
 ): PersistedBucket<T> {
   const { key, version = 1, defaults, onQuotaExceeded } = options;
+  const { legacyKeys = [], forgetLegacyKeys = false } = options;
   const storageKey = versionedStorageKey(key, version);
+  adoptLegacyEntries(storageKey, legacyKeys, forgetLegacyKeys);
+
+  function read(): BucketRead<T> {
+    const stored = readStorageEntry(storageKey);
+    const usable = isPlainRecord(stored) ? stored : undefined;
+    return {
+      value: mergeStored(defaults, usable),
+      firstRun: usable === undefined,
+    };
+  }
 
   return {
     storageKey,
-    read: () => {
-      const stored = readStorageEntry(storageKey);
-      const usable = isPlainRecord(stored) ? stored : undefined;
-      return {
-        value: mergeStored(defaults, usable),
-        firstRun: usable === undefined,
-      };
-    },
+    read,
     write: (value: T) => {
       writeStorageEntry(storageKey, value, onQuotaExceeded);
     },
     clear: () => {
       removeStorageEntry(storageKey);
     },
+    subscribe: (listener) => {
+      function handleStorage(event: Event): void {
+        const change = event as { key?: unknown; newValue?: unknown };
+        if (change.key !== storageKey || change.newValue === null) return;
+        listener(read());
+      }
+      globalThis.addEventListener?.('storage', handleStorage);
+      return () => {
+        globalThis.removeEventListener?.('storage', handleStorage);
+      };
+    },
   };
 }
 
@@ -70,9 +88,23 @@ export interface PersistBucketOptions<T extends object> {
    * @default undefined
    */
   onQuotaExceeded?: (error: unknown) => void;
+  /**
+   * The entries the bucket was kept under before this key: an unversioned
+   * one, another site's, or a shape that needs a `migrate`. The first holding
+   * something is copied over once, while the versioned entry does not exist.
+   * @default []
+   */
+  legacyKeys?: readonly LegacyStorageKey[];
+  /**
+   * Remove every legacy entry found once it has been read, so a bucket
+   * cleared later is not filled again from the old key. Left off, the old
+   * entries stay where they are.
+   * @default false
+   */
+  forgetLegacyKeys?: boolean;
 }
 
-/** The three ways a page uses its bucket. */
+/** The ways a page uses its bucket. */
 export interface PersistedBucket<T extends object> {
   /** The versioned key the bucket occupies, e.g. `smiles:exercises:v1`. */
   readonly storageKey: string;
@@ -82,6 +114,14 @@ export interface PersistedBucket<T extends object> {
   write: (value: T) => void;
   /** Forget the bucket, leaving whatever the page holds in memory untouched. */
   clear: () => void;
+  /**
+   * Hear another tab of the same site store the bucket. The tab writing never
+   * hears its own write, and a removal is not news: the listener is handed
+   * what is stored now, merged over the defaults.
+   * @param listener - Called with the fresh read after each write elsewhere.
+   * @returns The function that stops listening.
+   */
+  subscribe: (listener: (read: BucketRead<T>) => void) => () => void;
 }
 
 /** What one read of a bucket found. */

package/src/state/core/persistSignalBucket.ts

@@ -1,5 +1,7 @@
+import type { LegacyStorageKey } from './legacyEntries.ts';
 import { isPlainRecord } from './mergeStored.ts';
 import { persistBucket } from './persistBucket.ts';
+import { readStorageText } from './storageEntry.ts';
 
 /**
  * Keep a tree of signals in `localStorage`, under one versioned key.
@@ -19,6 +21,12 @@ import { persistBucket } from './persistBucket.ts';
  * the tracking is always done by the copy of the library that made the
  * signals. A member that is neither a signal nor a plain object is ignored.
  * Never put a `computed()` in a bucket: it cannot be written back.
+ *
+ * With `syncAcrossTabs`, every tab follows the entry: a tab opened before
+ * another one stored its work would otherwise write its stale copy over it. A
+ * write that would store what is already there is skipped, so two tabs cannot
+ * echo each other, and nothing is written while another tab's copy is being
+ * taken on.
  * @param options - See {@link PersistSignalBucketOptions}.
  * @returns The same bucket, rehydrated, so it can be exported directly.
  */
@@ -26,26 +34,51 @@ export function persistSignalBucket<TBucket extends object>(
   options: PersistSignalBucketOptions<TBucket>,
 ): TBucket {
   const { key, version, bucket, effect, onQuotaExceeded } = options;
+  const { legacyKeys, forgetLegacyKeys, syncAcrossTabs = false } = options;
   const stored = persistBucket({
     key,
     version,
     defaults: snapshotBucket(bucket),
     onQuotaExceeded,
+    legacyKeys,
+    forgetLegacyKeys,
   });
 
   const { value, firstRun } = stored.read();
   if (!firstRun) hydrateBucket(bucket, value);
 
   let subscribed = false;
+  let adopting = false;
   effect(() => {
     const snapshot = snapshotBucket(bucket);
     if (!subscribed) {
       subscribed = true;
       return;
     }
+    if (adopting) return;
+    if (
+      syncAcrossTabs !== false &&
+      readStorageText(stored.storageKey) === JSON.stringify(snapshot)
+    ) {
+      return;
+    }
     stored.write(snapshot);
   });
 
+  if (syncAcrossTabs !== false) {
+    stored.subscribe((read) => {
+      if (typeof syncAcrossTabs === 'function' && !syncAcrossTabs(bucket)) {
+        return;
+      }
+      adopting = true;
+      try {
+        hydrateBucket(bucket, read.value);
+      } finally {
+        adopting = false;
+      }
+    });
+  }
+
   return bucket;
 }
 
@@ -77,6 +110,25 @@ export interface PersistSignalBucketOptions<TBucket extends object> {
    * @default undefined
    */
   onQuotaExceeded?: (error: unknown) => void;
+  /**
+   * The entries the bucket was kept under before this key, the preferred one
+   * first; see `persistBucket`.
+   * @default []
+   */
+  legacyKeys?: readonly LegacyStorageKey[];
+  /**
+   * Remove every legacy entry found once it has been read.
+   * @default false
+   */
+  forgetLegacyKeys?: boolean;
+  /**
+   * Take on what another tab stores, and skip a write that would store what is
+   * already there. A function decides each time, handed the bucket as this tab
+   * holds it: a bucket of work in progress keeps its own while it has some,
+   * rather than two tabs overwriting each other in turn.
+   * @default false
+   */
+  syncAcrossTabs?: boolean | ((bucket: TBucket) => boolean);
 }
 
 interface SignalLeaf {

package/src/state/core/storageEntry.ts

@@ -81,6 +81,38 @@ export function removeStorageEntry(storageKey: string): void {
   }
 }
 
+/**
+ * Read one `localStorage` entry as the text it was stored as, so two copies of
+ * a payload can be compared without parsing either.
+ * @param storageKey - The full key.
+ * @returns The stored text, or `null` when there is none or the store cannot
+ * be reached.
+ */
+export function readStorageText(storageKey: string): string | null {
+  try {
+    return globalThis.localStorage?.getItem(storageKey) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write one `localStorage` entry as text, exactly as given. Best effort.
+ * @param storageKey - The full key.
+ * @param text - What to store.
+ * @returns Whether the store took it.
+ */
+export function writeStorageText(storageKey: string, text: string): boolean {
+  try {
+    const storage = globalThis.localStorage as Storage | undefined;
+    if (storage === undefined) return false;
+    storage.setItem(storageKey, text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function isQuotaExceeded(error: unknown): boolean {
   if (typeof error !== 'object' || error === null) return false;
   const { name, code } = error as { name?: unknown; code?: unknown };

package/src/structure/ui/StructureExportButton.tsx

@@ -0,0 +1,57 @@
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { OverlayIconButton } from '../../overlay/ui/OverlayIconButton.tsx';
+
+import { StructureExportDialog } from './StructureExportDialog.tsx';
+import type { StructureExportPanelProps } from './StructureExportPanel.tsx';
+
+/** What {@link StructureExportButton} hands over. */
+export interface StructureExportButtonProps extends StructureExportPanelProps {
+  /**
+   * What the glyph is called, for the pointer and for a screen reader.
+   * @default the chrome's own line, `Copy or save the structure: SMILES,
+   *   molfile`
+   */
+  label?: string;
+  /**
+   * Value of the `data-testid` attribute of the glyph.
+   * @default 'card-structure'
+   */
+  testId?: string;
+}
+
+/**
+ * The glyph beside a figure that hands its one structure over: as a SMILES,
+ * a molfile or an idCode, each copied with a click, or as a picture — the
+ * export dialog, the one the chat opens on its own molecule cards. It is drawn
+ * like the figure's other glyphs, so it sits in the `tools` of a `CardFigure`
+ * or of any overlay bar.
+ * @param props - The structure, the name of its files, and the glyph's name.
+ * @returns The glyph; the dialog is drawn over the page while it is open.
+ */
+export function StructureExportButton(
+  props: StructureExportButtonProps,
+): ReactElement {
+  const { label, testId = 'card-structure', ...structure } = props;
+  const t = useChromeT();
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <>
+      <OverlayIconButton
+        icon="export"
+        label={label ?? t('structure.export.glyph')}
+        active={isOpen}
+        opensMenu
+        testId={testId}
+        onClick={() => setIsOpen(true)}
+      />
+      <StructureExportDialog
+        {...structure}
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+      />
+    </>
+  );
+}

package/src/structure/ui/index.ts

@@ -25,6 +25,10 @@ export type { StructureEditorHelpProps } from './StructureEditorHelp.tsx';
 export { StructureEditorHelp } from './StructureEditorHelp.tsx';
 export type { StructureExportDialogProps } from './StructureExportDialog.tsx';
 export { StructureExportDialog } from './StructureExportDialog.tsx';
+export type { StructureExportButtonProps } from './StructureExportButton.tsx';
+export { StructureExportButton } from './StructureExportButton.tsx';
 export type { StructureExportPanelProps } from './StructureExportPanel.tsx';
 export type { ToolbarFloorOptions } from './useToolbarFloor.ts';
 export { useToolbarFloor } from './useToolbarFloor.ts';
+export type { StructureDraft } from './useStructureDraft.ts';
+export { useStructureDraft } from './useStructureDraft.ts';