react-cheminfo 0.10.0 → 0.12.0

package/src/format/core/relativeTime.ts

@@ -0,0 +1,80 @@
+import { MISSING_VALUE } from './missing.ts';
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+const UNITS: ReadonlyArray<{
+  unit: Intl.RelativeTimeFormatUnit;
+  milliseconds: number;
+}> = [
+  { unit: 'year', milliseconds: 365 * DAY },
+  { unit: 'month', milliseconds: 30 * DAY },
+  { unit: 'week', milliseconds: 7 * DAY },
+  { unit: 'day', milliseconds: DAY },
+  { unit: 'hour', milliseconds: HOUR },
+  { unit: 'minute', milliseconds: MINUTE },
+];
+
+const FORMATTER = new Intl.RelativeTimeFormat('en-US', { numeric: 'auto' });
+
+/** How {@link formatRelativeTime} measures and what it writes for nothing. */
+export interface FormatRelativeTimeOptions {
+  /**
+   * The instant the distance is measured from, in epoch milliseconds or as a
+   * date. Pass it when a list is drawn, so every row is measured against the
+   * same moment and a test gets the same words every time.
+   * @default Date.now()
+   */
+  now?: number | Date;
+  /**
+   * What is written when there is no instant, or it cannot be read.
+   * @default MISSING_VALUE
+   */
+  missing?: string;
+}
+
+/**
+ * How far an instant is from now, in words: `just now`, `5 minutes ago`,
+ * `yesterday`, `in 3 weeks`.
+ *
+ * The largest unit that fits is used and the count is rounded towards zero, so
+ * ninety minutes read `1 hour ago` rather than claiming two. Under a minute
+ * either way is `just now`, which also absorbs a clock that is a few seconds
+ * ahead. The locale is fixed to `en-US`, like every formatter of this module.
+ * @param instant - Epoch milliseconds, an ISO timestamp or a date.
+ * @param options - See {@link FormatRelativeTimeOptions}.
+ * @returns The phrase, or the missing text when the instant is absent or unreadable.
+ */
+export function formatRelativeTime(
+  instant: number | string | Date | undefined,
+  options: FormatRelativeTimeOptions = {},
+): string {
+  const { now = Date.now(), missing = MISSING_VALUE } = options;
+  const time = toTime(instant);
+  const reference = toTime(now);
+  if (time === undefined || reference === undefined) return missing;
+
+  const elapsed = time - reference;
+  const distance = Math.abs(elapsed);
+  for (const { unit, milliseconds } of UNITS) {
+    if (distance >= milliseconds) {
+      const count = Math.floor(distance / milliseconds);
+      return FORMATTER.format(elapsed < 0 ? -count : count, unit);
+    }
+  }
+  return 'just now';
+}
+
+function toTime(
+  instant: number | string | Date | undefined,
+): number | undefined {
+  if (instant === undefined || instant === '') return undefined;
+  const time =
+    typeof instant === 'number'
+      ? instant
+      : typeof instant === 'string'
+        ? Date.parse(instant)
+        : instant.getTime();
+  return Number.isFinite(time) ? time : undefined;
+}

package/src/format/core/roundTo.ts

@@ -0,0 +1,27 @@
+import { clamp } from './clamp.ts';
+
+const MAXIMUM_DECIMALS = 15;
+const DEFAULT_DECIMALS = 2;
+const POWERS_OF_TEN = [
+  1, 10, 100, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14,
+  1e15,
+] as const;
+
+/**
+ * A number rounded to a fixed count of decimals, and still a number.
+ *
+ * This is the rounding an SVG coordinate or a stored setting takes: `12.3456`
+ * becomes `12.35`, so a figure writes short attributes and two renders of the
+ * same data write the same markup. Use `formatTrimmed` when a string is wanted.
+ * @param value - The number to round.
+ * @param decimals - Decimals to keep, from 0 to 15. Defaults to `2`; a count that is not a finite number falls back to it.
+ * @returns The rounded number; a value that is not finite comes back unchanged.
+ */
+export function roundTo(value: number, decimals = DEFAULT_DECIMALS): number {
+  if (!Number.isFinite(value)) return value;
+  const index = Math.trunc(
+    clamp(decimals, 0, MAXIMUM_DECIMALS, DEFAULT_DECIMALS),
+  );
+  const factor = POWERS_OF_TEN[index] ?? 1;
+  return Math.round(value * factor) / factor;
+}

package/src/format/core/superscript.ts

@@ -0,0 +1,22 @@
+const SUPERSCRIPT_DIGITS = '⁰¹²³⁴⁵⁶⁷⁸⁹';
+const SUPERSCRIPT_MINUS = '⁻';
+
+/**
+ * A whole number written in Unicode superscript characters: `14` becomes `¹⁴`,
+ * `-3` becomes `⁻³`.
+ *
+ * It is how an exponent, a charge or a subshell occupancy is written inside a
+ * plain string — an axis title, an `<option>`, a copied value — where no
+ * `<sup>` element can go.
+ * @param value - The number to write; anything after the decimal point is dropped.
+ * @returns The superscript digits with their sign, or an empty string when the value is not finite.
+ */
+export function formatSuperscript(value: number): string {
+  if (!Number.isFinite(value)) return '';
+  const whole = Math.trunc(value);
+  let text = whole < 0 ? SUPERSCRIPT_MINUS : '';
+  for (const digit of Math.abs(whole).toString()) {
+    text += SUPERSCRIPT_DIGITS.charAt(Number(digit));
+  }
+  return text;
+}

package/src/format/core/units.ts

@@ -2,9 +2,39 @@ import { MISSING_VALUE } from './missing.ts';
 
 const BYTE_UNITS = ['B', 'kB', 'MB', 'GB', 'TB', 'PB'] as const;
 const BYTES_PER_UNIT = 1024;
+const MILLISECONDS_PER_SECOND = 1000;
+const TENTHS_PER_MINUTE = 600;
 const SECONDS_PER_MINUTE = 60;
 const MINUTES_PER_HOUR = 60;
 
+/** How a duration is spelled. */
+export type DurationStyle = 'compact' | 'spaced';
+
+const UNIT_NAMES: Record<
+  DurationStyle,
+  { millisecond: string; second: string; minute: string; hour: string }
+> = {
+  compact: { millisecond: 'ms', second: 's', minute: 'm', hour: 'h' },
+  spaced: { millisecond: ' ms', second: ' s', minute: ' min', hour: ' h' },
+};
+
+/** How {@link formatDuration} writes a duration. */
+export interface FormatDurationOptions {
+  /**
+   * `compact` glues each unit to its number (`3m 20s`), for a table cell;
+   * `spaced` writes the units out (`3 min 20 s`), for a sentence.
+   * @default 'compact'
+   */
+  style?: DurationStyle;
+  /**
+   * Whether a short duration keeps its fraction of a second: under a second it
+   * is written in milliseconds (`450 ms`), and under a minute with one decimal
+   * (`2.3 s`). Without it, both round to whole seconds.
+   * @default false
+   */
+  subSecond?: boolean;
+}
+
 /**
  * A byte count in the largest unit that keeps it under a thousand: `512 B`,
  * `1.5 kB`, `240 MB`.
@@ -29,11 +59,16 @@ export function formatBytes(bytes: number | undefined): string {
 }
 
 /**
- * A duration written with its two largest units: `45s`, `3m 20s`, `2h 05m`.
+ * A duration written with its two largest units: `45s`, `3m 20s`, `2h 05m`,
+ * or `45 s`, `3 min 20 s`, `2 h 05 min` in the spaced style.
  * @param milliseconds - The duration in milliseconds.
+ * @param options - See {@link FormatDurationOptions}.
  * @returns The duration, or the missing marker when there is no finite, non-negative duration.
  */
-export function formatDuration(milliseconds: number | undefined): string {
+export function formatDuration(
+  milliseconds: number | undefined,
+  options: FormatDurationOptions = {},
+): string {
   if (
     milliseconds === undefined ||
     !Number.isFinite(milliseconds) ||
@@ -41,18 +76,30 @@ export function formatDuration(milliseconds: number | undefined): string {
   ) {
     return MISSING_VALUE;
   }
-  const seconds = Math.round(milliseconds / 1000);
-  if (seconds < SECONDS_PER_MINUTE) return `${seconds}s`;
+  const { style = 'compact', subSecond = false } = options;
+  const names = UNIT_NAMES[style];
+
+  if (subSecond) {
+    const whole = Math.round(milliseconds);
+    if (whole < MILLISECONDS_PER_SECOND) return `${whole}${names.millisecond}`;
+    const tenths = Math.round(milliseconds / 100);
+    if (tenths < TENTHS_PER_MINUTE) {
+      return `${(tenths / 10).toFixed(1)}${names.second}`;
+    }
+  }
+
+  const seconds = Math.round(milliseconds / MILLISECONDS_PER_SECOND);
+  if (seconds < SECONDS_PER_MINUTE) return `${seconds}${names.second}`;
 
   const minutes = Math.floor(seconds / SECONDS_PER_MINUTE);
   const remainingSeconds = seconds % SECONDS_PER_MINUTE;
   if (minutes < MINUTES_PER_HOUR) {
-    return `${minutes}m ${pad(remainingSeconds)}s`;
+    return `${minutes}${names.minute} ${pad(remainingSeconds)}${names.second}`;
   }
 
   const hours = Math.floor(minutes / MINUTES_PER_HOUR);
   const remainingMinutes = minutes % MINUTES_PER_HOUR;
-  return `${hours}h ${pad(remainingMinutes)}m`;
+  return `${hours}${names.hour} ${pad(remainingMinutes)}${names.minute}`;
 }
 
 function pad(value: number): string {

package/src/help/ui/HelpBody.tsx

@@ -1,5 +1,7 @@
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+
 /** A worked example under a piece of help: the construct, and what it does. */
 export interface HelpExample {
   /** The construct itself, shown in monospace. */
@@ -19,16 +21,22 @@ export interface HelpExample {
 
 /** Everything a piece of help says, wherever it is shown. */
 export interface HelpContent {
-  /** First line, in bold: what the thing is, not what its label already says. */
-  title: string;
-  /** The explanation, one or two sentences. */
-  body: ReactNode;
   /**
-   * A concrete case, because a definition without one is what makes a reader
-   * give up.
+   * First line, in bold: what the thing is, not what its label already says.
+   * @default undefined — the body stands on its own, as a plain tooltip does
+   */
+  title?: string;
+  /**
+   * The explanation: one or two sentences, or any content of the site's own.
    * @default undefined
    */
-  example?: HelpExample;
+  body?: ReactNode;
+  /**
+   * A concrete case, or several read in order, because a definition without
+   * one is what makes a reader give up.
+   * @default undefined
+   */
+  example?: HelpExample | readonly HelpExample[];
   /**
    * Where the full documentation lives, offered as a "Learn more" link.
    * @default undefined
@@ -46,6 +54,11 @@ export interface HelpBodyProps {
    * @default 280
    */
   width?: number;
+  /**
+   * Class names added to the root element, after the component's own.
+   * @default undefined
+   */
+  className?: string;
 }
 
 /**
@@ -58,26 +71,29 @@ export interface HelpBodyProps {
  * @returns The help body.
  */
 export function HelpBody(props: HelpBodyProps): ReactElement {
-  const { content, width = DEFAULT_WIDTH } = props;
+  const { className, content, width = DEFAULT_WIDTH } = props;
   const { title, body, example, link } = content;
 
   return (
-    <div className="help-body" style={{ ...BODY_STYLE, maxWidth: width }}>
-      <div style={TITLE_STYLE}>{title}</div>
-      <div style={TEXT_STYLE}>{body}</div>
-      {example === undefined ? null : (
-        <div style={EXAMPLE_STYLE}>
-          <code style={CODE_STYLE}>{example.code}</code>
-          {example.input === undefined ? null : (
+    <div
+      className={joinClassNames('help-body', className)}
+      style={{ ...BODY_STYLE, maxWidth: width }}
+    >
+      {title === undefined ? null : <div style={TITLE_STYLE}>{title}</div>}
+      {body === undefined ? null : <div style={TEXT_STYLE}>{body}</div>}
+      {examplesOf(example).map((item) => (
+        <div key={exampleKey(item)} style={EXAMPLE_STYLE}>
+          <code style={CODE_STYLE}>{item.code}</code>
+          {item.input === undefined ? null : (
             <div style={INPUT_STYLE}>
-              on <code style={CODE_STYLE}>{example.input}</code>
+              on <code style={CODE_STYLE}>{item.input}</code>
             </div>
           )}
-          {example.note === undefined ? null : (
-            <div style={NOTE_STYLE}>{example.note}</div>
+          {item.note === undefined ? null : (
+            <div style={NOTE_STYLE}>{item.note}</div>
           )}
         </div>
-      )}
+      ))}
       {link === undefined ? null : (
         <a
           href={link}
@@ -92,6 +108,26 @@ export function HelpBody(props: HelpBodyProps): ReactElement {
   );
 }
 
+// Two examples are only the same when all three of their parts are, and a help
+// that repeats one example has nothing to gain from drawing it twice.
+function exampleKey(example: HelpExample): string {
+  return `${example.code}\n${example.input ?? ''}\n${example.note ?? ''}`;
+}
+
+function examplesOf(example: HelpContent['example']): readonly HelpExample[] {
+  if (example === undefined) return [];
+  if ('code' in example) return [example];
+  const seen = new Set<string>();
+  const unique: HelpExample[] = [];
+  for (const item of example) {
+    const key = exampleKey(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(item);
+  }
+  return unique;
+}
+
 /** How wide a piece of help is drawn when the caller does not say. */
 const DEFAULT_WIDTH = 280;
 

package/src/help/ui/HelpIcon.tsx

@@ -1,13 +1,30 @@
+import type { IconName } from '@blueprintjs/core';
 import { Icon } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+
 import type { HelpContent } from './HelpBody.tsx';
 import { HelpTooltip } from './HelpTooltip.tsx';
+import { helpName } from './helpName.ts';
 
-/** What {@link HelpIcon} explains, and how big the glyph is. */
+/** What {@link HelpIcon} explains, and how the glyph looks. */
 export interface HelpIconProps {
-  /** The help the glyph reveals. */
+  /**
+   * The help the glyph reveals. A site with free-form help passes only a
+   * `body`.
+   */
   content: HelpContent;
+  /**
+   * What a screen reader calls the glyph.
+   * @default the help's title, or `'Help'` when it has none
+   */
+  label?: string;
+  /**
+   * Glyph drawn, for a site that marks help with another sign.
+   * @default 'help'
+   */
+  icon?: IconName;
   /**
    * Size of the glyph in pixels, so it sits on the line of the label it
    * follows.
@@ -35,18 +52,23 @@ export interface HelpIconProps {
  * @returns The glyph and its help.
  */
 export function HelpIcon(props: HelpIconProps): ReactElement {
-  const { content, size = 13, placement = 'right', className } = props;
+  const {
+    content,
+    label = helpName(content),
+    icon = 'help',
+    size = 13,
+    placement = 'right',
+    className,
+  } = props;
 
   return (
     <HelpTooltip content={content} placement={placement}>
       <Icon
-        icon="help"
+        icon={icon}
         size={size}
         tabIndex={0}
-        aria-label={content.title}
-        className={
-          className === undefined ? 'help-icon' : `help-icon ${className}`
-        }
+        aria-label={label}
+        className={joinClassNames('help-icon', className)}
       />
     </HelpTooltip>
   );

package/src/help/ui/HelpToolbarButton.tsx

@@ -4,6 +4,7 @@ import type { ReactElement } from 'react';
 
 import type { HelpContent } from './HelpBody.tsx';
 import { HelpTooltip } from './HelpTooltip.tsx';
+import { helpName } from './helpName.ts';
 
 /** What {@link HelpToolbarButton} explains, and what pressing it does. */
 export interface HelpToolbarButtonProps {
@@ -63,7 +64,7 @@ export function HelpToolbarButton(props: HelpToolbarButtonProps): ReactElement {
         size={small ? 'small' : 'medium'}
         icon={icon}
         text={label}
-        aria-label={label ?? content.title}
+        aria-label={label ?? helpName(content)}
         className={className}
         onClick={onClick}
       />

package/src/help/ui/HelpTooltip.tsx

@@ -26,6 +26,11 @@ export interface HelpTooltipProps {
    * @default undefined
    */
   popoverClassName?: string;
+  /**
+   * Class names added to the root element.
+   * @default undefined
+   */
+  className?: string;
 }
 
 /**
@@ -39,6 +44,7 @@ export interface HelpTooltipProps {
  */
 export function HelpTooltip(props: HelpTooltipProps): ReactElement {
   const {
+    className,
     content,
     children,
     placement = 'top',
@@ -49,6 +55,7 @@ export function HelpTooltip(props: HelpTooltipProps): ReactElement {
 
   return (
     <Tooltip
+      className={className}
       content={<HelpBody content={content} width={width} />}
       placement={placement}
       hoverOpenDelay={HOVER_OPEN_DELAY}

package/src/help/ui/helpName.ts

@@ -0,0 +1,11 @@
+import type { HelpContent } from './HelpBody.tsx';
+
+/**
+ * The name a glyph or a button carries for a screen reader: the help's own
+ * title, or a plain "Help" when the help has none.
+ * @param content - The help being named.
+ * @returns The accessible name.
+ */
+export function helpName(content: HelpContent): string {
+  return content.title ?? 'Help';
+}

package/src/hooks/ui/activationKey.ts

@@ -0,0 +1,58 @@
+import { isInteractiveTarget, isTextEntryTarget } from './keyTargets.ts';
+
+/** The subset of a keyboard event {@link onActivateKey} reads. */
+export interface ActivationKeyEvent {
+  /** The key that was pressed. */
+  key: string;
+  /** What the event was aimed at. */
+  target?: EventTarget | null;
+  /** The element the handler is attached to. */
+  currentTarget?: EventTarget | null;
+  /** True while a held key auto-repeats. */
+  repeat?: boolean;
+  /** Stops the space bar from scrolling the page. */
+  preventDefault: () => void;
+}
+
+/**
+ * Whether a key is the keyboard equivalent of a click: `Enter` or the space
+ * bar, which is what a `<button>` answers to.
+ * @param event - The keyboard event, or anything carrying its `key`.
+ * @returns True for `Enter` and the space bar.
+ */
+export function isActivationKey(
+  event: Pick<ActivationKeyEvent, 'key'>,
+): boolean {
+  return event.key === 'Enter' || event.key === ' ';
+}
+
+/**
+ * A `keydown` handler that gives an element which is not a `<button>` — a
+ * clickable row, a card, a drop zone with `role="button"` — the activation a
+ * button gets for free.
+ *
+ * `Enter` and the space bar call `activate`, with the default suppressed so the
+ * space bar does not also scroll the page. A key typed into a field inside the
+ * element, a key aimed at a button or a link nested in it, and the repeats of a
+ * held key are all left alone, so nothing is activated twice.
+ * @param activate - What a click on the element does; it receives the event.
+ * @returns The handler, to pass as `onKeyDown`.
+ */
+export function onActivateKey<TEvent extends ActivationKeyEvent>(
+  activate: (event: TEvent) => void,
+): (event: TEvent) => void {
+  return (event) => {
+    if (!isActivationKey(event) || event.repeat === true) return;
+    const { target, currentTarget } = event;
+    if (isTextEntryTarget(target)) return;
+    if (
+      target !== currentTarget &&
+      currentTarget !== undefined &&
+      isInteractiveTarget(target)
+    ) {
+      return;
+    }
+    event.preventDefault();
+    activate(event);
+  };
+}

package/src/hooks/ui/activeHeading.ts

@@ -0,0 +1,30 @@
+/** Anything whose position in the viewport can be measured, as a heading's. */
+interface MeasurableHeading {
+  /** Where the heading sits, relative to the viewport. */
+  getBoundingClientRect: () => { top: number };
+}
+
+/**
+ * Which heading the reader is under.
+ *
+ * The headings are in document order, so the one being read is the last whose
+ * top has passed the reading line. Before any has, the first counts, so a
+ * table of contents always marks something.
+ * @param headings - The headings, in document order.
+ * @param readingLine - Distance from the top of the viewport, in CSS pixels,
+ * a heading must pass to count as the one being read.
+ * @returns Its index, or `-1` when there is no heading at all.
+ */
+export function activeHeadingIndex(
+  headings: ArrayLike<MeasurableHeading>,
+  readingLine: number,
+): number {
+  if (headings.length === 0) return -1;
+  let active = 0;
+  for (let index = 0; index < headings.length; index++) {
+    const heading = headings[index] as MeasurableHeading;
+    if (heading.getBoundingClientRect().top > readingLine) break;
+    active = index;
+  }
+  return active;
+}

package/src/hooks/ui/asyncState.ts

@@ -0,0 +1,38 @@
+import { toError } from '../../error/core/toError.ts';
+
+/** Where an async task stands: still running, answered, or failed. */
+export type AsyncState<TData> =
+  | { status: 'loading'; data: undefined; error: undefined }
+  | { status: 'success'; data: TData; error: undefined }
+  | { status: 'error'; data: undefined; error: Error };
+
+/** The state a task starts in. */
+export const ASYNC_LOADING: AsyncState<never> = {
+  status: 'loading',
+  data: undefined,
+  error: undefined,
+};
+
+/**
+ * The state after a task answered.
+ * @param data - What it resolved to.
+ * @returns The success state.
+ */
+export function asyncSucceeded<TData>(data: TData): AsyncState<TData> {
+  return { status: 'success', data, error: undefined };
+}
+
+/**
+ * The state after a task failed. Data already on screen is kept rather than
+ * replaced by the failure of a refresh.
+ * @param previous - The state before the task ran.
+ * @param thrown - What it rejected with.
+ * @returns The state to show.
+ */
+export function asyncFailed<TData>(
+  previous: AsyncState<TData>,
+  thrown: unknown,
+): AsyncState<TData> {
+  if (previous.status === 'success') return previous;
+  return { status: 'error', data: undefined, error: toError(thrown) };
+}

package/src/hooks/ui/documentListNavigation.ts

@@ -0,0 +1,87 @@
+import { isInteractiveTarget, isTextEntryTarget } from './keyTargets.ts';
+import type {
+  ListNavigationHandlerOptions,
+  ListNavigationKeyEvent,
+} from './listNavigation.ts';
+import { handleListNavigationKey } from './listNavigation.ts';
+
+/** How a list whose keys are heard on the whole document behaves. */
+export interface DocumentListNavigationOptions extends ListNavigationHandlerOptions {
+  /**
+   * Called with the selected index when `Enter` is pressed, unless the key is
+   * aimed at a button, a link or a field that answers it itself.
+   * @default undefined — `Enter` is left to the page
+   */
+  onActivate?: (index: number) => void;
+  /**
+   * Whether `PageUp`, `PageDown`, `Home` and `End` move the selection too. Off
+   * by default: heard on the document, they would stop scrolling the page.
+   * @default false
+   */
+  pageKeys?: boolean;
+  /**
+   * Whether the list listens at all, e.g. `false` while a dialog is open over
+   * it or while another list on the page is the one being read.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Leaves a key to whatever it is aimed at, on top of the text fields that
+   * are always left alone: a structure editor's canvas, a slider, a menu.
+   * @default undefined
+   */
+  ignoreKey?: (event: DocumentListKeyEvent) => boolean;
+}
+
+/** The subset of a document keyboard event the navigation reads. */
+export interface DocumentListKeyEvent extends ListNavigationKeyEvent {
+  /** True when an earlier handler already acted on the key. */
+  defaultPrevented?: boolean;
+  /** Whether Alt was held. */
+  altKey?: boolean;
+  /** Whether Control was held. */
+  ctrlKey?: boolean;
+  /** Whether Meta (Command) was held. */
+  metaKey?: boolean;
+  /** Whether Shift was held. */
+  shiftKey?: boolean;
+}
+
+/**
+ * Move a list's selection from a key heard on the whole document.
+ *
+ * A key already handled, a key pressed with a modifier, and a key aimed at a
+ * text field are left to the page. `ArrowUp` and `ArrowDown` move the
+ * selection as {@link handleListNavigationKey} does, and `Enter` activates the
+ * selected entry when the list asks for it.
+ * @param event - The native keyboard event.
+ * @param options - See {@link DocumentListNavigationOptions}.
+ * @returns Whether the selection moved; an activation does not move it.
+ */
+export function handleDocumentListKey(
+  event: DocumentListKeyEvent,
+  options: DocumentListNavigationOptions,
+): boolean {
+  const { enabled = true, pageKeys = false, onActivate, ignoreKey } = options;
+  if (!enabled || event.defaultPrevented === true) return false;
+  if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {
+    return false;
+  }
+  if (isTextEntryTarget(event.target)) return false;
+  if (ignoreKey?.(event) === true) return false;
+
+  if (event.key === 'Enter') {
+    const { selectedIndex, length } = options;
+    if (onActivate === undefined || isInteractiveTarget(event.target)) {
+      return false;
+    }
+    if (selectedIndex < 0 || selectedIndex >= length) return false;
+    event.preventDefault();
+    onActivate(selectedIndex);
+    return false;
+  }
+  if (!pageKeys && event.key !== 'ArrowUp' && event.key !== 'ArrowDown') {
+    return false;
+  }
+  return handleListNavigationKey(event, options);
+}