@sproutsocial/seeds-react-modal 2.4.8 → 2.5.0

package/src/v2/ModalV2.stories.tsx

@@ -3,9 +3,14 @@ import type { Meta, StoryObj } from "@storybook/react";
 import { Box } from "@sproutsocial/seeds-react-box";
 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,
   MenuContent,
+  MenuGroup,
   MenuItem,
   MenuToggleButton,
   SingleSelectMenu,
@@ -847,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 (
@@ -974,16 +1034,15 @@ export const PortaledComponentsInModal: Story = {
 };
 
 /**
- * Example using the useModalExternalTrigger hook for external triggers.
- *
- * ⚠️ NOT RECOMMENDED - This is a last resort pattern. Prefer using modalTrigger prop.
+ * 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).
  *
- * 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
+ * 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
  *
- * 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: () => {
@@ -994,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>
 
@@ -1037,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={
@@ -1082,14 +1146,15 @@ export const ExternalTriggerWithHook: Story = {
 };
 
 /**
- * Example using the ModalExternalTrigger component for external triggers.
- *
- * ⚠️ NOT RECOMMENDED - This is a last resort pattern. Prefer using modalTrigger prop.
+ * Alternative to useModalExternalTrigger when the trigger is specifically a Seeds Button.
  *
- * ModalExternalTrigger is a Button variant with built-in ARIA attributes.
- * Use it when you need an external trigger that is specifically a Button.
+ * 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.
  *
- * 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: () => {
@@ -1099,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
@@ -1153,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
@@ -1194,3 +1266,358 @@ export const ExternalTriggerComponent: Story = {
     );
   },
 };
+
+export const WithFormAndMenus: Story = {
+  render: () => {
+    const [selectedItem, setSelectedItem] =
+      useState<TypeSingleSelectMenuProps["selectedItem"]>(null);
+    const [name, setName] = useState("");
+    const [submitCount, setSubmitCount] = useState(0);
+
+    const handleSubmit = (e: React.FormEvent) => {
+      e.preventDefault();
+      setSubmitCount((c) => c + 1);
+    };
+
+    return (
+      <Modal
+        modalTrigger={
+          <Button appearance="primary">Open Modal with Form</Button>
+        }
+        aria-label="Form Auto-Submit Bug Reproduction"
+        closeButtonProps={{ "aria-label": "Close" }}
+      >
+        <ModalHeader
+          title="Assign User Role"
+          subtitle="Selecting a role should not submit the form"
+        />
+        <ModalBody>
+          <form onSubmit={handleSubmit}>
+            <Box p={400} display="flex" flexDirection="column" gap={400}>
+              <FormField
+                label="Name"
+                error={null}
+                helperText={null}
+                id="name-field"
+                qa={{}}
+                required={false}
+              >
+                {(props) => (
+                  <input
+                    {...props}
+                    type="text"
+                    placeholder="Enter a name"
+                    value={name}
+                    onChange={(e) => setName(e.target.value)}
+                    style={{
+                      padding: "8px 12px",
+                      borderRadius: "4px",
+                      border: "1px solid #ccc",
+                      width: "100%",
+                      boxSizing: "border-box",
+                      fontSize: "14px",
+                    }}
+                  />
+                )}
+              </FormField>
+
+              <FormField
+                label="Role"
+                error={null}
+                helperText={null}
+                id="role-field"
+                qa={{}}
+                required={false}
+              >
+                {() => (
+                  <SingleSelectMenu
+                    selectedItem={selectedItem}
+                    onSelectedItemChange={({ selectedItem: item }) =>
+                      setSelectedItem(item)
+                    }
+                    menuToggleElement={
+                      <MenuToggleButton>
+                        {selectedItem?.id ?? "Select a role..."}
+                      </MenuToggleButton>
+                    }
+                  >
+                    <MenuContent>
+                      <MenuItem id="admin">Admin</MenuItem>
+                      <MenuItem id="editor">Editor</MenuItem>
+                      <MenuItem id="viewer">Viewer</MenuItem>
+                    </MenuContent>
+                  </SingleSelectMenu>
+                )}
+              </FormField>
+
+              {submitCount > 0 && (
+                <Box
+                  p={400}
+                  bg="container.background.destructive"
+                  borderRadius="6px"
+                  border="1px solid"
+                  borderColor="container.border.destructive"
+                >
+                  <Text fontWeight="bold">
+                    Form submitted {submitCount} time(s)!
+                  </Text>
+                  <Text fontSize={200}>
+                    If you only clicked a menu item, this is a bug.
+                  </Text>
+                </Box>
+              )}
+            </Box>
+
+            <ModalFooter
+              cancelButton={<Button>Cancel</Button>}
+              primaryButton={
+                <Button type="submit" appearance="primary">
+                  Save
+                </Button>
+              }
+            />
+          </form>
+        </ModalBody>
+      </Modal>
+    );
+  },
+};
+
+export const WithPopout: Story = {
+  render: (args) => {
+    const [selectedItem, setSelectedItem] =
+      useState<TypeSingleSelectMenuProps["selectedItem"]>(null);
+
+    return (
+      <Modal
+        {...args}
+        closeButtonAriaLabel="Close Modal"
+        modalTrigger={<Button appearance="primary">Open Modal</Button>}
+      >
+        <ModalHeader
+          title="Popout Components"
+          subtitle="Various popout and menu components inside a modal"
+        />
+        <ModalBody>
+          <Box p={400} display="flex" flexDirection="column" gap={400}>
+            <Box>
+              <Text fontSize={200} fontWeight="semibold" mb={200}>
+                Popout V1
+              </Text>
+              <Popout
+                content={
+                  <Popout.Content>
+                    Look this is some popout content
+                  </Popout.Content>
+                }
+              >
+                <Button>Open Popout</Button>
+              </Popout>
+            </Box>
+            <Box>
+              <Text fontSize={200} fontWeight="semibold" mb={200}>
+                Popout V2
+              </Text>
+              <PopoutV2 content="Look this is some popout content">
+                <Button>Open Popout V2</Button>
+              </PopoutV2>
+            </Box>
+            <Box>
+              <Text fontSize={200} fontWeight="semibold" mb={200}>
+                Action Menu
+              </Text>
+              <ActionMenu
+                menuToggleElement={<MenuToggleButton>Actions</MenuToggleButton>}
+              >
+                <MenuContent>
+                  <MenuGroup id="actions">
+                    <MenuItem id="edit">Edit</MenuItem>
+                    <MenuItem id="duplicate">Duplicate</MenuItem>
+                    <MenuItem id="delete">Delete</MenuItem>
+                  </MenuGroup>
+                </MenuContent>
+              </ActionMenu>
+            </Box>
+            <Box>
+              <Text fontSize={200} fontWeight="semibold" mb={200}>
+                Single Select Menu
+              </Text>
+              <SingleSelectMenu
+                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>
+          </Box>
+        </ModalBody>
+        <ModalFooter
+          cancelButton={<Button>Cancel</Button>}
+          primaryButton={<Button appearance="primary">Confirm</Button>}
+        />
+      </Modal>
+    );
+  },
+};
+
+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>
+    );
+  },
+};