@sproutsocial/seeds-react-modal 2.2.5 → 2.4.0

package/src/v2/Modal.tsx

@@ -14,6 +14,14 @@ import {
 import type { TypeModalProps } from "./ModalTypes";
 import { getOverlayVariants, useIsMobile } from "./MotionConfig";
 
+// Type aliases for Dialog.Content event handlers
+type InteractOutsideHandler = NonNullable<
+  React.ComponentPropsWithoutRef<typeof Dialog.Content>["onInteractOutside"]
+>;
+type EscapeKeyDownHandler = NonNullable<
+  React.ComponentPropsWithoutRef<typeof Dialog.Content>["onEscapeKeyDown"]
+>;
+
 /**
  * Accessible modal dialog component built on Radix UI Dialog primitives.
  *
@@ -61,6 +69,16 @@ const Modal = (props: TypeModalProps) => {
     closeButtonAriaLabel = "Close",
     closeButtonProps,
     zIndex = 6,
+    // Extract Dialog.Content event handlers
+    onOpenAutoFocus,
+    onCloseAutoFocus,
+    onEscapeKeyDown,
+    onPointerDownOutside,
+    onFocusOutside,
+    onInteractOutside,
+    // Extract convenience boolean props
+    disableOutsideClickClose = false,
+    disableEscapeKeyClose = false,
     ...rest
   } = props;
 
@@ -104,6 +122,27 @@ const Modal = (props: TypeModalProps) => {
     ? DraggableModalContent
     : StaticModalContent;
 
+  // Wrap event handlers to support convenience boolean props
+  const wrappedOnInteractOutside = React.useCallback<InteractOutsideHandler>(
+    (e) => {
+      if (disableOutsideClickClose) {
+        e.preventDefault();
+      }
+      onInteractOutside?.(e);
+    },
+    [disableOutsideClickClose, onInteractOutside]
+  );
+
+  const wrappedOnEscapeKeyDown = React.useCallback<EscapeKeyDownHandler>(
+    (e) => {
+      if (disableEscapeKeyClose) {
+        e.preventDefault();
+      }
+      onEscapeKeyDown?.(e);
+    },
+    [disableEscapeKeyClose, onEscapeKeyDown]
+  );
+
   return (
     <Dialog.Root
       open={open}
@@ -130,6 +169,7 @@ const Modal = (props: TypeModalProps) => {
                     <StyledOverlay
                       data-slot="modal-overlay"
                       data-qa-modal-overlay
+                      data-testid="modal-overlay"
                       allowInteraction={draggable}
                     />
                   </StyledMotionOverlay>
@@ -141,6 +181,14 @@ const Modal = (props: TypeModalProps) => {
                 draggable={draggable}
                 zIndex={zIndex}
                 rest={rest}
+                dialogContentProps={{
+                  onOpenAutoFocus,
+                  onCloseAutoFocus,
+                  onEscapeKeyDown: wrappedOnEscapeKeyDown,
+                  onPointerDownOutside,
+                  onFocusOutside,
+                  onInteractOutside: wrappedOnInteractOutside,
+                }}
               >
                 {/* Floating actions rail - always show a close by default */}
                 <ModalRail>
@@ -178,4 +226,145 @@ const Modal = (props: TypeModalProps) => {
   );
 };
 
+/**
+ * Hook for adding proper ARIA attributes to external modal triggers.
+ *
+ * ⚠️ **NOT RECOMMENDED** - Prefer using modalTrigger prop or ModalTrigger component.
+ * Use this hook ONLY as a last resort when architectural constraints prevent keeping
+ * the trigger inside the Modal component tree.
+ *
+ * **Important Limitations:**
+ * - This hook only provides ARIA attributes (aria-haspopup, aria-expanded)
+ * - Focus restoration is NOT automatic - you must manually handle it with refs
+ * - Radix UI cannot track external triggers for proper accessibility
+ *
+ * **Why modalTrigger prop is better:**
+ * - Automatic ARIA attributes
+ * - Automatic focus restoration
+ * - Better touch device support
+ * - Follows WAI-ARIA Dialog best practices
+ *
+ * @param isOpen - Current open state of the modal
+ * @param modalId - Optional ID of the modal element for aria-controls
+ * @returns Object with ARIA attributes to spread onto trigger element
+ *
+ * @example
+ * ```tsx
+ * // Manual focus restoration required
+ * const [isOpen, setIsOpen] = useState(false);
+ * const triggerRef = useRef<HTMLButtonElement>(null);
+ * const triggerProps = useModalTriggerProps(isOpen);
+ *
+ * return (
+ *   <>
+ *     <Button
+ *       ref={triggerRef}
+ *       {...triggerProps}
+ *       onClick={() => setIsOpen(true)}
+ *     >
+ *       Open Modal
+ *     </Button>
+ *     <Modal
+ *       open={isOpen}
+ *       onOpenChange={setIsOpen}
+ *       onCloseAutoFocus={(e) => {
+ *         e.preventDefault();
+ *         triggerRef.current?.focus();
+ *       }}
+ *     >
+ *       <ModalBody>Content</ModalBody>
+ *     </Modal>
+ *   </>
+ * );
+ * ```
+ */
+export function useModalTriggerProps(
+  isOpen: boolean,
+  modalId?: string
+): {
+  "aria-haspopup": "dialog";
+  "aria-expanded": boolean;
+  "aria-controls"?: string;
+} {
+  return React.useMemo(
+    () => ({
+      "aria-haspopup": "dialog" as const,
+      "aria-expanded": isOpen,
+      ...(modalId ? { "aria-controls": modalId } : {}),
+    }),
+    [isOpen, modalId]
+  );
+}
+
+/**
+ * Hook for managing external modal triggers with automatic focus restoration.
+ *
+ * ⚠️ **NOT RECOMMENDED** - Prefer using modalTrigger prop or ModalTrigger component.
+ * Use this hook ONLY as a last resort when architectural constraints prevent keeping
+ * the trigger inside the Modal component tree.
+ *
+ * This hook improves upon useModalTriggerProps by managing the trigger ref internally
+ * and providing the onCloseAutoFocus callback, eliminating the need for manual
+ * focus restoration boilerplate.
+ *
+ * **Improvements over useModalTriggerProps:**
+ * - ✅ No manual ref creation
+ * - ✅ Automatic focus restoration via onCloseAutoFocus callback
+ * - ✅ Automatic ARIA attributes
+ *
+ * **Why modalTrigger prop is still better:**
+ * - Better touch device support
+ * - Follows WAI-ARIA Dialog best practices
+ * - Less boilerplate overall
+ *
+ * @param modalId - Optional ID of the modal element for aria-controls
+ * @returns Object with triggerRef, ARIA props, and onCloseAutoFocus callback
+ *
+ * @example
+ * ```tsx
+ * const [isOpen, setIsOpen] = useState(false);
+ * const { triggerRef, triggerProps, onCloseAutoFocus } = useModalExternalTrigger();
+ *
+ * return (
+ *   <>
+ *     <Button
+ *       ref={triggerRef}
+ *       {...triggerProps(isOpen)}
+ *       onClick={() => setIsOpen(true)}
+ *     >
+ *       Open Modal
+ *     </Button>
+ *     <Modal
+ *       open={isOpen}
+ *       onOpenChange={setIsOpen}
+ *       onCloseAutoFocus={onCloseAutoFocus}
+ *     >
+ *       <ModalBody>Content</ModalBody>
+ *     </Modal>
+ *   </>
+ * );
+ * ```
+ */
+export function useModalExternalTrigger<
+  T extends HTMLElement = HTMLButtonElement
+>(modalId?: string) {
+  const triggerRef = React.useRef<T>(null);
+
+  const triggerProps = React.useCallback(
+    (isOpen: boolean) => ({
+      "aria-haspopup": "dialog" as const,
+      "aria-expanded": isOpen,
+      ...(modalId ? { "aria-controls": modalId } : {}),
+    }),
+    [modalId]
+  );
+
+  const onCloseAutoFocus = React.useCallback((e: Event) => {
+    e.preventDefault();
+    triggerRef.current?.focus();
+  }, []);
+
+  return { triggerRef, triggerProps, onCloseAutoFocus };
+}
+
 export default Modal;

package/src/v2/ModalTypes.ts

@@ -145,6 +145,29 @@ export type TypeModalActionProps =
 // MODAL PROPS - Main Modal component types
 // =============================================================================
 
+/**
+ * Event handler props from Radix UI Dialog.Content.
+ * These control modal interaction behavior like closing on outside clicks or escape key.
+ */
+type DialogContentEventHandlers = Pick<
+  React.ComponentPropsWithoutRef<typeof Dialog.Content>,
+  | "onOpenAutoFocus"
+  | "onCloseAutoFocus"
+  | "onEscapeKeyDown"
+  | "onPointerDownOutside"
+  | "onFocusOutside"
+  | "onInteractOutside"
+>;
+
+/**
+ * Dialog.Content event handlers excluding onInteractOutside.
+ * Used for draggable modals where onInteractOutside conflicts with the draggable UX.
+ */
+type DialogContentEventHandlersWithoutInteractOutside = Omit<
+  DialogContentEventHandlers,
+  "onInteractOutside"
+>;
+
 /**
  * Base common props shared by all modal variants (without close button props).
  */
@@ -182,6 +205,18 @@ type TypeModalCommonPropsBase = TypeContainerProps &
 
     /** Controls the z-index CSS property (defaults to 6 to match Modal v1) */
     zIndex?: number;
+
+    /**
+     * Prevents the modal from closing when clicking outside.
+     * The onInteractOutside handler will still be called if provided.
+     */
+    disableOutsideClickClose?: boolean;
+
+    /**
+     * Prevents the modal from closing when pressing the Escape key.
+     * The onEscapeKeyDown handler will still be called if provided.
+     */
+    disableEscapeKeyClose?: boolean;
   };
 
 /**
@@ -244,18 +279,30 @@ type TypeModalCommonProps =
 /**
  * Base props with draggable and showOverlay relationship enforced.
  *
- * When draggable is true, showOverlay must be false because the overlay
- * would block interaction with content behind the modal.
+ * When draggable is true:
+ * - showOverlay must be false (overlay would block interaction with content behind the modal)
+ * - onInteractOutside is not allowed (conflicts with draggable UX which needs to keep modal open)
+ * - disableOutsideClickClose is not allowed (since onInteractOutside is not supported)
+ *
+ * When draggable is false (or undefined):
+ * - All Dialog.Content event handlers are available including onInteractOutside
+ * - disableOutsideClickClose can be used
  */
 type TypeModalBaseProps =
-  | (TypeModalCommonProps & {
-      draggable: true;
-      showOverlay?: false;
-    })
-  | (TypeModalCommonProps & {
-      draggable?: false;
-      showOverlay?: boolean;
-    });
+  | (TypeModalCommonProps &
+      DialogContentEventHandlersWithoutInteractOutside & {
+        draggable: true;
+        showOverlay?: false;
+        /** onInteractOutside is not supported for draggable modals */
+        onInteractOutside?: never;
+        /** disableOutsideClickClose is not supported for draggable modals */
+        disableOutsideClickClose?: never;
+      })
+  | (TypeModalCommonProps &
+      DialogContentEventHandlers & {
+        draggable?: false;
+        showOverlay?: boolean;
+      });
 
 /**
  * Modal props with title provided.

package/src/v2/ModalV2.stories.tsx

@@ -4,6 +4,13 @@ import { Box } from "@sproutsocial/seeds-react-box";
 import { Button } from "@sproutsocial/seeds-react-button";
 import Text from "@sproutsocial/seeds-react-text";
 import { FormField } from "@sproutsocial/seeds-react-form-field";
+import {
+  MenuContent,
+  MenuItem,
+  MenuToggleButton,
+  SingleSelectMenu,
+  type TypeSingleSelectMenuProps,
+} from "@sproutsocial/seeds-react-menu";
 import {
   Modal,
   ModalHeader,
@@ -11,6 +18,8 @@ import {
   ModalBody,
   ModalCloseWrapper,
   ModalCustomFooter,
+  ModalExternalTrigger,
+  useModalExternalTrigger,
 } from ".";
 
 const meta: Meta<typeof Modal> = {
@@ -83,9 +92,11 @@ export const Default: Story = {
       >
         <ModalHeader title="Modal Title" subtitle="This is a subtitle" />
         <ModalBody>
-          This modal uses uncontrolled state - no need to manage open/close
-          state! The modalTrigger prop and floating close button handle
-          everything.
+          <Text>
+            This modal uses uncontrolled state - no need to manage open/close
+            state! The modalTrigger prop and floating close button handle
+            everything.
+          </Text>
         </ModalBody>
         <ModalFooter
           cancelButton={<Button>Cancel</Button>}
@@ -876,3 +887,267 @@ export const CustomFooterOverride: Story = {
     );
   },
 };
+
+export const SingleSelectMenuInModal: Story = {
+  render: () => {
+    const [selectedItem, setSelectedItem] =
+      useState<TypeSingleSelectMenuProps["selectedItem"]>(null);
+
+    return (
+      <>
+        <Modal
+          modalTrigger={<Button appearance="primary">Open Modal</Button>}
+          showOverlay={true}
+          aria-label="Demo Modal"
+          closeButtonProps={{ "aria-label": "Close" }}
+        >
+          <ModalHeader title="Select an Option" />
+          <ModalBody>
+            <Box p={400}>
+              <SingleSelectMenu
+                popoutProps={{ appendToBody: false }}
+                selectedItem={selectedItem}
+                onSelectedItemChange={({ selectedItem: item }) =>
+                  setSelectedItem(item)
+                }
+                menuToggleElement={
+                  <MenuToggleButton>
+                    {selectedItem?.id ?? "Select..."}
+                  </MenuToggleButton>
+                }
+              >
+                <MenuContent>
+                  <MenuItem id="option-1">Option 1</MenuItem>
+                  <MenuItem id="option-2">Option 2</MenuItem>
+                  <MenuItem id="option-3">Option 3</MenuItem>
+                </MenuContent>
+              </SingleSelectMenu>
+            </Box>
+          </ModalBody>
+        </Modal>
+      </>
+    );
+  },
+};
+
+/**
+ * Example using the useModalExternalTrigger hook for external triggers.
+ *
+ * ⚠️ NOT RECOMMENDED - This is a last resort pattern. Prefer using modalTrigger prop.
+ *
+ * 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.
+ */
+export const ExternalTriggerWithHook: Story = {
+  render: () => {
+    const [isOpen, setIsOpen] = useState(false);
+    const { triggerRef, triggerProps, onCloseAutoFocus } =
+      useModalExternalTrigger();
+
+    return (
+      <Box>
+        <Text mb={400} fontWeight="semibold">
+          ⚠️ LAST RESORT: 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).
+        </Text>
+
+        <Text mb={400} fontWeight="semibold">
+          Benefits:
+        </Text>
+        <Box as="ul" pl={400} mb={400}>
+          <li>
+            <Text>
+              Works with any trigger element (Button, custom components, etc.)
+            </Text>
+          </li>
+          <li>
+            <Text>
+              Automatic focus restoration via onCloseAutoFocus callback
+            </Text>
+          </li>
+          <li>
+            <Text>No manual ref creation needed</Text>
+          </li>
+        </Box>
+
+        <Button
+          ref={triggerRef}
+          {...triggerProps(isOpen)}
+          appearance="primary"
+          onClick={() => setIsOpen(true)}
+        >
+          Open Modal (External Trigger)
+        </Button>
+
+        <Modal
+          open={isOpen}
+          onOpenChange={setIsOpen}
+          onCloseAutoFocus={onCloseAutoFocus}
+          aria-label="External Trigger Hook Modal"
+          closeButtonAriaLabel="Close Modal"
+        >
+          <ModalHeader
+            title="External Trigger with Hook"
+            subtitle="Using useModalExternalTrigger"
+          />
+          <ModalBody>
+            <Text mb={400}>
+              The useModalExternalTrigger hook simplifies external trigger setup
+              by:
+            </Text>
+            <Box as="ul" pl={400}>
+              <li>
+                <Text>Managing the trigger ref internally</Text>
+              </li>
+              <li>
+                <Text>Providing ARIA props via triggerProps function</Text>
+              </li>
+              <li>
+                <Text>
+                  Handling focus restoration via onCloseAutoFocus callback
+                </Text>
+              </li>
+            </Box>
+            <Text mt={400}>
+              This eliminates the boilerplate of manual ref management and
+              custom onCloseAutoFocus implementation.
+            </Text>
+          </ModalBody>
+          <ModalFooter
+            cancelButton={
+              <ModalCloseWrapper>
+                <Button>Cancel</Button>
+              </ModalCloseWrapper>
+            }
+            primaryButton={
+              <ModalCloseWrapper>
+                <Button appearance="primary">Confirm</Button>
+              </ModalCloseWrapper>
+            }
+          />
+        </Modal>
+      </Box>
+    );
+  },
+};
+
+/**
+ * Example using the ModalExternalTrigger component for external triggers.
+ *
+ * ⚠️ NOT RECOMMENDED - This is a last resort pattern. Prefer using modalTrigger prop.
+ *
+ * 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.
+ */
+export const ExternalTriggerComponent: Story = {
+  render: () => {
+    const [isOpen, setIsOpen] = useState(false);
+    const triggerRef = React.useRef<HTMLButtonElement>(null);
+
+    return (
+      <Box>
+        <Text mb={400} fontWeight="semibold">
+          ⚠️ LAST RESORT: 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.
+        </Text>
+
+        <Text mb={400} fontWeight="semibold">
+          Benefits:
+        </Text>
+        <Box as="ul" pl={400} mb={400}>
+          <li>
+            <Text>
+              Automatic ARIA attributes (aria-haspopup, aria-expanded, etc.)
+            </Text>
+          </li>
+          <li>
+            <Text>
+              All Button props supported (appearance, size, disabled, etc.)
+            </Text>
+          </li>
+          <li>
+            <Text>Cleaner than hook for Button-only triggers</Text>
+          </li>
+        </Box>
+
+        <Text mb={400} fontWeight="semibold">
+          Limitation:
+        </Text>
+        <Text mb={400}>
+          Focus restoration still requires manual onCloseAutoFocus handling.
+        </Text>
+
+        <ModalExternalTrigger
+          ref={triggerRef}
+          isOpen={isOpen}
+          onTrigger={() => setIsOpen(true)}
+          appearance="primary"
+          size="default"
+        >
+          Open Modal (External Trigger)
+        </ModalExternalTrigger>
+
+        <Modal
+          open={isOpen}
+          onOpenChange={setIsOpen}
+          onCloseAutoFocus={(e) => {
+            e.preventDefault();
+            triggerRef.current?.focus();
+          }}
+          aria-label="External Trigger Component Modal"
+          closeButtonAriaLabel="Close Modal"
+        >
+          <ModalHeader
+            title="External Trigger Component"
+            subtitle="Using ModalExternalTrigger"
+          />
+          <ModalBody>
+            <Text mb={400}>
+              ModalExternalTrigger extends Seeds Button with automatic ARIA
+              attributes:
+            </Text>
+            <Box as="ul" pl={400}>
+              <li>
+                <Text>aria-haspopup="dialog"</Text>
+              </li>
+              <li>
+                <Text>aria-expanded based on isOpen prop</Text>
+              </li>
+              <li>
+                <Text>aria-controls (if modalId provided)</Text>
+              </li>
+            </Box>
+            <Text mt={400}>
+              Supports all Button props (appearance, size, disabled, etc.).
+              Focus restoration requires manual onCloseAutoFocus handling.
+            </Text>
+          </ModalBody>
+          <ModalFooter
+            cancelButton={
+              <ModalCloseWrapper>
+                <Button>Cancel</Button>
+              </ModalCloseWrapper>
+            }
+            primaryButton={
+              <ModalCloseWrapper>
+                <Button appearance="primary">Confirm</Button>
+              </ModalCloseWrapper>
+            }
+          />
+        </Modal>
+      </Box>
+    );
+  },
+};

package/src/v2/components/ModalContent.tsx

@@ -119,6 +119,15 @@ interface ModalContentProps {
   draggable?: boolean;
   zIndex?: number;
   rest: any;
+  dialogContentProps?: Pick<
+    React.ComponentPropsWithoutRef<typeof Dialog.Content>,
+    | "onOpenAutoFocus"
+    | "onCloseAutoFocus"
+    | "onEscapeKeyDown"
+    | "onPointerDownOutside"
+    | "onFocusOutside"
+    | "onInteractOutside"
+  >;
 }
 
 /**
@@ -131,13 +140,14 @@ export const StaticModalContent: React.FC<ModalContentProps> = ({
   dataAttributes,
   zIndex,
   rest,
+  dialogContentProps,
 }) => {
   const isMobile = useIsMobile();
   const contentVariants = getContentVariants(isMobile, false);
 
   return (
     <DragContext.Provider value={null}>
-      <Dialog.Content asChild aria-label={label}>
+      <Dialog.Content asChild aria-label={label} {...dialogContentProps}>
         <StyledMotionWrapper
           $isMobile={isMobile}
           $zIndex={zIndex}
@@ -170,6 +180,7 @@ export const DraggableModalContent: React.FC<ModalContentProps> = ({
   dataAttributes,
   zIndex,
   rest,
+  dialogContentProps,
 }) => {
   const [position, setPosition] = React.useState({ x: 0, y: 0 });
   const [isDragging, setIsDragging] = React.useState(false);
@@ -274,6 +285,7 @@ export const DraggableModalContent: React.FC<ModalContentProps> = ({
       <Dialog.Content
         asChild
         aria-label={label}
+        {...dialogContentProps}
         onInteractOutside={handleInteractOutside}
       >
         <StyledMotionWrapper