@vaadin/popover 24.5.0-alpha1 → 24.5.0-alpha10

package/README.md

@@ -43,7 +43,7 @@ import '@vaadin/popover/src/vaadin-popover.js';
 
 ## Contributing
 
-Read the [contributing guide](https://vaadin.com/docs/latest/contributing/overview) to learn about our development process, how to propose bugfixes and improvements, and how to test your changes to Vaadin components.
+Read the [contributing guide](https://vaadin.com/docs/latest/contributing) to learn about our development process, how to propose bugfixes and improvements, and how to test your changes to Vaadin components.
 
 ## License
 

package/lit.d.ts

@@ -0,0 +1 @@
+export * from './src/lit/renderer-directives.js';

package/lit.js

@@ -0,0 +1 @@
+export * from './src/lit/renderer-directives.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/popover",
-  "version": "24.5.0-alpha1",
+  "version": "24.5.0-alpha10",
   "publishConfig": {
     "access": "public"
   },
@@ -20,6 +20,8 @@
   "module": "vaadin-popover.js",
   "type": "module",
   "files": [
+    "lit.d.ts",
+    "lit.js",
     "src",
     "theme",
     "vaadin-*.d.ts",
@@ -35,22 +37,23 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "24.5.0-alpha1",
-    "@vaadin/component-base": "24.5.0-alpha1",
-    "@vaadin/overlay": "24.5.0-alpha1",
-    "@vaadin/vaadin-lumo-styles": "24.5.0-alpha1",
-    "@vaadin/vaadin-material-styles": "24.5.0-alpha1",
-    "@vaadin/vaadin-themable-mixin": "24.5.0-alpha1",
+    "@vaadin/a11y-base": "24.5.0-alpha10",
+    "@vaadin/component-base": "24.5.0-alpha10",
+    "@vaadin/lit-renderer": "24.5.0-alpha10",
+    "@vaadin/overlay": "24.5.0-alpha10",
+    "@vaadin/vaadin-lumo-styles": "24.5.0-alpha10",
+    "@vaadin/vaadin-material-styles": "24.5.0-alpha10",
+    "@vaadin/vaadin-themable-mixin": "24.5.0-alpha10",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.6.0",
-    "sinon": "^13.0.2"
+    "@vaadin/chai-plugins": "24.5.0-alpha10",
+    "@vaadin/testing-helpers": "^1.0.0",
+    "sinon": "^18.0.0"
   },
   "web-types": [
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "57806caac5468532a3b4e3dbdda730cd0fca193a"
+  "gitHead": "6f9c37308031af872a98017bfab4de89aeacda51"
 }

package/src/lit/renderer-directives.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * Copyright (c) 2024 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { DirectiveResult } from 'lit/directive.js';
+import { LitRendererDirective, type LitRendererResult } from '@vaadin/lit-renderer';
+import type { Popover } from '../vaadin-popover.js';
+
+export type PopoverLitRenderer = (popover: Popover) => LitRendererResult;
+
+export class PopoverRendererDirective extends LitRendererDirective<Popover, PopoverLitRenderer> {
+  /**
+   * Adds the renderer callback to the popover.
+   */
+  addRenderer(): void;
+
+  /**
+   * Runs the renderer callback on the popover.
+   */
+  runRenderer(): void;
+
+  /**
+   * Removes the renderer callback from the popover.
+   */
+  removeRenderer(): void;
+}
+
+/**
+ * A Lit directive for populating the content of the `<vaadin-popover-overlay>` element.
+ *
+ * The directive accepts a renderer callback returning a Lit template and assigns it to the popover
+ * via the `renderer` property. The renderer is called once to populate the content when assigned
+ * and whenever a single dependency or an array of dependencies changes.
+ * It is not guaranteed that the renderer will be called immediately (synchronously) in both cases.
+ *
+ * Dependencies can be a single value or an array of values.
+ * Values are checked against previous values with strict equality (`===`),
+ * so the check won't detect nested property changes inside objects or arrays.
+ * When dependencies are provided as an array, each item is checked against the previous value
+ * at the same index with strict equality. Nested arrays are also checked only by strict
+ * equality.
+ *
+ * Example of usage:
+ * ```js
+ * `<vaadin-popover
+ *   ${popoverRenderer((popover) => html`...`)}
+ * ></vaadin-popover>`
+ * ```
+ *
+ * @param renderer the renderer callback that returns a Lit template.
+ * @param dependencies a single dependency or an array of dependencies
+ *                     which trigger a re-render when changed.
+ */
+export declare function popoverRenderer(
+  renderer: PopoverLitRenderer,
+  dependencies?: unknown,
+): DirectiveResult<typeof PopoverRendererDirective>;

package/src/lit/renderer-directives.js

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright (c) 2024 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { directive } from 'lit/directive.js';
+import { LitRendererDirective } from '@vaadin/lit-renderer';
+
+export class PopoverRendererDirective extends LitRendererDirective {
+  /**
+   * Adds the renderer callback to the popover.
+   */
+  addRenderer() {
+    this.element.renderer = (root, popover) => {
+      this.renderRenderer(root, popover);
+    };
+  }
+
+  /**
+   * Runs the renderer callback on the popover.
+   */
+  runRenderer() {
+    this.element.requestContentUpdate();
+  }
+
+  /**
+   * Removes the renderer callback from the popover.
+   */
+  removeRenderer() {
+    this.element.renderer = null;
+  }
+}
+
+/**
+ * A Lit directive for populating the content of the `<vaadin-popover-overlay>` element.
+ *
+ * The directive accepts a renderer callback returning a Lit template and assigns it to the popover
+ * via the `renderer` property. The renderer is called once to populate the content when assigned
+ * and whenever a single dependency or an array of dependencies changes.
+ * It is not guaranteed that the renderer will be called immediately (synchronously) in both cases.
+ *
+ * Dependencies can be a single value or an array of values.
+ * Values are checked against previous values with strict equality (`===`),
+ * so the check won't detect nested property changes inside objects or arrays.
+ * When dependencies are provided as an array, each item is checked against the previous value
+ * at the same index with strict equality. Nested arrays are also checked only by strict
+ * equality.
+ *
+ * Example of usage:
+ * ```js
+ * `<vaadin-popover
+ *   ${popoverRenderer((popover) => html`...`)}
+ * ></vaadin-popover>`
+ * ```
+ *
+ * @param renderer the renderer callback that returns a Lit template.
+ * @param dependencies a single dependency or an array of dependencies
+ *                     which trigger a re-render when changed.
+ */
+export const popoverRenderer = directive(PopoverRendererDirective);

package/src/vaadin-popover-overlay-mixin.js

@@ -59,6 +59,8 @@ export const PopoverOverlayMixin = (superClass) =>
         return;
       }
 
+      this.removeAttribute('arrow-centered');
+
       // Center the overlay horizontally
       if (this.position === 'bottom' || this.position === 'top') {
         const targetRect = this.positionTarget.getBoundingClientRect();
@@ -70,6 +72,8 @@ export const PopoverOverlayMixin = (superClass) =>
           const left = overlayRect.left + offset;
           if (left > 0) {
             this.style.left = `${left}px`;
+            // Center the pointer arrow horizontally
+            this.setAttribute('arrow-centered', '');
           }
         }
 
@@ -77,6 +81,8 @@ export const PopoverOverlayMixin = (superClass) =>
           const right = parseFloat(this.style.right) + offset;
           if (right > 0) {
             this.style.right = `${right}px`;
+            // Center the pointer arrow horizontally
+            this.setAttribute('arrow-centered', '');
           }
         }
       }

package/src/vaadin-popover-overlay.js

@@ -60,10 +60,8 @@ class PopoverOverlay extends PopoverOverlayMixin(DirMixin(ThemableMixin(PolylitM
         [part='overlay']::before {
           position: absolute;
           content: '';
-          top: calc(var(--vaadin-popover-offset-top, 0) * -1);
-          bottom: calc(var(--vaadin-popover-offset-bottom, 0) * -1);
-          inset-inline-start: calc(var(--vaadin-popover-offset-start, 0) * -1);
-          inset-inline-end: calc(var(--vaadin-popover-offset-end, 0) * -1);
+          inset-block: calc(var(--vaadin-popover-offset-top, 0) * -1) calc(var(--vaadin-popover-offset-bottom, 0) * -1);
+          inset-inline: calc(var(--vaadin-popover-offset-start, 0) * -1) calc(var(--vaadin-popover-offset-end, 0) * -1);
           z-index: -1;
           pointer-events: auto;
         }
@@ -82,6 +80,17 @@ class PopoverOverlay extends PopoverOverlayMixin(DirMixin(ThemableMixin(PolylitM
         :host([position^='end'][end-aligned]) [part='overlay'] {
           margin-inline-end: var(--vaadin-popover-offset-end, 0);
         }
+
+        [part='arrow'] {
+          display: none;
+          position: absolute;
+          height: 0;
+          width: 0;
+        }
+
+        :host([theme~='arrow']) [part='arrow'] {
+          display: block;
+        }
       `,
     ];
   }
@@ -91,6 +100,7 @@ class PopoverOverlay extends PopoverOverlayMixin(DirMixin(ThemableMixin(PolylitM
     return html`
       <div id="backdrop" part="backdrop" hidden ?hidden="${!this.withBackdrop}"></div>
       <div part="overlay" id="overlay" tabindex="0">
+        <div part="arrow"></div>
         <div part="content" id="content"><slot></slot></div>
       </div>
     `;

package/src/vaadin-popover-target-mixin.js

@@ -39,6 +39,24 @@ export const PopoverTargetMixin = (superClass) =>
       };
     }
 
+    /** @protected */
+    connectedCallback() {
+      super.connectedCallback();
+
+      if (this.target) {
+        this._addTargetListeners(this.target);
+      }
+    }
+
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
+
+      if (this.target) {
+        this._removeTargetListeners(this.target);
+      }
+    }
+
     /** @private */
     __forChanged(forId) {
       if (forId) {

package/src/vaadin-popover.d.ts

@@ -22,6 +22,8 @@ export type PopoverOpenedChangedEvent = CustomEvent<{ value: boolean }>;
 
 export interface PopoverCustomEventMap {
   'opened-changed': PopoverOpenedChangedEvent;
+
+  closed: Event;
 }
 
 export type PopoverEventMap = HTMLElementEventMap & PopoverCustomEventMap;
@@ -33,11 +35,66 @@ export type PopoverEventMap = HTMLElementEventMap & PopoverCustomEventMap;
  * Unlike `<vaadin-tooltip>`, the popover supports rich content
  * that can be provided by using `renderer` function.
  *
+ * ### Styling
+ *
+ * `<vaadin-popover>` uses `<vaadin-popover-overlay>` internal
+ * themable component as the actual visible overlay.
+ *
+ * See [`<vaadin-overlay>`](#/elements/vaadin-overlay) documentation
+ * for `<vaadin-popover-overlay>` parts.
+ *
+ * In addition to `<vaadin-overlay>` parts, the following parts are available for styling:
+ *
+ * Part name        | Description
+ * -----------------|-------------------------------------------
+ * `arrow`          | Optional arrow pointing to the target when using `theme="arrow"`
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute        | Description
+ * -----------------|----------------------------------------
+ * `position`       | Reflects the `position` property value.
+ *
+ * Note: the `theme` attribute value set on `<vaadin-popover>` is
+ * propagated to the internal `<vaadin-popover-overlay>` component.
+ *
+ * ### Custom CSS Properties
+ *
+ * The following custom CSS properties are available on the `<vaadin-popover>` element:
+ *
+ * Custom CSS property              | Description
+ * ---------------------------------|-------------
+ * `--vaadin-popover-offset-top`    | Used as an offset when the popover is aligned vertically below the target
+ * `--vaadin-popover-offset-bottom` | Used as an offset when the popover is aligned vertically above the target
+ * `--vaadin-popover-offset-start`  | Used as an offset when the popover is aligned horizontally after the target
+ * `--vaadin-popover-offset-end`    | Used as an offset when the popover is aligned horizontally before the target
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
  * @fires {CustomEvent} opened-changed - Fired when the `opened` property changes.
+ * @fires {CustomEvent} closed - Fired when the popover is closed.
  */
 declare class Popover extends PopoverPositionMixin(
   PopoverTargetMixin(OverlayClassMixin(ThemePropertyMixin(ElementMixin(HTMLElement)))),
 ) {
+  /**
+   * Sets the default focus delay to be used by all popover instances,
+   * except for those that have focus delay configured using property.
+   */
+  static setDefaultFocusDelay(focusDelay: number): void;
+
+  /**
+   * Sets the default hide delay to be used by all popover instances,
+   * except for those that have hide delay configured using property.
+   */
+  static setDefaultHideDelay(hideDelay: number): void;
+
+  /**
+   * Sets the default hover delay to be used by all popover instances,
+   * except for those that have hover delay configured using property.
+   */
+  static setDefaultHoverDelay(delay: number): void;
+
   /**
    * String used to label the overlay to screen reader users.
    *
@@ -52,6 +109,12 @@ declare class Popover extends PopoverPositionMixin(
    */
   accessibleNameRef: string | null | undefined;
 
+  /**
+   * When true, the popover content automatically receives focus after
+   * it is opened. Modal popovers use this behavior by default.
+   */
+  autofocus: boolean;
+
   /**
    * Height to be set on the overlay content.
    *
@@ -69,6 +132,9 @@ declare class Popover extends PopoverPositionMixin(
   /**
    * The delay in milliseconds before the popover is opened
    * on focus when the corresponding trigger is used.
+   *
+   * When not specified, the global default (500ms) is used.
+   *
    * @attr {number} focus-delay
    */
   focusDelay: number;
@@ -77,6 +143,9 @@ declare class Popover extends PopoverPositionMixin(
    * The delay in milliseconds before the popover is closed
    * on losing hover, when the corresponding trigger is used.
    * On blur, the popover is closed immediately.
+   *
+   * When not specified, the global default (500ms) is used.
+   *
    * @attr {number} hide-delay
    */
   hideDelay: number;
@@ -84,6 +153,9 @@ declare class Popover extends PopoverPositionMixin(
   /**
    * The delay in milliseconds before the popover is opened
    * on hover when the corresponding trigger is used.
+   *
+   * When not specified, the global default (500ms) is used.
+   *
    * @attr {number} hover-delay
    */
   hoverDelay: number;