@workday/canvas-kit-popup-stack 6.1.3 → 6.2.1

package/ts3.5/dist/es6/lib/PopupStack.d.ts

@@ -32,6 +32,16 @@ export interface PopupStackItem {
  * popups.
  */
 export declare function getValue(index: number, length: number): number;
+interface Stack {
+    items: PopupStackItem[];
+    container?: () => HTMLElement;
+    zIndex: {
+        min: number;
+        max: number;
+        getValue: typeof getValue;
+    };
+    _adapter: Partial<typeof PopupStack>;
+}
 export declare const PopupStack: {
     /**
      * Create a HTMLElement as the container for the popup stack item. The returned element reference
@@ -48,10 +58,11 @@ export declare const PopupStack: {
      */
     add(item: PopupStackItem): void;
     /**
-     * Removes an item from the stack by its `HTMLElement` reference. This should be called when a
-     * popup is "closed" or when the element is removed from the page entirely to ensure proper memory
-     * cleanup. This will not automatically be called when the element is removed from the DOM. Will
-     * reset z-index values of the stack
+     * Removes an item from a stack by its `HTMLElement` reference. This should be called when a popup
+     * is "closed" or when the element is removed from the page entirely to ensure proper memory
+     * cleanup. A popup will be removed from the stack it is a part of. This will not automatically be
+     * called when the element is removed from the DOM. This method will reset z-index values of the
+     * stack.
      */
     remove(element: HTMLElement): void;
     /**
@@ -65,7 +76,7 @@ export declare const PopupStack: {
      * elements in the order of lowest z-index to highest z-index. Some popup behaviors will need to
      * make decisions based on z-index order.
      */
-    getElements(): HTMLElement[];
+    getElements(stackOverride?: Stack | undefined): HTMLElement[];
     /**
      * Bring the element to the top of the stack. This is useful for persistent popups to place them
      * on top of the stack when clicked. If an `owner` was provided to an item when it was added and
@@ -91,6 +102,36 @@ export declare const PopupStack: {
      * is not inside `element`).
      */
     contains(element: HTMLElement, eventTarget: HTMLElement): boolean;
+    /**
+     * Add a new stack context for popups. This method could be called with the same element multiple
+     * times, but should only push a new stack context once. The most common use-case for calling
+     * `pushStackContext` is when entering fullscreen, but multiple fullscreen listeners could be
+     * pushing the same element which is very difficult to ensure only one stack is used. To mitigate,
+     * this method filters out multiple calls to push the same element as a new stack context.
+     */
+    pushStackContext(container: HTMLElement): void;
+    /**
+     * Remove the topmost stack context. The stack context will only be removed if the top stack
+     * context container element matches to guard against accidental remove of other stack contexts
+     * you don't own.
+     */
+    popStackContext(container: HTMLElement): void;
+    /**
+     * Transfer the popup stack item into the current popup stack context.
+     *
+     * An example might be a popup
+     * that is opened and an element goes into fullscreen. The default popup stack context is
+     * `document.body`, but the [Fullscreen
+     * API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API) will only render elements
+     * that are children of the fullscreen element. If the popup isn't transferred to the current
+     * popup stack context, the popup will remain open, but will no longer be rendered. This method
+     * will transfer that popup to the fullscreen element so that it will render. Popups created while
+     * in a fullscreen context that need to be transferred back when fullscreen is exited should also
+     * call this method. While popups may still render when fullscreen is exited, popups will be
+     * members of different popup stack contexts which will cause unspecified results (like the escape
+     * key will choose the wrong popup as the "topmost").
+     */
+    transferToCurrentContext(item: PopupStackItem): void;
 };
 /**
  * Reset all the items in the stack. This should only be used for testing or if the page doesn't
@@ -117,10 +158,11 @@ export declare const createAdapter: (adapter: Partial<{
      */
     add(item: PopupStackItem): void;
     /**
-     * Removes an item from the stack by its `HTMLElement` reference. This should be called when a
-     * popup is "closed" or when the element is removed from the page entirely to ensure proper memory
-     * cleanup. This will not automatically be called when the element is removed from the DOM. Will
-     * reset z-index values of the stack
+     * Removes an item from a stack by its `HTMLElement` reference. This should be called when a popup
+     * is "closed" or when the element is removed from the page entirely to ensure proper memory
+     * cleanup. A popup will be removed from the stack it is a part of. This will not automatically be
+     * called when the element is removed from the DOM. This method will reset z-index values of the
+     * stack.
      */
     remove(element: HTMLElement): void;
     /**
@@ -134,7 +176,7 @@ export declare const createAdapter: (adapter: Partial<{
      * elements in the order of lowest z-index to highest z-index. Some popup behaviors will need to
      * make decisions based on z-index order.
      */
-    getElements(): HTMLElement[];
+    getElements(stackOverride?: Stack | undefined): HTMLElement[];
     /**
      * Bring the element to the top of the stack. This is useful for persistent popups to place them
      * on top of the stack when clicked. If an `owner` was provided to an item when it was added and
@@ -160,5 +202,36 @@ export declare const createAdapter: (adapter: Partial<{
      * is not inside `element`).
      */
     contains(element: HTMLElement, eventTarget: HTMLElement): boolean;
+    /**
+     * Add a new stack context for popups. This method could be called with the same element multiple
+     * times, but should only push a new stack context once. The most common use-case for calling
+     * `pushStackContext` is when entering fullscreen, but multiple fullscreen listeners could be
+     * pushing the same element which is very difficult to ensure only one stack is used. To mitigate,
+     * this method filters out multiple calls to push the same element as a new stack context.
+     */
+    pushStackContext(container: HTMLElement): void;
+    /**
+     * Remove the topmost stack context. The stack context will only be removed if the top stack
+     * context container element matches to guard against accidental remove of other stack contexts
+     * you don't own.
+     */
+    popStackContext(container: HTMLElement): void;
+    /**
+     * Transfer the popup stack item into the current popup stack context.
+     *
+     * An example might be a popup
+     * that is opened and an element goes into fullscreen. The default popup stack context is
+     * `document.body`, but the [Fullscreen
+     * API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API) will only render elements
+     * that are children of the fullscreen element. If the popup isn't transferred to the current
+     * popup stack context, the popup will remain open, but will no longer be rendered. This method
+     * will transfer that popup to the fullscreen element so that it will render. Popups created while
+     * in a fullscreen context that need to be transferred back when fullscreen is exited should also
+     * call this method. While popups may still render when fullscreen is exited, popups will be
+     * members of different popup stack contexts which will cause unspecified results (like the escape
+     * key will choose the wrong popup as the "topmost").
+     */
+    transferToCurrentContext(item: PopupStackItem): void;
 }>) => void;
+export {};
 //# sourceMappingURL=PopupStack.d.ts.map