@commercetools/nimbus 1.0.1 → 2.0.1-rc1

package/dist/dialog.d.ts

@@ -1,40 +1,491 @@
-import { Dialog as Dialog_2 } from '@chakra-ui/react/dialog';
+import { AriaButtonProps } from 'react-aria';
+import { DialogBodyProps as DialogBodyProps_2 } from './dialog.types';
+import { DialogCloseTriggerProps as DialogCloseTriggerProps_2 } from './dialog.types';
+import { DialogContentProps as DialogContentProps_2 } from './dialog.types';
+import { DialogFooterProps as DialogFooterProps_2 } from './dialog.types';
+import { DialogHeaderProps as DialogHeaderProps_2 } from './dialog.types';
+import { DialogRootProps as DialogRootProps_2 } from './dialog.types';
+import { DialogTitleProps as DialogTitleProps_2 } from './dialog.types';
+import { DialogTriggerProps as DialogTriggerProps_2 } from './dialog.types';
+import { HTMLChakraProps } from '@chakra-ui/react';
 import { JSX } from 'react/jsx-runtime';
+import { ModalOverlayProps } from 'react-aria-components';
+import { RecipeProps } from '@chakra-ui/react';
+import { SlotRecipeProps } from '@chakra-ui/react';
+import { UnstyledProp } from '@chakra-ui/react';
+
+declare type ButtonProps = Omit<ButtonRootSlotProps, keyof AriaButtonProps> & AriaButtonProps & {
+    /**
+     * Data attributes for testing or custom metadata
+     */
+    [key: `data-${string}`]: unknown;
+    /**
+     * Slot name for React Aria Components composition
+     */
+    slot?: string | null | undefined;
+    /**
+     * Ref forwarding to the button element
+     */
+    ref?: React.Ref<HTMLButtonElement>;
+};
+
+declare type ButtonRecipeProps = {
+    /**
+     * Size variant of the button
+     * @default "md"
+     */
+    size?: RecipeProps<"button">["size"];
+    /**
+     * Visual style variant of the button
+     * @default "subtle"
+     */
+    variant?: RecipeProps<"button">["variant"];
+    /**
+     * Color tone palette for the button
+     */
+    tone?: RecipeProps<"button">["tone"];
+} & UnstyledProp;
+
+declare type ButtonRootSlotProps = Omit<HTMLChakraProps<"button", ButtonRecipeProps>, "slot"> & {
+    slot?: string | null | undefined;
+};
 
 /**
- * # Dialog
+ * Dialog
+ * ============================================================
+ * A foundational dialog component for overlays that require user attention.
+ * Built with React Aria Components for accessibility and WCAG 2.1 AA compliance.
  *
- * displays a dialog
+ * Features:
+ * - Controlled and uncontrolled modes
+ * - Customizable placement, size, and animations
+ * - Focus management and keyboard navigation
+ * - Click-outside and Escape key dismissal
+ * - Portal rendering support
+ * - Backdrop overlay with animations
  *
- * @see {@link https://nimbus-documentation.vercel.app/components/feedback/dialog}
+ * @example
+ * ```tsx
+ * <Dialog.Root>
+ *   <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+ *   <Dialog.Content size="md" placement="center">
+ *     <Dialog.Header>
+ *       <Dialog.Title>Dialog Title</Dialog.Title>
+ *       <Dialog.CloseTrigger>×</Dialog.CloseTrigger>
+ *     </Dialog.Header>
+ *     <Dialog.Body>
+ *       Dialog content goes here
+ *     </Dialog.Body>
+ *     <Dialog.Footer>
+ *       <button>Cancel</button>
+ *       <button>Save</button>
+ *     </Dialog.Footer>
+ *   </Dialog.Content>
+ * </Dialog.Root>
+ * ```
  *
- * @experimental This component is experimental and may change or be removed in future versions.
+ * @see https://nimbus-documentation.vercel.app/components/feedback/dialog
  */
-export declare const Dialog: DialogComponents;
+export declare const Dialog: {
+    /**
+     * # Dialog.Root
+     *
+     * The root component that provides context and state management for the dialog.
+     * Uses React Aria's DialogTrigger for accessibility and keyboard interaction.
+     *
+     * This component must wrap all dialog parts (Trigger, Content, etc.) and provides
+     * the dialog open/close state and variant styling context.
+     *
+     * @example
+     * ```tsx
+     * <Dialog.Root>
+     *   <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+     *   <Dialog.Content>
+     *     <Dialog.Header>
+     *       <Dialog.Title>Dialog Title</Dialog.Title>
+     *     </Dialog.Header>
+     *     <Dialog.Body>Dialog content</Dialog.Body>
+     *   </Dialog.Content>
+     * </Dialog.Root>
+     * ```
+     */
+    Root: {
+        (props: DialogRootProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Dialog.Trigger
+     *
+     * The trigger element that opens the dialog when activated.
+     * Uses React Aria's Button for accessibility and keyboard support.
+     *
+     * @example
+     * ```tsx
+     * <Dialog.Root>
+     *   <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+     *   <Dialog.Content>...</Dialog.Content>
+     * </Dialog.Root>
+     * ```
+     */
+    Trigger: {
+        ({ ref: forwardedRef, children, asChild, ...props }: DialogTriggerProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Dialog.Content
+     *
+     * The main dialog content container that wraps React Aria's Modal and Dialog.
+     * Handles portalling, backdrop, positioning, and content styling.
+     *
+     * This component creates the dialog overlay, positions the content, and provides
+     * accessibility features like focus management and keyboard dismissal.
+     *
+     * @example
+     * ```tsx
+     * <Dialog.Root>
+     *   <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+     *   <Dialog.Content size="md" placement="center">
+     *     <Dialog.Header>
+     *       <Dialog.Title>Title</Dialog.Title>
+     *     </Dialog.Header>
+     *     <Dialog.Body>Content</Dialog.Body>
+     *     <Dialog.Footer>Actions</Dialog.Footer>
+     *   </Dialog.Content>
+     * </Dialog.Root>
+     * ```
+     */
+    Content: {
+        (props: DialogContentProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Dialog.Header
+     *
+     * The header section of the dialog content.
+     * Typically contains the title and close button.
+     *
+     * @example
+     * ```tsx
+     * <Dialog.Content>
+     *   <Dialog.Header>
+     *     <Dialog.Title>Dialog Title</Dialog.Title>
+     *     <Dialog.CloseTrigger />
+     *   </Dialog.Header>
+     *   <Dialog.Body>...</Dialog.Body>
+     * </Dialog.Content>
+     * ```
+     */
+    Header: {
+        (props: DialogHeaderProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Dialog.Body
+     *
+     * The main body content section of the dialog.
+     * Contains the primary dialog content and handles overflow/scrolling.
+     *
+     * @example
+     * ```tsx
+     * <Dialog.Content>
+     *   <Dialog.Header>...</Dialog.Header>
+     *   <Dialog.Body>
+     *     <p>This is the main content of the dialog.</p>
+     *   </Dialog.Body>
+     *   <Dialog.Footer>...</Dialog.Footer>
+     * </Dialog.Content>
+     * ```
+     */
+    Body: {
+        (props: DialogBodyProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Dialog.Footer
+     *
+     * The footer section of the dialog, typically containing action buttons.
+     * Provides consistent spacing and alignment for dialog actions.
+     *
+     * @example
+     * ```tsx
+     * <Dialog.Content>
+     *   <Dialog.Header>...</Dialog.Header>
+     *   <Dialog.Body>...</Dialog.Body>
+     *   <Dialog.Footer>
+     *     <Button variant="outline">Cancel</Button>
+     *     <Button>Confirm</Button>
+     *   </Dialog.Footer>
+     * </Dialog.Content>
+     * ```
+     */
+    Footer: {
+        (props: DialogFooterProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Dialog.Title
+     *
+     * The accessible title element for the dialog.
+     * Uses React Aria's Heading for proper accessibility and screen reader support.
+     *
+     * @example
+     * ```tsx
+     * <Dialog.Content>
+     *   <Dialog.Header>
+     *     <Dialog.Title>Confirm Action</Dialog.Title>
+     *   </Dialog.Header>
+     *   <Dialog.Body>...</Dialog.Body>
+     * </Dialog.Content>
+     * ```
+     */
+    Title: {
+        (props: DialogTitleProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Dialog.CloseTrigger
+     *
+     * A button that closes the dialog when activated.
+     * Displays an IconButton with a close (X) icon by default.
+     *
+     * The component automatically handles the close behavior through React Aria's
+     * context, so no additional onPress handler is needed.
+     *
+     * @example
+     * ```tsx
+     * <Dialog.Root>
+     *   <Dialog.Trigger>Open Dialog</Dialog.Trigger>
+     *   <Dialog.Content>
+     *     <Dialog.Header>
+     *       <Dialog.Title>Title</Dialog.Title>
+     *       <Dialog.CloseTrigger aria-label="Close dialog" />
+     *     </Dialog.Header>
+     *     <Dialog.Body>Content</Dialog.Body>
+     *   </Dialog.Content>
+     * </Dialog.Root>
+     * ```
+     */
+    CloseTrigger: {
+        (props: DialogCloseTriggerProps_2): JSX.Element;
+        displayName: string;
+    };
+};
 
-declare interface DialogComponents {
-    Root: typeof Dialog_2.Root;
-    Trigger: typeof Dialog_2.Trigger;
-    Content: typeof DialogContent;
-    Backdrop: typeof Dialog_2.Backdrop;
-    Positioner: typeof Dialog_2.Positioner;
-    Title: typeof Dialog_2.Title;
-    Description: typeof Dialog_2.Description;
-    Body: typeof Dialog_2.Body;
-    Footer: typeof Dialog_2.Footer;
-    Header: typeof Dialog_2.Header;
-    CloseTrigger: typeof Dialog_2.CloseTrigger;
-    ActionTrigger: typeof Dialog_2.ActionTrigger;
-}
+/**
+ * Props for the Dialog.Body component
+ *
+ * The main body content section of the dialog.
+ */
+export declare type DialogBodyProps = DialogBodySlotProps & {
+    /**
+     * The body content
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the dialog body
+     */
+    ref?: React.Ref<HTMLDivElement>;
+};
 
-declare const DialogContent: (props: DialogContentProps) => JSX.Element;
+export declare type DialogBodySlotProps = HTMLChakraProps<"div">;
 
-declare interface DialogContentProps extends Dialog_2.ContentProps {
-    portalled?: boolean;
-    portalRef?: React.RefObject<HTMLElement>;
-    backdrop?: boolean;
-    ref?: React.Ref<HTMLDivElement>;
-}
+/**
+ * Props for the Dialog.CloseTrigger component
+ *
+ * A button that closes the dialog when activated.
+ * Displays an IconButton with an X icon by default.
+ */
+export declare type DialogCloseTriggerProps = Omit<IconButtonProps, "aria-label"> & {
+    /**
+     * Accessible label for the close button
+     * @default "Close dialog"
+     */
+    "aria-label"?: string;
+};
+
+export declare type DialogCloseTriggerSlotProps = HTMLChakraProps<"div">;
+
+/**
+ * Props for the Dialog.Content component
+ *
+ * The main dialog content container that wraps the React Aria Dialog and Dialog.
+ * Configuration (size, placement, etc.) is inherited from Dialog.Root via context.
+ */
+export declare type DialogContentProps = DialogModalOverlaySlotProps & {
+    /**
+     * The dialog content
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the dialog content
+     */
+    ref?: React.RefObject<HTMLDivElement>;
+};
+
+export declare type DialogContentSlotProps = HTMLChakraProps<"div">;
+
+/**
+ * Props for the Dialog.Footer component
+ *
+ * The footer section of the dialog, typically containing action buttons.
+ */
+export declare type DialogFooterProps = DialogFooterSlotProps & {
+    /**
+     * The footer content (usually buttons)
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the dialog footer
+     */
+    ref?: React.Ref<HTMLElement>;
+};
+
+export declare type DialogFooterSlotProps = HTMLChakraProps<"footer">;
+
+/**
+ * Props for the Dialog.Header component
+ *
+ * The header section of the dialog content.
+ */
+export declare type DialogHeaderProps = DialogHeaderSlotProps & {
+    /**
+     * The header content
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the dialog header
+     */
+    ref?: React.Ref<HTMLElement>;
+};
+
+export declare type DialogHeaderSlotProps = HTMLChakraProps<"header">;
+
+export declare type DialogModalOverlaySlotProps = HTMLChakraProps<"div">;
+
+export declare type DialogModalSlotProps = HTMLChakraProps<"div">;
+
+declare type DialogRecipeProps = {
+    /** Placement of the dialog in the viewport */
+    placement?: SlotRecipeProps<"dialog">["placement"];
+    /** How scrolling behavior is handled when content overflows */
+    scrollBehavior?: SlotRecipeProps<"dialog">["scrollBehavior"];
+};
+
+/**
+ * Props for the Dialog.Root component
+ *
+ * The root component that provides context and state management for the dialog.
+ * Uses React Aria's DialogTrigger for accessibility and state management.
+ *
+ * This component handles configuration through recipe variants that are passed
+ * down to child components via context.
+ */
+export declare type DialogRootProps = DialogRootSlotProps & {
+    /**
+     * The children components (Trigger, Content, etc.)
+     */
+    children: React.ReactNode;
+    /**
+     * Whether the dialog is open (controlled mode)
+     */
+    isOpen?: boolean;
+    /**
+     * Whether the dialog is open by default (uncontrolled mode)
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Whether the dialog can be dismissed by clicking the backdrop or pressing Escape.
+     * If true, clicking outside the dialog or pressing Escape will close it.
+     * @default true
+     */
+    isDismissable?: ModalOverlayProps["isDismissable"];
+    /**
+     * Whether keyboard dismissal (Escape key) is disabled.
+     * If true, pressing Escape will NOT close the dialog.
+     * @default false
+     */
+    isKeyboardDismissDisabled?: ModalOverlayProps["isKeyboardDismissDisabled"];
+    /**
+     * Function to determine whether the dialog should close when interacting outside.
+     * Receives the event and returns true to allow closing, false to prevent.
+     */
+    shouldCloseOnInteractOutside?: ModalOverlayProps["shouldCloseOnInteractOutside"];
+    /**
+     * Callback fired when the dialog open state changes
+     * @param isOpen - Whether the dialog is now open
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    /** A Title for the dialog, optional, as long as the Dialog.Title component is user
+     * or there is a Heading component used inside the Dialog with
+     * a `slot`-property set to `title`.
+     */
+    "aria-label"?: string;
+};
+
+export declare type DialogRootSlotProps = HTMLChakraProps<"div", DialogRecipeProps>;
+
+/**
+ * Scroll behavior variants for the dialog
+ */
+export declare type DialogScrollBehavior = "inside" | "outside";
+
+/**
+ * Props for the Dialog.Title component
+ *
+ * The accessible title element for the dialog.
+ */
+export declare type DialogTitleProps = DialogTitleSlotProps & {
+    /**
+     * The title text
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the dialog title
+     */
+    ref?: React.Ref<HTMLHeadingElement>;
+};
+
+export declare type DialogTitleSlotProps = HTMLChakraProps<"h2">;
+
+/**
+ * Props for the Dialog.Trigger component
+ *
+ * The trigger element that opens the dialog when activated.
+ */
+export declare type DialogTriggerProps = DialogTriggerSlotProps & {
+    /**
+     * The trigger content
+     */
+    children: React.ReactNode;
+    /**
+     * Whether to render as a child element (use children directly as the trigger)
+     * @default false
+     */
+    asChild?: boolean;
+    /**
+     * Whether the trigger is disabled
+     * @default false
+     */
+    isDisabled?: boolean;
+    /**
+     * The ref to the trigger html-button
+     */
+    ref?: React.RefObject<HTMLButtonElement>;
+};
+
+export declare type DialogTriggerSlotProps = HTMLChakraProps<"button">;
+
+declare type IconButtonProps = ButtonProps & {
+    /**
+     * Required accessible label explaining the intended action
+     */
+    "aria-label": string;
+    /**
+     * Ref forwarding to the button element
+     */
+    ref?: React.Ref<HTMLButtonElement>;
+};
 
 export { }