[useAnchorPositioning] Add OffsetFunction for sideOffset and alignOffset

docs/reference/generated/menu-positioner.json

@@ -7,7 +7,7 @@
       "description": "How to align the popup relative to the specified side."
     },
     "alignOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
       "description": "Additional offset along the alignment axis of the element."
     },
@@ -16,9 +16,9 @@
       "description": "Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."
     },
     "sideOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
-      "description": "Distance between the anchor and the popup."
+      "description": "Distance between the anchor and the popup in pixels.\nAlso accepts a function that returns a number to read the dimensions of the anchor and popup,\nalong with its side and alignment.\n\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.popup`: the dimensions of the popup element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the popup is aligned against.\n- `data.align`: how the popup is aligned relative to the specified side."
     },
     "arrowPadding": {
       "type": "number",

docs/reference/generated/popover-positioner.json

@@ -8,7 +8,7 @@
       "description": "How to align the popup relative to the specified side."
     },
     "alignOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
       "description": "Additional offset along the alignment axis of the element."
     },
@@ -18,9 +18,9 @@
       "description": "Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."
     },
     "sideOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
-      "description": "Distance between the anchor and the popup."
+      "description": "Distance between the anchor and the popup in pixels.\nAlso accepts a function that returns a number to read the dimensions of the anchor and popup,\nalong with its side and alignment.\n\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.popup`: the dimensions of the popup element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the popup is aligned against.\n- `data.align`: how the popup is aligned relative to the specified side."
     },
     "arrowPadding": {
       "type": "number",

docs/reference/generated/preview-card-positioner.json

@@ -8,7 +8,7 @@
       "description": "How to align the popup relative to the specified side."
     },
     "alignOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
       "description": "Additional offset along the alignment axis of the element."
     },
@@ -18,9 +18,9 @@
       "description": "Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."
     },
     "sideOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
-      "description": "Distance between the anchor and the popup."
+      "description": "Distance between the anchor and the popup in pixels.\nAlso accepts a function that returns a number to read the dimensions of the anchor and popup,\nalong with its side and alignment.\n\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.popup`: the dimensions of the popup element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the popup is aligned against.\n- `data.align`: how the popup is aligned relative to the specified side."
     },
     "arrowPadding": {
       "type": "number",

docs/reference/generated/select-positioner.json

@@ -8,7 +8,7 @@
       "description": "How to align the popup relative to the specified side."
     },
     "alignOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
       "description": "Additional offset along the alignment axis of the element."
     },
@@ -18,9 +18,9 @@
       "description": "Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."
     },
     "sideOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
-      "description": "Distance between the anchor and the popup."
+      "description": "Distance between the anchor and the popup in pixels.\nAlso accepts a function that returns a number to read the dimensions of the anchor and popup,\nalong with its side and alignment.\n\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.popup`: the dimensions of the popup element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the popup is aligned against.\n- `data.align`: how the popup is aligned relative to the specified side."
     },
     "arrowPadding": {
       "type": "number",

docs/reference/generated/tooltip-positioner.json

@@ -8,7 +8,7 @@
       "description": "How to align the popup relative to the specified side."
     },
     "alignOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
       "description": "Additional offset along the alignment axis of the element."
     },
@@ -18,9 +18,9 @@
       "description": "Which side of the anchor element to align the popup against.\nMay automatically change to avoid collisions."
     },
     "sideOffset": {
-      "type": "number",
+      "type": "number | (data) => number",
       "default": "0",
-      "description": "Distance between the anchor and the popup."
+      "description": "Distance between the anchor and the popup in pixels.\nAlso accepts a function that returns a number to read the dimensions of the anchor and popup,\nalong with its side and alignment.\n\n- `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.\n- `data.popup`: the dimensions of the popup element with properties `width` and `height`.\n- `data.side`: which side of the anchor element the popup is aligned against.\n- `data.align`: how the popup is aligned relative to the specified side."
     },
     "arrowPadding": {
       "type": "number",

docs/reference/overrides/common.json

@@ -1,5 +1,8 @@
 {
   "props": {
+    "alignOffset": {
+      "type": "number | (data) => number"
+    },
     "anchor": {
       "type": "React.Ref | Element | VirtualElement | (() => Element | VirtualElement | null) | null"
     },
@@ -26,6 +29,9 @@
     },
     "render": {
       "type": "React.ReactElement | (props, state) => React.ReactElement"
+    },
+    "sideOffset": {
+      "type": "number | (data) => number"
     }
   },
   "types": {

packages/react/src/menu/positioner/MenuPositioner.tsx

@@ -181,7 +181,7 @@ MenuPositioner.propTypes /* remove-proptypes */ = {
    * Additional offset along the alignment axis of the element.
    * @default 0
    */
-  alignOffset: PropTypes.number,
+  alignOffset: PropTypes.oneOfType([PropTypes.func, PropTypes.number]),
   /**
    * An element to position the popup against.
    * By default, the popup will be positioned against the trigger.
@@ -258,10 +258,17 @@ MenuPositioner.propTypes /* remove-proptypes */ = {
    */
   side: PropTypes.oneOf(['bottom', 'inline-end', 'inline-start', 'left', 'right', 'top']),
   /**
-   * Distance between the anchor and the popup.
+   * Distance between the anchor and the popup in pixels.
+   * Also accepts a function that returns a number to read the dimensions of the anchor and popup,
+   * along with its side and alignment.
+   *
+   * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+   * - `data.popup`: the dimensions of the popup element with properties `width` and `height`.
+   * - `data.side`: which side of the anchor element the popup is aligned against.
+   * - `data.align`: how the popup is aligned relative to the specified side.
    * @default 0
    */
-  sideOffset: PropTypes.number,
+  sideOffset: PropTypes.oneOfType([PropTypes.func, PropTypes.number]),
   /**
    * Whether to maintain the menu in the viewport after
    * the anchor element is scrolled out of view.

packages/react/src/menu/positioner/useMenuPositioner.ts

@@ -8,7 +8,12 @@ import type {
   FloatingEvents,
 } from '@floating-ui/react';
 import { mergeReactProps } from '../../utils/mergeReactProps';
-import { type Boundary, type Side, useAnchorPositioning } from '../../utils/useAnchorPositioning';
+import {
+  useAnchorPositioning,
+  type Boundary,
+  type OffsetFunction,
+  type Side,
+} from '../../utils/useAnchorPositioning';
 import type { GenericHTMLProps } from '../../utils/types';
 import { useMenuRootContext } from '../root/MenuRootContext';
 
@@ -121,10 +126,17 @@ export namespace useMenuPositioner {
      */
     side?: Side;
     /**
-     * Distance between the anchor and the popup.
+     * Distance between the anchor and the popup in pixels.
+     * Also accepts a function that returns a number to read the dimensions of the anchor and popup,
+     * along with its side and alignment.
+     *
+     * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+     * - `data.popup`: the dimensions of the popup element with properties `width` and `height`.
+     * - `data.side`: which side of the anchor element the popup is aligned against.
+     * - `data.align`: how the popup is aligned relative to the specified side.
      * @default 0
      */
-    sideOffset?: number;
+    sideOffset?: number | OffsetFunction;
     /**
      * How to align the popup relative to the specified side.
      */
@@ -133,7 +145,7 @@ export namespace useMenuPositioner {
      * Additional offset along the alignment axis of the element.
      * @default 0
      */
-    alignOffset?: number;
+    alignOffset?: number | OffsetFunction;
     /**
      * An element or a rectangle that delimits the area that the popup is confined to.
      * @default 'clipping-ancestors'

packages/react/src/popover/positioner/PopoverPositioner.tsx

@@ -124,7 +124,7 @@ PopoverPositioner.propTypes /* remove-proptypes */ = {
    * Additional offset along the alignment axis of the element.
    * @default 0
    */
-  alignOffset: PropTypes.number,
+  alignOffset: PropTypes.oneOfType([PropTypes.func, PropTypes.number]),
   /**
    * An element to position the popup against.
    * By default, the popup will be positioned against the trigger.
@@ -202,10 +202,17 @@ PopoverPositioner.propTypes /* remove-proptypes */ = {
    */
   side: PropTypes.oneOf(['bottom', 'inline-end', 'inline-start', 'left', 'right', 'top']),
   /**
-   * Distance between the anchor and the popup.
+   * Distance between the anchor and the popup in pixels.
+   * Also accepts a function that returns a number to read the dimensions of the anchor and popup,
+   * along with its side and alignment.
+   *
+   * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+   * - `data.popup`: the dimensions of the popup element with properties `width` and `height`.
+   * - `data.side`: which side of the anchor element the popup is aligned against.
+   * - `data.align`: how the popup is aligned relative to the specified side.
    * @default 0
    */
-  sideOffset: PropTypes.number,
+  sideOffset: PropTypes.oneOfType([PropTypes.func, PropTypes.number]),
   /**
    * Whether to maintain the popup in the viewport after
    * the anchor element is scrolled out of view.

packages/react/src/popover/positioner/usePopoverPositioner.tsx

@@ -6,7 +6,12 @@ import type {
   FloatingRootContext,
 } from '@floating-ui/react';
 import { mergeReactProps } from '../../utils/mergeReactProps';
-import { type Boundary, type Side, useAnchorPositioning } from '../../utils/useAnchorPositioning';
+import {
+  useAnchorPositioning,
+  type Boundary,
+  type OffsetFunction,
+  type Side,
+} from '../../utils/useAnchorPositioning';
 import type { GenericHTMLProps } from '../../utils/types';
 import { InteractionType } from '../../utils/useEnhancedClickHandler';
 
@@ -95,10 +100,17 @@ export namespace usePopoverPositioner {
      */
     side?: Side;
     /**
-     * Distance between the anchor and the popup.
+     * Distance between the anchor and the popup in pixels.
+     * Also accepts a function that returns a number to read the dimensions of the anchor and popup,
+     * along with its side and alignment.
+     *
+     * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+     * - `data.popup`: the dimensions of the popup element with properties `width` and `height`.
+     * - `data.side`: which side of the anchor element the popup is aligned against.
+     * - `data.align`: how the popup is aligned relative to the specified side.
      * @default 0
      */
-    sideOffset?: number;
+    sideOffset?: number | OffsetFunction;
     /**
      * How to align the popup relative to the specified side.
      * @default 'center'
@@ -108,7 +120,7 @@ export namespace usePopoverPositioner {
      * Additional offset along the alignment axis of the element.
      * @default 0
      */
-    alignOffset?: number;
+    alignOffset?: number | OffsetFunction;
     /**
      * An element or a rectangle that delimits the area that the popup is confined to.
      * @default 'clipping-ancestors'

packages/react/src/preview-card/positioner/PreviewCardPositioner.tsx

@@ -138,7 +138,7 @@ PreviewCardPositioner.propTypes /* remove-proptypes */ = {
    * Additional offset along the alignment axis of the element.
    * @default 0
    */
-  alignOffset: PropTypes.number,
+  alignOffset: PropTypes.oneOfType([PropTypes.func, PropTypes.number]),
   /**
    * An element to position the popup against.
    * By default, the popup will be positioned against the trigger.
@@ -216,10 +216,17 @@ PreviewCardPositioner.propTypes /* remove-proptypes */ = {
    */
   side: PropTypes.oneOf(['bottom', 'inline-end', 'inline-start', 'left', 'right', 'top']),
   /**
-   * Distance between the anchor and the popup.
+   * Distance between the anchor and the popup in pixels.
+   * Also accepts a function that returns a number to read the dimensions of the anchor and popup,
+   * along with its side and alignment.
+   *
+   * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+   * - `data.popup`: the dimensions of the popup element with properties `width` and `height`.
+   * - `data.side`: which side of the anchor element the popup is aligned against.
+   * - `data.align`: how the popup is aligned relative to the specified side.
    * @default 0
    */
-  sideOffset: PropTypes.number,
+  sideOffset: PropTypes.oneOfType([PropTypes.func, PropTypes.number]),
   /**
    * Whether to maintain the popup in the viewport after
    * the anchor element is scrolled out of view.

packages/react/src/preview-card/positioner/usePreviewCardPositioner.ts

@@ -6,7 +6,12 @@ import type {
   FloatingRootContext,
 } from '@floating-ui/react';
 import { mergeReactProps } from '../../utils/mergeReactProps';
-import { Boundary, useAnchorPositioning, type Side } from '../../utils/useAnchorPositioning';
+import {
+  useAnchorPositioning,
+  type Boundary,
+  type OffsetFunction,
+  type Side,
+} from '../../utils/useAnchorPositioning';
 import type { GenericHTMLProps } from '../../utils/types';
 import { usePreviewCardRootContext } from '../root/PreviewCardContext';
 
@@ -97,10 +102,17 @@ export namespace usePreviewCardPositioner {
      */
     side?: Side;
     /**
-     * Distance between the anchor and the popup.
+     * Distance between the anchor and the popup in pixels.
+     * Also accepts a function that returns a number to read the dimensions of the anchor and popup,
+     * along with its side and alignment.
+     *
+     * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+     * - `data.popup`: the dimensions of the popup element with properties `width` and `height`.
+     * - `data.side`: which side of the anchor element the popup is aligned against.
+     * - `data.align`: how the popup is aligned relative to the specified side.
      * @default 0
      */
-    sideOffset?: number;
+    sideOffset?: number | OffsetFunction;
     /**
      * How to align the popup relative to the specified side.
      * @default 'center'
@@ -110,7 +122,7 @@ export namespace usePreviewCardPositioner {
      * Additional offset along the alignment axis of the element.
      * @default 0
      */
-    alignOffset?: number;
+    alignOffset?: number | OffsetFunction;
     /**
      * An element or a rectangle that delimits the area that the popup is confined to.
      * @default 'clipping-ancestors'

packages/react/src/select/positioner/SelectPositioner.tsx

@@ -118,7 +118,7 @@ SelectPositioner.propTypes /* remove-proptypes */ = {
    * Additional offset along the alignment axis of the element.
    * @default 0
    */
-  alignOffset: PropTypes.number,
+  alignOffset: PropTypes.oneOfType([PropTypes.func, PropTypes.number]),
   /**
    * An element to position the popup against.
    * By default, the popup will be positioned against the trigger.
@@ -238,10 +238,17 @@ SelectPositioner.propTypes /* remove-proptypes */ = {
    */
   side: PropTypes.oneOf(['bottom', 'inline-end', 'inline-start', 'left', 'right', 'top']),
   /**
-   * Distance between the anchor and the popup.
+   * Distance between the anchor and the popup in pixels.
+   * Also accepts a function that returns a number to read the dimensions of the anchor and popup,
+   * along with its side and alignment.
+   *
+   * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+   * - `data.popup`: the dimensions of the popup element with properties `width` and `height`.
+   * - `data.side`: which side of the anchor element the popup is aligned against.
+   * - `data.align`: how the popup is aligned relative to the specified side.
    * @default 0
    */
-  sideOffset: PropTypes.number,
+  sideOffset: PropTypes.oneOfType([PropTypes.func, PropTypes.number]),
   /**
    * Whether to maintain the select menu in the viewport after
    * the anchor element is scrolled out of view.