@fluentui/react-positioning 9.72.9-experimental.component-base-hooks.20260122-49fc330360.0 → 9.74.3-experimental.esm.20260709-49ee7a20cf.0

package/CHANGELOG.md

@@ -1,20 +1,83 @@
 # Change Log - @fluentui/react-positioning
 
-This log was last generated on Thu, 22 Jan 2026 16:12:43 GMT and should not be manually modified.
+This log was last generated on Thu, 09 Jul 2026 17:34:14 GMT and should not be manually modified.
 
 <!-- Start content -->
 
-## [9.72.9-experimental.component-base-hooks.20260122-49fc330360.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0)
+## [9.74.3-experimental.esm.20260709-49ee7a20cf.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.74.3-experimental.esm.20260709-49ee7a20cf.0)
 
-Thu, 22 Jan 2026 16:12:43 GMT 
-[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-positioning_v9.20.11..@fluentui/react-positioning_v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0)
+Thu, 09 Jul 2026 17:34:14 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-positioning_v9.22.3..@fluentui/react-positioning_v9.74.3-experimental.esm.20260709-49ee7a20cf.0)
 
 ### Changes
 
-- Release 9.72.9-experimental.component-base-hooks.20260122-49fc330360 ([commit](https://github.com/microsoft/fluentui/commit/not available) by fluentui-internal@service.microsoft.com)
-- Bump @fluentui/react-shared-contexts to v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0 ([commit](https://github.com/microsoft/fluentui/commit/373001c3e19d022ef1fcf745ea96375cf4f3aff1) by beachball)
-- Bump @fluentui/react-theme to v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0 ([commit](https://github.com/microsoft/fluentui/commit/373001c3e19d022ef1fcf745ea96375cf4f3aff1) by beachball)
-- Bump @fluentui/react-utilities to v9.72.9-experimental.component-base-hooks.20260122-49fc330360.0 ([commit](https://github.com/microsoft/fluentui/commit/373001c3e19d022ef1fcf745ea96375cf4f3aff1) by beachball)
+- Release 9.74.3-experimental.esm.20260709-49ee7a20cf ([commit](https://github.com/microsoft/fluentui/commit/not available) by fluentui-internal@service.microsoft.com)
+- Bump @fluentui/react-shared-contexts to v9.74.3-experimental.esm.20260709-49ee7a20cf.0 ([commit](https://github.com/microsoft/fluentui/commit/175a26e0c520dd90a54578d1185a3b0b6c446e15) by beachball)
+- Bump @fluentui/react-theme to v9.74.3-experimental.esm.20260709-49ee7a20cf.0 ([commit](https://github.com/microsoft/fluentui/commit/175a26e0c520dd90a54578d1185a3b0b6c446e15) by beachball)
+- Bump @fluentui/react-utilities to v9.74.3-experimental.esm.20260709-49ee7a20cf.0 ([commit](https://github.com/microsoft/fluentui/commit/175a26e0c520dd90a54578d1185a3b0b6c446e15) by beachball)
+
+## [9.22.3](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.22.3)
+
+Wed, 24 Jun 2026 11:09:53 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-positioning_v9.22.2..@fluentui/react-positioning_v9.22.3)
+
+### Patches
+
+- fix: remove redundant use no memo directives, and add justification to valid ones ([PR #36224](https://github.com/microsoft/fluentui/pull/36224) by martinhochel@microsoft.com)
+- Bump @fluentui/react-utilities to v9.26.5 ([commit](https://github.com/microsoft/fluentui/commit/a4b871ca80c1f16f35ab4229def4fe02be7f30ea) by beachball)
+
+## [9.22.2](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.22.2)
+
+Tue, 26 May 2026 09:39:32 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-positioning_v9.22.1..@fluentui/react-positioning_v9.22.2)
+
+### Patches
+
+- Bump @fluentui/react-utilities to v9.26.4 ([PR #36246](https://github.com/microsoft/fluentui/pull/36246) by beachball)
+
+## [9.22.1](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.22.1)
+
+Thu, 23 Apr 2026 14:21:10 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-positioning_v9.22.0..@fluentui/react-positioning_v9.22.1)
+
+### Patches
+
+- Bump @fluentui/react-utilities to v9.26.3 ([PR #36035](https://github.com/microsoft/fluentui/pull/36035) by beachball)
+
+## [9.22.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.22.0)
+
+Tue, 03 Mar 2026 09:43:41 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-positioning_v9.21.0..@fluentui/react-positioning_v9.22.0)
+
+### Minor changes
+
+- refactor: deprecate createSlideStyles ([PR #35763](https://github.com/microsoft/fluentui/pull/35763) by robertpenner@microsoft.com)
+
+## [9.21.0](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.21.0)
+
+Wed, 25 Feb 2026 13:32:24 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-positioning_v9.20.12..@fluentui/react-positioning_v9.21.0)
+
+### Minor changes
+
+- feat(react-positioning): add placement to onPositioningEnd event ([PR #35773](https://github.com/microsoft/fluentui/pull/35773) by robertpenner@microsoft.com)
+- Bump @fluentui/react-shared-contexts to v9.26.2 ([PR #35782](https://github.com/microsoft/fluentui/pull/35782) by beachball)
+- Bump @fluentui/react-utilities to v9.26.2 ([PR #35782](https://github.com/microsoft/fluentui/pull/35782) by beachball)
+
+### Patches
+
+- fix: add  missing "use client" directive to client components and styles ([PR #35719](https://github.com/microsoft/fluentui/pull/35719) by dmytrokirpa@microsoft.com)
+
+## [9.20.12](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.20.12)
+
+Thu, 22 Jan 2026 17:06:36 GMT 
+[Compare changes](https://github.com/microsoft/fluentui/compare/@fluentui/react-positioning_v9.20.11..@fluentui/react-positioning_v9.20.12)
+
+### Patches
+
+- Bump @fluentui/react-shared-contexts to v9.26.1 ([PR #35574](https://github.com/microsoft/fluentui/pull/35574) by beachball)
+- Bump @fluentui/react-theme to v9.2.1 ([PR #35574](https://github.com/microsoft/fluentui/pull/35574) by beachball)
+- Bump @fluentui/react-utilities to v9.26.1 ([PR #35574](https://github.com/microsoft/fluentui/pull/35574) by beachball)
 
 ## [9.20.11](https://github.com/microsoft/fluentui/tree/@fluentui/react-positioning_v9.20.11)
 

package/dist/index.d.cts

@@ -0,0 +1,409 @@
+import type { GriffelStyle } from '@griffel/react';
+import type { JSXElement } from '@fluentui/react-utilities';
+import * as React_2 from 'react';
+import type { RefObjectFunction } from '@fluentui/react-utilities';
+
+export declare type Alignment = 'top' | 'bottom' | 'start' | 'end' | 'center';
+
+export declare type AutoSize = 'height' | 'height-always' | 'width' | 'width-always' | 'always' | boolean;
+
+/**
+ * @deprecated use PositioningBoundary instead
+ */
+export declare type Boundary = PositioningBoundary;
+
+/**
+ * Creates CSS styles to size the arrow created by createArrowStyles to the given height.
+ *
+ * Use this when you need to create classes for several different arrow sizes. If you only need a
+ * constant arrow size, you can pass the `arrowHeight` param to createArrowStyles instead.
+ *
+ * @internal
+ */
+export declare function createArrowHeightStyles(arrowHeight: number): GriffelStyle;
+
+/**
+ * Helper that creates a makeStyles rule for an arrow element.
+ * For runtime arrow size toggling simply create extra classnames to apply to the arrow element
+ *
+ * ```ts
+ *   makeStyles({
+ *     arrowWithSize: createArrowStyles({ arrowHeight: 6 }),
+ *
+ *     arrowWithoutSize: createArrowStyles({ arrowHeight: undefined }),
+ *     mediumArrow: createArrowHeightStyles(4),
+ *     smallArrow: createArrowHeightStyles(2),
+ *   })
+ *   ...
+ *
+ *   state.arrowWithSize.className = styles.arrowWithSize;
+ *   state.arrowWithoutSize.className = mergeClasses(
+ *     styles.arrowWithoutSize,
+ *     state.smallArrow && styles.smallArrow,
+ *     state.mediumArrow && styles.mediumArrow,
+ *   )
+ * ```
+ *
+ * @internal
+ */
+export declare function createArrowStyles(options: CreateArrowStylesOptions): GriffelStyle;
+
+/**
+ * Options parameter for the createArrowStyles function
+ *
+ * @internal
+ */
+export declare type CreateArrowStylesOptions = {
+    /**
+     * The height of the arrow from the base to the tip, in px. The base width of the arrow is always twice its height.
+     *
+     * This can be undefined to leave out the arrow size styles. You must then add styles created by
+     * createArrowHeightStyles to set the arrow's size correctly. This can be useful if the arrow can be different sizes.
+     */
+    arrowHeight: number | undefined;
+    /**
+     * The borderWidth of the arrow. Should be the same borderWidth as the parent element.
+     *
+     * @defaultvalue 1px
+     */
+    borderWidth?: GriffelStyle['borderBottomWidth'];
+    /**
+     * The borderStyle for the arrow. Should be the same borderStyle as the parent element.
+     *
+     * @defaultvalue solid
+     */
+    borderStyle?: GriffelStyle['borderBottomStyle'];
+    /**
+     * The borderColor of the arrow. Should be the same borderColor as the parent element.
+     *
+     * @defaultvalue tokens.colorTransparentStroke
+     */
+    borderColor?: GriffelStyle['borderBottomColor'];
+};
+
+/**
+ * Creates animation styles so that positioned elements slide in from the main axis
+ * @param mainAxis - distance than the element sides for
+ * @returns Griffel styles to spread to a slot
+ *
+ * @deprecated The popover-related components now use the Slide motion component,
+ * which they inject using the `surfaceMotion` slot.
+ */
+export declare function createSlideStyles(mainAxis: number): GriffelStyle;
+
+/**
+ * Creates a virtual element based on the position of a click event
+ * Can be used as a target for popper in scenarios such as context menus
+ */
+export declare function createVirtualElementFromClick(nativeEvent: MouseEvent): PositioningVirtualElement;
+
+/**
+ * Generally when adding an arrow to popper, it's necessary to offset the position of the popper by the
+ * height of the arrow. A simple utility to merge a provided offset with an arrow height to return the final offset
+ *
+ * @internal
+ * @param userOffset - The offset provided by the user
+ * @param arrowHeight - The height of the arrow in px
+ * @returns User offset augmented with arrow height
+ */
+export declare function mergeArrowOffset(userOffset: Offset | undefined | null, arrowHeight: number): Offset;
+
+export declare type Offset = OffsetFunction | OffsetObject | OffsetShorthand;
+
+export declare type OffsetFunction = (param: OffsetFunctionParam) => OffsetObject | OffsetShorthand;
+
+export declare type OffsetFunctionParam = {
+    positionedRect: PositioningRect;
+    targetRect: PositioningRect;
+    position: Position;
+    alignment?: Alignment;
+};
+
+export declare type OffsetObject = {
+    crossAxis?: number;
+    mainAxis: number;
+};
+
+export declare type OffsetShorthand = number;
+
+/**
+ * Custom DOM event dispatched on the positioned container element when a
+ * positioning update completes. Carries placement information in `event.detail`.
+ */
+declare type OnPositioningEndEvent = CustomEvent<OnPositioningEndEventDetail>;
+
+/**
+ * Detail payload of the positioning end event, providing the final computed placement
+ * after all middleware (flip, shift, etc.) have run.
+ */
+declare type OnPositioningEndEventDetail = {
+    /**
+     * The computed placement of the positioned element. May differ from the requested
+     * placement if flip or other middleware adjusted it.
+     */
+    placement: PositioningPlacement;
+};
+
+export declare type Position = 'above' | 'below' | 'before' | 'after';
+
+/**
+ * CSS custom properties used to encode the slide direction for positioning-aware enter animations.
+ * Set at runtime by `usePositioningSlideDirection` and registered via the CSS
+ * `registerProperty()` API so browsers can interpolate them as `<length>` values.
+ */
+export declare const POSITIONING_SLIDE_DIRECTION_VAR_X = "--fui-positioning-slide-direction-x";
+
+export declare const POSITIONING_SLIDE_DIRECTION_VAR_Y = "--fui-positioning-slide-direction-y";
+
+export declare type PositioningBoundary = PositioningRect | HTMLElement | Array<HTMLElement> | 'clippingParents' | 'scrollParent' | 'window';
+
+export declare type PositioningConfigurationFn = (params: {
+    container: HTMLElement;
+    arrow: HTMLElement | null;
+    options: PositioningConfigurationFnOptions;
+}) => PositioningConfigurationFnOptions;
+
+export declare type PositioningConfigurationFnOptions = Omit<PositioningOptions, 'enabled' | 'onPositioningEnd' | 'positionFixed'>;
+
+/**
+ * A context provider for the positioning configuration.
+ *
+ * Accepts a function that takes the positioning options and returns them modified.
+ */
+export declare const PositioningConfigurationProvider: React_2.Provider<PositioningConfigurationFn | undefined>;
+
+export declare type PositioningImperativeRef = {
+    /**
+     * Updates the position imperatively.
+     * Useful when the position of the target changes from other factors than scrolling of window resize.
+     */
+    updatePosition: () => void;
+    /**
+     * Sets the target and updates positioning imperatively.
+     * Useful for avoiding double renders with the target option.
+     */
+    setTarget: (target: TargetElement | null) => void;
+};
+
+/**
+ * Internal options for positioning
+ */
+declare interface PositioningOptions {
+    /** Alignment for the component. Only has an effect if used with the @see position option */
+    align?: Alignment;
+    /** The element which will define the boundaries of the positioned element for the flip behavior. */
+    flipBoundary?: PositioningBoundary | null;
+    /** The element which will define the boundaries of the positioned element for the overflow behavior. */
+    overflowBoundary?: PositioningBoundary | null;
+    /**
+     * Applies a padding to the overflow bounadry, so that overflow is detected earlier before the
+     * positioned surface hits the overflow boundary.
+     */
+    overflowBoundaryPadding?: number | Partial<{
+        top: number;
+        end: number;
+        bottom: number;
+        start: number;
+    }>;
+    /**
+     * Position for the component. Position has higher priority than align. If position is vertical ('above' | 'below')
+     * and align is also vertical ('top' | 'bottom') or if both position and align are horizontal ('before' | 'after'
+     * and 'start' | 'end' respectively),
+     * then provided value for 'align' will be ignored and 'center' will be used instead.
+     */
+    position?: Position;
+    /**
+     * Enables the position element to be positioned with 'fixed' (default value is position: 'absolute')
+     * @default false
+     * @deprecated use `strategy` instead
+     */
+    positionFixed?: boolean;
+    /**
+     * Specifies the type of CSS position property to use.
+     * @default absolute
+     */
+    strategy?: 'absolute' | 'fixed';
+    /**
+     * Lets you displace a positioned element from its reference element.
+     * This can be useful if you need to apply some margin between them or if you need to fine tune the
+     * position according to some custom logic.
+     */
+    offset?: Offset;
+    /**
+     * Defines padding between the corner of the popup element and the arrow.
+     * Use to prevent the arrow from overlapping a rounded corner, for example.
+     */
+    arrowPadding?: number;
+    /**
+     * Applies styles on the positioned element to fit it within the available space in viewport.
+     * - true: set styles for max height/width.
+     * - 'height': set styles for max height.
+     * - 'width'': set styles for max width.
+     * Note that options 'always'/'height-always'/'width-always' are now obsolete, and equivalent to true/'height'/'width'.
+     */
+    autoSize?: AutoSize;
+    /**
+     * Modifies position and alignment to cover the target
+     */
+    coverTarget?: boolean;
+    /**
+     * Disables automatic repositioning of the component; it will always be placed according to the values of `align` and
+     * `position` props, regardless of the size of the component, the reference element or the viewport.
+     */
+    pinned?: boolean;
+    /**
+     * When the reference element or the viewport is outside viewport allows a positioned element to be fully in viewport.
+     * "all" enables this behavior for all axis.
+     */
+    unstable_disableTether?: boolean | 'all';
+    /**
+     * If flip fails to stop the positioned element from overflowing
+     * its boundaries, use a specified fallback positions.
+     */
+    fallbackPositions?: PositioningShorthandValue[];
+    /**
+     * Modifies whether popover is positioned using transform.
+     * @default true
+     */
+    useTransform?: boolean;
+    /**
+     * If false, does not position anything
+     */
+    enabled?: boolean;
+    /**
+     * When set, the positioned element matches the chosen dimension(s) of the target element
+     */
+    matchTargetSize?: 'width';
+    /**
+     * Called when a position update has finished. Multiple position updates can happen in a single render,
+     * since positioning happens outside of the React lifecycle.
+     * The event's `detail.placement` indicates the final computed placement after middleware adjustments.
+     *
+     * It's also possible to listen to the custom DOM event `fui-positioningend`
+     */
+    onPositioningEnd?: (e: OnPositioningEndEvent) => void;
+    /**
+     * Disables the resize observer that updates position on target or dimension change
+     */
+    disableUpdateOnResize?: boolean;
+    /**
+     * When true, the positioned element will shift to cover the target element when there's not enough space.
+     * @default false
+     */
+    shiftToCoverTarget?: boolean;
+}
+
+/**
+ * Physical placement of a positioned element relative to its target, as computed by Floating UI.
+ * This is a Fluent-owned equivalent of Floating UI's `Placement` type, avoiding a transitive
+ * dependency on `@floating-ui/dom` in the public API surface.
+ */
+declare type PositioningPlacement = 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end';
+
+/**
+ * Public api that allows components using react-positioning to specify positioning options
+ */
+export declare interface PositioningProps extends Pick<PositioningOptions, 'align' | 'arrowPadding' | 'autoSize' | 'coverTarget' | 'fallbackPositions' | 'flipBoundary' | 'offset' | 'overflowBoundary' | 'overflowBoundaryPadding' | 'pinned' | 'position' | 'strategy' | 'useTransform' | 'matchTargetSize' | 'onPositioningEnd' | 'disableUpdateOnResize' | 'shiftToCoverTarget'> {
+    /** An imperative handle to Popper methods. */
+    positioningRef?: React_2.Ref<PositioningImperativeRef>;
+    /**
+     * Manual override for the target element. Useful for scenarios where a component accepts user prop to override target
+     */
+    target?: TargetElement | null;
+}
+
+export declare type PositioningRect = {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+};
+
+export declare type PositioningShorthand = PositioningProps | PositioningShorthandValue;
+
+export declare type PositioningShorthandValue = 'above' | 'above-start' | 'above-end' | 'below' | 'below-start' | 'below-end' | 'before' | 'before-top' | 'before-bottom' | 'after' | 'after-top' | 'after-bottom';
+
+export declare type PositioningVirtualElement = {
+    getBoundingClientRect: () => {
+        x: number;
+        y: number;
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+        width: number;
+        height: number;
+    };
+    contextElement?: Element;
+};
+
+export declare function resolvePositioningShorthand(shorthand: PositioningShorthand | undefined | null): Readonly<PositioningProps>;
+
+export declare type SetVirtualMouseTarget = (event: React_2.MouseEvent | MouseEvent | undefined | null) => void;
+
+declare type TargetElement = HTMLElement | PositioningVirtualElement;
+
+/**
+ * @internal
+ */
+export declare function usePositioning(options: PositioningProps & PositioningOptions): UsePositioningReturn;
+
+/**
+ * A state hook that manages a popper virtual element from mouseevents.
+ * Useful for scenarios where a component needs to be positioned by mouse click (e.g. contextmenu)
+ * React synthetic events are not persisted by this hook
+ *
+ * @internal
+ * @param initialState - initializes a user provided state similare to useState
+ * @returns state and dispatcher for a Popper virtual element that uses native/synthetic mouse events
+ */
+export declare const usePositioningMouseTarget: (initialState?: PositioningVirtualElement | (() => PositioningVirtualElement)) => readonly [PositioningVirtualElement | undefined, SetVirtualMouseTarget];
+
+declare interface UsePositioningReturn {
+    targetRef: React_2.MutableRefObject<any>;
+    containerRef: React_2.MutableRefObject<any>;
+    arrowRef: React_2.MutableRefObject<any>;
+}
+
+/**
+ * A hook that manages CSS custom properties for slide direction based on positioning placement.
+ *
+ * It wraps the `onPositioningEnd` callback to set `--fui-positioning-slide-direction-x` and
+ * `--fui-positioning-slide-direction-y` CSS custom properties on the positioned element,
+ * and registers them via `CSS.registerProperty` to avoid properties propagation down to a DOM tree.
+ *
+ * @returns The wrapped `onPositioningEnd` handler to pass to the positioning config.
+ */
+export declare function usePositioningSlideDirection(options: UsePositioningSlideDirectionOptions): NonNullable<PositioningProps['onPositioningEnd']>;
+
+declare type UsePositioningSlideDirectionOptions = {
+    /** The target document for CSS.registerProperty. */
+    targetDocument: Document | undefined;
+    /** The user's original onPositioningEnd callback, if any. */
+    onPositioningEnd?: PositioningProps['onPositioningEnd'];
+};
+
+export declare function useSafeZoneArea({ debug, disabled, onSafeZoneEnter, onSafeZoneMove, onSafeZoneLeave, onSafeZoneTimeout, timeout, }?: UseSafeZoneOptions): {
+    containerRef: RefObjectFunction<HTMLElement>;
+    targetRef: RefObjectFunction<HTMLElement>;
+    elementToRender: JSXElement | null;
+};
+
+export declare type UseSafeZoneOptions = {
+    /** Enables debug mode: makes drawn shapes visible. */
+    debug?: boolean;
+    /** Disables the safe zone area. */
+    disabled?: boolean;
+    /** The time in milliseconds to wait before clearing the safe zone. */
+    timeout?: number;
+    /** Called when the mouse enters the safe zone. */
+    onSafeZoneEnter?: (e: React_2.MouseEvent) => void;
+    /** Called when the mouse moves within the safe zone. */
+    onSafeZoneMove?: (e: React_2.MouseEvent) => void;
+    /** Called when the mouse leaves the safe zone. */
+    onSafeZoneLeave?: (e: React_2.MouseEvent) => void;
+    /** Called when the safe zone times out, even if a cursor is still over a safe zone. */
+    onSafeZoneTimeout?: () => void;
+};
+
+export { }

package/dist/index.d.ts

@@ -13,16 +13,16 @@ export declare type AutoSize = 'height' | 'height-always' | 'width' | 'width-alw
 export declare type Boundary = PositioningBoundary;
 
 /**
- * @internal
  * Creates CSS styles to size the arrow created by createArrowStyles to the given height.
  *
  * Use this when you need to create classes for several different arrow sizes. If you only need a
  * constant arrow size, you can pass the `arrowHeight` param to createArrowStyles instead.
+ *
+ * @internal
  */
 export declare function createArrowHeightStyles(arrowHeight: number): GriffelStyle;
 
 /**
- * @internal
  * Helper that creates a makeStyles rule for an arrow element.
  * For runtime arrow size toggling simply create extra classnames to apply to the arrow element
  *
@@ -43,12 +43,15 @@ export declare function createArrowHeightStyles(arrowHeight: number): GriffelSty
  *     state.mediumArrow && styles.mediumArrow,
  *   )
  * ```
+ *
+ * @internal
  */
 export declare function createArrowStyles(options: CreateArrowStylesOptions): GriffelStyle;
 
 /**
- * @internal
  * Options parameter for the createArrowStyles function
+ *
+ * @internal
  */
 export declare type CreateArrowStylesOptions = {
     /**
@@ -82,6 +85,9 @@ export declare type CreateArrowStylesOptions = {
  * Creates animation styles so that positioned elements slide in from the main axis
  * @param mainAxis - distance than the element sides for
  * @returns Griffel styles to spread to a slot
+ *
+ * @deprecated The popover-related components now use the Slide motion component,
+ * which they inject using the `surfaceMotion` slot.
  */
 export declare function createSlideStyles(mainAxis: number): GriffelStyle;
 
@@ -120,8 +126,35 @@ export declare type OffsetObject = {
 
 export declare type OffsetShorthand = number;
 
+/**
+ * Custom DOM event dispatched on the positioned container element when a
+ * positioning update completes. Carries placement information in `event.detail`.
+ */
+declare type OnPositioningEndEvent = CustomEvent<OnPositioningEndEventDetail>;
+
+/**
+ * Detail payload of the positioning end event, providing the final computed placement
+ * after all middleware (flip, shift, etc.) have run.
+ */
+declare type OnPositioningEndEventDetail = {
+    /**
+     * The computed placement of the positioned element. May differ from the requested
+     * placement if flip or other middleware adjusted it.
+     */
+    placement: PositioningPlacement;
+};
+
 export declare type Position = 'above' | 'below' | 'before' | 'after';
 
+/**
+ * CSS custom properties used to encode the slide direction for positioning-aware enter animations.
+ * Set at runtime by `usePositioningSlideDirection` and registered via the CSS
+ * `registerProperty()` API so browsers can interpolate them as `<length>` values.
+ */
+export declare const POSITIONING_SLIDE_DIRECTION_VAR_X = "--fui-positioning-slide-direction-x";
+
+export declare const POSITIONING_SLIDE_DIRECTION_VAR_Y = "--fui-positioning-slide-direction-y";
+
 export declare type PositioningBoundary = PositioningRect | HTMLElement | Array<HTMLElement> | 'clippingParents' | 'scrollParent' | 'window';
 
 export declare type PositioningConfigurationFn = (params: {
@@ -244,10 +277,11 @@ declare interface PositioningOptions {
     /**
      * Called when a position update has finished. Multiple position updates can happen in a single render,
      * since positioning happens outside of the React lifecycle.
+     * The event's `detail.placement` indicates the final computed placement after middleware adjustments.
      *
      * It's also possible to listen to the custom DOM event `fui-positioningend`
      */
-    onPositioningEnd?: () => void;
+    onPositioningEnd?: (e: OnPositioningEndEvent) => void;
     /**
      * Disables the resize observer that updates position on target or dimension change
      */
@@ -259,6 +293,13 @@ declare interface PositioningOptions {
     shiftToCoverTarget?: boolean;
 }
 
+/**
+ * Physical placement of a positioned element relative to its target, as computed by Floating UI.
+ * This is a Fluent-owned equivalent of Floating UI's `Placement` type, avoiding a transitive
+ * dependency on `@floating-ui/dom` in the public API surface.
+ */
+declare type PositioningPlacement = 'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end';
+
 /**
  * Public api that allows components using react-positioning to specify positioning options
  */
@@ -308,11 +349,11 @@ declare type TargetElement = HTMLElement | PositioningVirtualElement;
 export declare function usePositioning(options: PositioningProps & PositioningOptions): UsePositioningReturn;
 
 /**
- * @internal
  * A state hook that manages a popper virtual element from mouseevents.
  * Useful for scenarios where a component needs to be positioned by mouse click (e.g. contextmenu)
  * React synthetic events are not persisted by this hook
  *
+ * @internal
  * @param initialState - initializes a user provided state similare to useState
  * @returns state and dispatcher for a Popper virtual element that uses native/synthetic mouse events
  */
@@ -324,6 +365,24 @@ declare interface UsePositioningReturn {
     arrowRef: React_2.MutableRefObject<any>;
 }
 
+/**
+ * A hook that manages CSS custom properties for slide direction based on positioning placement.
+ *
+ * It wraps the `onPositioningEnd` callback to set `--fui-positioning-slide-direction-x` and
+ * `--fui-positioning-slide-direction-y` CSS custom properties on the positioned element,
+ * and registers them via `CSS.registerProperty` to avoid properties propagation down to a DOM tree.
+ *
+ * @returns The wrapped `onPositioningEnd` handler to pass to the positioning config.
+ */
+export declare function usePositioningSlideDirection(options: UsePositioningSlideDirectionOptions): NonNullable<PositioningProps['onPositioningEnd']>;
+
+declare type UsePositioningSlideDirectionOptions = {
+    /** The target document for CSS.registerProperty. */
+    targetDocument: Document | undefined;
+    /** The user's original onPositioningEnd callback, if any. */
+    onPositioningEnd?: PositioningProps['onPositioningEnd'];
+};
+
 export declare function useSafeZoneArea({ debug, disabled, onSafeZoneEnter, onSafeZoneMove, onSafeZoneLeave, onSafeZoneTimeout, timeout, }?: UseSafeZoneOptions): {
     containerRef: RefObjectFunction<HTMLElement>;
     targetRef: RefObjectFunction<HTMLElement>;

package/lib/PositioningConfigurationContext.js

@@ -1,5 +1,5 @@
 'use client';
-import * as React from 'react';
+import * as React from "react";
 // ---
 const DEFAULT_CONFIGURATION = ({ options })=>{
     return options;

package/lib/constants.js

@@ -3,3 +3,9 @@ export const DATA_POSITIONING_ESCAPED = 'data-popper-escaped';
 export const DATA_POSITIONING_HIDDEN = 'data-popper-reference-hidden';
 export const DATA_POSITIONING_PLACEMENT = 'data-popper-placement';
 export const POSITIONING_END_EVENT = 'fui-positioningend';
+/**
+ * CSS custom properties used to encode the slide direction for positioning-aware enter animations.
+ * Set at runtime by `usePositioningSlideDirection` and registered via the CSS
+ * `registerProperty()` API so browsers can interpolate them as `<length>` values.
+ */ export const POSITIONING_SLIDE_DIRECTION_VAR_X = '--fui-positioning-slide-direction-x';
+export const POSITIONING_SLIDE_DIRECTION_VAR_Y = '--fui-positioning-slide-direction-y';

package/lib/constants.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["export const DATA_POSITIONING_INTERSECTING = 'data-popper-is-intersecting';\nexport const DATA_POSITIONING_ESCAPED = 'data-popper-escaped';\nexport const DATA_POSITIONING_HIDDEN = 'data-popper-reference-hidden';\nexport const DATA_POSITIONING_PLACEMENT = 'data-popper-placement';\nexport const POSITIONING_END_EVENT = 'fui-positioningend';\n"],"names":["DATA_POSITIONING_INTERSECTING","DATA_POSITIONING_ESCAPED","DATA_POSITIONING_HIDDEN","DATA_POSITIONING_PLACEMENT","POSITIONING_END_EVENT"],"mappings":"AAAA,OAAO,MAAMA,gCAAgC,8BAA8B;AAC3E,OAAO,MAAMC,2BAA2B,sBAAsB;AAC9D,OAAO,MAAMC,0BAA0B,+BAA+B;AACtE,OAAO,MAAMC,6BAA6B,wBAAwB;AAClE,OAAO,MAAMC,wBAAwB,qBAAqB"}
+{"version":3,"sources":["../src/constants.ts"],"sourcesContent":["export const DATA_POSITIONING_INTERSECTING = 'data-popper-is-intersecting';\nexport const DATA_POSITIONING_ESCAPED = 'data-popper-escaped';\nexport const DATA_POSITIONING_HIDDEN = 'data-popper-reference-hidden';\nexport const DATA_POSITIONING_PLACEMENT = 'data-popper-placement';\nexport const POSITIONING_END_EVENT = 'fui-positioningend';\n\n/**\n * CSS custom properties used to encode the slide direction for positioning-aware enter animations.\n * Set at runtime by `usePositioningSlideDirection` and registered via the CSS\n * `registerProperty()` API so browsers can interpolate them as `<length>` values.\n */\nexport const POSITIONING_SLIDE_DIRECTION_VAR_X = '--fui-positioning-slide-direction-x';\nexport const POSITIONING_SLIDE_DIRECTION_VAR_Y = '--fui-positioning-slide-direction-y';\n"],"names":["DATA_POSITIONING_INTERSECTING","DATA_POSITIONING_ESCAPED","DATA_POSITIONING_HIDDEN","DATA_POSITIONING_PLACEMENT","POSITIONING_END_EVENT","POSITIONING_SLIDE_DIRECTION_VAR_X","POSITIONING_SLIDE_DIRECTION_VAR_Y"],"mappings":"AAAA,OAAO,MAAMA,gCAAgC,8BAA8B;AAC3E,OAAO,MAAMC,2BAA2B,sBAAsB;AAC9D,OAAO,MAAMC,0BAA0B,+BAA+B;AACtE,OAAO,MAAMC,6BAA6B,wBAAwB;AAClE,OAAO,MAAMC,wBAAwB,qBAAqB;AAE1D;;;;CAIC,GACD,OAAO,MAAMC,oCAAoC,sCAAsC;AACvF,OAAO,MAAMC,oCAAoC,sCAAsC"}