@instructure/ui-modal 8.23.1-snapshot.7 → 8.24.0

package/src/Modal/props.ts

@@ -30,6 +30,9 @@ import {
   Children as ChildrenPropTypes
 } from '@instructure/ui-prop-types'
 import { transitionTypePropType } from '@instructure/ui-motion'
+
+import { Dialog } from '@instructure/ui-dialog'
+
 import { ModalHeader } from './ModalHeader'
 import { ModalBody } from './ModalBody'
 import { ModalFooter } from './ModalFooter'
@@ -39,177 +42,201 @@ import type {
   PropValidators,
   ModalTheme,
   OtherHTMLAttributes,
-  LiveRegion
+  LiveRegion,
+  UIElement
 } from '@instructure/shared-types'
 import type { PortalNode } from '@instructure/ui-portal'
 import type { PositionMountNode } from '@instructure/ui-position'
 import type { TransitionType } from '@instructure/ui-motion'
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
 
-type ModalOwnProps = {
-  label: string
-  children: React.ReactNode // TODO: enforceOrder([ModalHeader, ModalBody, ModalFooter], [ModalHeader, ModalBody], [ModalBody, ModalFooter], [ModalBody])
-  as?: AsElementType
-  size?: 'auto' | 'small' | 'medium' | 'large' | 'fullscreen'
-  variant?: 'default' | 'inverse'
+type ModalPropsForPortal = {
+  /**
+   * Whether or not the `<Modal />` is open
+   */
   open?: boolean
-  defaultFocusElement?: React.ReactElement | ((...args: any[]) => any)
-  shouldReturnFocus?: boolean
-  shouldCloseOnDocumentClick?: boolean
-  onOpen?: (DOMNode: PortalNode) => void
-  onClose?: (...args: any[]) => any
-  onDismiss?: (...args: any[]) => any
-  contentRef?: (...args: any[]) => any
+
+  /**
+   * An element or a function returning an element to use as the mount node
+   * for the `<Modal />` (defaults to `document.body`)
+   */
   mountNode?: PositionMountNode
+
+  /**
+   * Insert the element at the 'top' of the mountNode or at the 'bottom'
+   */
   insertAt?: 'bottom' | 'top'
-  liveRegion?: LiveRegion
-  transition?: TransitionType
-  onEnter?: (...args: any[]) => any
-  onEntering?: (...args: any[]) => any
-  onEntered?: (...args: any[]) => any
-  onExit?: (...args: any[]) => any
-  onExiting?: (...args: any[]) => any
-  onExited?: (type?: TransitionType) => void
-  constrain?: 'window' | 'parent'
-  overflow?: 'scroll' | 'fit'
-}
 
-type PropKeys = keyof ModalOwnProps
+  /**
+   * Callback fired when `<Modal />` content has been mounted in the DOM
+   */
+  onOpen?: (DOMNode: PortalNode) => void
 
-type AllowedPropKeys = Readonly<Array<PropKeys>>
+  /**
+   * Callback fired when `<Modal />` has been unmounted from the DOM
+   */
+  onClose?: () => void
+}
 
-type ModalProps = ModalOwnProps &
-  WithStyleProps<ModalTheme, ModalStyle> &
-  OtherHTMLAttributes<ModalOwnProps>
+type ModalPropsForTransition = {
+  transition?: TransitionType
 
-type ModalStyle = ComponentStyle<'modal' | 'constrainContext'>
+  /**
+   * Callback fired before the <Modal /> transitions in
+   */
+  onEnter?: () => void
 
-const propTypes: PropValidators<PropKeys> = {
   /**
-   * An accessible label for the `<Modal />` content
+   * Callback fired as the <Modal /> begins to transition in
    */
-  label: PropTypes.string.isRequired,
+  onEntering?: () => void
 
   /**
-   * The children to be rendered within the `<Modal />`
+   * Callback fired after the <Modal /> finishes transitioning in
    */
-  children: ChildrenPropTypes.enforceOrder(
-    [ModalHeader, ModalBody, ModalFooter],
-    [ModalHeader, ModalBody],
-    [ModalBody, ModalFooter],
-    [ModalBody]
-  ),
+  onEntered?: (type?: TransitionType) => void
 
   /**
-   * The element to render the dialog as, `span` by default
+   * Callback fired right before the <Modal /> transitions out
    */
-  as: PropTypes.elementType,
+  onExit?: () => void
 
   /**
-   * The size of the `<Modal />` content
+   * Callback fired as the <Modal /> begins to transition out
    */
-  size: PropTypes.oneOf(['auto', 'small', 'medium', 'large', 'fullscreen']),
+  onExiting?: () => void
 
   /**
-   * Designates the background style of the `<Modal />`
+   * Callback fired after the <Modal /> finishes transitioning out
    */
-  variant: PropTypes.oneOf(['default', 'inverse']),
+  onExited?: (type?: TransitionType) => void
+}
 
+type ModalPropsForDialog = {
   /**
-   * Whether or not the `<Modal />` is open
+   * An accessible label for the `<Modal />` content
    */
-  open: PropTypes.bool,
+  label: string
 
   /**
-   * An element or a function returning an element to focus by default
+   * The element to render the dialog as, `span` by default
    */
-  defaultFocusElement: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  as?: AsElementType
 
   /**
    * Whether focus should be returned to the trigger when the `<Modal/>` is closed
    */
-  shouldReturnFocus: PropTypes.bool,
+  shouldReturnFocus?: boolean
 
   /**
    * Whether the `<Modal/>` should request close when the document is clicked
    */
-  shouldCloseOnDocumentClick: PropTypes.bool,
+  shouldCloseOnDocumentClick?: boolean
 
   /**
-   * Callback fired when `<Modal />` content has been mounted in the DOM
+   * Callback fired when the `<Modal />` is requesting to be closed
    */
-  onOpen: PropTypes.func,
+  onDismiss?: (
+    event: React.UIEvent | React.FocusEvent,
+    documentClick?: boolean
+  ) => void
 
   /**
-   * Callback fired when `<Modal />` has been unmounted from the DOM
+   * An element, function returning an element, or array of elements that will not be hidden from
+   * the screen reader when the `<Modal />` is open
    */
-  onClose: PropTypes.func,
+  liveRegion?: LiveRegion
 
   /**
-   * Callback fired when the `<Modal />` is requesting to be closed
+   * An element or a function returning an element to focus by default
    */
-  onDismiss: PropTypes.func,
+  defaultFocusElement?: UIElement
+}
 
+type ModalOwnProps = {
   /**
-   *
-   * A function that returns a reference to the content element
+   * The children to be rendered within the `<Modal />`. Children must be type of: `Modal.Header`, `Modal.Body`, `Modal.Footer`. The `Modal.Body` child is required, and they have to follow this order.
    */
-  contentRef: PropTypes.func,
+  children: React.ReactNode // TODO: enforceOrder([ModalHeader, ModalBody, ModalFooter], [ModalHeader, ModalBody], [ModalBody, ModalFooter], [ModalBody])
 
   /**
-   * An element or a function returning an element to use as the mount node
-   * for the `<Modal />` (defaults to `document.body`)
+   * The size of the `<Modal />` content
    */
-  mountNode: PropTypes.oneOfType([element, PropTypes.func]),
+  size?: 'auto' | 'small' | 'medium' | 'large' | 'fullscreen'
+
   /**
-   * Insert the element at the 'top' of the mountNode or at the 'bottom'
+   * Designates the background style of the `<Modal />`
    */
-  insertAt: PropTypes.oneOf(['bottom', 'top']),
+  variant?: 'default' | 'inverse'
 
   /**
-   * An element, function returning an element, or array of elements that will not be hidden from
-   * the screen reader when the `<Modal />` is open
+   *
+   * A function that returns a reference to the content element
+   */
+  contentRef?: (dialog: Dialog | null) => void
+
+  /**
+   * Constrain the Modal to the document window or its closest positioned parent
    */
+  constrain?: 'window' | 'parent'
+
+  /**
+   * Should ModalBody handle overflow with scrollbars, or fit its
+   * content within its own height?
+   */
+  overflow?: 'scroll' | 'fit'
+} & ModalPropsForPortal &
+  ModalPropsForTransition &
+  ModalPropsForDialog
+
+type PropKeys = keyof ModalOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ModalProps = ModalOwnProps &
+  WithStyleProps<ModalTheme, ModalStyle> &
+  OtherHTMLAttributes<ModalOwnProps>
+
+type ModalStyle = ComponentStyle<'modal' | 'constrainContext'>
+
+type ModalState = {
+  transitioning: boolean
+}
+
+const propTypes: PropValidators<PropKeys> = {
+  label: PropTypes.string.isRequired,
+  children: ChildrenPropTypes.enforceOrder(
+    [ModalHeader, ModalBody, ModalFooter],
+    [ModalHeader, ModalBody],
+    [ModalBody, ModalFooter],
+    [ModalBody]
+  ),
+  as: PropTypes.elementType,
+  size: PropTypes.oneOf(['auto', 'small', 'medium', 'large', 'fullscreen']),
+  variant: PropTypes.oneOf(['default', 'inverse']),
+  open: PropTypes.bool,
+  defaultFocusElement: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  shouldReturnFocus: PropTypes.bool,
+  shouldCloseOnDocumentClick: PropTypes.bool,
+  onOpen: PropTypes.func,
+  onClose: PropTypes.func,
+  onDismiss: PropTypes.func,
+  contentRef: PropTypes.func,
+  mountNode: PropTypes.oneOfType([element, PropTypes.func]),
+  insertAt: PropTypes.oneOf(['bottom', 'top']),
   liveRegion: PropTypes.oneOfType([
     PropTypes.arrayOf(PropTypes.element),
     PropTypes.element,
     PropTypes.func
   ]),
-
   transition: transitionTypePropType,
-
-  /**
-   * Callback fired before the <Modal /> transitions in
-   */
   onEnter: PropTypes.func,
-  /**
-   * Callback fired as the <Modal /> begins to transition in
-   */
   onEntering: PropTypes.func,
-  /**
-   * Callback fired after the <Modal /> finishes transitioning in
-   */
   onEntered: PropTypes.func,
-  /**
-   * Callback fired right before the <Modal /> transitions out
-   */
   onExit: PropTypes.func,
-  /**
-   * Callback fired as the <Modal /> begins to transition out
-   */
   onExiting: PropTypes.func,
-  /**
-   * Callback fired after the <Modal /> finishes transitioning out
-   */
   onExited: PropTypes.func,
-  /**
-   * Constrain the Modal to the document window or its closest positioned parent
-   */
   constrain: PropTypes.oneOf(['window', 'parent']),
-  /**
-   * Should ModalBody handle overflow with scrollbars, or fit its
-   * content within its own height?
-   */
   overflow: PropTypes.oneOf(['scroll', 'fit'])
 }
 
@@ -241,5 +268,12 @@ const allowedProps: AllowedPropKeys = [
   'overflow'
 ]
 
-export type { ModalProps, ModalStyle }
+export type {
+  ModalProps,
+  ModalStyle,
+  ModalState,
+  ModalPropsForPortal,
+  ModalPropsForTransition,
+  ModalPropsForDialog
+}
 export { propTypes, allowedProps }