@elliemae/ds-floating-context 3.70.0-next.7 → 3.70.0-next.71

package/dist/types/DSFloatingContext.d.ts

@@ -1,31 +1,71 @@
 import React from 'react';
 import type { DSHookFloatingContextT } from './react-desc-prop-types.js';
+/**
+ * useFloatingContext — headless positioning + open/close lifecycle for a floating surface
+ * (popover / tooltip / dialog-like panel). Returns positioning styles + refs, imperative show/hide
+ * helpers, interaction handlers to spread on a trigger, and a discriminated open/close notification.
+ *
+ * COUPLING: this hook is the shared substrate under ds-app-picker, ds-tooltip and others; its
+ * open/close/escape/reason contract is relied on across packages. The consumer that leans hardest on
+ * the exact semantics below is ds-app-picker
+ * (layout/ds-app-picker/src/parts/AppPickerFloatingContext/useAppPickerFloatingContext.ts). Treat
+ * changes to these semantics as cross-package.
+ *
+ * OPEN STATE — controlled vs uncontrolled
+ *  - Uncontrolled: `externallyControlledIsOpen` undefined → open state lives here (in the underlying
+ *    ds-hooks-headless-tooltip) and is driven by the focus/hover handlers + the show/hide helpers.
+ *  - Controlled: `externallyControlledIsOpen` is a boolean → the consumer owns visibility and the
+ *    internal open state is inert. `isControlled` is surfaced on every OpenChange payload.
+ *
+ * NOTIFICATION — one onOpen/onClose pair, two reasons (see OpenChange in react-desc-prop-types)
+ *  - 'interaction': fired synchronously in the event catch phase by this hook's own interaction
+ *    handling — focus/hover/blur/mouseleave, an imperative show/hide, or a NON-scoped Escape falling
+ *    through to onClose — carrying the DOM event when there is one. Fires for controlled contexts too
+ *    (the pre-flip signal a controlled consumer may act on).
+ *  - 'controlled-flip': fired from a post-commit effect (useSyntheticEventFromControlledState) when
+ *    `externallyControlledIsOpen` transitions. No event. NEVER fires on mount — a surface rendered
+ *    already-open gets no onOpen and must seed any initial focus itself.
+ *
+ * ESCAPE — one listener, not two
+ *  Escape dismissal rides ds-hooks-headless-tooltip's single always-on document keydown listener (it
+ *  calls hideTooltip on ANY Escape, even when this context never opened). handleClose is the one place
+ *  that interprets it:
+ *   - SCOPED Escape (was open + closeOnEscape + key 'Escape' + focus within the panel/reference)
+ *       → routes to `onEscape` (NOT onClose); if returnFocusToReference, focuses the reference.
+ *   - anything else, including a non-scoped Escape → `onClose` with reason 'interaction'.
+ *  returnFocusToReference is a SCOPED-ESCAPE-ONLY affordance; no other close path moves focus.
+ *
+ * FRAGILITY: closeOnEscape is honored independently of who owns open state. A CONTROLLED consumer that
+ * leaves closeOnEscape on but does not itself close on Escape will have focus returned to the reference
+ * on a scoped Escape while the consumer-owned open state has not changed — focus can leave a panel that
+ * stays open. Controlled consumers should own Escape (ds-app-picker uses `closeOnEscape: !onKeyDown`).
+ */
 declare const useFloatingContext: {
     (props?: DSHookFloatingContextT.Props): {
         refs: {
-            setReference: React.Dispatch<React.SetStateAction<Element | null>>;
+            setReference: (el: Element | null) => void;
             setFloating: React.Dispatch<React.SetStateAction<HTMLElement | null>>;
             floating: HTMLElement | null;
             reference: Element | null;
         };
         floatingStyles: React.CSSProperties;
         handlers: {
-            onMouseEnter: () => void;
-            onMouseLeave: () => void;
-            onFocus: () => void;
-            onBlur: () => void;
+            onMouseEnter: React.MouseEventHandler<Element>;
+            onMouseLeave: React.MouseEventHandler<Element>;
+            onFocus: React.FocusEventHandler<Element>;
+            onBlur: React.FocusEventHandler<Element>;
         };
         isOpen: boolean;
         arrowStyles: import("./parts/PopoverArrow.js").PopoverArrowT;
-        hideTooltip: () => void;
-        showTooltip: () => void;
+        hideTooltip: (event?: React.FocusEvent | React.MouseEvent | KeyboardEvent) => void;
+        showTooltip: (event?: React.FocusEvent | React.MouseEvent | React.KeyboardEvent) => void;
         context: {
             withoutPortal: boolean;
             withoutAnimation: boolean;
             portalDOMContainer: HTMLElement | undefined;
             animationDuration: number;
         };
-        mutableUpdateStyles: React.MutableRefObject<() => void>;
+        mutableUpdateStyles: React.MutableRefObject<import("lodash").DebouncedFunc<() => void>>;
         forceUpdatePosition: () => void;
     };
     displayName: string;

package/dist/types/hooks/useFloatingClickOutside.d.ts

@@ -0,0 +1,20 @@
+import { type MutableRefObject } from 'react';
+interface UseFloatingClickOutsideParams {
+    isOpen: boolean;
+    floatingWrapperNode: HTMLElement | null;
+    triggerElementReference: Element | null;
+    /**
+     * Latest-ref of the click-outside callback. Passed as a ref (rather than a value)
+     * so consumers can pass inline functions without re-attaching listeners on every render.
+     * Use `useLatestRef(onClickOutside)` to construct it.
+     */
+    onClickOutsideRef: MutableRefObject<((event: MouseEvent | TouchEvent) => void) | undefined>;
+}
+/**
+ * Attaches mousedown/touchstart listeners on the document that fire when the click target
+ * is outside BOTH the floating element and the reference element.
+ *
+ * Only active when `enabled === true` and both elements exist.
+ */
+export declare const useFloatingClickOutside: ({ isOpen, floatingWrapperNode, triggerElementReference, onClickOutsideRef, }: UseFloatingClickOutsideParams) => void;
+export {};

package/dist/types/hooks/useFloatingResizeObserver.d.ts

@@ -0,0 +1,11 @@
+interface UseFloatingResizeObserverParams {
+    isOpen: boolean;
+    floatingWrapperNode: HTMLElement | null;
+    onResize: () => void;
+}
+/**
+ * Observes the floating element's size and calls `onResize` when its bounding box changes.
+ * Used to re-run position computation when the floating content reflows (e.g. async-loaded data).
+ */
+export declare const useFloatingResizeObserver: ({ isOpen, floatingWrapperNode, onResize, }: UseFloatingResizeObserverParams) => void;
+export {};

package/dist/types/hooks/useLatestRef.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Latest-ref pattern: keeps the value in a ref that's updated on every render.
+ * Use this when an effect/listener needs to read the latest value of a prop or callback
+ * without including it in the effect's dependency array — avoids re-attaching listeners
+ * (and infinite loops via deep-equal comparators) when consumers pass inline callbacks.
+ */
+export declare const useLatestRef: <T>(value: T) => import("react").MutableRefObject<T>;

package/dist/types/hooks/useReferenceHiddenByBoundary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tracks whether `reference` is currently visible at all within `boundaryElement` — e.g. a
+ * scrollable ancestor the reference lives inside. Returns true the moment the reference scrolls
+ * fully out of that boundary's visible area (intersection ratio 0), even though it may still be
+ * within the browser viewport; flips back to false as soon as it's visible again. This is what
+ * boundaryElement/clamping cannot solve on its own: a clamped floating element just sticks at
+ * the boundary's edge, orphaned, once its reference is no longer visible to anchor it to — the
+ * consumer still considers it "open," it should just not be shown while its anchor isn't there.
+ *
+ * Always false (inert) when boundaryElement is not provided — this is opt-in, paired with
+ * useFloatingContext's boundaryElement prop.
+ */
+export declare const useReferenceHiddenByBoundary: ({ reference, boundaryElement, enabled, }: {
+    reference: Element | null;
+    boundaryElement?: Element | null;
+    enabled: boolean;
+}) => boolean;

package/dist/types/hooks/useResolvedReference.d.ts

@@ -0,0 +1,19 @@
+interface UseResolvedReferenceParams {
+    externalReferenceElement: Element | null | undefined;
+    internalReferenceElement: Element | null;
+    setInternalReferenceElement: (el: Element | null) => void;
+}
+/**
+ * Resolves the active reference element for the floating context.
+ *
+ * - When `externalReferenceElement` is provided (anything other than `undefined`, including `null`),
+ *   it is used as the source of truth. `setReference` becomes a no-op so consumers that mistakenly
+ *   call `refs.setReference()` don't desynchronize the two sources.
+ * - Otherwise the internally-managed state is used, populated by the consumer via `refs.setReference()`
+ *   (typically as a callback ref: `innerRef={refs.setReference}`).
+ */
+export declare const useResolvedReference: ({ externalReferenceElement, internalReferenceElement, setInternalReferenceElement, }: UseResolvedReferenceParams) => {
+    triggerElementReference: Element | null;
+    setReferenceElement: (el: Element | null) => void;
+};
+export {};

package/dist/types/hooks/useSyntheticEventFromControlledState.d.ts

@@ -0,0 +1,32 @@
+interface UseSyntheticEventFromControlledStateParams {
+    /**
+     * The externally-controlled value whose transitions are turned into events. `undefined` means
+     * the value is not being controlled (uncontrolled usage) — no events are synthesized in that case.
+     */
+    controlledValue: boolean | undefined;
+    /** Fired when `controlledValue` transitions to `true`. Passed inline is fine (latest-ref'd). */
+    onEnter?: () => void;
+    /** Fired when `controlledValue` transitions to `false`. Passed inline is fine (latest-ref'd). */
+    onExit?: () => void;
+}
+/**
+ * Synthesizes semantic enter/exit events from transitions of an **externally-controlled** value.
+ *
+ * Why this is a hook (and an effect), not something a caller should hand-roll: when a value is
+ * controlled by the consumer, its changes originate *outside* this component — there is no
+ * interaction handler in here to hang a notification on. Reacting to that change and emitting an
+ * event is the *sanctioned* `useEffect` use: **synchronizing with an external system**, where the
+ * external system is the consumer that owns the controlled state. This is categorically different
+ * from the `useEffect` misuse (deriving/coordinating internal state), and it is the reason the
+ * emitted callback is a genuine "for whatever reason the owner changed it" event rather than a
+ * per-interaction one.
+ *
+ * Guarantees:
+ * - Never fires on mount — only on real transitions after the initial value.
+ * - Never fires while uncontrolled (`undefined`); only on explicit `false ↔ true` edges.
+ * - The prev-value bookkeeping is a ref (not state) *on purpose*: it is read/written only inside
+ *   the effect (post-commit), never during render, so it carries none of the render-purity hazards
+ *   that would make a ref wrong for an in-render transition guard.
+ */
+export declare const useSyntheticEventFromControlledState: ({ controlledValue, onEnter, onExit, }: UseSyntheticEventFromControlledStateParams) => void;
+export {};

package/dist/types/react-desc-prop-types.d.ts

@@ -1,3 +1,4 @@
+import type React from 'react';
 import type { DSPropTypesSchema } from '@elliemae/ds-props-helpers';
 export declare namespace DSHookFloatingContextT {
     interface DefaultProps {
@@ -7,12 +8,85 @@ export declare namespace DSHookFloatingContextT {
         animationDuration: number;
         placement: PopperPlacementsT;
         customOffset: [number, number];
+        closeOnEscape: boolean;
+        returnFocusToReference: boolean;
     }
+    /**
+     * Describes why onOpen/onClose fired.
+     * - `interaction`: driven by this hook's own interaction handling (focus/hover/escape, via
+     *   ds-hooks-headless-tooltip). Fires synchronously in the event catch phase and carries the
+     *   originating DOM event when there is one (absent for imperative show/hide). Fires for
+     *   controlled contexts too — it is the pre-flip, event-carrying signal a controlled consumer can
+     *   choose to act on.
+     * - `controlled-flip`: driven by the consumer flipping `externallyControlledIsOpen`. Fires from a
+     *   post-commit effect — the change originates outside this hook, so there is no event to carry.
+     *
+     * A controlled consumer may see BOTH for one logical transition (the pre-flip interaction, then
+     * the post-flip controlled-flip when they echo it into the prop); discriminate on `reason` (and
+     * `isControlled`) to pick which one your logic cares about. That choice is the consumer's — this
+     * hook does not decide it for them.
+     */
+    type OpenChange = {
+        reason: 'interaction';
+        event?: React.FocusEvent | React.MouseEvent | React.KeyboardEvent | KeyboardEvent;
+        isControlled: boolean;
+    } | {
+        reason: 'controlled-flip';
+        isControlled: true;
+    };
     interface OptionalProps {
         placementOrderPreference?: PopperPlacementsT[];
-        onOpen?: () => void;
-        onClose?: () => void;
+        /**
+         * Called on every open transition — both interaction-driven (pre-flip, with `event`) and
+         * controlled-flip-driven (post-flip). Discriminate on the `OpenChange` argument's `reason`.
+         */
+        onOpen?: (info: OpenChange) => void;
+        /**
+         * Called on every close transition — both interaction-driven and controlled-flip-driven.
+         * Discriminate on `reason`. Note a scoped Escape close routes to `onEscape` instead of `onClose`
+         * (see `onEscape`).
+         */
+        onClose?: (info: OpenChange) => void;
         externallyControlledIsOpen?: boolean;
+        /**
+         * Pre-resolved reference element. When provided, the hook uses this as the
+         * source of truth for positioning and ignores its internal reference state.
+         * Eliminates the need for a follow-up `refs.setReference(...)` effect and
+         * removes the visibility:hidden race that breaks programmatic focus on open.
+         */
+        externalReferenceElement?: Element | null;
+        /**
+         * Opt-in extra boundary — e.g. a scrollable ancestor of the reference — the floating
+         * element should stay visually contained within, in addition to the viewport. Only
+         * applied when portaled (withoutPortal: false, the default).
+         *
+         * Not the same as `withoutPortal: true`, and not a substitute for it: withoutPortal already
+         * derives a clipping ancestor automatically, but does so by rendering the floating element
+         * as a literal DOM descendant of it — so the browser's own CSS overflow clipping applies
+         * unconditionally, cutting off any floating content taller/wider than that ancestor, with no
+         * way for position math to prevent it. boundaryElement keeps the portal, so oversized
+         * content (e.g. a full calendar popover inside a short container) still escapes fully into
+         * the page, unclipped — it only changes the clipping *math* used for shift/flip, ignored
+         * per-axis when the floating content doesn't fit that axis of the boundary, falling back to
+         * the plain viewport for that axis instead of forcing an impossible position.
+         *
+         * Also hides the floating element (opacity/pointer-events only — isOpen state is untouched)
+         * whenever the reference scrolls fully out of this boundary's visible area, and shows it
+         * again automatically once the reference is back in view.
+         */
+        boundaryElement?: Element | null;
+        /**
+         * Called when the user clicks/taps outside both the floating element and
+         * the reference element while the floating is open.
+         */
+        onClickOutside?: (event: MouseEvent | TouchEvent) => void;
+        /**
+         * Called when Escape is pressed while the floating element is open and focus is within the
+         * floating element or the reference element. Only fires when `closeOnEscape` is true.
+         * Receives the native KeyboardEvent — this is delivered via a document-level listener, not a
+         * JSX handler, so there is no React SyntheticEvent to hand back.
+         */
+        onEscape?: (event: KeyboardEvent) => void;
     }
     interface Props extends Partial<DefaultProps>, OptionalProps {
     }

package/dist/types/useComputedPositionStyles.d.ts

@@ -3,13 +3,16 @@ import type { DSHookFloatingContextT } from './react-desc-prop-types.js';
 import type { PopoverArrowT } from './parts/PopoverArrow.js';
 type UseComputedPositionStylesT = {
     /** Prevent computing when closed (optimization + avoids unnecessary frames) */
-    preventComputing?: boolean;
-    reference: Element | null;
-    floating: HTMLElement | null;
+    isClose?: boolean;
+    triggerElementReference: Element | null;
+    floatingWrapperNode: HTMLElement | null;
     placement: DSHookFloatingContextT.PopperPlacementsT;
     placementOrderPreference?: DSHookFloatingContextT.PopperPlacementsT[];
     customOffset: [number, number];
     withoutPortal: boolean;
+    /** Opt-in extra boundary the floating element should stay visually contained within, in
+     * addition to the viewport, when portaled. See computePosition's boundaryElement doc. */
+    boundaryElement?: Element | null;
     /** Debounce ms for scroll/resize/observer events */
     debounceMs?: number;
 };
@@ -19,7 +22,7 @@ export declare const useComputedPositionStyles: (config: UseComputedPositionStyl
     hasComputedOnce: boolean;
     updateStyles: () => void;
     debouncedUpdateStyles: import("lodash").DebouncedFunc<() => void>;
-    mutableUpdateStyles: import("react").MutableRefObject<() => void>;
+    mutableUpdateStyles: import("react").MutableRefObject<import("lodash").DebouncedFunc<() => void>>;
     resetVisibilityOnly: () => void;
 };
 export {};

package/dist/types/utils/computePosition.d.ts

@@ -1,11 +1,34 @@
 import type { DSHookFloatingContextT } from '../react-desc-prop-types.js';
 interface ComputePositionProps {
-    reference: Element;
-    floating: HTMLElement;
+    triggerElementReference: Element;
+    floatingWrapperNode: HTMLElement;
     placement: DSHookFloatingContextT.PopperPlacementsT;
     placementOrderPreference?: DSHookFloatingContextT.PopperPlacementsT[];
     customOffset: [number, number];
     withoutPortal: boolean;
+    /**
+     * Opt-in extra boundary (e.g. a scrollable ancestor of the reference) the floating element
+     * should stay visually contained within, in addition to the viewport. Only applied when
+     * portaled — the non-portal path already derives its own clipping ancestor automatically via
+     * getClippingParent, by walking up from the reference.
+     *
+     * Why this exists instead of just setting `withoutPortal: true` to get that same automatic
+     * clipping-ancestor derivation: withoutPortal renders the floating element as a literal DOM
+     * descendant of the clipping ancestor, so the browser's own CSS overflow clipping applies
+     * unconditionally — any floating content taller/wider than that ancestor gets visually cut
+     * off, with no way for position math to prevent it. That is fine for content that always fits
+     * (e.g. a small filter's low/high inputs), but breaks content that can legitimately be larger
+     * than its reference's scroll container (e.g. a date-range calendar popover inside a short
+     * table row) — see PUI-17187 in ds-data-table's FilterPopover for the exact regression this
+     * caused when withoutPortal was tried first.
+     *
+     * boundaryElement keeps the portal (so oversized content still escapes fully into the page,
+     * unclipped, exactly like the no-boundaryElement case) and only changes the clipping *rect*
+     * used for shift/flip math — ignored per-axis when the floating content doesn't fit that axis
+     * of the boundary (see getBoundaryConstrainedRect), falling back to the plain viewport for
+     * that axis so oversized content is never forced into an impossible position.
+     */
+    boundaryElement?: Element | null;
 }
 export declare const computePosition: (props: ComputePositionProps) => {
     coordsStyle: {

package/dist/types/utils/floatingPositioning.d.ts

@@ -21,6 +21,18 @@ declare const adjustForFixedParent: (child: Element) => {
  */
 declare const getClippingParent: (el: Element | null) => Element | null;
 declare const getViewportRect: () => RectLike;
+/**
+ * Intersects the viewport with an explicit boundary (e.g. a scrollable ancestor the consumer
+ * wants the floating element visually contained within), one axis at a time. An axis is only
+ * constrained to the boundary when the floating element's own size actually fits within it —
+ * otherwise that axis falls back to the plain viewport. Without this fallback, content larger
+ * than the boundary (e.g. a full calendar inside a short table row) gets forced into an
+ * impossible position instead of being allowed to escape it, as it does today.
+ */
+declare const getBoundaryConstrainedRect: (viewportRect: RectLike, boundaryRect: RectLike, floatingSize: {
+    width: number;
+    height: number;
+}) => RectLike;
 /**
  * Shift behavior: if any overflow side is positive, push the popper back inside.
  * Similar to Floating UI "shift" middleware.
@@ -50,4 +62,4 @@ declare const getOffsetParentData: (floating: HTMLElement) => {
     scrollLeft: number;
     scrollTop: number;
 };
-export { applyShift, adjustForFixedParent, expandWithVariations, fits, getClippingParent, getOverflowScore, getOffsetParentData, getViewportRect, type RectLike, type OverflowOffsets, };
+export { applyShift, adjustForFixedParent, expandWithVariations, fits, getBoundaryConstrainedRect, getClippingParent, getOverflowScore, getOffsetParentData, getViewportRect, type RectLike, type OverflowOffsets, };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliemae/ds-floating-context",
-  "version": "3.70.0-next.7",
+  "version": "3.70.0-next.71",
   "license": "MIT",
   "description": "ICE MT - Dimsum - Popper Hook",
   "files": [
@@ -22,7 +22,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://git.elliemae.io/platform-ui/dimsum.git"
+    "url": "https://github.com/intcx/PLATFORM-UI.dimsum.git"
   },
   "engines": {
     "pnpm": ">=9",
@@ -36,20 +36,20 @@
     "indent": 4
   },
   "dependencies": {
-    "@elliemae/ds-hooks-headless-tooltip": "3.70.0-next.7",
-    "@elliemae/ds-props-helpers": "3.70.0-next.7",
-    "@elliemae/ds-system": "3.70.0-next.7",
-    "@elliemae/ds-typescript-helpers": "3.70.0-next.7"
+    "@elliemae/ds-hooks-headless-tooltip": "3.70.0-next.71",
+    "@elliemae/ds-system": "3.70.0-next.71",
+    "@elliemae/ds-props-helpers": "3.70.0-next.71",
+    "@elliemae/ds-typescript-helpers": "3.70.0-next.71"
   },
   "devDependencies": {
     "jest": "^30.0.0",
-    "@elliemae/ds-monorepo-devops": "3.70.0-next.7"
+    "@elliemae/ds-monorepo-devops": "3.70.0-next.71"
   },
   "peerDependencies": {
-    "lodash-es": "^4.17.21",
+    "lodash-es": "^4.18.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "styled-components": "~5.3.9",
+    "styled-components": "~5.3.11",
     "styled-system": "^5.1.5"
   },
   "publishConfig": {
@@ -65,4 +65,4 @@
     "build": "cross-env NODE_ENV=production node ../../../scripts/build/build.mjs",
     "checkDeps": "npx -yes ../../util/ds-codemods check-missing-packages --projectFolderPath=\"./\" --ignorePackagesGlobPattern=\"\" --ignoreFilesGlobPattern=\"**/test-ables/*,**/tests/*\""
   }
-}
+}

package/dist/types/tests/ControlledTestRenderer.d.ts

@@ -1 +0,0 @@
-export const ControlledTestRenderer: import("react").FunctionComponent<import("react").JSX.IntrinsicAttributes>;

package/dist/types/tests/FloatingContext.a11y.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/tests/FloatingContext.data-testid.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/tests/FloatingContext.event.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/tests/FloatingContext.exports.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/tests/FloatingContext.get-owner-props.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/tests/FloatingContext.utils.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/tests/playwright/FloatingContext.test.playwright.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/typescript-testing/typescript-floating-context-valid.d.ts

@@ -1 +0,0 @@
-export {};