@sproutsocial/seeds-react-modal 2.2.5 → 2.4.0

package/.turbo/turbo-build.log

@@ -8,34 +8,34 @@ $ tsup --dts
 CLI Cleaning output folder
 CJS Build start
 ESM Build start
-CJS dist/index.js        37.00 KB
-CJS dist/v1/index.js     9.86 KB
-CJS dist/v2/index.js     28.98 KB
-CJS dist/index.js.map    66.80 KB
-CJS dist/v1/index.js.map 13.03 KB
-CJS dist/v2/index.js.map 53.42 KB
-CJS ⚡️ Build success in 212ms
-ESM dist/esm/v1/index.js           165.00 B
-ESM dist/esm/v2/index.js           596.00 B
 ESM dist/esm/index.js              583.00 B
+ESM dist/esm/v1/index.js           165.00 B
+ESM dist/esm/v2/index.js           746.00 B
 ESM dist/esm/chunk-IYDY4OPB.js     7.12 KB
-ESM dist/esm/chunk-UP2XQN57.js     24.15 KB
+ESM dist/esm/chunk-TQ44T5IM.js     26.85 KB
+ESM dist/esm/index.js.map          1.05 KB
 ESM dist/esm/v1/index.js.map       71.00 B
 ESM dist/esm/v2/index.js.map       71.00 B
-ESM dist/esm/index.js.map          1.05 KB
 ESM dist/esm/chunk-IYDY4OPB.js.map 12.85 KB
-ESM dist/esm/chunk-UP2XQN57.js.map 52.53 KB
-ESM ⚡️ Build success in 217ms
+ESM dist/esm/chunk-TQ44T5IM.js.map 63.46 KB
+ESM ⚡️ Build success in 280ms
+CJS dist/index.js        39.00 KB
+CJS dist/v1/index.js     9.86 KB
+CJS dist/v2/index.js     31.92 KB
+CJS dist/index.js.map    77.26 KB
+CJS dist/v1/index.js.map 13.03 KB
+CJS dist/v2/index.js.map 64.54 KB
+CJS ⚡️ Build success in 284ms
 DTS Build start
-DTS ⚡️ Build success in 16936ms
+DTS ⚡️ Build success in 19209ms
 DTS dist/index.d.ts                 975.00 B
 DTS dist/v1/index.d.ts              413.00 B
-DTS dist/v2/index.d.ts              1021.00 B
+DTS dist/v2/index.d.ts              3.72 KB
 DTS dist/Modal-ki8oiGbC.d.ts        2.52 KB
-DTS dist/ModalAction-gIgCE73I.d.ts  15.19 KB
+DTS dist/ModalAction-BHG3Zbd9.d.ts  20.46 KB
 DTS dist/index.d.mts                978.00 B
 DTS dist/v1/index.d.mts             415.00 B
-DTS dist/v2/index.d.mts             1022.00 B
+DTS dist/v2/index.d.mts             3.72 KB
 DTS dist/Modal-ki8oiGbC.d.mts       2.52 KB
-DTS dist/ModalAction-gIgCE73I.d.mts 15.19 KB
-Done in 19.68s.
+DTS dist/ModalAction-BHG3Zbd9.d.mts 20.46 KB
+Done in 22.38s.

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @sproutsocial/seeds-react-modal
 
+## 2.4.0
+
+### Minor Changes
+
+- 4a7f66e: Add external trigger helpers for Modal V2:
+
+  - Add `useModalExternalTrigger` hook that manages refs and provides ARIA attributes and focus restoration callback for external triggers
+  - Add `ModalExternalTrigger` component (Button wrapper with automatic ARIA attributes for external triggers)
+  - Update Modal V2 documentation with external trigger patterns and composition proposal
+
+## 2.3.0
+
+### Minor Changes
+
+- c76c353: Add modal interaction control to Modal v2 with both convenience props and Radix UI event handlers.
+
+  Convenience Boolean Props (recommended for simple cases):
+
+  - `disableOutsideClickClose`: Prevents modal from closing when clicking outside. Custom `onInteractOutside` handlers still fire for side effects.
+  - `disableEscapeKeyClose`: Prevents modal from closing when pressing Escape key. Custom `onEscapeKeyDown` handlers still fire for side effects.
+
+  Radix UI Dialog.Content Event Handlers (for granular control):
+
+  - `onInteractOutside`: Control behavior when user interacts outside the modal
+  - `onEscapeKeyDown`: Control behavior when Escape key is pressed
+  - `onPointerDownOutside`: Handle pointer down events outside the modal
+  - `onFocusOutside`: Handle focus moving outside the modal
+  - `onOpenAutoFocus`: Handle focus behavior when modal opens
+  - `onCloseAutoFocus`: Handle focus behavior when modal closes
+
+  Boolean props can be combined with event handlers - the boolean prevents closing while the handler adds custom side effects like analytics or warnings.
+
+  Draggable Modal Restrictions: `disableOutsideClickClose` and `onInteractOutside` are not supported for draggable modals (TypeScript will error) as they conflict with the draggable UX. All other props including `disableEscapeKeyClose` work with draggable modals. This is enforced through TypeScript discriminated union types.
+
+### Patch Changes
+
+- @sproutsocial/seeds-react-theme@3.3.2
+- @sproutsocial/seeds-react-box@1.1.10
+- @sproutsocial/seeds-react-icon@2.1.1
+- @sproutsocial/seeds-react-button@1.3.12
+
 ## 2.2.5
 
 ### Patch Changes

package/dist/{ModalAction-gIgCE73I.d.mts → ModalAction-BHG3Zbd9.d.mts}

@@ -1,8 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
 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';
 
@@ -111,6 +111,16 @@ type TypeModalActionProps = ({
     /** Click handler for the button */
     onClick?: () => void;
 } & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick">);
+/**
+ * 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).
  */
@@ -139,6 +149,16 @@ type TypeModalCommonPropsBase = TypeContainerProps & Omit<React.ComponentPropsWi
     actions?: TypeModalActionProps[];
     /** 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;
 };
 /**
  * Common props with close button accessibility enforcement.
@@ -194,13 +214,23 @@ type TypeModalCommonProps = (TypeModalCommonPropsBase & {
 /**
  * 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 & {
+type TypeModalBaseProps = (TypeModalCommonProps & DialogContentEventHandlersWithoutInteractOutside & {
     draggable: true;
     showOverlay?: false;
-}) | (TypeModalCommonProps & {
+    /** onInteractOutside is not supported for draggable modals */
+    onInteractOutside?: never;
+    /** disableOutsideClickClose is not supported for draggable modals */
+    disableOutsideClickClose?: never;
+}) | (TypeModalCommonProps & DialogContentEventHandlers & {
     draggable?: false;
     showOverlay?: boolean;
 });
@@ -303,6 +333,121 @@ type TypeModalProps = TypeModalPropsWithTitle | TypeModalPropsWithSubtitleOnly |
  * </Modal>
  */
 declare const Modal: (props: TypeModalProps) => react_jsx_runtime.JSX.Element;
+/**
+ * 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>
+ *   </>
+ * );
+ * ```
+ */
+declare function useModalTriggerProps(isOpen: boolean, modalId?: string): {
+    "aria-haspopup": "dialog";
+    "aria-expanded": boolean;
+    "aria-controls"?: string;
+};
+/**
+ * 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>
+ *   </>
+ * );
+ * ```
+ */
+declare function useModalExternalTrigger<T extends HTMLElement = HTMLButtonElement>(modalId?: string): {
+    triggerRef: React.RefObject<T>;
+    triggerProps: (isOpen: boolean) => {
+        "aria-controls"?: string | undefined;
+        "aria-haspopup": "dialog";
+        "aria-expanded": boolean;
+    };
+    onCloseAutoFocus: (e: Event) => void;
+};
 
 interface HeaderProps {
     draggable?: boolean;
@@ -416,4 +561,4 @@ 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 };
+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, useModalExternalTrigger as q, useModalTriggerProps as u };

package/dist/{ModalAction-gIgCE73I.d.ts → ModalAction-BHG3Zbd9.d.ts}

@@ -1,8 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
 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';
 
@@ -111,6 +111,16 @@ type TypeModalActionProps = ({
     /** Click handler for the button */
     onClick?: () => void;
 } & Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick">);
+/**
+ * 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).
  */
@@ -139,6 +149,16 @@ type TypeModalCommonPropsBase = TypeContainerProps & Omit<React.ComponentPropsWi
     actions?: TypeModalActionProps[];
     /** 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;
 };
 /**
  * Common props with close button accessibility enforcement.
@@ -194,13 +214,23 @@ type TypeModalCommonProps = (TypeModalCommonPropsBase & {
 /**
  * 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 & {
+type TypeModalBaseProps = (TypeModalCommonProps & DialogContentEventHandlersWithoutInteractOutside & {
     draggable: true;
     showOverlay?: false;
-}) | (TypeModalCommonProps & {
+    /** onInteractOutside is not supported for draggable modals */
+    onInteractOutside?: never;
+    /** disableOutsideClickClose is not supported for draggable modals */
+    disableOutsideClickClose?: never;
+}) | (TypeModalCommonProps & DialogContentEventHandlers & {
     draggable?: false;
     showOverlay?: boolean;
 });
@@ -303,6 +333,121 @@ type TypeModalProps = TypeModalPropsWithTitle | TypeModalPropsWithSubtitleOnly |
  * </Modal>
  */
 declare const Modal: (props: TypeModalProps) => react_jsx_runtime.JSX.Element;
+/**
+ * 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>
+ *   </>
+ * );
+ * ```
+ */
+declare function useModalTriggerProps(isOpen: boolean, modalId?: string): {
+    "aria-haspopup": "dialog";
+    "aria-expanded": boolean;
+    "aria-controls"?: string;
+};
+/**
+ * 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>
+ *   </>
+ * );
+ * ```
+ */
+declare function useModalExternalTrigger<T extends HTMLElement = HTMLButtonElement>(modalId?: string): {
+    triggerRef: React.RefObject<T>;
+    triggerProps: (isOpen: boolean) => {
+        "aria-controls"?: string | undefined;
+        "aria-haspopup": "dialog";
+        "aria-expanded": boolean;
+    };
+    onCloseAutoFocus: (e: Event) => void;
+};
 
 interface HeaderProps {
     draggable?: boolean;
@@ -416,4 +561,4 @@ 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 };
+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, useModalExternalTrigger as q, useModalTriggerProps as u };