DSS-491 - optimize overlay

libs/core/.storybook/preview-head.html

@@ -3,3 +3,11 @@
 <script nomodule src="/pine-core/index.esm.js"></script>
 
 <link rel="stylesheet" href="/pine-core/pine-core.css" />
+
+<style>
+  .docs-story div[scale] {
+    /* This is needed to prevent the storybook canvases from cropping
+    components meant to overflow */
+    transform: none !important;
+  }
+</style>

libs/core/package.json

@@ -55,6 +55,8 @@
     "test.watch": "stencil test --spec --e2e --watchAll --coverage"
   },
   "dependencies": {
+    "@floating-ui/dom": "^1.5.3",
+    "@floating-ui/core": "^1.5.2",
     "@pine-ds/icons": "^3.4.0",
     "@stencil/core": "^4.8.1",
     "sortablejs": "^1.15.0"

libs/core/src/components.d.ts

@@ -5,7 +5,9 @@
  * It contains typing information for all components that exist in this project.
  */
 import { HTMLStencilElement, JSXBase } from "@stencil/core/internal";
+import { OverlayPlacementType } from "./utils/types";
 import { TextareaChangeEventDetail } from "./components/pds-textarea/textarea-interface";
+export { OverlayPlacementType } from "./utils/types";
 export { TextareaChangeEventDetail } from "./components/pds-textarea/textarea-interface";
 export namespace Components {
     interface PdsAvatar {
@@ -310,6 +312,52 @@ export namespace Components {
          */
         "variant": 'inline' | 'plain';
     }
+    interface PdsPopover {
+        /**
+          * A unique identifier used for the underlying component id attribute.
+         */
+        "componentId": string;
+        /**
+          * Determines whether or not the popover has an arrow
+          * @defaultValue false
+         */
+        "hasArrow"?: boolean;
+        /**
+          * Hides the popover by disabling the opened property
+         */
+        "hidePdsPopover": () => Promise<void>;
+        /**
+          * Determines how the popover is positioned relative to the trigger element. By default, the popover will use `absolute` positioning, which allows the popover to scroll with the page. Setting this to `fixed` handles most used. However, if the trigger element is within a container that has `overflow: hidden` set, the popover will not be able to escape the container and get clipped. In this case, you can set the `hoisted` property to `true` to use `fixed` positioning instead. Be aware that this is less performant, as it requires recalculating the popover position on scroll. Only use this option if you need it.
+          * @defaultValue false
+         */
+        "hoisted"?: boolean;
+        /**
+          * Sets the offset distance(in pixels) between the popover and the trigger element
+         */
+        "offset"?: number;
+        /**
+          * Determines whether or not the popover is visible
+          * @defaultValue false
+         */
+        "opened": boolean;
+        /**
+          * Sets the padding(in pixels) of the popover content element
+         */
+        "padding"?: number;
+        /**
+          * Determines the preferred position of the popover
+          * @defaultValue "right"
+         */
+        "placement": OverlayPlacementType;
+        /**
+          * Shows the popover by enabling the opened property
+         */
+        "showPdsPopover": () => Promise<void>;
+        /**
+          * Toggles the popover visibility on click
+         */
+        "togglePdsPopover": () => Promise<void>;
+    }
     interface PdsProgress {
         /**
           * Determines whether or not progress is animated.
@@ -618,32 +666,34 @@ export namespace Components {
           * Hides the tooltip by disabling the opened property
          */
         "hideTooltip": () => Promise<void>;
+        /**
+          * Determines how the popover is positioned relative to the trigger element. By default, the popover will use `absolute` positioning, which allows the popover to scroll with the page. Setting this to `fixed` handles most used. However, if the trigger element is within a container that has `overflow: hidden` set, the popover will not be able to escape the container and get clipped. In this case, you can set the `hoisted` property to `true` to use `fixed` positioning instead. Be aware that this is less performant, as it requires recalculating the popover position on scroll. Only use this option if you need it.
+          * @defaultValue false
+         */
+        "hoisted"?: boolean;
         /**
           * Enable this option when using the content slot
           * @defaultValue false
          */
         "htmlContent": boolean;
+        /**
+          * Sets the offset distance(in pixels) between the popover and the trigger element
+         */
+        "offset"?: number;
         /**
           * Determines whether or not the tooltip is visible
           * @defaultValue false
          */
         "opened": boolean;
+        /**
+          * Sets the padding(in pixels) of the popover content element
+         */
+        "padding"?: number;
         /**
           * Determines the preferred position of the tooltip
           * @defaultValue "right"
          */
-        "placement": 'top'
-    | 'top-start'
-    | 'top-end'
-    | 'right'
-    | 'right-start'
-    | 'right-end'
-    | 'bottom'
-    | 'bottom-start'
-    | 'bottom-end'
-    | 'left'
-    | 'left-start'
-    | 'left-end';
+        "placement": OverlayPlacementType;
         /**
           * Shows the tooltip by enabling the opened property
          */
@@ -666,6 +716,10 @@ export interface PdsInputCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLPdsInputElement;
 }
+export interface PdsPopoverCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLPdsPopoverElement;
+}
 export interface PdsRadioCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLPdsRadioElement;
@@ -797,6 +851,24 @@ declare global {
         prototype: HTMLPdsLinkElement;
         new (): HTMLPdsLinkElement;
     };
+    interface HTMLPdsPopoverElementEventMap {
+        "pdsPopoverHide": any;
+        "pdsPopoverShow": any;
+    }
+    interface HTMLPdsPopoverElement extends Components.PdsPopover, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLPdsPopoverElementEventMap>(type: K, listener: (this: HTMLPdsPopoverElement, ev: PdsPopoverCustomEvent<HTMLPdsPopoverElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLPdsPopoverElementEventMap>(type: K, listener: (this: HTMLPdsPopoverElement, ev: PdsPopoverCustomEvent<HTMLPdsPopoverElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLPdsPopoverElement: {
+        prototype: HTMLPdsPopoverElement;
+        new (): HTMLPdsPopoverElement;
+    };
     interface HTMLPdsProgressElement extends Components.PdsProgress, HTMLStencilElement {
     }
     var HTMLPdsProgressElement: {
@@ -992,6 +1064,7 @@ declare global {
         "pds-image": HTMLPdsImageElement;
         "pds-input": HTMLPdsInputElement;
         "pds-link": HTMLPdsLinkElement;
+        "pds-popover": HTMLPdsPopoverElement;
         "pds-progress": HTMLPdsProgressElement;
         "pds-radio": HTMLPdsRadioElement;
         "pds-sortable": HTMLPdsSortableElement;
@@ -1329,6 +1402,48 @@ declare namespace LocalJSX {
          */
         "variant"?: 'inline' | 'plain';
     }
+    interface PdsPopover {
+        /**
+          * A unique identifier used for the underlying component id attribute.
+         */
+        "componentId"?: string;
+        /**
+          * Determines whether or not the popover has an arrow
+          * @defaultValue false
+         */
+        "hasArrow"?: boolean;
+        /**
+          * Determines how the popover is positioned relative to the trigger element. By default, the popover will use `absolute` positioning, which allows the popover to scroll with the page. Setting this to `fixed` handles most used. However, if the trigger element is within a container that has `overflow: hidden` set, the popover will not be able to escape the container and get clipped. In this case, you can set the `hoisted` property to `true` to use `fixed` positioning instead. Be aware that this is less performant, as it requires recalculating the popover position on scroll. Only use this option if you need it.
+          * @defaultValue false
+         */
+        "hoisted"?: boolean;
+        /**
+          * Sets the offset distance(in pixels) between the popover and the trigger element
+         */
+        "offset"?: number;
+        /**
+          * Emitted after a popover is closed
+         */
+        "onPdsPopoverHide"?: (event: PdsPopoverCustomEvent<any>) => void;
+        /**
+          * Emitted after a popover is shown
+         */
+        "onPdsPopoverShow"?: (event: PdsPopoverCustomEvent<any>) => void;
+        /**
+          * Determines whether or not the popover is visible
+          * @defaultValue false
+         */
+        "opened"?: boolean;
+        /**
+          * Sets the padding(in pixels) of the popover content element
+         */
+        "padding"?: number;
+        /**
+          * Determines the preferred position of the popover
+          * @defaultValue "right"
+         */
+        "placement"?: OverlayPlacementType;
+    }
     interface PdsProgress {
         /**
           * Determines whether or not progress is animated.
@@ -1658,11 +1773,20 @@ declare namespace LocalJSX {
           * @defaultValue true
          */
         "hasArrow"?: boolean;
+        /**
+          * Determines how the popover is positioned relative to the trigger element. By default, the popover will use `absolute` positioning, which allows the popover to scroll with the page. Setting this to `fixed` handles most used. However, if the trigger element is within a container that has `overflow: hidden` set, the popover will not be able to escape the container and get clipped. In this case, you can set the `hoisted` property to `true` to use `fixed` positioning instead. Be aware that this is less performant, as it requires recalculating the popover position on scroll. Only use this option if you need it.
+          * @defaultValue false
+         */
+        "hoisted"?: boolean;
         /**
           * Enable this option when using the content slot
           * @defaultValue false
          */
         "htmlContent"?: boolean;
+        /**
+          * Sets the offset distance(in pixels) between the popover and the trigger element
+         */
+        "offset"?: number;
         /**
           * Emitted after a tooltip is closed
          */
@@ -1676,22 +1800,15 @@ declare namespace LocalJSX {
           * @defaultValue false
          */
         "opened"?: boolean;
+        /**
+          * Sets the padding(in pixels) of the popover content element
+         */
+        "padding"?: number;
         /**
           * Determines the preferred position of the tooltip
           * @defaultValue "right"
          */
-        "placement"?: 'top'
-    | 'top-start'
-    | 'top-end'
-    | 'right'
-    | 'right-start'
-    | 'right-end'
-    | 'bottom'
-    | 'bottom-start'
-    | 'bottom-end'
-    | 'left'
-    | 'left-start'
-    | 'left-end';
+        "placement"?: OverlayPlacementType;
     }
     interface IntrinsicElements {
         "pds-avatar": PdsAvatar;
@@ -1703,6 +1820,7 @@ declare namespace LocalJSX {
         "pds-image": PdsImage;
         "pds-input": PdsInput;
         "pds-link": PdsLink;
+        "pds-popover": PdsPopover;
         "pds-progress": PdsProgress;
         "pds-radio": PdsRadio;
         "pds-sortable": PdsSortable;
@@ -1734,6 +1852,7 @@ declare module "@stencil/core" {
             "pds-image": LocalJSX.PdsImage & JSXBase.HTMLAttributes<HTMLPdsImageElement>;
             "pds-input": LocalJSX.PdsInput & JSXBase.HTMLAttributes<HTMLPdsInputElement>;
             "pds-link": LocalJSX.PdsLink & JSXBase.HTMLAttributes<HTMLPdsLinkElement>;
+            "pds-popover": LocalJSX.PdsPopover & JSXBase.HTMLAttributes<HTMLPdsPopoverElement>;
             "pds-progress": LocalJSX.PdsProgress & JSXBase.HTMLAttributes<HTMLPdsProgressElement>;
             "pds-radio": LocalJSX.PdsRadio & JSXBase.HTMLAttributes<HTMLPdsRadioElement>;
             "pds-sortable": LocalJSX.PdsSortable & JSXBase.HTMLAttributes<HTMLPdsSortableElement>;

libs/core/src/components/pds-popover/pds-popover.scss

@@ -0,0 +1,72 @@
+:host {
+  --popover-background-color: var(--pine-color-base-white);
+  --popover-color: var(--pine-color-neutral-charcoal-400);
+  --popover-arrow-color: var(--popover-background-color);
+
+  display: inline-block;
+  position: relative;
+
+  &::part(content) {
+    background-color: var(--popover-background-color);
+    color: var(--popover-color);
+  }
+}
+
+div {
+  // These custom props are not reachable
+  --box-shadow: var(--pine-box-shadow-md);
+  --arrow-size: 8px;
+  --arrow-offset: 14px;
+
+  --overlay-border-radius: var(--pine-border-radius-md);
+  --overlay-font-size: var(--pine-font-size-body-sm);
+  --overlay-line-height: var(--pine-line-height-sm);
+  --overlay-width: 240px;
+  --overlay-padding: var(--pine-spacing-xs) 12px;
+
+  --arrow-pointing-down: var(--arrow-size) var(--arrow-size) 0;
+  --arrow-pointing-to-the-right: var(--arrow-size) 0 var(--arrow-size) var(--arrow-size);
+  --arrow-pointing-to-the-left: var(--arrow-size) var(--arrow-size) var(--arrow-size) 0;
+  --arrow-pointing-up: 0 var(--arrow-size) var(--arrow-size);
+}
+
+.pds-popover__content {
+  border-radius: var(--overlay-border-radius);
+  box-shadow: var(--box-shadow);
+  color: var(--popover-content-color);
+  display: none;
+  font-size: var(--overlay-font-size);
+  line-height: var(--overlay-line-height);
+  max-width: var(--overlay-width); 
+  min-width: var(--overlay-width);
+  padding: var(--overlay-padding);
+  position: absolute;
+  /* add three width variations needed due to position values */
+  width: var(--overlay-width);
+
+  .pds-popover--hoisted & {
+    position: fixed;
+  }
+
+  .pds-popover--is-open & {
+    display: block;
+    z-index: 1000;
+  }
+
+  :host(.pds-popover--has-html-content) & {
+    width: auto;
+  }
+}
+
+.pds-popover__trigger {
+  display: inline-block;
+}
+
+.pds-popover__arrow {
+  background-color: var(--popover-arrow-color);
+  height: var(--arrow-size);
+  position: absolute;
+  transform: rotate(45deg);
+  width: var(--arrow-size);
+  z-index: -1;
+}