feat(popover): add pf-popover (#2320)

* feat(pf-popover): pf-popover init

* feat(pf-popover): pfe-popover init; add basic template and props

* chore: remove pf-popover element

* style: copy pf4 styles and template changes

* chore: reorganize

* feat: add essential functionality/styling

* refactor: don't use properties for styling

* chore: clean up

* feat: get arrow positioning from controller

* feat: use new arrow functionality

* fix: implement feedback from office hours

* refactor: undo arrow changes

* docs: add jsdoc

* docs: update README

* chore: clean up

* chore: clean up demo

* refactor: apply suggestions from code review

Co-authored-by: Benny Powers <[email protected]>

* refactor: rename popover element; delete requested files

* revert: rename after main merge

* refactor: migrate to css

* fix: reset lockfile

* fix: rename custom css var

* docs: update example

* docs: add usage snippet

* test: add basic unit test coverage

* docs: add changelog

* fix: demo formatting

* feat: add arrow middleware

* feat: add custom events for show and hide

* feat: use dialog element; add additional props

* chore: clean up

* style: remove unused CSS for arrow placement

* feat: ass string list converter

* fix: use the new converter; move dynamic options into show

* fix: removing arrow from BaseTooltip with FloatingDomController rework

* chore: clean up

* fix: arrow placement with left position

* fix: add visibility hidden on close

* chore: clean up

* test: add event hander cleanup test

* fix: use specific imports

* fix: formatting

Co-authored-by: Benny Powers <[email protected]>

* refactor: render all templates inline

* refactor: set fallback where used

* refactor: set fallback where used

* refactor: enableFlip to noFlip

* refactor: set fallback where used

* docs: add JSDoc to public props and methods

* refactor: manage listeners with set of instances

* fix: the default is flip (opposite side only)

* feat: add alert severity screen reader default text

* feat: add ability to override SR text

* feat: allow no hide on outside click

* feat: disable focus trapping

* chore: clean up

* fix: don't trap focus by default; add toggle

* feat: leverage showModal to trap focus

* revert: focus-trap attribute

* chore: clean up

* docs: tweak disclaimer

* docs: move disclaimer to overview

* docs: update elements/pf-popover/docs/pf-popover.md

* fix: typo

* perf(core): dedupe converter code

* docs: minor pedantry

* refactor: use `visually-hidden` classname

* docs: fixup docs page

* test: fail on a11y audit

* docs: update prop docblocks, slight refactors

* perf: only add one body listener

---------

Co-authored-by: Benny Powers <[email protected]>
Co-authored-by: Brian Ferry <[email protected]>
Co-authored-by: Benny Powers <[email protected]>

Author: 3 people

.changeset/core-string-list-converter.md

@@ -0,0 +1,4 @@
+---
+"@patternfly/pfe-core": minor
+---
+Added `StringListConverter` for managing comma-separated list attributes.

.changeset/pf-popover.md

@@ -0,0 +1,10 @@
+---
+"@patternfly/elements": minor
+---
+✨ Added `<pf-popover>`
+
+```html
+<pf-popover heading="Popover heading" body="Popovers are triggered by click rather than hover." footer="Popover footer">
+  <pf-button>Toggle popover</pf-button>
+</pf-popover>
+```

core/pfe-core/controllers/floating-dom-controller.ts

@@ -11,22 +11,25 @@ import {
   offset as offsetMiddleware,
   shift as shiftMiddleware,
   flip as flipMiddleware,
+  arrow as arrowMiddleware
 } from '@floating-ui/dom';
 
 type Lazy<T> = T | (() => T | null | undefined);
 
 interface FloatingDOMControllerOptions {
   content: Lazy<HTMLElement>;
   invoker?: Lazy<HTMLElement>;
-  arrow?: boolean;
-  flip?: boolean;
+  arrow?: Lazy<HTMLElement>;
   shift?: boolean;
   padding?: number;
+  fallbackPlacements?: Placement[];
 }
 
 interface ShowOptions {
   offset?: Offset;
   placement?: Placement;
+  flip?: boolean;
+  fallbackPlacements?: Placement[];
 }
 
 export type Anchor = '' | 'top' | 'left' | 'bottom' | 'right';
@@ -55,6 +58,11 @@ export class FloatingDOMController implements ReactiveController {
     return typeof content === 'function' ? content() : content;
   }
 
+  get #arrow() {
+    const { arrow } = this.#options;
+    return typeof arrow === 'function' ? arrow() : arrow;
+  }
+
   /** The crosswise alignment of the invoker on which to display the floating DOM */
   get alignment() {
     return this.#alignment ?? 'center';
@@ -93,33 +101,52 @@ export class FloatingDOMController implements ReactiveController {
     host.addController(this);
     this.#options = options as Required<FloatingDOMControllerOptions>;
     this.#options.invoker ??= host;
-    this.#options.arrow ??= false;
-    this.#options.flip ??= true;
     this.#options.shift ??= true;
   }
 
   hostDisconnected() {
     this.#cleanup?.();
   }
 
-  async #update(placement: Placement = 'top', offset?: Offset) {
-    const { flip, padding, shift } = this.#options;
+  async #update(placement: Placement = 'top', offset?: Offset, flip = true, fallbackPlacements?: Placement[]) {
+    const { padding, shift } = this.#options;
 
     const invoker = this.#invoker;
     const content = this.#content;
+    const arrow = this.#arrow;
     if (!invoker || !content) {
       return;
     }
-    const { x, y, placement: _placement } = await computePosition(invoker, content, {
+    const { x, y, placement: _placement, middlewareData } = await computePosition(invoker, content, {
       strategy: 'absolute',
       placement,
       middleware: [
         offsetMiddleware(offset),
         shift && shiftMiddleware({ padding }),
-        flip && flipMiddleware({ padding }),
+        arrow && arrowMiddleware({ element: arrow, padding: arrow.offsetHeight / 2 }),
+        flip && flipMiddleware({ padding, fallbackPlacements }),
       ].filter(Boolean)
     });
 
+    if (arrow) {
+      const { x: arrowX, y: arrowY } = middlewareData.arrow || {};
+
+      const staticSide = {
+        top: 'bottom',
+        right: 'left',
+        bottom: 'top',
+        left: 'right',
+      }[_placement.split('-')[0]] || '';
+
+      Object.assign(arrow.style, {
+        left: arrowX != null ? `${arrowX}px` : '',
+        top: arrowY != null && !['top'].includes(_placement) ? `${arrowY}px` : '',
+        right: '',
+        bottom: '',
+        [staticSide]: `-${arrow.offsetHeight / 2}px`,
+      });
+    }
+
     this.#placement = _placement;
     [this.#anchor, this.#alignment] = (this.#placement.split('-') ?? []) as [Anchor, Alignment];
     this.#styles = {
@@ -129,17 +156,17 @@ export class FloatingDOMController implements ReactiveController {
   }
 
   /** Show the floating DOM */
-  async show({ offset, placement }: ShowOptions = {}) {
+  async show({ offset, placement, flip, fallbackPlacements }: ShowOptions = {}) {
     const invoker = this.#invoker;
     const content = this.#content;
     if (!invoker || !content) {
       return;
     }
     if (!this.#opening) {
       this.#opening = true;
-      const p = this.#update(placement, offset);
+      const p = this.#update(placement, offset, flip, fallbackPlacements);
       this.#cleanup ??= autoUpdate(invoker, content, () =>
-        this.#update(placement, offset));
+        this.#update(placement, offset, flip, fallbackPlacements));
       await p;
       this.#opening = false;
     }

core/pfe-core/core.ts

@@ -29,22 +29,34 @@ export function trackPerformance(preference: boolean | typeof noPref = noPref) {
   return window.PfeConfig.trackPerformance;
 }
 
+function makeConverter<T>(f: (x: string, type?: unknown) => T): ComplexAttributeConverter<null | T[]> {
+  return {
+    fromAttribute(value: string) {
+      if (typeof value !== 'string') {
+        return null;
+      } else {
+        return value.split(',').map(f);
+      }
+    },
+    toAttribute(value: T[]) {
+      return value.join(',');
+    },
+  };
+}
+
 /**
  * A LitElement property converter which represents a list of numbers as a comma separated string
  * @see https://lit.dev/docs/components/properties/#conversion-converter
  */
-export const NumberListConverter: ComplexAttributeConverter<null | number[]> = {
-  fromAttribute(value: string) {
-    if (typeof value !== 'string') {
-      return null;
-    } else {
-      return value.split(',').map(x => x.trim()).map(x => parseInt(x, 10));
-    }
-  },
-  toAttribute(value: number[]) {
-    return value.join(',');
-  },
-};
+export const NumberListConverter =
+  makeConverter(x => parseInt(x?.trim(), 10));
+
+/**
+ * A LitElement property converter which represents a list of strings as a comma separated string
+ * @see https://lit.dev/docs/components/properties/#conversion-converter
+ */
+export const StringListConverter =
+  makeConverter(x => x.trim());
 
 /**
  * A composed, bubbling event for UI interactions

elements/package.json

@@ -54,7 +54,8 @@
     "./pf-tile/pf-tile.js": "./pf-tile/pf-tile.js",
     "./pf-timestamp/pf-timestamp.js": "./pf-timestamp/pf-timestamp.js",
     "./pf-tooltip/BaseTooltip.js": "./pf-tooltip/BaseTooltip.js",
-    "./pf-tooltip/pf-tooltip.js": "./pf-tooltip/pf-tooltip.js"
+    "./pf-tooltip/pf-tooltip.js": "./pf-tooltip/pf-tooltip.js",
+    "./pf-popover/pf-popover.js": "./pf-popover/pf-popover.js"
   },
   "publishConfig": {
     "access": "public",

elements/pf-popover/README.md

@@ -0,0 +1,48 @@
+# Popover
+
+A Popover displays content in a non-modal dialog and adds contextual information or provides resources via text and links.
+
+## Usage
+
+Read more about popovers in the [PatternFly Elements Popover documentation](https://patternflyelements.org/components/popover)
+
+## Installation
+
+Load `<pf-popover>` via CDN:
+
+```html
+<script src="https://jspm.dev/@patternfly/elements/pf-popover/pf-popover.js"></script>
+```
+
+Or, if you are using [NPM](https://npm.im), install it
+
+```bash
+npm install @patternfly/elements
+```
+
+Then once installed, import it to your application:
+
+```js
+import '@patternfly/elements/pf-popover/pf-popover.js';
+```
+
+## Usage
+
+### Basic Popover
+
+```html
+<pf-popover heading="Popover heading"
+            body="Popovers are triggered by click rather than hover."
+            footer="Popover footer">
+  <pf-button>Toggle popover</pf-button>
+</pf-popover>
+```
+
+```html
+<pf-popover>
+  <h3 slot="heading">Popover heading</h3>
+  <div slot="body">Popovers are triggered by click rather than hover.</div>
+  <span slot="footer">Popover footer</span>
+  <pf-button>Toggle popover</pf-button>
+</pf-popover>
+```

elements/pf-popover/demo/demo.css

@@ -0,0 +1,47 @@
+form {
+  padding: 0 2rem;
+  display: flex;
+  flex-flow: row wrap;
+  gap: 8px;
+}
+
+form h2 {
+  width: 100%;
+}
+
+label {
+  display: flex;
+  flex-direction: column;
+}
+
+fieldset label {
+  display: grid;
+  align-content: center;
+  display: contents;
+}
+
+select {
+  display: block;
+  margin-inline-end: auto;
+  flex-basis: 100%;
+}
+
+#position-select {
+  margin: 1rem 0;
+}
+
+#alert-select {
+  margin-bottom: 1rem;
+}
+
+#no-padding pf-popover::part(content) {
+  --pf-c-popover__content--PaddingTop: 0px;
+  --pf-c-popover__content--PaddingRight: 0px;
+  --pf-c-popover__content--PaddingBottom: 0px;
+  --pf-c-popover__content--PaddingLeft: 0px;
+}
+
+#auto-width pf-popover::part(content) {
+  --pf-c-popover--MaxWidth: none;
+  --pf-c-popover--MinWidth: auto;
+}