@instructure/ui-popover 8.12.1-snapshot.51 → 8.13.0

package/src/Popover/props.ts

@@ -33,270 +33,300 @@ import type { Shadow, Stacking } from '@instructure/emotion'
 import type {
   PlacementPropValues,
   PositionConstraint,
-  PositionMountNode
+  PositionMountNode,
+  PositionObject
 } from '@instructure/ui-position'
 import type { BidirectionalProps } from '@instructure/ui-i18n'
-import type { PropValidators, LiveRegion } from '@instructure/shared-types'
-
-// Copied list from "PositionPropTypes.placement" so that it appears as options in the properties table.
-// TODO: try to use "PositionPropTypes.placement" again once Popover is fully typed and uses @tsProps
-const placementPropValues = [
-  'top',
-  'bottom',
-  'start',
-  'end',
-  'top start',
-  'top center',
-  'top end',
-  'top stretch',
-  'bottom start',
-  'bottom center',
-  'bottom end',
-  'bottom stretch',
-  'start top',
-  'start center',
-  'start bottom',
-  'start stretch',
-  'end top',
-  'end center',
-  'end bottom',
-  'end stretch',
-  'center start',
-  'center end',
-  'offscreen'
-]
+import type {
+  PropValidators,
+  LiveRegion,
+  UIElement
+} from '@instructure/shared-types'
 
 type PopoverOwnProps = {
-  isShowingContent?: boolean
-  defaultIsShowingContent?: boolean
-  on?: ('click' | 'hover' | 'focus') | ('click' | 'hover' | 'focus')[]
-  withArrow?: boolean
-  color?: 'primary' | 'primary-inverse'
-  shadow?: Shadow
-  stacking?: Stacking
-  contentRef?: (...args: any[]) => any
-  defaultFocusElement?: React.ReactElement | ((...args: any[]) => any)
-  screenReaderLabel?: string
-  offsetX?: string | number
-  offsetY?: string | number
-  placement: PlacementPropValues
-  constrain?: PositionConstraint
-  mountNode?: PositionMountNode
-  positionTarget?: PositionMountNode
-  insertAt?: 'bottom' | 'top'
-  liveRegion?: LiveRegion
-  id?: string
-  shouldAlignArrow?: boolean
-  shouldTrackPosition?: boolean
-  shouldRenderOffscreen?: boolean
-  shouldContainFocus?: boolean
-  shouldReturnFocus?: boolean
-  shouldCloseOnDocumentClick?: boolean
-  shouldCloseOnEscape?: boolean
-  shouldFocusContentOnTriggerBlur?: boolean
-  onShowContent?: (...args: any[]) => any
-  onHideContent?: (...args: any[]) => any
-  onPositioned?: (...args: any[]) => any
-  onPositionChanged?: (...args: any[]) => any
-  onClick?: (...args: any[]) => any
-  onFocus?: (...args: any[]) => any
-  onBlur?: (...args: any[]) => any
-  onKeyDown?: (...args: any[]) => any
-  onKeyUp?: (...args: any[]) => any
-  onMouseOver?: (...args: any[]) => any
-  onMouseOut?: (...args: any[]) => any
-  renderTrigger?: React.ReactNode | ((...args: any[]) => any)
-  children?: React.ReactNode | ((...args: any[]) => React.ReactNode)
-  elementRef?: (element: Element | null) => void
-}
-
-type PopoverProps = PopoverOwnProps & BidirectionalProps
-
-type PropKeys = keyof PopoverOwnProps
-
-type AllowedPropKeys = Readonly<Array<PropKeys>>
-
-const propTypes: PropValidators<PropKeys> = {
   /**
    * Whether or not the `<Popover />` content is shown
    */
-  isShowingContent: PropTypes.bool,
+  isShowingContent?: boolean
+
   /**
    * Whether or not to show the content by default, when uncontrolled
    */
-  defaultIsShowingContent: PropTypes.bool,
+  defaultIsShowingContent?: boolean
+
   /**
    * The action that causes the content to display (`click`, `hover`, `focus`)
    */
-  on: PropTypes.oneOfType([
-    PropTypes.oneOf(['click', 'hover', 'focus']),
-    PropTypes.arrayOf(PropTypes.oneOf(['click', 'hover', 'focus']))
-  ]),
+  on?: ('click' | 'hover' | 'focus') | ('click' | 'hover' | 'focus')[]
+
   /**
    * Whether or not an arrow pointing to the trigger should be rendered
    */
-  withArrow: PropTypes.bool,
+  withArrow?: boolean
+
   /**
    * Color variant of the popover content
    */
-  color: PropTypes.oneOf(['primary', 'primary-inverse']),
-  /**
-   * The placement of the content in relation to the trigger
-   */
-  placement: PropTypes.oneOf(placementPropValues),
+  color?: 'primary' | 'primary-inverse'
+
   /**
    * Controls the shadow depth for the `<Popover />`
    */
-  shadow: ThemeablePropTypes.shadow,
+  shadow?: Shadow
+
   /**
    * Controls the z-index depth for the `<Popover />` content
    */
-  stacking: ThemeablePropTypes.stacking,
+  stacking?: Stacking
+
   /**
    * A function that returns a reference to the content element
    */
-  contentRef: PropTypes.func,
+  contentRef?: (contentElement: Element | null) => void
+
   /**
    * An element or a function returning an element to focus by default
    */
-  defaultFocusElement: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  defaultFocusElement?: UIElement
+
+  /**
+   * An element, function returning an element, or array of elements that will
+   * not be hidden from the screen reader when the `<Popover />` is open
+   */
+  liveRegion?: LiveRegion
+
   /**
    * An accessible label for the `<Popover />` content
    */
-  screenReaderLabel: PropTypes.string,
+  screenReaderLabel?: string
+
   /**
    * The horizontal offset for the positioned content
    */
-  offsetX: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+  offsetX?: string | number
+
   /**
    * The vertical offset for the positioned content
    */
-  offsetY: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+  offsetY?: string | number
+
+  // TODO: remove list when types can be read from other packages
+  /**
+   * The placement of the content in relation to the trigger
+   *
+   * One of: 'top', 'bottom', 'start', 'end', 'top start', 'top center',
+   * 'top end', 'top stretch', 'bottom start', 'bottom center', 'bottom end',
+   * 'bottom stretch', 'start top', 'start center', 'start bottom',
+   * 'start stretch', 'end top', 'end center', 'end bottom', 'end stretch',
+   * 'center start', 'center end', 'offscreen'
+   */
+  placement?: PlacementPropValues
+
   /**
    * The parent in which to constrain the popover.
+   *
    * One of: 'window', 'scroll-parent', 'parent', 'none', an element,
    * or a function returning an element
    */
-  constrain: PositionPropTypes.constrain,
-  /**
-   * Target element for positioning the Popover (if it differs from the trigger)
-   */
-  positionTarget: PropTypes.oneOfType([element, PropTypes.func]),
+  constrain?: PositionConstraint
+
   /**
    * An element or a function returning an element to use as the mount node
    * for the `<Popover />` (defaults to `document.body`)
    */
-  mountNode: PositionPropTypes.mountNode,
+  mountNode?: PositionMountNode
+
   /**
-   * Insert the element at the 'top' of the mountNode or at the 'bottom'
+   * Target element for positioning the Popover (if it differs from the trigger)
    */
-  insertAt: PropTypes.oneOf(['bottom', 'top']),
+  positionTarget?: PositionMountNode
+
   /**
-   * An element, function returning an element, or array of elements that will
-   * not be hidden from the screen reader when the `<Popover />` is open
+   * Insert the element at the 'top' of the mountNode or at the 'bottom'
    */
-  liveRegion: PropTypes.oneOfType([
-    PropTypes.arrayOf(PropTypes.element),
-    PropTypes.element,
-    PropTypes.func
-  ]),
+  insertAt?: 'bottom' | 'top'
+
   /**
    * An id is generated if not supplied.
    */
-  id: PropTypes.string,
+  id?: string
+
   /**
    * Whether or not the content should offset to align by its arrow
    */
-  shouldAlignArrow: PropTypes.bool,
+  shouldAlignArrow?: boolean
+
   /**
    * Whether or not position should be tracked or just set on initial render
    */
-  shouldTrackPosition: PropTypes.bool,
+  shouldTrackPosition?: boolean
+
   /**
    * Should the `<Popover />` render offscreen when visually hidden
    */
-  shouldRenderOffscreen: PropTypes.bool,
+  shouldRenderOffscreen?: boolean
+
   /**
    * Whether focus should contained within the `<Popover/>` when it is open
    */
-  shouldContainFocus: PropTypes.bool,
+  shouldContainFocus?: boolean
+
   /**
    * Whether focus should be returned to the trigger when the `<Popover/>` is closed
    */
-  shouldReturnFocus: PropTypes.bool,
+  shouldReturnFocus?: boolean
+
   /**
    * Should the `<Popover />` hide when clicks occur outside the content
    */
-  shouldCloseOnDocumentClick: PropTypes.bool,
+  shouldCloseOnDocumentClick?: boolean
+
   /**
    * Should the `<Popover />` hide when the escape key is pressed
    */
-  shouldCloseOnEscape: PropTypes.bool,
+  shouldCloseOnEscape?: boolean
+
   /**
    * Should the content become focused when the trigger is blurred
    */
-  shouldFocusContentOnTriggerBlur: PropTypes.bool,
+  shouldFocusContentOnTriggerBlur?: boolean
+
   /**
    * Callback fired when content is shown. When controlled, this callback is
    * fired when the Popover expects to be shown
    */
-  onShowContent: PropTypes.func,
+  onShowContent?: (event: Event) => void
+
   /**
    * Callback fired when content is hidden. When controlled, this callback is
    * fired when the Popover expects to be hidden
    */
-  onHideContent: PropTypes.func,
+  onHideContent?: (event: Event, args: { documentClick: boolean }) => void
+
   /**
    * Callback fired when content has been is initially positioned.
    * If `shouldRenderOffscreen` is true, it will only fire once, the first
    * time the content is shown
    */
-  onPositioned: PropTypes.func,
+  onPositioned?: (position: PositionObject) => void
+
   /**
    * Callback fired when the position changes
    */
-  onPositionChanged: PropTypes.func,
+  onPositionChanged?: (position: PositionObject) => void
+
   /**
    * Callback fired when component is clicked
    */
-  onClick: PropTypes.func,
+  onClick?: (event: Event) => void
+
   /**
    * Callback fired when trigger is focused
    */
-  onFocus: PropTypes.func,
+  onFocus?: (event: Event) => void
+
   /**
    * Callback fired when component is blurred
    */
-  onBlur: PropTypes.func,
+  onBlur?: (event: Event) => void
+
   /**
    * Callback fired on keydown
    */
-  onKeyDown: PropTypes.func,
+  onKeyDown?: (event: Event) => void
+
   /**
    * Callback fired on keyup
    */
-  onKeyUp: PropTypes.func,
-  /**
+  onKeyUp?: (event: Event) => void
+
   /**
    * Callback fired when mouse is over trigger
    */
-  onMouseOver: PropTypes.func,
+  onMouseOver?: (event: Event) => void
+
   /**
    * Callback fired when mouse leaves trigger
    */
-  onMouseOut: PropTypes.func,
+  onMouseOut?: (event: Event) => void
+
   /**
    * The element that triggers the popover
    */
-  renderTrigger: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  renderTrigger?: React.ReactNode | (() => React.ReactNode)
+
   /**
    * The content to be shown by the popover
    */
-  children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  children?: React.ReactNode | (() => React.ReactNode)
 
   /**
    * Provides a reference to the underlying HTML root element
    */
+  elementRef?: (element: Element | null) => void
+}
+
+type PopoverProps = PopoverOwnProps & BidirectionalProps
+
+type PopoverState = {
+  placement: PopoverOwnProps['placement']
+  offsetX: PopoverOwnProps['offsetX']
+  offsetY: PopoverOwnProps['offsetY']
+  isShowingContent?: boolean
+}
+
+type PropKeys = keyof PopoverOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+const propTypes: PropValidators<PropKeys> = {
+  isShowingContent: PropTypes.bool,
+  defaultIsShowingContent: PropTypes.bool,
+  on: PropTypes.oneOfType([
+    PropTypes.oneOf(['click', 'hover', 'focus']),
+    PropTypes.arrayOf(PropTypes.oneOf(['click', 'hover', 'focus']))
+  ]),
+  withArrow: PropTypes.bool,
+  color: PropTypes.oneOf(['primary', 'primary-inverse']),
+  placement: PositionPropTypes.placement,
+  shadow: ThemeablePropTypes.shadow,
+  stacking: ThemeablePropTypes.stacking,
+  contentRef: PropTypes.func,
+  defaultFocusElement: PropTypes.oneOfType([PropTypes.element, PropTypes.func]),
+  screenReaderLabel: PropTypes.string,
+  offsetX: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+  offsetY: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+  constrain: PositionPropTypes.constrain,
+  positionTarget: PropTypes.oneOfType([element, PropTypes.func]),
+  mountNode: PositionPropTypes.mountNode,
+  insertAt: PropTypes.oneOf(['bottom', 'top']),
+  liveRegion: PropTypes.oneOfType([
+    PropTypes.arrayOf(PropTypes.element),
+    PropTypes.element,
+    PropTypes.func
+  ]),
+  id: PropTypes.string,
+  shouldAlignArrow: PropTypes.bool,
+  shouldTrackPosition: PropTypes.bool,
+  shouldRenderOffscreen: PropTypes.bool,
+  shouldContainFocus: PropTypes.bool,
+  shouldReturnFocus: PropTypes.bool,
+  shouldCloseOnDocumentClick: PropTypes.bool,
+  shouldCloseOnEscape: PropTypes.bool,
+  shouldFocusContentOnTriggerBlur: PropTypes.bool,
+  onShowContent: PropTypes.func,
+  onHideContent: PropTypes.func,
+  onPositioned: PropTypes.func,
+  onPositionChanged: PropTypes.func,
+  onClick: PropTypes.func,
+  onFocus: PropTypes.func,
+  onBlur: PropTypes.func,
+  onKeyDown: PropTypes.func,
+  onKeyUp: PropTypes.func,
+  onMouseOver: PropTypes.func,
+  onMouseOut: PropTypes.func,
+  renderTrigger: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
   elementRef: PropTypes.func
 }
 
@@ -344,5 +374,5 @@ const allowedProps: AllowedPropKeys = [
   'elementRef'
 ]
 
-export type { PopoverProps }
+export type { PopoverProps, PopoverState }
 export { propTypes, allowedProps }