feat(router): add user-defined detail type to ViewConfig (#3431)

Author: cromoteca

packages/ts/file-router/src/runtime/createMenuItems.ts

@@ -23,7 +23,7 @@ function hasVariablePathSegment(path: string): boolean {
  *
  * @returns A list of menu items.
  */
-export function createMenuItems(): readonly MenuItem[] {
+export function createMenuItems<T = unknown>(): ReadonlyArray<MenuItem<T>> {
   // @ts-expect-error: esbuild injection
   // eslint-disable-next-line @typescript-eslint/no-unsafe-call
   __REGISTER__('createMenuItems', (window as VaadinWindow).Vaadin);
@@ -44,6 +44,7 @@ export function createMenuItems(): readonly MenuItem[] {
         icon: config.menu?.icon,
         title: config.menu?.title ?? config.title,
         order: config.menu?.order,
+        detail: config.detail as T | undefined,
       }))
       // Sort views according to the order specified in the view configuration.
       .sort((menuA, menuB) => {

packages/ts/file-router/src/shared/internal.ts

@@ -5,11 +5,11 @@ import type { RouteParamType } from './routeParamType.js';
  * Internal type used for server communication and menu building. It extends the
  * view configuration with the route parameters.
  */
-export type ServerViewConfig = Readonly<{
+export type ServerViewConfig<T = unknown> = Readonly<{
   children?: readonly ServerViewConfig[];
   params?: Readonly<Record<string, RouteParamType>>;
 }> &
-  ViewConfig;
+  ViewConfig<T>;
 
 export type VaadinObject = Readonly<{
   views: Readonly<Record<string, ViewConfig>>;

packages/ts/file-router/src/types.ts

@@ -1,6 +1,12 @@
 import type { createBrowserRouter, RouteObject } from 'react-router';
 
-export type ViewConfig = Readonly<{
+/**
+ * A configuration object for a view. This is used to define the view's
+ * metadata, such as the title, roles allowed, and other properties.
+ *
+ * @typeParam T - The type of the detail object.
+ */
+export type ViewConfig<T = unknown> = Readonly<{
   /**
    * View title used in the main layout header, as <title> and as the default
    * for the menu entry. If not defined, the component name will be taken,
@@ -59,6 +65,14 @@ export type ViewConfig = Readonly<{
      */
     icon?: string;
   }>;
+
+  /**
+   * Used to add additional properties to the view. This object will be
+   * available when building the menu.
+   *
+   * @see {@link ./runtime/createMenuItems.ts#createMenuItems}
+   */
+  detail?: T;
 }>;
 
 /**
@@ -87,11 +101,14 @@ export type AgnosticRoute = Readonly<{
 
 /**
  * A menu item used in for building the navigation menu.
+ *
+ * @typeParam T - The type of the detail object, same as in the view configuration.
  */
-export type MenuItem = Readonly<{
+export type MenuItem<T = unknown> = Readonly<{
   to: string;
   icon?: string;
   title?: string;
+  detail?: T;
 }>;
 
 export type RouterConfiguration = Readonly<{

packages/ts/file-router/test/runtime/createMenuItems.spec.ts

@@ -1,6 +1,7 @@
 import './vaadinGlobals.js'; // eslint-disable-line import/no-unassigned-import
 import { expect, describe, it } from 'vitest';
 import { createMenuItems, viewsSignal } from '../../src/runtime/createMenuItems.js';
+import type { ViewConfig } from '../../src/types.js';
 import { deepRemoveNullProps } from '../utils.js';
 
 const collator = new Intl.Collator('en-US');
@@ -165,5 +166,34 @@ describe('@vaadin/hilla-file-router', () => {
         },
       ]);
     });
+
+    it('should include detail objects in menu items', () => {
+      // used to check that the type of the detail object is correct
+      // this is a compile-time check, does nothing at runtime
+      type Detail = {
+        foo: string;
+        bar?: number;
+      };
+
+      const views: Record<string, ViewConfig<Detail>> = {
+        '/bar': { title: 'Bar', detail: { foo: '1', bar: 2 } },
+        '/foo': { title: 'Foo', detail: { foo: '3' } },
+      };
+      viewsSignal.value = views;
+
+      const items = createMenuItems<Detail>();
+      expect(deepRemoveNullProps(items)).to.be.deep.equal([
+        {
+          title: 'Bar',
+          to: '/bar',
+          detail: { foo: '1', bar: 2 },
+        },
+        {
+          title: 'Foo',
+          to: '/foo',
+          detail: { foo: '3' },
+        },
+      ]);
+    });
   });
 });