@protonradio/proton-ui 0.11.9 → 0.11.10-beta.2

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 import { AriaAttributes } from 'react';
 import { AriaDialogProps } from '@react-aria/dialog';
+import { AriaPopoverProps } from '@react-aria/overlays';
 import { default as default_2 } from 'react';
+import { DOMProps } from '@react-types/shared';
 import { ForwardRefExoticComponent } from 'react';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { MouseEvent as MouseEvent_2 } from 'react';
+import { OverlayTriggerProps } from '@react-stately/overlays';
+import { OverlayTriggerState } from '@react-stately/overlays';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
 import { RefAttributes } from 'react';
@@ -18,9 +22,9 @@ import { TooltipTriggerComponentProps } from 'react-aria-components';
  * API:
  *  - {@link ActionMenuProps}
  */
-export declare const ActionMenu: ({ isOpen, actions, children, showCancel, cancelButtonText, selectionMode, selectedKeys, disabledKeys, onSelectionChange, onClose, title, "data-testid": testId, }: ActionMenuProps) => JSX_2.Element;
+export declare const ActionMenu: ({ isOpen, selectionMode, selectedKeys, defaultSelectedKeys, disabledKeys, children, showCancel, cancelButtonText, actions, title, onSelectionChange, onClose, "data-testid": testId, }: ActionMenuProps) => JSX_2.Element;
 
-export declare interface ActionMenuAction {
+declare interface ActionMenuAction {
     key: string;
     label?: ReactNode;
     description?: ReactNode;
@@ -42,9 +46,9 @@ declare interface ActionMenuProps {
     }) => ReactNode);
     /** The test id of the menu */
     "data-testid"?: string;
-    /** The keys of the disabled items
-     * @default []
-     */
+    /** The keys of the default selected items */
+    defaultSelectedKeys?: string[];
+    /** The keys of the disabled items */
     disabledKeys?: string[];
     /** Whether the menu is open
      * @default false
@@ -59,7 +63,7 @@ declare interface ActionMenuProps {
     /** The selection mode of the menu
      * @default "single"
      */
-    selectionMode?: ActionMenuSelectionMode;
+    selectionMode?: "single" | "multiple" | "none";
     /** The keys of the selected items */
     selectedKeys?: string[];
     /** Whether to show the cancel button */
@@ -68,8 +72,6 @@ declare interface ActionMenuProps {
     title?: string;
 }
 
-export declare type ActionMenuSelectionMode = "single" | "multiple" | "none";
-
 /**
  * A badge component for displaying status, categories, or counts with various visual styles.
  *
@@ -598,7 +600,7 @@ declare interface MenuProps {
     /** Custom trigger component. If not provided, defaults to ellipsis icon.
      * - @prop triggerProps {@link TriggerProps}
      */
-    renderTrigger?: (triggerProps: MenuTriggerProps) => ReactNode;
+    renderTrigger?: (triggerProps: TriggerProps) => ReactNode;
     /** Size of the trigger icon
      * @default 24
      */
@@ -613,13 +615,13 @@ declare interface MenuProps {
      * @default false
      */
     disabled?: boolean;
-    /** Callback when the menu is closed */
+    /** Callback when menu closes */
     onClose?: () => void;
-    /** Test ID for the trigger button */
+    /** Test ID for the trigger component */
     triggerTestId?: string;
     /** Test ID for the menu */
     menuTestId?: string;
-    /** Callback when the selection changes */
+    /** Callback when a menu item is selected */
     onSelectionChange?: (key: string) => void;
     /** The key of the selected item */
     selectedKey?: string;
@@ -628,7 +630,7 @@ declare interface MenuProps {
 }
 
 /**
- * An uncontrolled component that displays either a popover menu or an action menu
+ * A component that displays either a popover menu or an action menu
  * depending on the screen size when the menu trigger is pressed.
  *
  * API:
@@ -636,12 +638,6 @@ declare interface MenuProps {
  */
 export declare function MenuTrigger({ renderTrigger, size, title, items, disabled, onClose, triggerTestId, menuTestId, onSelectionChange, selectedKey, disabledKeys, }: MenuProps): JSX_2.Element;
 
-export declare interface MenuTriggerProps {
-    disabled?: boolean;
-    isOpen?: boolean;
-    setIsOpen: (isOpen: boolean) => void;
-}
-
 export declare const Modal: (({ isOpen, onClose, title, subtitle, body, children, isOverlay, "data-testid": dataTestId, }: ModalProps) => JSX_2.Element) & {
     /**
      * Renders a h2 styled title
@@ -711,71 +707,44 @@ declare interface ModalProps {
 }
 
 /**
- * A popover component that handles positioning and supports controlled and uncontrolled modes.
+ * Popover is an unstyled popover component that handles positioning. It should be used
+ * with the Dialog component to provide a styled popover.
  *
  * A popover displays interactive content in context with a trigger element.
  * A tooltip displays a description of an element on hover or focus.
  *
+ * @see {@link usePopoverTrigger} for a complete usage example
+ *
  * API:
  *  - {@link PopoverProps}
+ *  - extends {@link AriaPopoverProps}
  */
-export declare function Popover({ trigger, children, open, defaultOpen, onOpenChange, side, align, arrow, constrainWidth, "data-testid": testId, }: PopoverProps): JSX_2.Element;
+export declare function Popover({ children, state, arrow, offset, ...props }: PopoverProps): JSX_2.Element;
 
 export declare namespace Popover {
     var displayName: string;
 }
 
-export declare type PopoverAlign = "start" | "center" | "end";
-
-declare interface PopoverProps {
+declare interface PopoverProps extends Omit<AriaPopoverProps, "popoverRef"> {
     /**
-     * The trigger element for the popover.
-     * @warning Do NOT pass a <button> element here. Use a span, div, or other non-button element.
-     * If a button is passed, an error will be thrown.
+     * Whether to show an arrow on the popover.
      */
-    trigger: default_2.ReactNode;
+    arrow?: boolean;
     /**
-     * The content of the popover.
+     * Content to display within the popover.
      */
     children: default_2.ReactNode;
     /**
-     * Constrain the width of the popover to the width of the trigger.
+     * Can optionally forward the ref to the popover.
      */
-    constrainWidth?: boolean;
+    popoverRef?: default_2.RefObject<HTMLDivElement>;
     /**
-     * Control open state (controlled mode).
+     * The `isOpen` state of the popover and the methods to toggle it.
+     * - type {@link OverlayTriggerState}
      */
-    open?: boolean;
-    /**
-     * Default open state (uncontrolled mode).
-     */
-    defaultOpen?: boolean;
-    /**
-     * Callback when open state changes.
-     */
-    onOpenChange?: (open: boolean) => void;
-    /**
-     * Popover side placement
-     * {@link PopoverSide}
-     */
-    side?: PopoverSide;
-    /**
-     * Popover alignment
-     * {@link PopoverAlign}
-     */
-    align?: PopoverAlign;
-    /**
-     * Show an arrow pointing to the trigger.
-     */
-    arrow?: boolean;
-    /**
-     * Test id for the popover content.
-     */
-    "data-testid"?: string;
+    state: OverlayTriggerState;
 }
 
-export declare type PopoverSide = "top" | "right" | "bottom" | "left";
-
 declare type ProtonColorScale = {
     SUPER_DARK: string;
     DARK: string;
@@ -1172,7 +1141,6 @@ declare interface ThemeContextType {
     style: ProtonStyleSheet;
     palette: ProtonPalette;
     hasPalette?: boolean;
-    themeProviderRef?: default_2.RefObject<HTMLDivElement>;
 }
 
 export declare const ThemeProvider: default_2.FC<ThemeProviderProps>;
@@ -1253,6 +1221,54 @@ export declare interface TooltipTriggerProps extends TooltipProps, TooltipTrigge
     disableTriggerClick?: boolean;
 }
 
+declare interface TriggerProps {
+    disabled?: boolean;
+    isOpen?: boolean;
+    setIsOpen?: (isOpen: boolean) => void;
+    triggerRef: React.RefObject<HTMLButtonElement>;
+}
+
+/**
+ * Hook for creating a popover trigger. This hook manages the state and events for the popover
+ * and popover trigger. For examples see Popover.stories.tsx.
+ *
+ * API:
+ *  - {@link OverlayTriggerProps}
+ *
+ * @example
+ * ```tsx
+ * let { buttonProps, overlayProps, buttonRef, state } = usePopoverTrigger();
+ *
+ * return (
+ *   <div>
+ *     <button {...buttonProps} ref={buttonRef}>
+ *       Trigger
+ *     </button>
+ *
+ *     {state.isOpen && (
+ *       <Popover
+ *         state={state}
+ *         triggerRef={buttonRef}
+ *         arrow={props.arrow}
+ *         offset={props.offset}
+ *         placement={props.placement}
+ *       >
+ *         <Dialog {...overlayProps} title="Popover">
+ *           Here is some popover content
+ *         </Dialog>
+ *       </Popover>
+ *     )}
+ *   </div>
+ * );
+ * ```
+ */
+export declare function usePopoverTrigger(props?: OverlayTriggerProps): {
+    buttonProps: default_2.ButtonHTMLAttributes<HTMLButtonElement>;
+    overlayProps: DOMProps;
+    buttonRef: default_2.MutableRefObject<HTMLButtonElement>;
+    state: OverlayTriggerState;
+};
+
 export declare const useTheme: () => ThemeContextType;
 
 /**