@elliemae/ds-floating-context 3.70.0-next.52 → 3.70.0-next.54

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 {
@@ -10,10 +11,42 @@ export declare namespace DSHookFloatingContextT {
         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
@@ -28,8 +61,10 @@ export declare namespace DSHookFloatingContextT {
          */
         onClickOutside?: (event: MouseEvent | TouchEvent) => void;
         /**
-         * Called when Escape is pressed while focus is within the floating element.
-         * Only fires when `closeOnEscape` is true.
+         * 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;
     }

package/dist/types/useComputedPositionStyles.d.ts

@@ -3,9 +3,9 @@ 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];

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

@@ -1,7 +1,7 @@
 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];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliemae/ds-floating-context",
-  "version": "3.70.0-next.52",
+  "version": "3.70.0-next.54",
   "license": "MIT",
   "description": "ICE MT - Dimsum - Popper Hook",
   "files": [
@@ -36,14 +36,14 @@
     "indent": 4
   },
   "dependencies": {
-    "@elliemae/ds-hooks-headless-tooltip": "3.70.0-next.52",
-    "@elliemae/ds-props-helpers": "3.70.0-next.52",
-    "@elliemae/ds-system": "3.70.0-next.52",
-    "@elliemae/ds-typescript-helpers": "3.70.0-next.52"
+    "@elliemae/ds-hooks-headless-tooltip": "3.70.0-next.54",
+    "@elliemae/ds-props-helpers": "3.70.0-next.54",
+    "@elliemae/ds-typescript-helpers": "3.70.0-next.54",
+    "@elliemae/ds-system": "3.70.0-next.54"
   },
   "devDependencies": {
     "jest": "^30.0.0",
-    "@elliemae/ds-monorepo-devops": "3.70.0-next.52"
+    "@elliemae/ds-monorepo-devops": "3.70.0-next.54"
   },
   "peerDependencies": {
     "lodash-es": "^4.18.1",

package/dist/cjs/hooks/useFloatingEscape.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/hooks/useFloatingEscape.ts", "../../../../../../scripts/build/transpile/react-shim.js"],
-  "sourcesContent": ["import { useCallback, useEffect, type MutableRefObject } from 'react';\n\ninterface UseFloatingEscapeParams {\n  enabled: boolean;\n  floating: HTMLElement | null;\n  reference: Element | null;\n  /** Latest-ref of the consumer's onEscape callback. Construct with `useLatestRef(onEscape)`. */\n  onEscapeRef: MutableRefObject<((event: KeyboardEvent) => void) | undefined>;\n  /** Fallback close handler invoked when no `onEscape` is provided. */\n  handleClose: () => void;\n  /** When true, calls `reference.focus()` after the escape close. */\n  returnFocusToReference: boolean;\n}\n\n/**\n * Listens for `Escape` on the document and dismisses the floating element when focus is\n * within the floating element or on the reference element. Outside that scope the event is\n * ignored \u2014 we don't hijack Escape for unrelated UI on the page.\n */\nexport const useFloatingEscape = ({\n  enabled,\n  floating,\n  reference,\n  onEscapeRef,\n  handleClose,\n  returnFocusToReference,\n}: UseFloatingEscapeParams) => {\n  const isFocusWithinFloatingScope = useCallback(\n    (active: Element | null): boolean => {\n      if (!active) return false;\n      if (floating && floating.contains(active)) return true;\n      if (!reference) return false;\n      return reference === active || reference.contains(active);\n    },\n    [floating, reference],\n  );\n\n  useEffect(() => {\n    if (!enabled) return undefined;\n\n    const listener = (event: KeyboardEvent) => {\n      if (event.key !== 'Escape') return;\n      if (!isFocusWithinFloatingScope(document.activeElement)) return;\n\n      const cb = onEscapeRef.current;\n      if (cb) {\n        cb(event);\n      } else {\n        handleClose();\n      }\n      if (returnFocusToReference && reference instanceof HTMLElement) {\n        reference.focus();\n      }\n    };\n\n    document.addEventListener('keydown', listener, true);\n    return () => {\n      document.removeEventListener('keydown', listener, true);\n    };\n  }, [enabled, handleClose, isFocusWithinFloatingScope, onEscapeRef, reference, returnFocusToReference]);\n};\n", "import * as React from 'react';\nexport { React };\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;ACAA,YAAuB;ADAvB,mBAA8D;AAmBvD,MAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MAA+B;AAC7B,QAAM,iCAA6B;AAAA,IACjC,CAAC,WAAoC;AACnC,UAAI,CAAC,OAAQ,QAAO;AACpB,UAAI,YAAY,SAAS,SAAS,MAAM,EAAG,QAAO;AAClD,UAAI,CAAC,UAAW,QAAO;AACvB,aAAO,cAAc,UAAU,UAAU,SAAS,MAAM;AAAA,IAC1D;AAAA,IACA,CAAC,UAAU,SAAS;AAAA,EACtB;AAEA,8BAAU,MAAM;AACd,QAAI,CAAC,QAAS,QAAO;AAErB,UAAM,WAAW,CAAC,UAAyB;AACzC,UAAI,MAAM,QAAQ,SAAU;AAC5B,UAAI,CAAC,2BAA2B,SAAS,aAAa,EAAG;AAEzD,YAAM,KAAK,YAAY;AACvB,UAAI,IAAI;AACN,WAAG,KAAK;AAAA,MACV,OAAO;AACL,oBAAY;AAAA,MACd;AACA,UAAI,0BAA0B,qBAAqB,aAAa;AAC9D,kBAAU,MAAM;AAAA,MAClB;AAAA,IACF;AAEA,aAAS,iBAAiB,WAAW,UAAU,IAAI;AACnD,WAAO,MAAM;AACX,eAAS,oBAAoB,WAAW,UAAU,IAAI;AAAA,IACxD;AAAA,EACF,GAAG,CAAC,SAAS,aAAa,4BAA4B,aAAa,WAAW,sBAAsB,CAAC;AACvG;",
-  "names": []
-}

package/dist/esm/hooks/useFloatingEscape.js

@@ -1,44 +0,0 @@
-import * as React from "react";
-import { useCallback, useEffect } from "react";
-const useFloatingEscape = ({
-  enabled,
-  floating,
-  reference,
-  onEscapeRef,
-  handleClose,
-  returnFocusToReference
-}) => {
-  const isFocusWithinFloatingScope = useCallback(
-    (active) => {
-      if (!active) return false;
-      if (floating && floating.contains(active)) return true;
-      if (!reference) return false;
-      return reference === active || reference.contains(active);
-    },
-    [floating, reference]
-  );
-  useEffect(() => {
-    if (!enabled) return void 0;
-    const listener = (event) => {
-      if (event.key !== "Escape") return;
-      if (!isFocusWithinFloatingScope(document.activeElement)) return;
-      const cb = onEscapeRef.current;
-      if (cb) {
-        cb(event);
-      } else {
-        handleClose();
-      }
-      if (returnFocusToReference && reference instanceof HTMLElement) {
-        reference.focus();
-      }
-    };
-    document.addEventListener("keydown", listener, true);
-    return () => {
-      document.removeEventListener("keydown", listener, true);
-    };
-  }, [enabled, handleClose, isFocusWithinFloatingScope, onEscapeRef, reference, returnFocusToReference]);
-};
-export {
-  useFloatingEscape
-};
-//# sourceMappingURL=useFloatingEscape.js.map

package/dist/esm/hooks/useFloatingEscape.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../../../scripts/build/transpile/react-shim.js", "../../../src/hooks/useFloatingEscape.ts"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import { useCallback, useEffect, type MutableRefObject } from 'react';\n\ninterface UseFloatingEscapeParams {\n  enabled: boolean;\n  floating: HTMLElement | null;\n  reference: Element | null;\n  /** Latest-ref of the consumer's onEscape callback. Construct with `useLatestRef(onEscape)`. */\n  onEscapeRef: MutableRefObject<((event: KeyboardEvent) => void) | undefined>;\n  /** Fallback close handler invoked when no `onEscape` is provided. */\n  handleClose: () => void;\n  /** When true, calls `reference.focus()` after the escape close. */\n  returnFocusToReference: boolean;\n}\n\n/**\n * Listens for `Escape` on the document and dismisses the floating element when focus is\n * within the floating element or on the reference element. Outside that scope the event is\n * ignored \u2014 we don't hijack Escape for unrelated UI on the page.\n */\nexport const useFloatingEscape = ({\n  enabled,\n  floating,\n  reference,\n  onEscapeRef,\n  handleClose,\n  returnFocusToReference,\n}: UseFloatingEscapeParams) => {\n  const isFocusWithinFloatingScope = useCallback(\n    (active: Element | null): boolean => {\n      if (!active) return false;\n      if (floating && floating.contains(active)) return true;\n      if (!reference) return false;\n      return reference === active || reference.contains(active);\n    },\n    [floating, reference],\n  );\n\n  useEffect(() => {\n    if (!enabled) return undefined;\n\n    const listener = (event: KeyboardEvent) => {\n      if (event.key !== 'Escape') return;\n      if (!isFocusWithinFloatingScope(document.activeElement)) return;\n\n      const cb = onEscapeRef.current;\n      if (cb) {\n        cb(event);\n      } else {\n        handleClose();\n      }\n      if (returnFocusToReference && reference instanceof HTMLElement) {\n        reference.focus();\n      }\n    };\n\n    document.addEventListener('keydown', listener, true);\n    return () => {\n      document.removeEventListener('keydown', listener, true);\n    };\n  }, [enabled, handleClose, isFocusWithinFloatingScope, onEscapeRef, reference, returnFocusToReference]);\n};\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACAvB,SAAS,aAAa,iBAAwC;AAmBvD,MAAM,oBAAoB,CAAC;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MAA+B;AAC7B,QAAM,6BAA6B;AAAA,IACjC,CAAC,WAAoC;AACnC,UAAI,CAAC,OAAQ,QAAO;AACpB,UAAI,YAAY,SAAS,SAAS,MAAM,EAAG,QAAO;AAClD,UAAI,CAAC,UAAW,QAAO;AACvB,aAAO,cAAc,UAAU,UAAU,SAAS,MAAM;AAAA,IAC1D;AAAA,IACA,CAAC,UAAU,SAAS;AAAA,EACtB;AAEA,YAAU,MAAM;AACd,QAAI,CAAC,QAAS,QAAO;AAErB,UAAM,WAAW,CAAC,UAAyB;AACzC,UAAI,MAAM,QAAQ,SAAU;AAC5B,UAAI,CAAC,2BAA2B,SAAS,aAAa,EAAG;AAEzD,YAAM,KAAK,YAAY;AACvB,UAAI,IAAI;AACN,WAAG,KAAK;AAAA,MACV,OAAO;AACL,oBAAY;AAAA,MACd;AACA,UAAI,0BAA0B,qBAAqB,aAAa;AAC9D,kBAAU,MAAM;AAAA,MAClB;AAAA,IACF;AAEA,aAAS,iBAAiB,WAAW,UAAU,IAAI;AACnD,WAAO,MAAM;AACX,eAAS,oBAAoB,WAAW,UAAU,IAAI;AAAA,IACxD;AAAA,EACF,GAAG,CAAC,SAAS,aAAa,4BAA4B,aAAa,WAAW,sBAAsB,CAAC;AACvG;",
-  "names": []
-}

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

@@ -1,19 +0,0 @@
-import { type MutableRefObject } from 'react';
-interface UseFloatingEscapeParams {
-    enabled: boolean;
-    floating: HTMLElement | null;
-    reference: Element | null;
-    /** Latest-ref of the consumer's onEscape callback. Construct with `useLatestRef(onEscape)`. */
-    onEscapeRef: MutableRefObject<((event: KeyboardEvent) => void) | undefined>;
-    /** Fallback close handler invoked when no `onEscape` is provided. */
-    handleClose: () => void;
-    /** When true, calls `reference.focus()` after the escape close. */
-    returnFocusToReference: boolean;
-}
-/**
- * Listens for `Escape` on the document and dismisses the floating element when focus is
- * within the floating element or on the reference element. Outside that scope the event is
- * ignored — we don't hijack Escape for unrelated UI on the page.
- */
-export declare const useFloatingEscape: ({ enabled, floating, reference, onEscapeRef, handleClose, returnFocusToReference, }: UseFloatingEscapeParams) => void;
-export {};