@vaadin/side-nav 24.4.0-dev.223e39f050 → 24.4.0-dev.4b20a0c55

package/README.md

@@ -4,8 +4,7 @@ A web component for navigation menus.
 
 [Documentation + Live Demo ↗](https://vaadin.com/docs/latest/components/side-nav)
 
-[![npm version](https://badgen.net/npm/v/@vaadin/vaadin-side-nav)](https://www.npmjs.com/package/@vaadin/vaadin-side-nav)
-[![Discord](https://img.shields.io/discord/732335336448852018?label=discord)](https://discord.gg/PHmkCKC)
+[![npm version](https://badgen.net/npm/v/@vaadin/side-nav)](https://www.npmjs.com/package/@vaadin/side-nav)
 
 ```html
 <vaadin-side-nav collapsible>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/side-nav",
-  "version": "24.4.0-dev.223e39f050",
+  "version": "24.4.0-dev.4b20a0c55",
   "publishConfig": {
     "access": "public"
   },
@@ -35,11 +35,11 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "24.4.0-dev.223e39f050",
-    "@vaadin/component-base": "24.4.0-dev.223e39f050",
-    "@vaadin/vaadin-lumo-styles": "24.4.0-dev.223e39f050",
-    "@vaadin/vaadin-material-styles": "24.4.0-dev.223e39f050",
-    "@vaadin/vaadin-themable-mixin": "24.4.0-dev.223e39f050",
+    "@vaadin/a11y-base": "24.4.0-dev.4b20a0c55",
+    "@vaadin/component-base": "24.4.0-dev.4b20a0c55",
+    "@vaadin/vaadin-lumo-styles": "24.4.0-dev.4b20a0c55",
+    "@vaadin/vaadin-material-styles": "24.4.0-dev.4b20a0c55",
+    "@vaadin/vaadin-themable-mixin": "24.4.0-dev.4b20a0c55",
     "lit": "^3.0.0"
   },
   "devDependencies": {
@@ -52,5 +52,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "5e2e3bfc811c95aed9354235fab93fdbf43eb354"
+  "gitHead": "b79c81e5f6fd24684b34ee0dc434e94d943ea13e"
 }

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

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2023 Vaadin Ltd.
+ * Copyright (c) 2023 - 2024 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { css } from 'lit';

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

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2023 Vaadin Ltd.
+ * Copyright (c) 2023 - 2024 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';

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

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2023 Vaadin Ltd.
+ * Copyright (c) 2023 - 2024 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';

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

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2023 Vaadin Ltd.
+ * Copyright (c) 2023 - 2024 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { DisabledMixin } from '@vaadin/a11y-base/src/disabled-mixin.js';
@@ -94,12 +94,32 @@ declare class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixi
   expanded: boolean;
 
   /**
-   * 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.
+   * Whether the item's path matches the current browser URL.
+   *
+   * A match occurs when both share the same base origin (like https://example.com),
+   * the same path (like /path/to/page), and the browser URL contains all
+   * the query parameters with the same values from the item's path.
+   *
+   * The state is updated when the item is added to the DOM or when the browser
+   * navigates to a new page.
    */
   readonly current: boolean;
 
+  /**
+   * The target of the link. Works only when `path` is set.
+   */
+  target: string | null | undefined;
+
+  /**
+   * Whether to exclude the item from client-side routing. When enabled,
+   * this causes the item to behave like a regular anchor, causing a full
+   * page reload. This only works with supported routers, such as the one
+   * provided in Vaadin apps, or when using the side nav `onNavigate` hook.
+   *
+   * @attr {boolean} router-ignore
+   */
+  routerIgnore: boolean;
+
   addEventListener<K extends keyof SideNavItemEventMap>(
     type: K,
     listener: (this: SideNavItem, ev: SideNavItemEventMap[K]) => void,

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

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2023 Vaadin Ltd.
+ * Copyright (c) 2023 - 2024 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { html, LitElement } from 'lit';
@@ -115,9 +115,14 @@ class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixin(Themab
       },
 
       /**
-       * 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.
+       * Whether the item's path matches the current browser URL.
+       *
+       * A match occurs when both share the same base origin (like https://example.com),
+       * the same path (like /path/to/page), and the browser URL contains at least
+       * all the query parameters with the same values from the item's path.
+       *
+       * The state is updated when the item is added to the DOM or when the browser
+       * navigates to a new page.
        *
        * @type {boolean}
        */
@@ -127,6 +132,25 @@ class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixin(Themab
         readOnly: true,
         reflectToAttribute: true,
       },
+
+      /**
+       * The target of the link. Works only when `path` is set.
+       */
+      target: String,
+
+      /**
+       * Whether to exclude the item from client-side routing. When enabled,
+       * this causes the item to behave like a regular anchor, causing a full
+       * page reload. This only works with supported routers, such as the one
+       * provided in Vaadin apps, or when using the side nav `onNavigate` hook.
+       *
+       * @type {boolean}
+       * @attr {boolean} router-ignore
+       */
+      routerIgnore: {
+        type: Boolean,
+        value: false,
+      },
     };
   }
 
@@ -184,12 +208,14 @@ class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixin(Themab
     this.__updateCurrent();
 
     window.addEventListener('popstate', this.__boundUpdateCurrent);
+    window.addEventListener('side-nav-location-changed', this.__boundUpdateCurrent);
   }
 
   /** @protected */
   disconnectedCallback() {
     super.disconnectedCallback();
     window.removeEventListener('popstate', this.__boundUpdateCurrent);
+    window.removeEventListener('side-nav-location-changed', this.__boundUpdateCurrent);
   }
 
   /** @protected */
@@ -201,6 +227,8 @@ class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixin(Themab
           ?disabled="${this.disabled}"
           tabindex="${this.disabled || this.path == null ? '-1' : '0'}"
           href="${ifDefined(this.disabled ? null : this.path)}"
+          target="${ifDefined(this.target)}"
+          ?router-ignore="${this.routerIgnore}"
           part="link"
           aria-current="${this.current ? 'page' : 'false'}"
         >
@@ -249,19 +277,33 @@ class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixin(Themab
   __updateCurrent() {
     this._setCurrent(this.__isCurrent());
     if (this.current) {
+      this.__expandParentItems();
       this.expanded = this._items.length > 0;
     }
   }
 
+  /** @private */
+  __expandParentItems() {
+    const parentItem = this.__getParentItem();
+    if (parentItem) {
+      parentItem.__expandParentItems();
+    }
+    this.expanded = true;
+  }
+
+  /** @private */
+  __getParentItem() {
+    return this.parentElement instanceof SideNavItem ? this.parentElement : null;
+  }
+
   /** @private */
   __isCurrent() {
     if (this.path == null) {
       return false;
     }
-    return (
-      matchPaths(document.location.pathname, this.path) ||
-      this.pathAliases.some((alias) => matchPaths(document.location.pathname, alias))
-    );
+
+    const browserPath = `${document.location.pathname}${document.location.search}`;
+    return matchPaths(browserPath, this.path) || this.pathAliases.some((alias) => matchPaths(browserPath, alias));
   }
 }
 

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

@@ -1,12 +1,13 @@
 /**
  * @license
- * Copyright (c) 2023 Vaadin Ltd.
+ * Copyright (c) 2023 - 2024 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { FocusMixin } from '@vaadin/a11y-base/src/focus-mixin.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 import { SideNavChildrenMixin, type SideNavI18n } from './vaadin-side-nav-children-mixin.js';
+import type { SideNavItem } from './vaadin-side-nav-item.js';
 
 export type { SideNavI18n };
 
@@ -21,6 +22,15 @@ export interface SideNavCustomEventMap {
 
 export type SideNavEventMap = HTMLElementEventMap & SideNavCustomEventMap;
 
+export type NavigateEvent = {
+  path: SideNavItem['path'];
+  target: SideNavItem['target'];
+  current: SideNavItem['current'];
+  expanded: SideNavItem['expanded'];
+  pathAliases: SideNavItem['pathAliases'];
+  originalEvent: MouseEvent;
+};
+
 /**
  * `<vaadin-side-nav>` is a Web Component for navigation menus.
  *
@@ -83,6 +93,40 @@ declare class SideNav extends SideNavChildrenMixin(FocusMixin(ElementMixin(Thema
    */
   collapsed: boolean;
 
+  /**
+   * Callback function for router integration.
+   *
+   * When a side nav item link is clicked, this function is called and the default click action is cancelled.
+   * This delegates the responsibility of navigation to the function's logic.
+   *
+   * The click event action is not cancelled in the following cases:
+   * - The click event has a modifier (e.g. `metaKey`, `shiftKey`)
+   * - The click event is on an external link
+   * - The click event is on a link with `target="_blank"`
+   * - The function explicitly returns `false`
+   *
+   * The function receives an object with the properties of the clicked side-nav item:
+   * - `path`: The path of the navigation item.
+   * - `target`: The target of the navigation item.
+   * - `current`: A boolean indicating whether the navigation item is currently selected.
+   * - `expanded`: A boolean indicating whether the navigation item is expanded.
+   * - `pathAliases`: An array of path aliases for the navigation item.
+   * - `originalEvent`: The original DOM event that triggered the navigation.
+   *
+   * Also see the `location` property for updating the highlighted navigation item on route change.
+   */
+  onNavigate?: ((event: NavigateEvent) => boolean) | ((event: NavigateEvent) => void);
+
+  /**
+   * A change to this property triggers an update of the highlighted item in the side navigation. While it typically
+   * corresponds to the browser's URL, the specific value assigned to the property is irrelevant. The component has
+   * its own internal logic for determining which item is highlighted.
+   *
+   * The main use case for this property is when the side navigation is used with a client-side router. In this case,
+   * the component needs to be informed about route changes so it can update the highlighted item.
+   */
+  location: any;
+
   addEventListener<K extends keyof SideNavEventMap>(
     type: K,
     listener: (this: SideNav, ev: SideNavEventMap[K]) => void,

package/src/vaadin-side-nav.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2023 Vaadin Ltd.
+ * Copyright (c) 2023 - 2024 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { html, LitElement } from 'lit';
@@ -103,6 +103,48 @@ class SideNav extends SideNavChildrenMixin(FocusMixin(ElementMixin(ThemableMixin
         notify: true,
         reflectToAttribute: true,
       },
+
+      /**
+       * Callback function for router integration.
+       *
+       * When a side nav item link is clicked, this function is called and the default click action is cancelled.
+       * This delegates the responsibility of navigation to the function's logic.
+       *
+       * The click event action is not cancelled in the following cases:
+       * - The click event has a modifier (e.g. `metaKey`, `shiftKey`)
+       * - The click event is on an external link
+       * - The click event is on a link with `target="_blank"`
+       * - The function explicitly returns `false`
+       *
+       * The function receives an object with the properties of the clicked side-nav item:
+       * - `path`: The path of the navigation item.
+       * - `target`: The target of the navigation item.
+       * - `current`: A boolean indicating whether the navigation item is currently selected.
+       * - `expanded`: A boolean indicating whether the navigation item is expanded.
+       * - `pathAliases`: An array of path aliases for the navigation item.
+       * - `originalEvent`: The original DOM event that triggered the navigation.
+       *
+       * Also see the `location` property for updating the highlighted navigation item on route change.
+       *
+       * @type {function(Object): boolean | undefined}
+       */
+      onNavigate: {
+        attribute: false,
+      },
+
+      /**
+       * A change to this property triggers an update of the highlighted item in the side navigation. While it typically
+       * corresponds to the browser's URL, the specific value assigned to the property is irrelevant. The component has
+       * its own internal logic for determining which item is highlighted.
+       *
+       * The main use case for this property is when the side navigation is used with a client-side router. In this case,
+       * the component needs to be informed about route changes so it can update the highlighted item.
+       *
+       * @type {any}
+       */
+      location: {
+        observer: '__locationChanged',
+      },
     };
   }
 
@@ -114,6 +156,7 @@ class SideNav extends SideNavChildrenMixin(FocusMixin(ElementMixin(ThemableMixin
     super();
 
     this._labelId = `side-nav-label-${generateUniqueId()}`;
+    this.addEventListener('click', this.__onClick);
   }
 
   /**
@@ -203,10 +246,67 @@ class SideNav extends SideNavChildrenMixin(FocusMixin(ElementMixin(ThemableMixin
     }
   }
 
+  /** @private */
+  __locationChanged() {
+    window.dispatchEvent(new CustomEvent('side-nav-location-changed'));
+  }
+
   /** @private */
   __toggleCollapsed() {
     this.collapsed = !this.collapsed;
   }
+
+  /** @private */
+  __onClick(e) {
+    if (!this.onNavigate) {
+      return;
+    }
+
+    const hasModifier = e.metaKey || e.shiftKey;
+    if (hasModifier) {
+      // Allow default action for clicks with modifiers
+      return;
+    }
+
+    const composedPath = e.composedPath();
+    const item = composedPath.find((el) => el.localName && el.localName.includes('side-nav-item'));
+    const anchor = composedPath.find((el) => el instanceof HTMLAnchorElement);
+    if (!item || !item.shadowRoot.contains(anchor)) {
+      // Not a click on a side-nav-item anchor
+      return;
+    }
+
+    const isRelative = anchor.href && anchor.href.startsWith(location.origin);
+    if (!isRelative) {
+      // Allow default action for external links
+      return;
+    }
+
+    if (item.target === '_blank') {
+      // Allow default action for links with target="_blank"
+      return;
+    }
+
+    if (item.routerIgnore) {
+      // Allow default action when client-side routing is ignored
+      return;
+    }
+
+    // Call the onNavigate callback
+    const result = this.onNavigate({
+      path: item.path,
+      target: item.target,
+      current: item.current,
+      expanded: item.expanded,
+      pathAliases: item.pathAliases,
+      originalEvent: e,
+    });
+
+    if (result !== false) {
+      // Cancel the default action if the callback didn't return false
+      e.preventDefault();
+    }
+  }
 }
 
 defineCustomElement(SideNav);

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

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

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

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

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

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

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

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