@mond-design-system/react 3.0.3 → 4.1.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { CSSProperties, HTMLAttributes, JSX, ReactElement, ReactNode, ButtonHTMLAttributes, ElementType, Ref, ComponentPropsWithoutRef, MouseEventHandler, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, RefObject, KeyboardEvent } from 'react';
+import { CSSProperties, HTMLAttributes, JSX, ReactElement, Ref, ReactNode, ButtonHTMLAttributes, ElementType, ComponentPropsWithRef, MouseEventHandler, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, RefObject, KeyboardEvent } from 'react';
 
 /**
  * Join class names, dropping anything falsy.
@@ -67,8 +67,10 @@ declare function Heading({ level, variant, tone, className, ...rest }: HeadingPr
 interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
     /** Diameter in px. Default 20. */
     size?: number;
-    /** Accessible label. Default "Loading". */
-    label?: string;
+    /** Accessible label. Required: the words are the app's, in the app's
+        language, and a default here is one no translation file can reach. */
+    label: string;
+    ref?: Ref<HTMLSpanElement>;
 }
 /**
  * Indeterminate loading ring. Arc takes currentColor, so it matches whatever
@@ -120,15 +122,26 @@ interface IconProps extends HTMLAttributes<HTMLSpanElement> {
     size?: IconSize;
     /** Accessible name. Omitted = decorative (aria-hidden). */
     label?: string;
+    ref?: Ref<HTMLSpanElement>;
 }
 /** A glyph from the app-registered set, sized on the core scale. */
 declare function Icon({ name, size, label, className, ...rest }: IconProps): ReactElement;
 
 type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "warning" | "highlight";
 type ButtonSize = "sm" | "md" | "lg";
+type ButtonShape = "rect" | "pill";
 interface ButtonBaseProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
     variant?: ButtonVariant;
     size?: ButtonSize;
+    /** Standing on a picture, where the page's own foreground would be read
+     *  against a photograph. Only the two see-through variants take it up: a
+     *  filled button brings its own ground. */
+    onMedia?: boolean;
+    /** Corner shape, when the default is not the one this button wants: a
+     *  rectangle where `iconOnly` would round it, or a pill around words.
+     *  Unset, the shape follows from the size — rect, or a circle when
+     *  `iconOnly`. */
+    shape?: ButtonShape;
     /** Glyph slots — pass an <Icon> or any node. Agnostic of icon set; the
      *  button sizes the slot from its own size, and publishes that step as
      *  --mds-icon-slot for an icon set that can only size itself. */
@@ -160,9 +173,10 @@ type ButtonProps = ButtonBaseProps & IconOnlyEnforcement;
  * <Button variant="danger" loading={deleting} onClick={remove}>Delete</Button>
  * <Button iconOnly aria-label="Close" variant="ghost"><Icon name="close" /></Button>
  * <Button href="/settings">Settings</Button>
+ * <Button iconOnly aria-label="Menu" shape="rect"><Icon name="menu" /></Button>
  * ```
  */
-declare function Button({ variant, size, iconLeft, iconRight, loading, disabled, fullWidth, iconOnly, type, href, as, className, children, ...rest }: ButtonProps): ReactElement;
+declare function Button({ variant, size, shape, onMedia, iconLeft, iconRight, loading, disabled, fullWidth, iconOnly, type, href, as, className, children, ...rest }: ButtonProps): ReactElement;
 
 type LinkVariant = "inline" | "standalone" | "plain";
 type LinkSize = "xs" | "sm" | "base" | "lg" | "xl";
@@ -180,7 +194,7 @@ type LinkOwnProps<E extends ElementType> = {
     as?: E;
     children?: ReactNode;
 };
-type LinkProps<E extends ElementType = "a"> = LinkOwnProps<E> & Omit<ComponentPropsWithoutRef<E>, keyof LinkOwnProps<E>>;
+type LinkProps<E extends ElementType = "a"> = LinkOwnProps<E> & Omit<ComponentPropsWithRef<E>, keyof LinkOwnProps<E>>;
 /**
  * Text link. Inline links keep their underline: color alone fails WCAG 1.4.1
  * for links inside prose.
@@ -208,6 +222,7 @@ interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
     /** Hide from assistive tech — for avatars that repeat a name already in
         the row's text. The name prop still drives the initials. */
     decorative?: boolean;
+    ref?: Ref<HTMLSpanElement>;
 }
 /**
  * Person marker. Image when available, initials otherwise — never an empty circle.
@@ -226,12 +241,17 @@ interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
     max?: number;
     /** Sizes the overflow chip to match the avatars. Default "md". */
     size?: AvatarSize;
+    /** Names the "+N" chip, e.g. `(n) => `${n} more``. Required and a function:
+        the chip stands for people whose names are not on screen, and only the app
+        knows how its language counts them. */
+    overflowLabel: (hidden: number) => string;
+    ref?: Ref<HTMLDivElement>;
 }
 /**
  * Overlapping stack of avatars with a "+N" chip past `max`.
  *
  * ```tsx
- * <AvatarGroup max={3}>
+ * <AvatarGroup max={3} overflowLabel={(n) => `${n} more`}>
  *   <Avatar name="Ada Lovelace" />
  *   <Avatar name="Grace Hopper" />
  *   <Avatar name="Margaret Hamilton" />
@@ -239,11 +259,12 @@ interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
  * </AvatarGroup>
  * ```
  */
-declare function AvatarGroup({ children, max, size, className, ...rest }: AvatarGroupProps): ReactElement;
+declare function AvatarGroup({ children, max, size, overflowLabel, className, ...rest }: AvatarGroupProps): ReactElement;
 
 type BadgeTone = "neutral" | "accent" | "danger" | "warning" | "success" | "highlight";
 interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
     tone?: BadgeTone;
+    ref?: Ref<HTMLSpanElement>;
 }
 /**
  * Small status marker — counts, "new", state words. Soft fill, strong text.
@@ -268,6 +289,9 @@ interface ChipProps extends HTMLAttributes<HTMLElement> {
     /** When provided, Chip renders as a `<button>`. */
     onClick?: MouseEventHandler;
     disabled?: boolean;
+    /** The root is a `<button>` when it has an onClick and a `<span>` otherwise,
+        so the ref is typed to what both are. */
+    ref?: Ref<HTMLElement>;
 }
 /**
  * Compact pill for filters and single/multi choices. Interactive (a button,
@@ -279,7 +303,7 @@ interface ChipProps extends HTMLAttributes<HTMLElement> {
  * <Chip variant="outline" icon={<Icon name="pin" />}>Nearby</Chip>
  * ```
  */
-declare function Chip({ children, variant, selected, icon, onClick, disabled, className, ...rest }: ChipProps): ReactElement;
+declare function Chip({ children, variant, selected, icon, onClick, disabled, className, ref, ...rest }: ChipProps): ReactElement;
 
 type ChipGroupGap = "hairline" | "tight" | "base";
 interface ChipGroupProps extends HTMLAttributes<HTMLDivElement> {
@@ -287,6 +311,7 @@ interface ChipGroupProps extends HTMLAttributes<HTMLDivElement> {
     children: ReactNode;
     /** Space between items, on the gap scale. Default "tight". */
     gap?: ChipGroupGap;
+    ref?: Ref<HTMLDivElement>;
 }
 /**
  * Wrapping row of Chips for multi-select choices inside a form (pick several
@@ -315,6 +340,7 @@ interface ChipBarProps extends HTMLAttributes<HTMLDivElement> {
     bordered?: boolean;
     /** Fade the trailing edge to hint that the row scrolls. Default true. */
     fade?: boolean;
+    ref?: Ref<HTMLDivElement>;
 }
 /**
  * Horizontally scrollable single-line row of Chips — a filter strip. Items
@@ -356,6 +382,7 @@ interface CountButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>,
     loading?: boolean;
     /** Visible text beside the icon — typically a count or a word. */
     children?: ReactNode;
+    ref?: Ref<HTMLButtonElement>;
 }
 /**
  * Inline, chrome-less pressable pairing an icon with a count or word — like,
@@ -394,7 +421,8 @@ interface DateTimePickerProps {
     value?: string | undefined;
     /** Fires with the combined ISO string when the user confirms. */
     onChange: (iso: string) => void;
-    /** Shown on the trigger when nothing is selected. */
+    /** Shown on the trigger when nothing is selected. Nothing is shown without
+        it: the component ships no words of its own. */
     placeholder?: string | undefined;
     /** Earliest selectable moment as an ISO string. Default: now. */
     min?: string | undefined;
@@ -407,8 +435,10 @@ interface DateTimePickerProps {
     "aria-label"?: string | undefined;
     /** BCP 47 tag for names, week start and hour cycle. Default: runtime locale. */
     locale?: string | undefined;
-    /** Overrides for the picker's own strings (defaults are English). */
-    labels?: Partial<DateTimePickerLabels> | undefined;
+    /** Every string the picker says. Required and whole rather than a partial
+        over English defaults: a default is a word no translation file reaches,
+        and a partial makes the one nobody filled in look deliberate. */
+    labels: DateTimePickerLabels;
 }
 /**
  * Mobile-first date + time picker. A trigger styled like Input opens a bottom
@@ -422,6 +452,7 @@ interface DateTimePickerProps {
  *   <DateTimePicker
  *     value={startsAt}
  *     onChange={setStartsAt}
+ *     labels={t("picker", { returnObjects: true })}
  *     min={new Date().toISOString()}
  *     minuteStep={30}
  *     locale={i18n.language}
@@ -429,27 +460,37 @@ interface DateTimePickerProps {
  * </Field>
  * ```
  */
-declare function DateTimePicker({ value, onChange, placeholder, min, minuteStep, disabled, id, "aria-label": ariaLabel, locale, labels, }: DateTimePickerProps): ReactElement;
+declare function DateTimePicker({ value, onChange, placeholder, min, minuteStep, disabled, id, "aria-label": ariaLabel, locale, labels: text, }: DateTimePickerProps): ReactElement;
 
 type TagTone = "neutral" | "accent";
-interface TagProps extends HTMLAttributes<HTMLSpanElement> {
+type TagProps = HTMLAttributes<HTMLSpanElement> & {
     children: ReactNode;
     tone?: TagTone;
-    /** Renders a labelled ✕ button. Label reads "Remove <content>" when content is text. */
-    onRemove?: () => void;
-}
+    ref?: Ref<HTMLSpanElement>;
+} & ({
+    /** Renders a ✕ button after the content. */
+    onRemove: () => void;
+    /** Names that button, e.g. "Remove Beginner". Required alongside
+        `onRemove`: the glyph says nothing, and only the app knows how its
+        language builds the sentence. */
+    removeLabel: string;
+} | {
+    onRemove?: undefined;
+    removeLabel?: undefined;
+});
 /**
  * Content label chip — categories, filters, topics.
  *
  * ```tsx
  * <Tag>Design</Tag>
- * <Tag tone="accent" onRemove={() => remove(id)}>Beginner</Tag>
+ * <Tag tone="accent" onRemove={() => remove(id)} removeLabel="Remove Beginner">Beginner</Tag>
  * ```
  */
-declare function Tag({ children, tone, onRemove, className, ...rest }: TagProps): ReactElement;
+declare function Tag({ children, tone, onRemove, removeLabel, className, ...rest }: TagProps): ReactElement;
 
 interface DividerProps extends HTMLAttributes<HTMLDivElement> {
     orientation?: "horizontal" | "vertical";
+    ref?: Ref<HTMLDivElement>;
 }
 /**
  * Visual separator. Semantic separator role via <hr>-equivalent div.
@@ -461,12 +502,33 @@ interface DividerProps extends HTMLAttributes<HTMLDivElement> {
  */
 declare function Divider({ orientation, className, ...rest }: DividerProps): ReactElement;
 
+interface VisuallyHiddenProps extends HTMLAttributes<HTMLElement> {
+    /** Element override when the markup needs a particular tag — a page's h1, a
+        table's thead. Default "span". */
+    as?: keyof JSX.IntrinsicElements;
+}
+/**
+ * Text for screen readers and not for eyes.
+ *
+ * The design does not always draw what the markup owes: a screen whose title is
+ * the tab bar underneath it still needs an h1, and a table whose columns are
+ * obvious to look at still needs a thead. Both go here rather than into a
+ * one-off class in the app.
+ *
+ * ```tsx
+ * <VisuallyHidden as="h1">Discover</VisuallyHidden>
+ * <VisuallyHidden role="status" aria-live="polite">{message}</VisuallyHidden>
+ * ```
+ */
+declare function VisuallyHidden({ as, className, ...rest }: VisuallyHiddenProps): ReactElement;
+
 type SkeletonVariant = "text" | "rect" | "circle";
 interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
     variant?: SkeletonVariant;
     /** Any CSS length. Text defaults to full width, one line tall. */
     width?: string;
     height?: string;
+    ref?: Ref<HTMLSpanElement>;
 }
 /**
  * Loading placeholder. aria-hidden — the loading announcement belongs to the
@@ -493,7 +555,11 @@ interface ProgressBarProps extends HTMLAttributes<HTMLDivElement> {
     value?: number;
     /** Accessible name — required. A bare bar announces nothing useful. */
     label: string;
+    /** What the bar has got through, in words — "2.1 MB of 5 MB". Read instead
+        of the percentage, which is not always what the number means. */
+    valueText?: string;
     indeterminate?: boolean;
+    ref?: Ref<HTMLDivElement>;
 }
 /**
  * Determinate or indeterminate progress track.
@@ -503,7 +569,7 @@ interface ProgressBarProps extends HTMLAttributes<HTMLDivElement> {
  * <ProgressBar label="Syncing" indeterminate />
  * ```
  */
-declare function ProgressBar({ value, label, indeterminate, className, style, ...rest }: ProgressBarProps): ReactElement;
+declare function ProgressBar({ value, label, valueText, indeterminate, className, style, ...rest }: ProgressBarProps): ReactElement;
 
 interface FieldContextValue {
     /** Control id — the label points here. */
@@ -563,18 +629,25 @@ interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size">
  */
 declare function Input({ size, invalid, iconLeft, iconRight, className, ...rest }: InputProps): ReactElement;
 
-type PasswordInputProps = Omit<InputProps, "type">;
+interface PasswordInputProps extends Omit<InputProps, "type"> {
+    /** Names the reveal button while the password is hidden, e.g. "Show password".
+        Required: the button carries no visible text, so this is the only thing a
+        screen reader has, and it is the app's language rather than the system's. */
+    showLabel: string;
+    /** Names the same button while the password is visible, e.g. "Hide password". */
+    hideLabel: string;
+}
 /**
  * Password field with a reveal toggle. Composes Input, so inside a Field it
  * inherits id/description/invalid the same way.
  *
  * ```tsx
  * <Field label="Password" hint="At least 12 characters">
- *   <PasswordInput autoComplete="new-password" />
+ *   <PasswordInput showLabel="Show password" hideLabel="Hide password" autoComplete="new-password" />
  * </Field>
  * ```
  */
-declare function PasswordInput({ className, ...rest }: PasswordInputProps): ReactElement;
+declare function PasswordInput({ showLabel, hideLabel, className, ...rest }: PasswordInputProps): ReactElement;
 
 interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
     /** Character counter under the control; pairs with native maxLength. */
@@ -684,6 +757,7 @@ interface SegmentOption<T extends string = string> {
     value: T;
     label: string;
 }
+type SegmentedControlSize = "sm" | "md";
 interface SegmentedControlProps<T extends string = string> {
     /** Accessible group name. */
     label: string;
@@ -695,6 +769,14 @@ interface SegmentedControlProps<T extends string = string> {
     /** Stretch across the container, segments sharing the width equally —
         the usual shape when the control heads a screen-wide view switch. */
     fullWidth?: boolean;
+    /** Control step. Default md. sm is for chrome — a switch sharing a header
+        bar with an avatar and a menu, where the medium step is the tallest
+        thing up there. */
+    size?: SegmentedControlSize;
+    /** Drop the frame: no tray, no padding around the segments. The tray is
+        what makes the group read as a form field, and in a header bar a field
+        is what it is not. The chosen segment still carries its own surface. */
+    bare?: boolean;
     className?: string;
 }
 /**
@@ -713,11 +795,14 @@ interface SegmentedControlProps<T extends string = string> {
  * />
  * ```
  */
-declare function SegmentedControl<T extends string = string>({ label, options, value, onChange, disabled, fullWidth, className, }: SegmentedControlProps<T>): ReactElement;
+declare function SegmentedControl<T extends string = string>({ label, options, value, onChange, disabled, fullWidth, size, bare, className, }: SegmentedControlProps<T>): ReactElement;
 
 interface SearchFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "value" | "onChange"> {
     /** Accessible name. */
     label: string;
+    /** Names the clear button, e.g. "Clear search". Required: the button is a
+        glyph, so this is all a screen reader has, and the words are the app's. */
+    clearLabel: string;
     value: string;
     /** Receives the new text — "" when cleared. */
     onChange: (value: string) => void;
@@ -727,15 +812,16 @@ interface SearchFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "
  * Controlled search input with a clear affordance once there is text.
  *
  * ```tsx
- * <SearchField label="Search sessions" value={query} onChange={setQuery} />
+ * <SearchField label="Search sessions" clearLabel="Clear search" value={query} onChange={setQuery} />
  * ```
  */
-declare function SearchField({ label, value, onChange, className, ...rest }: SearchFieldProps): ReactElement;
+declare function SearchField({ label, clearLabel, value, onChange, className, ...rest }: SearchFieldProps): ReactElement;
 
 interface ListGroupProps extends HTMLAttributes<HTMLUListElement> {
     children: ReactNode;
     /** Heading over the group. Also names the list to a screen reader. */
     label?: ReactNode;
+    ref?: Ref<HTMLUListElement>;
 }
 /**
  * Card-styled list container for ListItems.
@@ -769,6 +855,8 @@ interface ListItemProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "onC
     pressed?: boolean;
     /** Makes the whole row a link. Wins over onClick. */
     href?: string;
+    /** Element override for that link, e.g. a router's Link. */
+    as?: ElementType;
     /** What the row paints behind itself. Inside a ListGroup the group is the
         card, so grouped rows default to painting nothing; standalone rows
         default to their own card. `accent` is the tinted, accent-edged prompt
@@ -776,12 +864,15 @@ interface ListItemProps extends Omit<HTMLAttributes<HTMLElement>, "title" | "onC
         brings its own corner radius, which peeks past the row's in all four
         corners. */
     surface?: ListItemSurface;
+    /** The root is an `<li>` inside a ListGroup and a `<div>` outside one, so
+        the ref is typed to what both are. */
+    ref?: Ref<HTMLElement>;
 }
 /**
  * One row. Static by default; interactive as one whole-row button/link.
  * An `<li>` inside a ListGroup, a standalone `<div>` row anywhere else.
  */
-declare function ListItem({ title, description, leading, trailing, onClick, pressed, href, surface, className, ...rest }: ListItemProps): ReactElement;
+declare function ListItem({ title, description, leading, trailing, onClick, pressed, href, as, surface, className, ref, ...rest }: ListItemProps): ReactElement;
 
 interface EmptyStateProps {
     title: string;
@@ -830,26 +921,42 @@ interface TabListProps extends HTMLAttributes<HTMLDivElement> {
     /** Accessible name for the tab set. */
     label: string;
     children: ReactNode;
+    ref?: Ref<HTMLDivElement>;
 }
 declare function TabList({ label, className, children, ...rest }: TabListProps): ReactElement;
 interface TabProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" | "type"> {
     value: string;
     children: ReactNode;
+    ref?: Ref<HTMLButtonElement>;
 }
 declare function Tab({ value, className, children, ...rest }: TabProps): ReactElement;
 interface TabPanelProps extends HTMLAttributes<HTMLDivElement> {
     value: string;
     children: ReactNode;
+    ref?: Ref<HTMLDivElement>;
 }
 declare function TabPanel({ value, className, children, ...rest }: TabPanelProps): ReactElement;
 
 type ToastTone = "neutral" | "success" | "danger";
+interface ToastAction {
+    /** The word on the button — localise. */
+    label: string;
+    onClick: () => void;
+}
 interface ToastOptions {
     title: string;
     description?: string | undefined;
     tone?: ToastTone | undefined;
     /** ms until auto-dismiss. 0 = stays until dismissed. Default 5000. */
     duration?: number | undefined;
+    /** One thing to do about the message, beside it. A toast that asks for
+        something — "Update ready", "Add to home screen" — has nowhere else to
+        put the doing. Taking it closes the toast: the message is answered. */
+    action?: ToastAction | undefined;
+    /** Fires however the toast leaves — timeout, dismiss button, or action.
+        A nudge that must remember a refusal has one place to write it down,
+        rather than three that can disagree. */
+    onDismiss?: (() => void) | undefined;
 }
 interface ToastContextValue {
     toast: (options: ToastOptions) => number;
@@ -858,19 +965,19 @@ interface ToastContextValue {
 declare function useToast(): ToastContextValue;
 interface ToastProviderProps {
     children: ReactNode;
-    /** Accessible name of the notification region (localise). Default "Notifications". */
-    regionLabel?: string | undefined;
-    /** Prefix of each dismiss button's accessible name (localise). The toast's
-     *  title follows it, so every dismiss control names its own toast. Default
-     *  "Dismiss" — a button labelled "Dismiss: Saved". */
-    dismissLabel?: string | undefined;
+    /** Accessible name of the notification region, e.g. "Notifications".
+        Required: it is read aloud, in the app's language. */
+    regionLabel: string;
+    /** Prefix of each dismiss button's accessible name. The toast's title follows
+     *  it, so every dismiss control names its own toast: "Dismiss: Saved". */
+    dismissLabel: string;
 }
 /**
  * Mount once near the root. Renders the notification region itself.
  *
  * ```tsx
  * // App root
- * <ToastProvider>
+ * <ToastProvider regionLabel="Notifications" dismissLabel="Dismiss">
  *   <App />
  * </ToastProvider>
  *
@@ -963,6 +1070,11 @@ interface CardProps extends Omit<HTMLAttributes<HTMLElement>, "onClick"> {
     onClick?: () => void;
     /** Makes the whole card a link. Wins over onClick. */
     href?: string;
+    /** Element override for that link, e.g. a router's Link. */
+    as?: ElementType;
+    /** The root is an `<a>`, a `<button>` or a `<div>` depending on the props,
+        so the ref is typed to what all three are. */
+    ref?: Ref<HTMLElement>;
 }
 /**
  * Surface container. Compose with CardHeader/CardBody/CardFooter — the card
@@ -978,8 +1090,10 @@ interface CardProps extends Omit<HTMLAttributes<HTMLElement>, "onClick"> {
  * <Card href="/items/42" variant="flat">…</Card>
  * ```
  */
-declare function Card({ children, variant, emphasis, onClick, href, className, ...rest }: CardProps): ReactElement;
-type CardSectionProps = HTMLAttributes<HTMLDivElement>;
+declare function Card({ children, variant, emphasis, onClick, href, as, className, ref, ...rest }: CardProps): ReactElement;
+type CardSectionProps = HTMLAttributes<HTMLDivElement> & {
+    ref?: Ref<HTMLDivElement>;
+};
 /** Top slot — title row, media, tabs. */
 declare function CardHeader({ className, ...rest }: CardSectionProps): ReactElement;
 /** Main content slot. */
@@ -1084,8 +1198,9 @@ interface ConfirmDialogProps<T = void> {
     /** Consequence explained in a sentence or two. */
     description?: ReactNode;
     confirmLabel: string;
-    /** @default "Cancel" */
-    cancelLabel?: string;
+    /** Names the way out, e.g. "Cancel". Required: it is a button with words on
+        it, and the words are the app's. */
+    cancelLabel: string;
     /** Styles the confirm action: danger for destructive, warning for
         consequential-but-recoverable. */
     tone?: ConfirmDialogTone;
@@ -1111,6 +1226,7 @@ interface ConfirmDialogProps<T = void> {
  *   title="Delete session?"
  *   description="This cannot be undone."
  *   confirmLabel="Delete"
+ *   cancelLabel="Cancel"
  *   tone="danger"
  * />
  * ```
@@ -1150,7 +1266,7 @@ interface ScreenContentProps extends HTMLAttributes<HTMLElement> {
 /** The scrollable main region of a Screen. */
 declare function ScreenContent({ children, flush, className, ref, ...rest }: ScreenContentProps): react.JSX.Element;
 
-interface AppBarProps {
+interface AppBarProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
     /** Page heading — rendered as the h1. A node is allowed for titles that
         are themselves a control (e.g. a thread title that opens the event). */
     title?: ReactNode;
@@ -1161,6 +1277,7 @@ interface AppBarProps {
     leading?: ReactNode;
     /** Right slot — actions. */
     trailing?: ReactNode;
+    ref?: Ref<HTMLElement>;
 }
 /**
  * Top app bar. Sticky, one per screen; the title is the page h1.
@@ -1176,7 +1293,7 @@ interface AppBarProps {
  * />
  * ```
  */
-declare function AppBar({ title, subtitle, leading, trailing }: AppBarProps): react.JSX.Element;
+declare function AppBar({ title, subtitle, leading, trailing, className, ref, ...rest }: AppBarProps): react.JSX.Element;
 
 interface TabBarProps {
     /** Accessible name of the navigation landmark. */
@@ -1205,8 +1322,16 @@ interface TabBarItemProps {
     /** Attention dot on the icon — unread, pending. Boolean only: the count
         lives on the destination screen, the bar just says "something's there". */
     badge?: boolean | undefined;
+    /** Element override for the link, e.g. a router's Link. A bottom bar is
+        where a full page reload costs the most — it restarts the whole shell. */
+    as?: ElementType;
+    /** Take the caption off the screen and leave it in the accessible name.
+        For a bar whose glyphs carry the meaning: four captions on the narrowest
+        phone wrap, and a translation twice the length of the English wraps
+        everywhere. Hidden, never dropped — the word is the item's name. */
+    hideLabel?: boolean | undefined;
 }
-declare function TabBarItem({ label, icon, href, onClick, active, badge }: TabBarItemProps): react.JSX.Element;
+declare function TabBarItem({ label, icon, href, onClick, active, badge, as, hideLabel, }: TabBarItemProps): react.JSX.Element;
 interface TabBarActionProps {
     /** Names the action — icon-only, so this is all a screen reader gets. */
     label: string;
@@ -1217,6 +1342,289 @@ interface TabBarActionProps {
     it is a peer child, and the bar's flex layout leaves it its own width. */
 declare function TabBarAction({ label, icon, onClick }: TabBarActionProps): react.JSX.Element;
 
+interface MediaPlaceholderProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** CSS aspect-ratio for the box, e.g. "4 / 5". Default 16 / 9. */
+    aspect?: string;
+    /** Picture to draw. Absent, or broken, leaves the empty surface showing. */
+    src?: string;
+    /** Describes the picture. Empty = decorative, which is the honest default:
+        a file name is not a description. */
+    alt?: string;
+    /** Glyph for the empty surface — an <Icon> or any node. */
+    glyph?: ReactNode;
+    /** A few words under the glyph, or over the picture. */
+    caption?: string;
+    /** Obscures the media without hiding that there is media. */
+    blurred?: boolean;
+    /** Drawn over the surface, outside the blur — a reveal prompt, a badge, a
+        play button. The consent vocabulary that usually goes here belongs to the
+        app, so the system takes it as a node and asks no questions about it. */
+    cover?: ReactNode;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * The box a picture goes in, whether or not there is one yet.
+ *
+ * ```tsx
+ * <MediaPlaceholder
+ *   aspect="4 / 5"
+ *   src={post.media.src}
+ *   alt={post.media.alt}
+ *   blurred={!revealed}
+ *   cover={post.sensitive && <SensitiveMediaOverlay onReveal={reveal} />}
+ * />
+ * ```
+ */
+declare function MediaPlaceholder({ aspect, src, alt, glyph, caption, blurred, cover, className, style, ...rest }: MediaPlaceholderProps): ReactElement;
+
+interface CarouselSlide {
+    id: string;
+    src?: string;
+    alt?: string;
+    /** CSS aspect-ratio for this frame. Default 4 / 3. */
+    aspect?: string;
+    caption?: string;
+    /** Obscures the frame and takes away the way into it: a covered frame does
+        not open larger, however it is tapped. */
+    covered?: boolean;
+    /** Drawn over the frame, outside the blur — whatever the app asks consent
+        with. */
+    cover?: ReactNode;
+}
+type CarouselPager = "thumbnails" | "dots" | "none";
+interface ImageCarouselLabels {
+    /** Names the carousel landmark, e.g. "Images". */
+    region: string;
+    /** Read out in place of "region", e.g. "carousel". A screen reader says it
+        aloud, so it is the app's word in the app's language. */
+    carouselRole: string;
+    /** The same for one frame, e.g. "slide". */
+    slideRole: string;
+    previous: string;
+    next: string;
+    /** "3 of 8" — a function, because only the app knows how its language counts. */
+    counter: (current: number, total: number) => string;
+    /** Names one frame's thumbnail or dot, e.g. "Image 3". */
+    slide: (position: number) => string;
+    /** Names the button standing for the frames no thumbnail fits. */
+    more: (hidden: number) => string;
+}
+type ImageCarouselProps = Omit<HTMLAttributes<HTMLElement>, "children" | "onChange"> & {
+    slides: CarouselSlide[];
+    labels: ImageCarouselLabels;
+    /** Held index. Unset, the carousel keeps its own. */
+    index?: number;
+    defaultIndex?: number;
+    onIndexChange?: (index: number) => void;
+    pager?: CarouselPager;
+    maxThumbnails?: number;
+    ref?: Ref<HTMLElement>;
+} & ({
+    /** Called with the frame to open larger — by the control, or by a tap
+        on the frame itself. */
+    onZoom: (index: number) => void;
+    /** Glyph for that control, from the app's icon set. */
+    zoomIcon: ReactNode;
+    zoomLabel: string;
+} | {
+    onZoom?: undefined;
+    zoomIcon?: undefined;
+    zoomLabel?: undefined;
+});
+/**
+ * A gallery of frames, one on show.
+ *
+ * ```tsx
+ * <ImageCarousel
+ *   slides={post.images.map((image) => ({ ...image, covered: !revealed }))}
+ *   labels={t.gallery}
+ *   onZoom={openLightbox}
+ *   zoomIcon={<Icon name="zoom-in" />}
+ *   zoomLabel={t.viewLarger}
+ * />
+ * ```
+ */
+declare function ImageCarousel({ slides, labels, index, defaultIndex, onIndexChange, pager, maxThumbnails, onZoom, zoomIcon, zoomLabel, className, ...rest }: ImageCarouselProps): ReactElement | null;
+
+type UploadStatus = "uploading" | "processing" | "done" | "error";
+interface UploadProgressLabels {
+    /** Names the bar while bytes are moving, and the state after. */
+    uploading: string;
+    processing: string;
+    done: string;
+    /** Shown when the caller has no more specific `error` to give. */
+    error: string;
+    cancel: string;
+    retry: string;
+    remove: string;
+}
+interface UploadProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The file, as the person who picked it would name it. */
+    name: string;
+    labels: UploadProgressLabels;
+    /** Thumbnail of what is going up — an `<img>`, a `<video>`, anything. */
+    preview?: ReactNode;
+    /** Glyph for the state it ended in, from the app's icon set. Tinted by the
+        status: the system says which state, the app says with what glyph. */
+    mark?: ReactNode;
+    /** 0–100. Ignored while processing, which reports no percentage. */
+    value?: number;
+    status?: UploadStatus;
+    /** The progress in words — "2.1 MB of 5 MB". Read out instead of the
+        percentage, and shown under the bar. */
+    detail?: string;
+    /** Why it failed. Falls back to `labels.error`. */
+    error?: string;
+    onCancel?: () => void;
+    onRetry?: () => void;
+    onRemove?: () => void;
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * One file on its way up: what it is, how far it has got, and the way out.
+ *
+ * ```tsx
+ * <UploadProgress
+ *   name={file.name}
+ *   status={upload.status}
+ *   value={upload.percent}
+ *   detail={`${sent} of ${total}`}
+ *   onCancel={upload.abort}
+ *   labels={t.upload}
+ * />
+ * ```
+ */
+declare function UploadProgress({ name, labels, preview, mark, value, status, detail, error, onCancel, onRetry, onRemove, className, ...rest }: UploadProgressProps): ReactElement;
+
+interface LightboxLabels {
+    /** Names the dialog itself, e.g. "Image". */
+    dialog: string;
+    close: string;
+    zoomIn: string;
+    zoomOut: string;
+}
+interface LightboxProps {
+    open: boolean;
+    onClose: () => void;
+    src: string;
+    /** Empty says the picture is decoration — rare here, where it is the point. */
+    alt?: string;
+    caption?: string;
+    labels: LightboxLabels;
+}
+/**
+ * One picture, full screen, zoomable and pannable. Escape and the focus trap
+ * come from the overlay shell; the gestures are the component's own.
+ *
+ * ```tsx
+ * <Lightbox
+ *   open={shown !== null}
+ *   onClose={() => setShown(null)}
+ *   src={shown?.src ?? ""}
+ *   alt={shown?.alt ?? ""}
+ *   labels={{ dialog: t("image"), close: t("close"), zoomIn: t("zoomIn"), zoomOut: t("zoomOut") }}
+ * />
+ * ```
+ */
+declare function Lightbox({ open, onClose, src, alt, caption, labels }: LightboxProps): react.JSX.Element;
+
+interface VideoChapter {
+    /** Where the chapter starts, in seconds. */
+    at: number;
+    label: string;
+}
+interface VideoCaptions {
+    src: string;
+    lang: string;
+    /** Shown in the browser's own track menu, so it is the app's word. */
+    label: string;
+    defaultOn?: boolean;
+}
+interface VideoPlayerLabels {
+    /** Names the player itself, e.g. "Hip harness, slowly". */
+    region: string;
+    play: string;
+    pause: string;
+    mute: string;
+    unmute: string;
+    fullscreen: string;
+    exitFullscreen: string;
+    seek: string;
+}
+type Chaptered = {
+    chapters: VideoChapter[];
+    chaptersLabel: string;
+    onChapterSelect?: (at: number) => void;
+} | {
+    chapters?: undefined;
+    chaptersLabel?: undefined;
+    onChapterSelect?: undefined;
+};
+type Captioned = {
+    captions: VideoCaptions;
+    captionsLabel: string;
+} | {
+    captions?: undefined;
+    captionsLabel?: undefined;
+};
+type VideoPlayerProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+    src: string;
+    poster?: string;
+    labels: VideoPlayerLabels;
+    autoPlay?: boolean;
+    /** Obscures the picture and takes away the way into it — the cover is the
+        only way in while this is set. */
+    covered?: boolean;
+    /** Drawn over the picture, outside the blur: whatever asks to be let past. */
+    cover?: ReactNode;
+    ref?: Ref<HTMLElement>;
+} & Chaptered & Captioned;
+/**
+ * A video with its own transport: play, seek, sound, captions, fullscreen and
+ * chapters. The picture can be covered — `covered` obscures it and `cover`
+ * holds whatever asks to be let past, which is the app's to write.
+ *
+ * ```tsx
+ * <VideoPlayer
+ *   src={video.url}
+ *   poster={video.posterUrl}
+ *   labels={{ region: t("video.of", { title }), play: t("video.play"), … }}
+ *   chapters={chapters}
+ *   chaptersLabel={t("video.chapters")}
+ * />
+ * ```
+ */
+declare function VideoPlayer({ src, poster, labels, chapters, chaptersLabel, onChapterSelect, captions, captionsLabel, autoPlay, covered, cover, className, ref, ...rest }: VideoPlayerProps): ReactElement;
+
+interface Crumb {
+    label: string;
+    /** Absent = not a link. The last step never links, wherever it points. */
+    href?: string;
+}
+interface BreadcrumbProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** The trail, root first. The last item is where the reader is. */
+    items: Crumb[];
+    /** Names the landmark, e.g. "Breadcrumb". Required: a page can hold several
+        navigation landmarks, and the words are the app's. */
+    label: string;
+    /** Element the links render as, e.g. a router's Link. */
+    linkAs?: ElementType;
+    ref?: Ref<HTMLElement>;
+}
+/**
+ * The trail back up. A navigation landmark holding an ordered list, with the
+ * current page as its last, unlinked step.
+ *
+ * ```tsx
+ * <Breadcrumb
+ *   label={t("nav.breadcrumb")}
+ *   linkAs={RouterLink}
+ *   items={[{ label: "Library", href: "/library" }, { label: "Kihon" }]}
+ * />
+ * ```
+ */
+declare function Breadcrumb({ items, label, linkAs, className, ...rest }: BreadcrumbProps): ReactElement | null;
+
 interface UseOverlayOptions {
     open: boolean;
     onClose: () => void;
@@ -1297,4 +1705,4 @@ interface RovingGroupOptions {
  */
 declare function useRovingGroup(ref: RefObject<HTMLElement | null>, { selector, orientation }: RovingGroupOptions): (event: KeyboardEvent<HTMLElement>) => void;
 
-export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogTone, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, type ScreenContentProps, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarAction, type TabBarActionProps, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, type UseOverlayOptions, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };
+export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Breadcrumb, type BreadcrumbProps, Button, type ButtonProps, type ButtonShape, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, type CarouselPager, type CarouselSlide, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, type ConfirmDialogTone, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, type Crumb, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, ImageCarousel, type ImageCarouselLabels, type ImageCarouselProps, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Lightbox, type LightboxLabels, type LightboxProps, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, MediaPlaceholder, type MediaPlaceholderProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, type ScreenContentProps, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, type SegmentedControlSize, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarAction, type TabBarActionProps, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastAction, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, UploadProgress, type UploadProgressLabels, type UploadProgressProps, type UploadStatus, type UseOverlayOptions, type VideoCaptions, type VideoChapter, VideoPlayer, type VideoPlayerLabels, type VideoPlayerProps, VisuallyHidden, type VisuallyHiddenProps, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };