fix: type exports and comments (#2175)

packages/core/src/detectOverflow.ts

@@ -1,7 +1,7 @@
 import type {
   Boundary,
   ElementContext,
-  MiddlewareArguments,
+  MiddlewareState,
   Padding,
   RootBoundary,
   SideObject,
@@ -47,17 +47,17 @@ export interface Options {
 
 /**
  * Resolves with an object of overflow side offsets that determine how much the
- * element is overflowing a given clipping boundary.
+ * element is overflowing a given clipping boundary on each side.
  * - positive = overflowing the boundary by that number of pixels
  * - negative = how many pixels left before it will overflow
  * - 0 = lies flush with the boundary
  * @see https://floating-ui.com/docs/detectOverflow
  */
 export async function detectOverflow(
-  middlewareArguments: MiddlewareArguments,
+  state: MiddlewareState,
   options: Partial<Options> = {}
 ): Promise<SideObject> {
-  const {x, y, platform, rects, elements, strategy} = middlewareArguments;
+  const {x, y, platform, rects, elements, strategy} = state;
 
   const {
     boundary = 'clippingAncestors',

packages/core/src/middleware/arrow.ts

@@ -21,18 +21,17 @@ export interface Options {
 }
 
 /**
- * A data provider that provides data to position an inner element of the
- * floating element (usually a triangle or caret) so that it is centered to the
- * reference element.
+ * Provides data to position an inner element of the floating element so that it
+ * appears centered to the reference element.
  * @see https://floating-ui.com/docs/arrow
  */
 export const arrow = (options: Options): Middleware => ({
   name: 'arrow',
   options,
-  async fn(middlewareArguments) {
+  async fn(state) {
     // Since `element` is required, we don't Partial<> the type.
     const {element, padding = 0} = options || {};
-    const {x, y, placement, rects, platform} = middlewareArguments;
+    const {x, y, placement, rects, platform} = state;
 
     if (element == null) {
       if (__DEV__) {

packages/core/src/middleware/autoPlacement.ts

@@ -69,17 +69,18 @@ export interface Options {
 }
 
 /**
- * Automatically chooses the `placement` which has the most space available.
+ * Optimizes the visibility of the floating element by choosing the placement
+ * that has the most space available automatically, without needing to specify a
+ * preferred placement. Alternative to `flip`.
  * @see https://floating-ui.com/docs/autoPlacement
  */
 export const autoPlacement = (
   options: Partial<Options & DetectOverflowOptions> = {}
 ): Middleware => ({
   name: 'autoPlacement',
   options,
-  async fn(middlewareArguments) {
-    const {rects, middlewareData, placement, platform, elements} =
-      middlewareArguments;
+  async fn(state) {
+    const {rects, middlewareData, placement, platform, elements} = state;
 
     const {
       crossAxis = false,
@@ -94,10 +95,7 @@ export const autoPlacement = (
         ? getPlacementList(alignment || null, autoAlignment, allowedPlacements)
         : allowedPlacements;
 
-    const overflow = await detectOverflow(
-      middlewareArguments,
-      detectOverflowOptions
-    );
+    const overflow = await detectOverflow(state, detectOverflowOptions);
 
     const currentIndex = middlewareData.autoPlacement?.index || 0;
     const currentPlacement = placements[currentIndex];

packages/core/src/middleware/flip.ts

@@ -52,28 +52,25 @@ export interface Options {
 }
 
 /**
- * A visibility optimizer that changes the placement of the floating element in
- * order to keep it in view. By default, only the opposite placement is tried.
- *
- * It has the ability to flip to any placement, not just the opposite one. You
- * can use a series of “fallback” placements, where each placement is
- * progressively tried until the one that fits can be used.
+ * Optimizes the visibility of the floating element by flipping the `placement`
+ * in order to keep it in view when the preferred placement(s) will overflow the
+ * clipping boundary. Alternative to `autoPlacement`.
  * @see https://floating-ui.com/docs/flip
  */
 export const flip = (
   options: Partial<Options & DetectOverflowOptions> = {}
 ): Middleware => ({
   name: 'flip',
   options,
-  async fn(middlewareArguments) {
+  async fn(state) {
     const {
       placement,
       middlewareData,
       rects,
       initialPlacement,
       platform,
       elements,
-    } = middlewareArguments;
+    } = state;
 
     const {
       mainAxis: checkMainAxis = true,
@@ -108,10 +105,7 @@ export const flip = (
 
     const placements = [initialPlacement, ...fallbackPlacements];
 
-    const overflow = await detectOverflow(
-      middlewareArguments,
-      detectOverflowOptions
-    );
+    const overflow = await detectOverflow(state, detectOverflowOptions);
 
     const overflows = [];
     let overflowsData = middlewareData.flip?.overflows || [];

packages/core/src/middleware/hide.ts

@@ -26,23 +26,22 @@ export interface Options {
 }
 
 /**
- * A data provider that allows you to hide the floating element in applicable
- * situations, usually when it’s not within the same clipping context as the
- * reference element.
+ * Provides data to hide the floating element in applicable situations, such as
+ * when it is not in the same clipping context as the reference element.
  * @see https://floating-ui.com/docs/hide
  */
 export const hide = (
   options: Partial<Options & DetectOverflowOptions> = {}
 ): Middleware => ({
   name: 'hide',
   options,
-  async fn(middlewareArguments) {
+  async fn(state) {
     const {strategy = 'referenceHidden', ...detectOverflowOptions} = options;
-    const {rects} = middlewareArguments;
+    const {rects} = state;
 
     switch (strategy) {
       case 'referenceHidden': {
-        const overflow = await detectOverflow(middlewareArguments, {
+        const overflow = await detectOverflow(state, {
           ...detectOverflowOptions,
           elementContext: 'reference',
         });
@@ -55,7 +54,7 @@ export const hide = (
         };
       }
       case 'escaped': {
-        const overflow = await detectOverflow(middlewareArguments, {
+        const overflow = await detectOverflow(state, {
           ...detectOverflowOptions,
           altBoundary: true,
         });

packages/core/src/middleware/inline.ts

@@ -33,9 +33,8 @@ export interface Options {
 export const inline = (options: Partial<Options> = {}): Middleware => ({
   name: 'inline',
   options,
-  async fn(middlewareArguments) {
-    const {placement, elements, rects, platform, strategy} =
-      middlewareArguments;
+  async fn(state) {
+    const {placement, elements, rects, platform, strategy} = state;
     // A MouseEvent's client{X,Y} coords can be up to 2 pixels off a
     // ClientRect's bounds, despite the event listener being triggered. A
     // padding of 2 seems to handle this issue.

packages/core/src/middleware/offset.ts

@@ -1,4 +1,4 @@
-import type {Coords, Middleware, MiddlewareArguments} from '../types';
+import type {Coords, Middleware, MiddlewareState} from '../types';
 import {getAlignment} from '../utils/getAlignment';
 import {getMainAxisFromPlacement} from '../utils/getMainAxisFromPlacement';
 import {getSide} from '../utils/getSide';
@@ -33,15 +33,15 @@ type OffsetValue =
        */
       alignmentAxis?: number | null;
     };
-type OffsetFunction = (args: MiddlewareArguments) => OffsetValue;
+type OffsetFunction = (state: MiddlewareState) => OffsetValue;
 
 export type Options = OffsetValue | OffsetFunction;
 
 export async function convertValueToCoords(
-  middlewareArguments: MiddlewareArguments,
+  state: MiddlewareState,
   value: Options
 ): Promise<Coords> {
-  const {placement, platform, elements} = middlewareArguments;
+  const {placement, platform, elements} = state;
   const rtl = await platform.isRTL?.(elements.floating);
 
   const side = getSide(placement);
@@ -50,8 +50,7 @@ export async function convertValueToCoords(
   const mainAxisMulti = ['left', 'top'].includes(side) ? -1 : 1;
   const crossAxisMulti = rtl && isVertical ? -1 : 1;
 
-  const rawValue =
-    typeof value === 'function' ? value(middlewareArguments) : value;
+  const rawValue = typeof value === 'function' ? value(state) : value;
 
   // eslint-disable-next-line prefer-const
   let {mainAxis, crossAxis, alignmentAxis} =
@@ -69,18 +68,18 @@ export async function convertValueToCoords(
 }
 
 /**
- * A placement modifier that translates the floating element along the specified
- * axes.
+ * Modifies the placement by translating the floating element along the
+ * specified axes.
  * A number (shorthand for `mainAxis` or distance), or an axes configuration
  * object may be passed.
  * @see https://floating-ui.com/docs/offset
  */
 export const offset = (value: Options = 0): Middleware => ({
   name: 'offset',
   options: value,
-  async fn(middlewareArguments) {
-    const {x, y} = middlewareArguments;
-    const diffCoords = await convertValueToCoords(middlewareArguments, value);
+  async fn(state) {
+    const {x, y} = state;
+    const diffCoords = await convertValueToCoords(state, value);
 
     return {
       x: x + diffCoords.x,

packages/core/src/middleware/shift.ts

@@ -2,7 +2,7 @@ import {
   detectOverflow,
   Options as DetectOverflowOptions,
 } from '../detectOverflow';
-import type {Coords, Middleware, MiddlewareArguments} from '../types';
+import type {Coords, Middleware, MiddlewareState} from '../types';
 import {getCrossAxis} from '../utils/getCrossAxis';
 import {getMainAxisFromPlacement} from '../utils/getMainAxisFromPlacement';
 import {getSide} from '../utils/getSide';
@@ -28,23 +28,23 @@ export interface Options {
    * detachment.
    */
   limiter: {
-    fn: (middlewareArguments: MiddlewareArguments) => Coords;
+    fn: (state: MiddlewareState) => Coords;
     options?: any;
   };
 }
 
 /**
- * A visibility optimizer that shifts the floating element along the specified
- * axes in order to keep it in view.
+ * Optimizes the visibility of the floating element by shifting it in order to
+ * keep it in view when it will overflow the clipping boundary.
  * @see https://floating-ui.com/docs/shift
  */
 export const shift = (
   options: Partial<Options & DetectOverflowOptions> = {}
 ): Middleware => ({
   name: 'shift',
   options,
-  async fn(middlewareArguments) {
-    const {x, y, placement} = middlewareArguments;
+  async fn(state) {
+    const {x, y, placement} = state;
     const {
       mainAxis: checkMainAxis = true,
       crossAxis: checkCrossAxis = false,
@@ -53,10 +53,7 @@ export const shift = (
     } = options;
 
     const coords = {x, y};
-    const overflow = await detectOverflow(
-      middlewareArguments,
-      detectOverflowOptions
-    );
+    const overflow = await detectOverflow(state, detectOverflowOptions);
     const mainAxis = getMainAxisFromPlacement(getSide(placement));
     const crossAxis = getCrossAxis(mainAxis);
 
@@ -82,7 +79,7 @@ export const shift = (
     }
 
     const limitedCoords = limiter.fn({
-      ...middlewareArguments,
+      ...state,
       [mainAxis]: mainAxisCoord,
       [crossAxis]: crossAxisCoord,
     });
@@ -98,7 +95,7 @@ export const shift = (
 });
 
 type LimitShiftOffset =
-  | ((args: MiddlewareArguments) =>
+  | ((args: MiddlewareState) =>
       | number
       | {
           /**
@@ -152,11 +149,11 @@ export const limitShift = (
   options: Partial<LimitShiftOptions> = {}
 ): {
   options: Partial<LimitShiftOffset>;
-  fn: (middlewareArguments: MiddlewareArguments) => Coords;
+  fn: (state: MiddlewareState) => Coords;
 } => ({
   options,
-  fn(middlewareArguments) {
-    const {x, y, placement, rects, middlewareData} = middlewareArguments;
+  fn(state) {
+    const {x, y, placement, rects, middlewareData} = state;
     const {
       offset = 0,
       mainAxis: checkMainAxis = true,
@@ -170,8 +167,7 @@ export const limitShift = (
     let mainAxisCoord = coords[mainAxis];
     let crossAxisCoord = coords[crossAxis];
 
-    const rawOffset =
-      typeof offset === 'function' ? offset(middlewareArguments) : offset;
+    const rawOffset = typeof offset === 'function' ? offset(state) : offset;
     const computedOffset =
       typeof rawOffset === 'number'
         ? {mainAxis: rawOffset, crossAxis: 0}