@sproutsocial/seeds-react-modal 2.1.2 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutsocial/seeds-react-modal",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Seeds React Modal",
   "author": "Sprout Social, Inc.",
   "license": "MIT",
@@ -36,12 +36,12 @@
   },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.14",
-    "@sproutsocial/seeds-react-box": "^1.1.6",
-    "@sproutsocial/seeds-react-button": "^1.3.5",
-    "@sproutsocial/seeds-react-icon": "^2.0.0",
+    "@sproutsocial/seeds-react-box": "^1.1.7",
+    "@sproutsocial/seeds-react-button": "^1.3.6",
+    "@sproutsocial/seeds-react-icon": "^2.0.1",
     "@sproutsocial/seeds-react-system-props": "^3.0.1",
     "@sproutsocial/seeds-react-text": "^1.3.2",
-    "@sproutsocial/seeds-react-theme": "^3.2.0",
+    "@sproutsocial/seeds-react-theme": "^3.2.1",
     "motion": "^12.6.3",
     "react-dnd": "^16.0.1",
     "react-dnd-html5-backend": "^16.0.1",
@@ -50,8 +50,8 @@
   },
   "devDependencies": {
     "@sproutsocial/eslint-config-seeds": "*",
-    "@sproutsocial/seeds-react-form-field": "^1.0.5",
-    "@sproutsocial/seeds-react-input": "^1.4.11",
+    "@sproutsocial/seeds-react-form-field": "^1.0.6",
+    "@sproutsocial/seeds-react-input": "^1.4.12",
     "@sproutsocial/seeds-react-testing-library": "*",
     "@sproutsocial/seeds-testing": "*",
     "@sproutsocial/seeds-tsconfig": "*",

package/src/v2/Modal.tsx

@@ -59,6 +59,8 @@ const Modal = (props: TypeModalProps) => {
     showOverlay = true,
     actions,
     closeButtonAriaLabel = "Close",
+    closeButtonProps,
+    zIndex = 6,
     ...rest
   } = props;
 
@@ -119,12 +121,17 @@ const Modal = (props: TypeModalProps) => {
               {showOverlay && (
                 <Dialog.Overlay asChild>
                   <StyledMotionOverlay
+                    $zIndex={zIndex}
                     variants={overlayVariants}
                     initial="initial"
                     animate="animate"
                     exit="exit"
                   >
-                    <StyledOverlay allowInteraction={draggable} />
+                    <StyledOverlay
+                      data-slot="modal-overlay"
+                      data-qa-modal-overlay
+                      allowInteraction={draggable}
+                    />
                   </StyledMotionOverlay>
                 </Dialog.Overlay>
               )}
@@ -132,14 +139,19 @@ const Modal = (props: TypeModalProps) => {
                 label={label}
                 dataAttributes={dataAttributes}
                 draggable={draggable}
+                zIndex={zIndex}
                 rest={rest}
               >
                 {/* Floating actions rail - always show a close by default */}
                 <ModalRail>
                   <ModalAction
                     actionType="close"
-                    aria-label={closeButtonAriaLabel}
                     iconName="x-outline"
+                    {...closeButtonProps}
+                    aria-label={
+                      (closeButtonProps as any)?.["aria-label"] ??
+                      closeButtonAriaLabel
+                    }
                   />
                   {actions?.map((action, idx) => (
                     <ModalAction key={idx} {...action} />

package/src/v2/ModalTypes.ts

@@ -6,43 +6,36 @@ import type {
 } from "@sproutsocial/seeds-react-box";
 import type { TypeIconName } from "@sproutsocial/seeds-react-icon";
 
+// =============================================================================
+// COMPONENT PROPS - Individual modal component types
+// =============================================================================
+
 /**
  * Props for ModalHeader component.
  *
- * Renders the modal's header with title and optional subtitle. Supports draggable functionality
- * when the modal has draggable enabled.
+ * 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.
+ * Note: This component only supports slots (title/subtitle props).
+ * For custom headers, use ModalCustomHeader instead.
  */
 export 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).
+   * Automatically wrapped in Dialog.Description for accessibility.
    */
   subtitle?: string;
 
-  /** Additional props for the Dialog.Title when title is provided */
+  /** Additional props for 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.
-   */
+  /** Additional props for Dialog.Description when subtitle is provided */
   subtitleProps?: Omit<
     React.ComponentPropsWithoutRef<typeof Dialog.Description>,
     "asChild" | "children"
@@ -50,294 +43,291 @@ export interface TypeModalHeaderProps extends TypeBoxProps {
 }
 
 /**
- * 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.
+ * Props for ModalBody component.
  *
- * @example
- * // ✅ Valid - has primary button
- * <ModalFooter primaryButton={<Button>Save</Button>} />
+ * Renders the scrollable main content area of the modal.
+ */
+export interface TypeModalBodyProps extends TypeBoxProps {
+  /** The main content of the modal body */
+  children?: React.ReactNode;
+}
+
+/**
+ * Props for ModalDescription component.
  *
- * @example
- * // ✅ Valid - has cancel and primary
- * <ModalFooter
- *   cancelButton={<Button>Cancel</Button>}
- *   primaryButton={<Button>Save</Button>}
- * />
+ * Wraps content with Dialog.Description for accessible descriptions.
+ */
+export interface TypeModalDescriptionProps extends TypeBoxProps {
+  /** The description text content */
+  children: React.ReactNode;
+
+  /** Additional props for Dialog.Description */
+  descriptionProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof Dialog.Description>,
+    "asChild" | "children"
+  >;
+}
+
+/**
+ * Props for ModalFooter component.
  *
- * @example
- * // ✅ Valid - left action only
- * <ModalFooter leftAction={<Button>Delete</Button>} />
+ * Provides automatic button wrapping and layout management.
+ * At least one action (cancelButton, primaryButton, or leftAction) must be provided.
  *
- * @example
- * // ❌ TypeScript Error - no actions provided
- * <ModalFooter />
+ * Note: This component only supports slots (button props).
+ * For custom footers, use ModalCustomFooter instead.
  */
 export type TypeModalFooterProps = TypeBoxProps &
   (
     | {
-        /** Primary action button - automatically wrapped in ModalCloseWrapper to close the modal */
+        /** Primary action button - automatically wrapped in ModalCloseWrapper */
         primaryButton: React.ReactNode;
-        /** Cancel/secondary button - automatically wrapped in ModalCloseWrapper to close the modal */
+        /** Cancel/secondary button - automatically wrapped in ModalCloseWrapper */
         cancelButton?: React.ReactNode;
-        /** Optional action on the far left (e.g., Delete button) - NOT automatically wrapped */
+        /** Optional action on the far left (e.g., Delete) - 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.
+ * Props for ModalRail component.
  *
- * Renders the scrollable main content area of the modal between the header and footer.
+ * Container for floating action buttons displayed alongside the modal.
  */
-export interface TypeModalBodyProps extends TypeBoxProps {
-  /** The main content of the modal body */
+export type TypeModalRailProps = {
+  /** ModalAction components to display in the rail */
   children?: React.ReactNode;
-}
+};
 
 /**
- * Props for ModalDescription component.
+ * Props for ModalAction component.
  *
- * Wraps content with Radix UI's Dialog.Description for accessible modal descriptions
- * that are announced by screen readers.
+ * Action buttons that appear in the floating rail.
+ * Supports two action types:
+ * - "close": Automatically closes the modal (uses Dialog.Close)
+ * - "button": Custom action with user-defined onClick handler
+ *
+ * **IMPORTANT**: aria-label is required for accessibility.
  */
-export 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"
-  >;
-}
+export type TypeModalActionProps =
+  | ({
+      /** Action type - close triggers modal close */
+      actionType: "close";
+      /** REQUIRED: Accessible label for the button */
+      "aria-label": string;
+      /** Icon name from the Seeds icon set */
+      iconName?: TypeIconName;
+      /** Optional click handler called before closing */
+      onClick?: () => void;
+    } & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick">)
+  | ({
+      /** Action type - button for custom actions (default) */
+      actionType?: "button";
+      /** REQUIRED: Accessible label for the button */
+      "aria-label": string;
+      /** Icon name from the Seeds icon set */
+      iconName?: TypeIconName;
+      /** Click handler for the button */
+      onClick?: () => void;
+    } & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick">);
+
+// =============================================================================
+// MODAL PROPS - Main Modal component types
+// =============================================================================
 
-/** Common props shared by all modal variants */
-type TypeModalCommonProps = TypeContainerProps &
+/**
+ * Base common props shared by all modal variants (without close button props).
+ */
+type TypeModalCommonPropsBase = TypeContainerProps &
   Omit<React.ComponentPropsWithoutRef<"div">, keyof TypeContainerProps> & {
+    /** Modal content */
+    children: React.ReactNode;
+
     /** 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. */
+    /**
+     * Element that triggers 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) */
+    /** 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
+     * Custom data attributes added to the modal container.
+     * Each key will be prepended with "data-" when rendered.
      */
     data?: Record<string, string | boolean | number>;
 
-    /** Optional quick actions to render on a modal side rail */
+    /** Quick actions to render on the modal side rail */
     actions?: TypeModalActionProps[];
 
-    /** Accessible label for the close button in the rail (defaults to "Close") */
-    closeButtonAriaLabel?: string;
+    /** Controls the z-index CSS property (defaults to 6 to match Modal v1) */
+    zIndex?: number;
   };
 
+/**
+ * Common props with close button accessibility enforcement.
+ *
+ * Ensures close button always has an accessible label through either:
+ * - closeButtonAriaLabel prop (required unless closeButtonProps has aria-label)
+ * - closeButtonProps with aria-label
+ *
+ * @example
+ * // ✅ Valid - has closeButtonAriaLabel
+ * <Modal closeButtonAriaLabel="Close dialog" />
+ *
+ * @example
+ * // ✅ Valid - has aria-label in closeButtonProps
+ * <Modal closeButtonProps={{ "aria-label": "Close dialog", onClick: handler }} />
+ *
+ * @example
+ * // ✅ Valid - has both (closeButtonProps aria-label takes precedence)
+ * <Modal
+ *   closeButtonAriaLabel="Close"
+ *   closeButtonProps={{ onClick: handler }}
+ * />
+ *
+ * @example
+ * // ❌ TypeScript Error - missing aria-label in both places
+ * <Modal closeButtonProps={{ onClick: handler }} />
+ */
+type TypeModalCommonProps =
+  | (TypeModalCommonPropsBase & {
+      /**
+       * Accessible label for the close button.
+       * Required unless closeButtonProps includes aria-label.
+       */
+      closeButtonAriaLabel: string;
+      /**
+       * Props to pass to the default floating close button.
+       * Use this for advanced customization; for simple aria-label changes, use closeButtonAriaLabel instead.
+       */
+      closeButtonProps?: Omit<
+        TypeModalActionProps,
+        "actionType" | "aria-label"
+      >;
+    })
+  | (TypeModalCommonPropsBase & {
+      /**
+       * Accessible label for the close button.
+       * Optional when closeButtonProps includes aria-label.
+       */
+      closeButtonAriaLabel?: string;
+      /**
+       * Props to pass to the default floating close button.
+       * Must include aria-label when closeButtonAriaLabel is not provided.
+       */
+      closeButtonProps: Omit<TypeModalActionProps, "actionType"> & {
+        "aria-label": 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.
+ * When draggable is true, showOverlay must be false because the overlay
+ * would block interaction with content behind the modal.
  */
 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.
  */
-export type TypeModalPropsWithTitle = TypeModalBaseProps & {
-  /** Simplified API: Modal title (creates ModalHeader automatically) */
+type TypeModalPropsWithTitle = TypeModalBaseProps & {
+  /** 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.
-   */
+  /** Modal subtitle (creates ModalHeader automatically) */
   subtitle?: string;
-  /** Accessible label for the modal dialog (optional when title or subtitle is provided) */
+  /** Accessible label for the modal dialog (optional when title 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.
+ * Modal props with subtitle only (no title).
  */
-export type TypeModalPropsWithSubtitleOnly = TypeModalBaseProps & {
-  /** Simplified API: Modal title (creates ModalHeader automatically) */
+type TypeModalPropsWithSubtitleOnly = TypeModalBaseProps & {
   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.
-   */
+  /** Modal subtitle (creates ModalHeader automatically) */
   subtitle: string;
-  /** Accessible label for the modal dialog (optional when title or subtitle is provided) */
+  /** Accessible label for the modal dialog (optional when 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>
+ * aria-label is optional because users can provide accessible labeling through:
+ * - ModalHeader component as children
+ * - Dialog.Title or Dialog.Description components
+ * - Custom accessible content
  *
- * @example
- * // ❌ Invalid - missing required aria-label
- * <Modal>
- *   <p>Are you sure you want to delete this item?</p>
- * </Modal>
+ * However, for best accessibility, provide one of:
+ * - `aria-label` prop
+ * - ModalHeader component with title
+ * - Dialog.Title component in children
  */
-export type TypeModalPropsWithoutHeader = TypeModalBaseProps & {
-  /** Simplified API: Modal title (creates ModalHeader automatically) - not allowed when no header */
+type TypeModalPropsWithoutHeader = TypeModalBaseProps & {
   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.
+   * Accessible label for the modal dialog.
+   * Optional, but recommended when no title/subtitle props are provided.
    */
-  "aria-label": string;
+  "aria-label"?: string;
 };
 
 /**
- * Modal component props with discriminated union based on header presence.
+ * Modal component props.
  *
- * **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.
+ * **Accessibility Recommendations:**
+ * - With title/subtitle props: aria-label is optional (automatically accessible)
+ * - With ModalHeader as children: aria-label is optional (header provides labeling)
+ * - Without header props or components: aria-label is optional but strongly recommended
  *
  * @example
- * // ✅ Valid - has title, aria-label optional
+ * // With title prop
  * <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" />
+ * // With ModalHeader as children
+ * <Modal>
+ *   <ModalHeader title="Delete Item" />
+ * </Modal>
  *
  * @example
- * // ❌ TypeScript Error - no header and missing required aria-label
- * <Modal /> // Error: Property 'aria-label' is missing
+ * // With aria-label
+ * <Modal aria-label="Delete confirmation">
+ *   <ModalBody>Are you sure?</ModalBody>
+ * </Modal>
  */
 export type TypeModalProps =
   | TypeModalPropsWithTitle
   | TypeModalPropsWithSubtitleOnly
   | TypeModalPropsWithoutHeader;
-
-/**
- * Props for ModalRail component.
- *
- * Container for floating action buttons displayed alongside the modal.
- */
-export 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
- */
-export type TypeModalActionProps =
-  | (ModalActionBase & { actionType: "close" }) // uses Dialog.Close
-  | (ModalActionBase & { actionType?: "button" }); // regular button action