@workday/canvas-kit-react 7.1.5 → 7.2.0-427-next.2

package/dist/es6/popup/lib/hooks/usePopupCard.d.ts

@@ -1,7 +1,7 @@
 /**
- * Adds the necessary props to a `Card` component. Used by the `Popup.Card` subcomponent.
+ * Adds the necessary props to a {@link PopupCard Popup.Card} subcomponent.
  */
-export declare const usePopupCard: <P extends {}, R>(model: {
+export declare const usePopupCard: import("@workday/canvas-kit-react/common").BehaviorHook<{
     state: {
         stackRef: import("react").RefObject<HTMLDivElement>;
         targetRef: import("react").RefObject<HTMLButtonElement>;
@@ -9,7 +9,7 @@ export declare const usePopupCard: <P extends {}, R>(model: {
         returnFocusRef: import("react").RefObject<any> | undefined;
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../..").Visibility;
+        visibility: "hidden" | "visible";
     };
     events: {
         updatePlacement(data: {
@@ -18,10 +18,8 @@ export declare const usePopupCard: <P extends {}, R>(model: {
         show(event?: Event | import("react").SyntheticEvent<Element, Event> | undefined): void;
         hide(event?: Event | import("react").SyntheticEvent<Element, Event> | undefined): void;
     };
-}, elemProps?: P | undefined, ref?: ((instance: R | null) => void) | import("react").RefObject<R> | null | undefined) => {
+}, {
     role: string;
     'aria-labelledby': string;
-} & P & (R extends HTMLOrSVGElement ? {
-    ref: import("react").Ref<R>;
-} : {});
+}>;
 //# sourceMappingURL=usePopupCard.d.ts.map

package/dist/es6/popup/lib/hooks/usePopupCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePopupCard.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupCard.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;OAKvB,CAAC"}
+{"version":3,"file":"usePopupCard.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupCard.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;EAKvB,CAAC"}

package/dist/es6/popup/lib/hooks/usePopupCard.js

@@ -1,10 +1,9 @@
 import { createElemPropsHook } from '@workday/canvas-kit-react/common';
 import { usePopupModel } from './usePopupModel';
 /**
- * Adds the necessary props to a `Card` component. Used by the `Popup.Card` subcomponent.
+ * Adds the necessary props to a {@link PopupCard Popup.Card} subcomponent.
  */
-export var usePopupCard = createElemPropsHook(usePopupModel)(function (_a) {
-    var state = _a.state;
+export const usePopupCard = createElemPropsHook(usePopupModel)(({ state }) => {
     return {
         role: 'dialog',
         'aria-labelledby': state.id,

package/dist/es6/popup/lib/hooks/usePopupCloseButton.d.ts

@@ -1,8 +1,9 @@
 /**
- * Adds the necessary props to a close button component. Used by the `Popup.CloseButton`
- * subcomponent and `Popup.CloseIcon` subcomponent.
+ * Adds the necessary props to a close button component. Used by the
+ * {@link PopupCloseButton Popup.CloseButton} subcomponent and
+ * {@link PopupCloseIcon Popup.CloseIcon} subcomponent.
  */
-export declare const usePopupCloseButton: <P extends {}, R>(model: {
+export declare const usePopupCloseButton: import("@workday/canvas-kit-react/common").BehaviorHook<{
     state: {
         stackRef: import("react").RefObject<HTMLDivElement>;
         targetRef: import("react").RefObject<HTMLButtonElement>;
@@ -10,7 +11,7 @@ export declare const usePopupCloseButton: <P extends {}, R>(model: {
         returnFocusRef: import("react").RefObject<any> | undefined;
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../..").Visibility;
+        visibility: "hidden" | "visible";
     };
     events: {
         updatePlacement(data: {
@@ -19,9 +20,7 @@ export declare const usePopupCloseButton: <P extends {}, R>(model: {
         show(event?: Event | import("react").SyntheticEvent<Element, Event> | undefined): void;
         hide(event?: Event | import("react").SyntheticEvent<Element, Event> | undefined): void;
     };
-}, elemProps?: P | undefined, ref?: ((instance: R | null) => void) | import("react").RefObject<R> | null | undefined) => {
+}, {
     onClick: (event?: Event | import("react").SyntheticEvent<Element, Event> | undefined) => void;
-} & P & (R extends HTMLOrSVGElement ? {
-    ref: import("react").Ref<R>;
-} : {});
+}>;
 //# sourceMappingURL=usePopupCloseButton.d.ts.map

package/dist/es6/popup/lib/hooks/usePopupCloseButton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePopupCloseButton.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupCloseButton.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;OAI9B,CAAC"}
+{"version":3,"file":"usePopupCloseButton.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupCloseButton.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;EAI9B,CAAC"}

package/dist/es6/popup/lib/hooks/usePopupCloseButton.js

@@ -1,11 +1,11 @@
 import { createElemPropsHook } from '@workday/canvas-kit-react/common';
 import { usePopupModel } from './usePopupModel';
 /**
- * Adds the necessary props to a close button component. Used by the `Popup.CloseButton`
- * subcomponent and `Popup.CloseIcon` subcomponent.
+ * Adds the necessary props to a close button component. Used by the
+ * {@link PopupCloseButton Popup.CloseButton} subcomponent and
+ * {@link PopupCloseIcon Popup.CloseIcon} subcomponent.
  */
-export var usePopupCloseButton = createElemPropsHook(usePopupModel)(function (_a) {
-    var events = _a.events;
+export const usePopupCloseButton = createElemPropsHook(usePopupModel)(({ events }) => {
     return {
         onClick: events.hide,
     };

package/dist/es6/popup/lib/hooks/usePopupHeading.d.ts

@@ -1,7 +1,7 @@
 /**
- * Adds the necessary props to the `Heading` component. Used by the `Popup.Heading` subcomponent.
+ * Adds the necessary props to the {@link PopupHeading Popup.Heading} subcomponent.
  */
-export declare const usePopupHeading: <P extends {}, R>(model: {
+export declare const usePopupHeading: import("@workday/canvas-kit-react/common").BehaviorHook<{
     state: {
         stackRef: import("react").RefObject<HTMLDivElement>;
         targetRef: import("react").RefObject<HTMLButtonElement>;
@@ -9,7 +9,7 @@ export declare const usePopupHeading: <P extends {}, R>(model: {
         returnFocusRef: import("react").RefObject<any> | undefined;
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../..").Visibility;
+        visibility: "hidden" | "visible";
     };
     events: {
         updatePlacement(data: {
@@ -18,9 +18,7 @@ export declare const usePopupHeading: <P extends {}, R>(model: {
         show(event?: Event | import("react").SyntheticEvent<Element, Event> | undefined): void;
         hide(event?: Event | import("react").SyntheticEvent<Element, Event> | undefined): void;
     };
-}, elemProps?: P | undefined, ref?: ((instance: R | null) => void) | import("react").RefObject<R> | null | undefined) => {
+}, {
     id: string;
-} & P & (R extends HTMLOrSVGElement ? {
-    ref: import("react").Ref<R>;
-} : {});
+}>;
 //# sourceMappingURL=usePopupHeading.d.ts.map

package/dist/es6/popup/lib/hooks/usePopupHeading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePopupHeading.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupHeading.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;OAI1B,CAAC"}
+{"version":3,"file":"usePopupHeading.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupHeading.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;EAI1B,CAAC"}

package/dist/es6/popup/lib/hooks/usePopupHeading.js

@@ -1,10 +1,9 @@
 import { createElemPropsHook } from '@workday/canvas-kit-react/common';
 import { usePopupModel } from './usePopupModel';
 /**
- * Adds the necessary props to the `Heading` component. Used by the `Popup.Heading` subcomponent.
+ * Adds the necessary props to the {@link PopupHeading Popup.Heading} subcomponent.
  */
-export var usePopupHeading = createElemPropsHook(usePopupModel)(function (_a) {
-    var state = _a.state;
+export const usePopupHeading = createElemPropsHook(usePopupModel)(({ state }) => {
     return {
         id: state.id,
     };

package/dist/es6/popup/lib/hooks/usePopupModel.d.ts

@@ -12,7 +12,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
      */
     initialFocusRef: React.RefObject<any> | undefined;
     id: string;
-    initialVisibility: import("../../../disclosure").Visibility;
+    initialVisibility: import("@workday/canvas-kit-react/disclosure").Visibility;
 }> & {
     onUpdatePlacement?: ((data: {
         placement: Placement;
@@ -44,7 +44,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     }) => void) | undefined;
     onShow?: ((data: Event | React.SyntheticEvent<Element, Event> | undefined, prevState: {
         /**
@@ -74,7 +74,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     }) => void) | undefined;
     onHide?: ((data: Event | React.SyntheticEvent<Element, Event> | undefined, prevState: {
         /**
@@ -104,7 +104,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     }) => void) | undefined;
 } & {
     shouldUpdatePlacement?: ((data: {
@@ -137,7 +137,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     }) => boolean) | undefined;
     shouldShow?: ((data: Event | React.SyntheticEvent<Element, Event> | undefined, state: {
         /**
@@ -167,7 +167,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     }) => boolean) | undefined;
     shouldHide?: ((data: Event | React.SyntheticEvent<Element, Event> | undefined, state: {
         /**
@@ -197,7 +197,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     }) => boolean) | undefined;
 }) | undefined) => {
     state: {
@@ -228,7 +228,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     };
     events: {
         /**
@@ -244,7 +244,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          * Popup and is used in Popup-related behaviors.
          */
     };
-}) & import("../../../common").ModelExtras<{
+}) & import("@workday/canvas-kit-react/common").ModelExtras<{
     /**
      * Optional reference to an element that should receive focus when a popup is hidden. If left
      * blank, focus will return to the `targetRef`
@@ -256,7 +256,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
      */
     initialFocusRef: React.RefObject<any> | undefined;
     id: string;
-    initialVisibility: import("../../../disclosure").Visibility;
+    initialVisibility: import("@workday/canvas-kit-react/disclosure").Visibility;
 }, {}, {
     /**
      * Reference of the stack item used in the PopupStack. This value will be used in all
@@ -285,7 +285,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
      */
     placement: import("@popperjs/core").Placement;
     id: string;
-    visibility: import("../../../disclosure").Visibility;
+    visibility: "hidden" | "visible";
 }, {
     /**
      * Called whenever a popup placement changes around a target. This is useful for animations that
@@ -328,7 +328,7 @@ export declare const usePopupModel: (<TT_Special_Generic>(config?: (Partial<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     };
     events: {
         /**
@@ -374,7 +374,7 @@ export declare const PopupModelContext: React.Context<{
          */
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../../disclosure").Visibility;
+        visibility: "hidden" | "visible";
     };
     events: {
         /**

package/dist/es6/popup/lib/hooks/usePopupModel.js

@@ -1,78 +1,73 @@
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
 import * as React from 'react';
 import { createModelHook } from '@workday/canvas-kit-react/common';
 import { useDisclosureModel } from '@workday/canvas-kit-react/disclosure';
 // eslint-disable-next-line no-empty-function
-var noop = function () { };
-export var usePopupModel = createModelHook({
+const noop = () => { };
+export const usePopupModel = createModelHook({
     // create enough of a model to use `Popup.Card` without a `Popup` container component.
     defaultContext: { state: {}, events: { show: noop, hide: noop } },
-    defaultConfig: __assign(__assign({}, useDisclosureModel.defaultConfig), { 
+    defaultConfig: {
+        ...useDisclosureModel.defaultConfig,
         /**
          * Optional reference to an element that should receive focus when a popup is hidden. If left
          * blank, focus will return to the `targetRef`
          */
-        returnFocusRef: undefined, 
+        returnFocusRef: undefined,
         /**
          * Optional reference to an element that should receive focus when a popup is shown. If left blank,
          * focus will be moved to the first focusable element inside the popup.
          */
-        initialFocusRef: undefined }),
+        initialFocusRef: undefined,
+    },
     requiredConfig: useDisclosureModel.requiredConfig,
-})(function (config) {
-    var stackRef = React.useRef(null);
-    var targetRef = React.useRef(null);
-    var _a = React.useState('bottom'), placement = _a[0], setPlacement = _a[1];
-    var disclosure = useDisclosureModel(config);
-    var state = __assign(__assign({}, disclosure.state), { 
+})(config => {
+    const stackRef = React.useRef(null);
+    const targetRef = React.useRef(null);
+    const [placement, setPlacement] = React.useState('bottom');
+    const disclosure = useDisclosureModel(config);
+    const state = {
+        ...disclosure.state,
         /**
          * Reference of the stack item used in the PopupStack. This value will be used in all
          * Popup-related behaviors.
          */
-        stackRef: stackRef,
+        stackRef,
         /**
          * Reference of the target element. This will point to the element that triggered the showing of a
          * Popup and is used in Popup-related behaviors.
          */
-        targetRef: targetRef, 
+        targetRef,
         /**
          * Optional reference to an element that should receive focus when a popup is shown. If left blank,
          * focus will be moved to the first focusable element inside the popup.
          */
-        initialFocusRef: config.initialFocusRef, 
+        initialFocusRef: config.initialFocusRef,
         /**
          * Optional reference to an element that should receive focus when a popup is hidden. If left
          * blank, focus will return to the `targetRef`
          */
-        returnFocusRef: config.returnFocusRef, 
+        returnFocusRef: config.returnFocusRef,
         /**
          * The placement chosen by the positioning Popper. This should get set prior to showing the popup
          * content.
          * @default 'bottom'
          */
-        placement: placement });
-    var events = __assign(__assign({}, disclosure.events), { 
+        placement,
+    };
+    const events = {
+        ...disclosure.events,
         /**
          * Called whenever a popup placement changes around a target. This is useful for animations that
          * depend on the placement chosen.
          */
-        updatePlacement: function (data) {
+        updatePlacement(data) {
             setPlacement(data.placement);
-        } });
+        },
+    };
     return {
-        state: state,
-        events: events,
+        state,
+        events,
     };
 });
 // create enough of a model to use `Popup.Card` without a `Popup` container component.
-export var PopupModelContext = usePopupModel.Context;
+export const PopupModelContext = usePopupModel.Context;

package/dist/es6/popup/lib/hooks/usePopupPopper.d.ts

@@ -1,9 +1,10 @@
 import React from 'react';
 import { Placement } from '../Popper';
 /**
- * Hooks a Popper up to a PopupModel
+ * Adds the necessary props to a {@link Popper} component. Used by the
+ * {@link PopupPopper Popup.Popper} subcomponent.
  */
-export declare const usePopupPopper: <P extends {}, R>(model: {
+export declare const usePopupPopper: import("@workday/canvas-kit-react/common").BehaviorHook<{
     state: {
         stackRef: React.RefObject<HTMLDivElement>;
         targetRef: React.RefObject<HTMLButtonElement>;
@@ -11,7 +12,7 @@ export declare const usePopupPopper: <P extends {}, R>(model: {
         returnFocusRef: React.RefObject<any> | undefined;
         placement: import("@popperjs/core").Placement;
         id: string;
-        visibility: import("../../..").Visibility;
+        visibility: "hidden" | "visible";
     };
     events: {
         updatePlacement(data: {
@@ -20,12 +21,10 @@ export declare const usePopupPopper: <P extends {}, R>(model: {
         show(event?: Event | React.SyntheticEvent<Element, Event> | undefined): void;
         hide(event?: Event | React.SyntheticEvent<Element, Event> | undefined): void;
     };
-}, elemProps?: P | undefined, ref?: ((instance: R | null) => void) | React.RefObject<R> | null | undefined) => {
+}, {
     open: boolean;
     anchorElement: React.RefObject<HTMLButtonElement>;
-    ref: (instance: any) => void;
+    ref: (instance: unknown) => void;
     onPlacementChange: (placement: Placement) => void;
-} & P & (R extends HTMLOrSVGElement ? {
-    ref: React.Ref<R>;
-} : {});
+}>;
 //# sourceMappingURL=usePopupPopper.d.ts.map

package/dist/es6/popup/lib/hooks/usePopupPopper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePopupPopper.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupPopper.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAC,SAAS,EAAC,MAAM,WAAW,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;mCAGX,SAAS;;;OAevB,CAAC"}
+{"version":3,"file":"usePopupPopper.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupPopper.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAC,SAAS,EAAC,MAAM,WAAW,CAAC;AAEpC;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;mCAGX,SAAS;EAevB,CAAC"}

package/dist/es6/popup/lib/hooks/usePopupPopper.js

@@ -2,21 +2,21 @@ import { createElemPropsHook, useForkRef } from '@workday/canvas-kit-react/commo
 import { usePopupModel } from './usePopupModel';
 import React from 'react';
 /**
- * Hooks a Popper up to a PopupModel
+ * Adds the necessary props to a {@link Popper} component. Used by the
+ * {@link PopupPopper Popup.Popper} subcomponent.
  */
-export var usePopupPopper = createElemPropsHook(usePopupModel)(function (_a, ref) {
-    var state = _a.state, events = _a.events;
-    var elementRef = useForkRef(ref, state.stackRef);
-    var onPlacementChange = React.useCallback(function (placement) {
+export const usePopupPopper = createElemPropsHook(usePopupModel)(({ state, events }, ref) => {
+    const elementRef = useForkRef(ref, state.stackRef);
+    const onPlacementChange = React.useCallback((placement) => {
         if (placement !== state.placement) {
             // only update if the placement has changed
-            events.updatePlacement({ placement: placement });
+            events.updatePlacement({ placement });
         }
     }, [events, state.placement]);
     return {
         open: state.visibility !== 'hidden',
         anchorElement: state.targetRef,
         ref: elementRef,
-        onPlacementChange: onPlacementChange,
+        onPlacementChange,
     };
 });

package/dist/es6/popup/lib/hooks/usePopupStack.d.ts

@@ -1,37 +1,45 @@
 import React from 'react';
 /**
- * This hook should not be used directly. Use the `Popper` component instead.
+ * **Note:** If you're using {@link Popper}, you do not need to use this hook directly.
  *
- * This hook will add the `stackRef` element to the Popup stack on mount and remove on unmount. If
- * you use `Popper`, the popper `stackRef` is automatically added/removed from the Popup stack. The
- * Popup stack is required for proper z-index values to ensure Popups are rendered correct. It is
+ * This hook will add the `stackRef` element to the {@link PopupStack} on mount and remove on unmount. If
+ * you use `Popper`, the popper `stackRef` is automatically added/removed from the `PopupStack`. The
+ * `PopupStack` is required for proper z-index values to ensure Popups are rendered correct. It is
  * also required for global listeners like click outside or escape key closing a popup. Without the
- * Popup stack, all popups will close rather than only the topmost one.
+ * `PopupStack`, all popups will close rather than only the topmost one.
  *
- * If `forwardRef` is provided, it will be the same as `stackRef`. If `forwardRef` is not provided`,
+ * If `ref` is provided, it will be the same as `stackRef`. If `ref` is not provided`,
  * this hook will create one and return it.
  *
  * This hook should be used by all stacked UIs unless using the `Popper` component.
  *
- * @param forwardRef This ref will be managed by the PopupStack and should not be managed by React. Do
+ * ```tsx
+ * const model = usePopupModel();
+ * usePopupStack(model.state.stackRef, model.state.targetRef);
+ *
+ * // add some popup functionality
+ * useCloseOnOutsideClick(model);
+ * useCloseOnEscape(model);
+ *
+ * return (
+ *   <>
+ *     <button ref={model.state.targetRef}>Open Popup</button>
+ *     {model.state.visibility !== 'hidden'
+ *       ? ReactDOM.createPortal(<div>Popup Contents</div>, model.state.stackRef.current)
+ *       : null}
+ *   </>
+ * );
+ * ```
+ *
+ * @param ref This ref will be managed by the PopupStack and should not be managed by React. Do
  * not apply this stackRef to a React element. Doing so will result in an error. Instead, use this
  * `stackRef` directly with `ReactDOM.createPortal(<YourComponent>, stackRef.current!)`. This is
  * definitely strange for React code, but is necessary for the PopupStack to remain framework
- * agnostic and flexible to integrate with existing popup stack systems. If not provided, this hook
+ * agnostic and flexible to integrate with existing `PopupStack` systems. If not provided, this hook
  * will create one and return that `stackRef` instead.
- *
  * @param target Usually the trigger of a popup. This will fix `bringToTop` and should be provided
  * by all ephemeral-type popups (like Tooltips, Select menus, etc). It will also add in clickOutside
  * detection.
- *
- * @example
- * // must be part of a component life-cycle. Use `Popup.Popper` otherwise.
- * const model = usePopupModel({visibility: 'visible'})
- * usePopupStack(model.state.stackRef)
- *
- * // add some popup functionality
- * useCloseOnOutsideClick(model)
- * useCloseOnEscape(model)
  */
-export declare const usePopupStack: <E extends HTMLElement>(ref?: ((instance: E | null) => void) | React.RefObject<E> | null | undefined, target?: HTMLElement | React.RefObject<HTMLElement> | undefined) => React.RefObject<HTMLElement>;
+export declare const usePopupStack: <E extends HTMLElement>(ref?: React.Ref<E> | undefined, target?: HTMLElement | React.RefObject<HTMLElement> | undefined) => React.RefObject<HTMLElement>;
 //# sourceMappingURL=usePopupStack.d.ts.map

package/dist/es6/popup/lib/hooks/usePopupStack.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePopupStack.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupStack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,aAAa,4KAGvB,MAAM,SAAS,CAAC,WAAW,CA2C7B,CAAC"}
+{"version":3,"file":"usePopupStack.d.ts","sourceRoot":"","sources":["../../../../../popup/lib/hooks/usePopupStack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,aAAa,8HAGvB,MAAM,SAAS,CAAC,WAAW,CA2C7B,CAAC"}

package/dist/es6/popup/lib/hooks/usePopupStack.js

@@ -2,69 +2,77 @@ import React from 'react';
 import { PopupStack } from '@workday/canvas-kit-popup-stack';
 import { useLocalRef, useIsRTL } from '@workday/canvas-kit-react/common';
 /**
- * This hook should not be used directly. Use the `Popper` component instead.
+ * **Note:** If you're using {@link Popper}, you do not need to use this hook directly.
  *
- * This hook will add the `stackRef` element to the Popup stack on mount and remove on unmount. If
- * you use `Popper`, the popper `stackRef` is automatically added/removed from the Popup stack. The
- * Popup stack is required for proper z-index values to ensure Popups are rendered correct. It is
+ * This hook will add the `stackRef` element to the {@link PopupStack} on mount and remove on unmount. If
+ * you use `Popper`, the popper `stackRef` is automatically added/removed from the `PopupStack`. The
+ * `PopupStack` is required for proper z-index values to ensure Popups are rendered correct. It is
  * also required for global listeners like click outside or escape key closing a popup. Without the
- * Popup stack, all popups will close rather than only the topmost one.
+ * `PopupStack`, all popups will close rather than only the topmost one.
  *
- * If `forwardRef` is provided, it will be the same as `stackRef`. If `forwardRef` is not provided`,
+ * If `ref` is provided, it will be the same as `stackRef`. If `ref` is not provided`,
  * this hook will create one and return it.
  *
  * This hook should be used by all stacked UIs unless using the `Popper` component.
  *
- * @param forwardRef This ref will be managed by the PopupStack and should not be managed by React. Do
+ * ```tsx
+ * const model = usePopupModel();
+ * usePopupStack(model.state.stackRef, model.state.targetRef);
+ *
+ * // add some popup functionality
+ * useCloseOnOutsideClick(model);
+ * useCloseOnEscape(model);
+ *
+ * return (
+ *   <>
+ *     <button ref={model.state.targetRef}>Open Popup</button>
+ *     {model.state.visibility !== 'hidden'
+ *       ? ReactDOM.createPortal(<div>Popup Contents</div>, model.state.stackRef.current)
+ *       : null}
+ *   </>
+ * );
+ * ```
+ *
+ * @param ref This ref will be managed by the PopupStack and should not be managed by React. Do
  * not apply this stackRef to a React element. Doing so will result in an error. Instead, use this
  * `stackRef` directly with `ReactDOM.createPortal(<YourComponent>, stackRef.current!)`. This is
  * definitely strange for React code, but is necessary for the PopupStack to remain framework
- * agnostic and flexible to integrate with existing popup stack systems. If not provided, this hook
+ * agnostic and flexible to integrate with existing `PopupStack` systems. If not provided, this hook
  * will create one and return that `stackRef` instead.
- *
  * @param target Usually the trigger of a popup. This will fix `bringToTop` and should be provided
  * by all ephemeral-type popups (like Tooltips, Select menus, etc). It will also add in clickOutside
  * detection.
- *
- * @example
- * // must be part of a component life-cycle. Use `Popup.Popper` otherwise.
- * const model = usePopupModel({visibility: 'visible'})
- * usePopupStack(model.state.stackRef)
- *
- * // add some popup functionality
- * useCloseOnOutsideClick(model)
- * useCloseOnEscape(model)
  */
-export var usePopupStack = function (ref, target) {
-    var _a = useLocalRef(ref), elementRef = _a.elementRef, localRef = _a.localRef;
-    var isRTL = useIsRTL();
+export const usePopupStack = (ref, target) => {
+    const { elementRef, localRef } = useLocalRef(ref);
+    const isRTL = useIsRTL();
     // useState function input ensures we only create a container once.
-    var popupRef = React.useState(function () {
-        var container = PopupStack.createContainer();
+    const [popupRef] = React.useState(() => {
+        const container = PopupStack.createContainer();
         elementRef(container);
         return container;
-    })[0];
+    });
     // We useLayoutEffect to ensure proper timing of registration of the element to the popup stack.
     // Without this, the timing is unpredictable when mixed with other frameworks. Other frameworks
     // should also register as soon as the element is available
-    React.useLayoutEffect(function () {
+    React.useLayoutEffect(() => {
         if (popupRef !== localRef.current) {
-            throw Error("The 'ref' passed to usePopupStack should not be applied to a React element. This will cause a runtime error where the PopupStack and React compete for the element. Instead use ReactDOM.createPortal(<YourComponent />, ref.current)");
+            throw Error(`The 'ref' passed to usePopupStack should not be applied to a React element. This will cause a runtime error where the PopupStack and React compete for the element. Instead use ReactDOM.createPortal(<YourComponent />, ref.current)`);
         }
-        var targetEl = target
+        const targetEl = target
             ? 'current' in target
                 ? target.current || undefined
                 : target
             : undefined;
-        var element = localRef.current;
+        const element = localRef.current;
         PopupStack.add({ element: element, owner: targetEl });
-        return function () {
+        return () => {
             PopupStack.remove(element);
         };
     }, [localRef, target, popupRef]);
     // The direction will properly follow the theme via React context, but portals lose the `dir`
     // hierarchy, so we'll add it back here.
-    React.useLayoutEffect(function () {
+    React.useLayoutEffect(() => {
         var _a, _b;
         if (isRTL) {
             (_a = localRef.current) === null || _a === void 0 ? void 0 : _a.setAttribute('dir', 'rtl');