@rio-m3e/core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,44 @@
+/**
+ * The attributes of one part of a component's markup, in HTML form: names as HTML spells them
+ * (`class`, `aria-pressed`, `data-size`) and string values, with `undefined` leaving an attribute
+ * out. Each component's `parts` returns one of these per part. See "Core output" in
+ * `docs/conventions.md`.
+ */
+export type PartAttrs = Record<string, string | undefined>;
+/**
+ * An event a component's handler (`handleClick`) takes: a DOM event, or a framework's own, such
+ * as React's synthetic events. Core only cancels it, and hands the same event back to the adapter
+ * (`onClick`), so components are generic over its type, with `MouseEvent` as the default.
+ */
+export interface CancelableEvent {
+  preventDefault(): void;
+}
+/**
+ * One node of a component's skeleton: the markup an adapter renders, part by part. Adapters
+ * render it their own way; contract tests check what they rendered against it. Each component
+ * exports its skeleton (`buttonSkeleton`, `switchSkeleton`, ...).
+ *
+ * `Part` narrows the names to the component's parts, so a typo fails the build. `When` lists the
+ * decisions the skeleton may use; leave it out when every part always renders. Skeletons are
+ * shared objects, so everything is read-only.
+ */
+export interface PartNode<Part extends string = string, When extends string = never> {
+  /** The part, named as in the component's `parts`. */
+  readonly part: Part;
+  /** The element the part is, as `tagName` in lower case. */
+  readonly tag: keyof HTMLElementTagNameMap;
+  /**
+   * The component API's decision that says whether the part renders, such as `'showsIcon'`.
+   * Without it, the part always renders.
+   */
+  readonly when?: When;
+  /**
+   * Content from the app (slots, children) goes inside. The content itself isn't checked against
+   * the skeleton; where a component picks between contents, its contract test checks the pick.
+   */
+  readonly content?: true;
+  readonly children?: readonly PartNode<Part, When>[];
+}
 export declare const BUTTON_VARIANTS: readonly ["filled", "tonal", "outlined", "elevated", "text"];
 export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
 /** M3E button sizes. `small` is the default. */
@@ -28,6 +69,11 @@ export interface ButtonProps {
   softDisabled?: boolean;
   /** Defaults to `'button'`, so a button inside a form doesn't submit it by accident. */
   type?: 'button' | 'submit' | 'reset';
+  /**
+   * Identifies the button inside a button group that keeps a selection. Such a group makes the
+   * button a toggle and decides whether it is selected.
+   */
+  value?: ButtonGroupValue;
 }
 export declare const buttonDefaults: {
   variant: "filled";
@@ -39,20 +85,202 @@ export declare const buttonDefaults: {
   softDisabled: false;
   type: "button";
 };
-export interface ButtonOptions {
+/** What the adapter has to put in the button, which only the adapter can see. */
+export interface ButtonContent {
+  /** Whether there is a leading icon. */
+  icon: boolean;
+}
+export interface ButtonOptions<E extends CancelableEvent = MouseEvent> {
   /** Returns the current prop values. The adapter owns the state. */
   props: () => ButtonProps;
-  /** Called for a click that isn't blocked. */
-  onClick: (event: MouseEvent) => void;
-  /** Called after an unblocked click on a toggle button, with the new value. */
-  onSelectedChange: (selected: boolean) => void;
+  /** Returns what content the adapter has. Without it, the button has no icon. */
+  content?: () => ButtonContent;
+  /** Called for a click that isn't blocked, with the event `handleClick` got. */
+  onClick: (event: E) => void;
+  /** Called after an unblocked click on a toggle button, with the requested value. */
+  onChange: (selected: boolean) => void;
+}
+/**
+ * The button's markup, part by part. `buttonSkeleton` says how the adapter nests them.
+ */
+export interface ButtonParts {
+  root: () => PartAttrs;
+  /** Extends small buttons to the 48px target. */
+  touch: () => PartAttrs;
+  icon: () => PartAttrs;
+  label: () => PartAttrs;
 }
-export interface ButtonApi {
-  rootAttrs: () => Record<string, string | undefined>;
+/** How the adapter renders the button's parts. The icon holds the leading icon. */
+export declare const buttonSkeleton: PartNode<keyof ButtonParts, 'showsIcon'>;
+export interface ButtonApi<E extends CancelableEvent = MouseEvent> {
+  parts: ButtonParts;
+  /** Whether to render the icon part. */
+  showsIcon: () => boolean;
   /** Attach to the root element's `click`. */
-  handleClick: (event: MouseEvent) => void;
+  handleClick: (event: E) => void;
+}
+export declare function createButton<E extends CancelableEvent = MouseEvent>(options: ButtonOptions<E>): ButtonApi<E>;
+/**
+ * M3E button group variants. A standard group spaces its buttons and lets a pressed button push
+ * its neighbors; a connected group joins them with 2px gaps and shared corners, and fills the
+ * width it is given.
+ */
+export declare const BUTTON_GROUP_VARIANTS: readonly ["standard", "connected"];
+export type ButtonGroupVariant = (typeof BUTTON_GROUP_VARIANTS)[number];
+/** Whether the group's buttons can be selected: none, one at a time, or any number. */
+export declare const BUTTON_GROUP_SELECTIONS: readonly ["none", "single", "multiple"];
+export type ButtonGroupSelection = (typeof BUTTON_GROUP_SELECTIONS)[number];
+/** Identifies a button inside a selecting group, through its `value` prop. */
+export type ButtonGroupValue = string | number;
+/** The selected value for `single` (or `undefined`), or the selected values for `multiple`. */
+export type ButtonGroupSelected = ButtonGroupValue | ButtonGroupValue[] | undefined;
+export interface ButtonGroupProps {
+  /** Defaults to `'standard'`. */
+  variant?: ButtonGroupVariant;
+  /** The size of every button in the group that doesn't set its own. Defaults to `'small'`. */
+  size?: ButtonSize;
+  /** The shape of every button in the group that doesn't set its own. Defaults to `'round'`. */
+  shape?: ButtonShape;
+  /**
+   * Turns buttons that have a `value` into toggle buttons whose selection the group keeps.
+   * Defaults to `'none'`, where every button acts on its own.
+   */
+  selection?: ButtonGroupSelection;
+  /** With a selection, keeps at least one button selected: the last one can't be turned off. */
+  required?: boolean;
+  /** The selected value (`single`) or values (`multiple`). */
+  selected?: ButtonGroupSelected;
+}
+export declare const buttonGroupDefaults: {
+  variant: "standard";
+  size: "small";
+  shape: "round";
+  selection: "none";
+  required: false;
+};
+export interface ButtonGroupOptions {
+  /** Returns the current prop values. The adapter owns the state. */
+  props: () => ButtonGroupProps;
+  /** Called with the requested selection. Adapters wire it to v-model, a callback prop, and so on. */
+  onChange: (selected: ButtonGroupSelected) => void;
+}
+/**
+ * The button group's markup. `buttonGroupSkeleton` says how the adapter renders it.
+ */
+export interface ButtonGroupParts {
+  root: () => PartAttrs;
+}
+/** How the adapter renders the button group: one root, with the buttons as its direct children. */
+export declare const buttonGroupSkeleton: PartNode<keyof ButtonGroupParts>;
+export interface ButtonGroupApi {
+  parts: ButtonGroupParts;
+  /** The size for buttons that don't set their own, with the default filled in. */
+  size: () => ButtonSize;
+  /** The shape for buttons that don't set their own, with the default filled in. */
+  shape: () => ButtonShape;
+  /** The selection mode, with the default filled in. */
+  selection: () => ButtonGroupSelection;
+  /** Whether the button with this value is selected. */
+  isSelected: (value: ButtonGroupValue) => boolean;
+  /**
+   * Requests turning the button with this value on or off. The group applies its selection rules:
+   * a single selection turns the previous button off, and `required` keeps the last one on.
+   */
+  select: (value: ButtonGroupValue, selected: boolean) => void;
+}
+export declare function createButtonGroup(options: ButtonGroupOptions): ButtonGroupApi;
+export interface ButtonGroupInteractionOptions {
+  /**
+   * How much wider a pressed button gets, as a share of its width. Each neighbor gives up at most
+   * the same share of its own width. Defaults to 0.15, the spec's 15%.
+   */
+  pressedWidthRatio?: number;
+}
+export interface ButtonGroupHandle {
+  detach(): void;
+}
+export declare function attachButtonGroup(root: HTMLElement, options?: ButtonGroupInteractionOptions): ButtonGroupHandle;
+/**
+ * The dialog's ARIA role: `alertdialog` for a prompt that asks for a response, such as a
+ * confirmation, and `dialog` for one that holds a list or a form.
+ */
+export declare const DIALOG_ROLES: readonly ["alertdialog", "dialog"];
+export type DialogRole = (typeof DIALOG_ROLES)[number];
+export interface DialogProps {
+  /** Whether the dialog is shown. */
+  open?: boolean;
+  /** Defaults to `'alertdialog'`. */
+  role?: DialogRole;
+}
+export declare const dialogDefaults: {
+  open: false;
+  role: "alertdialog";
+};
+/** What the adapter has to put in the dialog, which only the adapter can see. */
+export interface DialogContent {
+  /** An icon above the headline */
+  icon: boolean;
+  headline: boolean;
+  /** Buttons below the content */
+  actions: boolean;
+}
+export interface DialogOptions {
+  props: () => DialogProps;
+  /** Without it, the dialog has only its content. */
+  content?: () => DialogContent;
+  /** Ids for the parts the dialog refers to, unique in the document. The adapter makes them. */
+  ids: {
+    headline: string;
+    content: string;
+  };
 }
-export declare function createButton(options: ButtonOptions): ButtonApi;
+export interface DialogParts {
+  /** The `<dialog>`, shown in the top layer */
+  root: () => PartAttrs;
+  /** Holds the icon, which only decorates: the headline says what the dialog is for. */
+  icon: () => PartAttrs;
+  headline: () => PartAttrs;
+  /** Holds the supporting text, or a list or a form. It scrolls when it doesn't fit. */
+  content: () => PartAttrs;
+  /** Holds the buttons. */
+  actions: () => PartAttrs;
+}
+type DialogPart = keyof DialogParts;
+type DialogWhen = 'showsIcon' | 'showsHeadline' | 'showsActions';
+/**
+ * The markup of an open dialog. The parts inside render from opening until `attachDialog`'s
+ * `onClosed`; a closed dialog is the empty `<dialog>`.
+ */
+export declare const dialogSkeleton: PartNode<DialogPart, DialogWhen>;
+export interface DialogApi extends Record<DialogWhen, () => boolean> {
+  parts: DialogParts;
+}
+export declare function createDialog(options: DialogOptions): DialogApi;
+/** What asks the dialog to close: Escape (or the back gesture), or a click on the scrim */
+export type DialogCancelReason = 'escape' | 'scrim';
+export interface DialogCancelEvent extends CancelableEvent {
+  readonly reason: DialogCancelReason;
+  readonly defaultPrevented: boolean;
+}
+export interface DialogDomOptions {
+  /** Escape or a click on the scrim asks to close. Canceling the event keeps the dialog open. */
+  onCancel?: (event: DialogCancelEvent) => void;
+  /** The dialog closes on its own, or is asked to and isn't kept open. The adapter sets `open`. */
+  onOpenChange: (open: boolean) => void;
+  /**
+   * The dialog finished closing, its motion included, and hasn't opened again since. The adapter
+   * renders the content from opening until then.
+   */
+  onClosed?: () => void;
+}
+export interface DialogDomHandle {
+  /** Brings the dialog in line with `open`. Call it once attached, and whenever `open` changes. */
+  sync(open: boolean): void;
+  /** Call it after the content changed, to update the dividers. */
+  update(): void;
+  detach(): void;
+}
+export declare function attachDialog(root: HTMLDialogElement, options: DialogDomOptions): DialogDomHandle;
 export declare const ICON_BUTTON_VARIANTS: readonly ["filled", "tonal", "outlined", "standard"];
 export type IconButtonVariant = (typeof ICON_BUTTON_VARIANTS)[number];
 /** M3E icon button widths. `default` makes a square (or circle) as wide as it is tall. */
@@ -82,6 +310,8 @@ export interface IconButtonProps {
   softDisabled?: boolean;
   /** Defaults to `'button'`, so it doesn't submit a form by accident. */
   type?: 'button' | 'submit' | 'reset';
+  /** Identifies the button inside a button group that keeps a selection, as on the button. */
+  value?: ButtonGroupValue;
 }
 export declare const iconButtonDefaults: {
   variant: "filled";
@@ -94,15 +324,327 @@ export declare const iconButtonDefaults: {
   softDisabled: false;
   type: "button";
 };
-export interface IconButtonOptions {
+/** What the adapter has to put in the icon button, which only the adapter can see. */
+export interface IconButtonContent {
+  /** Whether there is an icon for the selected state. */
+  selectedIcon: boolean;
+}
+export interface IconButtonOptions<E extends CancelableEvent = MouseEvent> {
   /** Returns the current prop values. The adapter owns the state. */
   props: () => IconButtonProps;
-  /** Called for a click that isn't blocked. */
-  onClick: (event: MouseEvent) => void;
-  /** Called after an unblocked click on a toggle button, with the new value. */
-  onSelectedChange: (selected: boolean) => void;
+  /** Returns what content the adapter has. Without it, there is no selected icon. */
+  content?: () => IconButtonContent;
+  /** Called for a click that isn't blocked, with the event `handleClick` got. */
+  onClick: (event: E) => void;
+  /** Called after an unblocked click on a toggle button, with the requested value. */
+  onChange: (selected: boolean) => void;
+}
+/**
+ * The icon button's markup, part by part. `iconButtonSkeleton` says how the adapter nests them.
+ */
+export interface IconButtonParts {
+  root: () => PartAttrs;
+  /** Extends small icon buttons to the 48px target. */
+  touch: () => PartAttrs;
+  icon: () => PartAttrs;
+}
+/**
+ * How the adapter renders the icon button's parts. The icon holds the selected icon when
+ * `showsSelectedIcon()`, otherwise the default one.
+ */
+export declare const iconButtonSkeleton: PartNode<keyof IconButtonParts>;
+export interface IconButtonApi<E extends CancelableEvent = MouseEvent> {
+  parts: IconButtonParts;
+  /** Whether the icon part shows the selected icon instead of the default one. */
+  showsSelectedIcon: () => boolean;
+  /** Attach to the root element's `click`. */
+  handleClick: (event: E) => void;
+}
+export declare function createIconButton<E extends CancelableEvent = MouseEvent>(options: IconButtonOptions<E>): IconButtonApi<E>;
+export type AnchoredSide = 'top' | 'bottom' | 'start' | 'end';
+export type AnchoredAlign = 'start' | 'center' | 'end';
+/** A point in viewport coordinates, such as a pointer event's `clientX` and `clientY`. */
+export interface AnchorPoint {
+  x: number;
+  y: number;
+}
+export interface AnchoredPositionOptions {
+  /** Returns the anchor. Placing is skipped while it returns nothing. */
+  anchor: () => Element | AnchorPoint | null | undefined;
+  /** The preferred side of the anchor. Defaults to `'bottom'`. */
+  side?: AnchoredSide;
+  /** Which edges line up along that side. Defaults to `'start'`. */
+  align?: AnchoredAlign;
+  /** Space between the anchor and the element, in px. Defaults to 0. */
+  offset?: number;
+  /**
+   * Moves the element along the anchor, in px, once lined up: down beside the anchor, toward the
+   * end of the line above or below it. Defaults to 0. A submenu uses it to line its first item up
+   * with the item that opened it.
+   */
+  alignOffset?: number;
+  /** Sides to try, in order, when the preferred one has no room. Defaults to the opposite side. */
+  fallbacks?: readonly AnchoredSide[];
+  /** Space kept from the edges of the window, in px. Defaults to 8. */
+  padding?: number;
+}
+export interface AnchoredPositionHandle {
+  /** Places the element now, for example after the anchor point moved. */
+  update(): void;
+  detach(): void;
+}
+export declare function attachAnchoredPosition(floating: HTMLElement, options: AnchoredPositionOptions): AnchoredPositionHandle;
+/** M3E vertical menu color styles: surface-based, or tertiary-based for more emphasis. */
+export declare const MENU_VARIANTS: readonly ["standard", "vibrant"];
+export type MenuVariant = (typeof MENU_VARIANTS)[number];
+/** Whether the menu's items can be selected: none, one at a time, or any number. */
+export declare const MENU_SELECTIONS: readonly ["none", "single", "multiple"];
+export type MenuSelection = (typeof MENU_SELECTIONS)[number];
+/** Identifies an item in a selecting menu, through its `value` prop. */
+export type MenuValue = string | number;
+/** The selected value for `single` (or `undefined`), or the selected values for `multiple`. */
+export type MenuSelected = MenuValue | MenuValue[] | undefined;
+export interface MenuProps {
+  /** Whether the menu is shown. */
+  open?: boolean;
+  /** Defaults to `'standard'`. */
+  variant?: MenuVariant;
+  /**
+   * Makes items with a `value` selectable, and keeps the selection. Defaults to `'none'`, where
+   * choosing an item only runs its action.
+   */
+  selection?: MenuSelection;
+  /** The selected value (`single`) or values (`multiple`). */
+  selected?: MenuSelected;
+  /** Names the menu for assistive technology, such as the label of the button that opens it. */
+  label?: string;
+  /** The side of the anchor it opens on, when there is room. Defaults to `'bottom'`. */
+  side?: AnchoredSide;
+  /** Which edges line up with the anchor's. Defaults to `'start'`. */
+  align?: AnchoredAlign;
+  /** Space between the anchor and the menu, in px. Defaults to 0; a split button's menu uses 4. */
+  offset?: number;
+  /** Opens and closes without the expanding motion, as dense desktop products may. */
+  instant?: boolean;
+}
+export declare const menuDefaults: {
+  open: false;
+  variant: "standard";
+  selection: "none";
+  side: "bottom";
+  align: "start";
+  offset: number;
+  instant: false;
+};
+export interface MenuOptions {
+  /** Returns the current prop values. The adapter owns the state. */
+  props: () => MenuProps;
+  /** Called with the requested selection. */
+  onChange: (selected: MenuSelected) => void;
+  /** Called with the requested `open`, such as `false` once an item is chosen. */
+  onOpenChange: (open: boolean) => void;
+}
+export interface MenuParts {
+  /** The surface, shown in the top layer. Its children are items, dividers, and groups. */
+  root: () => PartAttrs;
+}
+export declare const menuSkeleton: PartNode<keyof MenuParts>;
+export interface MenuApi {
+  parts: MenuParts;
+  /** The selection mode, with the default filled in. */
+  selection: () => MenuSelection;
+  /** Whether the item with this value is selected. */
+  isSelected: (value: MenuValue) => boolean;
+  /**
+   * An item was chosen. With a `value` in a selecting menu, the selection rules apply: `single`
+   * selects it, `multiple` toggles it. Then the menu asks to close, except for `multiple`, which
+   * stays open until dismissed.
+   */
+  choose: (value?: MenuValue) => void;
+  /** Asks the menu to close. In a submenu, the whole menu closes, as after a choice. */
+  close: () => void;
+  /** The color style, with the default filled in, which submenus take on. */
+  variant: () => MenuVariant;
+  /** Whether the menu opens without its motion, which submenus take on. */
+  instant: () => boolean;
+}
+export declare function createMenu(options: MenuOptions): MenuApi;
+export interface MenuItemProps {
+  /** Makes the item selectable in a menu that keeps a selection. */
+  value?: MenuValue;
+  /** Still focusable, but can't be chosen. */
+  disabled?: boolean;
+}
+export declare const menuItemDefaults: {
+  disabled: false;
+};
+/** What the adapter has to put in the item, which only the adapter can see. */
+export interface MenuItemContent {
+  /** A leading icon */
+  icon: boolean;
+  /** Supporting text under the label */
+  supportingText: boolean;
+  /** Trailing text, such as a keyboard shortcut */
+  trailingText: boolean;
+  /** A trailing icon */
+  trailingIcon: boolean;
+}
+export interface MenuItemOptions<E extends CancelableEvent = MouseEvent> {
+  props: () => MenuItemProps;
+  /** Without it, the item has only a label. */
+  content?: () => MenuItemContent;
+  /** The menu around the item. Without one, the item acts as in a menu without a selection. */
+  menu?: () => Pick<MenuApi, 'selection' | 'isSelected' | 'choose'> | undefined;
+  /**
+   * Called for a click on the item that isn't blocked, before the menu is told, with the event
+   * `handleClick` got.
+   */
+  onClick: (event: E) => void;
+  /**
+   * Makes it the item that opens a submenu (see `createSubMenu`): a click opens the submenu rather
+   * than choosing the item.
+   */
+  submenu?: {
+    /** Whether the submenu is open */
+    open: () => boolean;
+    /** Asks for the submenu to open. */
+    onOpen: () => void;
+  };
+}
+export interface MenuItemParts {
+  /** A `<button>` with the item's role */
+  root: () => PartAttrs;
+  /** Extends the 44px item to a 48px target, over the space between items. */
+  touch: () => PartAttrs;
+  icon: () => PartAttrs;
+  /** Holds the label and the supporting text, one above the other */
+  text: () => PartAttrs;
+  label: () => PartAttrs;
+  supportingText: () => PartAttrs;
+  trailingText: () => PartAttrs;
+  trailingIcon: () => PartAttrs;
+}
+type MenuItemWhen = 'showsIcon' | 'showsSupportingText' | 'showsTrailingText' | 'showsTrailingIcon';
+export declare const menuItemSkeleton: PartNode<keyof MenuItemParts, MenuItemWhen>;
+export interface MenuItemApi<E extends CancelableEvent = MouseEvent> extends Record<MenuItemWhen, () => boolean> {
+  parts: MenuItemParts;
+  /** Whether the item is selected, in a menu that keeps a selection. */
+  selected: () => boolean;
+  /** Attach to the item's `click`. */
+  handleClick: (event: E) => void;
 }
-export declare function createIconButton(options: IconButtonOptions): ButtonApi;
+export declare function createMenuItem<E extends CancelableEvent = MouseEvent>(options: MenuItemOptions<E>): MenuItemApi<E>;
+export interface SubMenuProps {
+  /** The label of the item that opens the submenu, which also names the submenu. */
+  label?: string;
+  /** The item stays focusable but doesn't open the submenu. */
+  disabled?: boolean;
+  /** As a menu's: a submenu keeps its own selection, such as a sort order. */
+  selection?: MenuSelection;
+  /** The selected value (`single`) or values (`multiple`). */
+  selected?: MenuSelected;
+}
+export interface SubMenuOptions {
+  props: () => SubMenuProps;
+  /** What the adapter put in the item that opens it. Without it, the item has only a label. */
+  content?: () => MenuItemContent;
+  /** The menu the submenu is in. Its color style and motion carry over, and choosing closes it. */
+  menu?: () => Pick<MenuApi, 'variant' | 'instant' | 'close'> | undefined;
+  /** Whether the submenu is open: the adapter owns it. */
+  open: () => boolean;
+  /** Called with the requested selection. */
+  onChange: (selected: MenuSelected) => void;
+  /** Called with the requested `open`: `true` for a click on its item. */
+  onOpenChange: (open: boolean) => void;
+}
+export interface SubMenuApi {
+  /**
+   * The item that opens the submenu, with the parts of a menu item (`menuItemSkeleton`). A click on
+   * it reports no event, so its `handleClick` takes any event it can cancel.
+   */
+  item: MenuItemApi<CancelableEvent>;
+  /** The submenu, with the parts of a menu (`menuSkeleton`). Its items take it as their menu. */
+  menu: MenuApi;
+}
+/**
+ * A submenu and the item that opens it. The two render side by side in the menu, the item where it
+ * sits and the submenu after it; the submenu shows in the top layer next to the item.
+ */
+export declare function createSubMenu(options: SubMenuOptions): SubMenuApi;
+export interface MenuGroupProps {
+  /** A label shown above the group's items, which also names the group. */
+  label?: string;
+}
+export interface MenuGroupParts {
+  root: () => PartAttrs;
+  /** The visible label. Assistive technology reads the name from the root instead. */
+  label: () => PartAttrs;
+  /** Holds the group's items. */
+  items: () => PartAttrs;
+}
+export declare const menuGroupSkeleton: PartNode<keyof MenuGroupParts, 'showsLabel'>;
+export interface MenuGroupApi {
+  parts: MenuGroupParts;
+  showsLabel: () => boolean;
+}
+export declare function createMenuGroup(options: {
+  props: () => MenuGroupProps;
+}): MenuGroupApi;
+export interface MenuDividerParts {
+  root: () => PartAttrs;
+}
+export declare const menuDividerSkeleton: PartNode<keyof MenuDividerParts>;
+export declare function createMenuDivider(): {
+  parts: MenuDividerParts;
+};
+/**
+ * A point a menu opens at, such as where a context menu was asked for, in viewport coordinates.
+ * With `element`, what the point is on, the menu keeps to that spot on it as it scrolls, as it
+ * follows an element anchor. Without, it stays where the point is on the screen.
+ */
+export interface MenuAnchorPoint extends AnchorPoint {
+  element?: Element;
+}
+export interface MenuDomOptions {
+  /** What the menu opens from: an element, such as a button, or a point, for a context menu. */
+  anchor: () => HTMLElement | MenuAnchorPoint | null | undefined;
+  /** The placement props, read when the menu opens. */
+  props: () => Pick<MenuProps, 'side' | 'align' | 'offset'>;
+  /**
+   * The menu closed, or asks to close, on its own: Escape, a click outside, Tab, or another
+   * overlay opening. The adapter sets `open` to false.
+   */
+  onClose: () => void;
+}
+export interface MenuDomHandle {
+  /** Brings the menu in line with `open`. Call it once attached, and whenever `open` changes. */
+  sync(open: boolean): void;
+  /**
+   * Call it when the anchor changes. An anchor other than the one the menu opened at is a new
+   * request, as from another right-click: an open menu opens afresh there, with its opening motion.
+   * One that fills in where there was none, such as a template ref, only places it.
+   */
+  update(): void;
+  detach(): void;
+}
+export interface SubMenuDomOptions {
+  /**
+   * The submenu opens or closes on its own: the pointer, the arrow keys, Escape, or a click
+   * elsewhere. The adapter sets its `open` to match.
+   */
+  onOpenChange: (open: boolean) => void;
+}
+export interface SubMenuDomHandle {
+  /** Brings the submenu in line with `open`. Call it once attached, and whenever `open` changes. */
+  sync(open: boolean): void;
+  detach(): void;
+}
+export declare function attachMenu(root: HTMLElement, options: MenuDomOptions): MenuDomHandle;
+/**
+ * A submenu's behavior in the DOM: a menu (see `attachMenu`) that `item` opens, shown beside it.
+ * `item` sits in a menu that `attachMenu` or this function runs, and `root` follows it.
+ */
+export declare function attachSubMenu(item: HTMLElement, root: HTMLElement, options: SubMenuDomOptions): SubMenuDomHandle;
 export interface DragInfo {
   /** Distance from where the press started, in px. */
   dx: number;
@@ -126,6 +668,41 @@ export interface DragHandle {
   detach(): void;
 }
 export declare function attachDrag(element: HTMLElement, options: DragOptions): DragHandle;
+export type OverlayMode = 'auto' | 'manual' | 'modal';
+/**
+ * Why an overlay closed, or asks to close, without the adapter asking:
+ * - `'escape'`: Escape, or the back gesture on a dialog. The overlay is still open, and the adapter
+ *   can turn the request down, as a dialog with unsaved changes might.
+ * - `'dismiss'`: the browser closed it: a click outside, or another popover or a modal dialog
+ *   opening.
+ * - `'parent'`: the overlay it was opened from closed.
+ * - `'replaced'`: another overlay opened, and this transient one gave way.
+ *
+ * All but `'escape'` arrive after the overlay closed, so the adapter has to follow them.
+ */
+export type OverlayCloseReason = 'escape' | 'dismiss' | 'parent' | 'replaced';
+export interface OverlayOptions {
+  mode: OverlayMode;
+  /** Closes when any other overlay opens, as a tooltip does. */
+  transient?: boolean;
+  /** Keeps clicks and presses in the element from bubbling past it, as a tooltip and a dialog do. */
+  contain?: boolean;
+  /** The overlay closed, or asks to close, without the adapter asking. */
+  onClose: (reason: OverlayCloseReason) => void;
+}
+export interface OverlayHandle {
+  /**
+   * Shows the element. `source` is what opened it, such as a menu item: a popover shown from
+   * inside an auto popover keeps that one open, and closes with it.
+   */
+  show(source?: HTMLElement): void;
+  /** Closes the element, without calling `onClose`. */
+  hide(): void;
+  /** Whether an overlay that opened after this one is still open, other than a transient one. */
+  covered(): boolean;
+  detach(): void;
+}
+export declare function attachOverlay(element: HTMLElement, options: OverlayOptions): OverlayHandle;
 export interface RippleHandle {
   /** Removes the listeners and the `data-ripple` marker. */
   detach(): void;
@@ -147,22 +724,21 @@ export declare function attachRipple(element: HTMLElement, options?: RippleOptio
 export interface ShapeMorphOptions {
   /** The motion token whose spring drives the morph. Defaults to `'fast-spatial'`. */
   token?: string;
-  /** Attributes whose changes can move the target. Defaults to Rio's state attributes. */
-  watch?: string[];
 }
 export interface ShapeMorphHandle {
   detach(): void;
 }
 export declare function attachShapeMorph(element: HTMLElement, options?: ShapeMorphOptions): ShapeMorphHandle;
 export interface SpringPropertyOptions {
-  /** A registered <length> custom property that holds the target for the current state. */
+  /**
+   * A registered custom property that holds the target for the current state: a <length>, read
+   * in px, or an <angle>, read in deg. The stylesheet has to transition it (see above).
+   */
   target: string;
-  /** Writes the animated value in px, or clears it with `undefined` at rest. */
+  /** Writes the animated value (px or deg), or clears it with `undefined` at rest. */
   apply: (value: number | undefined) => void;
   /** The motion token whose spring drives the value. Defaults to `'fast-spatial'`. */
   token?: string;
-  /** Attributes whose changes can move the target. Defaults to Rio's state attributes. */
-  watch?: string[];
 }
 export interface SpringPropertyHandle {
   /** The current animated value. */
@@ -173,8 +749,6 @@ export interface SpringPropertyHandle {
   release(velocity?: number): void;
   detach(): void;
 }
-/** The data attributes Rio's components use for state. */
-export declare const STATE_ATTRIBUTES: string[];
 export declare function attachSpringProperty(element: HTMLElement, options: SpringPropertyOptions): SpringPropertyHandle;
 export interface SpringParams {
   /** 1 settles without overshoot; lower values bounce, higher values approach more slowly. */
@@ -220,6 +794,11 @@ export interface Spring {
 }
 /** A spring that animates a single number with `requestAnimationFrame`. */
 export declare function createSpring(options: SpringOptions): Spring;
+/**
+ * Whether the user asked for reduced motion. Spatial springs should jump straight to their target
+ * (or be skipped) when it is on; see `docs/foundations.md`, section 3.
+ */
+export declare function prefersReducedMotion(): boolean;
 /**
  * Reads a motion token's spring from CSS variables on an element, for example
  * `--rio-motion-fast-spatial-damping` and `-stiffness`. Reading them from the element, rather than
@@ -227,11 +806,107 @@ export declare function createSpring(options: SpringOptions): Spring;
  * Returns `undefined` when the theme doesn't define them.
  */
 export declare function readSpringParams(element: Element, token: string): SpringParams | undefined;
+export interface SplitButtonMenuIconHandle {
+  detach(): void;
+}
+/** Attach to the trailing button. */
+export declare function attachSplitButtonMenuIcon(trailing: HTMLElement): SplitButtonMenuIconHandle;
+/** Split button colors: the button's, without text. */
+export declare const SPLIT_BUTTON_VARIANTS: readonly ["filled", "tonal", "outlined", "elevated"];
+export type SplitButtonVariant = (typeof SPLIT_BUTTON_VARIANTS)[number];
+/** What the trailing button opens, for `aria-haspopup`. */
+export type SplitButtonPopup = 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
+export interface SplitButtonProps {
+  /**
+   * Names the trailing button. It should say that more choices for the leading action are there,
+   * such as "More watch options" next to "Watch later".
+   */
+  menuLabel: string;
+  /**
+   * Names the leading button when it has no label text, only an icon. Ignored when there is label
+   * text, so the visible label stays the name (WCAG 2.5.3).
+   */
+  label?: string;
+  /** Defaults to `'filled'`. */
+  variant?: SplitButtonVariant;
+  /** Defaults to `'small'`. */
+  size?: ButtonSize;
+  /** Whether what the trailing button opens is open. */
+  open?: boolean;
+  /** What the trailing button opens. Defaults to `'menu'`. */
+  popup?: SplitButtonPopup;
+  /** Native disabled, on both buttons: not focusable and not pressable. The spec's behavior. */
+  disabled?: boolean;
+  /** Disabled but still focusable, on both buttons, as on the button. Deviates from the spec. */
+  softDisabled?: boolean;
+  /** The leading button's type. Defaults to `'button'`; the trailing button is always `'button'`. */
+  type?: 'button' | 'submit' | 'reset';
+}
+export declare const splitButtonDefaults: {
+  variant: "filled";
+  size: "small";
+  open: false;
+  popup: "menu";
+  disabled: false;
+  softDisabled: false;
+  type: "button";
+};
+/** What the adapter has to put in the leading button, which only the adapter can see. */
+export interface SplitButtonContent {
+  /** Whether there is a leading icon. */
+  icon: boolean;
+  /** Whether there is label text. */
+  label: boolean;
+}
+export interface SplitButtonOptions<E extends CancelableEvent = MouseEvent> {
+  /** Returns the current prop values. The adapter owns the state. */
+  props: () => SplitButtonProps;
+  /** Returns what content the adapter has. Without it, the leading button has only a label. */
+  content?: () => SplitButtonContent;
+  /**
+   * Called for a click on the leading button that isn't blocked, with the event
+   * `handleLeadingClick` got.
+   */
+  onClick: (event: E) => void;
+  /** Called with the requested `open` when the trailing button is clicked and isn't blocked. */
+  onChange: (open: boolean) => void;
+}
+/** The split button's markup, part by part. `splitButtonSkeleton` says how the adapter nests them. */
+export interface SplitButtonParts {
+  root: () => PartAttrs;
+  /** The main action, a button with an icon, label text, or both. */
+  leading: () => PartAttrs;
+  /** The button that opens the menu. */
+  trailing: () => PartAttrs;
+  /** Extends each button to the 48px target. Both buttons have one. */
+  touch: () => PartAttrs;
+  icon: () => PartAttrs;
+  label: () => PartAttrs;
+  /** Holds the expand icon, which turns when the menu opens. */
+  menuIcon: () => PartAttrs;
+}
+/**
+ * How the adapter renders the split button's parts. The icon and the label hold the leading
+ * button's content; the menu icon holds the expand icon the app provides.
+ */
+export declare const splitButtonSkeleton: PartNode<keyof SplitButtonParts, 'showsIcon' | 'showsLabel'>;
+export interface SplitButtonApi<E extends CancelableEvent = MouseEvent> {
+  parts: SplitButtonParts;
+  /** Whether to render the icon part. */
+  showsIcon: () => boolean;
+  /** Whether to render the label part. */
+  showsLabel: () => boolean;
+  /** Attach to the leading button's `click`. */
+  handleLeadingClick: (event: E) => void;
+  /** Attach to the trailing button's `click`. */
+  handleTrailingClick: (event: E) => void;
+}
+export declare function createSplitButton<E extends CancelableEvent = MouseEvent>(options: SplitButtonOptions<E>): SplitButtonApi<E>;
 export interface SwitchHandleOptions {
   /** Returns whether the switch is on. */
   selected: () => boolean;
   /** Called when a drag ends on the other side. */
-  onSelectedChange: (selected: boolean) => void;
+  onChange: (selected: boolean) => void;
 }
 export interface SwitchHandleHandle {
   detach(): void;
@@ -254,15 +929,148 @@ export declare const switchDefaults: {
   disabled: false;
   softDisabled: false;
 };
+/** What the adapter has to put in the switch, which only the adapter can see. */
+export interface SwitchContent {
+  /** Whether there is an icon for the handle while the switch is on. */
+  selectedIcon: boolean;
+  /** Whether there is an icon for the handle while the switch is off. */
+  unselectedIcon: boolean;
+}
 export interface SwitchOptions {
   /** Returns the current prop values. The adapter owns the state. */
   props: () => SwitchProps;
-  /** Called with the requested value. Adapters wire it to v-model, onChange, and so on. */
-  onSelectedChange: (selected: boolean) => void;
+  /** Returns what content the adapter has. Without it, the handle has no icons. */
+  content?: () => SwitchContent;
+  /** Called with the requested value. Adapters wire it to v-model, a callback prop, and so on. */
+  onChange: (selected: boolean) => void;
 }
+/**
+ * The switch's markup, part by part. `switchSkeleton` says how the adapter nests them.
+ */
+export interface SwitchParts {
+  root: () => PartAttrs;
+  /** Extends the 32px track to the 48px target. */
+  touch: () => PartAttrs;
+  state: () => PartAttrs;
+  handle: () => PartAttrs;
+  icon: () => PartAttrs;
+}
+/**
+ * How the adapter renders the switch's parts. The state part is the circle where the state layer
+ * and the ripple draw. The icon holds the selected icon when `showsSelectedIcon()`, otherwise the
+ * unselected one.
+ */
+export declare const switchSkeleton: PartNode<keyof SwitchParts, 'showsIcon'>;
 export interface SwitchApi {
-  rootAttrs: () => Record<string, string | undefined>;
+  parts: SwitchParts;
+  /** Whether the handle shows an icon in the current state, which also makes it bigger. */
+  showsIcon: () => boolean;
+  /** Whether the icon part shows the selected icon: the switch is on and has one. */
+  showsSelectedIcon: () => boolean;
   /** Attach to the root element's `click`. */
-  handleClick: (event: MouseEvent) => void;
+  handleClick: (event: CancelableEvent) => void;
+}
+export declare function createSwitch(options: SwitchOptions): SwitchApi;
+/** M3 tooltip variants: a brief label, or a card with a subhead, text, and actions. */
+export declare const TOOLTIP_VARIANTS: readonly ["plain", "rich"];
+export type TooltipVariant = (typeof TOOLTIP_VARIANTS)[number];
+export interface TooltipProps {
+  /** Defaults to `'plain'`. */
+  variant?: TooltipVariant;
+  /**
+   * Rich only: opens on a click on its element rather than on hover or focus, and stays open
+   * until the person interacts with something else.
+   */
+  persistent?: boolean;
+  /** Whether the tooltip is shown. */
+  open?: boolean;
+  /** The side of its element it shows on. Defaults to `'top'` for plain, `'bottom'` for rich. */
+  side?: AnchoredSide;
+  /** Which edges line up with the element's. Defaults to `'center'` for plain, `'start'` for rich. */
+  align?: AnchoredAlign;
+  /**
+   * Space between the element and the tooltip, in px. Defaults to 4, for an element with a visible
+   * edge, such as a button; 8 suits one without, such as text.
+   */
+  offset?: number;
+}
+export declare const tooltipDefaults: {
+  variant: "plain";
+  persistent: false;
+  open: false;
+  offset: number;
+};
+/** What the adapter has to put in the tooltip, which only the adapter can see. */
+export interface TooltipContent {
+  /** A subhead above the text (rich only) */
+  subhead: boolean;
+  /** Text buttons below the text (rich only) */
+  actions: boolean;
+}
+export interface TooltipOptions {
+  props: () => TooltipProps;
+  /** Without it, the tooltip has only its text. */
+  content?: () => TooltipContent;
+  /** Ids for the parts that others refer to, unique in the document. The adapter makes them. */
+  ids: {
+    root: string;
+    subhead: string;
+    supportingText: string;
+  };
+}
+export interface TooltipParts {
+  /**
+   * Wraps the element the tooltip is for, then the tooltip itself, without a box of its own. The
+   * tooltip shows in the top layer, but comes right after its element in the focus order.
+   */
+  trigger: () => PartAttrs;
+  /** The tooltip, shown in the top layer */
+  root: () => PartAttrs;
+  subhead: () => PartAttrs;
+  supportingText: () => PartAttrs;
+  /** Holds the text buttons. */
+  actions: () => PartAttrs;
+}
+/** The trigger holds the app's element first, then the tooltip (`tooltipSkeleton`). */
+export declare const tooltipTriggerSkeleton: PartNode<'trigger'>;
+type TooltipPart = Exclude<keyof TooltipParts, 'trigger'>;
+type TooltipWhen = 'showsSubhead' | 'showsActions';
+/** Spans throughout, so a tooltip may sit inside a paragraph. */
+export declare const tooltipSkeleton: PartNode<TooltipPart, TooltipWhen>;
+export interface TooltipPlacement {
+  side: AnchoredSide;
+  align: AnchoredAlign;
+  offset: number;
+}
+export interface TooltipApi extends Record<TooltipWhen, () => boolean> {
+  parts: TooltipParts;
+  /**
+   * Whether it holds actions, which take the focus: a rich tooltip with actions is a non-modal
+   * dialog rather than a tooltip.
+   */
+  interactive: () => boolean;
+  /** Whether it opens on a click and stays open (rich only). */
+  persistent: () => boolean;
+  /** Where it shows, with the defaults of its variant filled in. */
+  placement: () => TooltipPlacement;
+}
+export declare function createTooltip(options: TooltipOptions): TooltipApi;
+export interface TooltipDomOptions {
+  /** Where the tooltip shows, read when it opens. */
+  placement: () => TooltipPlacement;
+  /** Whether it opens on a click and stays open. */
+  persistent: () => boolean;
+  /** Whether it holds actions, and so is a dialog whose text describes the element. */
+  interactive: () => boolean;
+  /** The tooltip opens or closes on its own. The adapter sets `open` to match. */
+  onOpenChange: (open: boolean) => void;
+}
+export interface TooltipDomHandle {
+  /** Brings the tooltip in line with `open`. Call it once attached, and whenever `open` changes. */
+  sync(open: boolean): void;
+  /** Call it after the element or the tooltip's content changed, to update the element's ARIA. */
+  update(): void;
+  detach(): void;
 }
-export declare function createSwitch(options: SwitchOptions): SwitchApi;
+export declare function attachTooltip(trigger: HTMLElement, root: HTMLElement, options: TooltipDomOptions): TooltipDomHandle;
+export {};