@sproutsocial/seeds-react-modal 1.1.1 → 2.0.0

package/dist/ModalAction-BB7qJtQj.d.ts

@@ -0,0 +1,445 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as styled_components from 'styled-components';
+import * as _sproutsocial_seeds_react_box from '@sproutsocial/seeds-react-box';
+import { TypeContainerProps, TypeBoxProps } from '@sproutsocial/seeds-react-box';
+import * as React from 'react';
+import * as Dialog from '@radix-ui/react-dialog';
+import { TypeIconName } from '@sproutsocial/seeds-react-icon';
+
+/**
+ * Props for ModalHeader component.
+ *
+ * Renders the modal's header with title and optional subtitle. Supports draggable functionality
+ * when the modal has draggable enabled.
+ *
+ * Note: This component only supports slots (title/subtitle props). For custom headers,
+ * use ModalCustomHeader instead.
+ */
+interface TypeModalHeaderProps extends TypeBoxProps {
+    /** Modal title text displayed as a headline */
+    title?: string;
+    /**
+     * Modal subtitle text.
+     *
+     * This is automatically wrapped in `Dialog.Description` from Radix UI,
+     * which provides accessible description text for screen readers. The subtitle
+     * provides additional context about the modal and is announced alongside
+     * the title when the dialog opens. Radix UI automatically connects this to
+     * the dialog via ARIA attributes (typically `aria-describedby` on the dialog root).
+     */
+    subtitle?: string;
+    /** Additional props for the Dialog.Title when title is provided */
+    titleProps?: Omit<React.ComponentPropsWithoutRef<typeof Dialog.Title>, "asChild" | "children">;
+    /**
+     * Additional props for the Dialog.Description when subtitle is provided.
+     *
+     * Dialog.Description provides accessible description text for the modal that
+     * screen readers announce when the dialog opens. It complements Dialog.Title
+     * by providing additional context about the modal. Radix UI automatically
+     * connects this to the dialog via ARIA attributes.
+     */
+    subtitleProps?: Omit<React.ComponentPropsWithoutRef<typeof Dialog.Description>, "asChild" | "children">;
+}
+/**
+ * Props for ModalFooter component.
+ *
+ * Provides automatic button wrapping and layout management. At least one action
+ * (cancelButton, primaryButton, or leftAction) must be provided.
+ *
+ * Note: This component only supports slots (button props). For custom footers,
+ * use ModalCustomFooter instead.
+ *
+ * @example
+ * // ✅ Valid - has primary button
+ * <ModalFooter primaryButton={<Button>Save</Button>} />
+ *
+ * @example
+ * // ✅ Valid - has cancel and primary
+ * <ModalFooter
+ *   cancelButton={<Button>Cancel</Button>}
+ *   primaryButton={<Button>Save</Button>}
+ * />
+ *
+ * @example
+ * // ✅ Valid - left action only
+ * <ModalFooter leftAction={<Button>Delete</Button>} />
+ *
+ * @example
+ * // ❌ TypeScript Error - no actions provided
+ * <ModalFooter />
+ */
+type TypeModalFooterProps = TypeBoxProps & ({
+    /** Primary action button - automatically wrapped in ModalCloseWrapper to close the modal */
+    primaryButton: React.ReactNode;
+    /** Cancel/secondary button - automatically wrapped in ModalCloseWrapper to close the modal */
+    cancelButton?: React.ReactNode;
+    /** Optional action on the far left (e.g., Delete button) - NOT automatically wrapped */
+    leftAction?: React.ReactNode;
+} | {
+    /** Primary action button - automatically wrapped in ModalCloseWrapper to close the modal */
+    primaryButton?: React.ReactNode;
+    /** Cancel/secondary button - automatically wrapped in ModalCloseWrapper to close the modal */
+    cancelButton: React.ReactNode;
+    /** Optional action on the far left (e.g., Delete button) - NOT automatically wrapped */
+    leftAction?: React.ReactNode;
+} | {
+    /** Primary action button - automatically wrapped in ModalCloseWrapper to close the modal */
+    primaryButton?: React.ReactNode;
+    /** Cancel/secondary button - automatically wrapped in ModalCloseWrapper to close the modal */
+    cancelButton?: React.ReactNode;
+    /** Optional action on the far left (e.g., Delete button) - NOT automatically wrapped */
+    leftAction: React.ReactNode;
+});
+/**
+ * Props for ModalBody component.
+ *
+ * Renders the scrollable main content area of the modal between the header and footer.
+ */
+interface TypeModalBodyProps extends TypeBoxProps {
+    /** The main content of the modal body */
+    children?: React.ReactNode;
+}
+/**
+ * Props for ModalDescription component.
+ *
+ * Wraps content with Radix UI's Dialog.Description for accessible modal descriptions
+ * that are announced by screen readers.
+ */
+interface TypeModalDescriptionProps extends TypeBoxProps {
+    /** The description text content */
+    children: React.ReactNode;
+    /** Additional props for the Dialog.Description */
+    descriptionProps?: Omit<React.ComponentPropsWithoutRef<typeof Dialog.Description>, "asChild" | "children">;
+}
+/** Common props shared by all modal variants */
+type TypeModalCommonProps = TypeContainerProps & Omit<React.ComponentPropsWithoutRef<"div">, keyof TypeContainerProps> & {
+    /** Controls whether the modal is open (controlled mode) */
+    open?: boolean;
+    /** Default open state for uncontrolled mode */
+    defaultOpen?: boolean;
+    /** body content of the modal */
+    children: React.ReactNode;
+    /** Callback when open state changes */
+    onOpenChange?: (open: boolean) => void;
+    /** The element that will trigger the modal when clicked.
+     *  Can be any React element like a button, link, or custom component. */
+    modalTrigger?: React.ReactElement<any>;
+    /** Simplified API: Modal description (automatically wrapped in Dialog.Description) */
+    description?: string;
+    /**
+     * Custom attributes to be added to the modals container
+     * Each key will be prepended with "data-" when rendered in the DOM
+     */
+    data?: Record<string, string | boolean | number>;
+    /** Optional quick actions to render on a modal side rail */
+    actions?: TypeModalActionProps[];
+    /** Accessible label for the close button in the rail (defaults to "Close") */
+    closeButtonAriaLabel?: string;
+};
+/**
+ * Base props with draggable and showOverlay relationship enforced.
+ *
+ * When draggable is true, showOverlay must be false or undefined because
+ * the overlay would block interaction with content behind the modal,
+ * defeating the purpose of being able to drag the modal aside.
+ */
+type TypeModalBaseProps = (TypeModalCommonProps & {
+    /** Enable draggable functionality */
+    draggable: true;
+    /**
+     * Whether to show the background overlay.
+     * Must be false when draggable is true to allow interaction with background content.
+     */
+    showOverlay?: false;
+}) | (TypeModalCommonProps & {
+    /** Enable draggable functionality */
+    draggable?: false;
+    /** Whether to show the background overlay (defaults to true) */
+    showOverlay?: boolean;
+});
+/**
+ * Modal props with title provided.
+ * aria-label is optional since Dialog.Title can serve as the accessible name.
+ */
+type TypeModalPropsWithTitle = TypeModalBaseProps & {
+    /** Simplified API: Modal title (creates ModalHeader automatically) */
+    title: string;
+    /**
+     * Simplified API: Modal subtitle (creates ModalHeader automatically).
+     *
+     * This is automatically wrapped in `Dialog.Description` from Radix UI,
+     * which provides accessible description text for screen readers. The subtitle
+     * provides additional context about the modal and is announced alongside
+     * the title when the dialog opens.
+     */
+    subtitle?: string;
+    /** Accessible label for the modal dialog (optional when title or subtitle is provided) */
+    "aria-label"?: string;
+};
+/**
+ * Modal props with subtitle provided but no title.
+ * aria-label is optional since Dialog.Description can help identify the modal.
+ */
+type TypeModalPropsWithSubtitleOnly = TypeModalBaseProps & {
+    /** Simplified API: Modal title (creates ModalHeader automatically) */
+    title?: never;
+    /**
+     * Simplified API: Modal subtitle (creates ModalHeader automatically).
+     *
+     * This is automatically wrapped in `Dialog.Description` from Radix UI,
+     * which provides accessible description text for screen readers. The subtitle
+     * provides additional context about the modal and is announced alongside
+     * the title when the dialog opens.
+     */
+    subtitle: string;
+    /** Accessible label for the modal dialog (optional when title or subtitle is provided) */
+    "aria-label"?: string;
+};
+/**
+ * Modal props without title or subtitle.
+ *
+ * **IMPORTANT**: When no header (title or subtitle) is provided,
+ * `aria-label` is REQUIRED for accessibility compliance.
+ *
+ * Without a visible header, screen readers need `aria-label` to identify
+ * what the modal dialog is about.
+ *
+ * @example
+ * // ✅ Valid - provides aria-label when no header
+ * <Modal aria-label="Delete confirmation dialog">
+ *   <p>Are you sure you want to delete this item?</p>
+ * </Modal>
+ *
+ * @example
+ * // ❌ Invalid - missing required aria-label
+ * <Modal>
+ *   <p>Are you sure you want to delete this item?</p>
+ * </Modal>
+ */
+type TypeModalPropsWithoutHeader = TypeModalBaseProps & {
+    /** Simplified API: Modal title (creates ModalHeader automatically) - not allowed when no header */
+    title?: never;
+    /** Simplified API: Modal subtitle (creates ModalHeader automatically) - not allowed when no header */
+    subtitle?: never;
+    /**
+     * **REQUIRED: aria-label must be provided when no title or subtitle is given**
+     *
+     * Accessible label for the modal dialog. This is required for accessibility
+     * when the modal has no visible header. Screen readers use this to announce
+     * what the modal is about.
+     *
+     * **Error**: If you see a TypeScript error saying this property is missing,
+     * it means you need to either:
+     * 1. Provide `aria-label` (required when no header), OR
+     * 2. Provide `title` or `subtitle` (which makes aria-label optional)
+     *
+     * If you have a title or subtitle, this prop is optional.
+     */
+    "aria-label": string;
+};
+/**
+ * Modal component props with discriminated union based on header presence.
+ *
+ * **Accessibility Requirements:**
+ * - ✅ **With header** (title or subtitle provided): `aria-label` is optional
+ * - ❌ **Without header** (no title, no subtitle): `aria-label` is **REQUIRED**
+ *
+ * TypeScript will error if you forget to provide `aria-label` when no header is present.
+ * This ensures accessibility compliance and better screen reader support.
+ *
+ * @example
+ * // ✅ Valid - has title, aria-label optional
+ * <Modal title="Delete Item" />
+ *
+ * @example
+ * // ✅ Valid - has subtitle only, aria-label optional
+ * <Modal subtitle="Confirmation" />
+ *
+ * @example
+ * // ✅ Valid - no header, aria-label provided
+ * <Modal aria-label="Delete confirmation dialog" />
+ *
+ * @example
+ * // ❌ TypeScript Error - no header and missing required aria-label
+ * <Modal /> // Error: Property 'aria-label' is missing
+ */
+type TypeModalProps = TypeModalPropsWithTitle | TypeModalPropsWithSubtitleOnly | TypeModalPropsWithoutHeader;
+/**
+ * Props for ModalRail component.
+ *
+ * Container for floating action buttons displayed alongside the modal.
+ */
+type TypeModalRailProps = {
+    /** ModalAction components to display in the rail */
+    children?: React.ReactNode;
+};
+/**
+ * Base props for modal action buttons.
+ *
+ * Extends standard button HTML attributes with modal-specific properties.
+ */
+type ModalActionBase = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> & {
+    /** Icon name from the Seeds icon set */
+    iconName?: TypeIconName;
+    /** Optional click handler; ignored for type "close" */
+    onClick?: () => void;
+    /** Accessible name for the action button */
+    "aria-label": string;
+};
+/**
+ * Props for ModalAction component.
+ *
+ * Discriminated union supporting two action types:
+ * - "close": Automatically closes the modal when clicked (uses Dialog.Close)
+ * - "button": Custom action with user-defined onClick handler
+ */
+type TypeModalActionProps = (ModalActionBase & {
+    actionType: "close";
+}) | (ModalActionBase & {
+    actionType?: "button";
+});
+
+/**
+ * Accessible modal dialog component built on Radix UI Dialog primitives.
+ *
+ * This component provides a flexible modal implementation with comprehensive accessibility
+ * features, keyboard navigation, and focus management built in.
+ *
+ * Key capabilities:
+ * - Automatic ARIA attributes and focus trapping
+ * - ESC key and outside click to close
+ * - Simplified API with title/subtitle props for common use cases
+ * - Controlled and uncontrolled state modes
+ * - Optional draggable behavior for side-by-side interaction
+ * - Floating action rail for quick actions like close, expand, etc.
+ * - Responsive bottom sheet layout on mobile
+ *
+ * @example
+ * // Simple uncontrolled modal
+ * <Modal
+ *   title="Delete Item"
+ *   subtitle="This action cannot be undone"
+ *   modalTrigger={<Button>Delete</Button>}
+ * >
+ *   <ModalBody>Are you sure you want to delete this item?</ModalBody>
+ *   <ModalFooter
+ *     cancelButton={<Button>Cancel</Button>}
+ *     primaryButton={<Button appearance="destructive">Delete</Button>}
+ *   />
+ * </Modal>
+ */
+declare const Modal: (props: TypeModalProps) => react_jsx_runtime.JSX.Element;
+
+interface HeaderProps {
+    draggable?: boolean;
+    isDragging?: boolean;
+}
+/**
+ * Base styled header component for custom modal headers.
+ *
+ * Use this component when you need complete control over the header layout
+ * and don't want to use the slot-based ModalHeader component.
+ *
+ * @example
+ * <ModalCustomHeader>
+ *   <YourCustomHeaderContent />
+ * </ModalCustomHeader>
+ */
+declare const ModalCustomHeader: styled_components.StyledComponent<React.ForwardRefExoticComponent<Omit<_sproutsocial_seeds_react_box.TypeBoxProps, "ref"> & React.RefAttributes<HTMLDivElement>>, styled_components.DefaultTheme, HeaderProps, never>;
+/**
+ * Modal header component with title and subtitle slots.
+ *
+ * This component only supports slot-based rendering via title and subtitle props.
+ * For custom header layouts, use ModalCustomHeader instead.
+ *
+ * @example
+ * <ModalHeader title="Delete Item" subtitle="This action cannot be undone" />
+ */
+declare const ModalHeader: {
+    (props: TypeModalHeaderProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Base styled footer component for custom modal footers.
+ *
+ * Use this component when you need complete control over the footer layout
+ * and don't want to use the slot-based ModalFooter component.
+ *
+ * @example
+ * <ModalCustomFooter>
+ *   <YourCustomFooterContent />
+ * </ModalCustomFooter>
+ */
+declare const ModalCustomFooter: styled_components.StyledComponent<React.ForwardRefExoticComponent<Omit<_sproutsocial_seeds_react_box.TypeBoxProps, "ref"> & React.RefAttributes<HTMLDivElement>>, styled_components.DefaultTheme, {}, never>;
+/**
+ * Modal footer component for action buttons.
+ *
+ * This component only supports slot-based rendering with button props.
+ * For custom footer layouts, use ModalCustomFooter instead.
+ *
+ * Provides automatic button wrapping and layout management. Supports three button positions:
+ * - primaryButton: Main action button on the right (auto-closes modal)
+ * - cancelButton: Secondary action on the right (auto-closes modal)
+ * - leftAction: Optional action on the left (no auto-close, for destructive actions)
+ *
+ * @example
+ * <ModalFooter
+ *   cancelButton={<Button>Cancel</Button>}
+ *   primaryButton={<Button appearance="primary">Save</Button>}
+ * />
+ *
+ * @example
+ * // With left action
+ * <ModalFooter
+ *   leftAction={<Button appearance="destructive">Delete</Button>}
+ *   cancelButton={<Button>Cancel</Button>}
+ *   primaryButton={<Button appearance="primary">Save</Button>}
+ * />
+ */
+declare const ModalFooter: {
+    (props: TypeModalFooterProps): react_jsx_runtime.JSX.Element | null;
+    displayName: string;
+};
+
+declare const ModalBody: React.ForwardRefExoticComponent<Omit<TypeModalBodyProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Modal description component that wraps content with accessible Dialog.Description.
+ *
+ * This component automatically connects description text to the modal dialog via ARIA attributes,
+ * ensuring screen readers announce the description when the modal opens. Use this for additional
+ * context beyond the title that helps users understand the modal's purpose.
+ *
+ * @example
+ * <ModalDescription>
+ *   Deleting this item will permanently remove it from your account.
+ * </ModalDescription>
+ */
+declare const ModalDescription: React.ForwardRefExoticComponent<Omit<TypeModalDescriptionProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Props for ModalCloseWrapper component.
+ */
+interface ModalCloseWrapperProps {
+    /** The element to wrap with close functionality */
+    children: React.ReactNode;
+    /** Optional click handler called before closing the modal */
+    onClick?: (e: React.MouseEvent) => void;
+    /** Whether to merge props into the child element (default: true) */
+    asChild?: boolean;
+}
+/**
+ * A wrapper component that closes the modal when its child is clicked.
+ * Uses asChild pattern like Radix primitives - by default asChild is true.
+ */
+declare const ModalCloseWrapper: {
+    (props: ModalCloseWrapperProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+declare const ModalRail: React.FC<TypeModalRailProps>;
+
+declare const ModalAction: React.FC<TypeModalActionProps>;
+
+export { Modal as M, type TypeModalProps as T, ModalDescription as a, ModalHeader as b, ModalFooter as c, ModalBody as d, ModalCloseWrapper as e, ModalRail as f, ModalAction as g, ModalCustomHeader as h, ModalCustomFooter as i, type TypeModalHeaderProps as j, type TypeModalFooterProps as k, type TypeModalBodyProps as l, type TypeModalDescriptionProps as m, type TypeModalRailProps as n, type TypeModalActionProps as o, type ModalCloseWrapperProps as p };