@vaadin/side-nav 24.4.0-alpha9 → 24.4.0-beta2

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-alpha9",
+  "version": "24.4.0-beta2",
   "publishConfig": {
     "access": "public"
   },
@@ -35,11 +35,11 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/a11y-base": "24.4.0-alpha9",
-    "@vaadin/component-base": "24.4.0-alpha9",
-    "@vaadin/vaadin-lumo-styles": "24.4.0-alpha9",
-    "@vaadin/vaadin-material-styles": "24.4.0-alpha9",
-    "@vaadin/vaadin-themable-mixin": "24.4.0-alpha9",
+    "@vaadin/a11y-base": "24.4.0-beta2",
+    "@vaadin/component-base": "24.4.0-beta2",
+    "@vaadin/vaadin-lumo-styles": "24.4.0-beta2",
+    "@vaadin/vaadin-material-styles": "24.4.0-beta2",
+    "@vaadin/vaadin-themable-mixin": "24.4.0-beta2",
     "lit": "^3.0.0"
   },
   "devDependencies": {
@@ -52,5 +52,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "effb81abe3c6283a6ec620cc0cee56069af58226"
+  "gitHead": "886ab2e7ccb8353ac3b7a42ebb96dfe2d1211556"
 }

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

@@ -94,9 +94,14 @@ 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;
 
@@ -105,6 +110,16 @@ declare class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixi
    */
   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

@@ -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}
        */
@@ -132,6 +137,20 @@ class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixin(Themab
        * 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,
+      },
     };
   }
 
@@ -189,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 */
@@ -207,6 +228,7 @@ class SideNavItem extends SideNavChildrenMixin(DisabledMixin(ElementMixin(Themab
           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'}"
         >
@@ -255,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

@@ -7,6 +7,7 @@ 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

@@ -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/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/side-nav",
-  "version": "24.4.0-alpha9",
+  "version": "24.4.0-beta2",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -52,6 +52,15 @@
                 ]
               }
             },
+            {
+              "name": "router-ignore",
+              "description": "Whether to exclude the item from client-side routing. When enabled,\nthis causes the item to behave like a regular anchor, causing a full\npage reload. This only works with supported routers, such as the one\nprovided in Vaadin apps, or when using the side nav `onNavigate` hook.",
+              "value": {
+                "type": [
+                  "boolean"
+                ]
+              }
+            },
             {
               "name": "theme",
               "description": "The theme variants to apply to the component.",
@@ -125,6 +134,15 @@
                     "undefined"
                   ]
                 }
+              },
+              {
+                "name": "routerIgnore",
+                "description": "Whether to exclude the item from client-side routing. When enabled,\nthis causes the item to behave like a regular anchor, causing a full\npage reload. This only works with supported routers, such as the one\nprovided in Vaadin apps, or when using the side nav `onNavigate` hook.",
+                "value": {
+                  "type": [
+                    "boolean"
+                  ]
+                }
               }
             ],
             "events": [
@@ -157,6 +175,25 @@
                 ]
               }
             },
+            {
+              "name": "on-navigate",
+              "description": "Callback function for router integration.\n\nWhen a side nav item link is clicked, this function is called and the default click action is cancelled.\nThis delegates the responsibility of navigation to the function's logic.\n\nThe click event action is not cancelled in the following cases:\n- The click event has a modifier (e.g. `metaKey`, `shiftKey`)\n- The click event is on an external link\n- The click event is on a link with `target=\"_blank\"`\n- The function explicitly returns `false`\n\nThe function receives an object with the properties of the clicked side-nav item:\n- `path`: The path of the navigation item.\n- `target`: The target of the navigation item.\n- `current`: A boolean indicating whether the navigation item is currently selected.\n- `expanded`: A boolean indicating whether the navigation item is expanded.\n- `pathAliases`: An array of path aliases for the navigation item.\n- `originalEvent`: The original DOM event that triggered the navigation.\n\nAlso see the `location` property for updating the highlighted navigation item on route change.",
+              "value": {
+                "type": [
+                  "function Object: boolean",
+                  "undefined"
+                ]
+              }
+            },
+            {
+              "name": "location",
+              "description": "A change to this property triggers an update of the highlighted item in the side navigation. While it typically\ncorresponds to the browser's URL, the specific value assigned to the property is irrelevant. The component has\nits own internal logic for determining which item is highlighted.\n\nThe main use case for this property is when the side navigation is used with a client-side router. In this case,\nthe component needs to be informed about route changes so it can update the highlighted item.",
+              "value": {
+                "type": [
+                  "any"
+                ]
+              }
+            },
             {
               "name": "theme",
               "description": "The theme variants to apply to the component.",
@@ -197,6 +234,25 @@
                     "boolean"
                   ]
                 }
+              },
+              {
+                "name": "onNavigate",
+                "description": "Callback function for router integration.\n\nWhen a side nav item link is clicked, this function is called and the default click action is cancelled.\nThis delegates the responsibility of navigation to the function's logic.\n\nThe click event action is not cancelled in the following cases:\n- The click event has a modifier (e.g. `metaKey`, `shiftKey`)\n- The click event is on an external link\n- The click event is on a link with `target=\"_blank\"`\n- The function explicitly returns `false`\n\nThe function receives an object with the properties of the clicked side-nav item:\n- `path`: The path of the navigation item.\n- `target`: The target of the navigation item.\n- `current`: A boolean indicating whether the navigation item is currently selected.\n- `expanded`: A boolean indicating whether the navigation item is expanded.\n- `pathAliases`: An array of path aliases for the navigation item.\n- `originalEvent`: The original DOM event that triggered the navigation.\n\nAlso see the `location` property for updating the highlighted navigation item on route change.",
+                "value": {
+                  "type": [
+                    "function Object: boolean",
+                    "undefined"
+                  ]
+                }
+              },
+              {
+                "name": "location",
+                "description": "A change to this property triggers an update of the highlighted item in the side navigation. While it typically\ncorresponds to the browser's URL, the specific value assigned to the property is irrelevant. The component has\nits own internal logic for determining which item is highlighted.\n\nThe main use case for this property is when the side navigation is used with a client-side router. In this case,\nthe component needs to be informed about route changes so it can update the highlighted item.",
+                "value": {
+                  "type": [
+                    "any"
+                  ]
+                }
               }
             ],
             "events": [

package/web-types.lit.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@vaadin/side-nav",
-  "version": "24.4.0-alpha9",
+  "version": "24.4.0-beta2",
   "description-markup": "markdown",
   "framework": "lit",
   "framework-config": {
@@ -33,6 +33,13 @@
                 "kind": "expression"
               }
             },
+            {
+              "name": "?routerIgnore",
+              "description": "Whether to exclude the item from client-side routing. When enabled,\nthis causes the item to behave like a regular anchor, causing a full\npage reload. This only works with supported routers, such as the one\nprovided in Vaadin apps, or when using the side nav `onNavigate` hook.",
+              "value": {
+                "kind": "expression"
+              }
+            },
             {
               "name": ".i18n",
               "description": "The object used to localize this component.\n\nTo change the default localization, replace the entire\n`i18n` object with a custom one.\n\nThe object has the following structure and default values:\n```\n{\n  toggle: 'Toggle child items'\n}\n```",
@@ -89,6 +96,13 @@
                 "kind": "expression"
               }
             },
+            {
+              "name": "?onNavigate",
+              "description": "Callback function for router integration.\n\nWhen a side nav item link is clicked, this function is called and the default click action is cancelled.\nThis delegates the responsibility of navigation to the function's logic.\n\nThe click event action is not cancelled in the following cases:\n- The click event has a modifier (e.g. `metaKey`, `shiftKey`)\n- The click event is on an external link\n- The click event is on a link with `target=\"_blank\"`\n- The function explicitly returns `false`\n\nThe function receives an object with the properties of the clicked side-nav item:\n- `path`: The path of the navigation item.\n- `target`: The target of the navigation item.\n- `current`: A boolean indicating whether the navigation item is currently selected.\n- `expanded`: A boolean indicating whether the navigation item is expanded.\n- `pathAliases`: An array of path aliases for the navigation item.\n- `originalEvent`: The original DOM event that triggered the navigation.\n\nAlso see the `location` property for updating the highlighted navigation item on route change.",
+              "value": {
+                "kind": "expression"
+              }
+            },
             {
               "name": ".i18n",
               "description": "The object used to localize this component.\n\nTo change the default localization, replace the entire\n`i18n` object with a custom one.\n\nThe object has the following structure and default values:\n```\n{\n  toggle: 'Toggle child items'\n}\n```",
@@ -96,6 +110,13 @@
                 "kind": "expression"
               }
             },
+            {
+              "name": ".location",
+              "description": "A change to this property triggers an update of the highlighted item in the side navigation. While it typically\ncorresponds to the browser's URL, the specific value assigned to the property is irrelevant. The component has\nits own internal logic for determining which item is highlighted.\n\nThe main use case for this property is when the side navigation is used with a client-side router. In this case,\nthe component needs to be informed about route changes so it can update the highlighted item.",
+              "value": {
+                "kind": "expression"
+              }
+            },
             {
               "name": "@collapsed-changed",
               "description": "Fired when the `collapsed` property changes.",