@sproutsocial/seeds-react-modal 2.3.0 → 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        38.17 KB
-CJS dist/v1/index.js     9.86 KB
-CJS dist/v2/index.js     30.16 KB
-CJS dist/index.js.map    69.27 KB
-CJS dist/v1/index.js.map 13.03 KB
-CJS dist/v2/index.js.map 55.88 KB
-CJS ⚡️ Build success in 201ms
 ESM dist/esm/index.js              583.00 B
 ESM dist/esm/v1/index.js           165.00 B
-ESM dist/esm/v2/index.js           596.00 B
+ESM dist/esm/v2/index.js           746.00 B
 ESM dist/esm/chunk-IYDY4OPB.js     7.12 KB
-ESM dist/esm/chunk-4F3JQDQZ.js     25.32 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/chunk-IYDY4OPB.js.map 12.85 KB
-ESM dist/esm/chunk-4F3JQDQZ.js.map 54.99 KB
-ESM ⚡️ Build success in 205ms
+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 16886ms
+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-B9lvk1rm.d.ts  16.80 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-B9lvk1rm.d.mts 16.80 KB
-Done in 19.02s.
+DTS dist/ModalAction-BHG3Zbd9.d.mts 20.46 KB
+Done in 22.38s.

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @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

package/dist/{ModalAction-B9lvk1rm.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';
 
@@ -333,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;
@@ -446,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-B9lvk1rm.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';
 
@@ -333,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;
@@ -446,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/esm/{chunk-4F3JQDQZ.js → chunk-TQ44T5IM.js}

@@ -1,5 +1,5 @@
 // src/v2/Modal.tsx
-import * as React11 from "react";
+import * as React12 from "react";
 import * as Dialog6 from "@radix-ui/react-dialog";
 import { AnimatePresence } from "motion/react";
 
@@ -705,6 +705,34 @@ var ModalAction = ({
 };
 ModalAction.displayName = "ModalAction";
 
+// src/v2/components/ModalExternalTrigger.tsx
+import * as React10 from "react";
+import { Button } from "@sproutsocial/seeds-react-button";
+import { jsx as jsx9 } from "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__ */ jsx9(
+    Button,
+    {
+      ref,
+      onClick: handleClick,
+      "aria-haspopup": "dialog",
+      "aria-expanded": isOpen,
+      "aria-controls": modalId,
+      ...buttonProps
+    }
+  );
+});
+ModalExternalTrigger.displayName = "ModalExternalTrigger";
+
 // src/v2/components/ModalOverlay.tsx
 import "react";
 import styled7 from "styled-components";
@@ -743,7 +771,7 @@ var StyledOverlay = styled7.div.withConfig({
 StyledOverlay.displayName = "ModalOverlay";
 
 // src/v2/Modal.tsx
-import { Fragment, jsx as jsx9, jsxs as jsxs3 } from "react/jsx-runtime";
+import { Fragment, jsx as jsx10, jsxs as jsxs3 } from "react/jsx-runtime";
 var Modal = (props) => {
   const {
     children,
@@ -774,15 +802,15 @@ var Modal = (props) => {
     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);
@@ -797,7 +825,7 @@ var Modal = (props) => {
   const isMobile = useIsMobile();
   const overlayVariants = getOverlayVariants(isMobile);
   const ModalContentComponent = draggable ? DraggableModalContent : StaticModalContent;
-  const wrappedOnInteractOutside = React11.useCallback(
+  const wrappedOnInteractOutside = React12.useCallback(
     (e) => {
       if (disableOutsideClickClose) {
         e.preventDefault();
@@ -806,7 +834,7 @@ var Modal = (props) => {
     },
     [disableOutsideClickClose, onInteractOutside]
   );
-  const wrappedOnEscapeKeyDown = React11.useCallback(
+  const wrappedOnEscapeKeyDown = React12.useCallback(
     (e) => {
       if (disableEscapeKeyClose) {
         e.preventDefault();
@@ -823,9 +851,9 @@ var Modal = (props) => {
       onOpenChange: handleOpenChange,
       modal: !draggable,
       children: [
-        modalTrigger && /* @__PURE__ */ jsx9(Dialog6.Trigger, { asChild: true, children: modalTrigger }),
-        /* @__PURE__ */ jsx9(Dialog6.Portal, { forceMount: true, children: /* @__PURE__ */ jsx9(AnimatePresence, { mode: "wait", children: (open ?? isOpen) && /* @__PURE__ */ jsxs3(Fragment, { children: [
-          showOverlay && /* @__PURE__ */ jsx9(Dialog6.Overlay, { asChild: true, children: /* @__PURE__ */ jsx9(
+        modalTrigger && /* @__PURE__ */ jsx10(Dialog6.Trigger, { asChild: true, children: modalTrigger }),
+        /* @__PURE__ */ jsx10(Dialog6.Portal, { forceMount: true, children: /* @__PURE__ */ jsx10(AnimatePresence, { mode: "wait", children: (open ?? isOpen) && /* @__PURE__ */ jsxs3(Fragment, { children: [
+          showOverlay && /* @__PURE__ */ jsx10(Dialog6.Overlay, { asChild: true, children: /* @__PURE__ */ jsx10(
             StyledMotionOverlay,
             {
               $zIndex: zIndex,
@@ -833,7 +861,7 @@ var Modal = (props) => {
               initial: "initial",
               animate: "animate",
               exit: "exit",
-              children: /* @__PURE__ */ jsx9(
+              children: /* @__PURE__ */ jsx10(
                 StyledOverlay,
                 {
                   "data-slot": "modal-overlay",
@@ -862,7 +890,7 @@ var Modal = (props) => {
               },
               children: [
                 /* @__PURE__ */ jsxs3(ModalRail, { children: [
-                  /* @__PURE__ */ jsx9(
+                  /* @__PURE__ */ jsx10(
                     ModalAction,
                     {
                       actionType: "close",
@@ -871,10 +899,10 @@ var Modal = (props) => {
                       "aria-label": closeButtonProps?.["aria-label"] ?? closeButtonAriaLabel
                     }
                   ),
-                  actions?.map((action, idx) => /* @__PURE__ */ jsx9(ModalAction, { ...action }, idx))
+                  actions?.map((action, idx) => /* @__PURE__ */ jsx10(ModalAction, { ...action }, idx))
                 ] }),
-                shouldRenderHeader && /* @__PURE__ */ jsx9(ModalHeader, { title, subtitle }),
-                description && /* @__PURE__ */ jsx9(ModalDescription, { children: description }),
+                shouldRenderHeader && /* @__PURE__ */ jsx10(ModalHeader, { title, subtitle }),
+                description && /* @__PURE__ */ jsx10(ModalDescription, { children: description }),
                 children
               ]
             }
@@ -884,6 +912,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;
 
 export {
@@ -900,6 +954,9 @@ export {
   ModalDescription,
   ModalRail,
   ModalAction,
+  ModalExternalTrigger,
+  useModalTriggerProps,
+  useModalExternalTrigger,
   Modal_default
 };
-//# sourceMappingURL=chunk-4F3JQDQZ.js.map
+//# sourceMappingURL=chunk-TQ44T5IM.js.map