@vaadin/side-nav 24.1.0-alpha10

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

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 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 { 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 { sideNavItemBaseStyles } from './vaadin-side-nav-base-styles.js';
+
+function isEnabled() {
+  return window.Vaadin && window.Vaadin.featureFlags && !!window.Vaadin.featureFlags.sideNavComponent;
+}
+
+/**
+ * A navigation item to be used within `<vaadin-side-nav>`. Represents a navigation target.
+ * Not intended to be used separately.
+ *
+ * ```html
+ * <vaadin-side-nav-item>
+ *   Item 1
+ *   <vaadin-side-nav-item path="/path1" slot="children">
+ *     Child item 1
+ *   </vaadin-side-nav-item>
+ *   <vaadin-side-nav-item path="/path2" slot="children">
+ *     Child item 2
+ *   </vaadin-side-nav-item>
+ * </vaadin-side-nav-item>
+ * ```
+ *
+ * ### Customization
+ *
+ * You can configure the item by using `slot` names.
+ *
+ * Slot name | Description
+ * ----------|-------------
+ * `prefix`  | A slot for content before the label (e.g. an icon).
+ * `suffix`  | A slot for content after the label (e.g. an icon).
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-side-nav-item>
+ *   <vaadin-icon icon="vaadin:chart" slot="prefix"></vaadin-icon>
+ *   Item
+ *   <span theme="badge primary" slot="suffix">Suffix</span>
+ * </vaadin-side-nav-item>
+ * ```
+ *
+ * @fires {CustomEvent} expanded-changed - Fired when the `expanded` property changes.
+ *
+ * @extends LitElement
+ * @mixes PolylitMixin
+ * @mixes ThemableMixin
+ * @mixes ElementMixin
+ */
+class SideNavItem extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
+  static get is() {
+    return 'vaadin-side-nav-item';
+  }
+
+  static get properties() {
+    return {
+      /**
+       * The path to navigate to
+       */
+      path: String,
+
+      /**
+       * Whether to show the child items or not
+       *
+       * @type {boolean}
+       */
+      expanded: {
+        type: Boolean,
+        value: false,
+        notify: true,
+        reflectToAttribute: true,
+      },
+
+      /**
+       * Whether the path of the item matches the current path.
+       * Set when the item is appended to DOM or when navigated back
+       * to the page that contains this item using the browser.
+       *
+       * @type {boolean}
+       */
+      active: {
+        type: Boolean,
+        value: false,
+        readOnly: true,
+        reflectToAttribute: true,
+      },
+    };
+  }
+
+  static get styles() {
+    return sideNavItemBaseStyles;
+  }
+
+  /** @protected */
+  get _button() {
+    return this.shadowRoot.querySelector('button');
+  }
+
+  /**
+   * @protected
+   * @override
+   */
+  firstUpdated() {
+    // By default, if the user hasn't provided a custom role,
+    // the role attribute is set to "listitem".
+    if (!this.hasAttribute('role')) {
+      this.setAttribute('role', 'listitem');
+    }
+  }
+
+  /**
+   * @protected
+   * @override
+   */
+  updated(props) {
+    super.updated(props);
+
+    if (props.has('path')) {
+      this.__updateActive();
+    }
+  }
+
+  /** @protected */
+  connectedCallback() {
+    super.connectedCallback();
+    this.__updateActive();
+    this.__boundUpdateActive = this.__updateActive.bind(this);
+    window.addEventListener('popstate', this.__boundUpdateActive);
+  }
+
+  /** @protected */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    window.removeEventListener('popstate', this.__boundUpdateActive);
+  }
+
+  /** @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>
+        <button
+          part="toggle-button"
+          @click="${this.__toggleExpanded}"
+          ?hidden="${!this.querySelector('[slot=children]')}"
+          aria-controls="children"
+          aria-expanded="${this.expanded}"
+          aria-label="Toggle child items"
+        ></button>
+      </a>
+      <slot name="children" role="list" part="children" id="children" ?hidden="${!this.expanded}"></slot>
+    `;
+  }
+
+  /** @private */
+  __toggleExpanded(e) {
+    e.preventDefault();
+    e.stopPropagation();
+    this.expanded = !this.expanded;
+  }
+
+  /** @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;
+    }
+  }
+
+  /** @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;
+    }
+    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;
+    }
+    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;
+  }
+}
+
+if (isEnabled()) {
+  customElements.define(SideNavItem.is, SideNavItem);
+}
+
+export { SideNavItem };

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

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * 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';
+
+/**
+ * Fired when the `collapsed` property changes.
+ */
+export type SideNavCollapsedChangedEvent = CustomEvent<{ value: boolean }>;
+
+export interface SideNavCustomEventMap {
+  'collapsed-changed': SideNavCollapsedChangedEvent;
+}
+
+export type SideNavEventMap = HTMLElementEventMap & SideNavCustomEventMap;
+
+/**
+ * `<vaadin-side-nav>` is a Web Component for navigation menus.
+ *
+ * ```html
+ * <vaadin-side-nav>
+ *   <vaadin-side-nav-item>Item 1</vaadin-side-nav-item>
+ *   <vaadin-side-nav-item>Item 2</vaadin-side-nav-item>
+ *   <vaadin-side-nav-item>Item 3</vaadin-side-nav-item>
+ *   <vaadin-side-nav-item>Item 4</vaadin-side-nav-item>
+ * </vaadin-side-nav>
+ * ```
+ *
+ * ### Customization
+ *
+ * You can configure the component by using `slot` names.
+ *
+ * Slot name | Description
+ * ----------|-------------
+ * `label`   | The label (text) inside the side nav.
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-side-nav>
+ *   <span slot="label">Main menu</span>
+ *   <vaadin-side-nav-item>Item</vaadin-side-nav-item>
+ * </vaadin-side-nav>
+ * ```
+ *
+ * @fires {CustomEvent} collapsed-changed - Fired when the `collapsed` property changes.
+ */
+declare class SideNav extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
+  /**
+   * Whether the side nav is collapsible. When enabled, the toggle icon is shown.
+   */
+  collapsible: boolean;
+
+  /**
+   * Whether the side nav is collapsed. When collapsed, the items are hidden.
+   */
+  collapsed: boolean;
+
+  addEventListener<K extends keyof SideNavEventMap>(
+    type: K,
+    listener: (this: SideNav, ev: SideNavEventMap[K]) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void;
+
+  removeEventListener<K extends keyof SideNavEventMap>(
+    type: K,
+    listener: (this: SideNav, ev: SideNavEventMap[K]) => void,
+    options?: EventListenerOptions | boolean,
+  ): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vaadin-side-nav': SideNav;
+  }
+}
+
+export { SideNav };

package/src/vaadin-side-nav.js

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * 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 { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
+import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
+import { generateUniqueId } from '@vaadin/component-base/src/unique-id-utils.js';
+import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+import { sideNavBaseStyles } from './vaadin-side-nav-base-styles.js';
+
+function isEnabled() {
+  return window.Vaadin && window.Vaadin.featureFlags && !!window.Vaadin.featureFlags.sideNavComponent;
+}
+
+/**
+ * `<vaadin-side-nav>` is a Web Component for navigation menus.
+ *
+ * ```html
+ * <vaadin-side-nav>
+ *   <vaadin-side-nav-item>Item 1</vaadin-side-nav-item>
+ *   <vaadin-side-nav-item>Item 2</vaadin-side-nav-item>
+ *   <vaadin-side-nav-item>Item 3</vaadin-side-nav-item>
+ *   <vaadin-side-nav-item>Item 4</vaadin-side-nav-item>
+ * </vaadin-side-nav>
+ * ```
+ *
+ * ### Customization
+ *
+ * You can configure the component by using `slot` names.
+ *
+ * Slot name | Description
+ * ----------|-------------
+ * `label`   | The label (text) inside the side nav.
+ *
+ * #### Example
+ *
+ * ```html
+ * <vaadin-side-nav>
+ *   <span slot="label">Main menu</span>
+ *   <vaadin-side-nav-item>Item</vaadin-side-nav-item>
+ * </vaadin-side-nav>
+ * ```
+ *
+ * @fires {CustomEvent} collapsed-changed - Fired when the `collapsed` property changes.
+ *
+ * @extends LitElement
+ * @mixes PolylitMixin
+ * @mixes ThemableMixin
+ * @mixes ElementMixin
+ */
+class SideNav extends ElementMixin(ThemableMixin(PolylitMixin(LitElement))) {
+  static get is() {
+    return 'vaadin-side-nav';
+  }
+
+  static get properties() {
+    return {
+      /**
+       * Whether the side nav is collapsible. When enabled, the toggle icon is shown.
+       *
+       * @type {boolean}
+       */
+      collapsible: {
+        type: Boolean,
+        value: false,
+        reflectToAttribute: true,
+      },
+
+      /**
+       * Whether the side nav is collapsed. When collapsed, the items are hidden.
+       *
+       * @type {boolean}
+       */
+      collapsed: {
+        type: Boolean,
+        value: false,
+        notify: true,
+        reflectToAttribute: true,
+      },
+    };
+  }
+
+  static get styles() {
+    return sideNavBaseStyles;
+  }
+
+  /** @protected */
+  firstUpdated() {
+    // By default, if the user hasn't provided a custom role,
+    // the role attribute is set to "navigation".
+    if (!this.hasAttribute('role')) {
+      this.setAttribute('role', 'navigation');
+    }
+  }
+
+  /** @protected */
+  render() {
+    const label = this.querySelector('[slot="label"]');
+    if (label && this.collapsible) {
+      return html`
+        <details ?open="${!this.collapsed}" @toggle="${this.__toggleCollapsed}">${this.__renderBody(label)}</details>
+      `;
+    }
+    return this.__renderBody(label);
+  }
+
+  /** @private */
+  __renderBody(label) {
+    if (label) {
+      if (!label.id) label.id = `side-nav-label-${generateUniqueId()}`;
+      this.setAttribute('aria-labelledby', label.id);
+    } else {
+      this.removeAttribute('aria-labelledby');
+    }
+    return html`
+      <summary part="label" ?hidden="${label == null}">
+        <slot name="label" @slotchange="${() => this.requestUpdate()}"></slot>
+      </summary>
+      <slot role="list"></slot>
+    `;
+  }
+
+  /** @private */
+  __toggleCollapsed(e) {
+    this.collapsed = !e.target.open;
+  }
+}
+
+if (isEnabled()) {
+  customElements.define(SideNav.is, SideNav);
+} else {
+  console.warn(
+    'WARNING: The side-nav component is currently an experimental feature and needs to be explicitly enabled. To enable the component, `import "@vaadin/side-nav/enable.js"` *before* importing the side-nav module itself.',
+  );
+}
+
+export { SideNav };

package/theme/lumo/vaadin-side-nav-item.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import './vaadin-side-nav-styles.js';
+import '../../src/vaadin-side-nav-item.js';

package/theme/lumo/vaadin-side-nav-styles.js

@@ -0,0 +1,164 @@
+import '@vaadin/vaadin-lumo-styles/color.js';
+import '@vaadin/vaadin-lumo-styles/typography.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/font-icons.js';
+import { css, registerStyles } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
+
+export const sideNavItemStyles = css`
+  a {
+    gap: var(--lumo-space-xs);
+    padding: var(--lumo-space-s);
+    padding-inline-start: calc(var(--lumo-space-s) + var(--_child-indent, 0px));
+    border-radius: var(--lumo-border-radius-m);
+    transition: background-color 140ms, color 140ms;
+    cursor: var(--lumo-clickable-cursor, default);
+    min-height: var(--lumo-icon-size-m);
+  }
+
+  button {
+    border: 0;
+    margin: calc((var(--lumo-icon-size-m) - var(--lumo-size-s)) / 2) 0;
+    margin-inline-end: calc(var(--lumo-space-xs) * -1);
+    padding: 0;
+    background: transparent;
+    font: inherit;
+    color: var(--lumo-tertiary-text-color);
+    width: var(--lumo-size-s);
+    height: var(--lumo-size-s);
+    cursor: var(--lumo-clickable-cursor, default);
+    transition: color 140ms;
+  }
+
+  @media (any-hover: hover) {
+    a:hover {
+      color: var(--lumo-header-text-color);
+    }
+
+    button:hover {
+      color: var(--lumo-body-text-color);
+    }
+  }
+
+  a:active:focus {
+    background-color: var(--lumo-contrast-5pct);
+  }
+
+  button::before {
+    font-family: lumo-icons;
+    content: var(--lumo-icons-dropdown);
+    font-size: 1.5em;
+    line-height: var(--lumo-size-s);
+    display: inline-block;
+    transform: rotate(-90deg);
+    transition: transform 140ms;
+  }
+
+  :host([expanded]) button::before {
+    transform: none;
+  }
+
+  @supports selector(:focus-visible) {
+    a,
+    button {
+      outline: none;
+    }
+
+    a:focus-visible,
+    button:focus-visible {
+      border-radius: var(--lumo-border-radius-m);
+      box-shadow: 0 0 0 2px var(--lumo-primary-color-50pct);
+    }
+  }
+
+  a:active {
+    color: var(--lumo-header-text-color);
+  }
+
+  slot:not([name]) {
+    margin: 0 var(--lumo-space-xs);
+  }
+
+  slot[name='prefix']::slotted(:is(vaadin-icon, [class*='icon'])) {
+    color: var(--lumo-contrast-60pct);
+  }
+
+  :host([active]) slot[name='prefix']::slotted(:is(vaadin-icon, [class*='icon'])) {
+    color: inherit;
+  }
+
+  slot[name='children'] {
+    --_child-indent: calc(var(--_child-indent-2, 0px) + var(--vaadin-side-nav-child-indent, var(--lumo-space-l)));
+  }
+
+  slot[name='children']::slotted(*) {
+    --_child-indent-2: var(--_child-indent);
+  }
+
+  :host([active]) a {
+    color: var(--lumo-primary-text-color);
+    background-color: var(--lumo-primary-color-10pct);
+  }
+`;
+
+registerStyles('vaadin-side-nav-item', sideNavItemStyles, { moduleId: 'lumo-side-nav-item' });
+
+export const sideNavStyles = css`
+  :host {
+    font-family: var(--lumo-font-family);
+    font-size: var(--lumo-font-size-m);
+    font-weight: 500;
+    line-height: var(--lumo-line-height-xs);
+    color: var(--lumo-body-text-color);
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  summary {
+    cursor: var(--lumo-clickable-cursor, default);
+    border-radius: var(--lumo-border-radius-m);
+  }
+
+  summary ::slotted([slot='label']) {
+    font-size: var(--lumo-font-size-s);
+    color: var(--lumo-secondary-text-color);
+    margin: var(--lumo-space-s);
+    border-radius: inherit;
+  }
+
+  summary::after {
+    font-family: lumo-icons;
+    color: var(--lumo-tertiary-text-color);
+    font-size: var(--lumo-icon-size-m);
+    width: var(--lumo-size-s);
+    height: var(--lumo-size-s);
+    transition: transform 140ms;
+    margin: 0 var(--lumo-space-xs);
+  }
+
+  :host([collapsible]) summary::after {
+    content: var(--lumo-icons-dropdown);
+  }
+
+  @media (any-hover: hover) {
+    summary:hover::after {
+      color: var(--lumo-body-text-color);
+    }
+  }
+
+  :host([collapsed]) summary::after {
+    transform: rotate(-90deg);
+  }
+
+  @supports selector(:focus-visible) {
+    summary {
+      outline: none;
+    }
+
+    summary:focus-visible {
+      box-shadow: 0 0 0 2px var(--lumo-primary-color-50pct);
+    }
+  }
+`;
+
+registerStyles('vaadin-side-nav', sideNavStyles, { moduleId: 'lumo-side-nav' });

package/theme/lumo/vaadin-side-nav.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import './vaadin-side-nav-item.js';
+import '../../src/vaadin-side-nav.js';

package/theme/material/vaadin-side-nav.js

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import '../../src/vaadin-side-nav.js';
+import '../../src/vaadin-side-nav-item.js';

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

@@ -0,0 +1 @@
+export * from './src/vaadin-side-nav-item.js';

package/vaadin-side-nav-item.js

@@ -0,0 +1,2 @@
+import './theme/lumo/vaadin-side-nav.js';
+export * from './src/vaadin-side-nav-item.js';

package/vaadin-side-nav.d.ts

@@ -0,0 +1 @@
+export * from './src/vaadin-side-nav.js';

package/vaadin-side-nav.js

@@ -0,0 +1,2 @@
+import './theme/lumo/vaadin-side-nav.js';
+export * from './src/vaadin-side-nav.js';