@elliemae/ds-floating-context 3.61.5-rc.6 → 3.61.5-rc.7

package/dist/esm/react-desc-prop-types.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../scripts/build/transpile/react-shim.js", "../../src/react-desc-prop-types.ts"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable @typescript-eslint/no-empty-interface */\nimport type { DSPropTypesSchema } from '@elliemae/ds-props-helpers';\nimport { PropTypes } from '@elliemae/ds-props-helpers';\nexport declare namespace DSHookFloatingContextT {\n  export interface DefaultProps {\n    withoutPortal: boolean;\n    withoutAnimation: boolean;\n    portalDOMContainer?: HTMLElement;\n    animationDuration: number;\n    placement: PopperPlacementsT;\n    customOffset: [number, number];\n  }\n\n  export interface OptionalProps {\n    placementOrderPreference?: PopperPlacementsT[];\n    onOpen?: () => void;\n    onClose?: () => void;\n    externallyControlledIsOpen?: boolean;\n  }\n  export interface Props extends Partial<DefaultProps>, OptionalProps {}\n\n  export interface InternalProps extends DefaultProps, OptionalProps {}\n\n  export type PopperPlacementsT =\n    | 'top-start'\n    | 'top'\n    | 'top-end'\n    | 'right-start'\n    | 'right'\n    | 'right-end'\n    | 'bottom-end'\n    | 'bottom'\n    | 'bottom-start'\n    | 'left-end'\n    | 'left'\n    | 'left-start';\n}\n\nexport const defaultProps: DSHookFloatingContextT.DefaultProps = {\n  withoutAnimation: false,\n  animationDuration: 300,\n  withoutPortal: false,\n  placement: 'top',\n  customOffset: [0, 12],\n};\n\nexport const DSFloatingContextPropTypes: DSPropTypesSchema<DSHookFloatingContextT.Props> = {\n  withoutPortal: PropTypes.bool\n    .description('If true, the tooltip will not be rendered inside a portal.')\n    .defaultValue(false),\n  withoutAnimation: PropTypes.bool.description('If true, the tooltip will not have an animation.').defaultValue(false),\n  portalDOMContainer: PropTypes.instanceOf(HTMLElement)\n    .description('The DOM element where the tooltip will be rendered.')\n    .defaultValue('the first \"main\" landmark available in the document or the body if no \"main\" is found'),\n  animationDuration: PropTypes.number.description('The duration of the animation in milliseconds.').defaultValue(300),\n  placement: PropTypes.oneOf([\n    'top-start',\n    'top',\n    'top-end',\n    'right-start',\n    'right',\n    'right-end',\n    'bottom-end',\n    'bottom',\n    'bottom-start',\n    'left-end',\n    'left',\n    'left-start',\n  ])\n    .description('The placement of the tooltip.')\n    .defaultValue('top'),\n  customOffset: PropTypes.arrayOf(PropTypes.number)\n    .description('The custom offset of the tooltip.')\n    .defaultValue([12, 12]),\n  placementOrderPreference: PropTypes.oneOfType([\n    PropTypes.tuple([PropTypes.oneOf(['top-start'])]),\n    PropTypes.tuple([PropTypes.oneOf(['top'])]),\n    PropTypes.tuple([PropTypes.oneOf(['top-end'])]),\n    PropTypes.tuple([PropTypes.oneOf(['right-start'])]),\n    PropTypes.tuple([PropTypes.oneOf(['right'])]),\n    PropTypes.tuple([PropTypes.oneOf(['right-end'])]),\n    PropTypes.tuple([PropTypes.oneOf(['bottom-end'])]),\n    PropTypes.tuple([PropTypes.oneOf(['bottom'])]),\n    PropTypes.tuple([PropTypes.oneOf(['bottom-start'])]),\n    PropTypes.tuple([PropTypes.oneOf(['left-end'])]),\n    PropTypes.tuple([PropTypes.oneOf(['left'])]),\n    PropTypes.tuple([PropTypes.oneOf(['left-start'])]),\n  ]).description('The order of the placement preference.'),\n  onOpen: PropTypes.func.description('Callback when the tooltip is opened.'),\n  onClose: PropTypes.func.description('Callback when the tooltip is closed.'),\n  externallyControlledIsOpen: PropTypes.bool.description(\n    'If true, the context open/close state will be controlled externally.',\n  ),\n};\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACEvB,SAAS,iBAAiB;AAoCnB,MAAM,eAAoD;AAAA,EAC/D,kBAAkB;AAAA,EAClB,mBAAmB;AAAA,EACnB,eAAe;AAAA,EACf,WAAW;AAAA,EACX,cAAc,CAAC,GAAG,EAAE;AACtB;AAEO,MAAM,6BAA8E;AAAA,EACzF,eAAe,UAAU,KACtB,YAAY,4DAA4D,EACxE,aAAa,KAAK;AAAA,EACrB,kBAAkB,UAAU,KAAK,YAAY,kDAAkD,EAAE,aAAa,KAAK;AAAA,EACnH,oBAAoB,UAAU,WAAW,WAAW,EACjD,YAAY,qDAAqD,EACjE,aAAa,uFAAuF;AAAA,EACvG,mBAAmB,UAAU,OAAO,YAAY,gDAAgD,EAAE,aAAa,GAAG;AAAA,EAClH,WAAW,UAAU,MAAM;AAAA,IACzB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC,EACE,YAAY,+BAA+B,EAC3C,aAAa,KAAK;AAAA,EACrB,cAAc,UAAU,QAAQ,UAAU,MAAM,EAC7C,YAAY,mCAAmC,EAC/C,aAAa,CAAC,IAAI,EAAE,CAAC;AAAA,EACxB,0BAA0B,UAAU,UAAU;AAAA,IAC5C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;AAAA,IAChD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAAA,IAC1C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;AAAA,IAC9C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;AAAA,IAClD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AAAA,IAC5C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;AAAA,IAChD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;AAAA,IACjD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;AAAA,IAC7C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;AAAA,IACnD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;AAAA,IAC/C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AAAA,IAC3C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;AAAA,EACnD,CAAC,EAAE,YAAY,wCAAwC;AAAA,EACvD,QAAQ,UAAU,KAAK,YAAY,sCAAsC;AAAA,EACzE,SAAS,UAAU,KAAK,YAAY,sCAAsC;AAAA,EAC1E,4BAA4B,UAAU,KAAK;AAAA,IACzC;AAAA,EACF;AACF;",
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable @typescript-eslint/no-empty-interface */\nimport type { DSPropTypesSchema } from '@elliemae/ds-props-helpers';\nimport { PropTypes } from '@elliemae/ds-props-helpers';\nexport declare namespace DSHookFloatingContextT {\n  export interface DefaultProps {\n    withoutPortal: boolean;\n    withoutAnimation: boolean;\n    portalDOMContainer?: HTMLElement;\n    animationDuration: number;\n    placement: PopperPlacementsT;\n    customOffset: [number, number];\n    closeOnEscape: boolean;\n    returnFocusToReference: boolean;\n  }\n\n  export interface OptionalProps {\n    placementOrderPreference?: PopperPlacementsT[];\n    onOpen?: () => void;\n    onClose?: () => void;\n    externallyControlledIsOpen?: boolean;\n    /**\n     * Pre-resolved reference element. When provided, the hook uses this as the\n     * source of truth for positioning and ignores its internal reference state.\n     * Eliminates the need for a follow-up `refs.setReference(...)` effect and\n     * removes the visibility:hidden race that breaks programmatic focus on open.\n     */\n    externalReferenceElement?: Element | null;\n    /**\n     * Called when the user clicks/taps outside both the floating element and\n     * the reference element while the floating is open.\n     */\n    onClickOutside?: (event: MouseEvent | TouchEvent) => void;\n    /**\n     * Called when Escape is pressed while focus is within the floating element.\n     * Only fires when `closeOnEscape` is true.\n     */\n    onEscape?: (event: KeyboardEvent) => void;\n  }\n  export interface Props extends Partial<DefaultProps>, OptionalProps {}\n\n  export interface InternalProps extends DefaultProps, OptionalProps {}\n\n  export type PopperPlacementsT =\n    | 'top-start'\n    | 'top'\n    | 'top-end'\n    | 'right-start'\n    | 'right'\n    | 'right-end'\n    | 'bottom-end'\n    | 'bottom'\n    | 'bottom-start'\n    | 'left-end'\n    | 'left'\n    | 'left-start';\n}\n\nexport const defaultProps: DSHookFloatingContextT.DefaultProps = {\n  withoutAnimation: false,\n  animationDuration: 300,\n  withoutPortal: false,\n  placement: 'top',\n  customOffset: [0, 12],\n  closeOnEscape: false,\n  returnFocusToReference: false,\n};\n\nexport const DSFloatingContextPropTypes: DSPropTypesSchema<DSHookFloatingContextT.Props> = {\n  withoutPortal: PropTypes.bool\n    .description('If true, the tooltip will not be rendered inside a portal.')\n    .defaultValue(false),\n  withoutAnimation: PropTypes.bool.description('If true, the tooltip will not have an animation.').defaultValue(false),\n  portalDOMContainer: PropTypes.instanceOf(HTMLElement)\n    .description('The DOM element where the tooltip will be rendered.')\n    .defaultValue('the first \"main\" landmark available in the document or the body if no \"main\" is found'),\n  animationDuration: PropTypes.number.description('The duration of the animation in milliseconds.').defaultValue(300),\n  placement: PropTypes.oneOf([\n    'top-start',\n    'top',\n    'top-end',\n    'right-start',\n    'right',\n    'right-end',\n    'bottom-end',\n    'bottom',\n    'bottom-start',\n    'left-end',\n    'left',\n    'left-start',\n  ])\n    .description('The placement of the tooltip.')\n    .defaultValue('top'),\n  customOffset: PropTypes.arrayOf(PropTypes.number)\n    .description('The custom offset of the tooltip.')\n    .defaultValue([12, 12]),\n  placementOrderPreference: PropTypes.oneOfType([\n    PropTypes.tuple([PropTypes.oneOf(['top-start'])]),\n    PropTypes.tuple([PropTypes.oneOf(['top'])]),\n    PropTypes.tuple([PropTypes.oneOf(['top-end'])]),\n    PropTypes.tuple([PropTypes.oneOf(['right-start'])]),\n    PropTypes.tuple([PropTypes.oneOf(['right'])]),\n    PropTypes.tuple([PropTypes.oneOf(['right-end'])]),\n    PropTypes.tuple([PropTypes.oneOf(['bottom-end'])]),\n    PropTypes.tuple([PropTypes.oneOf(['bottom'])]),\n    PropTypes.tuple([PropTypes.oneOf(['bottom-start'])]),\n    PropTypes.tuple([PropTypes.oneOf(['left-end'])]),\n    PropTypes.tuple([PropTypes.oneOf(['left'])]),\n    PropTypes.tuple([PropTypes.oneOf(['left-start'])]),\n  ]).description('The order of the placement preference.'),\n  onOpen: PropTypes.func.description('Callback when the tooltip is opened.'),\n  onClose: PropTypes.func.description('Callback when the tooltip is closed.'),\n  externallyControlledIsOpen: PropTypes.bool.description(\n    'If true, the context open/close state will be controlled externally.',\n  ),\n  externalReferenceElement: PropTypes.instanceOf(Element).description(\n    'Pre-resolved reference element. When provided, used as the source of truth for positioning, ' +\n      'avoiding the need for a follow-up refs.setReference() effect and the visibility:hidden race on open.',\n  ),\n  onClickOutside: PropTypes.func.description(\n    'Called on mousedown/touchstart outside both the floating element and the reference element while open.',\n  ),\n  closeOnEscape: PropTypes.bool\n    .description('If true, listens for Escape on the floating element and calls onEscape (or onClose).')\n    .defaultValue(false),\n  onEscape: PropTypes.func.description('Called when Escape is pressed while focus is within the floating element.'),\n  returnFocusToReference: PropTypes.bool\n    .description('If true, returns focus to the reference element after Escape-close.')\n    .defaultValue(false),\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACEvB,SAAS,iBAAiB;AAuDnB,MAAM,eAAoD;AAAA,EAC/D,kBAAkB;AAAA,EAClB,mBAAmB;AAAA,EACnB,eAAe;AAAA,EACf,WAAW;AAAA,EACX,cAAc,CAAC,GAAG,EAAE;AAAA,EACpB,eAAe;AAAA,EACf,wBAAwB;AAC1B;AAEO,MAAM,6BAA8E;AAAA,EACzF,eAAe,UAAU,KACtB,YAAY,4DAA4D,EACxE,aAAa,KAAK;AAAA,EACrB,kBAAkB,UAAU,KAAK,YAAY,kDAAkD,EAAE,aAAa,KAAK;AAAA,EACnH,oBAAoB,UAAU,WAAW,WAAW,EACjD,YAAY,qDAAqD,EACjE,aAAa,uFAAuF;AAAA,EACvG,mBAAmB,UAAU,OAAO,YAAY,gDAAgD,EAAE,aAAa,GAAG;AAAA,EAClH,WAAW,UAAU,MAAM;AAAA,IACzB;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC,EACE,YAAY,+BAA+B,EAC3C,aAAa,KAAK;AAAA,EACrB,cAAc,UAAU,QAAQ,UAAU,MAAM,EAC7C,YAAY,mCAAmC,EAC/C,aAAa,CAAC,IAAI,EAAE,CAAC;AAAA,EACxB,0BAA0B,UAAU,UAAU;AAAA,IAC5C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;AAAA,IAChD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAAA,IAC1C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;AAAA,IAC9C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;AAAA,IAClD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;AAAA,IAC5C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC;AAAA,IAChD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;AAAA,IACjD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;AAAA,IAC7C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;AAAA,IACnD,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;AAAA,IAC/C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AAAA,IAC3C,UAAU,MAAM,CAAC,UAAU,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;AAAA,EACnD,CAAC,EAAE,YAAY,wCAAwC;AAAA,EACvD,QAAQ,UAAU,KAAK,YAAY,sCAAsC;AAAA,EACzE,SAAS,UAAU,KAAK,YAAY,sCAAsC;AAAA,EAC1E,4BAA4B,UAAU,KAAK;AAAA,IACzC;AAAA,EACF;AAAA,EACA,0BAA0B,UAAU,WAAW,OAAO,EAAE;AAAA,IACtD;AAAA,EAEF;AAAA,EACA,gBAAgB,UAAU,KAAK;AAAA,IAC7B;AAAA,EACF;AAAA,EACA,eAAe,UAAU,KACtB,YAAY,sFAAsF,EAClG,aAAa,KAAK;AAAA,EACrB,UAAU,UAAU,KAAK,YAAY,2EAA2E;AAAA,EAChH,wBAAwB,UAAU,KAC/B,YAAY,qEAAqE,EACjF,aAAa,KAAK;AACvB;",
   "names": []
 }

package/dist/esm/typescript-testing/typescript-floating-context-valid.js

@@ -14,7 +14,9 @@ const testCompleteDefaults = {
   animationDuration: 300,
   placement: "top",
   customOffset: [10, 10],
-  portalDOMContainer: document.body
+  portalDOMContainer: document.body,
+  closeOnEscape: false,
+  returnFocusToReference: false
 };
 const testInternalProps = {
   ...testOptionalProps,
@@ -31,6 +33,8 @@ const testExplicitDefinition = {
   placement: "top",
   customOffset: [10, 10],
   portalDOMContainer: document.body,
+  closeOnEscape: false,
+  returnFocusToReference: false,
   ...testOptionalProps
 };
 const testInferedTypeCompatibility = {

package/dist/esm/typescript-testing/typescript-floating-context-valid.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../../scripts/build/transpile/react-shim.js", "../../../src/typescript-testing/typescript-floating-context-valid.tsx"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */\nimport React from 'react';\nimport { FloatingWrapper } from '../index.js';\nimport type { DSHookFloatingContextT } from '../index.js';\n\n// test we expose the namespace and the namespace follows our deliverable conventions\ntype ComponentPropsForApp = DSHookFloatingContextT.Props;\ntype ComponentPropsInternals = DSHookFloatingContextT.InternalProps;\ntype ComponentPropsDefaultProps = DSHookFloatingContextT.DefaultProps;\ntype ComponentPropsOptionalProps = DSHookFloatingContextT.OptionalProps;\n\nconst testOptionalProps: ComponentPropsOptionalProps = {};\n\n// difference Props and InternalProps is that InternalProps has all the default props filled in\n// Props allows for partial defaults\nconst testPartialDefaults: Partial<ComponentPropsDefaultProps> = {\n  withoutAnimation: false,\n  withoutPortal: false,\n  animationDuration: 300,\n};\n\n// InternalProps requires all defaults to be filled in\nconst testCompleteDefaults: Required<ComponentPropsDefaultProps> = {\n  withoutAnimation: false,\n  withoutPortal: false,\n  animationDuration: 300,\n  placement: 'top',\n  customOffset: [10, 10],\n  portalDOMContainer: document.body,\n};\n\nconst testInternalProps: ComponentPropsInternals = {\n  ...testOptionalProps,\n  ...testCompleteDefaults,\n};\n\nconst testInternalPropsAsSyntax = {\n  ...testOptionalProps,\n  ...testCompleteDefaults,\n} as ComponentPropsInternals;\n\n// using the explicit type definition, if there is an error, it will be marked on the key that is wrong\nconst testExplicitDefinition: ComponentPropsForApp = {\n  animationDuration: 300,\n  withoutAnimation: false,\n  withoutPortal: false,\n  placement: 'top',\n  customOffset: [10, 10],\n  portalDOMContainer: document.body,\n  ...testOptionalProps,\n};\n\n// using the \"as\" syntax, if there is an error, it will be marking the whole object as wrong because it is not compatible with the type\nconst testInferedTypeCompatibility = {\n  ...testOptionalProps,\n  ...testPartialDefaults,\n  animationDuration: 300,\n} as ComponentPropsForApp;\n\nconst testDefinitionAsConst = {\n  animationDuration: 300,\n  withoutAnimation: false,\n  withoutPortal: false,\n  placement: 'top',\n  portalDOMContainer: document.body,\n} as const;\n\nconst ExampleUsageComponent = () => (\n  <>\n    {/* works with explicitly casted props, all syntaxes */}\n    <FloatingWrapper\n      {...testExplicitDefinition}\n      innerRef={React.createRef<HTMLDivElement>()}\n      isOpen\n      floatingStyles={{}}\n    >\n      <div>Content</div>\n    </FloatingWrapper>\n    <FloatingWrapper\n      {...testInferedTypeCompatibility}\n      innerRef={React.createRef<HTMLDivElement>()}\n      isOpen\n      floatingStyles={{}}\n    >\n      <div>Content</div>\n    </FloatingWrapper>\n    <FloatingWrapper {...testDefinitionAsConst} innerRef={React.createRef<HTMLDivElement>()} isOpen floatingStyles={{}}>\n      <div>Content</div>\n    </FloatingWrapper>\n    {/* works with inline values */}\n  </>\n);\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACoErB,mBAQI,KARJ;AAnEF,OAAOA,YAAW;AAClB,SAAS,uBAAuB;AAShC,MAAM,oBAAiD,CAAC;AAIxD,MAAM,sBAA2D;AAAA,EAC/D,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,mBAAmB;AACrB;AAGA,MAAM,uBAA6D;AAAA,EACjE,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,mBAAmB;AAAA,EACnB,WAAW;AAAA,EACX,cAAc,CAAC,IAAI,EAAE;AAAA,EACrB,oBAAoB,SAAS;AAC/B;AAEA,MAAM,oBAA6C;AAAA,EACjD,GAAG;AAAA,EACH,GAAG;AACL;AAEA,MAAM,4BAA4B;AAAA,EAChC,GAAG;AAAA,EACH,GAAG;AACL;AAGA,MAAM,yBAA+C;AAAA,EACnD,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,WAAW;AAAA,EACX,cAAc,CAAC,IAAI,EAAE;AAAA,EACrB,oBAAoB,SAAS;AAAA,EAC7B,GAAG;AACL;AAGA,MAAM,+BAA+B;AAAA,EACnC,GAAG;AAAA,EACH,GAAG;AAAA,EACH,mBAAmB;AACrB;AAEA,MAAM,wBAAwB;AAAA,EAC5B,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,WAAW;AAAA,EACX,oBAAoB,SAAS;AAC/B;AAEA,MAAM,wBAAwB,MAC5B,iCAEE;AAAA;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,UAAUA,OAAM,UAA0B;AAAA,MAC1C,QAAM;AAAA,MACN,gBAAgB,CAAC;AAAA,MAEjB,8BAAC,SAAI,qBAAO;AAAA;AAAA,EACd;AAAA,EACA;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,UAAUA,OAAM,UAA0B;AAAA,MAC1C,QAAM;AAAA,MACN,gBAAgB,CAAC;AAAA,MAEjB,8BAAC,SAAI,qBAAO;AAAA;AAAA,EACd;AAAA,EACA,oBAAC,mBAAiB,GAAG,uBAAuB,UAAUA,OAAM,UAA0B,GAAG,QAAM,MAAC,gBAAgB,CAAC,GAC/G,8BAAC,SAAI,qBAAO,GACd;AAAA,GAEF;",
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable @typescript-eslint/no-unused-vars, no-unused-vars */\nimport React from 'react';\nimport { FloatingWrapper } from '../index.js';\nimport type { DSHookFloatingContextT } from '../index.js';\n\n// test we expose the namespace and the namespace follows our deliverable conventions\ntype ComponentPropsForApp = DSHookFloatingContextT.Props;\ntype ComponentPropsInternals = DSHookFloatingContextT.InternalProps;\ntype ComponentPropsDefaultProps = DSHookFloatingContextT.DefaultProps;\ntype ComponentPropsOptionalProps = DSHookFloatingContextT.OptionalProps;\n\nconst testOptionalProps: ComponentPropsOptionalProps = {};\n\n// difference Props and InternalProps is that InternalProps has all the default props filled in\n// Props allows for partial defaults\nconst testPartialDefaults: Partial<ComponentPropsDefaultProps> = {\n  withoutAnimation: false,\n  withoutPortal: false,\n  animationDuration: 300,\n};\n\n// InternalProps requires all defaults to be filled in\nconst testCompleteDefaults: Required<ComponentPropsDefaultProps> = {\n  withoutAnimation: false,\n  withoutPortal: false,\n  animationDuration: 300,\n  placement: 'top',\n  customOffset: [10, 10],\n  portalDOMContainer: document.body,\n  closeOnEscape: false,\n  returnFocusToReference: false,\n};\n\nconst testInternalProps: ComponentPropsInternals = {\n  ...testOptionalProps,\n  ...testCompleteDefaults,\n};\n\nconst testInternalPropsAsSyntax = {\n  ...testOptionalProps,\n  ...testCompleteDefaults,\n} as ComponentPropsInternals;\n\n// using the explicit type definition, if there is an error, it will be marked on the key that is wrong\nconst testExplicitDefinition: ComponentPropsForApp = {\n  animationDuration: 300,\n  withoutAnimation: false,\n  withoutPortal: false,\n  placement: 'top',\n  customOffset: [10, 10],\n  portalDOMContainer: document.body,\n  closeOnEscape: false,\n  returnFocusToReference: false,\n  ...testOptionalProps,\n};\n\n// using the \"as\" syntax, if there is an error, it will be marking the whole object as wrong because it is not compatible with the type\nconst testInferedTypeCompatibility = {\n  ...testOptionalProps,\n  ...testPartialDefaults,\n  animationDuration: 300,\n} as ComponentPropsForApp;\n\nconst testDefinitionAsConst = {\n  animationDuration: 300,\n  withoutAnimation: false,\n  withoutPortal: false,\n  placement: 'top',\n  portalDOMContainer: document.body,\n} as const;\n\nconst ExampleUsageComponent = () => (\n  <>\n    {/* works with explicitly casted props, all syntaxes */}\n    <FloatingWrapper\n      {...testExplicitDefinition}\n      innerRef={React.createRef<HTMLDivElement>()}\n      isOpen\n      floatingStyles={{}}\n    >\n      <div>Content</div>\n    </FloatingWrapper>\n    <FloatingWrapper\n      {...testInferedTypeCompatibility}\n      innerRef={React.createRef<HTMLDivElement>()}\n      isOpen\n      floatingStyles={{}}\n    >\n      <div>Content</div>\n    </FloatingWrapper>\n    <FloatingWrapper {...testDefinitionAsConst} innerRef={React.createRef<HTMLDivElement>()} isOpen floatingStyles={{}}>\n      <div>Content</div>\n    </FloatingWrapper>\n    {/* works with inline values */}\n  </>\n);\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACwErB,mBAQI,KARJ;AAvEF,OAAOA,YAAW;AAClB,SAAS,uBAAuB;AAShC,MAAM,oBAAiD,CAAC;AAIxD,MAAM,sBAA2D;AAAA,EAC/D,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,mBAAmB;AACrB;AAGA,MAAM,uBAA6D;AAAA,EACjE,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,mBAAmB;AAAA,EACnB,WAAW;AAAA,EACX,cAAc,CAAC,IAAI,EAAE;AAAA,EACrB,oBAAoB,SAAS;AAAA,EAC7B,eAAe;AAAA,EACf,wBAAwB;AAC1B;AAEA,MAAM,oBAA6C;AAAA,EACjD,GAAG;AAAA,EACH,GAAG;AACL;AAEA,MAAM,4BAA4B;AAAA,EAChC,GAAG;AAAA,EACH,GAAG;AACL;AAGA,MAAM,yBAA+C;AAAA,EACnD,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,WAAW;AAAA,EACX,cAAc,CAAC,IAAI,EAAE;AAAA,EACrB,oBAAoB,SAAS;AAAA,EAC7B,eAAe;AAAA,EACf,wBAAwB;AAAA,EACxB,GAAG;AACL;AAGA,MAAM,+BAA+B;AAAA,EACnC,GAAG;AAAA,EACH,GAAG;AAAA,EACH,mBAAmB;AACrB;AAEA,MAAM,wBAAwB;AAAA,EAC5B,mBAAmB;AAAA,EACnB,kBAAkB;AAAA,EAClB,eAAe;AAAA,EACf,WAAW;AAAA,EACX,oBAAoB,SAAS;AAC/B;AAEA,MAAM,wBAAwB,MAC5B,iCAEE;AAAA;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,UAAUA,OAAM,UAA0B;AAAA,MAC1C,QAAM;AAAA,MACN,gBAAgB,CAAC;AAAA,MAEjB,8BAAC,SAAI,qBAAO;AAAA;AAAA,EACd;AAAA,EACA;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,UAAUA,OAAM,UAA0B;AAAA,MAC1C,QAAM;AAAA,MACN,gBAAgB,CAAC;AAAA,MAEjB,8BAAC,SAAI,qBAAO;AAAA;AAAA,EACd;AAAA,EACA,oBAAC,mBAAiB,GAAG,uBAAuB,UAAUA,OAAM,UAA0B,GAAG,QAAM,MAAC,gBAAgB,CAAC,GAC/G,8BAAC,SAAI,qBAAO,GACd;AAAA,GAEF;",
   "names": ["React"]
 }

package/dist/esm/useComputedPositionStyles.js

@@ -17,7 +17,8 @@ const useComputedPositionStyles = (config) => {
   const [floatingStyles, setFloatingStyles] = useState({
     position: "absolute",
     zIndex: 3e3,
-    visibility: "hidden",
+    opacity: 0,
+    pointerEvents: "none",
     willChange: "transform"
   });
   const [hasComputedOnce, setHasComputedOnce] = useState(false);
@@ -32,12 +33,11 @@ const useComputedPositionStyles = (config) => {
       customOffset,
       withoutPortal
     });
-    setFloatingStyles((prev) => ({
-      position: "absolute",
-      zIndex: 3e3,
-      ...prev,
-      ...coordsStyle
-    }));
+    const { transform, top, left } = coordsStyle;
+    setFloatingStyles((prev) => {
+      if (prev.transform === transform) return prev;
+      return { position: "absolute", zIndex: 3e3, ...prev, transform, top, left };
+    });
     setArrowStyles({ style: coordsArrow, placement: finalPlacement });
     setHasComputedOnce(true);
   }, [canCompute, reference, floating, placement, placementOrderPreference, customOffset, withoutPortal]);
@@ -49,6 +49,8 @@ const useComputedPositionStyles = (config) => {
     }, debounceMs);
     return d;
   }, [debounceMs]);
+  const mutableDebouncedStyles = useRef(debouncedUpdateStyles);
+  mutableDebouncedStyles.current = debouncedUpdateStyles;
   useLayoutEffect(
     () => () => {
       debouncedUpdateStyles.cancel();
@@ -66,7 +68,8 @@ const useComputedPositionStyles = (config) => {
   const resetVisibilityOnly = useCallback(() => {
     setFloatingStyles((prev) => ({
       ...prev,
-      visibility: "hidden"
+      opacity: 0,
+      pointerEvents: "none"
     }));
   }, []);
   return useMemo(
@@ -76,7 +79,7 @@ const useComputedPositionStyles = (config) => {
       hasComputedOnce,
       updateStyles: forceUpdatePosition,
       debouncedUpdateStyles,
-      mutableUpdateStyles,
+      mutableUpdateStyles: mutableDebouncedStyles,
       resetVisibilityOnly
     }),
     [arrowStyles, floatingStyles, hasComputedOnce, forceUpdatePosition, debouncedUpdateStyles, resetVisibilityOnly]

package/dist/esm/useComputedPositionStyles.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../scripts/build/transpile/react-shim.js", "../../src/useComputedPositionStyles.tsx"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable max-statements */\nimport { useLayoutEffect, useMemo, useRef, useState, useCallback } from 'react';\nimport { debounce } from 'lodash-es';\nimport { type CSSProperties } from 'styled-components';\nimport { computePosition } from './utils/computePosition.js';\nimport type { DSHookFloatingContextT } from './react-desc-prop-types.js';\nimport type { PopoverArrowT } from './parts/PopoverArrow.js';\n\ntype UseComputedPositionStylesT = {\n  /** Prevent computing when closed (optimization + avoids unnecessary frames) */\n  preventComputing?: boolean;\n  reference: Element | null;\n  floating: HTMLElement | null;\n  placement: DSHookFloatingContextT.PopperPlacementsT;\n  placementOrderPreference?: DSHookFloatingContextT.PopperPlacementsT[];\n  customOffset: [number, number];\n  withoutPortal: boolean;\n  /** Debounce ms for scroll/resize/observer events */\n  debounceMs?: number;\n};\n\nexport const useComputedPositionStyles = (config: UseComputedPositionStylesT) => {\n  const {\n    reference,\n    floating,\n    placement,\n    placementOrderPreference,\n    customOffset,\n    withoutPortal,\n    preventComputing = false,\n    debounceMs = 150,\n  } = config;\n\n  const [arrowStyles, setArrowStyles] = useState<PopoverArrowT>({ style: { left: 0 }, placement: 'top' });\n\n  // Important: do not initialize top/left to (0,0); keep hidden until the first computation\n  const [floatingStyles, setFloatingStyles] = useState<CSSProperties>({\n    position: 'absolute',\n    zIndex: 3000,\n    visibility: 'hidden',\n    willChange: 'transform',\n  });\n\n  const [hasComputedOnce, setHasComputedOnce] = useState(false);\n\n  const canCompute = reference !== null && floating !== null && !preventComputing;\n\n  const updateStyles = useCallback(() => {\n    if (!canCompute) return;\n\n    const { coordsStyle, finalPlacement, coordsArrow } = computePosition({\n      reference,\n      floating,\n      placement,\n      placementOrderPreference,\n      customOffset,\n      withoutPortal,\n    });\n\n    // Do not touch visibility here; it is managed outside depending on open/hasComputedOnce\n    setFloatingStyles((prev) => ({\n      position: 'absolute',\n      zIndex: 3000,\n      ...prev,\n      ...coordsStyle,\n    }));\n    setArrowStyles({ style: coordsArrow, placement: finalPlacement });\n    setHasComputedOnce(true);\n  }, [canCompute, reference, floating, placement, placementOrderPreference, customOffset, withoutPortal]);\n\n  // Store latest update function in a ref to keep debounced stable\n  const mutableUpdateStyles = useRef(updateStyles);\n  mutableUpdateStyles.current = updateStyles;\n\n  const debouncedUpdateStyles = useMemo(() => {\n    const d = debounce(() => {\n      mutableUpdateStyles.current();\n    }, debounceMs);\n    return d;\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [debounceMs]);\n\n  // Clean up debounce on unmount\n  useLayoutEffect(\n    () => () => {\n      debouncedUpdateStyles.cancel();\n    },\n    [debouncedUpdateStyles],\n  );\n\n  // Recalculate BEFORE paint when dependencies change\n  useLayoutEffect(() => {\n    if (canCompute) {\n      mutableUpdateStyles.current();\n    }\n  }, [canCompute, reference, floating, placement, placementOrderPreference, customOffset, withoutPortal]);\n\n  const forceUpdatePosition = useCallback(() => {\n    mutableUpdateStyles.current();\n  }, []);\n\n  // Do not reset coordinates when closing; just hide\n  const resetVisibilityOnly = useCallback(() => {\n    setFloatingStyles((prev) => ({\n      ...prev,\n      visibility: 'hidden',\n    }));\n  }, []);\n\n  return useMemo(\n    () => ({\n      arrowStyles,\n      floatingStyles,\n      hasComputedOnce,\n      updateStyles: forceUpdatePosition,\n      debouncedUpdateStyles,\n      mutableUpdateStyles,\n      resetVisibilityOnly,\n    }),\n    [arrowStyles, floatingStyles, hasComputedOnce, forceUpdatePosition, debouncedUpdateStyles, resetVisibilityOnly],\n  );\n};\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACCvB,SAAS,iBAAiB,SAAS,QAAQ,UAAU,mBAAmB;AACxE,SAAS,gBAAgB;AAEzB,SAAS,uBAAuB;AAiBzB,MAAM,4BAA4B,CAAC,WAAuC;AAC/E,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,mBAAmB;AAAA,IACnB,aAAa;AAAA,EACf,IAAI;AAEJ,QAAM,CAAC,aAAa,cAAc,IAAI,SAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,WAAW,MAAM,CAAC;AAGtG,QAAM,CAAC,gBAAgB,iBAAiB,IAAI,SAAwB;AAAA,IAClE,UAAU;AAAA,IACV,QAAQ;AAAA,IACR,YAAY;AAAA,IACZ,YAAY;AAAA,EACd,CAAC;AAED,QAAM,CAAC,iBAAiB,kBAAkB,IAAI,SAAS,KAAK;AAE5D,QAAM,aAAa,cAAc,QAAQ,aAAa,QAAQ,CAAC;AAE/D,QAAM,eAAe,YAAY,MAAM;AACrC,QAAI,CAAC,WAAY;AAEjB,UAAM,EAAE,aAAa,gBAAgB,YAAY,IAAI,gBAAgB;AAAA,MACnE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAGD,sBAAkB,CAAC,UAAU;AAAA,MAC3B,UAAU;AAAA,MACV,QAAQ;AAAA,MACR,GAAG;AAAA,MACH,GAAG;AAAA,IACL,EAAE;AACF,mBAAe,EAAE,OAAO,aAAa,WAAW,eAAe,CAAC;AAChE,uBAAmB,IAAI;AAAA,EACzB,GAAG,CAAC,YAAY,WAAW,UAAU,WAAW,0BAA0B,cAAc,aAAa,CAAC;AAGtG,QAAM,sBAAsB,OAAO,YAAY;AAC/C,sBAAoB,UAAU;AAE9B,QAAM,wBAAwB,QAAQ,MAAM;AAC1C,UAAM,IAAI,SAAS,MAAM;AACvB,0BAAoB,QAAQ;AAAA,IAC9B,GAAG,UAAU;AACb,WAAO;AAAA,EAET,GAAG,CAAC,UAAU,CAAC;AAGf;AAAA,IACE,MAAM,MAAM;AACV,4BAAsB,OAAO;AAAA,IAC/B;AAAA,IACA,CAAC,qBAAqB;AAAA,EACxB;AAGA,kBAAgB,MAAM;AACpB,QAAI,YAAY;AACd,0BAAoB,QAAQ;AAAA,IAC9B;AAAA,EACF,GAAG,CAAC,YAAY,WAAW,UAAU,WAAW,0BAA0B,cAAc,aAAa,CAAC;AAEtG,QAAM,sBAAsB,YAAY,MAAM;AAC5C,wBAAoB,QAAQ;AAAA,EAC9B,GAAG,CAAC,CAAC;AAGL,QAAM,sBAAsB,YAAY,MAAM;AAC5C,sBAAkB,CAAC,UAAU;AAAA,MAC3B,GAAG;AAAA,MACH,YAAY;AAAA,IACd,EAAE;AAAA,EACJ,GAAG,CAAC,CAAC;AAEL,SAAO;AAAA,IACL,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA,cAAc;AAAA,MACd;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA,CAAC,aAAa,gBAAgB,iBAAiB,qBAAqB,uBAAuB,mBAAmB;AAAA,EAChH;AACF;",
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable max-statements */\nimport { useLayoutEffect, useMemo, useRef, useState, useCallback } from 'react';\nimport { debounce } from 'lodash-es';\nimport { type CSSProperties } from 'styled-components';\nimport { computePosition } from './utils/computePosition.js';\nimport type { DSHookFloatingContextT } from './react-desc-prop-types.js';\nimport type { PopoverArrowT } from './parts/PopoverArrow.js';\n\ntype UseComputedPositionStylesT = {\n  /** Prevent computing when closed (optimization + avoids unnecessary frames) */\n  preventComputing?: boolean;\n  reference: Element | null;\n  floating: HTMLElement | null;\n  placement: DSHookFloatingContextT.PopperPlacementsT;\n  placementOrderPreference?: DSHookFloatingContextT.PopperPlacementsT[];\n  customOffset: [number, number];\n  withoutPortal: boolean;\n  /** Debounce ms for scroll/resize/observer events */\n  debounceMs?: number;\n};\n\nexport const useComputedPositionStyles = (config: UseComputedPositionStylesT) => {\n  const {\n    reference,\n    floating,\n    placement,\n    placementOrderPreference,\n    customOffset,\n    withoutPortal,\n    preventComputing = false,\n    debounceMs = 150,\n  } = config;\n\n  const [arrowStyles, setArrowStyles] = useState<PopoverArrowT>({ style: { left: 0 }, placement: 'top' });\n\n  // Initial state: invisible (opacity:0) but FOCUSABLE.\n  // We intentionally use opacity instead of visibility:hidden \u2014 `visibility:hidden` blocks\n  // programmatic focus on descendants (including React's `autoFocus` attribute on inputs),\n  // which causes a race on first-open: the floating content's autoFocus fires before the\n  // position-computation useLayoutEffect can flip visibility to `visible`, so the focus\n  // silently no-ops. Opacity:0 keeps the element invisible while letting `.focus()` work.\n  // pointer-events:none prevents accidental clicks on the still-unpositioned (0,0) area.\n  const [floatingStyles, setFloatingStyles] = useState<CSSProperties>({\n    position: 'absolute',\n    zIndex: 3000,\n    opacity: 0,\n    pointerEvents: 'none',\n    willChange: 'transform',\n  });\n\n  const [hasComputedOnce, setHasComputedOnce] = useState(false);\n\n  const canCompute = reference !== null && floating !== null && !preventComputing;\n\n  const updateStyles = useCallback(() => {\n    if (!canCompute) return;\n\n    const { coordsStyle, finalPlacement, coordsArrow } = computePosition({\n      reference,\n      floating,\n      placement,\n      placementOrderPreference,\n      customOffset,\n      withoutPortal,\n    });\n    // INTENTIONAL explicit destructure \u2014 do NOT replace with `...coordsStyle`.\n    //\n    // PUI-18470 is a ghost bug: an infinite ResizeObserver \u2192 setState \u2192 re-render loop\n    // that only triggers at specific viewport pixel combinations (\"magic pixel\") and is\n    // nearly impossible to reproduce consistently across machines. It took a synthetic\n    // Playwright ResizeObserver-intercept test to surface it at all.\n    //\n    // Part of the fix is the bail-out below (`prev.transform === transform`): if the\n    // computed position hasn't changed we return the same state reference, preventing a\n    // re-render and breaking the loop. That bail-out only works if we know exactly which\n    // properties coordsStyle contributes. Spreading `...coordsStyle` hides that contract:\n    // if computePosition ever extends coordsStyle with a new property, the bail-out\n    // silently becomes incomplete and the loop can re-emerge with no obvious cause.\n    //\n    // Keeping the destructure explicit forces any future change to computePosition's\n    // coordsStyle contract to be a conscious, visible decision here \u2014 not a silent pass-through.\n    const { transform, top, left } = coordsStyle;\n\n    // Do not touch visibility here; it is managed outside depending on open/hasComputedOnce\n    setFloatingStyles((prev) => {\n      if (prev.transform === transform) return prev;\n      return { position: 'absolute', zIndex: 3000, ...prev, transform, top, left };\n    });\n    setArrowStyles({ style: coordsArrow, placement: finalPlacement });\n    setHasComputedOnce(true);\n  }, [canCompute, reference, floating, placement, placementOrderPreference, customOffset, withoutPortal]);\n\n  // Store latest update function in a ref to keep debounced stable\n  const mutableUpdateStyles = useRef(updateStyles);\n  mutableUpdateStyles.current = updateStyles;\n\n  const debouncedUpdateStyles = useMemo(() => {\n    const d = debounce(() => {\n      mutableUpdateStyles.current();\n    }, debounceMs);\n    return d;\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [debounceMs]);\n\n  const mutableDebouncedStyles = useRef(debouncedUpdateStyles);\n  mutableDebouncedStyles.current = debouncedUpdateStyles;\n\n  // Clean up debounce on unmount\n  useLayoutEffect(\n    () => () => {\n      debouncedUpdateStyles.cancel();\n    },\n    [debouncedUpdateStyles],\n  );\n\n  // Recalculate BEFORE paint when dependencies change\n  useLayoutEffect(() => {\n    if (canCompute) {\n      mutableUpdateStyles.current();\n    }\n  }, [canCompute, reference, floating, placement, placementOrderPreference, customOffset, withoutPortal]);\n\n  const forceUpdatePosition = useCallback(() => {\n    mutableUpdateStyles.current();\n  }, []);\n\n  // Do not reset coordinates when closing; just hide via opacity (keeps element focusable\n  // if anything inside needs to remain focusable during animations).\n  const resetVisibilityOnly = useCallback(() => {\n    setFloatingStyles((prev) => ({\n      ...prev,\n      opacity: 0,\n      pointerEvents: 'none',\n    }));\n  }, []);\n\n  return useMemo(\n    () => ({\n      arrowStyles,\n      floatingStyles,\n      hasComputedOnce,\n      updateStyles: forceUpdatePosition,\n      debouncedUpdateStyles,\n      mutableUpdateStyles: mutableDebouncedStyles,\n      resetVisibilityOnly,\n    }),\n    [arrowStyles, floatingStyles, hasComputedOnce, forceUpdatePosition, debouncedUpdateStyles, resetVisibilityOnly],\n  );\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACCvB,SAAS,iBAAiB,SAAS,QAAQ,UAAU,mBAAmB;AACxE,SAAS,gBAAgB;AAEzB,SAAS,uBAAuB;AAiBzB,MAAM,4BAA4B,CAAC,WAAuC;AAC/E,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,mBAAmB;AAAA,IACnB,aAAa;AAAA,EACf,IAAI;AAEJ,QAAM,CAAC,aAAa,cAAc,IAAI,SAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,WAAW,MAAM,CAAC;AAStG,QAAM,CAAC,gBAAgB,iBAAiB,IAAI,SAAwB;AAAA,IAClE,UAAU;AAAA,IACV,QAAQ;AAAA,IACR,SAAS;AAAA,IACT,eAAe;AAAA,IACf,YAAY;AAAA,EACd,CAAC;AAED,QAAM,CAAC,iBAAiB,kBAAkB,IAAI,SAAS,KAAK;AAE5D,QAAM,aAAa,cAAc,QAAQ,aAAa,QAAQ,CAAC;AAE/D,QAAM,eAAe,YAAY,MAAM;AACrC,QAAI,CAAC,WAAY;AAEjB,UAAM,EAAE,aAAa,gBAAgB,YAAY,IAAI,gBAAgB;AAAA,MACnE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF,CAAC;AAiBD,UAAM,EAAE,WAAW,KAAK,KAAK,IAAI;AAGjC,sBAAkB,CAAC,SAAS;AAC1B,UAAI,KAAK,cAAc,UAAW,QAAO;AACzC,aAAO,EAAE,UAAU,YAAY,QAAQ,KAAM,GAAG,MAAM,WAAW,KAAK,KAAK;AAAA,IAC7E,CAAC;AACD,mBAAe,EAAE,OAAO,aAAa,WAAW,eAAe,CAAC;AAChE,uBAAmB,IAAI;AAAA,EACzB,GAAG,CAAC,YAAY,WAAW,UAAU,WAAW,0BAA0B,cAAc,aAAa,CAAC;AAGtG,QAAM,sBAAsB,OAAO,YAAY;AAC/C,sBAAoB,UAAU;AAE9B,QAAM,wBAAwB,QAAQ,MAAM;AAC1C,UAAM,IAAI,SAAS,MAAM;AACvB,0BAAoB,QAAQ;AAAA,IAC9B,GAAG,UAAU;AACb,WAAO;AAAA,EAET,GAAG,CAAC,UAAU,CAAC;AAEf,QAAM,yBAAyB,OAAO,qBAAqB;AAC3D,yBAAuB,UAAU;AAGjC;AAAA,IACE,MAAM,MAAM;AACV,4BAAsB,OAAO;AAAA,IAC/B;AAAA,IACA,CAAC,qBAAqB;AAAA,EACxB;AAGA,kBAAgB,MAAM;AACpB,QAAI,YAAY;AACd,0BAAoB,QAAQ;AAAA,IAC9B;AAAA,EACF,GAAG,CAAC,YAAY,WAAW,UAAU,WAAW,0BAA0B,cAAc,aAAa,CAAC;AAEtG,QAAM,sBAAsB,YAAY,MAAM;AAC5C,wBAAoB,QAAQ;AAAA,EAC9B,GAAG,CAAC,CAAC;AAIL,QAAM,sBAAsB,YAAY,MAAM;AAC5C,sBAAkB,CAAC,UAAU;AAAA,MAC3B,GAAG;AAAA,MACH,SAAS;AAAA,MACT,eAAe;AAAA,IACjB,EAAE;AAAA,EACJ,GAAG,CAAC,CAAC;AAEL,SAAO;AAAA,IACL,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA,cAAc;AAAA,MACd;AAAA,MACA,qBAAqB;AAAA,MACrB;AAAA,IACF;AAAA,IACA,CAAC,aAAa,gBAAgB,iBAAiB,qBAAqB,uBAAuB,mBAAmB;AAAA,EAChH;AACF;",
   "names": []
 }

package/dist/esm/utils/computePosition.js

@@ -51,8 +51,8 @@ const computePosition = (props) => {
     y += window.scrollY;
   } else {
     const op = getOffsetParentData(floating);
-    x = x - op.left + op.scrollLeft;
-    y = y - op.top + op.scrollTop;
+    x = x + clippingRect.left - op.left + op.scrollLeft;
+    y = y + clippingRect.top - op.top + op.scrollTop;
   }
   ({ x, y } = applyShift(x, y, overflows));
   const coordsArrow = getArrowOffsetDynamic({

package/dist/esm/utils/computePosition.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../../scripts/build/transpile/react-shim.js", "../../../src/utils/computePosition.ts"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable max-lines */\n/* eslint-disable no-nested-ternary */\n/* eslint-disable complexity */\n/* eslint-disable max-statements */\n/* eslint-disable @typescript-eslint/no-use-before-define */\n/* eslint-disable max-params */\n/* eslint-disable @typescript-eslint/no-unsafe-assignment */\n/* eslint-disable arrow-body-style */\nimport type { DSHookFloatingContextT } from '../react-desc-prop-types.js';\nimport { getExpandedFallbackPlacements } from './getExpandedFallbackPlacements.js';\nimport { getArrowOffsetDynamic } from './getArrowOffset.js';\nimport { detectOverflow } from './detectOverflow.js';\nimport {\n  applyShift,\n  adjustForFixedParent,\n  expandWithVariations,\n  fits,\n  getClippingParent,\n  getOverflowScore,\n  getOffsetParentData,\n  getViewportRect,\n  type RectLike,\n  type OverflowOffsets,\n} from './floatingPositioning.js';\n\ninterface ComputePositionProps {\n  reference: Element;\n  floating: HTMLElement;\n  placement: DSHookFloatingContextT.PopperPlacementsT;\n  placementOrderPreference?: DSHookFloatingContextT.PopperPlacementsT[];\n  customOffset: [number, number];\n  withoutPortal: boolean;\n}\n\nexport const computePosition = (props: ComputePositionProps) => {\n  const { reference, floating, placement, placementOrderPreference, customOffset, withoutPortal } = props;\n\n  // When WITHOUT portal: only apply fixed-parent offsets (absolute parents scroll and must NOT be treated as fixed)\n  const parentOffsets = withoutPortal ? adjustForFixedParent(reference) : { top: 0, left: 0 };\n\n  const referenceRect = reference.getBoundingClientRect();\n  const floatingRect = floating.getBoundingClientRect();\n\n  const fallbackPlacements = placementOrderPreference || getExpandedFallbackPlacements(placement);\n\n  const placements = expandWithVariations(\n    [placement].concat(fallbackPlacements as DSHookFloatingContextT.PopperPlacementsT[]),\n  );\n\n  // Boundary selection:\n  // - Portal => viewport (inset by body padding for Storybook)\n  // - No portal => nearest clipping/scroll container (fallback viewport rect)\n  const clippingParent = withoutPortal ? getClippingParent(reference) : null;\n  const clippingRect: RectLike = clippingParent ? clippingParent.getBoundingClientRect() : getViewportRect();\n\n  // Best-fit selection:\n  // 1) choose first placement that fully fits\n  // 2) otherwise choose placement with smallest max overflow, tie-break by total overflow\n  let bestPlacement = placement;\n  let bestOverflows: OverflowOffsets | null = null;\n  let bestScore = { total: Number.POSITIVE_INFINITY, maxSide: Number.POSITIVE_INFINITY };\n\n  for (let i = 0; i < placements.length; i += 1) {\n    const currentPlacement = placements[i];\n\n    const overflows = detectOverflow(referenceRect, floatingRect, currentPlacement, customOffset, clippingRect);\n\n    if (fits(overflows)) {\n      bestPlacement = currentPlacement;\n      bestOverflows = overflows;\n      break;\n    }\n\n    const score = getOverflowScore(overflows);\n\n    const isBetter =\n      score.maxSide < bestScore.maxSide || (score.maxSide === bestScore.maxSide && score.total < bestScore.total);\n\n    if (isBetter) {\n      bestPlacement = currentPlacement;\n      bestOverflows = overflows;\n      bestScore = score;\n    }\n  }\n\n  const finalPlacement = bestPlacement;\n\n  const overflows =\n    bestOverflows ?? detectOverflow(referenceRect, floatingRect, finalPlacement, customOffset, clippingRect);\n\n  // Convert overflow -> coordinates.\n  // detectOverflow uses viewport/clipping-rect coordinates.\n  //\n  // - If tooltip is rendered IN A PORTAL (withoutPortal === false) and is positioned with `position: absolute`,\n  //   convert viewport coords to page coords by adding window.scrollX/Y.\n  //\n  // - If tooltip is rendered WITHOUT portal, convert viewport coords to offsetParent coords\n  //   (subtract offsetParent rect, add its scroll).\n  let x = -overflows.left - parentOffsets.left;\n  let y = -overflows.top - parentOffsets.top;\n\n  if (!withoutPortal) {\n    x += window.scrollX;\n    y += window.scrollY;\n  } else {\n    const op = getOffsetParentData(floating);\n    x = x - op.left + op.scrollLeft;\n    y = y - op.top + op.scrollTop;\n  }\n\n  // Always shift back inside boundary\n  ({ x, y } = applyShift(x, y, overflows));\n\n  const coordsArrow = getArrowOffsetDynamic({\n    placement: finalPlacement,\n    referenceRect,\n    floatingRect,\n    x,\n    y,\n    withoutPortal,\n    parentOffsets,\n    floatingEl: floating,\n    arrowPadding: 12,\n  });\n\n  return {\n    coordsStyle: {\n      transform: `translate3d(${Math.round(x)}px, ${Math.round(y)}px, 0)`,\n      top: 0,\n      left: 0,\n    },\n    finalPlacement,\n    coordsArrow,\n  };\n};\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACSvB,SAAS,qCAAqC;AAC9C,SAAS,6BAA6B;AACtC,SAAS,sBAAsB;AAC/B;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AAWA,MAAM,kBAAkB,CAAC,UAAgC;AAC9D,QAAM,EAAE,WAAW,UAAU,WAAW,0BAA0B,cAAc,cAAc,IAAI;AAGlG,QAAM,gBAAgB,gBAAgB,qBAAqB,SAAS,IAAI,EAAE,KAAK,GAAG,MAAM,EAAE;AAE1F,QAAM,gBAAgB,UAAU,sBAAsB;AACtD,QAAM,eAAe,SAAS,sBAAsB;AAEpD,QAAM,qBAAqB,4BAA4B,8BAA8B,SAAS;AAE9F,QAAM,aAAa;AAAA,IACjB,CAAC,SAAS,EAAE,OAAO,kBAAgE;AAAA,EACrF;AAKA,QAAM,iBAAiB,gBAAgB,kBAAkB,SAAS,IAAI;AACtE,QAAM,eAAyB,iBAAiB,eAAe,sBAAsB,IAAI,gBAAgB;AAKzG,MAAI,gBAAgB;AACpB,MAAI,gBAAwC;AAC5C,MAAI,YAAY,EAAE,OAAO,OAAO,mBAAmB,SAAS,OAAO,kBAAkB;AAErF,WAAS,IAAI,GAAG,IAAI,WAAW,QAAQ,KAAK,GAAG;AAC7C,UAAM,mBAAmB,WAAW,CAAC;AAErC,UAAMA,aAAY,eAAe,eAAe,cAAc,kBAAkB,cAAc,YAAY;AAE1G,QAAI,KAAKA,UAAS,GAAG;AACnB,sBAAgB;AAChB,sBAAgBA;AAChB;AAAA,IACF;AAEA,UAAM,QAAQ,iBAAiBA,UAAS;AAExC,UAAM,WACJ,MAAM,UAAU,UAAU,WAAY,MAAM,YAAY,UAAU,WAAW,MAAM,QAAQ,UAAU;AAEvG,QAAI,UAAU;AACZ,sBAAgB;AAChB,sBAAgBA;AAChB,kBAAY;AAAA,IACd;AAAA,EACF;AAEA,QAAM,iBAAiB;AAEvB,QAAM,YACJ,iBAAiB,eAAe,eAAe,cAAc,gBAAgB,cAAc,YAAY;AAUzG,MAAI,IAAI,CAAC,UAAU,OAAO,cAAc;AACxC,MAAI,IAAI,CAAC,UAAU,MAAM,cAAc;AAEvC,MAAI,CAAC,eAAe;AAClB,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd,OAAO;AACL,UAAM,KAAK,oBAAoB,QAAQ;AACvC,QAAI,IAAI,GAAG,OAAO,GAAG;AACrB,QAAI,IAAI,GAAG,MAAM,GAAG;AAAA,EACtB;AAGA,GAAC,EAAE,GAAG,EAAE,IAAI,WAAW,GAAG,GAAG,SAAS;AAEtC,QAAM,cAAc,sBAAsB;AAAA,IACxC,WAAW;AAAA,IACX;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,YAAY;AAAA,IACZ,cAAc;AAAA,EAChB,CAAC;AAED,SAAO;AAAA,IACL,aAAa;AAAA,MACX,WAAW,eAAe,KAAK,MAAM,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC;AAAA,MAC3D,KAAK;AAAA,MACL,MAAM;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;",
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable max-lines */\n/* eslint-disable no-nested-ternary */\n/* eslint-disable complexity */\n/* eslint-disable max-statements */\n/* eslint-disable @typescript-eslint/no-use-before-define */\n/* eslint-disable max-params */\n/* eslint-disable @typescript-eslint/no-unsafe-assignment */\n/* eslint-disable arrow-body-style */\nimport type { DSHookFloatingContextT } from '../react-desc-prop-types.js';\nimport { getExpandedFallbackPlacements } from './getExpandedFallbackPlacements.js';\nimport { getArrowOffsetDynamic } from './getArrowOffset.js';\nimport { detectOverflow } from './detectOverflow.js';\nimport {\n  applyShift,\n  adjustForFixedParent,\n  expandWithVariations,\n  fits,\n  getClippingParent,\n  getOverflowScore,\n  getOffsetParentData,\n  getViewportRect,\n  type RectLike,\n  type OverflowOffsets,\n} from './floatingPositioning.js';\n\ninterface ComputePositionProps {\n  reference: Element;\n  floating: HTMLElement;\n  placement: DSHookFloatingContextT.PopperPlacementsT;\n  placementOrderPreference?: DSHookFloatingContextT.PopperPlacementsT[];\n  customOffset: [number, number];\n  withoutPortal: boolean;\n}\n\nexport const computePosition = (props: ComputePositionProps) => {\n  const { reference, floating, placement, placementOrderPreference, customOffset, withoutPortal } = props;\n\n  // When WITHOUT portal: only apply fixed-parent offsets (absolute parents scroll and must NOT be treated as fixed)\n  const parentOffsets = withoutPortal ? adjustForFixedParent(reference) : { top: 0, left: 0 };\n\n  const referenceRect = reference.getBoundingClientRect();\n  const floatingRect = floating.getBoundingClientRect();\n\n  const fallbackPlacements = placementOrderPreference || getExpandedFallbackPlacements(placement);\n\n  const placements = expandWithVariations(\n    [placement].concat(fallbackPlacements as DSHookFloatingContextT.PopperPlacementsT[]),\n  );\n\n  // Boundary selection:\n  // - Portal => viewport (inset by body padding for Storybook)\n  // - No portal => nearest clipping/scroll container (fallback viewport rect)\n  const clippingParent = withoutPortal ? getClippingParent(reference) : null;\n  const clippingRect: RectLike = clippingParent ? clippingParent.getBoundingClientRect() : getViewportRect();\n\n  // Best-fit selection:\n  // 1) choose first placement that fully fits\n  // 2) otherwise choose placement with smallest max overflow, tie-break by total overflow\n  let bestPlacement = placement;\n  let bestOverflows: OverflowOffsets | null = null;\n  let bestScore = { total: Number.POSITIVE_INFINITY, maxSide: Number.POSITIVE_INFINITY };\n\n  for (let i = 0; i < placements.length; i += 1) {\n    const currentPlacement = placements[i];\n\n    const overflows = detectOverflow(referenceRect, floatingRect, currentPlacement, customOffset, clippingRect);\n\n    if (fits(overflows)) {\n      bestPlacement = currentPlacement;\n      bestOverflows = overflows;\n      break;\n    }\n\n    const score = getOverflowScore(overflows);\n\n    const isBetter =\n      score.maxSide < bestScore.maxSide || (score.maxSide === bestScore.maxSide && score.total < bestScore.total);\n\n    if (isBetter) {\n      bestPlacement = currentPlacement;\n      bestOverflows = overflows;\n      bestScore = score;\n    }\n  }\n\n  const finalPlacement = bestPlacement;\n\n  const overflows =\n    bestOverflows ?? detectOverflow(referenceRect, floatingRect, finalPlacement, customOffset, clippingRect);\n\n  // Convert overflow -> coordinates.\n  // detectOverflow uses viewport/clipping-rect coordinates.\n  //\n  // - If tooltip is rendered IN A PORTAL (withoutPortal === false) and is positioned with `position: absolute`,\n  //   convert viewport coords to page coords by adding window.scrollX/Y.\n  //\n  // - If tooltip is rendered WITHOUT portal, convert viewport coords to offsetParent coords\n  //   (subtract offsetParent rect, add its scroll).\n  let x = -overflows.left - parentOffsets.left;\n  let y = -overflows.top - parentOffsets.top;\n\n  if (!withoutPortal) {\n    x += window.scrollX;\n    y += window.scrollY;\n  } else {\n    // clippingRect.top/left may be non-zero (e.g. a scroll container below the viewport top).\n    // The overflow values already subtracted it; add it back so we convert pure viewport coords\n    // to offset-parent-relative coords: viewportCoord - offsetParent.top + offsetParent.scrollTop\n    const op = getOffsetParentData(floating);\n    x = x + clippingRect.left - op.left + op.scrollLeft;\n    y = y + clippingRect.top - op.top + op.scrollTop;\n  }\n\n  // Always shift back inside boundary\n  ({ x, y } = applyShift(x, y, overflows));\n\n  const coordsArrow = getArrowOffsetDynamic({\n    placement: finalPlacement,\n    referenceRect,\n    floatingRect,\n    x,\n    y,\n    withoutPortal,\n    parentOffsets,\n    floatingEl: floating,\n    arrowPadding: 12,\n  });\n\n  return {\n    coordsStyle: {\n      transform: `translate3d(${Math.round(x)}px, ${Math.round(y)}px, 0)`,\n      top: 0,\n      left: 0,\n    },\n    finalPlacement,\n    coordsArrow,\n  };\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACSvB,SAAS,qCAAqC;AAC9C,SAAS,6BAA6B;AACtC,SAAS,sBAAsB;AAC/B;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AAWA,MAAM,kBAAkB,CAAC,UAAgC;AAC9D,QAAM,EAAE,WAAW,UAAU,WAAW,0BAA0B,cAAc,cAAc,IAAI;AAGlG,QAAM,gBAAgB,gBAAgB,qBAAqB,SAAS,IAAI,EAAE,KAAK,GAAG,MAAM,EAAE;AAE1F,QAAM,gBAAgB,UAAU,sBAAsB;AACtD,QAAM,eAAe,SAAS,sBAAsB;AAEpD,QAAM,qBAAqB,4BAA4B,8BAA8B,SAAS;AAE9F,QAAM,aAAa;AAAA,IACjB,CAAC,SAAS,EAAE,OAAO,kBAAgE;AAAA,EACrF;AAKA,QAAM,iBAAiB,gBAAgB,kBAAkB,SAAS,IAAI;AACtE,QAAM,eAAyB,iBAAiB,eAAe,sBAAsB,IAAI,gBAAgB;AAKzG,MAAI,gBAAgB;AACpB,MAAI,gBAAwC;AAC5C,MAAI,YAAY,EAAE,OAAO,OAAO,mBAAmB,SAAS,OAAO,kBAAkB;AAErF,WAAS,IAAI,GAAG,IAAI,WAAW,QAAQ,KAAK,GAAG;AAC7C,UAAM,mBAAmB,WAAW,CAAC;AAErC,UAAMA,aAAY,eAAe,eAAe,cAAc,kBAAkB,cAAc,YAAY;AAE1G,QAAI,KAAKA,UAAS,GAAG;AACnB,sBAAgB;AAChB,sBAAgBA;AAChB;AAAA,IACF;AAEA,UAAM,QAAQ,iBAAiBA,UAAS;AAExC,UAAM,WACJ,MAAM,UAAU,UAAU,WAAY,MAAM,YAAY,UAAU,WAAW,MAAM,QAAQ,UAAU;AAEvG,QAAI,UAAU;AACZ,sBAAgB;AAChB,sBAAgBA;AAChB,kBAAY;AAAA,IACd;AAAA,EACF;AAEA,QAAM,iBAAiB;AAEvB,QAAM,YACJ,iBAAiB,eAAe,eAAe,cAAc,gBAAgB,cAAc,YAAY;AAUzG,MAAI,IAAI,CAAC,UAAU,OAAO,cAAc;AACxC,MAAI,IAAI,CAAC,UAAU,MAAM,cAAc;AAEvC,MAAI,CAAC,eAAe;AAClB,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd,OAAO;AAIL,UAAM,KAAK,oBAAoB,QAAQ;AACvC,QAAI,IAAI,aAAa,OAAO,GAAG,OAAO,GAAG;AACzC,QAAI,IAAI,aAAa,MAAM,GAAG,MAAM,GAAG;AAAA,EACzC;AAGA,GAAC,EAAE,GAAG,EAAE,IAAI,WAAW,GAAG,GAAG,SAAS;AAEtC,QAAM,cAAc,sBAAsB;AAAA,IACxC,WAAW;AAAA,IACX;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,YAAY;AAAA,IACZ,cAAc;AAAA,EAChB,CAAC;AAED,SAAO;AAAA,IACL,aAAa;AAAA,MACX,WAAW,eAAe,KAAK,MAAM,CAAC,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC;AAAA,MAC3D,KAAK;AAAA,MACL,MAAM;AAAA,IACR;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;",
   "names": ["overflows"]
 }

package/dist/types/DSFloatingContext.d.ts

@@ -3,7 +3,7 @@ import type { DSHookFloatingContextT } from './react-desc-prop-types.js';
 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;
@@ -25,7 +25,7 @@ declare const useFloatingContext: {
             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 {
+    enabled: boolean;
+    floating: HTMLElement | null;
+    reference: 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.
+     */
+    callbackRef: 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: ({ enabled, floating, reference, callbackRef, }: UseFloatingClickOutsideParams) => void;
+export {};

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

@@ -0,0 +1,19 @@
+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 {};

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

@@ -0,0 +1,11 @@
+interface UseFloatingResizeObserverParams {
+    enabled: boolean;
+    floating: 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: ({ enabled, floating, 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/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) => {
+    referenceElement: Element | null;
+    setReferenceElement: (el: Element | null) => void;
+};
+export {};

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

@@ -7,12 +7,31 @@ export declare namespace DSHookFloatingContextT {
         animationDuration: number;
         placement: PopperPlacementsT;
         customOffset: [number, number];
+        closeOnEscape: boolean;
+        returnFocusToReference: boolean;
     }
     interface OptionalProps {
         placementOrderPreference?: PopperPlacementsT[];
         onOpen?: () => void;
         onClose?: () => 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;
+        /**
+         * 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 focus is within the floating element.
+         * Only fires when `closeOnEscape` is true.
+         */
+        onEscape?: (event: KeyboardEvent) => void;
     }
     interface Props extends Partial<DefaultProps>, OptionalProps {
     }

package/dist/types/useComputedPositionStyles.d.ts

@@ -19,7 +19,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/package.json

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