@sproutsocial/seeds-react-modal 2.2.5 → 2.4.0

package/dist/v2/index.d.mts

@@ -1,11 +1,85 @@
-export { M as Modal, g as ModalAction, d as ModalBody, e as ModalCloseWrapper, p as ModalCloseWrapperProps, i as ModalCustomFooter, h as ModalCustomHeader, a as ModalDescription, c as ModalFooter, b as ModalHeader, f as ModalRail, o as TypeModalActionProps, l as TypeModalBodyProps, m as TypeModalDescriptionProps, k as TypeModalFooterProps, j as TypeModalHeaderProps, T as TypeModalProps, n as TypeModalRailProps } from '../ModalAction-gIgCE73I.mjs';
+export { M as Modal, g as ModalAction, d as ModalBody, e as ModalCloseWrapper, p as ModalCloseWrapperProps, i as ModalCustomFooter, h as ModalCustomHeader, a as ModalDescription, c as ModalFooter, b as ModalHeader, f as ModalRail, o as TypeModalActionProps, l as TypeModalBodyProps, m as TypeModalDescriptionProps, k as TypeModalFooterProps, j as TypeModalHeaderProps, T as TypeModalProps, n as TypeModalRailProps, q as useModalExternalTrigger, u as useModalTriggerProps } from '../ModalAction-BHG3Zbd9.mjs';
+import * as React from 'react';
+import { TypeButtonProps } from '@sproutsocial/seeds-react-button';
 import 'react/jsx-runtime';
 import 'styled-components';
 import '@sproutsocial/seeds-react-box';
-import 'react';
 import '@radix-ui/react-dialog';
 import '@sproutsocial/seeds-react-icon';
 
+/**
+ * Props for ModalExternalTrigger component.
+ */
+interface ModalExternalTriggerProps extends Omit<TypeButtonProps, "onClick"> {
+    /** Callback when button is clicked to trigger modal open */
+    onTrigger: () => void;
+    /** Whether the modal is currently open (for ARIA expanded state) */
+    isOpen: boolean;
+    /** Optional modal ID for aria-controls attribute */
+    modalId?: string;
+    /** Optional onClick handler (called before onTrigger) */
+    onClick?: React.MouseEventHandler<HTMLButtonElement>;
+}
+/**
+ * A Button component pre-configured for triggering modals from outside the Modal component tree.
+ *
+ * ⚠️ **NOT RECOMMENDED** - Prefer using modalTrigger prop or ModalTrigger component.
+ * Use this component ONLY as a last resort when architectural constraints prevent keeping
+ * the trigger inside the Modal component tree.
+ *
+ * This component wraps the Seeds Button with automatic ARIA attributes for modal triggers.
+ * However, focus restoration still requires manual handling via onCloseAutoFocus callback
+ * due to Radix UI's architectural limitations with external triggers.
+ *
+ * **Why modalTrigger prop is better:**
+ * - Automatic ARIA attributes
+ * - Automatic focus restoration (no onCloseAutoFocus needed)
+ * - Better touch device support
+ * - Follows WAI-ARIA Dialog best practices
+ *
+ * **When to use ModalExternalTrigger:**
+ * - Trigger must live outside Modal component tree (e.g., in a page header)
+ * - Using Seeds Button as the trigger
+ * - Want automatic ARIA attributes without manual hook usage
+ *
+ * **Usage pattern with focus restoration:**
+ * You must still handle focus restoration manually by passing a ref and implementing
+ * onCloseAutoFocus on the Modal component.
+ *
+ * @example
+ * ```tsx
+ * const [isOpen, setIsOpen] = useState(false);
+ * const triggerRef = useRef<HTMLButtonElement>(null);
+ *
+ * return (
+ *   <>
+ *     <ModalExternalTrigger
+ *       ref={triggerRef}
+ *       isOpen={isOpen}
+ *       onTrigger={() => setIsOpen(true)}
+ *       appearance="primary"
+ *     >
+ *       Open Modal
+ *     </ModalExternalTrigger>
+ *
+ *     <Modal
+ *       open={isOpen}
+ *       onOpenChange={setIsOpen}
+ *       onCloseAutoFocus={(e) => {
+ *         e.preventDefault();
+ *         triggerRef.current?.focus();
+ *       }}
+ *     >
+ *       <ModalBody>Content</ModalBody>
+ *     </Modal>
+ *   </>
+ * );
+ * ```
+ *
+ * @see useModalExternalTrigger - Hook alternative for non-Button triggers
+ */
+declare const ModalExternalTrigger: React.ForwardRefExoticComponent<Omit<ModalExternalTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+
 declare const DEFAULT_MODAL_WIDTH = "600px";
 declare const DEFAULT_MODAL_BG = "container.background.base";
 declare const BODY_PADDING = "64px";
@@ -16,4 +90,4 @@ declare const MODAL_SIZE_PRESETS: {
     readonly full: "90vw";
 };
 
-export { BODY_PADDING, DEFAULT_MODAL_BG, DEFAULT_MODAL_WIDTH, MODAL_SIZE_PRESETS };
+export { BODY_PADDING, DEFAULT_MODAL_BG, DEFAULT_MODAL_WIDTH, MODAL_SIZE_PRESETS, ModalExternalTrigger, type ModalExternalTriggerProps };

package/dist/v2/index.d.ts

@@ -1,11 +1,85 @@
-export { M as Modal, g as ModalAction, d as ModalBody, e as ModalCloseWrapper, p as ModalCloseWrapperProps, i as ModalCustomFooter, h as ModalCustomHeader, a as ModalDescription, c as ModalFooter, b as ModalHeader, f as ModalRail, o as TypeModalActionProps, l as TypeModalBodyProps, m as TypeModalDescriptionProps, k as TypeModalFooterProps, j as TypeModalHeaderProps, T as TypeModalProps, n as TypeModalRailProps } from '../ModalAction-gIgCE73I.js';
+export { M as Modal, g as ModalAction, d as ModalBody, e as ModalCloseWrapper, p as ModalCloseWrapperProps, i as ModalCustomFooter, h as ModalCustomHeader, a as ModalDescription, c as ModalFooter, b as ModalHeader, f as ModalRail, o as TypeModalActionProps, l as TypeModalBodyProps, m as TypeModalDescriptionProps, k as TypeModalFooterProps, j as TypeModalHeaderProps, T as TypeModalProps, n as TypeModalRailProps, q as useModalExternalTrigger, u as useModalTriggerProps } from '../ModalAction-BHG3Zbd9.js';
+import * as React from 'react';
+import { TypeButtonProps } from '@sproutsocial/seeds-react-button';
 import 'react/jsx-runtime';
 import 'styled-components';
 import '@sproutsocial/seeds-react-box';
-import 'react';
 import '@radix-ui/react-dialog';
 import '@sproutsocial/seeds-react-icon';
 
+/**
+ * Props for ModalExternalTrigger component.
+ */
+interface ModalExternalTriggerProps extends Omit<TypeButtonProps, "onClick"> {
+    /** Callback when button is clicked to trigger modal open */
+    onTrigger: () => void;
+    /** Whether the modal is currently open (for ARIA expanded state) */
+    isOpen: boolean;
+    /** Optional modal ID for aria-controls attribute */
+    modalId?: string;
+    /** Optional onClick handler (called before onTrigger) */
+    onClick?: React.MouseEventHandler<HTMLButtonElement>;
+}
+/**
+ * A Button component pre-configured for triggering modals from outside the Modal component tree.
+ *
+ * ⚠️ **NOT RECOMMENDED** - Prefer using modalTrigger prop or ModalTrigger component.
+ * Use this component ONLY as a last resort when architectural constraints prevent keeping
+ * the trigger inside the Modal component tree.
+ *
+ * This component wraps the Seeds Button with automatic ARIA attributes for modal triggers.
+ * However, focus restoration still requires manual handling via onCloseAutoFocus callback
+ * due to Radix UI's architectural limitations with external triggers.
+ *
+ * **Why modalTrigger prop is better:**
+ * - Automatic ARIA attributes
+ * - Automatic focus restoration (no onCloseAutoFocus needed)
+ * - Better touch device support
+ * - Follows WAI-ARIA Dialog best practices
+ *
+ * **When to use ModalExternalTrigger:**
+ * - Trigger must live outside Modal component tree (e.g., in a page header)
+ * - Using Seeds Button as the trigger
+ * - Want automatic ARIA attributes without manual hook usage
+ *
+ * **Usage pattern with focus restoration:**
+ * You must still handle focus restoration manually by passing a ref and implementing
+ * onCloseAutoFocus on the Modal component.
+ *
+ * @example
+ * ```tsx
+ * const [isOpen, setIsOpen] = useState(false);
+ * const triggerRef = useRef<HTMLButtonElement>(null);
+ *
+ * return (
+ *   <>
+ *     <ModalExternalTrigger
+ *       ref={triggerRef}
+ *       isOpen={isOpen}
+ *       onTrigger={() => setIsOpen(true)}
+ *       appearance="primary"
+ *     >
+ *       Open Modal
+ *     </ModalExternalTrigger>
+ *
+ *     <Modal
+ *       open={isOpen}
+ *       onOpenChange={setIsOpen}
+ *       onCloseAutoFocus={(e) => {
+ *         e.preventDefault();
+ *         triggerRef.current?.focus();
+ *       }}
+ *     >
+ *       <ModalBody>Content</ModalBody>
+ *     </Modal>
+ *   </>
+ * );
+ * ```
+ *
+ * @see useModalExternalTrigger - Hook alternative for non-Button triggers
+ */
+declare const ModalExternalTrigger: React.ForwardRefExoticComponent<Omit<ModalExternalTriggerProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
+
 declare const DEFAULT_MODAL_WIDTH = "600px";
 declare const DEFAULT_MODAL_BG = "container.background.base";
 declare const BODY_PADDING = "64px";
@@ -16,4 +90,4 @@ declare const MODAL_SIZE_PRESETS: {
     readonly full: "90vw";
 };
 
-export { BODY_PADDING, DEFAULT_MODAL_BG, DEFAULT_MODAL_WIDTH, MODAL_SIZE_PRESETS };
+export { BODY_PADDING, DEFAULT_MODAL_BG, DEFAULT_MODAL_WIDTH, MODAL_SIZE_PRESETS, ModalExternalTrigger, type ModalExternalTriggerProps };

package/dist/v2/index.js

@@ -41,14 +41,17 @@ __export(v2_exports, {
   ModalCustomFooter: () => ModalCustomFooter,
   ModalCustomHeader: () => ModalCustomHeader,
   ModalDescription: () => ModalDescription,
+  ModalExternalTrigger: () => ModalExternalTrigger,
   ModalFooter: () => ModalFooter,
   ModalHeader: () => ModalHeader,
-  ModalRail: () => ModalRail
+  ModalRail: () => ModalRail,
+  useModalExternalTrigger: () => useModalExternalTrigger,
+  useModalTriggerProps: () => useModalTriggerProps
 });
 module.exports = __toCommonJS(v2_exports);
 
 // src/v2/Modal.tsx
-var React11 = __toESM(require("react"));
+var React12 = __toESM(require("react"));
 var Dialog6 = __toESM(require("@radix-ui/react-dialog"));
 var import_react4 = require("motion/react");
 
@@ -279,11 +282,12 @@ var StaticModalContent = ({
   label,
   dataAttributes,
   zIndex,
-  rest
+  rest,
+  dialogContentProps
 }) => {
   const isMobile = useIsMobile();
   const contentVariants = getContentVariants(isMobile, false);
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DragContext.Provider, { value: null, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Dialog.Content, { asChild: true, "aria-label": label, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DragContext.Provider, { value: null, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Dialog.Content, { asChild: true, "aria-label": label, ...dialogContentProps, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
     StyledMotionWrapper,
     {
       $isMobile: isMobile,
@@ -310,7 +314,8 @@ var DraggableModalContent = ({
   label,
   dataAttributes,
   zIndex,
-  rest
+  rest,
+  dialogContentProps
 }) => {
   const [position, setPosition] = React2.useState({ x: 0, y: 0 });
   const [isDragging, setIsDragging] = React2.useState(false);
@@ -379,6 +384,7 @@ var DraggableModalContent = ({
     {
       asChild: true,
       "aria-label": label,
+      ...dialogContentProps,
       onInteractOutside: handleInteractOutside,
       children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
         StyledMotionWrapper,
@@ -731,6 +737,34 @@ var ModalAction = ({
 };
 ModalAction.displayName = "ModalAction";
 
+// src/v2/components/ModalExternalTrigger.tsx
+var React10 = __toESM(require("react"));
+var import_seeds_react_button = require("@sproutsocial/seeds-react-button");
+var import_jsx_runtime9 = require("react/jsx-runtime");
+var ModalExternalTrigger = React10.forwardRef(({ isOpen, onTrigger, modalId, onClick, ...buttonProps }, ref) => {
+  const handleClick = React10.useCallback(
+    (e) => {
+      onClick?.(e);
+      if (!e.defaultPrevented) {
+        onTrigger();
+      }
+    },
+    [onClick, onTrigger]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+    import_seeds_react_button.Button,
+    {
+      ref,
+      onClick: handleClick,
+      "aria-haspopup": "dialog",
+      "aria-expanded": isOpen,
+      "aria-controls": modalId,
+      ...buttonProps
+    }
+  );
+});
+ModalExternalTrigger.displayName = "ModalExternalTrigger";
+
 // src/v2/components/ModalOverlay.tsx
 var import_react2 = require("react");
 var import_styled_components8 = __toESM(require("styled-components"));
@@ -764,7 +798,7 @@ var StyledOverlay = import_styled_components8.default.div.withConfig({
 StyledOverlay.displayName = "ModalOverlay";
 
 // src/v2/Modal.tsx
-var import_jsx_runtime9 = require("react/jsx-runtime");
+var import_jsx_runtime10 = require("react/jsx-runtime");
 var Modal = (props) => {
   const {
     children,
@@ -783,17 +817,27 @@ var Modal = (props) => {
     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;
-  const [isOpen, setIsOpen] = React11.useState(defaultOpen ?? false);
-  const handleOpenChange = React11.useCallback(
+  const [isOpen, setIsOpen] = React12.useState(defaultOpen ?? false);
+  const handleOpenChange = React12.useCallback(
     (newOpen) => {
       setIsOpen(newOpen);
       onOpenChange?.(newOpen);
     },
     [onOpenChange]
   );
-  const dataAttributes = React11.useMemo(() => {
+  const dataAttributes = React12.useMemo(() => {
     const attrs = {};
     Object.entries(data).forEach(([key, value]) => {
       attrs[`data-${key}`] = String(value);
@@ -808,7 +852,25 @@ var Modal = (props) => {
   const isMobile = useIsMobile();
   const overlayVariants = getOverlayVariants(isMobile);
   const ModalContentComponent = draggable ? DraggableModalContent : StaticModalContent;
-  return /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)(
+  const wrappedOnInteractOutside = React12.useCallback(
+    (e) => {
+      if (disableOutsideClickClose) {
+        e.preventDefault();
+      }
+      onInteractOutside?.(e);
+    },
+    [disableOutsideClickClose, onInteractOutside]
+  );
+  const wrappedOnEscapeKeyDown = React12.useCallback(
+    (e) => {
+      if (disableEscapeKeyClose) {
+        e.preventDefault();
+      }
+      onEscapeKeyDown?.(e);
+    },
+    [disableEscapeKeyClose, onEscapeKeyDown]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
     Dialog6.Root,
     {
       open,
@@ -816,9 +878,9 @@ var Modal = (props) => {
       onOpenChange: handleOpenChange,
       modal: !draggable,
       children: [
-        modalTrigger && /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(Dialog6.Trigger, { asChild: true, children: modalTrigger }),
-        /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(Dialog6.Portal, { forceMount: true, children: /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(import_react4.AnimatePresence, { mode: "wait", children: (open ?? isOpen) && /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)(import_jsx_runtime9.Fragment, { children: [
-          showOverlay && /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(Dialog6.Overlay, { asChild: true, children: /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+        modalTrigger && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Dialog6.Trigger, { asChild: true, children: modalTrigger }),
+        /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Dialog6.Portal, { forceMount: true, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(import_react4.AnimatePresence, { mode: "wait", children: (open ?? isOpen) && /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_jsx_runtime10.Fragment, { children: [
+          showOverlay && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(Dialog6.Overlay, { asChild: true, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
             StyledMotionOverlay,
             {
               $zIndex: zIndex,
@@ -826,17 +888,18 @@ var Modal = (props) => {
               initial: "initial",
               animate: "animate",
               exit: "exit",
-              children: /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+              children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
                 StyledOverlay,
                 {
                   "data-slot": "modal-overlay",
                   "data-qa-modal-overlay": true,
+                  "data-testid": "modal-overlay",
                   allowInteraction: draggable
                 }
               )
             }
           ) }),
-          /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)(
+          /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(
             ModalContentComponent,
             {
               label,
@@ -844,9 +907,17 @@ var Modal = (props) => {
               draggable,
               zIndex,
               rest,
+              dialogContentProps: {
+                onOpenAutoFocus,
+                onCloseAutoFocus,
+                onEscapeKeyDown: wrappedOnEscapeKeyDown,
+                onPointerDownOutside,
+                onFocusOutside,
+                onInteractOutside: wrappedOnInteractOutside
+              },
               children: [
-                /* @__PURE__ */ (0, import_jsx_runtime9.jsxs)(ModalRail, { children: [
-                  /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(
+                /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(ModalRail, { children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(
                     ModalAction,
                     {
                       actionType: "close",
@@ -855,10 +926,10 @@ var Modal = (props) => {
                       "aria-label": closeButtonProps?.["aria-label"] ?? closeButtonAriaLabel
                     }
                   ),
-                  actions?.map((action, idx) => /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(ModalAction, { ...action }, idx))
+                  actions?.map((action, idx) => /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(ModalAction, { ...action }, idx))
                 ] }),
-                shouldRenderHeader && /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(ModalHeader, { title, subtitle }),
-                description && /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(ModalDescription, { children: description }),
+                shouldRenderHeader && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(ModalHeader, { title, subtitle }),
+                description && /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(ModalDescription, { children: description }),
                 children
               ]
             }
@@ -868,6 +939,32 @@ var Modal = (props) => {
     }
   );
 };
+function useModalTriggerProps(isOpen, modalId) {
+  return React12.useMemo(
+    () => ({
+      "aria-haspopup": "dialog",
+      "aria-expanded": isOpen,
+      ...modalId ? { "aria-controls": modalId } : {}
+    }),
+    [isOpen, modalId]
+  );
+}
+function useModalExternalTrigger(modalId) {
+  const triggerRef = React12.useRef(null);
+  const triggerProps = React12.useCallback(
+    (isOpen) => ({
+      "aria-haspopup": "dialog",
+      "aria-expanded": isOpen,
+      ...modalId ? { "aria-controls": modalId } : {}
+    }),
+    [modalId]
+  );
+  const onCloseAutoFocus = React12.useCallback((e) => {
+    e.preventDefault();
+    triggerRef.current?.focus();
+  }, []);
+  return { triggerRef, triggerProps, onCloseAutoFocus };
+}
 var Modal_default = Modal;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -882,8 +979,11 @@ var Modal_default = Modal;
   ModalCustomFooter,
   ModalCustomHeader,
   ModalDescription,
+  ModalExternalTrigger,
   ModalFooter,
   ModalHeader,
-  ModalRail
+  ModalRail,
+  useModalExternalTrigger,
+  useModalTriggerProps
 });
 //# sourceMappingURL=index.js.map