@vaadin/tooltip 24.2.3 → 24.3.0-alpha10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/tooltip",
-  "version": "24.2.3",
+  "version": "24.3.0-alpha10",
   "publishConfig": {
     "access": "public"
   },
@@ -21,6 +21,9 @@
   "type": "module",
   "files": [
     "src",
+    "!src/vaadin-lit-tooltip-overlay.js",
+    "!src/vaadin-lit-tooltip.d.ts",
+    "!src/vaadin-lit-tooltip.js",
     "theme",
     "vaadin-*.d.ts",
     "vaadin-*.js",
@@ -34,22 +37,23 @@
     "web-component"
   ],
   "dependencies": {
+    "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/a11y-base": "~24.2.3",
-    "@vaadin/component-base": "~24.2.3",
-    "@vaadin/overlay": "~24.2.3",
-    "@vaadin/vaadin-lumo-styles": "~24.2.3",
-    "@vaadin/vaadin-material-styles": "~24.2.3",
-    "@vaadin/vaadin-themable-mixin": "~24.2.3"
+    "@vaadin/a11y-base": "24.3.0-alpha10",
+    "@vaadin/component-base": "24.3.0-alpha10",
+    "@vaadin/overlay": "24.3.0-alpha10",
+    "@vaadin/vaadin-lumo-styles": "24.3.0-alpha10",
+    "@vaadin/vaadin-material-styles": "24.3.0-alpha10",
+    "@vaadin/vaadin-themable-mixin": "24.3.0-alpha10"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.5.0",
+    "@vaadin/testing-helpers": "^0.6.0",
     "sinon": "^13.0.2"
   },
   "web-types": [
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "72e557e765e72559e9c6a525e257d185ad186dc5"
+  "gitHead": "0271523d93fe5df0425ff64206886614f3c6f401"
 }

package/src/vaadin-tooltip-mixin.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * Copyright (c) 2022 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+import type { OverlayClassMixinClass } from '@vaadin/component-base/src/overlay-class-mixin.js';
+
+export type TooltipPosition =
+  | 'bottom-end'
+  | 'bottom-start'
+  | 'bottom'
+  | 'end-bottom'
+  | 'end-top'
+  | 'end'
+  | 'start-bottom'
+  | 'start-top'
+  | 'start'
+  | 'top-end'
+  | 'top-start'
+  | 'top';
+
+/**
+ * A mixin providing common tooltip functionality.
+ */
+export declare function TooltipMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<OverlayClassMixinClass> & Constructor<TooltipMixinClass> & T;
+
+export declare class TooltipMixinClass {
+  /**
+   * Element used to link with the `aria-describedby`
+   * attribute. Supports array of multiple elements.
+   * When not set, defaults to `target`.
+   */
+  ariaTarget: HTMLElement | HTMLElement[] | undefined;
+
+  /**
+   * Object with properties passed to `generator` and
+   * `shouldShow` functions for generating tooltip text
+   * or detecting whether to show the tooltip or not.
+   */
+  context: Record<string, unknown>;
+
+  /**
+   * The delay in milliseconds before the tooltip
+   * is opened on keyboard focus, when not in manual mode.
+   * @attr {number} focus-delay
+   */
+  focusDelay: number;
+
+  /**
+   * The id of the element used as a tooltip trigger.
+   * The element should be in the DOM by the time when
+   * the attribute is set, otherwise a warning is shown.
+   */
+  for: string | undefined;
+
+  /**
+   * Function used to generate the tooltip content.
+   * When provided, it overrides the `text` property.
+   * Use the `context` property to provide argument
+   * that can be passed to the generator function.
+   */
+  generator: (context: Record<string, unknown>) => string;
+
+  /**
+   * The delay in milliseconds before the tooltip
+   * is closed on losing hover, when not in manual mode.
+   * On blur, the tooltip is closed immediately.
+   * @attr {number} hide-delay
+   */
+  hideDelay: number;
+
+  /**
+   * The delay in milliseconds before the tooltip
+   * is opened on hover, when not in manual mode.
+   * @attr {number} hover-delay
+   */
+  hoverDelay: number;
+
+  /**
+   * When true, the tooltip is controlled programmatically
+   * instead of reacting to focus and mouse events.
+   */
+  manual: boolean;
+
+  /**
+   * When true, the tooltip is opened programmatically.
+   * Only works if `manual` is set to `true`.
+   */
+  opened: boolean;
+
+  /**
+   * Position of the tooltip with respect to its target.
+   * Supported values: `top-start`, `top`, `top-end`,
+   * `bottom-start`, `bottom`, `bottom-end`, `start-top`,
+   * `start`, `start-bottom`, `end-top`, `end`, `end-bottom`.
+   */
+  position: TooltipPosition;
+
+  /**
+   * Function used to detect whether to show the tooltip based on a condition,
+   * called every time the tooltip is about to be shown on hover and focus.
+   * The function takes two parameters: `target` and `context`, which contain
+   * values of the corresponding tooltip properties at the time of calling.
+   * The tooltip is only shown when the function invocation returns `true`.
+   */
+  shouldShow: (target: HTMLElement, context?: Record<string, unknown>) => boolean;
+
+  /**
+   * Reference to the element used as a tooltip trigger.
+   * The target must be placed in the same shadow scope.
+   * Defaults to an element referenced with `for`.
+   */
+  target: HTMLElement | undefined;
+
+  /**
+   * String used as a tooltip content.
+   */
+  text: string | null | undefined;
+}