@vaadin/side-nav 24.1.2 → 24.2.0-alpha2

package/README.md

@@ -49,9 +49,14 @@ import '@vaadin/side-nav';
 ## Themes
 
 Vaadin components come with two built-in [themes](https://vaadin.com/docs/latest/styling), Lumo and Material.
-This component currently does not support Material theme.
 The [main entrypoint](https://github.com/vaadin/web-components/blob/main/packages/side-nav/vaadin-side-nav.js) of the package uses the Lumo theme.
 
+To use the Material theme, import the component from the `theme/material` folder:
+
+```js
+import '@vaadin/side-nav/theme/material/vaadin-side-nav.js';
+```
+
 You can also import the Lumo version of the component explicitly:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/side-nav",
-  "version": "24.1.2",
+  "version": "24.2.0-alpha2",
   "publishConfig": {
     "access": "public"
   },
@@ -35,10 +35,10 @@
     "web-component"
   ],
   "dependencies": {
-    "@vaadin/component-base": "~24.1.2",
-    "@vaadin/vaadin-lumo-styles": "~24.1.2",
-    "@vaadin/vaadin-material-styles": "~24.1.2",
-    "@vaadin/vaadin-themable-mixin": "~24.1.2",
+    "@vaadin/component-base": "24.2.0-alpha2",
+    "@vaadin/vaadin-lumo-styles": "24.2.0-alpha2",
+    "@vaadin/vaadin-material-styles": "24.2.0-alpha2",
+    "@vaadin/vaadin-themable-mixin": "24.2.0-alpha2",
     "lit": "^2.0.0"
   },
   "devDependencies": {
@@ -51,5 +51,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "2d52aec53816cf8ee5cc4e08344adfb0c0b4d2f7"
+  "gitHead": "b8378bd2267728e172012bcb2ea45c3e5a6e590a"
 }

package/src/vaadin-side-nav-base-styles.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2017 - 2023 Vaadin Ltd.
+ * Copyright (c) 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { css } from 'lit';
@@ -10,11 +10,17 @@ export const sideNavItemBaseStyles = css`
     display: block;
   }
 
+  :host([hidden]),
   [hidden] {
     display: none !important;
   }
 
-  a {
+  [part='content'] {
+    display: flex;
+    align-items: center;
+  }
+
+  [part='link'] {
     flex: auto;
     min-width: 0;
     display: flex;
@@ -28,10 +34,21 @@ export const sideNavItemBaseStyles = css`
     -webkit-appearance: none;
     appearance: none;
     flex: none;
+    position: relative;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    background: transparent;
   }
 
-  :host(:not([path])) a {
-    position: relative;
+  [part='children'] {
+    padding: 0;
+    margin: 0;
+    list-style-type: none;
+  }
+
+  :host(:not([has-children])) button {
+    display: none !important;
   }
 
   :host(:not([path])) button::after {
@@ -56,12 +73,6 @@ export const sideNavItemBaseStyles = css`
     text-overflow: ellipsis;
     white-space: nowrap;
   }
-
-  slot[name='children'] {
-    /* Needed to make role="list" work */
-    display: block;
-    width: 100%;
-  }
 `;
 
 export const sideNavBaseStyles = css`
@@ -73,32 +84,24 @@ export const sideNavBaseStyles = css`
     display: none !important;
   }
 
-  summary {
+  button {
     display: flex;
     align-items: center;
-    justify-content: space-between;
-  }
-
-  summary ::slotted([slot='label']) {
-    display: block;
-  }
-
-  summary::-webkit-details-marker {
-    display: none;
-  }
-
-  summary::marker {
-    content: '';
-  }
-
-  summary::after {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
+    justify-content: inherit;
+    width: 100%;
+    margin: 0;
+    padding: 0;
+    background-color: initial;
+    color: inherit;
+    border: initial;
+    outline: none;
+    font: inherit;
+    text-align: inherit;
   }
 
-  slot {
-    /* Needed to make role="list" work */
-    display: block;
+  [part='children'] {
+    padding: 0;
+    margin: 0;
+    list-style-type: none;
   }
 `;

package/src/vaadin-side-nav-children-mixin.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright (c) 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';
+
+export interface SideNavI18n {
+  toggle: string;
+}
+
+export declare function SideNavChildrenMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<SideNavChildrenMixinClass> & T;
+
+export declare class SideNavChildrenMixinClass {
+  /**
+   * The object used to localize this component.
+   *
+   * To change the default localization, replace the entire
+   * `i18n` object with a custom one.
+   *
+   * The object has the following structure and default values:
+   * ```
+   * {
+   *   toggle: 'Toggle child items'
+   * }
+   * ```
+   */
+  i18n: SideNavI18n;
+
+  /**
+   * List of child items of this component.
+   */
+  protected readonly _items: HTMLElement[];
+
+  /**
+   * Name of the slot to be used for children.
+   */
+  protected readonly _itemsSlotName: string;
+}

package/src/vaadin-side-nav-children-mixin.js

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { SlotController } from '@vaadin/component-base/src/slot-controller.js';
+
+/**
+ * A controller that manages the item content children slot.
+ */
+class ChildrenController extends SlotController {
+  constructor(host, slotName) {
+    super(host, slotName, null, { observe: true, multiple: true });
+  }
+
+  /**
+   * @protected
+   * @override
+   */
+  initAddedNode() {
+    this.host.requestUpdate();
+  }
+
+  /**
+   * @protected
+   * @override
+   */
+  teardownNode() {
+    this.host.requestUpdate();
+  }
+}
+
+/**
+ * @polymerMixin
+ */
+export const SideNavChildrenMixin = (superClass) =>
+  class SideNavChildrenMixin extends superClass {
+    static get properties() {
+      return {
+        /**
+         * The object used to localize this component.
+         *
+         * To change the default localization, replace the entire
+         * `i18n` object with a custom one.
+         *
+         * The object has the following structure and default values:
+         * ```
+         * {
+         *   toggle: 'Toggle child items'
+         * }
+         * ```
+         *
+         * @type {SideNavI18n}
+         * @default {English/US}
+         */
+        i18n: {
+          type: Object,
+          value: () => {
+            return {
+              toggle: 'Toggle child items',
+            };
+          },
+        },
+
+        /**
+         * Count of child items.
+         * @private
+         */
+        _itemsCount: {
+          type: Number,
+          value: 0,
+        },
+      };
+    }
+
+    constructor() {
+      super();
+
+      this._childrenController = new ChildrenController(this, this._itemsSlotName);
+    }
+
+    /**
+     * List of child items of this component.
+     * @protected
+     */
+    get _items() {
+      return this._childrenController.nodes;
+    }
+
+    /**
+     * Name of the slot to be used for children.
+     * @protected
+     */
+    get _itemsSlotName() {
+      return 'children';
+    }
+
+    /** @protected */
+    firstUpdated() {
+      super.firstUpdated();
+
+      // Controller that detects changes to the side-nav items.
+      this.addController(this._childrenController);
+    }
+
+    /**
+     * @protected
+     * @override
+     */
+    willUpdate(props) {
+      super.willUpdate(props);
+
+      this._itemsCount = this._items.length;
+    }
+
+    /**
+     * @protected
+     * @override
+     */
+    updated(props) {
+      super.updated(props);
+
+      if (props.has('_itemsCount')) {
+        this.toggleAttribute('has-children', this._itemsCount > 0);
+      }
+
+      // Propagate i18n object to all the child items
+      if (props.has('_itemsCount') || props.has('i18n')) {
+        this._items.forEach((item) => {
+          item.i18n = this.i18n;
+        });
+      }
+    }
+  };

package/src/vaadin-side-nav-item.d.ts

@@ -1,12 +1,13 @@
 /**
  * @license
- * Copyright (c) 2017 - 2023 Vaadin Ltd.
+ * Copyright (c) 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { LitElement } from 'lit';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { SideNavChildrenMixin } from './vaadin-side-nav-children-mixin.js';
 
 /**
  * Fired when the `expanded` property changes.
@@ -54,14 +55,39 @@ export type SideNavItemEventMap = HTMLElementEventMap & SideNavItemCustomEventMa
  * </vaadin-side-nav-item>
  * ```
  *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name       | Description
+ * ----------------|----------------
+ * `content`       | The element that wraps link and toggle button
+ * `children`      | The element that wraps child items
+ * `link`          | The clickable anchor used for navigation
+ * `toggle-button` | The toggle button
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------|-------------
+ * `expanded`     | Set when the element is expanded.
+ * `has-children` | Set when the element has child items.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
  * @fires {CustomEvent} expanded-changed - Fired when the `expanded` property changes.
  */
-declare class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
+declare class SideNavItem extends SideNavChildrenMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)))) {
   /**
    * The path to navigate to
    */
   path: string | null | undefined;
 
+  /**
+   * The list of alternative paths matching this item
+   */
+  pathAliases: string[];
+
   /**
    * Whether to show the child items or not
    */
@@ -72,7 +98,7 @@ declare class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitEle
    * Set when the item is appended to DOM or when navigated back
    * to the page that contains this item using the browser.
    */
-  readonly active: boolean;
+  readonly current: boolean;
 
   addEventListener<K extends keyof SideNavItemEventMap>(
     type: K,

package/src/vaadin-side-nav-item.js

@@ -1,14 +1,17 @@
 /**
  * @license
- * Copyright (c) 2017 - 2023 Vaadin Ltd.
+ * Copyright (c) 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { html, LitElement } from 'lit';
 import { ifDefined } from 'lit/directives/if-defined.js';
+import { screenReaderOnly } from '@vaadin/a11y-base/src/styles/sr-only-styles.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { matchPaths } from '@vaadin/component-base/src/url-utils.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { sideNavItemBaseStyles } from './vaadin-side-nav-base-styles.js';
+import { SideNavChildrenMixin } from './vaadin-side-nav-children-mixin.js';
 
 function isEnabled() {
   return window.Vaadin && window.Vaadin.featureFlags && !!window.Vaadin.featureFlags.sideNavComponent;
@@ -49,14 +52,35 @@ function isEnabled() {
  * </vaadin-side-nav-item>
  * ```
  *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name       | Description
+ * ----------------|----------------
+ * `content`       | The element that wraps link and toggle button
+ * `children`      | The element that wraps child items
+ * `link`          | The clickable anchor used for navigation
+ * `toggle-button` | The toggle button
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute      | Description
+ * ---------------|-------------
+ * `expanded`     | Set when the element is expanded.
+ * `has-children` | Set when the element has child items.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
  * @fires {CustomEvent} expanded-changed - Fired when the `expanded` property changes.
  *
  * @extends LitElement
  * @mixes PolylitMixin
  * @mixes ThemableMixin
  * @mixes ElementMixin
+ * @mixes SideNavChildrenMixin
  */
-class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
+class SideNavItem extends SideNavChildrenMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement)))) {
   static get is() {
     return 'vaadin-side-nav-item';
   }
@@ -68,6 +92,16 @@ class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitElement)))
        */
       path: String,
 
+      /**
+       * The list of alternative paths matching this item
+       *
+       * @type {!Array<string>}
+       */
+      pathAliases: {
+        type: Array,
+        value: () => [],
+      },
+
       /**
        * Whether to show the child items or not
        *
@@ -87,7 +121,7 @@ class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitElement)))
        *
        * @type {boolean}
        */
-      active: {
+      current: {
         type: Boolean,
         value: false,
         readOnly: true,
@@ -97,7 +131,13 @@ class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitElement)))
   }
 
   static get styles() {
-    return sideNavItemBaseStyles;
+    return [screenReaderOnly, sideNavItemBaseStyles];
+  }
+
+  constructor() {
+    super();
+
+    this.__boundUpdateCurrent = this.__updateCurrent.bind(this);
   }
 
   /** @protected */
@@ -110,6 +150,8 @@ class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitElement)))
    * @override
    */
   firstUpdated() {
+    super.firstUpdated();
+
     // By default, if the user hasn't provided a custom role,
     // the role attribute is set to "listitem".
     if (!this.hasAttribute('role')) {
@@ -124,84 +166,87 @@ class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitElement)))
   updated(props) {
     super.updated(props);
 
-    if (props.has('path')) {
-      this.__updateActive();
+    if (props.has('path') || props.has('pathAliases')) {
+      this.__updateCurrent();
     }
   }
 
   /** @protected */
   connectedCallback() {
     super.connectedCallback();
-    this.__updateActive();
-    this.__boundUpdateActive = this.__updateActive.bind(this);
-    window.addEventListener('popstate', this.__boundUpdateActive);
+    this.__updateCurrent();
+
+    window.addEventListener('popstate', this.__boundUpdateCurrent);
   }
 
   /** @protected */
   disconnectedCallback() {
     super.disconnectedCallback();
-    window.removeEventListener('popstate', this.__boundUpdateActive);
+    window.removeEventListener('popstate', this.__boundUpdateCurrent);
   }
 
   /** @protected */
   render() {
     return html`
-      <a href="${ifDefined(this.path)}" part="item" aria-current="${this.active ? 'page' : 'false'}">
-        <slot name="prefix"></slot>
-        <slot></slot>
-        <slot name="suffix"></slot>
+      <div part="content" @click="${this._onContentClick}">
+        <a id="link" href="${ifDefined(this.path)}" part="link" aria-current="${this.current ? 'page' : 'false'}">
+          <slot name="prefix"></slot>
+          <slot></slot>
+          <slot name="suffix"></slot>
+        </a>
         <button
           part="toggle-button"
-          @click="${this.__toggleExpanded}"
-          ?hidden="${!this.querySelector('[slot=children]')}"
+          @click="${this._onButtonClick}"
           aria-controls="children"
           aria-expanded="${this.expanded}"
-          aria-label="Toggle child items"
+          aria-labelledby="link i18n"
         ></button>
-      </a>
-      <slot name="children" role="list" part="children" id="children" ?hidden="${!this.expanded}"></slot>
+      </div>
+      <ul part="children" ?hidden="${!this.expanded}">
+        <slot name="children"></slot>
+      </ul>
+      <div class="sr-only" id="i18n">${this.i18n.toggle}</div>
     `;
   }
 
   /** @private */
-  __toggleExpanded(e) {
-    e.preventDefault();
-    e.stopPropagation();
-    this.expanded = !this.expanded;
+  _onButtonClick(event) {
+    // Prevent the event from being handled
+    // by the content click listener below
+    event.stopPropagation();
+    this.__toggleExpanded();
   }
 
   /** @private */
-  __updateActive() {
-    if (!this.path && this.path !== '') {
-      this._setActive(false);
-      return;
-    }
-    this._setActive(this.__calculateActive());
-    this.toggleAttribute('child-active', document.location.pathname.startsWith(this.path));
-    if (this.active) {
-      this.expanded = true;
+  _onContentClick() {
+    // Toggle item expanded state unless the link has a non-empty path
+    if (this.path == null && this.hasAttribute('has-children')) {
+      this.__toggleExpanded();
     }
   }
 
   /** @private */
-  __calculateActive() {
-    const pathAbsolute = this.path.startsWith('/');
-    // Absolute path or no base uri in use. No special comparison needed
-    if (pathAbsolute) {
-      // Compare an absolute view path
-      return document.location.pathname === this.path;
+  __toggleExpanded() {
+    this.expanded = !this.expanded;
+  }
+
+  /** @private */
+  __updateCurrent() {
+    this._setCurrent(this.__isCurrent());
+    if (this.current) {
+      this.expanded = this._items.length > 0;
     }
-    const hasBaseUri = document.baseURI !== document.location.href;
-    if (!hasBaseUri) {
-      // Compare a relative view path (strip the starting slash)
-      return document.location.pathname.substring(1) === this.path;
+  }
+
+  /** @private */
+  __isCurrent() {
+    if (this.path == null) {
+      return false;
     }
-    const pathRelativeToRoot = document.location.pathname;
-    const basePath = new URL(document.baseURI).pathname;
-    const pathWithoutBase = pathRelativeToRoot.substring(basePath.length);
-    const pathRelativeToBase =
-      basePath !== pathRelativeToRoot && pathRelativeToRoot.startsWith(basePath) ? pathWithoutBase : pathRelativeToRoot;
-    return pathRelativeToBase === this.path;
+    return (
+      matchPaths(document.location.pathname, this.path) ||
+      this.pathAliases.some((alias) => matchPaths(document.location.pathname, alias))
+    );
   }
 }
 

package/src/vaadin-side-nav.d.ts

@@ -4,9 +4,13 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { LitElement } from 'lit';
+import { FocusMixin } from '@vaadin/a11y-base/src/focus-mixin.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { SideNavChildrenMixin, type SideNavI18n } from './vaadin-side-nav-children-mixin.js';
+
+export type { SideNavI18n };
 
 /**
  * Fired when the `collapsed` property changes.
@@ -48,9 +52,29 @@ export type SideNavEventMap = HTMLElementEventMap & SideNavCustomEventMap;
  * </vaadin-side-nav>
  * ```
  *
+ * ### Styling
+ *
+ * The following shadow DOM parts are available for styling:
+ *
+ * Part name       | Description
+ * ----------------|----------------
+ * `label`         | The label element
+ * `children`      | The element that wraps child items
+ * `toggle-button` | The toggle button
+ *
+ * The following state attributes are available for styling:
+ *
+ * Attribute    | Description
+ * -------------|-------------
+ * `collapsed`  | Set when the element is collapsed.
+ * `focus-ring` | Set when the label is focused using the keyboard.
+ * `focused`    | Set when the label is focused.
+ *
+ * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
+ *
  * @fires {CustomEvent} collapsed-changed - Fired when the `collapsed` property changes.
  */
-declare class SideNav extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
+declare class SideNav extends SideNavChildrenMixin(FocusMixin(ElementMixin(ThemableMixin(PolylitMixin(LitElement))))) {
   /**
    * Whether the side nav is collapsible. When enabled, the toggle icon is shown.
    */