@sproutsocial/seeds-react-modal 2.4.9 → 2.5.0

package/src/__tests__/v2/Modal.test.tsx

@@ -13,6 +13,7 @@ import userEvent from "@testing-library/user-event";
 import {
   Modal,
   ModalBody,
+  ModalFooter,
   useModalExternalTrigger,
   ModalExternalTrigger,
 } from "../../v2";
@@ -1122,3 +1123,79 @@ describe("Portaled components in modal", () => {
     expect(contextValue).toHaveTextContent("false");
   });
 });
+
+describe("ModalFooter - closeOnPrimaryAction", () => {
+  it("should close the modal when primary button is clicked by default", async () => {
+    const onOpenChange = jest.fn();
+
+    render(
+      <Modal
+        open
+        onOpenChange={onOpenChange}
+        aria-label="Test Modal"
+        closeButtonAriaLabel="Close"
+      >
+        <ModalBody>Content</ModalBody>
+        <ModalFooter
+          primaryButton={<Button appearance="primary">Save</Button>}
+          cancelButton={<Button>Cancel</Button>}
+        />
+      </Modal>
+    );
+
+    const saveButton = screen.getByRole("button", { name: "Save" });
+    await userEvent.click(saveButton);
+
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("should NOT close the modal when primary button is clicked and closeOnPrimaryAction is false", async () => {
+    const onOpenChange = jest.fn();
+
+    render(
+      <Modal
+        open
+        onOpenChange={onOpenChange}
+        aria-label="Test Modal"
+        closeButtonAriaLabel="Close"
+      >
+        <ModalBody>Content</ModalBody>
+        <ModalFooter
+          closeOnPrimaryAction={false}
+          primaryButton={<Button appearance="primary">Save</Button>}
+          cancelButton={<Button>Cancel</Button>}
+        />
+      </Modal>
+    );
+
+    const saveButton = screen.getByRole("button", { name: "Save" });
+    await userEvent.click(saveButton);
+
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
+  it("should still close the modal when cancel button is clicked even if closeOnPrimaryAction is false", async () => {
+    const onOpenChange = jest.fn();
+
+    render(
+      <Modal
+        open
+        onOpenChange={onOpenChange}
+        aria-label="Test Modal"
+        closeButtonAriaLabel="Close"
+      >
+        <ModalBody>Content</ModalBody>
+        <ModalFooter
+          closeOnPrimaryAction={false}
+          primaryButton={<Button appearance="primary">Save</Button>}
+          cancelButton={<Button>Cancel</Button>}
+        />
+      </Modal>
+    );
+
+    const cancelButton = screen.getByRole("button", { name: "Cancel" });
+    await userEvent.click(cancelButton);
+
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+});

package/src/index.ts

@@ -24,6 +24,9 @@ export {
   ModalAction,
   ModalCustomHeader,
   ModalCustomFooter,
+  ModalExternalTrigger,
+  useModalExternalTrigger,
+  useModalTriggerProps,
 } from "./v2";
 export type {
   TypeModalProps as TypeModalV2Props,
@@ -34,4 +37,5 @@ export type {
   TypeModalRailProps,
   TypeModalActionProps,
   ModalCloseWrapperProps,
+  ModalExternalTriggerProps,
 } from "./v2";

package/src/v1/Modal.tsx

@@ -106,10 +106,40 @@ const Modal = (props: TypeModalProps) => {
       ? (document.querySelector(appElementSelector) as HTMLElement)
       : undefined;
 
+  /**
+   * When a Radix Dialog (Modal V2) is open it sets `pointer-events: none` on
+   * `document.body` and listens for `pointerdown` on the document to detect
+   * "outside" clicks. react-modal portals its overlay to body, so:
+   *   1. The overlay inherits `pointer-events: none` → unclickable
+   *   2. Clicks on the overlay bubble to document → Radix dismisses Modal V2
+   *
+   * We use `contentRef` to reach the portal DOM and fix both issues.
+   */
+  const handleContentRef = React.useCallback(
+    (contentEl: HTMLElement | null) => {
+      if (!contentEl) return;
+      // DOM structure: body > portal > overlay > content
+      const portal = contentEl.parentElement?.parentElement;
+      if (portal) {
+        portal.style.pointerEvents = "auto";
+        portal.addEventListener("pointerdown", (e) => {
+          // Only stop propagation when Radix Dialog has disabled body pointer events.
+          // This avoids interfering with document-level listeners (analytics, other
+          // click-outside patterns) when no Modal V2 is open.
+          if (document.body.style.pointerEvents === "none") {
+            e.stopPropagation();
+          }
+        });
+      }
+    },
+    []
+  );
+
   return (
     <Container
       appElement={appElement}
       ariaHideApp={!!appElement}
+      contentRef={handleContentRef}
       isOpen={isOpen}
       contentLabel={label}
       // eslint-disable-next-line @typescript-eslint/no-empty-function

package/src/v2/ModalTypes.ts

@@ -77,8 +77,15 @@ export interface TypeModalDescriptionProps extends TypeBoxProps {
  * Note: This component only supports slots (button props).
  * For custom footers, use ModalCustomFooter instead.
  */
-export type TypeModalFooterProps = TypeBoxProps &
-  (
+export type TypeModalFooterProps = TypeBoxProps & {
+  /**
+   * Whether clicking the primary button automatically closes the modal.
+   * Set to `false` when the primary action is async (e.g., saving data)
+   * and the modal should stay open until the operation completes.
+   * @default true
+   */
+  closeOnPrimaryAction?: boolean;
+} & (
     | {
         /** Primary action button - automatically wrapped in ModalCloseWrapper */
         primaryButton: React.ReactNode;

package/src/v2/ModalV2.stories.tsx

@@ -5,6 +5,7 @@ import { Button } from "@sproutsocial/seeds-react-button";
 import Text from "@sproutsocial/seeds-react-text";
 import { Popout } from "@sproutsocial/seeds-react-popout";
 import { Popout as PopoutV2 } from "@sproutsocial/seeds-react-popout/v2";
+import ModalV1 from "../v1/Modal";
 import { FormField } from "@sproutsocial/seeds-react-form-field";
 import {
   ActionMenu,
@@ -851,6 +852,61 @@ export const FooterWithLeftAction: Story = {
   },
 };
 
+export const AsyncPrimaryAction: Story = {
+  render: () => {
+    const [isOpen, setIsOpen] = useState(false);
+    const [isSaving, setIsSaving] = useState(false);
+
+    const handleSave = async () => {
+      setIsSaving(true);
+      // Simulate async operation
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+      setIsSaving(false);
+      setIsOpen(false);
+    };
+
+    return (
+      <>
+        <Button appearance="primary" onClick={() => setIsOpen(true)}>
+          Open Async Save Modal
+        </Button>
+        <Modal
+          open={isOpen}
+          onOpenChange={setIsOpen}
+          aria-label="Async Save Modal"
+          closeButtonAriaLabel="Close"
+        >
+          <ModalHeader
+            title="Save Changes"
+            subtitle="The modal stays open until the save completes."
+          />
+          <ModalBody>
+            <Text>
+              This modal uses <code>closeOnPrimaryAction=false</code> so the
+              primary button does not auto-close the modal. Instead, the
+              consumer controls when to close after the async operation
+              completes.
+            </Text>
+          </ModalBody>
+          <ModalFooter
+            closeOnPrimaryAction={false}
+            cancelButton={<Button>Cancel</Button>}
+            primaryButton={
+              <Button
+                appearance="primary"
+                onClick={handleSave}
+                disabled={isSaving}
+              >
+                {isSaving ? "Saving..." : "Save"}
+              </Button>
+            }
+          />
+        </Modal>
+      </>
+    );
+  },
+};
+
 export const CustomFooterOverride: Story = {
   render: () => {
     return (
@@ -978,16 +1034,15 @@ export const PortaledComponentsInModal: Story = {
 };
 
 /**
- * Example using the useModalExternalTrigger hook for external triggers.
+ * The recommended pattern for controlled modals where the trigger lives outside
+ * the Modal component tree (e.g., a button in a table row, page header, or list item).
  *
- * ⚠️ NOT RECOMMENDED - This is a last resort pattern. Prefer using modalTrigger prop.
+ * useModalExternalTrigger provides:
+ * - triggerRef: Ref to attach to your trigger element for focus restoration
+ * - triggerProps: Function returning ARIA attributes (aria-haspopup, aria-expanded, aria-controls)
+ * - onCloseAutoFocus: Pass to Modal to automatically restore focus to the trigger on close
  *
- * The hook provides:
- * - triggerRef: Ref to attach to your trigger element
- * - triggerProps: Function that returns ARIA props (pass isOpen state)
- * - onCloseAutoFocus: Callback for Modal to restore focus
- *
- * This eliminates manual ref creation and focus restoration boilerplate.
+ * This is the standard pattern for most real-world controlled modals.
  */
 export const ExternalTriggerWithHook: Story = {
   render: () => {
@@ -998,29 +1053,31 @@ export const ExternalTriggerWithHook: Story = {
     return (
       <Box>
         <Text mb={400} fontWeight="semibold">
-          ⚠️ LAST RESORT: useModalExternalTrigger Hook
+          Controlled Modal: useModalExternalTrigger Hook
         </Text>
         <Text mb={400}>
-          Only use when the trigger absolutely cannot be near the Modal (e.g.,
-          trigger in header, modal at bottom of app tree).
+          Use this pattern when the trigger and modal live in different parts of
+          the component tree — for example, a button in a data table row, a list
+          item, or a page header.
         </Text>
 
         <Text mb={400} fontWeight="semibold">
-          Benefits:
+          What this hook provides:
         </Text>
         <Box as="ul" pl={400} mb={400}>
           <li>
             <Text>
-              Works with any trigger element (Button, custom components, etc.)
+              Works with any trigger element (Button, link, custom component)
             </Text>
           </li>
           <li>
             <Text>
-              Automatic focus restoration via onCloseAutoFocus callback
+              Correct ARIA attributes on the trigger (aria-haspopup,
+              aria-expanded, aria-controls)
             </Text>
           </li>
           <li>
-            <Text>No manual ref creation needed</Text>
+            <Text>Automatic focus restoration when the modal closes</Text>
           </li>
         </Box>
 
@@ -1041,31 +1098,34 @@ export const ExternalTriggerWithHook: Story = {
           closeButtonAriaLabel="Close Modal"
         >
           <ModalHeader
-            title="External Trigger with Hook"
-            subtitle="Using useModalExternalTrigger"
+            title="Controlled Modal"
+            subtitle="Trigger lives outside the Modal component tree"
           />
           <ModalBody>
             <Text mb={400}>
-              The useModalExternalTrigger hook simplifies external trigger setup
-              by:
+              The trigger button used to open this modal is rendered separately
+              from the Modal component. The useModalExternalTrigger hook
+              handles:
             </Text>
             <Box as="ul" pl={400}>
               <li>
-                <Text>Managing the trigger ref internally</Text>
+                <Text>
+                  A ref on the trigger for focus restoration when the modal
+                  closes
+                </Text>
               </li>
               <li>
-                <Text>Providing ARIA props via triggerProps function</Text>
+                <Text>
+                  ARIA attributes on the trigger (aria-haspopup, aria-expanded,
+                  aria-controls)
+                </Text>
               </li>
               <li>
                 <Text>
-                  Handling focus restoration via onCloseAutoFocus callback
+                  The onCloseAutoFocus callback to return focus to the trigger
                 </Text>
               </li>
             </Box>
-            <Text mt={400}>
-              This eliminates the boilerplate of manual ref management and
-              custom onCloseAutoFocus implementation.
-            </Text>
           </ModalBody>
           <ModalFooter
             cancelButton={
@@ -1086,14 +1146,15 @@ export const ExternalTriggerWithHook: Story = {
 };
 
 /**
- * Example using the ModalExternalTrigger component for external triggers.
+ * Alternative to useModalExternalTrigger when the trigger is specifically a Seeds Button.
  *
- * ⚠️ NOT RECOMMENDED - This is a last resort pattern. Prefer using modalTrigger prop.
+ * ModalExternalTrigger is a pre-configured Button component that automatically applies
+ * the correct ARIA attributes (aria-haspopup, aria-expanded, aria-controls) for a modal
+ * trigger. Use it when the trigger lives outside the Modal component tree and you want
+ * to avoid spreading hook props manually.
  *
- * ModalExternalTrigger is a Button variant with built-in ARIA attributes.
- * Use it when you need an external trigger that is specifically a Button.
- *
- * Note: Focus restoration still requires manual onCloseAutoFocus implementation.
+ * Note: Unlike useModalExternalTrigger, focus restoration still requires passing an
+ * onCloseAutoFocus callback to the Modal manually.
  */
 export const ExternalTriggerComponent: Story = {
   render: () => {
@@ -1103,37 +1164,41 @@ export const ExternalTriggerComponent: Story = {
     return (
       <Box>
         <Text mb={400} fontWeight="semibold">
-          ⚠️ LAST RESORT: ModalExternalTrigger Component
+          Controlled Modal: ModalExternalTrigger Component
         </Text>
         <Text mb={400}>
-          Only use when the trigger absolutely cannot be near the Modal AND
-          you're using a Seeds Button specifically.
+          Use this component when the trigger is a Seeds Button and lives
+          outside the Modal component tree. It applies the correct ARIA
+          attributes automatically without needing to spread hook props.
         </Text>
 
         <Text mb={400} fontWeight="semibold">
-          Benefits:
+          What this component provides:
         </Text>
         <Box as="ul" pl={400} mb={400}>
           <li>
             <Text>
-              Automatic ARIA attributes (aria-haspopup, aria-expanded, etc.)
+              Automatic ARIA attributes (aria-haspopup, aria-expanded,
+              aria-controls)
             </Text>
           </li>
           <li>
             <Text>
-              All Button props supported (appearance, size, disabled, etc.)
+              All Seeds Button props supported (appearance, size, disabled,
+              etc.)
             </Text>
           </li>
           <li>
-            <Text>Cleaner than hook for Button-only triggers</Text>
+            <Text>Cleaner than the hook when using a Button trigger</Text>
           </li>
         </Box>
 
         <Text mb={400} fontWeight="semibold">
-          Limitation:
+          Note:
         </Text>
         <Text mb={400}>
-          Focus restoration still requires manual onCloseAutoFocus handling.
+          Pass a ref and implement onCloseAutoFocus on the Modal to restore
+          focus when the modal closes.
         </Text>
 
         <ModalExternalTrigger
@@ -1157,28 +1222,31 @@ export const ExternalTriggerComponent: Story = {
           closeButtonAriaLabel="Close Modal"
         >
           <ModalHeader
-            title="External Trigger Component"
-            subtitle="Using ModalExternalTrigger"
+            title="Controlled Modal"
+            subtitle="Using ModalExternalTrigger component"
           />
           <ModalBody>
             <Text mb={400}>
-              ModalExternalTrigger extends Seeds Button with automatic ARIA
-              attributes:
+              The trigger button for this modal is a ModalExternalTrigger
+              component rendered outside the Modal tree. It automatically
+              applies:
             </Text>
             <Box as="ul" pl={400}>
               <li>
                 <Text>aria-haspopup="dialog"</Text>
               </li>
               <li>
-                <Text>aria-expanded based on isOpen prop</Text>
+                <Text>aria-expanded reflecting the current open state</Text>
               </li>
               <li>
-                <Text>aria-controls (if modalId provided)</Text>
+                <Text>
+                  aria-controls linking to the modal (if modalId provided)
+                </Text>
               </li>
             </Box>
             <Text mt={400}>
-              Supports all Button props (appearance, size, disabled, etc.).
-              Focus restoration requires manual onCloseAutoFocus handling.
+              Focus returns to the trigger on close via the onCloseAutoFocus
+              callback passed to the Modal.
             </Text>
           </ModalBody>
           <ModalFooter
@@ -1402,3 +1470,154 @@ export const WithPopout: Story = {
     );
   },
 };
+
+export const WithModalV1: Story = {
+  render: () => {
+    const [v1Open, setV1Open] = useState(false);
+    return (
+      <Modal
+        closeButtonAriaLabel="Close Modal V2"
+        modalTrigger={<Button appearance="primary">Open Modal V2</Button>}
+      >
+        <ModalHeader title="Modal V2" subtitle="Open a Modal V1 from inside" />
+        <ModalBody>
+          <Text as="p" mb={400}>
+            Click the button below to open a Modal V1 on top of this Modal V2.
+            The V1 modal should be fully interactive and closing it should not
+            dismiss the V2 modal.
+          </Text>
+          <Button appearance="secondary" onClick={() => setV1Open(true)}>
+            Open Modal V1
+          </Button>
+          <ModalV1
+            isOpen={v1Open}
+            onClose={() => setV1Open(false)}
+            label="Modal V1 on top of V2"
+            closeButtonLabel="Close Modal V1"
+            zIndex={100}
+          >
+            <ModalV1.Header title="Modal V1" />
+            <ModalV1.Content>
+              <Box p={400}>
+                <Text as="p">
+                  This Modal V1 is rendered on top of a Modal V2. It should be
+                  clickable and closing it should not dismiss the V2 behind it.
+                </Text>
+              </Box>
+            </ModalV1.Content>
+          </ModalV1>
+        </ModalBody>
+        <ModalFooter
+          cancelButton={<Button>Cancel</Button>}
+          primaryButton={<Button appearance="primary">Confirm</Button>}
+        />
+      </Modal>
+    );
+  },
+};
+
+/**
+ * Two Modal V2s stacked — a primary modal that opens a secondary confirmation modal.
+ *
+ * The secondary modal uses zIndex={8} so its overlay (8) and content (9) render
+ * above the primary modal's overlay (6) and content (7). Without this, the second
+ * modal's overlay would sit behind the first modal's content.
+ */
+export const NestedModals: Story = {
+  render: () => {
+    const [primaryOpen, setPrimaryOpen] = useState(false);
+    const [secondaryOpen, setSecondaryOpen] = useState(false);
+    const secondaryTriggerRef = React.useRef<HTMLButtonElement>(null);
+    const {
+      triggerRef: primaryTriggerRef,
+      triggerProps: primaryTriggerProps,
+      onCloseAutoFocus: primaryOnCloseAutoFocus,
+    } = useModalExternalTrigger();
+
+    return (
+      <Box>
+        <Button
+          ref={primaryTriggerRef}
+          {...primaryTriggerProps(primaryOpen)}
+          appearance="primary"
+          onClick={() => setPrimaryOpen(true)}
+        >
+          Open Primary Modal
+        </Button>
+
+        {/* Primary modal — default z-index (overlay: 6, content: 7) */}
+        <Modal
+          open={primaryOpen}
+          onOpenChange={setPrimaryOpen}
+          onCloseAutoFocus={primaryOnCloseAutoFocus}
+          aria-label="Primary Modal"
+          closeButtonAriaLabel="Close Primary Modal"
+        >
+          <ModalHeader
+            title="Primary Modal"
+            subtitle="This is the first modal"
+          />
+          <ModalBody>
+            <Text mb={400}>
+              This is the primary modal. Click the button below to open a
+              secondary confirmation modal on top of this one.
+            </Text>
+            <Button
+              ref={secondaryTriggerRef}
+              aria-haspopup="dialog"
+              aria-expanded={secondaryOpen}
+              appearance="destructive"
+              onClick={() => setSecondaryOpen(true)}
+            >
+              Delete item
+            </Button>
+          </ModalBody>
+          <ModalFooter
+            cancelButton={<Button>Cancel</Button>}
+            primaryButton={<Button appearance="primary">Save</Button>}
+          />
+        </Modal>
+
+        {/* Secondary modal — elevated z-index (overlay: 8, content: 9) */}
+        <Modal
+          open={secondaryOpen}
+          onOpenChange={setSecondaryOpen}
+          onCloseAutoFocus={(e) => {
+            e.preventDefault();
+            secondaryTriggerRef.current?.focus();
+          }}
+          zIndex={8}
+          aria-label="Confirm Deletion"
+          closeButtonAriaLabel="Close Confirmation"
+        >
+          <ModalHeader
+            title="Are you sure?"
+            subtitle="This action can't be undone."
+          />
+          <ModalBody>
+            <Text>
+              Deleting this item will remove it permanently. The primary modal
+              behind this one remains open.
+            </Text>
+          </ModalBody>
+          <ModalFooter
+            cancelButton={
+              <Button onClick={() => setSecondaryOpen(false)}>Cancel</Button>
+            }
+            primaryButton={
+              <Button
+                appearance="destructive"
+                onClick={() => {
+                  setSecondaryOpen(false);
+                  setPrimaryOpen(false);
+                }}
+              >
+                Delete
+              </Button>
+            }
+          />
+        </Modal>
+      </Box>
+    );
+  },
+};

package/src/v2/components/ModalFooter.tsx

@@ -74,13 +74,26 @@ ModalCustomFooter.displayName = "ModalCustomFooter";
  * />
  */
 export const ModalFooter = (props: TypeModalFooterProps) => {
-  const { cancelButton, primaryButton, leftAction, ...rest } = props;
+  const {
+    cancelButton,
+    primaryButton,
+    leftAction,
+    closeOnPrimaryAction = true,
+    ...rest
+  } = props;
 
   // If no simplified props provided, return empty footer
   if (!cancelButton && !primaryButton && !leftAction) {
     return null;
   }
 
+  const wrappedPrimaryButton =
+    primaryButton && closeOnPrimaryAction ? (
+      <ModalCloseWrapper>{primaryButton}</ModalCloseWrapper>
+    ) : (
+      primaryButton
+    );
+
   // Build simplified API layout
   return (
     <ModalCustomFooter data-slot="modal-footer" data-qa-modal-footer {...rest}>
@@ -90,9 +103,7 @@ export const ModalFooter = (props: TypeModalFooterProps) => {
       {/* Right-aligned button group (Cancel + Primary) */}
       <Box display="flex" gap={300} marginLeft="auto">
         {cancelButton && <ModalCloseWrapper>{cancelButton}</ModalCloseWrapper>}
-        {primaryButton && (
-          <ModalCloseWrapper>{primaryButton}</ModalCloseWrapper>
-        )}
+        {wrappedPrimaryButton}
       </Box>
     </ModalCustomFooter>
   );