@sproutsocial/seeds-react-modal 1.1.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sproutsocial/seeds-react-modal",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Seeds React Modal",
   "author": "Sprout Social, Inc.",
   "license": "MIT",
@@ -36,12 +36,13 @@
   },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.14",
-    "@sproutsocial/seeds-react-box": "^1.1.4",
-    "@sproutsocial/seeds-react-button": "^1.2.3",
-    "@sproutsocial/seeds-react-icon": "^1.1.4",
+    "@sproutsocial/seeds-react-box": "^1.1.5",
+    "@sproutsocial/seeds-react-button": "^1.3.1",
+    "@sproutsocial/seeds-react-icon": "^1.1.5",
     "@sproutsocial/seeds-react-system-props": "^3.0.1",
     "@sproutsocial/seeds-react-text": "^1.3.2",
-    "@sproutsocial/seeds-react-theme": "^3.1.0",
+    "@sproutsocial/seeds-react-theme": "^3.1.1",
+    "motion": "^12.6.3",
     "react-dnd": "^16.0.1",
     "react-dnd-html5-backend": "^16.0.1",
     "react-modal": "^3.16.1",
@@ -49,8 +50,8 @@
   },
   "devDependencies": {
     "@sproutsocial/eslint-config-seeds": "*",
-    "@sproutsocial/seeds-react-form-field": "^1.0.3",
-    "@sproutsocial/seeds-react-input": "^1.4.5",
+    "@sproutsocial/seeds-react-form-field": "^1.0.4",
+    "@sproutsocial/seeds-react-input": "^1.4.7",
     "@sproutsocial/seeds-react-testing-library": "*",
     "@sproutsocial/seeds-testing": "*",
     "@sproutsocial/seeds-tsconfig": "*",

package/src/index.ts

@@ -12,27 +12,26 @@ export type {
   TypeModalCloseButtonProps,
 } from "./v1";
 
-// V2 Modal exports
+// V2 Modal exports (renamed to just Modal)
 export {
   Modal as ModalV2,
-  ModalTrigger,
   ModalDescription,
   ModalHeader,
   ModalFooter,
-  ModalContent,
-  ModalCloseButton,
-  ModalClose,
+  ModalBody,
+  ModalCloseWrapper,
   ModalRail,
   ModalAction,
+  ModalCustomHeader,
+  ModalCustomFooter,
 } from "./v2";
 export type {
-  TypeModalV2Props,
-  TypeModalV2TriggerProps,
-  TypeModalV2CloseButtonProps,
-  TypeModalV2HeaderProps,
-  TypeModalV2FooterProps,
-  TypeModalV2ContentProps,
-  TypeModalV2DescriptionProps,
+  TypeModalProps as TypeModalV2Props,
+  TypeModalHeaderProps as TypeModalV2HeaderProps,
+  TypeModalFooterProps as TypeModalV2FooterProps,
+  TypeModalBodyProps as TypeModalV2BodyProps,
+  TypeModalDescriptionProps as TypeModalV2DescriptionProps,
   TypeModalRailProps,
   TypeModalActionProps,
+  ModalCloseWrapperProps,
 } from "./v2";

package/src/shared/constants.ts

@@ -1,6 +1,6 @@
 // Shared constants for both Modal versions
 
-// Default z-index values
+// Default z-index values (v1 only - v2 relies on portal stacking order)
 export const DEFAULT_MODAL_Z_INDEX = 6;
 export const DEFAULT_OVERLAY_Z_INDEX_OFFSET = -1;
 
@@ -10,6 +10,8 @@ export const DEFAULT_MODAL_BG = "container.background.base";
 export const DEFAULT_CLOSE_BUTTON_LABEL = "Close dialog";
 
 // Max space allowed between the modal and the edge of the browser
+// Note: 64px doesn't have a direct space token match (space[500] = 32px, space[600] = 40px)
+// Keeping as hardcoded value for now as it's a specific layout constraint
 export const BODY_PADDING = "64px";
 
 // Size presets for simplified API
@@ -20,9 +22,11 @@ export const MODAL_SIZE_PRESETS = {
   full: "90vw",
 } as const;
 
-// Priority level z-index mappings
-export const MODAL_PRIORITY_Z_INDEX = {
-  low: 100,
-  medium: 1000,
-  high: 2000,
-} as const;
+// Mobile breakpoint for bottom sheet layout
+export const MOBILE_BREAKPOINT = "780px";
+
+// Rail button constants
+export const RAIL_BUTTON_SIZE = 44; // px
+export const RAIL_OFFSET = 12; // px from card edge
+export const RAIL_GAP = 12; // px between buttons
+export const RAIL_EXTRA_SPACE = RAIL_BUTTON_SIZE + RAIL_OFFSET; // 56px

package/src/v2/Modal.tsx

@@ -0,0 +1,169 @@
+import * as React from "react";
+import * as Dialog from "@radix-ui/react-dialog";
+import { AnimatePresence } from "motion/react";
+import {
+  StyledOverlay,
+  StyledMotionOverlay,
+  DraggableModalContent,
+  StaticModalContent,
+  ModalHeader,
+  ModalDescription,
+  ModalRail,
+  ModalAction,
+} from "./components";
+import type { TypeModalProps } from "./ModalTypes";
+import { getOverlayVariants, useIsMobile } from "./MotionConfig";
+
+/**
+ * Accessible modal dialog component built on Radix UI Dialog primitives.
+ *
+ * This component provides a flexible modal implementation with comprehensive accessibility
+ * features, keyboard navigation, and focus management built in.
+ *
+ * Key capabilities:
+ * - Automatic ARIA attributes and focus trapping
+ * - ESC key and outside click to close
+ * - Simplified API with title/subtitle props for common use cases
+ * - Controlled and uncontrolled state modes
+ * - Optional draggable behavior for side-by-side interaction
+ * - Floating action rail for quick actions like close, expand, etc.
+ * - Responsive bottom sheet layout on mobile
+ *
+ * @example
+ * // Simple uncontrolled modal
+ * <Modal
+ *   title="Delete Item"
+ *   subtitle="This action cannot be undone"
+ *   modalTrigger={<Button>Delete</Button>}
+ * >
+ *   <ModalBody>Are you sure you want to delete this item?</ModalBody>
+ *   <ModalFooter
+ *     cancelButton={<Button>Cancel</Button>}
+ *     primaryButton={<Button appearance="destructive">Delete</Button>}
+ *   />
+ * </Modal>
+ */
+const Modal = (props: TypeModalProps) => {
+  const {
+    children,
+    modalTrigger,
+    draggable = false,
+    open,
+    defaultOpen,
+    onOpenChange,
+    "aria-label": label,
+    title,
+    subtitle,
+    description,
+    data = {},
+    showOverlay = true,
+    actions,
+    closeButtonAriaLabel = "Close",
+    ...rest
+  } = props;
+
+  // Track open state for AnimatePresence
+  // This state is synced via onOpenChange regardless of controlled/uncontrolled mode
+  const [isOpen, setIsOpen] = React.useState(defaultOpen ?? false);
+
+  const handleOpenChange = React.useCallback(
+    (newOpen: boolean) => {
+      // Always sync state for AnimatePresence
+      setIsOpen(newOpen);
+      // Call user's callback
+      onOpenChange?.(newOpen);
+    },
+    [onOpenChange]
+  );
+
+  // Create data attributes object
+  const dataAttributes = React.useMemo(() => {
+    const attrs: Record<string, string> = {};
+    Object.entries(data).forEach(([key, value]) => {
+      attrs[`data-${key}`] = String(value);
+    });
+    attrs["data-qa-modal"] = "";
+    // Only add open attribute if in controlled mode
+    if (open !== undefined) {
+      attrs["data-qa-modal-open"] = String(open);
+    }
+    return attrs;
+  }, [data, open]);
+
+  // Determine if we should auto-render the header from provided props
+  const shouldRenderHeader = Boolean(title || subtitle);
+
+  // Get mobile state and appropriate overlay variants
+  const isMobile = useIsMobile();
+  const overlayVariants = getOverlayVariants(isMobile);
+
+  // Choose the appropriate content component based on draggable prop
+  const ModalContentComponent = draggable
+    ? DraggableModalContent
+    : StaticModalContent;
+
+  return (
+    <Dialog.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={handleOpenChange}
+      modal={!draggable}
+    >
+      {/* Render trigger button if provided */}
+      {modalTrigger && <Dialog.Trigger asChild>{modalTrigger}</Dialog.Trigger>}
+
+      <Dialog.Portal forceMount>
+        <AnimatePresence mode="wait">
+          {(open ?? isOpen) && (
+            <>
+              {showOverlay && (
+                <Dialog.Overlay asChild>
+                  <StyledMotionOverlay
+                    variants={overlayVariants}
+                    initial="initial"
+                    animate="animate"
+                    exit="exit"
+                  >
+                    <StyledOverlay allowInteraction={draggable} />
+                  </StyledMotionOverlay>
+                </Dialog.Overlay>
+              )}
+              <ModalContentComponent
+                label={label}
+                dataAttributes={dataAttributes}
+                draggable={draggable}
+                rest={rest}
+              >
+                {/* Floating actions rail - always show a close by default */}
+                <ModalRail>
+                  <ModalAction
+                    actionType="close"
+                    aria-label={closeButtonAriaLabel}
+                    iconName="x-outline"
+                  />
+                  {actions?.map((action, idx) => (
+                    <ModalAction key={idx} {...action} />
+                  ))}
+                </ModalRail>
+                {/* Auto-render header when title or subtitle is provided */}
+                {shouldRenderHeader && (
+                  <ModalHeader title={title} subtitle={subtitle} />
+                )}
+
+                {/* Auto-render description when provided */}
+                {description && (
+                  <ModalDescription>{description}</ModalDescription>
+                )}
+
+                {/* Main content */}
+                {children}
+              </ModalContentComponent>
+            </>
+          )}
+        </AnimatePresence>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+};
+
+export default Modal;

package/src/v2/ModalTypes.ts

@@ -0,0 +1,343 @@
+import * as React from "react";
+import * as Dialog from "@radix-ui/react-dialog";
+import type {
+  TypeBoxProps,
+  TypeContainerProps,
+} from "@sproutsocial/seeds-react-box";
+import type { TypeIconName } from "@sproutsocial/seeds-react-icon";
+
+/**
+ * Props for ModalHeader component.
+ *
+ * Renders the modal's header with title and optional subtitle. Supports draggable functionality
+ * when the modal has draggable enabled.
+ *
+ * Note: This component only supports slots (title/subtitle props). For custom headers,
+ * use ModalCustomHeader instead.
+ */
+export interface TypeModalHeaderProps extends TypeBoxProps {
+  /** Modal title text displayed as a headline */
+  title?: string;
+  /**
+   * Modal subtitle text.
+   *
+   * This is automatically wrapped in `Dialog.Description` from Radix UI,
+   * which provides accessible description text for screen readers. The subtitle
+   * provides additional context about the modal and is announced alongside
+   * the title when the dialog opens. Radix UI automatically connects this to
+   * the dialog via ARIA attributes (typically `aria-describedby` on the dialog root).
+   */
+  subtitle?: string;
+
+  /** Additional props for the Dialog.Title when title is provided */
+  titleProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof Dialog.Title>,
+    "asChild" | "children"
+  >;
+
+  /**
+   * Additional props for the Dialog.Description when subtitle is provided.
+   *
+   * Dialog.Description provides accessible description text for the modal that
+   * screen readers announce when the dialog opens. It complements Dialog.Title
+   * by providing additional context about the modal. Radix UI automatically
+   * connects this to the dialog via ARIA attributes.
+   */
+  subtitleProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof Dialog.Description>,
+    "asChild" | "children"
+  >;
+}
+
+/**
+ * Props for ModalFooter component.
+ *
+ * Provides automatic button wrapping and layout management. At least one action
+ * (cancelButton, primaryButton, or leftAction) must be provided.
+ *
+ * Note: This component only supports slots (button props). For custom footers,
+ * use ModalCustomFooter instead.
+ *
+ * @example
+ * // ✅ Valid - has primary button
+ * <ModalFooter primaryButton={<Button>Save</Button>} />
+ *
+ * @example
+ * // ✅ Valid - has cancel and primary
+ * <ModalFooter
+ *   cancelButton={<Button>Cancel</Button>}
+ *   primaryButton={<Button>Save</Button>}
+ * />
+ *
+ * @example
+ * // ✅ Valid - left action only
+ * <ModalFooter leftAction={<Button>Delete</Button>} />
+ *
+ * @example
+ * // ❌ TypeScript Error - no actions provided
+ * <ModalFooter />
+ */
+export type TypeModalFooterProps = TypeBoxProps &
+  (
+    | {
+        /** Primary action button - automatically wrapped in ModalCloseWrapper to close the modal */
+        primaryButton: React.ReactNode;
+        /** Cancel/secondary button - automatically wrapped in ModalCloseWrapper to close the modal */
+        cancelButton?: React.ReactNode;
+        /** Optional action on the far left (e.g., Delete button) - NOT automatically wrapped */
+        leftAction?: React.ReactNode;
+      }
+    | {
+        /** Primary action button - automatically wrapped in ModalCloseWrapper to close the modal */
+        primaryButton?: React.ReactNode;
+        /** Cancel/secondary button - automatically wrapped in ModalCloseWrapper to close the modal */
+        cancelButton: React.ReactNode;
+        /** Optional action on the far left (e.g., Delete button) - NOT automatically wrapped */
+        leftAction?: React.ReactNode;
+      }
+    | {
+        /** Primary action button - automatically wrapped in ModalCloseWrapper to close the modal */
+        primaryButton?: React.ReactNode;
+        /** Cancel/secondary button - automatically wrapped in ModalCloseWrapper to close the modal */
+        cancelButton?: React.ReactNode;
+        /** Optional action on the far left (e.g., Delete button) - NOT automatically wrapped */
+        leftAction: React.ReactNode;
+      }
+  );
+
+/**
+ * Props for ModalBody component.
+ *
+ * Renders the scrollable main content area of the modal between the header and footer.
+ */
+export interface TypeModalBodyProps extends TypeBoxProps {
+  /** The main content of the modal body */
+  children?: React.ReactNode;
+}
+
+/**
+ * Props for ModalDescription component.
+ *
+ * Wraps content with Radix UI's Dialog.Description for accessible modal descriptions
+ * that are announced by screen readers.
+ */
+export interface TypeModalDescriptionProps extends TypeBoxProps {
+  /** The description text content */
+  children: React.ReactNode;
+  /** Additional props for the Dialog.Description */
+  descriptionProps?: Omit<
+    React.ComponentPropsWithoutRef<typeof Dialog.Description>,
+    "asChild" | "children"
+  >;
+}
+
+/** Common props shared by all modal variants */
+type TypeModalCommonProps = TypeContainerProps &
+  Omit<React.ComponentPropsWithoutRef<"div">, keyof TypeContainerProps> & {
+    /** Controls whether the modal is open (controlled mode) */
+    open?: boolean;
+
+    /** Default open state for uncontrolled mode */
+    defaultOpen?: boolean;
+
+    /** body content of the modal */
+    children: React.ReactNode;
+
+    /** Callback when open state changes */
+    onOpenChange?: (open: boolean) => void;
+
+    /** The element that will trigger the modal when clicked.
+     *  Can be any React element like a button, link, or custom component. */
+    modalTrigger?: React.ReactElement<any>;
+
+    /** Simplified API: Modal description (automatically wrapped in Dialog.Description) */
+    description?: string;
+
+    /**
+     * Custom attributes to be added to the modals container
+     * Each key will be prepended with "data-" when rendered in the DOM
+     */
+    data?: Record<string, string | boolean | number>;
+
+    /** Optional quick actions to render on a modal side rail */
+    actions?: TypeModalActionProps[];
+
+    /** Accessible label for the close button in the rail (defaults to "Close") */
+    closeButtonAriaLabel?: string;
+  };
+
+/**
+ * Base props with draggable and showOverlay relationship enforced.
+ *
+ * When draggable is true, showOverlay must be false or undefined because
+ * the overlay would block interaction with content behind the modal,
+ * defeating the purpose of being able to drag the modal aside.
+ */
+type TypeModalBaseProps =
+  | (TypeModalCommonProps & {
+      /** Enable draggable functionality */
+      draggable: true;
+      /**
+       * Whether to show the background overlay.
+       * Must be false when draggable is true to allow interaction with background content.
+       */
+      showOverlay?: false;
+    })
+  | (TypeModalCommonProps & {
+      /** Enable draggable functionality */
+      draggable?: false;
+      /** Whether to show the background overlay (defaults to true) */
+      showOverlay?: boolean;
+    });
+
+/**
+ * Modal props with title provided.
+ * aria-label is optional since Dialog.Title can serve as the accessible name.
+ */
+export type TypeModalPropsWithTitle = TypeModalBaseProps & {
+  /** Simplified API: Modal title (creates ModalHeader automatically) */
+  title: string;
+  /**
+   * Simplified API: Modal subtitle (creates ModalHeader automatically).
+   *
+   * This is automatically wrapped in `Dialog.Description` from Radix UI,
+   * which provides accessible description text for screen readers. The subtitle
+   * provides additional context about the modal and is announced alongside
+   * the title when the dialog opens.
+   */
+  subtitle?: string;
+  /** Accessible label for the modal dialog (optional when title or subtitle is provided) */
+  "aria-label"?: string;
+};
+
+/**
+ * Modal props with subtitle provided but no title.
+ * aria-label is optional since Dialog.Description can help identify the modal.
+ */
+export type TypeModalPropsWithSubtitleOnly = TypeModalBaseProps & {
+  /** Simplified API: Modal title (creates ModalHeader automatically) */
+  title?: never;
+  /**
+   * Simplified API: Modal subtitle (creates ModalHeader automatically).
+   *
+   * This is automatically wrapped in `Dialog.Description` from Radix UI,
+   * which provides accessible description text for screen readers. The subtitle
+   * provides additional context about the modal and is announced alongside
+   * the title when the dialog opens.
+   */
+  subtitle: string;
+  /** Accessible label for the modal dialog (optional when title or subtitle is provided) */
+  "aria-label"?: string;
+};
+
+/**
+ * Modal props without title or subtitle.
+ *
+ * **IMPORTANT**: When no header (title or subtitle) is provided,
+ * `aria-label` is REQUIRED for accessibility compliance.
+ *
+ * Without a visible header, screen readers need `aria-label` to identify
+ * what the modal dialog is about.
+ *
+ * @example
+ * // ✅ Valid - provides aria-label when no header
+ * <Modal aria-label="Delete confirmation dialog">
+ *   <p>Are you sure you want to delete this item?</p>
+ * </Modal>
+ *
+ * @example
+ * // ❌ Invalid - missing required aria-label
+ * <Modal>
+ *   <p>Are you sure you want to delete this item?</p>
+ * </Modal>
+ */
+export type TypeModalPropsWithoutHeader = TypeModalBaseProps & {
+  /** Simplified API: Modal title (creates ModalHeader automatically) - not allowed when no header */
+  title?: never;
+  /** Simplified API: Modal subtitle (creates ModalHeader automatically) - not allowed when no header */
+  subtitle?: never;
+  /**
+   * **REQUIRED: aria-label must be provided when no title or subtitle is given**
+   *
+   * Accessible label for the modal dialog. This is required for accessibility
+   * when the modal has no visible header. Screen readers use this to announce
+   * what the modal is about.
+   *
+   * **Error**: If you see a TypeScript error saying this property is missing,
+   * it means you need to either:
+   * 1. Provide `aria-label` (required when no header), OR
+   * 2. Provide `title` or `subtitle` (which makes aria-label optional)
+   *
+   * If you have a title or subtitle, this prop is optional.
+   */
+  "aria-label": string;
+};
+
+/**
+ * Modal component props with discriminated union based on header presence.
+ *
+ * **Accessibility Requirements:**
+ * - ✅ **With header** (title or subtitle provided): `aria-label` is optional
+ * - ❌ **Without header** (no title, no subtitle): `aria-label` is **REQUIRED**
+ *
+ * TypeScript will error if you forget to provide `aria-label` when no header is present.
+ * This ensures accessibility compliance and better screen reader support.
+ *
+ * @example
+ * // ✅ Valid - has title, aria-label optional
+ * <Modal title="Delete Item" />
+ *
+ * @example
+ * // ✅ Valid - has subtitle only, aria-label optional
+ * <Modal subtitle="Confirmation" />
+ *
+ * @example
+ * // ✅ Valid - no header, aria-label provided
+ * <Modal aria-label="Delete confirmation dialog" />
+ *
+ * @example
+ * // ❌ TypeScript Error - no header and missing required aria-label
+ * <Modal /> // Error: Property 'aria-label' is missing
+ */
+export type TypeModalProps =
+  | TypeModalPropsWithTitle
+  | TypeModalPropsWithSubtitleOnly
+  | TypeModalPropsWithoutHeader;
+
+/**
+ * Props for ModalRail component.
+ *
+ * Container for floating action buttons displayed alongside the modal.
+ */
+export type TypeModalRailProps = {
+  /** ModalAction components to display in the rail */
+  children?: React.ReactNode;
+};
+
+/**
+ * Base props for modal action buttons.
+ *
+ * Extends standard button HTML attributes with modal-specific properties.
+ */
+type ModalActionBase = Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "onClick"
+> & {
+  /** Icon name from the Seeds icon set */
+  iconName?: TypeIconName;
+  /** Optional click handler; ignored for type "close" */
+  onClick?: () => void;
+  /** Accessible name for the action button */
+  "aria-label": string;
+};
+
+/**
+ * Props for ModalAction component.
+ *
+ * Discriminated union supporting two action types:
+ * - "close": Automatically closes the modal when clicked (uses Dialog.Close)
+ * - "button": Custom action with user-defined onClick handler
+ */
+export type TypeModalActionProps =
+  | (ModalActionBase & { actionType: "close" }) // uses Dialog.Close
+  | (ModalActionBase & { actionType?: "button" }); // regular button action