react-cheminfo 0.64.0 → 0.65.0

package/src/share/core/keySetParam.ts

@@ -0,0 +1,92 @@
+import type { ShareParamCodec } from './params.ts';
+
+/** What {@link keySetParam} is configured with. */
+export interface KeySetParamOptions<Key extends string> {
+  /**
+   * The word an empty set is written as. An empty value is dropped from the
+   * address, so a link switching every key off has to say so in a word.
+   * @default 'none'
+   */
+  none?: string;
+  /**
+   * The set a link carrying nothing stands for, and the one deleted rather
+   * than written. `null` means the link then says nothing about the keys, so
+   * whatever the visitor stored is left alone.
+   * @default null
+   */
+  default?: readonly Key[] | null;
+  /**
+   * The set deleted from a link rather than written, when it is not the
+   * default — a site whose absent parameter leaves the visitor's stored keys
+   * alone, and whose own initial keys must not grow a plain visit a query
+   * string.
+   * @default the default set
+   */
+  omitted?: readonly Key[];
+}
+
+/**
+ * A set of keys a link switches on — the layers a figure draws,
+ * `?flags=breakdown,working` — written comma separated, in the order the keys
+ * are listed, so one selection always produces one link.
+ *
+ * A key the tool does not list is dropped rather than refused, so a link
+ * written before a key was renamed still opens; the word for nothing, `none`
+ * by default, reads as the empty set, and an absent or empty parameter as the
+ * default.
+ * @param keys - Every key the tool understands, in the order links write them.
+ * @param options - The word for nothing, and the default set.
+ * @returns The codec.
+ */
+export function keySetParam<Key extends string>(
+  keys: readonly Key[],
+  options: KeySetParamOptions<Key> = {},
+): ShareParamCodec<ReadonlySet<Key> | null> {
+  const none = options.none ?? 'none';
+  const fallback =
+    options.default === undefined || options.default === null
+      ? null
+      : orderKeys(new Set<string>(options.default), keys);
+  const omitted =
+    options.omitted === undefined
+      ? fallback
+      : orderKeys(new Set<string>(options.omitted), keys);
+  const omittedText = omitted === null ? null : writeKeys(omitted, keys);
+  return {
+    parse(raw) {
+      if (raw === null || raw.trim() === '') return fallback;
+      if (raw.trim() === none) return new Set<Key>();
+      const asked = new Set<string>();
+      for (const name of raw.split(',')) asked.add(name.trim());
+      return orderKeys(asked, keys);
+    },
+    serialize(value) {
+      if (value === null) return null;
+      const text = writeKeys(value, keys);
+      if (text === omittedText) return null;
+      return text === '' ? none : text;
+    },
+  };
+}
+
+function orderKeys<Key extends string>(
+  asked: ReadonlySet<string>,
+  keys: readonly Key[],
+): ReadonlySet<Key> {
+  const ordered = new Set<Key>();
+  for (const key of keys) {
+    if (asked.has(key)) ordered.add(key);
+  }
+  return ordered;
+}
+
+function writeKeys<Key extends string>(
+  value: ReadonlySet<Key>,
+  keys: readonly Key[],
+): string {
+  const on: string[] = [];
+  for (const key of keys) {
+    if (value.has(key)) on.push(key);
+  }
+  return on.join(',');
+}

package/src/share/core/vocabulary.ts

@@ -65,4 +65,12 @@ export interface ShareVocabulary<
    * @default {}
    */
   params?: Codecs;
+  /**
+   * The `?hide=` keys older links dropped the chrome with, before the site
+   * spoke `?embed` — `header`, `menu`. A link naming one still opens framed,
+   * because course pages built then must keep opening bare; the key is no part
+   * of the page, so it is never offered and never written back.
+   * @default []
+   */
+  legacyEmbedParts?: readonly string[];
 }

package/src/shell/ui/ShareControl.tsx

@@ -0,0 +1,150 @@
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { siteById } from '../../ecosystem/core/lookup.ts';
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { ShareParamCodecs } from '../../share/core/index.ts';
+import type { ShareButtonVariant } from '../../share/ui/ShareButton.tsx';
+import { ShareButton } from '../../share/ui/ShareButton.tsx';
+import type { ShareDialogProps } from '../../share/ui/ShareDialog.tsx';
+import { ShareDialog } from '../../share/ui/ShareDialog.tsx';
+
+/** What {@link ShareControl} needs: the dialog's props, and the button's. */
+export interface ShareControlProps<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> extends Omit<
+  ShareDialogProps<Codecs>,
+  'isOpen' | 'onClose' | 'search' | 'frameTitle'
+> {
+  /**
+   * The site the page belongs to, which names the frame `<host> — <title>`.
+   * @default undefined — the frame is named by the title alone
+   */
+  siteId?: SiteId;
+  /**
+   * What a screen reader announces the frame as.
+   * @default `<host> — <title>` with a `siteId`, the title without one
+   */
+  frameTitle?: string;
+  /**
+   * The address as it stands, so the tool's inputs travel with the link. A
+   * function is called only while the dialog is open, so a value that is costly
+   * to write — a pinned preference, a list of molecules — is written when a
+   * link is asked for and not on every render of the header.
+   * @default the query string of the page
+   */
+  search?: string | (() => string | undefined);
+  /**
+   * Whether the button keeps only its icon, in a bar that has run out of room.
+   * @default false
+   */
+  compact?: boolean;
+  /**
+   * Text of the button.
+   * @default the chrome's own word for it, in the language of the page
+   */
+  buttonLabel?: string;
+  /**
+   * What the pointer is told over the button.
+   * @default the chrome's own line, in the language of the page
+   */
+  buttonTitle?: string;
+  /**
+   * A plain bar entry, or a Blueprint button for a toolbar made of them.
+   * @default 'nav-link'
+   */
+  variant?: ShareButtonVariant;
+  /**
+   * Whether the dialog is open, for a page that has to know — to compute what
+   * the dialog shows only while it is. Pass it with `onOpenChange`.
+   * @default undefined — the control keeps the state itself
+   */
+  open?: boolean;
+  /**
+   * Called when the dialog opens or closes.
+   * @default undefined
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * Called as the button is pressed, before the dialog opens — to write the
+   * page's state into the address the link is read from.
+   * @default undefined
+   */
+  onOpen?: () => void;
+}
+
+/**
+ * The Share entry of a header and the dialog it opens: the page handed out as a
+ * link, or as the iframe that frames it in somebody else's site.
+ *
+ * It is what a header's `share` prop takes, so the entry lands after Contact on
+ * every site. Everything the dialog can be told is passed straight through; the
+ * control adds the open state, and the frame's name read off the site.
+ * @param props - The dialog's props, and how the button is dressed.
+ * @returns The button, and the dialog while it is open.
+ */
+export function ShareControl<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(props: ShareControlProps<Codecs>): ReactElement {
+  const {
+    siteId,
+    frameTitle,
+    search,
+    compact = false,
+    buttonLabel,
+    buttonTitle,
+    variant,
+    open,
+    onOpenChange,
+    onOpen,
+    title,
+    ...dialog
+  } = props;
+  const t = useChromeT();
+  const [ownOpen, setOwnOpen] = useState(false);
+  const isOpen = open ?? ownOpen;
+
+  function setOpen(next: boolean): void {
+    if (open === undefined) setOwnOpen(next);
+    onOpenChange?.(next);
+  }
+
+  const host = siteId === undefined ? undefined : siteById(siteId).host;
+  const named =
+    frameTitle ??
+    (host === undefined ? title : t('share.frameTitle', { site: host, title }));
+
+  return (
+    <>
+      <ShareButton
+        compact={compact}
+        label={buttonLabel}
+        title={buttonTitle}
+        variant={variant}
+        onClick={() => {
+          onOpen?.();
+          setOpen(true);
+        }}
+      />
+      <ShareDialog<Codecs>
+        {...dialog}
+        title={title}
+        frameTitle={named}
+        search={
+          isOpen && typeof search === 'function' ? search() : searchText(search)
+        }
+        isOpen={isOpen}
+        onClose={() => {
+          setOpen(false);
+        }}
+      />
+    </>
+  );
+}
+
+function searchText(
+  search: string | (() => string | undefined) | undefined,
+): string | undefined {
+  return typeof search === 'string' ? search : undefined;
+}

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