feat(ui-position): add available space to position

Author: joyenjoyer

packages/ui-position/src/Position/__tests__/Position.test.tsx

@@ -583,4 +583,25 @@ describe('<Position />', () => {
       expect(style.display).toEqual('block')
     })
   })
+
+  it('writes --ui-position-available-{height,width} on the content node', async () => {
+    render(
+      <Position
+        constrain="window"
+        placement="bottom"
+        renderTarget={<button data-testid="target">Target</button>}
+      >
+        <div data-testid="content">Content</div>
+      </Position>
+    )
+    const content = screen.getByTestId('content')
+    await waitFor(() => {
+      expect(
+        content.style.getPropertyValue('--ui-position-available-height')
+      ).not.toBe('')
+      expect(
+        content.style.getPropertyValue('--ui-position-available-width')
+      ).not.toBe('')
+    })
+  })
 })

packages/ui-position/src/Position/index.tsx

@@ -80,9 +80,13 @@ class Position extends Component<PositionProps, PositionState> {
   constructor(props: PositionProps) {
     super(props)
 
+    const initial = this.calculatePosition(props)
+    this._availableHeight = initial.availableHeight
+    this._availableWidth = initial.availableWidth
     this.state = {
       positioned: false,
-      ...this.calculatePosition(props)
+      placement: initial.placement,
+      style: initial.style
     }
     this.position = debounce(this.position, 0, {
       leading: false,
@@ -98,6 +102,8 @@ class Position extends Component<PositionProps, PositionState> {
   _listener: PositionChangeListenerType | null = null
   _content?: PositionElement
   _target?: PositionElement
+  _availableHeight?: number
+  _availableWidth?: number
 
   handleRef = (el: Element | null) => {
     const { elementRef } = this.props
@@ -220,6 +226,22 @@ class Position extends Component<PositionProps, PositionState> {
     )
   }
 
+  // Write `--ui-position-available-{height,width}` directly on the content
+  // node's inline style
+  applyAvailableSpaceCustomProperties() {
+    const node = findDOMNode(this._content) as HTMLElement | null
+    if (!node?.style) return
+    const set = (name: string, value: number | undefined) => {
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        node.style.setProperty(name, `${value}px`)
+      } else {
+        node.style.removeProperty(name)
+      }
+    }
+    set('--ui-position-available-height', this._availableHeight)
+    set('--ui-position-available-width', this._availableWidth)
+  }
+
   calculatePosition(props: PositionProps) {
     return calculateElementPosition(this._content, this._target, {
       placement: props.placement,
@@ -232,10 +254,12 @@ class Position extends Component<PositionProps, PositionState> {
   }
 
   position = () => {
-    this.setState({
-      positioned: true,
-      ...this.calculatePosition(this.props)
-    })
+    const { placement, style, availableHeight, availableWidth } =
+      this.calculatePosition(this.props)
+    this._availableHeight = availableHeight
+    this._availableWidth = availableWidth
+    this.applyAvailableSpaceCustomProperties()
+    this.setState({ positioned: true, placement, style })
   }
 
   startTracking() {

packages/ui-position/src/PositionPropTypes.ts

@@ -135,6 +135,17 @@ export type ElementPosition = {
   }
 }
 
+/**
+ * The full output of `calculateElementPosition`, including the available
+ * space numbers driving `--ui-position-available-{height,width}`. Kept
+ * separate from `ElementPosition` so `PositionState` (which extends
+ * `ElementPosition`) doesn't falsely advertise these fields
+ */
+export type ElementPositionWithAvailableSpace = ElementPosition & {
+  availableHeight?: number
+  availableWidth?: number
+}
+
 export type PositionElement = UIElement
 
 export type Offset<Type extends number | string | undefined = number> = {

packages/ui-position/src/calculateElementPosition.ts

@@ -33,7 +33,6 @@ import {
 } from '@instructure/ui-dom-utils'
 import type { RectType } from '@instructure/ui-dom-utils'
 import { mirrorPlacement } from './mirrorPlacement'
-// @ts-expect-error will be needed for fix in the `offsetToPx` method
 import { px } from '@instructure/ui-utils'
 
 import type {
@@ -42,6 +41,7 @@ import type {
   PositionConstraint,
   PositionMountNode,
   ElementPosition,
+  ElementPositionWithAvailableSpace,
   PositionElement,
   Size,
   Overflow,
@@ -95,7 +95,7 @@ function calculateElementPosition(
   element?: PositionElement,
   target?: PositionElement,
   options: Options = {}
-): ElementPosition {
+): ElementPositionWithAvailableSpace {
   if (!element || options.placement === 'offscreen') {
     // hide offscreen content at the bottom of the DOM from screenreaders
     // unless content is contained somewhere else
@@ -113,10 +113,13 @@ function calculateElementPosition(
   }
 
   const pos = new PositionData(element, target, options)
+  const { height: availableHeight, width: availableWidth } = pos.availableSpace
 
   return {
     placement: pos.placement,
-    style: pos.style
+    style: pos.style,
+    availableHeight,
+    availableWidth
   }
 }
 
@@ -304,7 +307,7 @@ class PositionData {
   ) {
     this.options = options || {}
 
-    const { container, constrain, placement, over } = this.options
+    const { container, placement, over } = this.options
 
     if (!element || placement === 'offscreen') return
 
@@ -320,16 +323,9 @@ class PositionData {
       over ? this.element.placement : this.element.mirroredPlacement
     )
 
-    if (constrain === 'window') {
-      this.constrainTo(ownerWindow(element))
-    } else if (constrain === 'scroll-parent') {
-      this.constrainTo(getScrollParents(this.target.node)[0])
-    } else if (constrain === 'parent') {
-      this.constrainTo(this.container)
-    } else if (typeof constrain === 'function') {
-      this.constrainTo(findDOMNode(constrain.call(null)))
-    } else if (typeof constrain === 'object') {
-      this.constrainTo(findDOMNode(constrain))
+    const constraintNode = this.resolveConstraintNode()
+    if (constraintNode) {
+      this.constrainTo(constraintNode)
     }
   }
 
@@ -543,6 +539,96 @@ class PositionData {
       }
     }
   }
+
+  // Resolves the `constrain` option (`'window'`, `'scroll-parent'`,
+  // `'parent'`, a function, or an element) to the DOM node it points at.
+  resolveConstraintNode(): Node | Window | null {
+    const { constrain } = this.options
+    const elementNode = this.element?.node
+    if (!elementNode) return null
+
+    if (constrain === 'window') return ownerWindow(elementNode) ?? null
+    if (constrain === 'scroll-parent') {
+      return getScrollParents(this.target?.node)[0] ?? null
+    }
+    if (constrain === 'parent') return findDOMNode(this.container) ?? null
+    if (typeof constrain === 'function') {
+      return findDOMNode(constrain.call(null)) ?? null
+    }
+    if (typeof constrain === 'object' && constrain) {
+      return findDOMNode(constrain) ?? null
+    }
+    return null
+  }
+
+  /**
+   * Maximum height/width (in CSS px) the positioned element can occupy in
+   * the resolved placement before crossing the constraint. Drives the
+   * `--ui-position-available-{height,width}` CSS variables
+   */
+  get availableSpace(): { height: number; width: number } {
+    const targetNode = this.target?.node as Element | undefined
+    const constraintNode = this.resolveConstraintNode()
+    if (
+      !this.element ||
+      !targetNode?.getBoundingClientRect ||
+      !constraintNode
+    ) {
+      return { height: Infinity, width: Infinity }
+    }
+
+    const targetRect = targetNode.getBoundingClientRect()
+    let constraintRect: RectType
+    if ('getBoundingClientRect' in constraintNode) {
+      constraintRect = (constraintNode as Element).getBoundingClientRect()
+    } else {
+      const win =
+        'defaultView' in constraintNode
+          ? (constraintNode as Document).defaultView
+          : (constraintNode as Window)
+      if (!win) return { height: Infinity, width: Infinity }
+      constraintRect = {
+        top: 0,
+        left: 0,
+        right: win.innerWidth,
+        bottom: win.innerHeight,
+        width: win.innerWidth,
+        height: win.innerHeight
+      }
+    }
+
+    // `offsetX` / `offsetY` always push the popover *away* from the trigger
+    // so on the primary axis they consume available space.
+    const elementNode = this.element.node
+    const offsetY = px(this.element._offset.top, elementNode)
+    const offsetX = px(this.element._offset.left, elementNode)
+    const [primary] = this.element.placement
+
+    let height: number
+    if (primary === 'bottom') {
+      height = constraintRect.bottom - targetRect.bottom - offsetY
+    } else if (primary === 'top') {
+      height = targetRect.top - constraintRect.top - offsetY
+    } else {
+      height = constraintRect.height
+    }
+
+    let width: number
+    if (primary === 'end') {
+      width = constraintRect.right - targetRect.right - offsetX
+    } else if (primary === 'start') {
+      width = targetRect.left - constraintRect.left - offsetX
+    } else {
+      width = constraintRect.width
+    }
+
+    // Floor at 16px so a consumer's `max-height` doesn't collapse to 0 in the
+    // frame(s) before placement flips when the trigger sits right at the edge.
+    return {
+      height: Math.max(16, height),
+      width: Math.max(16, width)
+    }
+  }
 }
 
 function addOffsets(offsets: Offset[]) {