@commercetools/nimbus 1.0.1 → 2.0.1-rc1

package/dist/drawer.d.ts

@@ -0,0 +1,590 @@
+import { AriaButtonProps } from 'react-aria';
+import { DrawerBodyProps as DrawerBodyProps_2 } from './drawer.types';
+import { DrawerCloseTriggerProps as DrawerCloseTriggerProps_2 } from './drawer.types';
+import { DrawerContentProps as DrawerContentProps_2 } from './drawer.types';
+import { DrawerFooterProps as DrawerFooterProps_2 } from './drawer.types';
+import { DrawerHeaderProps as DrawerHeaderProps_2 } from './drawer.types';
+import { DrawerRootProps as DrawerRootProps_2 } from './drawer.types';
+import { DrawerTitleProps as DrawerTitleProps_2 } from './drawer.types';
+import { DrawerTriggerProps as DrawerTriggerProps_2 } from './drawer.types';
+import { HTMLChakraProps } from '@chakra-ui/react/styled-system';
+import { HTMLChakraProps as HTMLChakraProps_2 } from '@chakra-ui/react';
+import { JSX } from 'react/jsx-runtime';
+import { ModalOverlayProps } from 'react-aria-components';
+import { RecipeProps } from '@chakra-ui/react';
+import { RecipeVariantProps } from '@chakra-ui/react';
+import { SlotRecipeDefinition } 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_2<"button", ButtonRecipeProps>, "slot"> & {
+    slot?: string | null | undefined;
+};
+
+/**
+ * Drawer
+ * ============================================================
+ * A foundational drawer component for overlays that require user attention.
+ * Built for accessibility and WCAG 2.1 AA compliance.
+ *
+ * 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
+ *
+ * @example
+ * ```tsx
+ * <Drawer.Root>
+ *   <Drawer.Trigger>Open Drawer</Drawer.Trigger>
+ *   <Drawer.Content size="md" placement="center">
+ *     <Drawer.Header>
+ *       <Drawer.Title>Drawer Title</Drawer.Title>
+ *       <Drawer.CloseTrigger>×</Drawer.CloseTrigger>
+ *     </Drawer.Header>
+ *     <Drawer.Body>
+ *       Drawer content goes here
+ *     </Drawer.Body>
+ *     <Drawer.Footer>
+ *       <button>Cancel</button>
+ *       <button>Save</button>
+ *     </Drawer.Footer>
+ *   </Drawer.Content>
+ * </Drawer.Root>
+ * ```
+ * @see https://nimbus-documentation.vercel.app/components/feedback/drawer
+ */
+export declare const Drawer: {
+    /**
+     * # Drawer.Root
+     *
+     * The root component that provides context and state management for the drawer.
+     * Handles accessibility and keyboard interaction.
+     *
+     * This component must wrap all drawer parts (Trigger, Content, etc.) and provides
+     * the drawer open/close state and variant styling context.
+     *
+     * @example
+     * ```tsx
+     * <Drawer.Root>
+     *   <Drawer.Trigger>Open Drawer</Drawer.Trigger>
+     *   <Drawer.Content>
+     *     <Drawer.Header>
+     *       <Drawer.Title>Drawer Title</Drawer.Title>
+     *     </Drawer.Header>
+     *     <Drawer.Body>Drawer content</Drawer.Body>
+     *   </Drawer.Content>
+     * </Drawer.Root>
+     * ```
+     */
+    Root: {
+        (props: DrawerRootProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Drawer.Trigger
+     *
+     * The trigger element that opens the drawer when activated.
+     * Provides accessibility and keyboard support.
+     *
+     * @example
+     * ```tsx
+     * <Drawer.Root>
+     *   <Drawer.Trigger>Open Drawer</Drawer.Trigger>
+     *   <Drawer.Content>...</Drawer.Content>
+     * </Drawer.Root>
+     * ```
+     */
+    Trigger: {
+        ({ ref: forwardedRef, children, asChild, ...props }: DrawerTriggerProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Drawer.Content
+     *
+     * The main drawer content container that handles portalling, backdrop,
+     * positioning, and content styling.
+     *
+     * This component creates the drawer overlay, positions the content, and provides
+     * accessibility features like focus management and keyboard dismissal.
+     *
+     * @example
+     * ```tsx
+     * <Drawer.Root>
+     *   <Drawer.Trigger>Open Drawer</Drawer.Trigger>
+     *   <Drawer.Content size="md" placement="center">
+     *     <Drawer.Header>
+     *       <Drawer.Title>Title</Drawer.Title>
+     *     </Drawer.Header>
+     *     <Drawer.Body>Content</Drawer.Body>
+     *     <Drawer.Footer>Actions</Drawer.Footer>
+     *   </Drawer.Content>
+     * </Drawer.Root>
+     * ```
+     */
+    Content: {
+        (props: DrawerContentProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Drawer.Header
+     *
+     * The header section of the drawer content.
+     * Typically contains the title and close button.
+     *
+     * @example
+     * ```tsx
+     * <Drawer.Content>
+     *   <Drawer.Header>
+     *     <Drawer.Title>Drawer Title</Drawer.Title>
+     *     <Drawer.CloseTrigger />
+     *   </Drawer.Header>
+     *   <Drawer.Body>...</Drawer.Body>
+     * </Drawer.Content>
+     * ```
+     */
+    Header: {
+        (props: DrawerHeaderProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Drawer.Body
+     *
+     * The main body content section of the drawer.
+     * Contains the primary drawer content and handles overflow/scrolling.
+     *
+     * @example
+     * ```tsx
+     * <Drawer.Content>
+     *   <Drawer.Header>...</Drawer.Header>
+     *   <Drawer.Body>
+     *     <p>This is the main content of the drawer.</p>
+     *   </Drawer.Body>
+     *   <Drawer.Footer>...</Drawer.Footer>
+     * </Drawer.Content>
+     * ```
+     */
+    Body: {
+        (props: DrawerBodyProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Drawer.Footer
+     *
+     * The footer section of the drawer, typically containing action buttons.
+     * Provides consistent spacing and alignment for drawer actions.
+     *
+     * @example
+     * ```tsx
+     * <Drawer.Content>
+     *   <Drawer.Header>...</Drawer.Header>
+     *   <Drawer.Body>...</Drawer.Body>
+     *   <Drawer.Footer>
+     *     <Button variant="outline">Cancel</Button>
+     *     <Button>Confirm</Button>
+     *   </Drawer.Footer>
+     * </Drawer.Content>
+     * ```
+     */
+    Footer: {
+        (props: DrawerFooterProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Drawer.Title
+     *
+     * The accessible title element for the drawer.
+     * Provides proper accessibility and screen reader support.
+     *
+     * @example
+     * ```tsx
+     * <Drawer.Content>
+     *   <Drawer.Header>
+     *     <Drawer.Title>Confirm Action</Drawer.Title>
+     *   </Drawer.Header>
+     *   <Drawer.Body>...</Drawer.Body>
+     * </Drawer.Content>
+     * ```
+     */
+    Title: {
+        (props: DrawerTitleProps_2): JSX.Element;
+        displayName: string;
+    };
+    /**
+     * # Drawer.CloseTrigger
+     *
+     * A button that closes the drawer when activated.
+     * Displays an IconButton with a close (X) icon by default.
+     *
+     * The component automatically handles the close behavior,
+     * so no additional onPress handler is needed.
+     *
+     * @example
+     * ```tsx
+     * <Drawer.Root>
+     *   <Drawer.Trigger>Open Drawer</Drawer.Trigger>
+     *   <Drawer.Content>
+     *     <Drawer.Header>
+     *       <Drawer.Title>Title</Drawer.Title>
+     *       <Drawer.CloseTrigger aria-label="Close drawer" />
+     *     </Drawer.Header>
+     *     <Drawer.Body>Content</Drawer.Body>
+     *   </Drawer.Content>
+     * </Drawer.Root>
+     * ```
+     */
+    CloseTrigger: {
+        (props: DrawerCloseTriggerProps_2): JSX.Element;
+        displayName: string;
+    };
+};
+
+export declare type DrawerBackdropSlotProps = HTMLChakraProps<"div">;
+
+/**
+ * Props for the Drawer.Body component
+ *
+ * The main body content section of the drawer.
+ */
+export declare type DrawerBodyProps = DrawerBodySlotProps & {
+    /**
+     * The body content
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the drawer body
+     */
+    ref?: React.Ref<HTMLDivElement>;
+};
+
+export declare type DrawerBodySlotProps = HTMLChakraProps<"div">;
+
+/**
+ * Props for the Drawer.CloseTrigger component
+ *
+ * A button that closes the drawer when activated.
+ * Displays an IconButton with an X icon by default.
+ */
+export declare type DrawerCloseTriggerProps = Omit<IconButtonProps, "aria-label"> & {
+    /**
+     * Accessible label for the close button
+     * @default "Close drawer"
+     */
+    "aria-label"?: string;
+};
+
+export declare type DrawerCloseTriggerSlotProps = HTMLChakraProps<"div">;
+
+/**
+ * Props for the Drawer.Content component
+ *
+ * The main drawer content container that wraps the React Aria Dialog and Dialog.
+ * Configuration (size, placement, etc.) is inherited from Drawer.Root via context.
+ */
+export declare type DrawerContentProps = DrawerBackdropSlotProps & {
+    /**
+     * The drawer content
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the drawer content
+     */
+    ref?: React.RefObject<HTMLDivElement>;
+};
+
+export declare type DrawerContentSlotProps = HTMLChakraProps<"div">;
+
+/**
+ * Props for the Drawer.Footer component
+ *
+ * The footer section of the drawer, typically containing action buttons.
+ */
+export declare type DrawerFooterProps = DrawerFooterSlotProps & {
+    /**
+     * The footer content (usually buttons)
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the drawer footer
+     */
+    ref?: React.Ref<HTMLElement>;
+};
+
+export declare type DrawerFooterSlotProps = HTMLChakraProps<"footer">;
+
+/**
+ * Props for the Drawer.Header component
+ *
+ * The header section of the drawer content.
+ */
+export declare type DrawerHeaderProps = DrawerHeaderSlotProps & {
+    /**
+     * The header content
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the drawer header
+     */
+    ref?: React.Ref<HTMLElement>;
+};
+
+export declare type DrawerHeaderSlotProps = HTMLChakraProps<"header">;
+
+/**
+ * Props for the Drawer.Root component
+ *
+ * The root component that provides context and state management for the drawer.
+ * 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 DrawerRootProps = RecipeVariantProps<typeof drawerSlotRecipe> & {
+    /**
+     * The children components (Trigger, Content, etc.)
+     */
+    children: React.ReactNode;
+    /**
+     * Whether the drawer is open (controlled mode)
+     */
+    isOpen?: boolean;
+    /**
+     * Whether the drawer is open by default (uncontrolled mode)
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Whether the drawer can be dismissed by clicking the backdrop or pressing Escape.
+     * If true, clicking outside the drawer 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 drawer.
+     * @default false
+     */
+    isKeyboardDismissDisabled?: ModalOverlayProps["isKeyboardDismissDisabled"];
+    /**
+     * Function to determine whether the drawer should close when interacting outside.
+     * Receives the event and returns true to allow closing, false to prevent.
+     */
+    shouldCloseOnInteractOutside?: ModalOverlayProps["shouldCloseOnInteractOutside"];
+    /**
+     * Callback fired when the drawer open state changes
+     * @param isOpen - Whether the drawer is now open
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Whether to show the backdrop overlay behind the drawer
+     * @default false
+     */
+    showBackdrop?: boolean;
+    /** A Title for the drawer, optional, as long as the Drawer.Title component is used
+     * or there is a Heading component used inside the Drawer with
+     * a `slot`-property set to `title`.
+     */
+    "aria-label"?: string;
+};
+
+export declare type DrawerRootSlotProps = HTMLChakraProps<"div">;
+
+/**
+ * Drawer recipe - styling for Drawer component overlays
+ * Supports center positioning, various sizes, and motion presets for accessible drawer experiences
+ */
+declare const drawerSlotRecipe: SlotRecipeDefinition<"content" | "body" | "modal" | "trigger" | "title" | "header" | "footer" | "modalOverlay" | "closeTrigger", {
+showBackdrop: {
+true: {
+modalOverlay: {
+bg: {
+_dark: "bg/20";
+_light: "fg/20";
+};
+backdropFilter: "blur({sizes.100})";
+};
+};
+false: {
+modalOverlay: {
+bg: "transparent";
+};
+};
+};
+placement: {
+left: {
+modal: {
+justifyContent: "flex-start";
+alignItems: "stretch";
+"&[data-entering]": {
+animationName: "slide-from-left-full";
+};
+"&[data-exiting]": {
+animationName: "slide-to-left-full";
+};
+};
+content: {
+"--drawer-base-margin": number;
+mx: number;
+height: "100vh";
+maxH: "100vh";
+borderRadius: number;
+};
+};
+right: {
+modal: {
+justifyContent: "flex-end";
+alignItems: "stretch";
+"&[data-entering]": {
+animationName: "slide-from-right-full";
+};
+"&[data-exiting]": {
+animationName: "slide-to-right-full";
+};
+};
+content: {
+"--drawer-base-margin": number;
+mx: number;
+height: "100vh";
+maxH: "100vh";
+borderRadius: number;
+};
+};
+top: {
+modal: {
+alignItems: "flex-start";
+justifyContent: "stretch";
+"&[data-entering]": {
+animationName: "slide-from-top-full";
+};
+"&[data-exiting]": {
+animationName: "slide-to-top-full";
+};
+};
+content: {
+"--drawer-base-margin": number;
+mx: number;
+width: "100vw";
+borderRadius: number;
+};
+};
+bottom: {
+modal: {
+alignItems: "flex-end";
+justifyContent: "stretch";
+"&[data-entering]": {
+animationName: "slide-from-bottom-full";
+};
+"&[data-exiting]": {
+animationName: "slide-to-bottom-full";
+};
+};
+content: {
+"--drawer-base-margin": number;
+mx: number;
+width: "100vw";
+borderRadius: number;
+};
+};
+};
+}>;
+
+/**
+ * Props for the Drawer.Title component
+ *
+ * The accessible title element for the drawer.
+ */
+export declare type DrawerTitleProps = DrawerTitleSlotProps & {
+    /**
+     * The title text
+     */
+    children: React.ReactNode;
+    /**
+     * The ref to the drawer title
+     */
+    ref?: React.Ref<HTMLHeadingElement>;
+};
+
+export declare type DrawerTitleSlotProps = HTMLChakraProps<"h2">;
+
+/**
+ * Props for the Drawer.Trigger component
+ *
+ * The trigger element that opens the drawer when activated.
+ */
+export declare type DrawerTriggerProps = DrawerTriggerSlotProps & {
+    /**
+     * 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 DrawerTriggerSlotProps = 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 { }
+
+
+declare module "slate" {
+    interface CustomTypes {
+        Editor: BaseEditor & ReactEditor & HistoryEditor;
+        Element: CustomElement;
+        Text: CustomText;
+    }
+}