react-cheminfo 0.64.1 → 0.65.0

package/src/shell/ui/ShellFrame.tsx

@@ -0,0 +1,180 @@
+/**
+ * The body of `SiteShell`, once the route has been read: the theme, the bar,
+ * the page and the footer.
+ */
+
+import type { ReactElement, ReactNode } from 'react';
+import { isValidElement } from 'react';
+
+import { AboutPage } from '../../about/ui/AboutPage.tsx';
+import { AboutButton } from '../../chrome/ui/AboutButton.tsx';
+import { SiteFooter } from '../../chrome/ui/SiteFooter.tsx';
+import { SiteHeader } from '../../chrome/ui/SiteHeader.tsx';
+import { useCompactHeader } from '../../chrome/ui/useCompactHeader.ts';
+import { CiteButton } from '../../citation/ui/CiteButton.tsx';
+import { EcosystemButton } from '../../ecosystem/ui/EcosystemButton.tsx';
+import { SiteTheme } from '../../ecosystem/ui/SiteTheme.tsx';
+import type { ShareParamCodecs } from '../../share/core/index.ts';
+import { HiddenPartsProvider } from '../../share/ui/HiddenPartsProvider.tsx';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+
+import { ShareControl } from './ShareControl.tsx';
+import type { ShellSlot, SiteShellProps } from './SiteShell.tsx';
+
+/**
+ * Draw the shell.
+ * @param props - The shell's props, the route already read.
+ * @returns The page in its chrome.
+ */
+export function ShellFrame<Codecs extends ShareParamCodecs, Tab extends string>(
+  props: SiteShellProps<Codecs, Tab>,
+): ReactElement {
+  const {
+    siteId,
+    site,
+    mark,
+    markSize,
+    nav,
+    activeId,
+    homeHref,
+    onHome,
+    renderNavItem,
+    navPart = 'tabs',
+    width = 'page',
+    embedded = false,
+    hidden,
+    about = false,
+    contact,
+    belowHeader,
+    mainClassName,
+    mainTestId,
+    footer = {},
+    account,
+    children,
+  } = props;
+  const compact = useCompactHeader();
+  const footerSiteId = footer === false ? undefined : (footer.siteId ?? siteId);
+  const aboutOnShow = about !== false && about.active === true;
+
+  const page = (
+    <>
+      {siteId === undefined ? (
+        <SiteTheme site={site} />
+      ) : (
+        <SiteTheme siteId={siteId} />
+      )}
+      <div className="site-shell">
+        <SiteHeader
+          siteId={siteId}
+          site={site}
+          mark={mark}
+          markSize={markSize}
+          embedded={embedded}
+          width={width}
+          nav={hidden?.includes(navPart) ? [] : nav}
+          activeId={aboutOnShow ? (about.id ?? 'about') : activeId}
+          homeHref={homeHref}
+          onHome={onHome}
+          renderNavItem={renderNavItem}
+          contact={contact}
+          actions={<ShellActions {...props} compact={compact} />}
+          share={<ShellShare {...props} compact={compact} />}
+          account={account}
+        />
+        {embedded ? null : belowHeader}
+        <main
+          className={joinClassNames(
+            'site-shell__main',
+            width === 'full' ? 'site-shell__main--full' : undefined,
+            embedded ? 'site-shell__main--embedded' : undefined,
+            mainClassName,
+          )}
+          data-testid={mainTestId}
+        >
+          {aboutOnShow
+            ? (about.page ?? <AboutPage content={about.content} />)
+            : children}
+        </main>
+      </div>
+      {footer === false || footerSiteId === undefined ? null : (
+        <SiteFooter
+          siteId={footerSiteId}
+          embedded={embedded}
+          width={width}
+          heading={footer.heading}
+          layout={footer.layout}
+        >
+          {footer.note === undefined ? null : (
+            <p className="app-footer__note">{footer.note}</p>
+          )}
+          {footer.children}
+        </SiteFooter>
+      )}
+    </>
+  );
+
+  return hidden === undefined ? (
+    page
+  ) : (
+    <HiddenPartsProvider hidden={hidden}>{page}</HiddenPartsProvider>
+  );
+}
+
+type ActionProps<
+  Codecs extends ShareParamCodecs,
+  Tab extends string,
+> = SiteShellProps<Codecs, Tab> & { compact: boolean };
+
+function ShellActions<Codecs extends ShareParamCodecs, Tab extends string>(
+  props: ActionProps<Codecs, Tab>,
+): ReactNode {
+  const {
+    siteId,
+    about = false,
+    cite,
+    ecosystem = true,
+    actionsAfterAbout,
+    actionsAfterCite,
+    actions,
+    language,
+    compact,
+  } = props;
+  const works = cite ?? (about === false ? [] : (about.content.cite ?? []));
+  return (
+    <>
+      {about === false ? null : (
+        <AboutButton
+          id={about.id}
+          href={about.href ?? '/about'}
+          active={about.active}
+          onSelect={about.onSelect}
+          label={about.label}
+          title={about.title}
+        />
+      )}
+      {fill(actionsAfterAbout, compact)}
+      {works === false || works.length === 0 ? null : (
+        <CiteButton works={works} compact={compact} />
+      )}
+      {fill(actionsAfterCite, compact)}
+      {ecosystem ? (
+        <EcosystemButton currentSiteId={siteId} compact={compact} />
+      ) : null}
+      {fill(actions, compact)}
+      {fill(language, compact)}
+    </>
+  );
+}
+
+function ShellShare<Codecs extends ShareParamCodecs, Tab extends string>(
+  props: ActionProps<Codecs, Tab>,
+): ReactNode {
+  const { share, siteId, compact } = props;
+  if (share === undefined) return null;
+  if (isValidElement(share)) return share;
+  return <ShareControl<Codecs> siteId={siteId} compact={compact} {...share} />;
+}
+
+function fill(slot: ShellSlot, compact: boolean): ReactNode {
+  return typeof slot === 'function' ? slot(compact) : slot;
+}

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. */