@galaxy-io/dls 1.6.1 → 2.0.1

package/dist/menu/Menu.d.ts

@@ -0,0 +1,280 @@
+import { type Icon as PhosphorIcon } from "@phosphor-icons/react";
+import { type AriaAttributes, type CSSProperties, type ElementType, type ReactElement, type ReactNode, type RefAttributes } from "react";
+import { PopoverTrigger } from "../overlays/Popover.js";
+import { Placement } from "../theme/enums.js";
+/** Row rung (canonical subset): 24px or 32px rows. */
+export declare enum MenuSize {
+    /** 24px rows, `body_sm` labels, 12px icons, 10px submenu caret: dense menus (table cells, toolbars; the 1.x density). */
+    SMALL = "SMALL",
+    /** 32px rows, `body_md` labels, 14px icons, 12px submenu caret. The default. */
+    MEDIUM = "MEDIUM"
+}
+/** Panel fill: a surface step (Constitution V-A surface set). */
+export declare enum MenuVariant {
+    /** The canvas fill, `background.base`. The default. */
+    BASE = "BASE",
+    /** A panel fill, `background.primary`. */
+    PRIMARY = "PRIMARY",
+    /** A raised fill, `background.secondary`. */
+    SECONDARY = "SECONDARY",
+    /** The most elevated fill, `background.tertiary`. */
+    TERTIARY = "TERTIARY"
+}
+/** Row mode (Constitution V-A: MenuItem `DEFAULT` / `ERROR`; declared in `scripts/lint-dls.ts` `MODE_SETS`). */
+export declare enum MenuItemVariant {
+    /** A monochrome row. The default. */
+    DEFAULT = "DEFAULT",
+    /** A destructive command: error text and icon, error-tinted highlight. */
+    ERROR = "ERROR"
+}
+export interface MenuProps extends AriaAttributes {
+    /**
+     * The element that opens the menu: one element that forwards its `ref` and spreads props to a
+     * DOM element (a `Button`). Menu clones it and does not wrap it.
+     */
+    trigger: ReactElement;
+    /** The rows: `MenuItem`, `MenuCheckboxItem`, `MenuRadioGroup`, `MenuGroup`, `MenuSeparator`. */
+    children?: ReactNode;
+    /**
+     * Row rung: 24 or 32px rows, with matching type, icon and shortcut sizes.
+     * @default MenuSize.MEDIUM
+     */
+    size?: MenuSize;
+    /**
+     * Panel fill (surface step).
+     * @default MenuVariant.BASE
+     */
+    variant?: MenuVariant;
+    /**
+     * Preferred side and alignment. The panel flips and shifts to stay in the viewport; `AUTO*`
+     * picks the side with the most room.
+     * @default Placement.BOTTOM_START
+     */
+    placement?: Placement;
+    /**
+     * Shows a search field above the rows that filters them by label and description. Focus starts in the field.
+     * @default false
+     */
+    isSearchable?: boolean;
+    /** Controlled open state. When set, Menu calls `onOpenChange` and lets the caller decide. */
+    isOpen?: boolean;
+    /**
+     * Initial open state while uncontrolled.
+     * @default false
+     */
+    defaultIsOpen?: boolean;
+    /** Called with the requested open state on trigger interaction, a selection, Escape, outside press and Tab. */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Never opens. The trigger renders exactly as when enabled, without the popup ARIA.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /** Accessible name of the menu. When omitted (and no `aria-labelledby` is passed), the menu is labelled by the trigger. */
+    ariaLabel?: string;
+    /** DOM id on the panel; the trigger's `aria-controls` target. @default a `useId()` value */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the panel. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the panel. */
+    className?: string;
+    /** Inline style on the panel; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/**
+ * @internal Shared by Menu and ContextMenu; apps use those. `MenuProps` plus the Popover mode that
+ * opens the menu.
+ */
+export interface MenuRootProps extends MenuProps {
+    /** How the menu opens: `CLICK` (Menu) or `CONTEXT_MENU` (ContextMenu). */
+    popoverTrigger: PopoverTrigger.CLICK | PopoverTrigger.CONTEXT_MENU;
+}
+/** Every `MenuItem` prop except the command / submenu pair. */
+export interface MenuItemBaseProps extends AriaAttributes {
+    /** Row text. Also what typeahead and the search filter match. */
+    label: string;
+    /** Second line under the label, up to two lines. The search filter matches it too. */
+    description?: string;
+    /** Phosphor icon component before the label, sized and colored by the row. */
+    icon?: PhosphorIcon;
+    /** Anything else before the label (an `Avatar`, a `Status`). Must not be interactive. */
+    leading?: ReactNode;
+    /** Content after the label (a count `Chip`). Must not be interactive. */
+    trailing?: ReactNode;
+    /** Shortcut shown as `Kbd` caps at the end of the row, in `useHotkey` grammar. Display only: the app binds it. */
+    hotKeys?: string[];
+    /**
+     * `ERROR` for a destructive command (Delete, Remove).
+     * @default MenuItemVariant.DEFAULT
+     */
+    variant?: MenuItemVariant;
+    /**
+     * Cannot be chosen. Stays focusable so `disabledReason` can be read.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /** With `isDisabled`: why, shown in a tooltip beside the row on hover and keyboard focus. */
+    disabledReason?: string;
+    /** DOM id on the row element. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the row element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the row element. */
+    className?: string;
+    /** Inline style on the row element; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** A row that runs a command or follows a link. */
+interface MenuItemCommandProps {
+    /** Runs when the row is chosen (click, Enter, Space). The whole menu then closes. */
+    onSelect?: () => void;
+    /** Renders the row as a link (`<a role="menuitem">`). */
+    href?: string;
+    /**
+     * Router link component that renders the row when `href` is set. It receives `href` and must forward its `ref`. Ignored without `href`.
+     * @default "a"
+     */
+    as?: ElementType;
+    /**
+     * With `href`: opens in a new tab (`target="_blank"`, `rel="noopener noreferrer"`) and adds a trailing arrow plus visually hidden "(opens in a new tab)".
+     * @default false
+     */
+    isExternal?: boolean;
+    /** Submenu rows. When set, the row opens a submenu beside it instead of being chosen, and shows a trailing caret. */
+    children?: undefined;
+}
+/** A row that opens a submenu. */
+interface MenuItemSubmenuProps {
+    /** Runs when the row is chosen (click, Enter, Space). The whole menu then closes. */
+    onSelect?: never;
+    /** Renders the row as a link (`<a role="menuitem">`). */
+    href?: never;
+    /** Router link component that renders the row when `href` is set. */
+    as?: never;
+    /** With `href`: opens in a new tab. */
+    isExternal?: never;
+    /** Submenu rows. When set, the row opens a submenu beside it instead of being chosen, and shows a trailing caret. */
+    children: ReactNode;
+}
+/** `MenuItem` props: a command (or link) row, or a submenu row, never both. */
+export type MenuItemProps = MenuItemBaseProps & (MenuItemCommandProps | MenuItemSubmenuProps);
+export interface MenuCheckboxItemProps extends AriaAttributes {
+    /** Row text. Also what typeahead and the search filter match. */
+    label: string;
+    /** Second line under the label. */
+    description?: string;
+    /** Icon before the label. */
+    icon?: PhosphorIcon;
+    /** Anything else before the label. Must not be interactive. */
+    leading?: ReactNode;
+    /** Shortcut shown as `Kbd` caps. Display only. */
+    hotKeys?: string[];
+    /** Controlled checked state. Pass it with `onChange`. */
+    isChecked?: boolean;
+    /**
+     * Initial checked state while uncontrolled.
+     * @default false
+     */
+    defaultIsChecked?: boolean;
+    /** Called with the new state when the row is toggled. The menu stays open. */
+    onChange?: (isChecked: boolean) => void;
+    /**
+     * Cannot be toggled. Stays focusable.
+     * @default false
+     */
+    isDisabled?: boolean;
+    /** With `isDisabled`: why, in a tooltip beside the row. */
+    disabledReason?: string;
+    /** DOM id on the row element. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the row element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the row element. */
+    className?: string;
+    /** Inline style on the row element; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** One choice of a `MenuRadioGroup`. */
+export interface MenuRadioOption<TId extends string = string> {
+    /** Value reported by `onChange`. */
+    id: TId;
+    /** Row text; also what typeahead and the search filter match. */
+    label: string;
+    /** Second line under the label. */
+    description?: string;
+    /** Icon before the label. */
+    icon?: PhosphorIcon;
+    /** Anything else before the label (an `Avatar`, a `Status`). */
+    leading?: ReactNode;
+    /** Shortcut shown as `Kbd` caps. Display only. */
+    hotKeys?: string[];
+    /** Cannot be chosen; stays focusable. */
+    isDisabled?: boolean;
+    /** With `isDisabled`: why, in a tooltip beside the row. */
+    disabledReason?: string;
+}
+export interface MenuRadioGroupProps<TId extends string = string> extends AriaAttributes {
+    /** The choices, one row each. */
+    options: MenuRadioOption<TId>[];
+    /** Controlled chosen id. `null` checks no row. */
+    value?: TId | null;
+    /**
+     * Initial chosen id while uncontrolled.
+     * @default null
+     */
+    defaultValue?: TId | null;
+    /** Called with the chosen option's `id`. The whole menu then closes. */
+    onChange?: (value: TId) => void;
+    /** Section heading above the options, and the group's accessible name. */
+    label?: string;
+    /** DOM id on the group element. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the group element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the group element. */
+    className?: string;
+    /** Inline style on the group element; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+export interface MenuGroupProps extends AriaAttributes {
+    /** Section heading, and the group's accessible name. */
+    label?: string;
+    /** The rows in this section. */
+    children?: ReactNode;
+    /** DOM id on the group element. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the group element. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the group element. */
+    className?: string;
+    /** Inline style on the group element; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+export interface MenuSeparatorProps extends AriaAttributes {
+    /** DOM id on the separator wrapper. */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the separator wrapper. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the separator wrapper. */
+    className?: string;
+    /** Inline style on the separator wrapper; only for setting CSS custom properties. */
+    style?: CSSProperties;
+}
+/** A command, a link, or the opener of a submenu. */
+export declare const MenuItem: import("react").ForwardRefExoticComponent<MenuItemProps & RefAttributes<HTMLAnchorElement | HTMLButtonElement>>;
+/** An on/off option; toggling keeps the menu open. */
+export declare const MenuCheckboxItem: import("react").ForwardRefExoticComponent<MenuCheckboxItemProps & RefAttributes<HTMLButtonElement>>;
+/** One choice among options; choosing closes the menu. */
+export declare const MenuRadioGroup: <TId extends string = string>(props: MenuRadioGroupProps<TId> & RefAttributes<HTMLDivElement>) => ReactElement | null;
+/** A labelled section of rows. */
+export declare const MenuGroup: import("react").ForwardRefExoticComponent<MenuGroupProps & RefAttributes<HTMLDivElement>>;
+/** A hairline between rows; renders nothing while a search term is set. */
+export declare const MenuSeparator: import("react").ForwardRefExoticComponent<MenuSeparatorProps & RefAttributes<HTMLDivElement>>;
+/**
+ * @internal Shared by Menu and ContextMenu; apps use those. The menu engine: a Popover in `MENU`
+ * role (or `DIALOG` around a search field) holding the rows, opened by `popoverTrigger`.
+ */
+export declare const MenuRoot: import("react").ForwardRefExoticComponent<MenuRootProps & RefAttributes<HTMLDivElement>>;
+/** A menu button: a trigger that opens a list of commands, navigated with arrow keys and typeahead. */
+declare const Menu: import("react").ForwardRefExoticComponent<MenuProps & RefAttributes<HTMLDivElement>>;
+export default Menu;