@vaadin/item 22.0.0-alpha7 → 22.0.0-beta2

package/README.md

@@ -1,13 +1,10 @@
-# <vaadin-item>
+# @vaadin/item
 
-[Live Demo ↗](https://vaadin.com/components/vaadin-item/html-examples)
-|
-[API documentation ↗](https://vaadin.com/components/vaadin-item/html-api)
+A web component for displaying items in list-box, context-menu or select components.
 
-[<vaadin-item>](https://vaadin.com/components/vaadin-item) is a Web Component providing a container for item elements, part of the [Vaadin components](https://vaadin.com/components).
+[Documentation + Live Demo ↗](https://vaadin.com/components/vaadin-item/html-examples)
 
 [![npm version](https://badgen.net/npm/v/@vaadin/item)](https://www.npmjs.com/package/@vaadin/item)
-[![Published on Vaadin Directory](https://img.shields.io/badge/Vaadin%20Directory-published-00b4f0.svg)](https://vaadin.com/directory/component/vaadinvaadin-item)
 [![Discord](https://img.shields.io/discord/732335336448852018?label=discord)](https://discord.gg/PHmkCKC)
 
 ```html
@@ -18,37 +15,40 @@
 
 ## Installation
 
-Install `vaadin-item`:
+Install the component:
 
 ```sh
-npm i @vaadin/item --save
+npm i @vaadin/item
 ```
 
-Once installed, import it in your application:
+Once installed, import the component in your application:
 
 ```js
-import '@vaadin/item/vaadin-item.js';
+import '@vaadin/item';
 ```
 
-## Getting started
+## Themes
 
-Vaadin components use the Lumo theme by default.
+Vaadin components come with two built-in [themes](https://vaadin.com/docs/latest/ds/customization/using-themes), Lumo and Material.
+The [main entrypoint](https://github.com/vaadin/web-components/blob/master/packages/item/vaadin-item.js) of the package uses Lumo theme.
 
-To use the Material theme, import the correspondent file from the `theme/material` folder.
+To use the Material theme, import the component from the `theme/material` folder:
 
-## Entry points
-
-- The component with the Lumo theme:
-
-  `theme/lumo/vaadin-item.js`
+```js
+import '@vaadin/item/theme/material/vaadin-item.js';
+```
 
-- The component with the Material theme:
+You can also import the Lumo version of the component explicitly:
 
-  `theme/material/vaadin-item.js`
+```js
+import '@vaadin/item/theme/lumo/vaadin-item.js';
+```
 
-- Alias for `theme/lumo/vaadin-item.js`:
+Finally, you can import the un-themed component from the `src` folder to get a minimal starting point:
 
-  `vaadin-item.js`
+```js
+import '@vaadin/item/src/vaadin-item.js';
+```
 
 ## Contributing
 
@@ -57,3 +57,6 @@ Read the [contributing guide](https://vaadin.com/docs/latest/guide/contributing/
 ## License
 
 Apache License 2.0
+
+Vaadin collects usage statistics at development time to improve this product.
+For details and to opt-out, see https://github.com/vaadin/vaadin-usage-statistics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/item",
-  "version": "22.0.0-alpha7",
+  "version": "22.0.0-beta2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,16 +32,17 @@
     "polymer"
   ],
   "dependencies": {
+    "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/component-base": "22.0.0-alpha7",
-    "@vaadin/vaadin-lumo-styles": "22.0.0-alpha7",
-    "@vaadin/vaadin-material-styles": "22.0.0-alpha7",
-    "@vaadin/vaadin-themable-mixin": "22.0.0-alpha7"
+    "@vaadin/component-base": "22.0.0-beta2",
+    "@vaadin/vaadin-lumo-styles": "22.0.0-beta2",
+    "@vaadin/vaadin-material-styles": "22.0.0-beta2",
+    "@vaadin/vaadin-themable-mixin": "22.0.0-beta2"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
     "@vaadin/testing-helpers": "^0.3.0",
     "sinon": "^9.2.1"
   },
-  "gitHead": "8e89419c6b44a1d225d5859e180d7b35e47ddb52"
+  "gitHead": "f13833683e6667f6ca6678452db14aa6b7eac4a4"
 }

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

@@ -1,15 +1,27 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { Constructor } from '@open-wc/dedupe-mixin';
+import { ActiveMixinClass } from '@vaadin/component-base/src/active-mixin.js';
+import { DisabledMixinClass } from '@vaadin/component-base/src/disabled-mixin.js';
+import { FocusMixinClass } from '@vaadin/component-base/src/focus-mixin.js';
+
 /**
  * A mixin providing `focused`, `focus-ring`, `active`, `disabled` and `selected`.
  *
  * `focused`, `active` and `focus-ring` are set as only as attributes.
  */
-declare function ItemMixin<T extends new (...args: any[]) => {}>(base: T): T & ItemMixinConstructor;
-
-interface ItemMixinConstructor {
-  new (...args: any[]): ItemMixin;
-}
-
-interface ItemMixin {
+export declare function ItemMixin<T extends Constructor<HTMLElement>>(
+  base: T
+): T &
+  Constructor<ItemMixinClass> &
+  Constructor<ActiveMixinClass> &
+  Constructor<DisabledMixinClass> &
+  Constructor<FocusMixinClass>;
+
+export declare class ItemMixinClass {
   value: string;
 
   /**
@@ -17,25 +29,10 @@ interface ItemMixin {
    * e.g. in VaadinListMixin it filters items by using the
    * `element._hasVaadinItemMixin` condition.
    */
-  _hasVaadinItemMixin: boolean;
-
-  /**
-   * If true, the user cannot interact with this element.
-   */
-  disabled: boolean;
+  protected _hasVaadinItemMixin: boolean;
 
   /**
    * If true, the item is in selected state.
    */
   selected: boolean;
-
-  _setFocused(focused: boolean): void;
-
-  _setActive(active: boolean): void;
-
-  _onKeydown(event: KeyboardEvent): void;
-
-  _onKeyup(event: KeyboardEvent): void;
 }
-
-export { ItemMixin, ItemMixinConstructor };

package/src/vaadin-item-mixin.js

@@ -3,6 +3,8 @@
  * Copyright (c) 2021 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
+import { ActiveMixin } from '@vaadin/component-base/src/active-mixin.js';
+import { FocusMixin } from '@vaadin/component-base/src/focus-mixin.js';
 
 /**
  * A mixin providing `focused`, `focus-ring`, `active`, `disabled` and `selected`.
@@ -11,7 +13,7 @@
  * @polymerMixin
  */
 export const ItemMixin = (superClass) =>
-  class VaadinItemMixin extends superClass {
+  class VaadinItemMixin extends ActiveMixin(FocusMixin(superClass)) {
     static get properties() {
       return {
         /**
@@ -24,17 +26,6 @@ export const ItemMixin = (superClass) =>
           value: true
         },
 
-        /**
-         * If true, the user cannot interact with this element.
-         * @type {boolean}
-         */
-        disabled: {
-          type: Boolean,
-          value: false,
-          observer: '_disabledChanged',
-          reflectToAttribute: true
-        },
-
         /**
          * If true, the item is in selected state.
          * @type {boolean}
@@ -51,6 +42,18 @@ export const ItemMixin = (superClass) =>
       };
     }
 
+    /**
+     * By default, `Space` is the only possible activation key for a focusable HTML element.
+     * Nonetheless, the item is an exception as it can be also activated by pressing `Enter`.
+     * See the "Keyboard Support" section in https://www.w3.org/TR/wai-aria-practices/examples/menubar/menubar-1/menubar-1.html.
+     *
+     * @protected
+     * @override
+     */
+    get _activeKeys() {
+      return ['Enter', ' '];
+    }
+
     /**
      * @return {string}
      */
@@ -73,31 +76,30 @@ export const ItemMixin = (superClass) =>
       if (attrValue !== null) {
         this.value = attrValue;
       }
-
-      this.addEventListener('focus', () => this._setFocused(true), true);
-      this.addEventListener('blur', () => this._setFocused(false), true);
-      this.addEventListener('mousedown', () => {
-        this._setActive((this._mousedown = true));
-        const mouseUpListener = () => {
-          this._setActive((this._mousedown = false));
-          document.removeEventListener('mouseup', mouseUpListener);
-        };
-        document.addEventListener('mouseup', mouseUpListener);
-      });
-      this.addEventListener('keydown', (e) => this._onKeydown(e));
-      this.addEventListener('keyup', (e) => this._onKeyup(e));
     }
 
-    /** @protected */
-    disconnectedCallback() {
-      super.disconnectedCallback();
-
-      // in Firefox and Safari, blur does not fire on the element when it is removed,
-      // especially between keydown and keyup events, being active at the same time.
-      // reproducible in `<vaadin-select>` when closing overlay on select.
-      if (this.hasAttribute('active')) {
-        this._setFocused(false);
+    /**
+     * Override native `focus` to set focused attribute
+     * when focusing the item programmatically.
+     * @protected
+     * @override
+     */
+    focus() {
+      if (this.disabled) {
+        return;
       }
+
+      super.focus();
+      this._setFocused(true);
+    }
+
+    /**
+     * @param {KeyboardEvent | MouseEvent} _event
+     * @protected
+     * @override
+     */
+    _shouldSetActive(event) {
+      return !this.disabled && !(event.type === 'keydown' && event.defaultPrevented);
     }
 
     /** @private */
@@ -105,64 +107,40 @@ export const ItemMixin = (superClass) =>
       this.setAttribute('aria-selected', selected);
     }
 
-    /** @private */
+    /**
+     * Override an observer from `DisabledMixin`.
+     * @protected
+     * @override
+     */
     _disabledChanged(disabled) {
+      super._disabledChanged(disabled);
+
       if (disabled) {
         this.selected = false;
-        this.setAttribute('aria-disabled', 'true');
         this.blur();
-      } else {
-        this.removeAttribute('aria-disabled');
-      }
-    }
-
-    /**
-     * @param {boolean} focused
-     * @protected
-     */
-    _setFocused(focused) {
-      if (focused) {
-        this.setAttribute('focused', '');
-        if (!this._mousedown) {
-          this.setAttribute('focus-ring', '');
-        }
-      } else {
-        this.removeAttribute('focused');
-        this.removeAttribute('focus-ring');
-        this._setActive(false);
       }
     }
 
     /**
-     * @param {boolean} active
+     * In order to be fully accessible from the keyboard, the item should
+     * manually fire the `click` event once an activation key is pressed.
+     *
+     * According to the UI Events specifications,
+     * the `click` event should be fired exactly on `keydown`:
+     * https://www.w3.org/TR/uievents/#event-type-keydown
+     *
+     * @param {KeyboardEvent} event
      * @protected
+     * @override
      */
-    _setActive(active) {
-      if (active) {
-        this.setAttribute('active', '');
-      } else {
-        this.removeAttribute('active');
-      }
-    }
+    _onKeyDown(event) {
+      super._onKeyDown(event);
 
-    /**
-     * @param {!KeyboardEvent} event
-     * @protected
-     */
-    _onKeydown(event) {
-      if (/^( |SpaceBar|Enter)$/.test(event.key) && !event.defaultPrevented) {
+      if (this._activeKeys.includes(event.key) && !event.defaultPrevented) {
         event.preventDefault();
-        this._setActive(true);
-      }
-    }
 
-    /**
-     * @param {!KeyboardEvent} event
-     * @protected
-     */
-    _onKeyup() {
-      if (this.hasAttribute('active')) {
-        this._setActive(false);
+        // `DisabledMixin` overrides the standard `click()` method
+        // so that it doesn't fire the `click` event when the element is disabled.
         this.click();
       }
     }

package/src/vaadin-item.d.ts

@@ -1,7 +1,10 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
 import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
-
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
-
 import { ItemMixin } from './vaadin-item-mixin.js';
 
 /**
@@ -25,19 +28,22 @@ import { ItemMixin } from './vaadin-item-mixin.js';
  *
  * The following shadow DOM parts are available for styling:
  *
- * Part name | Description
- * ---|---
- * `content` | The element that wraps the slot
+ * Part name    | Description
+ * -------------|----------------
+ * `checkmark`  | The graphical checkmark shown for a selected item
+ * `content`    | The element that wraps the slot
  *
  * The following state attributes are available for styling:
  *
- * Attribute  | Description | Part name
- * -----------|-------------|------------
- * `disabled` | Set to a disabled item | :host
- * `focused` | Set when the element is focused | :host
- * `focus-ring` | Set when the element is keyboard focused | :host
- * `selected` | Set when the item is selected | :host
- * `active` | Set when mousedown or enter/spacebar pressed | :host
+ * Attribute    | Description
+ * -------------|-------------
+ * `active`     | Set when the item is pressed down, either with mouse, touch or the keyboard.
+ * `disabled`   | Set when the item is disabled.
+ * `focus-ring` | Set when the item is focused using the keyboard.
+ * `focused`    | Set when the item is focused.
+ * `selected`   | Set when the item is selected
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/ds/customization/styling-components) documentation.
  */
 declare class Item extends ItemMixin(ThemableMixin(DirMixin(HTMLElement))) {
   /**

package/src/vaadin-item.js

@@ -3,7 +3,7 @@
  * Copyright (c) 2021 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { PolymerElement, html } from '@polymer/polymer/polymer-element.js';
+import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
 import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { ItemMixin } from './vaadin-item-mixin.js';
@@ -29,19 +29,22 @@ import { ItemMixin } from './vaadin-item-mixin.js';
  *
  * The following shadow DOM parts are available for styling:
  *
- * Part name | Description
- * ---|---
- * `content` | The element that wraps the slot
+ * Part name    | Description
+ * -------------|----------------
+ * `checkmark`  | The graphical checkmark shown for a selected item
+ * `content`    | The element that wraps the slot
  *
  * The following state attributes are available for styling:
  *
- * Attribute  | Description | Part name
- * -----------|-------------|------------
- * `disabled` | Set to a disabled item | :host
- * `focused` | Set when the element is focused | :host
- * `focus-ring` | Set when the element is keyboard focused | :host
- * `selected` | Set when the item is selected | :host
- * `active` | Set when mousedown or enter/spacebar pressed | :host
+ * Attribute    | Description
+ * -------------|-------------
+ * `active`     | Set when the item is pressed down, either with mouse, touch or the keyboard.
+ * `disabled`   | Set when the item is disabled.
+ * `focus-ring` | Set when the item is focused using the keyboard.
+ * `focused`    | Set when the item is focused.
+ * `selected`   | Set when the item is selected
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/ds/customization/styling-components) documentation.
  *
  * @extends HTMLElement
  * @mixes ItemMixin
@@ -60,6 +63,7 @@ class Item extends ItemMixin(ThemableMixin(DirMixin(PolymerElement))) {
           display: none !important;
         }
       </style>
+      <span part="checkmark" aria-hidden="true"></span>
       <div part="content">
         <slot></slot>
       </div>

package/theme/lumo/vaadin-item-styles.js

@@ -1,9 +1,9 @@
-import { registerStyles, css } from '@vaadin/vaadin-themable-mixin/register-styles.js';
 import '@vaadin/vaadin-lumo-styles/font-icons.js';
 import '@vaadin/vaadin-lumo-styles/sizing.js';
 import '@vaadin/vaadin-lumo-styles/spacing.js';
 import '@vaadin/vaadin-lumo-styles/style.js';
 import '@vaadin/vaadin-lumo-styles/typography.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 const item = css`
   :host {
@@ -13,15 +13,19 @@ const item = css`
     font-family: var(--lumo-font-family);
     font-size: var(--lumo-font-size-m);
     line-height: var(--lumo-line-height-xs);
-    padding: 0.5em 1em;
+    padding: 0.5em calc(var(--lumo-space-l) + var(--lumo-border-radius-m) / 4) 0.5em
+      var(--_lumo-list-box-item-padding-left, calc(var(--lumo-border-radius-m) / 4));
     min-height: var(--lumo-size-m);
+    outline: none;
+    border-radius: var(--lumo-border-radius-m);
+    cursor: var(--lumo-clickable-cursor);
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
-    -webkit-tap-highlight-color: transparent;
+    -webkit-tap-highlight-color: var(--lumo-primary-color-10pct);
   }
 
   /* Checkmark */
-  :host([tabindex])::before {
+  [part='checkmark']::before {
     display: var(--_lumo-item-selected-icon-display, none);
     content: var(--lumo-icons-checkmark);
     font-family: lumo-icons;
@@ -37,11 +41,11 @@ const item = css`
     transition: transform 0.2s cubic-bezier(0.12, 0.32, 0.54, 2), opacity 0.1s;
   }
 
-  :host([selected])::before {
+  :host([selected]) [part='checkmark']::before {
     opacity: 1;
   }
 
-  :host([active]:not([selected]))::before {
+  :host([active]:not([selected])) [part='checkmark']::before {
     transform: scale(0.8);
     opacity: 0;
     transition-duration: 0s;
@@ -58,6 +62,23 @@ const item = css`
     pointer-events: none;
   }
 
+  /* TODO a workaround until we have "focus-follows-mouse". After that, use the hover style for focus-ring as well */
+  @media (any-hover: hover) {
+    :host(:hover:not([disabled])) {
+      background-color: var(--lumo-primary-color-10pct);
+    }
+
+    :host([focus-ring]:not([disabled])) {
+      box-shadow: inset 0 0 0 2px var(--lumo-primary-color-50pct);
+    }
+  }
+
+  /* RTL specific styles */
+  :host([dir='rtl']) {
+    padding-left: calc(var(--lumo-space-l) + var(--lumo-border-radius-m) / 4);
+    padding-right: var(--_lumo-list-box-item-padding-left, calc(var(--lumo-border-radius-m) / 4));
+  }
+
   /* Slotted icons */
   :host ::slotted(vaadin-icon),
   :host ::slotted(iron-icon) {

package/theme/material/vaadin-item-styles.js

@@ -1,18 +1,19 @@
-import { registerStyles, css } from '@vaadin/vaadin-themable-mixin/register-styles.js';
 import '@vaadin/vaadin-material-styles/font-icons.js';
 import '@vaadin/vaadin-material-styles/color.js';
 import '@vaadin/vaadin-material-styles/typography.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
 const item = css`
   :host {
     display: flex;
     align-items: center;
     box-sizing: border-box;
+    min-height: 36px;
+    padding: 8px 32px 8px 10px;
     overflow: hidden;
     font-family: var(--material-font-family);
-    font-size: var(--material-body-font-size);
+    font-size: var(--material-small-font-size);
     line-height: 24px;
-    padding: 4px 0;
   }
 
   /* It's the list-box's responsibility to add the focus style */
@@ -21,7 +22,7 @@ const item = css`
   }
 
   /* Checkmark */
-  :host::before {
+  [part='checkmark']::before {
     display: var(--_material-item-selected-icon-display, none);
     content: '';
     font-family: material-icons;
@@ -35,10 +36,20 @@ const item = css`
     flex: none;
   }
 
-  :host([selected])::before {
+  :host([selected]) [part='checkmark']::before {
     content: var(--material-icons-check);
   }
 
+  @media (any-hover: hover) {
+    :host(:hover:not([disabled])) {
+      background-color: var(--material-secondary-background-color);
+    }
+
+    :host([focused]:not([disabled])) {
+      background-color: var(--material-divider-color);
+    }
+  }
+
   /* Disabled */
   :host([disabled]) {
     color: var(--material-disabled-text-color);
@@ -47,7 +58,11 @@ const item = css`
   }
 
   /* RTL specific styles */
-  :host([dir='rtl'])::before {
+  :host([dir='rtl']) {
+    padding: 8px 10px 8px 32px;
+  }
+
+  :host([dir='rtl']) [part='checkmark']::before {
     margin-right: 0;
     margin-left: 10px;
   }