@vaadin/component-base 23.2.0 → 23.3.0-alpha1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/component-base",
-  "version": "23.2.0",
+  "version": "23.3.0-alpha1",
   "publishConfig": {
     "access": "public"
   },
@@ -42,5 +42,5 @@
     "@vaadin/testing-helpers": "^0.3.2",
     "sinon": "^13.0.2"
   },
-  "gitHead": "8b1f5941f26ac41ca038e75e24c8584e331bc7a8"
+  "gitHead": "beabc527d4b1274eb798ff701d406fed45cfe638"
 }

package/src/element-mixin.js

@@ -39,7 +39,7 @@ const registered = new Set();
 export const ElementMixin = (superClass) =>
   class VaadinElementMixin extends DirMixin(superClass) {
     static get version() {
-      return '23.2.0';
+      return '23.3.0-alpha1';
     }
 
     /** @protected */

package/src/keyboard-direction-mixin.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright (c) 2022 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 { KeyboardMixinClass } from './keyboard-mixin.js';
+
+/**
+ * A mixin for navigating items with keyboard.
+ */
+export declare function KeyboardDirectionMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<KeyboardDirectionMixinClass> & Constructor<KeyboardMixinClass> & T;
+
+export declare class KeyboardDirectionMixinClass {
+  protected readonly focused: Element | null;
+
+  protected readonly _vertical: boolean;
+
+  /**
+   * Returns index of the next item that satisfies the given condition,
+   * based on the index of the current item and a numeric increment.
+   */
+  protected _getAvailableIndex(
+    items: Element[],
+    index: number,
+    increment: number,
+    condition: (item: Element) => boolean,
+  ): number;
+
+  /**
+   * Focus the item at given index. Override this method to add custom logic.
+   */
+  protected _focus(index: number, navigating: boolean): void;
+
+  /**
+   * Focus the given item. Override this method to add custom logic.
+   */
+  protected _focusItem(item: Element, navigating: boolean): void;
+}

package/src/keyboard-direction-mixin.js

@@ -0,0 +1,192 @@
+/**
+ * @license
+ * Copyright (c) 2022 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { isElementFocused, isElementHidden } from './focus-utils.js';
+import { KeyboardMixin } from './keyboard-mixin.js';
+
+/**
+ * A mixin for navigating items with keyboard.
+ *
+ * @polymerMixin
+ * @mixes KeyboardMixin
+ */
+export const KeyboardDirectionMixin = (superclass) =>
+  class KeyboardDirectionMixinClass extends KeyboardMixin(superclass) {
+    /** @protected */
+    focus() {
+      const items = this._getItems();
+      if (Array.isArray(items)) {
+        const idx = this._getAvailableIndex(items, 0, null, (item) => !isElementHidden(item));
+        if (idx >= 0) {
+          items[idx].focus();
+        }
+      }
+    }
+
+    /**
+     * @return {Element | null}
+     * @protected
+     */
+    get focused() {
+      return (this._getItems() || []).find(isElementFocused);
+    }
+
+    /**
+     * @return {boolean}
+     * @protected
+     */
+    get _vertical() {
+      return true;
+    }
+
+    /**
+     * Get the list of items participating in keyboard navigation.
+     * By default, it treats all the light DOM children as items.
+     * Override this method to provide custom list of elements.
+     *
+     * @return {Element[]}
+     * @protected
+     */
+    _getItems() {
+      return Array.from(this.children);
+    }
+
+    /**
+     * Override an event listener from `KeyboardMixin`.
+     *
+     * @param {!KeyboardEvent} event
+     * @protected
+     * @override
+     */
+    _onKeyDown(event) {
+      super._onKeyDown(event);
+
+      if (event.metaKey || event.ctrlKey) {
+        return;
+      }
+
+      const { key } = event;
+      const items = this._getItems() || [];
+      const currentIdx = items.indexOf(this.focused);
+
+      let idx;
+      let increment;
+
+      const isRTL = !this._vertical && this.getAttribute('dir') === 'rtl';
+      const dirIncrement = isRTL ? -1 : 1;
+
+      if (this.__isPrevKey(key)) {
+        increment = -dirIncrement;
+        idx = currentIdx - dirIncrement;
+      } else if (this.__isNextKey(key)) {
+        increment = dirIncrement;
+        idx = currentIdx + dirIncrement;
+      } else if (key === 'Home') {
+        increment = 1;
+        idx = 0;
+      } else if (key === 'End') {
+        increment = -1;
+        idx = items.length - 1;
+      }
+
+      idx = this._getAvailableIndex(items, idx, increment, (item) => !isElementHidden(item));
+
+      if (idx >= 0) {
+        event.preventDefault();
+        this._focus(idx, true);
+      }
+    }
+
+    /**
+     * @param {string} key
+     * @return {boolean}
+     * @private
+     */
+    __isPrevKey(key) {
+      return this._vertical ? key === 'ArrowUp' : key === 'ArrowLeft';
+    }
+
+    /**
+     * @param {string} key
+     * @return {boolean}
+     * @private
+     */
+    __isNextKey(key) {
+      return this._vertical ? key === 'ArrowDown' : key === 'ArrowRight';
+    }
+
+    /**
+     * Focus the item at given index. Override this method to add custom logic.
+     *
+     * @param {number} index
+     * @param {boolean} navigating
+     * @protected
+     */
+    _focus(index, navigating = false) {
+      const items = this._getItems();
+
+      this._focusItem(items[index], navigating);
+    }
+
+    /**
+     * Focus the given item. Override this method to add custom logic.
+     *
+     * @param {Element} item
+     * @param {boolean} navigating
+     * @protected
+     */
+    _focusItem(item) {
+      if (item) {
+        item.focus();
+
+        // Generally, the items are expected to implement `FocusMixin`
+        // that would set this attribute based on the `keydown` event.
+        // We set it manually to handle programmatic focus() calls.
+        item.setAttribute('focus-ring', '');
+      }
+    }
+
+    /**
+     * Returns index of the next item that satisfies the given condition,
+     * based on the index of the current item and a numeric increment.
+     *
+     * @param {Element[]} items - array of items to iterate over
+     * @param {number} index - index of the current item
+     * @param {number} increment - numeric increment, can be either 1 or -1
+     * @param {Function} condition - function used to check the item
+     * @return {number}
+     * @protected
+     */
+    _getAvailableIndex(items, index, increment, condition) {
+      const totalItems = items.length;
+      let idx = index;
+      for (let i = 0; typeof idx === 'number' && i < totalItems; i += 1, idx += increment || 1) {
+        if (idx < 0) {
+          idx = totalItems - 1;
+        } else if (idx >= totalItems) {
+          idx = 0;
+        }
+
+        const item = items[idx];
+
+        if (!item.hasAttribute('disabled') && this.__isMatchingItem(item, condition)) {
+          return idx;
+        }
+      }
+      return -1;
+    }
+
+    /**
+     * Returns true if the item matches condition.
+     *
+     * @param {Element} item - item to check
+     * @param {Function} condition - function used to check the item
+     * @return {number}
+     * @private
+     */
+    __isMatchingItem(item, condition) {
+      return typeof condition === 'function' ? condition(item) : true;
+    }
+  };

package/src/tooltip-controller.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright (c) 2022 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { SlotController } from './slot-controller.js';
+
+type TooltipPosition =
+  | 'bottom-end'
+  | 'bottom-start'
+  | 'bottom'
+  | 'end-bottom'
+  | 'end-top'
+  | 'end'
+  | 'start-bottom'
+  | 'start-top'
+  | 'start'
+  | 'top-end'
+  | 'top-start'
+  | 'top';
+
+/**
+ * A controller that manages the slotted tooltip element.
+ */
+export class TooltipController extends SlotController {
+  /**
+   * Object with properties passed to `textGenerator`
+   * function to be used for generating tooltip text.
+   */
+  context: Record<string, unknown>;
+
+  /**
+   * 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.
+   */
+  position: TooltipPosition;
+
+  /**
+   * An HTML element to attach the tooltip to.
+   */
+  target: HTMLElement;
+
+  /**
+   * Set a context object to be used by text generator.
+   */
+  setContext(context: Record<string, unknown>): void;
+
+  /**
+   * Toggle manual state on the slotted tooltip.
+   */
+  setManual(manual: boolean): void;
+
+  /**
+   * Toggle opened state on the slotted tooltip.
+   */
+  setOpened(opened: boolean): void;
+
+  /**
+   * Set position on the slotted tooltip.
+   */
+  setPosition(position: TooltipPosition): void;
+
+  /**
+   * Set function used to detect whether to show
+   * the tooltip based on a condition.
+   */
+  setShouldShow(shouldShow: (target: HTMLElement) => boolean): void;
+
+  /**
+   * Set an HTML element to attach the tooltip to.
+   */
+  setTarget(target: HTMLElement): void;
+}

package/src/tooltip-controller.js

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright (c) 2022 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { SlotController } from './slot-controller.js';
+
+/**
+ * A controller that manages the slotted tooltip element.
+ */
+export class TooltipController extends SlotController {
+  constructor(host) {
+    // Do not provide slot factory to create tooltip lazily.
+    super(host, 'tooltip');
+
+    this.setTarget(host);
+  }
+
+  /**
+   * Override to initialize the newly added custom tooltip.
+   *
+   * @param {Node} tooltipNode
+   * @protected
+   * @override
+   */
+  initCustomNode(tooltipNode) {
+    tooltipNode.target = this.target;
+
+    if (this.context !== undefined) {
+      tooltipNode.context = this.context;
+    }
+
+    if (this.manual !== undefined) {
+      tooltipNode.manual = this.manual;
+    }
+
+    if (this.opened !== undefined) {
+      tooltipNode.opened = this.opened;
+    }
+
+    if (this.position !== undefined) {
+      tooltipNode.position = this.position;
+    }
+
+    if (this.shouldShow !== undefined) {
+      tooltipNode.shouldShow = this.shouldShow;
+    }
+  }
+
+  /**
+   * Set a context object to be used by text generator.
+   * @param {object} context
+   */
+  setContext(context) {
+    this.context = context;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.context = context;
+    }
+  }
+
+  /**
+   * Toggle manual state on the slotted tooltip.
+   * @param {boolean} manual
+   */
+  setManual(manual) {
+    this.manual = manual;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.manual = manual;
+    }
+  }
+
+  /**
+   * Toggle opened state on the slotted tooltip.
+   * @param {boolean} opened
+   */
+  setOpened(opened) {
+    this.opened = opened;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.opened = opened;
+    }
+  }
+
+  /**
+   * Set position on the slotted tooltip.
+   * @param {string} position
+   */
+  setPosition(position) {
+    this.position = position;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.position = position;
+    }
+  }
+
+  /**
+   * Set function used to detect whether to show
+   * the tooltip based on a condition.
+   * @param {Function} shouldShow
+   */
+  setShouldShow(shouldShow) {
+    this.shouldShow = shouldShow;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.shouldShow = shouldShow;
+    }
+  }
+
+  /**
+   * Set an HTML element to attach the tooltip to.
+   * @param {HTMLElement} target
+   */
+  setTarget(target) {
+    this.target = target;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.target = target;
+    }
+  }
+}