@rio-m3e/core 0.2.0 → 0.3.0

package/README.md

@@ -4,4 +4,6 @@ Framework-agnostic logic for [Rio](https://github.com/LegenLee/rio), a Material
 
 Framework adapters such as [`@rio-m3e/vue`](https://www.npmjs.com/package/@rio-m3e/vue) are built on it, and install it for you. Install it directly only to build components of your own.
 
+You can see the document page in [here](https://legenlee.github.io/rio/).
+
 Licensed under the Apache License 2.0.

package/dist/index.d.ts

@@ -5,6 +5,14 @@
  * `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
@@ -82,13 +90,13 @@ export interface ButtonContent {
   /** Whether there is a leading icon. */
   icon: boolean;
 }
-export interface ButtonOptions {
+export interface ButtonOptions<E extends CancelableEvent = MouseEvent> {
   /** Returns the current prop values. The adapter owns the state. */
   props: () => ButtonProps;
   /** Returns what content the adapter has. Without it, the button has no icon. */
   content?: () => ButtonContent;
-  /** Called for a click that isn't blocked. */
-  onClick: (event: MouseEvent) => void;
+  /** 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;
 }
@@ -104,14 +112,14 @@ export interface ButtonParts {
 }
 /** 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 {
+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(options: ButtonOptions): ButtonApi;
+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
@@ -192,6 +200,87 @@ 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 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. */
@@ -240,13 +329,13 @@ export interface IconButtonContent {
   /** Whether there is an icon for the selected state. */
   selectedIcon: boolean;
 }
-export interface IconButtonOptions {
+export interface IconButtonOptions<E extends CancelableEvent = MouseEvent> {
   /** Returns the current prop values. The adapter owns the state. */
   props: () => IconButtonProps;
   /** Returns what content the adapter has. Without it, there is no selected icon. */
   content?: () => IconButtonContent;
-  /** Called for a click that isn't blocked. */
-  onClick: (event: MouseEvent) => void;
+  /** 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;
 }
@@ -264,14 +353,298 @@ export interface IconButtonParts {
  * `showsSelectedIcon()`, otherwise the default one.
  */
 export declare const iconButtonSkeleton: PartNode<keyof IconButtonParts>;
-export interface IconButtonApi {
+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: MouseEvent) => void;
+  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): IconButtonApi;
+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;
@@ -295,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;
@@ -450,13 +858,16 @@ export interface SplitButtonContent {
   /** Whether there is label text. */
   label: boolean;
 }
-export interface SplitButtonOptions {
+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. */
-  onClick: (event: MouseEvent) => void;
+  /**
+   * 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;
 }
@@ -479,18 +890,18 @@ export interface SplitButtonParts {
  * 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 {
+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: MouseEvent) => void;
+  handleLeadingClick: (event: E) => void;
   /** Attach to the trailing button's `click`. */
-  handleTrailingClick: (event: MouseEvent) => void;
+  handleTrailingClick: (event: E) => void;
 }
-export declare function createSplitButton(options: SplitButtonOptions): SplitButtonApi;
+export declare function createSplitButton<E extends CancelableEvent = MouseEvent>(options: SplitButtonOptions<E>): SplitButtonApi<E>;
 export interface SwitchHandleOptions {
   /** Returns whether the switch is on. */
   selected: () => boolean;
@@ -557,6 +968,109 @@ export interface SwitchApi {
   /** 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 {};