@blakesteve/roster 5.8.0 → 5.10.0

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

@@ -0,0 +1,169 @@
+import { ButtonProps } from '../../atoms/Button/Button';
+import * as React from "react";
+/**
+ * The props every link item is rendered with. `href` and `to` carry the same
+ * value, so `next/link`, React Router's `Link` and a plain `<a>` all work
+ * without a wrapper. The rest must reach the DOM: the role, the tab index and
+ * the handlers are what make the link an item of the menu.
+ */
+export interface MenuLinkProps {
+    href: string;
+    to: string;
+    className: string;
+    children: React.ReactNode;
+    role: "menuitem";
+    tabIndex: -1;
+    "aria-disabled"?: true;
+    "aria-keyshortcuts"?: string;
+    "aria-describedby"?: string;
+    "data-menu-item": "";
+    onClick: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+    onKeyDown: (event: React.KeyboardEvent<HTMLAnchorElement>) => void;
+    onPointerMove: (event: React.PointerEvent<HTMLAnchorElement>) => void;
+}
+export interface MenuProps {
+    /** The trigger (`MenuButton`) and the panel (`MenuItems`). */
+    children: React.ReactNode;
+    /**
+     * Controlled open state. Leave both off to let the menu keep its own. Pass
+     * `onOpenChange` with `open`: every way the menu closes itself (Escape,
+     * Tab, a press outside, a choice) is a call to it.
+     */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Renders every link item (a `MenuItem` with an `href`). Defaults to a plain
+     * `<a>`, which inside a router turns each choice into a full page load: pass
+     * `next/link` or your router's link, from a client component.
+     */
+    linkComponent?: React.ComponentType<MenuLinkProps>;
+}
+/**
+ * A button that opens a panel of actions: the menu button pattern. Compose it:
+ *
+ * ```tsx
+ * <Menu>
+ *   <MenuButton>Actions</MenuButton>
+ *   <MenuItems>
+ *     <MenuItem icon={<EditIcon />} shortcut="⌘E" onSelect={edit}>Edit</MenuItem>
+ *     <MenuSeparator />
+ *     <MenuItem destructive onSelect={remove}>Delete</MenuItem>
+ *   </MenuItems>
+ * </Menu>
+ * ```
+ *
+ * The keyboard follows the pattern: Enter, Space or Down open it on the first
+ * item and Up on the last; arrows move, Home and End jump, a typed letter
+ * jumps to the next item starting with it; Escape closes it and puts focus
+ * back on the button; Tab closes it and moves on. A submenu opens with the
+ * arrow away from the parent and closes with the arrow back.
+ */
+declare function Menu({ children, open: openProp, onOpenChange, linkComponent }: MenuProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuButtonProps extends ButtonProps {
+    /**
+     * A plain `<button>` with only your `className`, for a trigger drawn its own
+     * way: an avatar, an icon. Keep its target at least 44 by 44, with
+     * padding or a hit area, if you draw it smaller.
+     */
+    plain?: boolean;
+}
+declare const MenuButton: React.ForwardRefExoticComponent<MenuButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export interface MenuItemsProps {
+    children: React.ReactNode;
+    /** Which edge of the button the panel lines up with. */
+    align?: "start" | "end";
+    /** The gap between the button and the panel, in px. */
+    offset?: number;
+    /** Names the menu when the button's own name shouldn't. By default the button names it. */
+    "aria-label"?: string;
+    /** Applied to the panel. Its surface reads `--roster-popover-*`; set those to repaint it. */
+    className?: string;
+}
+declare function MenuItems({ children, align, offset, className, ...aria }: MenuItemsProps): import("react/jsx-runtime").JSX.Element | null;
+interface ItemContent {
+    /** A leading icon. Decorative: the item's words name it. */
+    icon?: React.ReactNode;
+    /** A second, quieter line under the label: what the item does, or to what. Read as the item's description. */
+    description?: React.ReactNode;
+    /** A count or a status at the end of the row, read with the item's name. */
+    badge?: React.ReactNode;
+    /** A keyboard shortcut to show, right-aligned: display only. The app handles the keys. */
+    shortcut?: string;
+    /** The same shortcut in `aria-keyshortcuts` form ("Control+E"), for assistive technology. */
+    keyshortcuts?: string;
+    /** Reads as a consequence: red. The words still have to say what it does. */
+    destructive?: boolean;
+    /** Can be reached by the arrows but not chosen. */
+    disabled?: boolean;
+    /** What typeahead matches, when the item's text isn't the right thing to match. */
+    textValue?: string;
+    className?: string;
+    children: React.ReactNode;
+}
+export interface MenuItemProps extends ItemContent {
+    /** Called when the item is chosen: a click, Enter or Space. */
+    onSelect?: (event: React.SyntheticEvent) => void;
+    /** Makes it a link item. It navigates through the menu's `linkComponent`. */
+    href?: string;
+    /** Close the menu once chosen. On by default. */
+    closeOnSelect?: boolean;
+}
+/** One action. With `href`, a link. */
+declare function MenuItem({ onSelect, href, closeOnSelect, disabled, destructive, keyshortcuts, textValue, className, ...content }: MenuItemProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuCheckboxItemProps extends ItemContent {
+    checked: boolean;
+    onCheckedChange: (checked: boolean) => void;
+    /**
+     * Replaces the leading check mark with an indicator of your own at the end
+     * of the row: a switch's track, say. Its state still reaches assistive
+     * technology through `aria-checked`.
+     */
+    indicator?: React.ReactNode;
+    /** Close the menu once chosen by click or Enter. Space always keeps it open. */
+    closeOnSelect?: boolean;
+}
+/** An on/off choice: `menuitemcheckbox`. */
+declare function MenuCheckboxItem({ checked, onCheckedChange, indicator, closeOnSelect, disabled, destructive, keyshortcuts, textValue, className, ...content }: MenuCheckboxItemProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuRadioGroupProps {
+    value: string | undefined;
+    onValueChange: (value: string) => void;
+    /** The choice's name, shown above its items and read with them. */
+    label?: React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+}
+/** One choice among several: its items are `menuitemradio`. */
+declare function MenuRadioGroup({ value, onValueChange, label, children, className }: MenuRadioGroupProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuRadioItemProps extends ItemContent {
+    value: string;
+    /** Close the menu once chosen by click or Enter. Space always keeps it open. */
+    closeOnSelect?: boolean;
+}
+declare function MenuRadioItem({ value, closeOnSelect, disabled, destructive, keyshortcuts, textValue, className, ...content }: MenuRadioItemProps): import("react/jsx-runtime").JSX.Element;
+export interface MenuGroupProps {
+    /** Shown above the group's items, and names the group. */
+    label?: React.ReactNode;
+    children: React.ReactNode;
+    className?: string;
+}
+/** Items that belong together, under an optional label. */
+declare function MenuGroup({ label, children, className }: MenuGroupProps): import("react/jsx-runtime").JSX.Element;
+/** A rule between groups of items. */
+declare function MenuSeparator({ className }: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export interface MenuSubmenuProps extends Omit<ItemContent, "shortcut" | "keyshortcuts" | "children" | "destructive" | "description" | "badge"> {
+    /** The item that opens it. */
+    label: React.ReactNode;
+    /** Its items. */
+    children: React.ReactNode;
+    /** Applied to the submenu's panel. */
+    panelClassName?: string;
+}
+/**
+ * An item that opens a menu of its own beside it. It opens with the arrow away
+ * from its parent, Enter, Space, a click, or the pointer resting on it; the
+ * arrow back, or Escape, closes it and returns to its item.
+ */
+declare function MenuSubmenu({ label, children, icon, disabled, textValue, className, panelClassName }: MenuSubmenuProps): import("react/jsx-runtime").JSX.Element;
+export { Menu, MenuButton, MenuItems, MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuGroup, MenuSeparator, MenuSubmenu, };