@instructure/ui-position 11.7.3 → 11.7.4-pr-snapshot-1781695314229

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [11.7.4-pr-snapshot-1781695314229](https://github.com/instructure/instructure-ui/compare/v11.7.3...v11.7.4-pr-snapshot-1781695314229) (2026-06-17)
+
+
+### Features
+
+* **ui-position:** add available space to position ([2ce7236](https://github.com/instructure/instructure-ui/commit/2ce7236db58f6678aabd544823c65dda4a51082c))
+* **ui-position:** use border and padding in available space calculation ([1967e20](https://github.com/instructure/instructure-ui/commit/1967e20a214df364ead442b4f236b5e7c6019c66))
+
+
+
+
+
 ## [11.7.3](https://github.com/instructure/instructure-ui/compare/v11.7.2...v11.7.3) (2026-05-07)
 
 

package/LICENSE.md

@@ -2,6 +2,7 @@
 title: The MIT License (MIT)
 category: Getting Started
 order: 9
+isWIP: true
 ---
 
 # The MIT License (MIT)

package/{lib/Position/props.js → babel.config.cjs}

@@ -1,9 +1,3 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.allowedProps = void 0;
 /*
  * The MIT License (MIT)
  *
@@ -28,4 +22,15 @@ exports.allowedProps = void 0;
  * SOFTWARE.
  */
 
-const allowedProps = exports.allowedProps = ['renderTarget', 'target', 'placement', 'mountNode', 'insertAt', 'constrain', 'offsetX', 'offsetY', 'id', 'shouldTrackPosition', 'shouldPositionOverTarget', 'onPositionChanged', 'onPositioned', 'children', 'containerDisplay', 'elementRef'];
+module.exports = {
+  presets: [
+    [
+      require('@instructure/ui-babel-preset'),
+      {
+        esModules: Boolean(process.env.ES_MODULES),
+        removeConsole: process.env.NODE_ENV === 'production',
+        transformImports: Boolean(process.env.TRANSFORM_IMPORTS)
+      }
+    ]
+  ]
+}

package/es/Position/index.js

@@ -30,18 +30,18 @@ import { deepEqual, shallowEqual, combineDataCid } from '@instructure/ui-utils';
 import { debounce } from '@instructure/debounce';
 import { Portal } from '@instructure/ui-portal';
 import { withStyle } from '@instructure/emotion';
-import generateStyle from "./styles.js";
-import generateComponentTheme from "./theme.js";
-import { allowedProps } from "./props.js";
-import { calculateElementPosition } from "../calculateElementPosition.js";
+import generateStyle from './styles.js';
+import generateComponentTheme from './theme.js';
+import { allowedProps } from './props.js';
+import { calculateElementPosition } from '../calculateElementPosition.js';
 import { jsx as _jsx, jsxs as _jsxs } from "@emotion/react/jsx-runtime";
 /**
 ---
-category: components/utilities
+category: components/Util Components
 ---
 **/
 let Position = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, generateComponentTheme), _dec(_class = _dec2(_class = class Position extends Component {
-  static displayName = "Position";
+  static displayName = 'Position';
   static componentId = 'Position';
   static allowedProps = allowedProps;
   static defaultProps = {
@@ -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,102 @@ 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) an *inner* box inside the positioned
+   * element can occupy before the wrapper crosses the constraint edge.
+   * 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;
+    }
+
+    // Measure the wrapper's frame
+    let vFrame = 0;
+    let hFrame = 0;
+    if (elementNode && 'ownerDocument' in elementNode) {
+      const view = elementNode.ownerDocument?.defaultView;
+      if (view) {
+        const cs = view.getComputedStyle(elementNode);
+        vFrame = (parseFloat(cs.borderTopWidth) || 0) + (parseFloat(cs.borderBottomWidth) || 0) + (parseFloat(cs.paddingTop) || 0) + (parseFloat(cs.paddingBottom) || 0);
+        hFrame = (parseFloat(cs.borderLeftWidth) || 0) + (parseFloat(cs.borderRightWidth) || 0) + (parseFloat(cs.paddingLeft) || 0) + (parseFloat(cs.paddingRight) || 0);
+      }
+    }
+    return {
+      height: Math.max(0, Math.floor(height - vFrame - 1)),
+      width: Math.max(0, Math.floor(width - hFrame - 1))
+    };
+  }
 }
 function addOffsets(offsets) {
   return offsets.reduce((sum, offset) => {

package/es/index.js

@@ -21,9 +21,9 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-export { Position } from "./Position/index.js";
-export { calculateElementPosition } from "./calculateElementPosition.js";
-export { executeMirrorFunction } from "./executeMirrorFunction.js";
-export { mirrorHorizontalPlacement } from "./mirrorHorizontalPlacement.js";
-export { mirrorPlacement } from "./mirrorPlacement.js";
-export { parsePlacement } from "./parsePlacement.js";
+export { Position } from './Position/index.js';
+export { calculateElementPosition } from './calculateElementPosition.js';
+export { executeMirrorFunction } from './executeMirrorFunction.js';
+export { mirrorHorizontalPlacement } from './mirrorHorizontalPlacement.js';
+export { mirrorPlacement } from './mirrorPlacement.js';
+export { parsePlacement } from './parsePlacement.js';

package/es/mirrorHorizontalPlacement.js

@@ -21,8 +21,10 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { mirrorMap } from "./PositionPropTypes.js";
-import executeMirrorFunction from "./executeMirrorFunction.js";
+
+import { mirrorMap } from './PositionPropTypes.js';
+import executeMirrorFunction from './executeMirrorFunction.js';
+
 /**
  * Given a string or array of one or two placement values, mirrors the placement
  * horizontally.

package/es/mirrorPlacement.js

@@ -21,8 +21,10 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import { mirrorMap } from "./PositionPropTypes.js";
-import executeMirrorFunction from "./executeMirrorFunction.js";
+
+import { mirrorMap } from './PositionPropTypes.js';
+import executeMirrorFunction from './executeMirrorFunction.js';
+
 /**
  * ---
  * category: utilities/position

package/es/parsePlacement.js

@@ -21,4 +21,4 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-export { parsePlacement } from "./calculateElementPosition.js";
+export { parsePlacement } from './calculateElementPosition.js';

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@instructure/ui-position",
-  "version": "11.7.3",
+  "version": "11.7.4-pr-snapshot-1781695314229",
+  "type": "module",
   "description": "A component for positioning content with respect to a designated target.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
-  "main": "./lib/index.js",
   "types": "./types/index.d.ts",
   "repository": {
     "type": "git",
@@ -15,22 +15,22 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.29.2",
-    "@instructure/ui-dom-utils": "11.7.3",
-    "@instructure/emotion": "11.7.3",
-    "@instructure/ui-portal": "11.7.3",
-    "@instructure/shared-types": "11.7.3",
-    "@instructure/debounce": "11.7.3",
-    "@instructure/ui-react-utils": "11.7.3",
-    "@instructure/ui-themes": "11.7.3",
-    "@instructure/ui-utils": "11.7.3",
-    "@instructure/uid": "11.7.3"
+    "@instructure/debounce": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/shared-types": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/emotion": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-portal": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-dom-utils": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-react-utils": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-themes": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-utils": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/uid": "11.7.4-pr-snapshot-1781695314229"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "15.0.7",
     "vitest": "^3.2.2",
-    "@instructure/ui-babel-preset": "11.7.3",
-    "@instructure/ui-color-utils": "11.7.3"
+    "@instructure/ui-babel-preset": "11.7.4-pr-snapshot-1781695314229",
+    "@instructure/ui-color-utils": "11.7.4-pr-snapshot-1781695314229"
   },
   "peerDependencies": {
     "react": ">=18 <=19"
@@ -44,10 +44,8 @@
       "src": "./src/index.ts",
       "types": "./types/index.d.ts",
       "import": "./es/index.js",
-      "require": "./lib/index.js",
       "default": "./es/index.js"
     },
-    "./lib/*": "./lib/*",
     "./es/*": "./es/*",
     "./types/*": "./types/*",
     "./package.json": "./package.json",
@@ -57,7 +55,7 @@
     "lint": "ui-scripts lint",
     "lint:fix": "ui-scripts lint --fix",
     "clean": "ui-scripts clean",
-    "build": "ui-scripts build --modules es,cjs",
+    "build": "ui-scripts build",
     "build:watch": "pnpm run ts:check -- --watch & ui-scripts build --watch",
     "build:types": "tsc -p tsconfig.build.json",
     "ts:check": "tsc -p tsconfig.build.json --noEmit --emitDeclarationOnly false"

package/src/Position/index.tsx

@@ -41,22 +41,23 @@ import { debounce } from '@instructure/debounce'
 import { Portal } from '@instructure/ui-portal'
 import { withStyle } from '@instructure/emotion'
 
-import generateStyle from './styles'
-import generateComponentTheme from './theme'
+import generateStyle from './styles.js'
+import generateComponentTheme from './theme.js'
 import type { PositionProps, PositionState } from './props'
-import { allowedProps } from './props'
+import { allowedProps } from './props.js'
 
-import { calculateElementPosition } from '../calculateElementPosition'
-import { PositionElement } from '../PositionPropTypes'
+import { calculateElementPosition } from '../calculateElementPosition.js'
+import { PositionElement } from '../PositionPropTypes.js'
 
 /**
 ---
-category: components/utilities
+category: components/Util Components
 ---
 **/
 @withDeterministicId()
 @withStyle(generateStyle, generateComponentTheme)
 class Position extends Component<PositionProps, PositionState> {
+  static displayName = 'Position'
   static readonly componentId = 'Position'
 
   static allowedProps = allowedProps
@@ -80,9 +81,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 +103,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 +227,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 +255,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> = {