react-cheminfo 0.2.0 → 0.4.0

package/src/share/core/vocabulary.ts

@@ -0,0 +1,60 @@
+import type { ShareParamCodec } from './params.ts';
+
+/**
+ * A part of a page a shared link can switch off through `?hide=`.
+ *
+ * The label is written positively — the dialog shows a ticked box for a part
+ * that stays visible — and the description says what switching it off does,
+ * for the person building the link rather than for the visitor.
+ */
+export interface HideablePart {
+  /** The name this part takes in `?hide=`, in lowerCamelCase. */
+  key: string;
+  /** How the part is named in the dialog. */
+  label: string;
+  /** What hiding it does. */
+  description: string;
+  /**
+   * Whether the dialog starts with this part already switched off, because it
+   * is noise inside somebody else's page.
+   * @default false
+   */
+  hiddenByDefault?: boolean;
+}
+
+/**
+ * The codecs of a tool's own parameters, keyed by the name each takes in the
+ * query string.
+ */
+export type ShareParamCodecs = Readonly<
+  Record<string, ShareParamCodec<unknown>>
+>;
+
+/** The value each codec of a set reads and writes. */
+export type ShareParamValues<Codecs extends ShareParamCodecs> = {
+  [Key in keyof Codecs]: Codecs[Key] extends ShareParamCodec<infer Value>
+    ? Value
+    : never;
+};
+
+/**
+ * Everything one site's links can say: the parts they can switch off, and the
+ * typed parameters they carry beyond `embed` and `hide`.
+ *
+ * This is the only place that knows those names. A key it does not list is a
+ * tool input, left alone by every function here.
+ */
+export interface ShareVocabulary<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /**
+   * The hideable parts, in the order `?hide=` and the dialog list them, so one
+   * selection always produces one link.
+   */
+  parts: readonly HideablePart[];
+  /**
+   * The tool's own parameters — a series length, a zoom, a seed.
+   * @default {}
+   */
+  params?: Codecs;
+}

package/src/share/ui/HiddenPartsProvider.tsx

@@ -0,0 +1,34 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useMemo } from 'react';
+
+import { HiddenPartsContext } from './hiddenParts.ts';
+
+export interface HiddenPartsProviderProps {
+  /**
+   * The parts the link switches off — the `hidden` of the parsed
+   * configuration.
+   * @default [] — nothing is switched off
+   */
+  hidden?: readonly string[];
+  /** The page, and everything in it that may ask what is hidden. */
+  children: ReactNode;
+}
+
+/**
+ * Put the configuration of the current link where every part of the page can
+ * read it, so nothing has to be threaded through props.
+ * @param props - The parts the link switches off, and the page.
+ * @returns The page, under the configuration.
+ */
+export function HiddenPartsProvider(
+  props: HiddenPartsProviderProps,
+): ReactElement {
+  const { hidden, children } = props;
+  const parts = useMemo(() => new Set(hidden), [hidden]);
+
+  return (
+    <HiddenPartsContext.Provider value={parts}>
+      {children}
+    </HiddenPartsContext.Provider>
+  );
+}

package/src/share/ui/PagePart.tsx

@@ -0,0 +1,26 @@
+import type { ReactNode } from 'react';
+
+import { useIsHidden } from './hiddenParts.ts';
+
+export interface PagePartProps {
+  /** The name this region takes in `?hide=`. */
+  part: string;
+  /** What the region draws. */
+  children: ReactNode;
+}
+
+/**
+ * A region of the page a shared link may leave out.
+ *
+ * A switched-off part is dropped from the tree rather than hidden with CSS: an
+ * embedded figure must not mount a 3D canvas, or run a search, for a panel
+ * nobody will see.
+ * @param props - Which region this is, and what it draws.
+ * @returns The children, or nothing.
+ */
+export function PagePart(props: PagePartProps): ReactNode {
+  const { part, children } = props;
+  const isHidden = useIsHidden();
+
+  return isHidden(part) ? null : children;
+}

package/src/share/ui/ShareButton.tsx

@@ -0,0 +1,84 @@
+import { Button, Icon } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+const SHARE_TITLE = 'Share a link to this page, or embed it in your own site';
+
+/** How the button is dressed for the bar it sits in. */
+export type ShareButtonVariant = 'nav-link' | 'blueprint';
+
+export interface ShareButtonProps {
+  /** Called when the button is pressed; what it opens is the caller's business. */
+  onClick: () => void;
+  /**
+   * A plain entry of a site's own header bar, or a Blueprint button for a
+   * toolbar already made of them.
+   * @default 'nav-link'
+   */
+  variant?: ShareButtonVariant;
+  /**
+   * Text of the button, and what a screen reader is told.
+   * @default 'Share'
+   */
+  label?: string;
+  /**
+   * Whether the button is reduced to its icon, for a bar that has run out of
+   * room. It is still named to the pointer and to a screen reader.
+   * @default false
+   */
+  compact?: boolean;
+  /**
+   * What the pointer is told.
+   * @default 'Share a link to this page, or embed it in your own site'
+   */
+  title?: string;
+  /**
+   * Class the button carries, on top of the one its variant gives it.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The Share entry of a site header: the button that offers the open page as a
+ * link, or as the iframe that frames it in someone else's site.
+ * @param props - What the button does, how it is dressed, and how it is named.
+ * @returns The button.
+ */
+export function ShareButton(props: ShareButtonProps): ReactElement {
+  const {
+    onClick,
+    variant = 'nav-link',
+    label = 'Share',
+    compact = false,
+    title = SHARE_TITLE,
+    className,
+  } = props;
+  const text = compact ? undefined : label;
+
+  if (variant === 'blueprint') {
+    return (
+      <Button
+        className={className}
+        variant="minimal"
+        icon="share"
+        text={text}
+        title={title}
+        aria-label={label}
+        onClick={onClick}
+      />
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      className={className === undefined ? 'nav-link' : `nav-link ${className}`}
+      title={title}
+      aria-label={label}
+      onClick={onClick}
+    >
+      <Icon icon="share" size={14} />
+      {text}
+    </button>
+  );
+}

package/src/share/ui/ShareDialog.tsx

@@ -0,0 +1,114 @@
+import { Dialog } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type {
+  ShareConfig,
+  ShareParamCodecs,
+  ShareParamValues,
+  ShareVocabulary,
+} from '../core/index.ts';
+
+import { ShareDialogContent } from './ShareDialogContent.tsx';
+
+const DIALOG_STYLE: CSSProperties = { width: 'min(680px, 94vw)' };
+
+/**
+ * The configuration the dialog is holding, handed to a tool-specific section so
+ * it can read it and change it.
+ */
+export interface ShareDraft<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /** What the link would say if it were handed out now. */
+  config: ShareConfig<Codecs>;
+  /** Frame the page, or give it its chrome back. */
+  setEmbed: (embed: boolean) => void;
+  /** Switch one part of the page off, or on again. */
+  setPartHidden: (part: string, hidden: boolean) => void;
+  /** Give one of the tool's own parameters a new value. */
+  setParam: <Key extends keyof ShareParamValues<Codecs>>(
+    key: Key,
+    value: ShareParamValues<Codecs>[Key],
+  ) => void;
+}
+
+export interface ShareDialogProps<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> {
+  /** Whether the dialog is on screen. */
+  isOpen: boolean;
+  /** Called when the dialog is dismissed. */
+  onClose: () => void;
+  /** What this site's links can say: the hideable parts, and the tool's own parameters. */
+  vocabulary: ShareVocabulary<Codecs>;
+  /** How the open page is named in the dialog, and in the frame. */
+  title: string;
+  /**
+   * Where the page is served from — origin and path. Anything from the first
+   * `?` or `#` is dropped, so an address can be handed over as it is.
+   * @default the address of the page
+   */
+  baseUrl?: string;
+  /**
+   * The address as it stands, so the tool's own inputs travel with the link and
+   * a page already running a configuration opens on that one.
+   * @default the query string of the page
+   */
+  search?: string;
+  /**
+   * What a screen reader announces the frame as. A frame in someone else's page
+   * is usually named after the site as well as the page.
+   * @default the title
+   */
+  frameTitle?: string;
+  /**
+   * Height of the frame, in pixels.
+   * @default 700
+   */
+  frameHeight?: number;
+  /**
+   * Whether the dialog is rendered through a portal on `document.body`.
+   * @default true
+   */
+  usePortal?: boolean;
+  /**
+   * An extra section for what only this tool can configure — a series length, a
+   * difficulty, a seed. A function is handed the draft, so such a section can
+   * write the tool's own parameters into the link.
+   * @default undefined — the dialog shows the sections every site shares
+   */
+  children?: ReactNode | ((draft: ShareDraft<Codecs>) => ReactNode);
+}
+
+/**
+ * Hand the open page out as a link, or as the iframe that frames it in someone
+ * else's site.
+ *
+ * The dialog opens on the link one actually hands out: framed, and with the
+ * parts a host page has no use for already switched off. A page that is itself
+ * running a configuration shows that one instead.
+ * @param props - Whether the dialog is open, what the site's links can say, and how the page is named.
+ * @returns The dialog.
+ */
+export function ShareDialog<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(props: ShareDialogProps<Codecs>): ReactElement {
+  const { isOpen, onClose, usePortal = true, ...rest } = props;
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onClose={onClose}
+      usePortal={usePortal}
+      title="Share or embed"
+      icon="share"
+      className="share-dialog"
+      style={DIALOG_STYLE}
+    >
+      {/* The draft is mounted with the body, so a dialog a page leaves mounted
+          still opens on the link it would hand out rather than on whatever was
+          left in it. */}
+      {isOpen ? <ShareDialogContent {...rest} onClose={onClose} /> : null}
+    </Dialog>
+  );
+}

package/src/share/ui/ShareDialogContent.tsx

@@ -0,0 +1,189 @@
+import {
+  AnchorButton,
+  Button,
+  Checkbox,
+  DialogBody,
+  DialogFooter,
+  H6,
+} from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useState } from 'react';
+
+import { CodeBlock, CopyButton } from '../../clipboard/ui/index.ts';
+import type {
+  ShareConfig,
+  ShareParamCodecs,
+  ShareParamValues,
+  ShareVocabulary,
+} from '../core/index.ts';
+import {
+  buildEmbedCode,
+  buildShareUrl,
+  isShareConfigured,
+  parseShareConfig,
+  suggestedShareConfig,
+} from '../core/index.ts';
+
+import type { ShareDialogProps, ShareDraft } from './ShareDialog.tsx';
+import { SharePartOptions } from './SharePartOptions.tsx';
+import { withPart } from './draft.ts';
+
+const LEAD_STYLE: CSSProperties = { marginTop: 0, color: '#5b6875' };
+const SECTION_STYLE: CSSProperties = { marginBottom: 18 };
+const ACTIONS_STYLE: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 8,
+  marginTop: 8,
+};
+const HINT_STYLE: CSSProperties = {
+  display: 'block',
+  marginLeft: 26,
+  color: '#5b6875',
+  fontSize: 12,
+};
+
+/** Everything the dialog holds, minus what only its shell is concerned with. */
+export type ShareDialogContentProps<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+> = Omit<ShareDialogProps<Codecs>, 'isOpen' | 'usePortal'>;
+
+/**
+ * The sections of the share dialog: what the link says, what it hands out, and
+ * the markup that frames it.
+ * @param props - What the site's links can say, how the page is named, and the extra section.
+ * @returns The body and the footer of the dialog.
+ */
+export function ShareDialogContent<
+  Codecs extends ShareParamCodecs = Record<string, never>,
+>(props: ShareDialogContentProps<Codecs>): ReactElement {
+  const {
+    onClose,
+    vocabulary,
+    title,
+    baseUrl,
+    search,
+    frameTitle,
+    frameHeight,
+    children,
+  } = props;
+
+  const address = globalThis.location;
+  const base = baseUrl ?? address?.href ?? '';
+  const query = search ?? address?.search ?? '';
+  const [config, setConfig] = useState<ShareConfig<Codecs>>(() =>
+    initialDraft(query, vocabulary),
+  );
+
+  function setEmbed(embed: boolean): void {
+    setConfig((previous) => ({ ...previous, embed }));
+  }
+
+  function setPartHidden(part: string, hidden: boolean): void {
+    setConfig((previous) => ({
+      ...previous,
+      hidden: withPart(previous.hidden, part, hidden),
+    }));
+  }
+
+  function setParam<Key extends keyof ShareParamValues<Codecs>>(
+    key: Key,
+    value: ShareParamValues<Codecs>[Key],
+  ): void {
+    setConfig((previous) => ({
+      ...previous,
+      params: { ...previous.params, [key]: value },
+    }));
+  }
+
+  const draft: ShareDraft<Codecs> = {
+    config,
+    setEmbed,
+    setPartHidden,
+    setParam,
+  };
+  const url = buildShareUrl({ base, search: query, config, vocabulary });
+  const frame = buildEmbedCode({
+    url,
+    title: frameTitle ?? title,
+    height: frameHeight,
+  });
+
+  return (
+    <>
+      <DialogBody>
+        <p style={LEAD_STYLE}>
+          A link to <b>{title}</b> as you have it set up now.
+        </p>
+
+        <section className="share-section" style={SECTION_STYLE}>
+          <H6>Layout</H6>
+          <Checkbox
+            checked={config.embed}
+            label="Embed in another page"
+            onChange={(event) => {
+              setEmbed(event.currentTarget.checked);
+            }}
+          />
+          <span style={HINT_STYLE}>
+            Drops the site header and its navigation, so the page sits inside a
+            page of your own.
+          </span>
+        </section>
+
+        {vocabulary.parts.length > 0 ? (
+          <section className="share-section" style={SECTION_STYLE}>
+            <H6>Show on the page</H6>
+            <SharePartOptions
+              parts={vocabulary.parts}
+              hidden={config.hidden}
+              onChange={setPartHidden}
+            />
+          </section>
+        ) : null}
+
+        {children === undefined ? null : (
+          <section className="share-section" style={SECTION_STYLE}>
+            {typeof children === 'function' ? children(draft) : children}
+          </section>
+        )}
+
+        <section className="share-section" style={SECTION_STYLE}>
+          <H6>Link</H6>
+          <CodeBlock code={url} tone="muted" />
+          <div style={ACTIONS_STYLE}>
+            <CopyButton content={url} label="Copy the link" />
+            <AnchorButton
+              icon="share"
+              text="Open in a new tab"
+              href={url}
+              target="_blank"
+              rel="noopener noreferrer"
+            />
+          </div>
+        </section>
+
+        <section className="share-section" style={SECTION_STYLE}>
+          <H6>Iframe</H6>
+          <CodeBlock code={frame} tone="muted" />
+          <div style={ACTIONS_STYLE}>
+            <CopyButton content={frame} label="Copy the iframe" />
+          </div>
+        </section>
+      </DialogBody>
+      <DialogFooter
+        actions={<Button intent="primary" text="Done" onClick={onClose} />}
+      />
+    </>
+  );
+}
+
+function initialDraft<Codecs extends ShareParamCodecs>(
+  search: string,
+  vocabulary: ShareVocabulary<Codecs>,
+): ShareConfig<Codecs> {
+  const current = parseShareConfig(search, vocabulary);
+  return isShareConfigured(current, vocabulary)
+    ? current
+    : suggestedShareConfig(vocabulary);
+}

package/src/share/ui/SharePartOptions.tsx

@@ -0,0 +1,51 @@
+import { Checkbox } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { HideablePart } from '../core/index.ts';
+
+const OPTION_STYLE: CSSProperties = { marginBottom: 8 };
+
+const DESCRIPTION_STYLE: CSSProperties = {
+  display: 'block',
+  marginLeft: 26,
+  color: '#5b6875',
+  fontSize: 12,
+};
+
+export interface SharePartOptionsProps {
+  /** The parts this page can switch off, in the order the vocabulary lists them. */
+  parts: readonly HideablePart[];
+  /** The parts the draft currently switches off. */
+  hidden: readonly string[];
+  /** Called with the part and whether the link should switch it off. */
+  onChange: (part: string, hidden: boolean) => void;
+}
+
+/**
+ * One box per part of the page, worded positively: a ticked box is a part the
+ * link keeps, which is how somebody building a course tile thinks about it.
+ * @param props - The parts, what is switched off, and how to change it.
+ * @returns The list of boxes.
+ */
+export function SharePartOptions(props: SharePartOptionsProps): ReactElement {
+  const { parts, hidden, onChange } = props;
+
+  return (
+    <>
+      {parts.map((part) => (
+        <div key={part.key} style={OPTION_STYLE} className="share-part">
+          <Checkbox
+            checked={!hidden.includes(part.key)}
+            label={part.label}
+            onChange={(event) => {
+              onChange(part.key, !event.currentTarget.checked);
+            }}
+          />
+          <span style={DESCRIPTION_STYLE} className="share-part-description">
+            {part.description}
+          </span>
+        </div>
+      ))}
+    </>
+  );
+}

package/src/share/ui/draft.ts

@@ -0,0 +1,19 @@
+/**
+ * Switch one part of the page off, or on again, in the draft the dialog holds.
+ *
+ * A part is named once however many times it is ticked, and the order the
+ * vocabulary gives is restored when the link is written, so two people who
+ * ticked the same boxes hand out the same link.
+ * @param hidden - The parts the draft switches off.
+ * @param part - The part being ticked.
+ * @param off - Whether the link should switch it off.
+ * @returns The parts the draft switches off after the change.
+ */
+export function withPart(
+  hidden: readonly string[],
+  part: string,
+  off: boolean,
+): readonly string[] {
+  const rest = hidden.filter((entry) => entry !== part);
+  return off ? [...rest, part] : rest;
+}

package/src/share/ui/hiddenParts.ts

@@ -0,0 +1,22 @@
+import { createContext, useCallback, useContext } from 'react';
+
+/**
+ * The parts the link switched off, so a component that can be left out of an
+ * embedded page reads the configuration instead of taking it as a prop.
+ *
+ * A page with no provider above it hides nothing, which is what a site that
+ * hands out no links wants.
+ */
+export const HiddenPartsContext = createContext<ReadonlySet<string>>(new Set());
+
+/**
+ * Ask whether the link the page was opened with switches a part off.
+ *
+ * Hidden means hidden, not disabled: the value a hidden control carries still
+ * applies, so an embedder can preset what a visitor may not change.
+ * @returns A predicate over the part keys of the site's vocabulary.
+ */
+export function useIsHidden(): (part: string) => boolean {
+  const hidden = useContext(HiddenPartsContext);
+  return useCallback((part: string) => hidden.has(part), [hidden]);
+}

package/src/share/ui/index.ts

@@ -0,0 +1,9 @@
+export type { HiddenPartsProviderProps } from './HiddenPartsProvider.tsx';
+export { HiddenPartsProvider } from './HiddenPartsProvider.tsx';
+export { useIsHidden } from './hiddenParts.ts';
+export type { PagePartProps } from './PagePart.tsx';
+export { PagePart } from './PagePart.tsx';
+export type { ShareButtonProps, ShareButtonVariant } from './ShareButton.tsx';
+export { ShareButton } from './ShareButton.tsx';
+export type { ShareDialogProps } from './ShareDialog.tsx';
+export { ShareDialog } from './ShareDialog.tsx';

package/src/shared/ui/index.ts

@@ -1 +1,2 @@
-export type { HeaderButtonProps } from './MenuButton.tsx';
+export type { HeaderButtonProps, MenuButtonProps } from './MenuButton.tsx';
+export { MenuButton } from './MenuButton.tsx';

package/src/state/ui/index.ts

@@ -0,0 +1,6 @@
+export type {
+  BucketRead,
+  PersistBucketOptions,
+  PersistedBucket,
+} from './persistBucket.ts';
+export { persistBucket } from './persistBucket.ts';