fixup! refactor(react-headless-components-preview): rebuild usePositioning on spec-pure CSS anchor positioning

Author: mainframev

packages/react-components/react-headless-components-preview/library/docs/popover-spec.md

@@ -586,7 +586,6 @@ export type PositioningProps = {
     };
     fallbackPositions?: PositioningShorthandValue[];
     coverTarget?: boolean;
-    autoSize?: boolean | 'width' | 'height';
     target?: HTMLElement | React_2.RefObject<HTMLElement | null> | null;
     strategy?: 'absolute' | 'fixed';
     matchTargetSize?: 'width';

packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md

@@ -66,17 +66,15 @@ export type PositioningProps = {
   fallbackPositions?: PositioningShorthandValue[];
   /** Position on top of the target */
   coverTarget?: boolean;
-  /** Auto-size to available space */
-  autoSize?: boolean | 'width' | 'height';
   /**
    * Custom anchor element for the positioned surface. When provided, the
    * anchor-name is written to this element instead of the target assigned via
    * the returned `targetRef`. Accepts a DOM element or a RefObject.
    */
   target?: HTMLElement | React.RefObject<HTMLElement | null> | null;
   /**
-   * CSS `position` value used on the positioned surface.
-   * @default 'fixed'
+   * CSS `position` value used on the positioned surface. Matches v9's default.
+   * @default 'absolute'
    */
   strategy?: 'absolute' | 'fixed';
   /**
@@ -98,18 +96,32 @@ export type PositioningProps = {
    */
   positioningRef?: React.Ref<PositioningImperativeRef>;
   /**
-   * Element that clips the surface when `autoSize` is set. Instead of
-   * constraining the surface to the viewport, `max-width` / `max-height`
-   * are computed from this element's rect. Accepts a DOM element or ref.
+   * Element the surface must stay within. When set, the hook writes logical
+   * `max-inline-size` and `max-block-size` on the surface so it can never
+   * extend past the boundary's opposite edge on either axis. The surface's
+   * start edge stays anchored where CSS anchor positioning placed it; only
+   * the far edge is clamped.
+   *
+   * Known limitations:
+   * - **No boundary-driven flip.** Native CSS `position-try-fallbacks`
+   *   evaluates overflow against the viewport only (the surface lives in
+   *   the top layer via the HTML Popover API). A primary placement that
+   *   wouldn't fit the custom boundary but does fit the viewport won't
+   *   flip — surface content wraps due to the clamp instead.
+   * - **Clamp, not shift.** Differs from v9's `shift({ altBoundary: true })`
+   *   which translates the surface whole. Here the surface is reshaped.
+   * - **Ref updates.** A `useRef` whose `.current` mutates without a render
+   *   won't trigger re-subscription. Prefer a `useState<HTMLElement | null>`
+   *   setter-ref pattern.
    */
   overflowBoundary?: HTMLElement | React.RefObject<HTMLElement | null> | null;
   /**
-   * Padding (in pixels) applied inward from the `overflowBoundary` rect
-   * before `autoSize`'s `max-width` / `max-height` math runs. Accepts a
-   * single number for uniform padding, or a logical-side object
-   * (`{ top, end, bottom, start }`) for per-side control.
+   * Padding (in pixels) subtracted from each side of the `overflowBoundary`
+   * rect before the clamp is computed — breathing room between the surface
+   * and the boundary edges. Accepts a single number for uniform padding or
+   * a logical-side object (`{ top, end, bottom, start }`, RTL-aware).
    *
-   * Has no effect when `overflowBoundary` or `autoSize` is unset.
+   * Has no effect when `overflowBoundary` is unset.
    */
   overflowBoundaryPadding?: PositioningBoundaryPadding;
 };

packages/react-components/react-headless-components-preview/library/src/hooks/usePositioning/types.ts

@@ -0,0 +1,92 @@
+'use client';
+
+import { useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
+import type { LogicalAlignment, Position, PositioningProps, ResolvedBoundaryPadding } from './types';
+import { computeAvailableHeight, computeAvailableWidth, resolveBoundaryPadding, resolveElementRef } from './utils';
+
+export type UseBoundaryClampOptions = {
+  overflowBoundary: PositioningProps['overflowBoundary'];
+  overflowBoundaryPadding: PositioningProps['overflowBoundaryPadding'];
+  position: Position;
+  align: LogicalAlignment;
+  coverTarget: boolean;
+  containerEl: HTMLElement | null;
+  targetEl: HTMLElement | null;
+  targetDocument: Document | undefined;
+};
+
+function shrinkRect(rect: DOMRect, padding: ResolvedBoundaryPadding): DOMRect {
+  return {
+    top: rect.top + padding.top,
+    right: rect.right - padding.right,
+    bottom: rect.bottom - padding.bottom,
+    left: rect.left + padding.left,
+    width: rect.width - padding.left - padding.right,
+    height: rect.height - padding.top - padding.bottom,
+    x: rect.left + padding.left,
+    y: rect.top + padding.top,
+    toJSON: rect.toJSON,
+  };
+}
+
+export function useBoundaryClamp({
+  overflowBoundary,
+  overflowBoundaryPadding,
+  position,
+  align,
+  coverTarget,
+  containerEl,
+  targetEl,
+  targetDocument,
+}: UseBoundaryClampOptions): void {
+  useIsomorphicLayoutEffect(() => {
+    if (coverTarget || !containerEl || !targetEl) {
+      return;
+    }
+
+    const boundaryEl = resolveElementRef(overflowBoundary);
+    const view = targetDocument?.defaultView;
+    const ResizeObserverCtor = view?.ResizeObserver;
+
+    if (!boundaryEl || !view || !ResizeObserverCtor) {
+      return;
+    }
+
+    const surface = containerEl;
+    const trigger = targetEl;
+
+    const apply = () => {
+      const direction = view.getComputedStyle(surface).direction === 'rtl' ? 'rtl' : 'ltr';
+      const padding = resolveBoundaryPadding(overflowBoundaryPadding, direction);
+      const boundaryRect = shrinkRect(boundaryEl.getBoundingClientRect(), padding);
+      const triggerRect = trigger.getBoundingClientRect();
+
+      const maxBlock = Math.max(0, computeAvailableHeight(position, align, boundaryRect, triggerRect));
+      const maxInline = Math.max(0, computeAvailableWidth(position, align, boundaryRect, triggerRect));
+
+      surface.style.setProperty('box-sizing', 'border-box');
+      surface.style.setProperty('max-inline-size', `${maxInline}px`);
+      surface.style.setProperty('max-block-size', `${maxBlock}px`);
+    };
+
+    apply();
+
+    const observer = new ResizeObserverCtor(apply);
+
+    observer.observe(surface);
+    observer.observe(trigger);
+    observer.observe(boundaryEl);
+
+    view.addEventListener('scroll', apply, true);
+    view.addEventListener('resize', apply);
+
+    return () => {
+      observer.disconnect();
+      view.removeEventListener('scroll', apply, true);
+      view.removeEventListener('resize', apply);
+      surface.style.removeProperty('box-sizing');
+      surface.style.removeProperty('max-inline-size');
+      surface.style.removeProperty('max-block-size');
+    };
+  }, [overflowBoundary, overflowBoundaryPadding, position, align, coverTarget, containerEl, targetEl, targetDocument]);
+}