@windmorph/react 0.0.0-stage → 0.1.0

package/dist/components/menu/Menu.d.ts

@@ -0,0 +1,215 @@
+import { Density } from "../../tokens/density.js";
+import { RootDOMProps } from "../../utils/root-props.js";
+import { MenuLayout, MenuVariant } from "./menu-styles.js";
+import { ContextMenuTrigger, ContextMenuTriggerProps, MenuTrigger, MenuTriggerProps } from "./menu-trigger.js";
+import { CSSProperties, JSX, Key as Key$1, ReactElement, ReactNode, Ref } from "react";
+import { AriaMenuProps } from "react-aria";
+//#region src/components/menu/Menu.d.ts
+/** Props of a {@link MenuItem}; the React `key` identifies it for `onAction` and selection. */
+export interface MenuItemProps {
+  /** The label. */
+  children: ReactNode;
+  /** Plain-text label for typeahead when `children` is not a string. */
+  textValue?: string;
+  /** Icon before the label. */
+  leadingIcon?: ReactNode;
+  /** Icon shown while selected (defaults to a check in selectable menus). */
+  selectedIcon?: ReactNode;
+  /** Second line of text (supporting text), read as part of the item's name after the label. */
+  description?: ReactNode;
+  /**
+   * A badge before the trailing text or icon (M3 anatomy), such as a `Badge` with a count.
+   * It's read after the name, as the item's description.
+   */
+  badge?: ReactNode;
+  /** Keyboard shortcut shown at the end, e.g. "⌘C", read as the item's description. */
+  shortcut?: string;
+  /** Icon at the end (an item with a submenu shows an arrow by default). */
+  trailingIcon?: ReactNode;
+  /** Accessible name when the label isn't plain text. */
+  'aria-label'?: string;
+  /** Classes for the item, merged after `classNames.item`; consumer classes win. */
+  className?: string;
+}
+/** An item in a `Menu` (a React Stately collection item: identify it with `key`). */
+export declare const MenuItem: (props: MenuItemProps) => JSX.Element;
+export interface MenuGroupProps {
+  /** Group label shown above its items. */
+  title?: ReactNode;
+  /** Accessible name for the group when it has no `title`. */
+  'aria-label'?: string;
+  /** `MenuItem`s and `SubmenuTrigger`s. */
+  children: ReactElement | ReactElement[];
+}
+/**
+ * A group of items (a React Stately collection section): set off by dividers in the
+ * `divider` layout, its own surface in the `gap` layout.
+ */
+export declare const MenuGroup: (props: MenuGroupProps) => JSX.Element;
+export interface SubmenuTriggerProps {
+  /** The `MenuItem` that opens the submenu, then the submenu's `Menu`. */
+  children: [ReactElement<MenuItemProps>, ReactElement<MenuProps>];
+  /** How long (ms) the pointer rests on the item before the submenu opens. @default 200 */
+  delay?: number;
+}
+/**
+ * Gives a menu item a submenu (M3: "On web, menus can open submenus"). It opens beside the
+ * item, without covering it, on hover, press, Enter, Space or the arrow key pointing away
+ * from the menu (Left in right-to-left), and closes with the opposite arrow or Escape.
+ * While it's open, the item shows its active (pressed) layer, and the menu holding focus
+ * takes rounder corners than the other one.
+ *
+ * @example
+ * <SubmenuTrigger>
+ *   <MenuItem key="share">Share</MenuItem>
+ *   <Menu onAction={(key) => share(key)}>
+ *     <MenuItem key="email">Email</MenuItem>
+ *     <MenuItem key="link">Copy link</MenuItem>
+ *   </Menu>
+ * </SubmenuTrigger>
+ */
+export declare const SubmenuTrigger: (props: SubmenuTriggerProps) => JSX.Element;
+export interface MenuClassNames {
+  /**
+   * The menu's surface (the `menu` element): its colour, corners, size and the list that
+   * scrolls. In a sheet it spans the sheet, without a surface of its own.
+   */
+  panel?: string;
+  /**
+   * The bottom sheet the menu opens in (`presentation="sheet"`, or `"auto"` on compact
+   * windows): the sheet's surface, as its `classNames.panel`.
+   */
+  sheet?: string;
+  /** Each group of items (its own surface in the `gap` layout). */
+  group?: string;
+  /** Each `MenuGroup`'s heading. */
+  heading?: string;
+  /** Each item. */
+  item?: string;
+  /** Each item's leading icon, or the icon marking a selected item. */
+  icon?: string;
+  /** Each item's `description` line. */
+  description?: string;
+  /** Each item's keyboard `shortcut`. */
+  shortcut?: string;
+  /** Each item's trailing icon, including a submenu's arrow. */
+  trailingIcon?: string;
+  /** The dividers between groups in the `divider` layout. */
+  divider?: string;
+}
+export interface MenuProps extends Omit<AriaMenuProps<object>, 'children' | 'items' | 'onClose' | 'autoFocus' | 'disallowEmptySelection' | 'shouldFocusWrap' | 'escapeKeyBehavior'>, Omit<RootDOMProps, keyof AriaMenuProps<object>> {
+  /**
+   * With `selectionMode`: the last selected item can be deselected, leaving none. `false` keeps
+   * at least one item selected. @default true
+   */
+  deselectable?: boolean;
+  /**
+   * The keys of items that can't be chosen. They stay focusable, as M3 asks ("Disabled menu
+   * items can receive focus but aren't selectable").
+   */
+  disabledKeys?: AriaMenuProps<object>['disabledKeys'];
+  /** `MenuItem`s, `MenuGroup`s and `SubmenuTrigger`s. */
+  children: ReactNode;
+  /** `standard` (surface colours) or `vibrant` (tertiary container). @default "standard" */
+  variant?: MenuVariant;
+  /**
+   * How groups are set apart. `divider`: one surface with dividers between groups, which M3
+   * recommends on the web and for menus that scroll. `gap`: each group is its own surface,
+   * 2px apart; a `gap` menu that has to scroll switches to dividers, since M3 doesn't use
+   * gaps in scrolling menus. A submenu takes its parent's layout and variant unless it
+   * sets its own.
+   * @default "divider"
+   */
+  layout?: MenuLayout;
+  /**
+   * Web density (M3: "On web only … Increasing density decreases the top and bottom
+   * padding"): each step down takes 4px off the items' height (44px at 0, 32px at -3) and 2px
+   * off the space around dividers. Left out, the menu takes the density of the nearest
+   * `ThemeProvider` or `ThemeScope`; a submenu takes its parent menu's. Keep 0 for touch.
+   * @default 0
+   */
+  density?: Density;
+  /**
+   * Placement relative to the trigger: a side, then optionally the edge to align with
+   * (`start` / `end` follow the text direction). A submenu always opens beside its item.
+   * @default "bottom-start"
+   */
+  placement?: MenuPlacement;
+  /** Gap between the trigger and the menu, in px (a split button's menu sits 4px away). @default 0 */
+  offset?: number;
+  /**
+   * The least space kept between the menu and the window's edges, in px. A split button
+   * passes 0, so its menu lines up with the trailing button even at the edge of the screen.
+   * @default 12
+   */
+  containerPadding?: number;
+  /**
+   * Where the menu opens. `popover`: anchored to its trigger. `sheet`: in a modal bottom
+   * sheet. `auto`: a sheet on compact windows (below 600px wide) and a popover on larger
+   * ones (M3: "Consider adapting menus into bottom sheets on small screens"). Set it on the
+   * root menu.
+   * @default "popover"
+   */
+  presentation?: MenuPresentation;
+  /** Words the menu shows in a sheet. Set them on the root menu. */
+  labels?: Partial<MenuLabels>;
+  /**
+   * Open and close with no motion (M3: "In dense products, such as on desktop, menus can
+   * open instantly to reduce motion"). Submenus follow their root menu. Popovers only: a menu
+   * shown as a bottom sheet (`presentation="sheet"`, or `auto` on a compact window) keeps the
+   * sheet's slide, as M3's and Compose's modal bottom sheets always animate; under reduced
+   * motion it fades instead.
+   * @default false
+   */
+  instant?: boolean;
+  /**
+   * Goes with `style` on the menu's outermost element: the box React Aria places against the
+   * trigger, or the bottom sheet's outermost element in a sheet. The surface inside keeps
+   * its size and its place against the trigger whatever layout class lands here (the box
+   * keeps the menu's own width); style it with `classNames.panel`.
+   */
+  className?: string;
+  /** Classes for each part, by slot. */
+  classNames?: MenuClassNames;
+  /** Goes on the menu's outermost element, with `className`. */
+  style?: CSSProperties;
+  /** Ref to the menu's list, the `role="menu"` element, in a popover or a sheet. */
+  ref?: Ref<HTMLDivElement>;
+}
+/** Where a {@link Menu} sits against its trigger: a side, then optionally the edge it aligns with. */
+export type MenuPlacement = 'top' | 'bottom' | 'start' | 'end' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'start-top' | 'start-bottom' | 'end-top' | 'end-bottom';
+/** Where a {@link Menu} opens. */
+export type MenuPresentation = 'popover' | 'sheet' | 'auto';
+/** Words a {@link Menu} shows. */
+export interface MenuLabels {
+  /**
+   * In a sheet, the button above a submenu that goes back to the menu that opened it.
+   * @default "Back"
+   */
+  back: string;
+}
+/**
+ * M3 Expressive menu: items on one surface with dividers between groups (or on grouped
+ * surfaces), standard or vibrant colours, optional single or multiple selection with a
+ * selected shape and check, submenus, keyboard navigation and typeahead (React Aria
+ * `useMenu`). Must be inside a `MenuTrigger` or `ContextMenuTrigger`; it opens anchored to
+ * the trigger in a portal that keeps the surrounding theme and direction.
+ *
+ * @example
+ * <MenuTrigger>
+ *   <IconButton icon={<MoreIcon />} aria-label="More" />
+ *   <Menu onAction={(key) => run(key)}>
+ *     <MenuGroup>
+ *       <MenuItem key="copy" shortcut="⌘C">Copy</MenuItem>
+ *       <MenuItem key="paste" shortcut="⌘V">Paste</MenuItem>
+ *     </MenuGroup>
+ *     <MenuGroup>
+ *       <MenuItem key="delete">Delete</MenuItem>
+ *     </MenuGroup>
+ *   </Menu>
+ * </MenuTrigger>
+ */
+export declare function Menu({ presentation, instant, ...props }: MenuProps): JSX.Element | null;
+//#endregion
+export { ContextMenuTrigger, type ContextMenuTriggerProps, type Key$1 as MenuKey, MenuTrigger, type MenuTriggerProps };
+//# sourceMappingURL=Menu.d.ts.map