feat(utils): Export additional positioning types

Author: mlaursen

packages/transition/src/useFixedPositioning.ts

@@ -7,6 +7,7 @@ import {
 } from "react";
 import { TransitionProps } from "react-transition-group/Transition";
 import {
+  BELOW_CENTER_ANCHOR,
   FixedPositionOptions,
   getFixedPosition,
   getViewportSize,
@@ -164,7 +165,7 @@ export function useFixedPositioning({
   getOptions,
   onResize,
   onScroll,
-  anchor: currentAnchor = {},
+  anchor = BELOW_CENTER_ANCHOR,
   initialX,
   initialY,
   xMargin = 0,
@@ -192,10 +193,6 @@ export function useFixedPositioning({
         return;
       }
 
-      const anchor = {
-        x: currentAnchor.x || "center",
-        y: currentAnchor.y || "below",
-      };
       const overrides =
         typeof getOptions === "function" ? getOptions(node) : {};
       const opts: FixedPositionOptions = {
@@ -229,23 +226,22 @@ export function useFixedPositioning({
       setStyle(style);
     },
     [
-      currentAnchor.x,
-      currentAnchor.y,
-      disableSwapping,
-      disableVHBounds,
-      fixedTo,
+      element,
       getOptions,
       initialX,
       initialY,
-      onPositionChange,
-      preventOverlap,
-      transformOrigin,
-      vhMargin,
-      vwMargin,
-      width,
       xMargin,
+      vwMargin,
       yMargin,
-      element,
+      vhMargin,
+      width,
+      transformOrigin,
+      preventOverlap,
+      disableSwapping,
+      disableVHBounds,
+      anchor,
+      fixedTo,
+      onPositionChange,
     ]
   );
 

packages/utils/src/positioning/constants.ts

@@ -1,4 +1,4 @@
-import { PositionAnchor } from "./types";
+import type { PositionAnchor } from "./types";
 
 export const ABOVE_LEFT_ANCHOR: PositionAnchor = {
   x: "left",

packages/utils/src/positioning/createHorizontalPosition.ts

@@ -6,7 +6,7 @@ import {
   getRightCoord,
   XCoordConfig,
 } from "./getCoord";
-import { FixedPositionOptions, HorizontalPosition } from "./types";
+import type { FixedPositionOptions, HorizontalPosition } from "./types";
 
 /**
  * @internal

packages/utils/src/positioning/createVerticalPosition.ts

@@ -7,7 +7,7 @@ import {
   YCoordConfig,
 } from "./getCoord";
 import { getViewportSize } from "./getViewportSize";
-import { FixedPositionOptions, VerticalPosition } from "./types";
+import type { FixedPositionOptions, VerticalPosition } from "./types";
 
 /**
  * @internal

packages/utils/src/positioning/getElementRect.ts

@@ -1,4 +1,4 @@
-import { Coords } from "./types";
+import type { Coords } from "./types";
 
 function applyCoords(coord: number | undefined): string {
   return typeof coord === "number" ? `${coord}px` : "";

packages/utils/src/positioning/getFixedPosition.ts

@@ -1,10 +1,11 @@
+import { BELOW_CENTER_ANCHOR } from "./constants";
 import { createHorizontalPosition } from "./createHorizontalPosition";
 import { createVerticalPosition } from "./createVerticalPosition";
 import { findSizingContainer } from "./findSizingContainer";
 import { getElementRect } from "./getElementRect";
 import { getTransformOrigin } from "./getTransformOrigin";
 import { getViewportSize } from "./getViewportSize";
-import { FixedPosition, FixedPositionOptions } from "./types";
+import type { FixedPosition, FixedPositionOptions } from "./types";
 
 /**
  * One of the most complicated functions in this project that will attempt to
@@ -40,7 +41,7 @@ import { FixedPosition, FixedPositionOptions } from "./types";
 export function getFixedPosition({
   container,
   element,
-  anchor: propAnchor = {},
+  anchor = BELOW_CENTER_ANCHOR,
   initialX,
   initialY,
   vwMargin = 16,
@@ -54,10 +55,6 @@ export function getFixedPosition({
   disableVHBounds = false,
 }: FixedPositionOptions): FixedPosition {
   container = findSizingContainer(container);
-  const anchor = {
-    x: propAnchor.x || "center",
-    y: propAnchor.y || "below",
-  };
 
   if (process.env.NODE_ENV !== "production") {
     if (widthType !== "auto" && anchor.x !== "center") {

packages/utils/src/positioning/getTransformOrigin.ts

@@ -1,4 +1,4 @@
-import { PositionAnchor } from "./types";
+import type { PositionAnchor } from "./types";
 
 /**
  * This is a simple util that'll generate a css `transform-origin` string so

packages/utils/src/positioning/types.ts

@@ -67,6 +67,8 @@ export type SimplePosition = "above" | "below" | "left" | "right";
  *
  * If this is set to `"equal"` or `"min"` and the horizontal anchor is not set
  * to `"center"`, an error will be thrown.
+ *
+ * @defaultValue `"auto"`
  */
 export type PositionWidth = "auto" | "equal" | "min";
 
@@ -88,54 +90,55 @@ export interface InitialCoords {
   initialY?: number;
 }
 
-export interface FixedPositionOptions extends InitialCoords {
-  /**
-   * The container element that the `element` should be fixed to.
-   */
-  container: HTMLElement | null;
-
-  /**
-   * The element that is fixed to a `container` element.
-   */
-  element: HTMLElement | null;
-
+/** @remarks \@since 4.0.0 */
+export interface CalculateFixedPositionOptions extends InitialCoords {
   /**
    * The configuration to anchor the fixed element to the container element.
+   *
+   * @defaultValue `BELOW_CENTER_ANCHOR`
    */
-  anchor?: Partial<PositionAnchor>;
+  anchor?: PositionAnchor;
 
   /**
    * The viewwidth margin to apply so that the element doesn't need to be
    * directly on the screen edge.
+   *
+   * @defaultValue `16`
    */
   vwMargin?: number;
 
   /**
    * The viewwidth margin to apply so that the element doesn't need to be
    * directly on the screen edge.
+   *
+   * @defaultValue `16`
    */
   vhMargin?: number;
 
   /**
    * The container width margin to apply so that the element doesn't need to be
    * directly on the container's edge.
+   *
+   * @defaultValue `0`
    */
   xMargin?: number;
 
   /**
    * The container height margin to apply so that the element doesn't need to be
    * directly on the container's edge
+   *
+   * @defaultValue `0`
    */
   yMargin?: number;
 
-  /**
-   * @see PositionWidth
-   */
+  /** {@inheritDoc PositionWidth} */
   width?: PositionWidth;
 
   /**
    * Boolean if the style object should include the `transformOrigin` value
    * based on the x and y positions.
+   *
+   * @defaultValue `false`
    */
   transformOrigin?: boolean;
 
@@ -144,24 +147,42 @@ export interface FixedPositionOptions extends InitialCoords {
    * container element. This is useful for autocomplete menus or other
    * components that retain focus on the container element while the fixed
    * element becomes visible.
+   *
+   * @defaultValue `false`
    */
   preventOverlap?: boolean;
 
   /**
    * Boolean if the auto-swapping behavior should be disabled. It's normally
    * recommended to not disable this since it'll allow elements to appear off
    * screen.
+   *
+   * @defaultValue `false`
    */
   disableSwapping?: boolean;
 
   /**
    * Boolean if the fixed positioning should no longer prevent the fixed element
    * to be positioned within the viewport. This is nice if you want to allow for
    * full page scrolling instead and manually set a max-height on your element.
+   *
+   * @defaultValue `false`
    */
   disableVHBounds?: boolean;
 }
 
+export interface FixedPositionOptions extends CalculateFixedPositionOptions {
+  /**
+   * The container element that the `element` should be fixed to.
+   */
+  container: HTMLElement | null;
+
+  /**
+   * The element that is fixed to a `container` element.
+   */
+  element: HTMLElement | null;
+}
+
 /**
  * This is more of a private interface that is used to help show how fixed
  * elements are placed within the viewport. Most of the time the `top` and
@@ -182,6 +203,30 @@ export interface Coords {
   minWidth?: number;
 }
 
+/**
+ * The style object that should be applied to the fixed element so it will be
+ * fixed to the container element. This will be `undefined` if the container
+ * element doesn't exist within the DOM.
+ *
+ * Note: The fixed element styles **will not** contain styles for `z-index` or
+ * `background-color` so you'll need to add that manually.
+ *
+ * @remarks \@since 4.0.0
+ */
+export interface FixedPositionStyle extends Coords {
+  /**
+   * This will be `"fixed"` unless
+   * {@link CalculateFixedPositionOptions.disableVHBounds} is set to `true`.
+   */
+  position: "fixed" | "absolute";
+
+  /**
+   * This will be `undefined` unless
+   * {@link CalculateFixedPositionOptions.transformOrigin} is set to `true`
+   */
+  transformOrigin?: string;
+}
+
 /**
  * Since the position can be "swapped" to help fit the fixed element within the
  * viewport, this interface is used to contain the calculated positions as well
@@ -201,17 +246,6 @@ export interface FixedPosition {
    * applied.
    */
   actualY: VerticalPosition;
-
-  /**
-   * The style object that should be applied to the fixed element so it will be
-   * fixed to the container element. This will be `undefined` if the container
-   * element doesn't exist within the DOM.
-   *
-   * Note: The fixed element styles **will not** contain styles for `z-index` or
-   * `background-color` so you'll need to add that manually.
-   */
-  style?: Coords & {
-    position: "fixed" | "absolute";
-    transformOrigin?: string;
-  };
+  /** {@inheritDoc FixedPositionStyle} */
+  style?: FixedPositionStyle;
 }