refactor: improve callback signatures (floating-ui#1674)

Author: atomiks

packages/core/src/middleware/offset.ts

@@ -1,4 +1,4 @@
-import type {Placement, Rect, Coords, Middleware, ElementRects} from '../types';
+import type {Coords, Middleware, MiddlewareArguments} from '../types';
 import {getAlignment} from '../utils/getAlignment';
 import {getSide} from '../utils/getSide';
 import {getMainAxisFromPlacement} from '../utils/getMainAxisFromPlacement';
@@ -25,28 +25,25 @@ type OffsetValue =
        */
       alignmentAxis?: number | null;
     };
-type OffsetFunction = (args: {
-  floating: Rect;
-  reference: Rect;
-  placement: Placement;
-}) => OffsetValue;
+type OffsetFunction = (args: MiddlewareArguments) => OffsetValue;
 
 export type Options = OffsetValue | OffsetFunction;
 
-export function convertValueToCoords(
-  placement: Placement,
-  rects: ElementRects,
-  value: Options,
-  rtl = false
-): Coords {
+export async function convertValueToCoords(
+  middlewareArguments: MiddlewareArguments,
+  value: Options
+): Promise<Coords> {
+  const {placement, platform, elements} = middlewareArguments;
+  const rtl = await platform.isRTL?.(elements.floating);
+
   const side = getSide(placement);
   const alignment = getAlignment(placement);
   const isVertical = getMainAxisFromPlacement(placement) === 'x';
   const mainAxisMulti = ['left', 'top'].includes(side) ? -1 : 1;
   const crossAxisMulti = rtl && isVertical ? -1 : 1;
 
   const rawValue =
-    typeof value === 'function' ? value({...rects, placement}) : value;
+    typeof value === 'function' ? value(middlewareArguments) : value;
 
   // eslint-disable-next-line prefer-const
   let {mainAxis, crossAxis, alignmentAxis} =
@@ -71,14 +68,8 @@ export const offset = (value: Options = 0): Middleware => ({
   name: 'offset',
   options: value,
   async fn(middlewareArguments) {
-    const {x, y, placement, rects, platform, elements} = middlewareArguments;
-
-    const diffCoords = convertValueToCoords(
-      placement,
-      rects,
-      value,
-      await platform.isRTL?.(elements.floating)
-    );
+    const {x, y} = middlewareArguments;
+    const diffCoords = await convertValueToCoords(middlewareArguments, value);
 
     return {
       x: x + diffCoords.x,

packages/core/src/middleware/size.ts

@@ -1,4 +1,4 @@
-import type {Dimensions, ElementRects, Middleware} from '../types';
+import type {Middleware, MiddlewareArguments} from '../types';
 import {
   detectOverflow,
   Options as DetectOverflowOptions,
@@ -13,7 +13,12 @@ export interface Options {
    * to change its size.
    * @default undefined
    */
-  apply(args: Dimensions & ElementRects): void;
+  apply(
+    args: MiddlewareArguments & {
+      availableWidth: number;
+      availableHeight: number;
+    }
+  ): void;
 }
 
 /**
@@ -59,15 +64,15 @@ export const size = (
     const yMax = max(overflow.bottom, 0);
 
     const dimensions = {
-      height:
+      availableHeight:
         rects.floating.height -
         (['left', 'right'].includes(placement)
           ? 2 *
             (yMin !== 0 || yMax !== 0
               ? yMin + yMax
               : max(overflow.top, overflow.bottom))
           : overflow[heightSide]),
-      width:
+      availableWidth:
         rects.floating.width -
         (['top', 'bottom'].includes(placement)
           ? 2 *
@@ -79,7 +84,10 @@ export const size = (
 
     const prevDimensions = await platform.getDimensions(elements.floating);
 
-    apply?.({...dimensions, ...rects});
+    apply?.({
+      ...middlewareArguments,
+      ...dimensions,
+    });
 
     const nextDimensions = await platform.getDimensions(elements.floating);
 

packages/dom/test/visual/spec/Offset.tsx

@@ -11,9 +11,9 @@ const VALUES: Array<{offset: Options; name: string}> = [
   {offset: -10, name: '-10'},
   {offset: {crossAxis: 10}, name: 'cA: 10'},
   {offset: {mainAxis: 5, crossAxis: -10}, name: 'mA: 5, cA: -10'},
-  {offset: ({floating}) => -floating.height, name: '() => -f.height'},
+  {offset: ({rects}) => -rects.floating.height, name: '() => -f.height'},
   {
-    offset: ({floating}) => ({crossAxis: -floating.width / 2}),
+    offset: ({rects}) => ({crossAxis: -rects.floating.width / 2}),
     name: '() => cA: -f.width/2',
   },
   {offset: {alignmentAxis: 5}, name: 'aA: 5'},

packages/dom/test/visual/spec/Size.tsx

@@ -1,22 +1,21 @@
-import type {Dimensions, ElementRects, Placement} from '@floating-ui/core';
+import type {Placement} from '@floating-ui/core';
 import {useFloating, size} from '@floating-ui/react-dom';
 import {allPlacements} from '../utils/allPlacements';
 import {useState, useLayoutEffect} from 'react';
 import {Controls} from '../utils/Controls';
 import {useScroll} from '../utils/useScroll';
-import {flushSync} from 'react-dom';
 
 export function Size() {
   const [rtl, setRtl] = useState(false);
-  const [sizeData, setSizeData] = useState<ElementRects & Dimensions>();
   const [placement, setPlacement] = useState<Placement>('bottom');
   const {x, y, reference, floating, strategy, update, refs} = useFloating({
     placement,
     middleware: [
       size({
-        apply: (data) => {
-          flushSync(() => {
-            setSizeData(data);
+        apply({availableHeight, availableWidth, elements}) {
+          Object.assign(elements.floating.style, {
+            maxWidth: `${availableWidth}px`,
+            maxHeight: `${availableHeight}px`,
           });
         },
         padding: 10,
@@ -50,8 +49,6 @@ export function Size() {
               position: strategy,
               top: y ?? '',
               left: x ?? '',
-              maxHeight: sizeData?.height ?? '',
-              maxWidth: sizeData?.width ?? '',
               width: 400,
               height: 300,
             }}

packages/react-dom/test/index.test.tsx

@@ -14,7 +14,6 @@ import {
 import {renderHook} from '@testing-library/react-hooks';
 import {render, waitFor, fireEvent} from '@testing-library/react';
 import {useRef, useState} from 'react';
-import type {Dimensions, ElementRects} from '@floating-ui/core';
 
 test('`x` and `y` are initially `null`', async () => {
   const {result} = renderHook(() => useFloating());
@@ -25,9 +24,6 @@ test('`x` and `y` are initially `null`', async () => {
 
 test('middleware is always fresh and does not cause an infinite loop', async () => {
   function InlineMiddleware() {
-    const [sizeData, setSizeData] = useState<
-      (ElementRects & Dimensions) | null
-    >(null);
     const arrowRef = useRef(null);
     const {reference, floating} = useFloating({
       placement: 'right',
@@ -54,22 +50,25 @@ test('middleware is always fresh and does not cause an infinite loop', async ()
 
         hide(),
 
-        size({apply: setSizeData}),
+        size({
+          apply({availableHeight, elements}) {
+            Object.assign(elements.floating.style, {
+              maxHeight: `${availableHeight}px`,
+            });
+          },
+        }),
       ],
     });
 
     return (
       <>
         <div ref={reference} />
-        <div ref={floating} style={{height: sizeData?.height ?? ''}} />
+        <div ref={floating} />
       </>
     );
   }
 
   function StateMiddleware() {
-    const [sizeData, setSizeData] = useState<
-      (ElementRects & Dimensions) | null
-    >(null);
     const arrowRef = useRef(null);
     const [middleware, setMiddleware] = useState([
       offset(),
@@ -97,7 +96,13 @@ test('middleware is always fresh and does not cause an infinite loop', async ()
 
       hide(),
 
-      size({apply: setSizeData}),
+      size({
+        apply({availableHeight, elements}) {
+          Object.assign(elements.floating.style, {
+            maxHeight: `${availableHeight}px`,
+          });
+        },
+      }),
     ]);
     const {x, y, reference, floating} = useFloating({
       placement: 'right',
@@ -107,7 +112,7 @@ test('middleware is always fresh and does not cause an infinite loop', async ()
     return (
       <>
         <div ref={reference} />
-        <div ref={floating} style={{height: sizeData?.height ?? ''}} />
+        <div ref={floating} />
         <button
           data-testid="step1"
           onClick={() => setMiddleware([offset(10)])}

website/pages/docs/offset.mdx

@@ -123,14 +123,18 @@ values — this enables you to read the dimensions of the reference
 or floating elements and the current `placement{:.objectKey}`.
 
 ```js
-offset(({reference, floating, placement}) =>
-  placement === 'bottom' ? floating.width : reference.width
+offset(({rects, placement}) =>
+  placement === 'bottom'
+    ? rects.floating.width
+    : rects.reference.width
 );
 
-offset(({reference, floating, placement}) => ({
+offset(({rects, placement}) => ({
   mainAxis: placement === 'top' ? 5 : -5,
   crossAxis:
-    placement === 'right' ? reference.width : floating.width,
+    placement === 'right'
+      ? rects.reference.width
+      : rects.floating.width,
 }));
 ```
 

website/pages/docs/size.mdx

@@ -36,11 +36,11 @@ import {computePosition, size} from '@floating-ui/dom';
 computePosition(referenceEl, floatingEl, {
   middleware: [
     size({
-      apply({width, height, reference, floating}) {
+      apply({availableWidth, availableHeight, elements}) {
         // Do things with the data, e.g.
-        Object.assign(floatingEl.style, {
-          maxWidth: `${width}px`,
-          maxHeight: `${height}px`,
+        Object.assign(elements.floating.style, {
+          maxWidth: `${availableWidth}px`,
+          maxHeight: `${availableHeight}px`,
         });
       },
     }),
@@ -57,7 +57,12 @@ These are the options you can pass to `size(){:js}`.
 
 ```ts
 interface Options extends DetectOverflowOptions {
-  apply?: (args: Dimensions & ElementRects) => void;
+  apply?: (
+    args: MiddlewareArguments & {
+      availableWidth: number;
+      availableHeight: number;
+    }
+  ) => void;
 }
 ```
 
@@ -72,16 +77,36 @@ lifecycle:
 
 ```js
 size({
-  apply({width, height}) {
+  apply({
+    availableWidth,
+    availableHeight,
+    ...middlewareArguments
+  }) {
     // Style mutations here
   },
 });
 ```
 
-This is because the `x` and `y` coordinates become incorrect
-after you've changed the size, and so changes to the dimensions
-of the floating element need to be performed before the
-coordinates get assigned to it.
+#### availableWidth
+
+Represents how wide the floating element can be before it will
+overflow its clipping context. You'll generally set this as the
+`maxWidth{:.objectKey}` CSS property.
+
+#### availableHeight
+
+Represents how tall the floating element can be before it will
+overflow its clipping context. You'll generally set this as the
+`maxHeight{:.objectKey}` CSS property.
+
+#### ...middlewareArguments
+
+See [MiddlewareArguments](/docs/middleware#middlewarearguments).
+
+Many useful properties are also accessible via this callback,
+such as `rects{:.objectKey}` and `elements{:.objectKey}`, the
+latter of which is useful in the context of React where you need
+access to the floating element and it does not exist in scope.
 
 ### ...detectOverflowOptions
 
@@ -113,7 +138,7 @@ placement is used. In this scenario, place `size(){:js}`
 const middleware = [
   flip(),
   size({
-    apply({width, height}) {
+    apply({availableWidth, availableHeight}) {
       // ...
     },
   }),
@@ -155,11 +180,11 @@ and are setting a minimum acceptable size, place `size(){:js}`
 ```js
 const middleware = [
   size({
-    apply({width, height}) {
-      Object.assign(floatingEl.style, {
+    apply({availableHeight, elements}) {
+      Object.assign(elements.floating.style, {
         // Minimum acceptable height is 50px.
         // `flip` will then take over.
-        maxHeight: `${Math.max(50, height)}px`,
+        maxHeight: `${Math.max(50, availableHeight)}px`,
       });
     },
   }),
@@ -176,11 +201,11 @@ the width of the reference regardless of its contents. You can
 also use `size(){:js}` for this, as the `Rect{:.class}`s get
 passed in:
 
-```js
+```js /rects/
 size({
-  apply({reference}) {
+  apply({rects}) {
     Object.assign(floatingEl.style, {
-      width: `${reference.width}px`,
+      width: `${rects.reference.width}px`,
     });
   },
 });