@adecore/ui 0.14.0

package/src/Toasts.tsx

@@ -0,0 +1,151 @@
+import { useState, type ReactNode, type Ref } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { CircleAlert, CircleCheck, Trash, X } from 'lucide-react';
+import { Icon } from './Icon.tsx';
+import { IconButton } from './IconButton.tsx';
+import { Kbd } from './Kbd.tsx';
+import { Spinner } from './Spinner.tsx';
+import { Surface } from './Surface.tsx';
+import { elapsedOf, type Toast, type ToastAction, type ToastDeadline, type ToastStoreHook } from './toast-store.ts';
+
+const ICON = {
+    success: CircleCheck,
+    error: CircleAlert,
+    deleted: Trash
+} as const;
+
+const TONE = {
+    progress: 'text-text-muted',
+    success: 'text-status-idle',
+    error: 'text-status-error',
+    deleted: 'text-text-muted'
+} as const;
+
+/* The box is as tall as the title's own line, so what sits beside the title centers on that line. */
+const TITLE_LINE = 'flex h-(--text-sm--line-height) shrink-0 items-center';
+
+/*
+ * How long the offer in a toast still stands, drawn from the timer that takes the toast away: the
+ * ring starts as far along as that timer already is, so both end together. With motion off it stays full.
+ */
+function TimerRing({ deadline, onDismiss }: { deadline: ToastDeadline; onDismiss(): void }) {
+    const { t } = useTranslation('ui');
+    const lifetime = deadline.end - deadline.start;
+    const [elapsed] = useState(() => elapsedOf(deadline, Date.now()));
+    return (
+        <IconButton size="xs" label={t('action.dismiss')} className="group/ring relative -my-px" onClick={onDismiss}>
+            <svg width={16} height={16} viewBox="0 0 16 16" className="-rotate-90" aria-hidden>
+                <circle cx={8} cy={8} r={6} fill="none" strokeWidth={2} className="stroke-border" />
+                <circle
+                    cx={8}
+                    cy={8}
+                    r={6}
+                    fill="none"
+                    strokeWidth={2}
+                    pathLength={1}
+                    strokeDasharray={1}
+                    className="toast-timer-arc stroke-current"
+                    style={{ animationDuration: `${lifetime}ms`, animationDelay: `${-elapsed}ms` }}
+                />
+            </svg>
+            <Icon icon={X} size={8} className="absolute opacity-0 group-hover/ring:opacity-100 group-focus-visible/ring:opacity-100" />
+        </IconButton>
+    );
+}
+
+function ActionButton({ action }: { action: ToastAction }) {
+    return (
+        <span className="flex items-center gap-2">
+            <button className="rounded-sm text-sm font-semibold text-text hover:text-text-muted" onClick={action.run}>
+                {action.label}
+            </button>
+            {action.shortcut && <Kbd shortcut={action.shortcut} className="font-sans text-xs text-text-faint" />}
+        </span>
+    );
+}
+
+function ToastCard<T extends Toast>({ toast, footer, onDismiss }: { toast: T; footer?: (toast: T) => ReactNode; onDismiss(): void }) {
+    const { t } = useTranslation('ui');
+    // A toast that goes by itself keeps its close button out of sight until the pointer or the keyboard is on it.
+    const leaves = toast.kind === 'deleted' || (toast.kind === 'success' && toast.persist !== true);
+    const actions = [...(toast.action === undefined ? [] : [toast.action]), ...(toast.actions ?? [])];
+    // An offer that runs out shows how long it has left instead.
+    const countdown = actions.length > 0 ? toast.deadline : undefined;
+    return (
+        <Surface className="group flex items-start gap-3 rounded-[10px] py-2.5 pr-2 pl-3">
+            <span className={clsx(TITLE_LINE, 'w-4 justify-center')}>
+                {toast.kind === 'progress' ? (
+                    <Spinner size={16} className={TONE.progress} />
+                ) : (
+                    <Icon icon={ICON[toast.kind]} size={16} className={TONE[toast.kind]} />
+                )}
+            </span>
+            <div className="flex min-w-0 grow flex-col gap-1">
+                <span className="text-sm text-text">{toast.title}</span>
+                {/* Wraps rather than clips: the line under the title is the one that says what went
+                   wrong, and a reason cut off at the card's edge is no reason at all. */}
+                {toast.description !== undefined && toast.description !== '' && (
+                    <span className="text-xs break-words text-pretty text-text-muted">{toast.description}</span>
+                )}
+                {/* Two or more would squeeze the title beside them, so they get a line of their own. */}
+                {actions.length > 1 && (
+                    <span className="mt-1 flex flex-wrap items-center gap-x-4 gap-y-1">
+                        {actions.map((action) => (
+                            <ActionButton key={action.label} action={action} />
+                        ))}
+                    </span>
+                )}
+                {footer?.(toast)}
+            </div>
+            {actions.length === 1 && (
+                <span className={TITLE_LINE}>
+                    <ActionButton action={actions[0]} />
+                </span>
+            )}
+            {countdown !== undefined ? (
+                <TimerRing key={countdown.start} deadline={countdown} onDismiss={onDismiss} />
+            ) : (
+                <IconButton
+                    icon={X}
+                    size="xs"
+                    label={t('action.dismiss')}
+                    className={clsx('-my-px', leaves && 'opacity-0 group-focus-within:opacity-100 group-hover:opacity-100')}
+                    onClick={onDismiss}
+                />
+            )}
+        </Surface>
+    );
+}
+
+export interface ToastsProps<T extends Toast> {
+    store: ToastStoreHook<T>;
+    /* Drawn under the description, for what only the app knows how to offer, such as copying a command's output. */
+    footer?: (toast: T) => ReactNode;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+
+/*
+ * Bottom right, over everything: what an action is doing while it runs and how it went when it is
+ * over, and a deletion that can still be taken back. A success takes itself away after four seconds,
+ * a deletion after eight, and a failure waits to be read.
+ */
+export function Toasts<T extends Toast>({ store, footer, className, ref }: ToastsProps<T>) {
+    const toasts = store((state) => state.toasts);
+    if (toasts.length === 0) {
+        return null;
+    }
+    return (
+        <div
+            ref={ref}
+            className={clsx('fixed right-4 bottom-4 z-(--z-popup) flex w-90 max-w-[calc(100vw-32px)] flex-col gap-2', className)}
+            role="status"
+            aria-live="polite"
+        >
+            {toasts.map((toast) => (
+                <ToastCard key={toast.id} toast={toast} footer={footer} onDismiss={() => store.getState().dismiss(toast.id)} />
+            ))}
+        </div>
+    );
+}

package/src/Tooltip.tsx

@@ -0,0 +1,70 @@
+import { useCallback, type ReactElement, type ReactNode } from 'react';
+import { Tooltip as BaseTooltip } from '@base-ui-components/react/tooltip';
+import { Kbd } from './Kbd.tsx';
+import type { Shortcut } from './shortcut.ts';
+import { registerShortcutHint } from './shortcut-hints.ts';
+
+export type TooltipSide = 'top' | 'bottom' | 'left' | 'right';
+
+/* One provider per app. Tooltips share a delay, so moving along a row of buttons feels instant. `UIProvider` mounts it. */
+export function TooltipProvider({ children }: { children: ReactNode }) {
+    return (
+        <BaseTooltip.Provider delay={150} closeDelay={0}>
+            {children}
+        </BaseTooltip.Provider>
+    );
+}
+
+export interface TooltipProps {
+    label: ReactNode;
+    /* A shortcut, or a short phrase about a key that is not one ("Shift skips the cache"). */
+    kbd?: Shortcut | string;
+    side?: TooltipSide;
+    sideOffset?: number;
+    /* Makes the label the accessible name of the trigger as well: what an icon-only button needs,
+       and the way to keep the name and the tooltip from ever saying two different things. */
+    name?: boolean;
+    /* Keeps the hint closed, for a trigger that only needs one some of the time. */
+    disabled?: boolean;
+    /* The trigger element. Its own children and handlers are kept; Base UI merges the tooltip props in. */
+    children: ReactElement<Record<string, unknown>>;
+}
+
+/* A hint on hover and on keyboard focus. Every hint in an app is one of these, never a `title`. */
+export function Tooltip({ label, kbd, side = 'top', sideOffset = 6, name = false, disabled = false, children }: TooltipProps) {
+    // Held Cmd (Ctrl off macOS) prints this shortcut under the trigger (`ShortcutHints`).
+    const hintRef = useCallback(
+        (element: HTMLElement | null) => {
+            if (element === null || kbd === undefined || typeof kbd === 'string') {
+                return undefined;
+            }
+            return registerShortcutHint(element, kbd);
+        },
+        [kbd]
+    );
+
+    return (
+        <BaseTooltip.Root disabled={disabled}>
+            <BaseTooltip.Trigger ref={hintRef} render={children} aria-label={name && typeof label === 'string' ? label : undefined} />
+            <BaseTooltip.Portal>
+                <BaseTooltip.Positioner side={side} sideOffset={sideOffset} className="tooltip-positioner">
+                    <BaseTooltip.Popup className="tooltip-popup">
+                        <BaseTooltip.Viewport className="max-w-72 px-[9px] py-[5px] text-pretty">
+                            <span className="wrap-anywhere">{label}</span>
+                            {/* The viewport wraps its children in a div of its own, so the 8px
+                                between the label and the shortcut has to sit on the shortcut itself. */}
+                            {kbd !== undefined &&
+                                (typeof kbd === 'string' ? (
+                                    <Kbd variant="inline" className="ml-2">
+                                        {kbd}
+                                    </Kbd>
+                                ) : (
+                                    <Kbd shortcut={kbd} variant="inline" className="ml-2" />
+                                ))}
+                        </BaseTooltip.Viewport>
+                    </BaseTooltip.Popup>
+                </BaseTooltip.Positioner>
+            </BaseTooltip.Portal>
+        </BaseTooltip.Root>
+    );
+}

package/src/UIProvider.tsx

@@ -0,0 +1,41 @@
+import { useLayoutEffect, useState, type ReactNode } from 'react';
+import type { i18n as I18n } from 'i18next';
+import { I18nextProvider } from 'react-i18next';
+import { setFormatSource, type FormatSource } from './format/locale.ts';
+import { addUiResources } from './locales.ts';
+import { startInputModality } from './modality.ts';
+import { TooltipProvider } from './Tooltip.tsx';
+
+export interface UIProviderProps {
+    /* The app's i18next instance. The library's `ui` namespace is added to it, in every language it ships. */
+    i18n: I18n;
+    /* Where the formatters read the language and the region a person set. Without one they write English in the region of that language. */
+    formatSource?: FormatSource;
+    children: ReactNode;
+}
+
+/*
+ * Everything the library needs from an app, once, around the whole tree: its words in the app's
+ * i18next, the source of the formatters, the shared tooltip delay and the note of which input device
+ * is in use. Mount it above the first component of the library.
+ */
+export function UIProvider({ i18n, formatSource, children }: UIProviderProps) {
+    const [handed, setHanded] = useState<{ i18n: I18n | null; source: FormatSource | undefined }>({ i18n: null, source: undefined });
+    // In render and not in an effect, so the first child already reads the words and the region.
+    // Both calls only store what they are handed, so a render React throws away leaves nothing wrong behind.
+    if (handed.i18n !== i18n || handed.source !== formatSource) {
+        addUiResources(i18n);
+        if (formatSource !== undefined) {
+            setFormatSource(formatSource);
+        }
+        setHanded({ i18n, source: formatSource });
+    }
+
+    useLayoutEffect(startInputModality, []);
+
+    return (
+        <I18nextProvider i18n={i18n}>
+            <TooltipProvider>{children}</TooltipProvider>
+        </I18nextProvider>
+    );
+}

package/src/Waveform.tsx

@@ -0,0 +1,199 @@
+import { useMemo, useRef, type KeyboardEvent, type PointerEvent, type Ref } from 'react';
+import clsx from 'clsx';
+import { useTranslation } from 'react-i18next';
+import { formatClockDuration } from './format/duration.ts';
+import { mergeRefs } from './merge-refs.ts';
+import { useMeasuredWidth } from './useMeasuredWidth.ts';
+
+/* About one bar per 3px, each 2px wide; a bar sits at its own time, so it lines up with the marks and the playhead. */
+const BAR_PITCH = 3;
+const BAR_WIDTH = 2;
+
+/* The height of a silent bar, so silence still reads as a line. */
+const SILENCE = 0.04;
+
+/* Page Up and Page Down move this many steps, as a Base UI slider does. */
+const PAGE_STEPS = 10;
+
+/* The loudest sample under each bar, or null for a bar past either end of the audio. */
+const barsOf = (levels: readonly number[], duration: number, from: number, to: number, count: number): (number | null)[] => {
+    if (count <= 0 || levels.length === 0 || duration <= 0 || to <= from) {
+        return [];
+    }
+    const perSecond = levels.length / duration;
+    return Array.from({ length: count }, (_, i) => {
+        const start = from + ((to - from) * i) / count;
+        const end = from + ((to - from) * (i + 1)) / count;
+        if (end <= 0 || start >= duration) {
+            return null;
+        }
+        const first = Math.max(0, Math.floor(start * perSecond));
+        const last = Math.min(levels.length - 1, Math.max(first, Math.ceil(end * perSecond) - 1));
+        let level = 0;
+        for (let index = first; index <= last; index++) {
+            level = Math.max(level, levels[index] ?? 0);
+        }
+        return Math.min(1, Math.max(SILENCE, level));
+    });
+};
+
+export interface WaveformProps {
+    /* The loudness as samples spread evenly over the duration, from 0 for silence to 1 for the loudest, at any rate. */
+    levels: readonly number[];
+    /* In seconds. */
+    duration: number;
+    /* The stretch it shows, in seconds, such as the visible part of a zoomed timeline. Defaults to the whole. */
+    range?: readonly [from: number, to: number];
+    /* How far it has played, in seconds. Left out, the waveform draws no playhead. */
+    value?: number;
+    /* Seeks to a time in seconds. Without it the waveform only shows. */
+    onValueChange?(value: number): void;
+    /* The time a drag lets go at, and the one a key moved to: where a player resumes what it held during the drag. */
+    onValueCommitted?(value: number): void;
+    /* How far an arrow key moves the playhead, in seconds. */
+    step?: number;
+    /* Hears a key before the waveform does. A key it calls `preventDefault` on, the waveform leaves alone and lets
+       bubble, for a player around it that binds the key to something else. */
+    onKeyDown?(e: KeyboardEvent<HTMLDivElement>): void;
+    /* Times in seconds drawn as lines through the waveform, such as cuts. */
+    marks?: readonly number[];
+    label: string;
+    /* Its height, which the waveform fills. */
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+
+/* The loudness of a piece of audio over time, played up to the playhead, where a press or a drag seeks. */
+export function Waveform({
+    levels,
+    duration,
+    range,
+    value,
+    onValueChange,
+    onValueCommitted,
+    step = 1,
+    onKeyDown,
+    marks = [],
+    label,
+    className,
+    ref
+}: WaveformProps) {
+    const { t } = useTranslation('ui');
+    const [measure, width] = useMeasuredWidth();
+    const rootRef = useMemo(() => mergeRefs(ref, measure), [ref, measure]);
+    const dragged = useRef(0);
+    const [from, to] = range ?? [0, duration];
+    const span = to - from;
+    const count = Math.floor(width / BAR_PITCH);
+    const bars = useMemo(() => barsOf(levels, duration, from, to, count), [levels, duration, from, to, count]);
+
+    const positionOf = (time: number): number => (span > 0 ? (time - from) / span : 0);
+    const inView = (time: number): boolean => positionOf(time) >= 0 && positionOf(time) <= 1;
+    const clamp = (time: number): number => Math.min(duration, Math.max(0, time));
+
+    const seekAt = (e: PointerEvent<HTMLDivElement>): void => {
+        const rect = e.currentTarget.getBoundingClientRect();
+        if (rect.width > 0) {
+            dragged.current = clamp(from + ((e.clientX - rect.left) / rect.width) * span);
+            onValueChange?.(dragged.current);
+        }
+    };
+
+    const letGo = (e: PointerEvent<HTMLDivElement>): void => {
+        if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+            e.currentTarget.releasePointerCapture(e.pointerId);
+            onValueCommitted?.(dragged.current);
+        }
+    };
+
+    const moveByKey = (e: KeyboardEvent<HTMLDivElement>): void => {
+        onKeyDown?.(e);
+        if (e.defaultPrevented) {
+            return;
+        }
+        const at = value ?? 0;
+        const moves: Record<string, number> = {
+            ArrowLeft: at - step,
+            ArrowDown: at - step,
+            ArrowRight: at + step,
+            ArrowUp: at + step,
+            PageDown: at - step * PAGE_STEPS,
+            PageUp: at + step * PAGE_STEPS,
+            Home: 0,
+            End: duration
+        };
+        const next = moves[e.key];
+        if (next === undefined) {
+            return;
+        }
+        // The slider owns these keys; a transport listening higher up would move the playhead a second time.
+        e.preventDefault();
+        e.stopPropagation();
+        onValueChange?.(clamp(next));
+        onValueCommitted?.(clamp(next));
+    };
+
+    const slider =
+        onValueChange === undefined
+            ? { role: 'img' }
+            : {
+                  role: 'slider',
+                  tabIndex: 0,
+                  'aria-valuemin': 0,
+                  'aria-valuemax': duration,
+                  'aria-valuenow': value ?? 0,
+                  'aria-valuetext': t('waveform.position', {
+                      time: formatClockDuration((value ?? 0) * 1000),
+                      duration: formatClockDuration(duration * 1000)
+                  }),
+                  onPointerDown: (e: PointerEvent<HTMLDivElement>) => {
+                      e.currentTarget.setPointerCapture(e.pointerId);
+                      seekAt(e);
+                  },
+                  onPointerMove: (e: PointerEvent<HTMLDivElement>) => {
+                      if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+                          seekAt(e);
+                      }
+                  },
+                  onPointerUp: letGo,
+                  onPointerCancel: letGo,
+                  onKeyDown: moveByKey
+              };
+
+    return (
+        <div
+            ref={rootRef}
+            aria-label={label}
+            {...slider}
+            className={clsx('relative select-none', onValueChange !== undefined && 'focus-ring cursor-ew-resize touch-none', className)}
+        >
+            <svg className="absolute inset-0 size-full" viewBox={`0 0 ${Math.max(1, width)} 100`} preserveAspectRatio="none" aria-hidden>
+                {bars.map((level, i) => {
+                    if (level === null) {
+                        return null;
+                    }
+                    const center = from + (span * (i + 0.5)) / count;
+                    return (
+                        <rect
+                            key={i}
+                            x={Math.round((i * width) / count)}
+                            y={(100 - level * 100) / 2}
+                            width={BAR_WIDTH}
+                            height={level * 100}
+                            className={value !== undefined && center <= value ? 'fill-accent' : 'fill-text-faint'}
+                        />
+                    );
+                })}
+                {marks.filter(inView).map((mark) => {
+                    const x = Math.round(positionOf(mark) * width) + 0.5;
+                    return (
+                        <line key={mark} x1={x} x2={x} y1={0} y2={100} strokeWidth={1} vectorEffect="non-scaling-stroke" className="stroke-accent opacity-60" />
+                    );
+                })}
+            </svg>
+            {value !== undefined && inView(value) && (
+                <span className="pointer-events-none absolute inset-y-0 w-px bg-accent" style={{ left: `${positionOf(value) * 100}%` }} />
+            )}
+        </div>
+    );
+}

package/src/Wipe.tsx

@@ -0,0 +1,99 @@
+import { useRef, type KeyboardEvent, type PointerEvent, type ReactNode, type Ref } from 'react';
+import clsx from 'clsx';
+import { ChevronsLeftRight } from 'lucide-react';
+import { Icon } from './Icon.tsx';
+import { formatPercent } from './format/number.ts';
+import { mergeRefs } from './merge-refs.ts';
+import { splitAt, splitForKey } from './wipe-split.ts';
+
+export interface WipeProps {
+    /* The share of the width left of the handle, from 0 to 1. */
+    value: number;
+    onValueChange(value: number): void;
+    before: ReactNode;
+    after: ReactNode;
+    label: string;
+    handle?: 'knob' | 'line';
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+
+/*
+ * Two versions of one picture in one frame: `before` left of the split and `after` right of it, with a
+ * handle between them a person drags or moves with the arrow keys. It fills the positioned element it
+ * sits in. The handle is a line with a round knob on it, or the plain line, which is dragged anywhere
+ * along its height.
+ */
+export function Wipe({ value: split, onValueChange: onSplit, before, after, label, handle = 'knob', className, ref }: WipeProps) {
+    const frame = useRef<HTMLDivElement>(null);
+    const percent = `${split * 100}%`;
+
+    function moveTo(clientX: number): void {
+        const rect = frame.current?.getBoundingClientRect();
+        const next = rect ? splitAt(clientX, rect) : null;
+        if (next !== null) {
+            onSplit(next);
+        }
+    }
+
+    function onPointerDown(e: PointerEvent<HTMLDivElement>): void {
+        e.preventDefault();
+        e.stopPropagation();
+        e.currentTarget.setPointerCapture(e.pointerId);
+        moveTo(e.clientX);
+    }
+
+    function onPointerMove(e: PointerEvent<HTMLDivElement>): void {
+        if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+            moveTo(e.clientX);
+        }
+    }
+
+    function onKeyDown(e: KeyboardEvent<HTMLDivElement>): void {
+        const next = splitForKey(split, e.key);
+        if (next === null) {
+            return;
+        }
+        // Only while the handle has the focus, so a canvas or a timeline around it never hears these keys.
+        e.preventDefault();
+        e.stopPropagation();
+        onSplit(next);
+    }
+
+    return (
+        <div ref={mergeRefs(frame, ref)} className={clsx('absolute inset-0', className)}>
+            <div className="absolute inset-0">{before}</div>
+            <div className="absolute inset-0" style={{ clipPath: `inset(0 0 0 ${percent})` }}>
+                {after}
+            </div>
+            <div
+                role="slider"
+                tabIndex={0}
+                aria-label={label}
+                aria-orientation="horizontal"
+                aria-valuemin={0}
+                aria-valuemax={100}
+                aria-valuenow={Math.round(split * 100)}
+                aria-valuetext={formatPercent(Math.round(split * 100))}
+                className={clsx('group absolute inset-y-0 z-10 -ml-3.5 w-7 cursor-ew-resize touch-none', handle === 'line' && 'outline-none')}
+                style={{ left: percent }}
+                onPointerDown={onPointerDown}
+                onPointerMove={onPointerMove}
+                onKeyDown={onKeyDown}
+            >
+                {/* Without a knob the line itself shows the focus, since a ring around its wide grip would read as two more lines. */}
+                <span
+                    className={clsx(
+                        'absolute inset-y-0 left-3.25 w-0.5 bg-media-handle shadow-media-handle-edge',
+                        handle === 'line' && 'group-focus-visible:bg-accent'
+                    )}
+                />
+                {handle === 'knob' && (
+                    <span className="absolute top-1/2 left-3.5 grid h-7 w-7 -translate-1/2 place-items-center rounded-full bg-media-handle text-media-handle-text shadow-media-handle">
+                        <Icon icon={ChevronsLeftRight} size={14} />
+                    </span>
+                )}
+            </div>
+        </div>
+    );
+}

package/src/ZoomControls.tsx

@@ -0,0 +1,99 @@
+import type { Ref } from 'react';
+import { Maximize, Minus, Plus, Scan } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
+import { ButtonGroup } from './ButtonGroup.tsx';
+import { Icon } from './Icon.tsx';
+import { IconButton } from './IconButton.tsx';
+import { Kbd } from './Kbd.tsx';
+import { MenuItem, MenuPopup, MenuRadioGroup, MenuRadioItem, MenuRoot, MenuSeparator, MenuTrigger } from './menu/parts.tsx';
+import type { Shortcut } from './shortcut.ts';
+import { Tooltip } from './Tooltip.tsx';
+import { activeZoomPreset, steppedZoom, ZOOM_PRESETS } from './zoom.ts';
+
+export interface ZoomSelection {
+    label: string;
+    shortcut?: Shortcut;
+    /* Nothing is selected, so the row is there but says so rather than doing nothing. */
+    enabled: boolean;
+    onZoom(): void;
+}
+
+/* The words, when the app wants its own; each falls back to the library's. */
+export interface ZoomLabels {
+    out?: string;
+    in?: string;
+    presets?: string;
+    fit?: string;
+    fitEverything?: string;
+}
+
+export interface ZoomControlsProps {
+    /* 1 is 100%. */
+    zoom: number;
+    onZoomChange(zoom: number): void;
+    onFitAll(): void;
+    /* The percentages in the menu under the readout. */
+    presets?: readonly number[];
+    labels?: ZoomLabels;
+    shortcuts?: { zoomReset?: Shortcut; fitAll?: Shortcut };
+    /* Left out by a surface with nothing to select. */
+    selection?: ZoomSelection;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+
+/* The zoom group of a dock: out, the readout with its presets, in, and fit everything. */
+export function ZoomControls({
+    zoom,
+    onZoomChange,
+    onFitAll,
+    presets = ZOOM_PRESETS,
+    labels = {},
+    shortcuts = {},
+    selection,
+    className,
+    ref
+}: ZoomControlsProps) {
+    const { t } = useTranslation('ui');
+    const preset = activeZoomPreset(zoom, presets);
+
+    return (
+        <ButtonGroup ref={ref} className={className}>
+            <IconButton icon={Minus} label={labels.out ?? t('zoom.out')} onClick={() => onZoomChange(steppedZoom(zoom, -10))} />
+            <MenuRoot>
+                <Tooltip label={labels.presets ?? t('zoom.presets')}>
+                    <MenuTrigger className="h-8 min-w-14 rounded-lg px-1 text-xs text-text-muted tabular-nums hover:bg-surface-hover hover:text-text data-[popup-open]:bg-surface-active data-[popup-open]:text-text">
+                        {Math.round(zoom * 100)}%
+                    </MenuTrigger>
+                </Tooltip>
+                <MenuPopup side="top" sideOffset={10} align="center" className="min-w-44">
+                    <MenuRadioGroup value={preset} onValueChange={(value: number) => onZoomChange(value / 100)}>
+                        {presets.map((percent) => (
+                            <MenuRadioItem key={percent} value={percent}>
+                                <span className="tabular-nums">{percent}%</span>
+                                {percent === 100 && shortcuts.zoomReset && <Kbd shortcut={shortcuts.zoomReset} />}
+                            </MenuRadioItem>
+                        ))}
+                    </MenuRadioGroup>
+                    <MenuSeparator />
+                    <MenuItem onClick={onFitAll}>
+                        <span className="grid h-4 w-4 place-items-center">
+                            <Icon icon={Maximize} size={14} />
+                        </span>
+                        {labels.fit ?? t('zoom.fit')} {shortcuts.fitAll && <Kbd shortcut={shortcuts.fitAll} />}
+                    </MenuItem>
+                    {selection && (
+                        <MenuItem disabled={!selection.enabled} onClick={selection.onZoom}>
+                            <span className="grid h-4 w-4 place-items-center">
+                                <Icon icon={Scan} size={14} />
+                            </span>
+                            {selection.label} {selection.shortcut && <Kbd shortcut={selection.shortcut} />}
+                        </MenuItem>
+                    )}
+                </MenuPopup>
+            </MenuRoot>
+            <IconButton icon={Plus} label={labels.in ?? t('zoom.in')} onClick={() => onZoomChange(steppedZoom(zoom, 10))} />
+            <IconButton icon={Maximize} label={labels.fitEverything ?? t('zoom.fitEverything')} kbd={shortcuts.fitAll} onClick={onFitAll} />
+        </ButtonGroup>
+    );
+}

package/src/class-name.ts

@@ -0,0 +1,8 @@
+import clsx from 'clsx';
+
+/* A Base UI `className`: a string, or a function of the part's state. */
+export type StateClassName<State> = string | ((state: State) => string | undefined) | undefined;
+
+/* Puts the library's own classes before a caller's, whichever form the caller's takes. */
+export const withClass = <State>(own: string, className: StateClassName<State>): string | ((state: State) => string) =>
+    typeof className === 'function' ? (state: State) => clsx(own, className(state)) : clsx(own, className);