@instructure/ui-position 11.7.4-snapshot-185 → 11.7.4-snapshot-8

package/CHANGELOG.md

@@ -3,17 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [11.7.4-snapshot-185](https://github.com/instructure/instructure-ui/compare/v11.6.0...v11.7.4-snapshot-185) (2026-05-15)
-
-
-### Bug Fixes
-
-* **many:** update dependencies, remove lots of Babel plugins, remove Webpack 4 support ([98ff8e8](https://github.com/instructure/instructure-ui/commit/98ff8e8126a70d8496d6967795a8fbb2779c6fd9))
+## [11.7.4-snapshot-8](https://github.com/instructure/instructure-ui/compare/v11.7.3...v11.7.4-snapshot-8) (2026-05-19)
 
 
 ### Features
 
-* **many:** add solution for using both old and new token system in the same app ([688a713](https://github.com/instructure/instructure-ui/commit/688a713ff715433bb085323dbad61285387c5141))
+* **ui-position:** add available space to position ([2ce7236](https://github.com/instructure/instructure-ui/commit/2ce7236db58f6678aabd544823c65dda4a51082c))
 
 
 

package/es/Position/index.js

@@ -60,9 +60,13 @@ let Position = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, g
   static contentLocatorAttribute = 'data-position-content';
   constructor(props) {
     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,
@@ -76,6 +80,8 @@ let Position = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, g
   _listener = null;
   _content;
   _target;
+  _availableHeight;
+  _availableWidth;
   handleRef = el => {
     const {
       elementRef
@@ -152,6 +158,22 @@ let Position = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, g
       }
     }, 0));
   };
+
+  // Write `--ui-position-available-{height,width}` directly on the content
+  // node's inline style
+  applyAvailableSpaceCustomProperties() {
+    const node = findDOMNode(this._content);
+    if (!node?.style) return;
+    const set = (name, value) => {
+      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) {
     return calculateElementPosition(this._content, this._target, {
       placement: props.placement,
@@ -163,9 +185,19 @@ let Position = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, g
     });
   }
   position = () => {
+    const {
+      placement,
+      style,
+      availableHeight,
+      availableWidth
+    } = this.calculatePosition(this.props);
+    this._availableHeight = availableHeight;
+    this._availableWidth = availableWidth;
+    this.applyAvailableSpaceCustomProperties();
     this.setState({
       positioned: true,
-      ...this.calculatePosition(this.props)
+      placement,
+      style
     });
   };
   startTracking() {

package/es/PositionPropTypes.js

@@ -49,4 +49,12 @@ const mirrorMap = {
   stretch: 'stretch',
   offscreen: 'offscreen'
 };
+
+/**
+ * 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 { placementPropValues, mirrorMap };

package/es/calculateElementPosition.js

@@ -23,7 +23,8 @@
  */
 
 import { getBoundingClientRect, getScrollParents, getOffsetParents, canUseDOM, findDOMNode, ownerDocument, ownerWindow } from '@instructure/ui-dom-utils';
-import { mirrorPlacement } from "./mirrorPlacement.js"; // @ts-expect-error will be needed for fix in the `offsetToPx` method
+import { mirrorPlacement } from "./mirrorPlacement.js";
+import { px } from '@instructure/ui-utils';
 /**
  * ---
  * category: utilities/position
@@ -63,9 +64,15 @@ function calculateElementPosition(element, target, options = {}) {
     };
   }
   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
   };
 }
 class PositionedElement {
@@ -211,7 +218,6 @@ class PositionData {
     this.options = options || {};
     const {
       container,
-      constrain,
       placement,
       over
     } = this.options;
@@ -222,16 +228,9 @@ class PositionData {
       left: this.options.offsetX
     });
     this.target = new PositionedElement(target || this.container, 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);
     }
   }
   options;
@@ -418,6 +417,93 @@ class PositionData {
       }
     }
   }
+
+  // Resolves the `constrain` option (`'window'`, `'scroll-parent'`,
+  // `'parent'`, a function, or an element) to the DOM node it points at.
+  resolveConstraintNode() {
+    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() {
+    const targetNode = this.target?.node;
+    const constraintNode = this.resolveConstraintNode();
+    if (!this.element || !targetNode?.getBoundingClientRect || !constraintNode) {
+      return {
+        height: Infinity,
+        width: Infinity
+      };
+    }
+    const targetRect = targetNode.getBoundingClientRect();
+    let constraintRect;
+    if ('getBoundingClientRect' in constraintNode) {
+      constraintRect = constraintNode.getBoundingClientRect();
+    } else {
+      const win = 'defaultView' in constraintNode ? constraintNode.defaultView : constraintNode;
+      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;
+    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;
+    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) {
   return offsets.reduce((sum, offset) => {

package/lib/Position/index.js

@@ -72,9 +72,13 @@ let Position = exports.Position = (_dec = (0, _withDeterministicId.withDetermini
   static contentLocatorAttribute = 'data-position-content';
   constructor(props) {
     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 = (0, _debounce.debounce)(this.position, 0, {
       leading: false,
@@ -88,6 +92,8 @@ let Position = exports.Position = (_dec = (0, _withDeterministicId.withDetermini
   _listener = null;
   _content;
   _target;
+  _availableHeight;
+  _availableWidth;
   handleRef = el => {
     const {
       elementRef
@@ -164,6 +170,22 @@ let Position = exports.Position = (_dec = (0, _withDeterministicId.withDetermini
       }
     }, 0));
   };
+
+  // Write `--ui-position-available-{height,width}` directly on the content
+  // node's inline style
+  applyAvailableSpaceCustomProperties() {
+    const node = (0, _findDOMNode.findDOMNode)(this._content);
+    if (!node?.style) return;
+    const set = (name, value) => {
+      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) {
     return (0, _calculateElementPosition.calculateElementPosition)(this._content, this._target, {
       placement: props.placement,
@@ -175,9 +197,19 @@ let Position = exports.Position = (_dec = (0, _withDeterministicId.withDetermini
     });
   }
   position = () => {
+    const {
+      placement,
+      style,
+      availableHeight,
+      availableWidth
+    } = this.calculatePosition(this.props);
+    this._availableHeight = availableHeight;
+    this._availableWidth = availableWidth;
+    this.applyAvailableSpaceCustomProperties();
     this.setState({
       positioned: true,
-      ...this.calculatePosition(this.props)
+      placement,
+      style
     });
   };
   startTracking() {

package/lib/PositionPropTypes.js

@@ -54,4 +54,11 @@ const mirrorMap = exports.mirrorMap = {
   bottom: 'top',
   stretch: 'stretch',
   offscreen: 'offscreen'
-};
+};
+
+/**
+ * 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
+ */

package/lib/calculateElementPosition.js

@@ -14,6 +14,7 @@ var _findDOMNode = require("@instructure/ui-dom-utils/lib/findDOMNode.js");
 var _ownerDocument = require("@instructure/ui-dom-utils/lib/ownerDocument.js");
 var _ownerWindow = require("@instructure/ui-dom-utils/lib/ownerWindow.js");
 var _mirrorPlacement = require("./mirrorPlacement");
+var _px = require("@instructure/ui-utils/lib/px.js");
 /*
  * The MIT License (MIT)
  *
@@ -38,8 +39,6 @@ var _mirrorPlacement = require("./mirrorPlacement");
  * SOFTWARE.
  */
 
-// @ts-expect-error will be needed for fix in the `offsetToPx` method
-
 /**
  * ---
  * category: utilities/position
@@ -79,9 +78,15 @@ function calculateElementPosition(element, target, options = {}) {
     };
   }
   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
   };
 }
 class PositionedElement {
@@ -227,7 +232,6 @@ class PositionData {
     this.options = options || {};
     const {
       container,
-      constrain,
       placement,
       over
     } = this.options;
@@ -238,16 +242,9 @@ class PositionData {
       left: this.options.offsetX
     });
     this.target = new PositionedElement(target || this.container, over ? this.element.placement : this.element.mirroredPlacement);
-    if (constrain === 'window') {
-      this.constrainTo((0, _ownerWindow.ownerWindow)(element));
-    } else if (constrain === 'scroll-parent') {
-      this.constrainTo((0, _getScrollParents.getScrollParents)(this.target.node)[0]);
-    } else if (constrain === 'parent') {
-      this.constrainTo(this.container);
-    } else if (typeof constrain === 'function') {
-      this.constrainTo((0, _findDOMNode.findDOMNode)(constrain.call(null)));
-    } else if (typeof constrain === 'object') {
-      this.constrainTo((0, _findDOMNode.findDOMNode)(constrain));
+    const constraintNode = this.resolveConstraintNode();
+    if (constraintNode) {
+      this.constrainTo(constraintNode);
     }
   }
   options;
@@ -434,6 +431,93 @@ class PositionData {
       }
     }
   }
+
+  // Resolves the `constrain` option (`'window'`, `'scroll-parent'`,
+  // `'parent'`, a function, or an element) to the DOM node it points at.
+  resolveConstraintNode() {
+    const {
+      constrain
+    } = this.options;
+    const elementNode = this.element?.node;
+    if (!elementNode) return null;
+    if (constrain === 'window') return (0, _ownerWindow.ownerWindow)(elementNode) ?? null;
+    if (constrain === 'scroll-parent') {
+      return (0, _getScrollParents.getScrollParents)(this.target?.node)[0] ?? null;
+    }
+    if (constrain === 'parent') return (0, _findDOMNode.findDOMNode)(this.container) ?? null;
+    if (typeof constrain === 'function') {
+      return (0, _findDOMNode.findDOMNode)(constrain.call(null)) ?? null;
+    }
+    if (typeof constrain === 'object' && constrain) {
+      return (0, _findDOMNode.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() {
+    const targetNode = this.target?.node;
+    const constraintNode = this.resolveConstraintNode();
+    if (!this.element || !targetNode?.getBoundingClientRect || !constraintNode) {
+      return {
+        height: Infinity,
+        width: Infinity
+      };
+    }
+    const targetRect = targetNode.getBoundingClientRect();
+    let constraintRect;
+    if ('getBoundingClientRect' in constraintNode) {
+      constraintRect = constraintNode.getBoundingClientRect();
+    } else {
+      const win = 'defaultView' in constraintNode ? constraintNode.defaultView : constraintNode;
+      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 = (0, _px.px)(this.element._offset.top, elementNode);
+    const offsetX = (0, _px.px)(this.element._offset.left, elementNode);
+    const [primary] = this.element.placement;
+    let height;
+    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;
+    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) {
   return offsets.reduce((sum, offset) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-position",
-  "version": "11.7.4-snapshot-185",
+  "version": "11.7.4-snapshot-8",
   "description": "A component for positioning content with respect to a designated target.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -15,22 +15,22 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.29.2",
-    "@instructure/debounce": "11.7.4-snapshot-185",
-    "@instructure/emotion": "11.7.4-snapshot-185",
-    "@instructure/shared-types": "11.7.4-snapshot-185",
-    "@instructure/ui-dom-utils": "11.7.4-snapshot-185",
-    "@instructure/ui-portal": "11.7.4-snapshot-185",
-    "@instructure/ui-react-utils": "11.7.4-snapshot-185",
-    "@instructure/ui-themes": "11.7.4-snapshot-185",
-    "@instructure/uid": "11.7.4-snapshot-185",
-    "@instructure/ui-utils": "11.7.4-snapshot-185"
+    "@instructure/shared-types": "11.7.4-snapshot-8",
+    "@instructure/debounce": "11.7.4-snapshot-8",
+    "@instructure/emotion": "11.7.4-snapshot-8",
+    "@instructure/ui-portal": "11.7.4-snapshot-8",
+    "@instructure/ui-dom-utils": "11.7.4-snapshot-8",
+    "@instructure/ui-utils": "11.7.4-snapshot-8",
+    "@instructure/ui-react-utils": "11.7.4-snapshot-8",
+    "@instructure/uid": "11.7.4-snapshot-8",
+    "@instructure/ui-themes": "11.7.4-snapshot-8"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "15.0.7",
     "vitest": "^3.2.2",
-    "@instructure/ui-babel-preset": "11.7.4-snapshot-185",
-    "@instructure/ui-color-utils": "11.7.4-snapshot-185"
+    "@instructure/ui-babel-preset": "11.7.4-snapshot-8",
+    "@instructure/ui-color-utils": "11.7.4-snapshot-8"
   },
   "peerDependencies": {
     "react": ">=18 <=19"

package/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() {

package/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> = {