react-cheminfo 0.38.0 → 0.39.0

package/src/chart/ui/Axes.tsx

@@ -78,6 +78,25 @@ export interface AxesProps {
    * @default 44
    */
   yTickSpacing?: number;
+  /**
+   * The values to rule the vertical axis at, instead of the ones the room
+   * allows.
+   *
+   * An axis whose ticks are decided by what is being measured rather than by
+   * how much space there is: a concentration read over fifteen decades is ruled
+   * at the decades, and a tick at 0.0037 between two of them says nothing. The
+   * values outside the window are dropped, so one list serves every zoom.
+   * @default the ticks worked out from the window and the room
+   */
+  yTickValues?: readonly number[];
+  /**
+   * How a value up the side is written, instead of as a plain number.
+   *
+   * What goes with `yTickValues`: an axis ruled at the decades writes `10⁻³`,
+   * and the exponent is the only part of it a reader is reading.
+   * @default the notation the window's step calls for
+   */
+  formatYTick?: (value: number) => string;
 }
 
 /**
@@ -123,6 +142,8 @@ export function Axes(props: AxesProps): ReactElement {
     yTitle,
     xTickSpacing = X_TICK_SPACING,
     yTickSpacing = Y_TICK_SPACING,
+    yTickValues,
+    formatYTick,
   } = props;
 
   const xTicks = useMemo(
@@ -134,7 +155,15 @@ export function Axes(props: AxesProps): ReactElement {
     [yDomain, plot.height, yTickSpacing],
   );
   const writeXTick = useMemo(() => axisLabeller(xTicks), [xTicks]);
-  const writeYTick = useMemo(() => axisLabeller(yTicks), [yTicks]);
+  const labelYTick = useMemo(() => axisLabeller(yTicks), [yTicks]);
+  const writeYTick = formatYTick ?? labelYTick;
+
+  // Ruled where the quantity asks rather than where there is room; a value the
+  // zoom has left behind is dropped rather than drawn onto the margin.
+  const yRules = useMemo(
+    () => (yTickValues ? insideWindow(yTickValues, yDomain) : yTicks.values),
+    [yTickValues, yDomain, yTicks],
+  );
 
   const middleX = plot.left + plot.width / 2;
   const middleY = plot.top + plot.height / 2;
@@ -144,8 +173,8 @@ export function Axes(props: AxesProps): ReactElement {
   // clear of the narrower — far enough to read as naming the chart rather than
   // the axis.
   const titleColumn = useMemo(
-    () => valueTitleColumn(yTicks.values, writeYTick, absYTicks, plot.left),
-    [yTicks, writeYTick, absYTicks, plot.left],
+    () => valueTitleColumn(yRules, writeYTick, absYTicks, plot.left),
+    [yRules, writeYTick, absYTicks, plot.left],
   );
   // The rule a mirrored pair is reflected in only exists while both halves are
   // on screen; on an ordinary chart zero is the baseline and already drawn.
@@ -164,7 +193,7 @@ export function Axes(props: AxesProps): ReactElement {
           style={gridStyle}
         />
       ))}
-      {yTicks.values.map((tick) => (
+      {yRules.map((tick) => (
         <line
           key={tick}
           x1={plot.left}
@@ -201,7 +230,7 @@ export function Axes(props: AxesProps): ReactElement {
             {writeXTick(tick)}
           </text>
         ))}
-      {yTicks.values.map((tick) => (
+      {yRules.map((tick) => (
         <text
           key={tick}
           x={plot.left - TICK_LABEL_GAP}
@@ -238,6 +267,25 @@ export function Axes(props: AxesProps): ReactElement {
   );
 }
 
+/**
+ * The values of a given list that the window still shows.
+ * @param values - Every value the axis would be ruled at.
+ * @param domain - The window on screen, `[from, to]`.
+ * @returns Those inside it, in the order they were given.
+ */
+function insideWindow(
+  values: readonly number[],
+  domain: readonly [number, number],
+): number[] {
+  const low = Math.min(domain[0], domain[1]);
+  const high = Math.max(domain[0], domain[1]);
+  const inside: number[] = [];
+  for (const value of values) {
+    if (value >= low && value <= high) inside.push(value);
+  }
+  return inside;
+}
+
 /**
  * The ticks of one axis of a chart a reader has zoomed for themselves.
  *

package/src/chrome/ui/NavMenuButton.tsx

@@ -58,7 +58,7 @@ export function NavMenuButton(props: NavMenuButtonProps): ReactElement {
     children,
   } = props;
 
-  const holdsActive = items.some((item) => item.id === activeId);
+  const holdsActive = holdsId(items, activeId);
   const classes = [
     'nav-link',
     icon === undefined ? null : 'nav-link--icon',
@@ -73,23 +73,7 @@ export function NavMenuButton(props: NavMenuButtonProps): ReactElement {
       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();
-              }}
-            />
+            <NavMenuEntry key={item.id} item={item} activeId={activeId} />
           ))}
           {children}
         </Menu>
@@ -114,3 +98,62 @@ export function NavMenuButton(props: NavMenuButtonProps): ReactElement {
     </PopoverNext>
   );
 }
+
+/**
+ * One line of a header menu, holding a submenu of its own when the entry folds
+ * pages — which is how a bar entry that is already a menu reads once the whole
+ * bar has folded into one.
+ * @param props - The entry and the page on show.
+ * @param props.item - The entry.
+ * @param props.activeId - The page on show.
+ * @returns The line.
+ */
+function NavMenuEntry(props: {
+  item: NavItem;
+  activeId: string | undefined;
+}): ReactElement {
+  const { item, activeId } = props;
+
+  return (
+    <MenuItem
+      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.items === undefined
+          ? item.id === activeId
+          : holdsId(item.items, activeId)
+      }
+      onClick={(event) => {
+        if (item.onSelect === undefined || isModifiedClick(event)) return;
+        event.preventDefault();
+        item.onSelect();
+      }}
+    >
+      {item.items?.map((child) => (
+        <NavMenuEntry key={child.id} item={child} activeId={activeId} />
+      ))}
+    </MenuItem>
+  );
+}
+
+/**
+ * Whether a run of entries holds the page on show, looking through the ones
+ * that are menus of their own.
+ * @param items - The entries.
+ * @param activeId - The page on show.
+ * @returns Whether one of them is it.
+ */
+function holdsId(
+  items: readonly NavItem[],
+  activeId: string | undefined,
+): boolean {
+  for (const item of items) {
+    if (item.id === activeId) return true;
+    if (item.items !== undefined && holdsId(item.items, activeId)) return true;
+  }
+  return false;
+}

package/src/chrome/ui/SiteHeader.tsx

@@ -150,7 +150,7 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
           {nav.map((item) => (
             <Fragment key={item.id}>
               {renderNavItem === undefined ? (
-                <NavLink item={item} active={item.id === activeId} />
+                <NavEntry item={item} activeId={activeId} />
               ) : (
                 renderNavItem(item, item.id === activeId)
               )}
@@ -177,6 +177,42 @@ export function SiteHeader(props: SiteHeaderProps): ReactElement | null {
   );
 }
 
+/**
+ * One page of the bar: a link, or the menu it opens when the entry folds pages
+ * of its own. A menu stands where its pages would, among them and not among the
+ * utilities, because picking one of them changes what the page shows.
+ * @param props - The entry and the page on show.
+ * @param props.item - The entry.
+ * @param props.activeId - The page on show.
+ * @returns The entry.
+ */
+function NavEntry(props: {
+  item: NavItem;
+  activeId: string | undefined;
+}): ReactElement {
+  const { item, activeId } = props;
+  if (item.items === undefined) {
+    return <NavLink item={item} active={item.id === activeId} />;
+  }
+
+  return (
+    <NavMenuButton
+      label={menuLabel(item)}
+      icon={typeof item.icon === 'string' ? item.icon : undefined}
+      items={item.items}
+      activeId={activeId}
+      placement="bottom-start"
+    />
+  );
+}
+
+// The trigger names itself to a screen reader, so an entry drawn as a glyph
+// alone says what it opens through its title rather than through its id.
+function menuLabel(item: NavItem): string {
+  if (typeof item.label === 'string') return item.label;
+  return item.title ?? item.id;
+}
+
 /** The two widths the bar's contents run at, as the classes that set them. */
 const INNER_CLASS = {
   page: 'app-header__inner',

package/src/chrome/ui/navItem.ts

@@ -49,6 +49,13 @@ export interface NavItem {
    * @default undefined
    */
   after?: ReactNode;
+  /**
+   * The pages this entry folds, which make it a menu rather than a link: the
+   * run of pages that do not each need a place of their own in the bar. The
+   * entry takes the brand tint while one of them is the page on show.
+   * @default undefined
+   */
+  items?: readonly NavItem[];
   /**
    * Whether the page cannot be opened yet — a view that needs data the site
    * has not been given.

package/src/citation/ui/entries.tsx

@@ -3,6 +3,7 @@ import { MenuItem, Tooltip } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { useActionTooltip } from '../../shared/ui/useActionTooltip.ts';
 import { downloadCitations } from '../core/download.ts';
 import type { CitationDownload, CitationFormat } from '../core/formats.ts';
 import type { Reference } from '../core/reference.ts';
@@ -131,11 +132,16 @@ function PreviewTooltip(props: {
   children: (targetProps: Record<string, unknown>) => ReactElement;
 }): ReactElement {
   const { references, format, style, children } = props;
+  // Held rather than left to Blueprint: pressing an entry downloads or copies
+  // and closes the menu, and a preview opened by the hover that led to the
+  // press would outlive both — see `useActionTooltip`.
+  const { isOpen, target } = useActionTooltip(false, PREVIEW_OPEN_DELAY);
+
   return (
     <Tooltip
       placement="left"
       popoverClassName="citation-tooltip"
-      hoverOpenDelay={PREVIEW_OPEN_DELAY}
+      isOpen={isOpen}
       content={
         <CitationPreview
           reference={references}
@@ -143,7 +149,9 @@ function PreviewTooltip(props: {
           style={style?.id}
         />
       }
-      renderTarget={({ isOpen, ...targetProps }) => children(targetProps)}
+      renderTarget={({ isOpen: drawn, ...targetProps }) =>
+        children({ ...targetProps, ...target })
+      }
     />
   );
 }

package/src/clipboard/ui/ClickToCopy.tsx

@@ -1,3 +1,4 @@
+import type { IconName } from '@blueprintjs/core';
 import { Icon } from '@blueprintjs/core';
 import type {
   CSSProperties,
@@ -20,6 +21,9 @@ import { useCopyToClipboard } from './useCopyToClipboard.ts';
 /** The elements a {@link ClickToCopy} can be, so a table cell is its own target. */
 export type ClickToCopyElement = 'span' | 'code' | 'div' | 'td' | 'th';
 
+/** Where the glyph sits: past the value, or inside its right edge. */
+export type ClickToCopyLayout = 'inline' | 'block';
+
 /** What {@link ClickToCopy} copies, and how it reads. */
 export interface ClickToCopyProps {
   /**
@@ -48,6 +52,15 @@ export interface ClickToCopyProps {
    * @default 'span'
    */
   as?: ClickToCopyElement;
+  /**
+   * Where the glyph goes. A value in a line of text shows it just past itself,
+   * so the line keeps its spacing; one laid out as a block keeps room for it
+   * inside its right edge, because a glyph past the edge of a full-width block
+   * is a glyph past the edge of whatever holds it — which scrolls the page
+   * sideways by the width of the glyph.
+   * @default read from `as`: a `span` or a `code` is inline, the rest a block
+   */
+  layout?: ClickToCopyLayout;
   /**
    * Whether the value is a tab stop and a button of its own, with the glyph a
    * keyboard is shown instead of the cursor. Off when a copy button beside it
@@ -108,6 +121,7 @@ export function ClickToCopy(props: ClickToCopyProps): ReactElement {
     label,
     title,
     as: Element = 'span',
+    layout,
     focusable = true,
     disabled = false,
     className,
@@ -116,6 +130,7 @@ export function ClickToCopy(props: ClickToCopyProps): ReactElement {
   } = props;
   const t = useChromeT();
   const { copied, failed, copy } = useCopyToClipboard();
+  const placing = layout ?? (INLINE.has(Element) ? 'inline' : 'block');
 
   if (disabled) {
     return (
@@ -141,7 +156,7 @@ export function ClickToCopy(props: ClickToCopyProps): ReactElement {
     <Element
       className={joinClassNames(
         'click-to-copy',
-        INLINE.has(Element) ? 'click-to-copy--inline' : 'click-to-copy--block',
+        `click-to-copy--${placing}`,
         className,
       )}
       style={style}
@@ -157,27 +172,46 @@ export function ClickToCopy(props: ClickToCopyProps): ReactElement {
       {focusable ? (
         <Icon
           className="click-to-copy__icon"
-          icon={
-            outcome === 'copied'
-              ? 'tick'
-              : outcome === 'failed'
-                ? 'cross'
-                : 'clipboard'
-          }
+          icon={outcomeIcon(outcome)}
           size={16}
         />
       ) : null}
       <span className="click-to-copy__status" role="status">
-        {outcome === 'copied'
-          ? t('clipboard.copied')
-          : outcome === 'failed'
-            ? t('clipboard.failed')
-            : null}
+        {outcomeStatus(outcome, t)}
       </span>
     </Element>
   );
 }
 
+/** How the last copy went, while it is still being confirmed. */
+type CopyOutcome = 'copied' | 'failed' | undefined;
+
+/**
+ * The glyph the value carries: the clipboard at rest, then the answer.
+ * @param outcome - How the last copy went.
+ * @returns The icon.
+ */
+function outcomeIcon(outcome: CopyOutcome): IconName {
+  if (outcome === 'copied') return 'tick';
+  if (outcome === 'failed') return 'cross';
+  return 'clipboard';
+}
+
+/**
+ * What a screen reader is told once a copy has been attempted.
+ * @param outcome - How it went.
+ * @param t - The chrome's formatter.
+ * @returns The line, or nothing before anything was copied.
+ */
+function outcomeStatus(
+  outcome: CopyOutcome,
+  t: Translate<ChromeKey>,
+): string | null {
+  if (outcome === 'copied') return t('clipboard.copied');
+  if (outcome === 'failed') return t('clipboard.failed');
+  return null;
+}
+
 function isOnNestedControl(
   event: MouseEvent<HTMLElement> | KeyboardEvent<HTMLElement>,
 ): boolean {

package/src/clipboard/ui/CopyButton.tsx

@@ -3,6 +3,7 @@ import { Button } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 
 import {
   DEFAULT_COPY_RESET_AFTER,
@@ -60,7 +61,8 @@ export interface CopyButtonProps {
    */
   resetAfter?: number;
   /**
-   * What the pointer and a screen reader are told.
+   * What the pointer and a screen reader are told. An empty string drops the
+   * hover title, for a button that already sits in a tooltip of its own.
    * @default the chrome's own line, in the language of the page
    */
   title?: string;
@@ -105,7 +107,7 @@ export function CopyButton(props: CopyButtonProps): ReactElement {
 
   return (
     <Button
-      className={className}
+      className={joinClassNames('no-print', className)}
       variant={minimal ? 'minimal' : 'solid'}
       size={small ? 'small' : 'medium'}
       icon={look.icon}

package/src/clipboard/ui/CopyableValue.tsx

@@ -1,12 +1,18 @@
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 
 import { MISSING_VALUE } from '../../format/core/missing.ts';
+import type { HelpText } from '../../help/ui/HelpBody.tsx';
+import { HelpTooltip } from '../../help/ui/HelpTooltip.tsx';
+import { OVERLAY_HELP_NAME_STYLE } from '../../overlay/ui/overlayRowStyles.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 
 import { ClickToCopy } from './ClickToCopy.tsx';
 
 const DEFAULT_BLOCK_HEIGHT = 160;
 
+/** What says there is more of the value than is on screen. */
+const FADE = 'linear-gradient(to bottom, #000 72%, transparent 100%)';
+
 /** What {@link CopyableValue} names, shows and copies. */
 export interface CopyableValueProps {
   /** What the value is, written above it, e.g. `InChIKey`. */
@@ -14,10 +20,13 @@ export interface CopyableValueProps {
   /** The value itself, which is what a click on it copies. */
   value: string;
   /**
-   * A longer explanation of the label, shown on hover.
-   * @default undefined — the label carries no hover text
+   * What the value is, read by hovering the label — which is underlined with
+   * dots to say so. It opens as the family's help card rather than as the
+   * browser's own tooltip, which takes a second to appear and is drawn by the
+   * operating system rather than by us.
+   * @default undefined — the label explains nothing beyond itself
    */
-  hint?: string;
+  hint?: HelpText;
   /**
    * Whether the value keeps its line breaks and scrolls past `maxHeight`, for
    * a molfile or any other multi-line notation.
@@ -25,16 +34,32 @@ export interface CopyableValueProps {
    */
   block?: boolean;
   /**
-   * Height past which a block value scrolls on its own.
+   * Height past which a block value scrolls on its own, or is cut off when it
+   * is clipped.
    * @default 160
    */
   maxHeight?: number | string;
+  /**
+   * Whether a block value is cut off at `maxHeight` and faded, rather than
+   * given scrollbars. A notation is copied rather than read, and a molfile is
+   * both long and wide, so a scrollbar on each axis of each of two of them is
+   * four bars of chrome buying nothing.
+   * @default false
+   */
+  clip?: boolean;
   /**
    * What the pointer and a screen reader are told, replacing the title built
    * from the label and the value.
    * @default undefined — `Copy the ${label} (${value})`
    */
   copyTitle?: string;
+  /**
+   * A control on the label's own line, pushed to the right — a save button for
+   * a notation that is also a file, a menu of the forms it comes in. It sits
+   * outside the value, so pressing it never copies.
+   * @default undefined
+   */
+  action?: ReactNode;
   /**
    * What goes under the value: the links an identifier leads to, a note on it.
    * @default undefined
@@ -66,12 +91,31 @@ export function CopyableValue(props: CopyableValueProps): ReactElement {
     hint,
     block = false,
     maxHeight = DEFAULT_BLOCK_HEIGHT,
+    clip = false,
     copyTitle,
+    action,
     children,
     className,
   } = props;
   const isEmpty = value === '';
 
+  const written = (
+    <span
+      className="copyable-value__label"
+      style={hint === undefined ? LABEL_STYLE : HINTED_LABEL_STYLE}
+    >
+      {label}
+    </span>
+  );
+  const name =
+    hint === undefined ? (
+      written
+    ) : (
+      <HelpTooltip content={{ body: hint }} placement="top-start">
+        {written}
+      </HelpTooltip>
+    );
+
   return (
     <div
       className={
@@ -80,21 +124,29 @@ export function CopyableValue(props: CopyableValueProps): ReactElement {
           : `copyable-value ${className}`
       }
     >
-      <span
-        className="copyable-value__label"
-        style={hint === undefined ? LABEL_STYLE : HINTED_LABEL_STYLE}
-        title={hint}
-      >
-        {label}
-      </span>
+      {action === undefined ? (
+        name
+      ) : (
+        <span className="copyable-value__header" style={HEADER_STYLE}>
+          {name}
+          {action}
+        </span>
+      )}
       <ClickToCopy
         as="code"
+        // The value fills the row, so the glyph goes inside its right edge: a
+        // `code` is an inline element but this one is laid out as a block.
+        layout="block"
         value={value}
         label={label}
         title={copyTitle}
         disabled={isEmpty}
         className="copyable-value__value"
-        style={block ? { ...BLOCK_VALUE_STYLE, maxHeight } : VALUE_STYLE}
+        style={
+          block
+            ? { ...(clip ? CLIPPED_VALUE_STYLE : BLOCK_VALUE_STYLE), maxHeight }
+            : VALUE_STYLE
+        }
       >
         {isEmpty ? MISSING_VALUE : value}
       </ClickToCopy>
@@ -110,9 +162,24 @@ const LABEL_STYLE = {
   fontWeight: 600,
 } as const satisfies CSSProperties;
 
+/**
+ * A label that explains itself is underlined with dots, which is the one
+ * convention that lets a `?` glyph leave the row — see `OverlayRow`, where the
+ * rest of the package already reads this way.
+ */
 const HINTED_LABEL_STYLE = {
   ...LABEL_STYLE,
-  cursor: 'help',
+  ...OVERLAY_HELP_NAME_STYLE,
+  display: 'inline',
+} as const satisfies CSSProperties;
+
+/** The label and its control, on one line with the control at the right. */
+const HEADER_STYLE = {
+  display: 'flex',
+  minHeight: 20,
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 8,
 } as const satisfies CSSProperties;
 
 const VALUE_STYLE = {
@@ -128,3 +195,11 @@ const BLOCK_VALUE_STYLE = {
   overflowWrap: 'normal',
   overflow: 'auto',
 } as const satisfies CSSProperties;
+
+/** The same block, cut off at its height and faded out rather than scrolled. */
+const CLIPPED_VALUE_STYLE = {
+  ...BLOCK_VALUE_STYLE,
+  overflow: 'hidden',
+  maskImage: FADE,
+  WebkitMaskImage: FADE,
+} as const satisfies CSSProperties;

package/src/clipboard/ui/index.ts

@@ -1,4 +1,8 @@
-export type { ClickToCopyElement, ClickToCopyProps } from './ClickToCopy.tsx';
+export type {
+  ClickToCopyElement,
+  ClickToCopyLayout,
+  ClickToCopyProps,
+} from './ClickToCopy.tsx';
 export { ClickToCopy } from './ClickToCopy.tsx';
 export type { CodeBlockProps, CodeBlockTone } from './CodeBlock.tsx';
 export { CodeBlock } from './CodeBlock.tsx';

package/src/confirm/ui/ConfirmButton.tsx

@@ -4,6 +4,7 @@ import type { ReactElement, ReactNode } from 'react';
 import { useState } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 
 /** Props of {@link ConfirmButton}: a Blueprint button, and what it asks. */
 export interface ConfirmButtonProps extends Omit<ButtonProps, 'onClick'> {
@@ -46,6 +47,7 @@ export function ConfirmButton(props: ConfirmButtonProps): ReactElement {
     <>
       <Button
         {...buttonProps}
+        className={joinClassNames('no-print', buttonProps.className)}
         onClick={() => {
           setAsking(true);
         }}

package/src/delimited/ui/TableDataButton.tsx

@@ -4,6 +4,7 @@ import type { ReactElement, ReactNode } from 'react';
 import { useState } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 
 import type { DelimitedTextDialogProps } from './DelimitedTextDialog.tsx';
 import { DelimitedTextDialog } from './DelimitedTextDialog.tsx';
@@ -139,7 +140,7 @@ export function TableDataButton(props: TableDataButtonProps): ReactElement {
         trigger(show)
       ) : (
         <Button
-          className={buttonClassName}
+          className={joinClassNames('no-print', buttonClassName)}
           icon={icon}
           text={text}
           variant={minimal ? 'minimal' : 'solid'}