feat: adapt navigation to support sub-navigation with and without landing page

Author: michaelmkraus

app.navigation.ts

@@ -3,7 +3,7 @@ export const appNavigation: AppNavigation = [
     title: "Products & Services",
     children: [
       { title: "Foundations", path: "products-and-services/foundations" },
-      { title: "Components & Patterns", path: "products-and-services/components-and-patterns", },
+      { title: "Components & Patterns", path: "products-and-services/components-and-patterns" },
       { title: "Templates", path: "products-and-services/templates" },
       { title: "Extensions", path: "products-and-services/extensions" },
     ],
@@ -13,9 +13,11 @@ export const appNavigation: AppNavigation = [
     children: [
       {
         title: "Documentation",
+        path: "resources/documentation",
+        isSubNavigation: true,
         children: [
-          { title: "Getting Started", path: "resources/documentation/getting-started", },
-          { title: "Foundations", path: "resources/documentation/foundations", },
+          { title: "Getting Started", path: "resources/documentation/getting-started" },
+          { title: "Foundations", path: "resources/documentation/foundations" },
         ],
       },
     ],

content/pages/resources/documentation/index.md

@@ -0,0 +1,7 @@
+---
+layout: "@template/layouts/default"
+title: "Documentation"
+toc: false
+---
+
+XXX

template/layouts/default/shell/control-panel/nav-item.tsx

@@ -1,37 +1,50 @@
-
-import {
-  DBNavigationItem,
-  DBNavigationItemGroup,
-} from "@db-ux/react-core-components";
+import { DBNavigationItem, DBNavigationItemGroup } from "@db-ux/react-core-components";
 import { getAriaCurrent } from "@template/utils/client.utils.ts";
+import { covers, getFirstChildPath } from "@template/utils/navigation.utils.ts";
+
+const NavItem = ({ path, title, icon, iconTrailing, children, isSubNavigation }: NavigationItem) => {
+    // if sub-navigation node, do not render children here
+    if (isSubNavigation) {
+        const target = path ?? getFirstChildPath(children);
+        const currentPath = typeof window !== "undefined" ? window.location.pathname : "/";
+        const isActive = covers({ path, title, icon, iconTrailing, children, isSubNavigation }, currentPath);
+
+        return (
+            <DBNavigationItem icon={icon} key={`router-leaf-${target ?? title}`}>
+                <a
+                    href={target}
+                    aria-current={isActive ? "page" : undefined}
+                    data-icon-trailing={iconTrailing}
+                >
+                    {title}
+                </a>
+            </DBNavigationItem>
+        );
+    }
 
-const NavItem = ({
-  path,
-  title,
-  icon,iconTrailing,
-  children,
-}: NavigationItem) => {
-  if (children) {
+    // node with children
+    if (children && children.length > 0) {
+        return (
+            <DBNavigationItemGroup text={title} key={`router-group-${path ?? title}`}>
+                {children.map((subItem) => (
+                    <NavItem key={`router-sub-path-${subItem.path ?? subItem.title}`} {...subItem} />
+                ))}
+            </DBNavigationItemGroup>
+        );
+    }
+
+    // leaf-node, no children
     return (
-      <DBNavigationItemGroup text={title} key={`router-path-${path}-${title}`}>
-        {children.map((subItem) => (
-          <NavItem key={`router-sub-path-${subItem.path}`} {...subItem} />
-        ))}
-      </DBNavigationItemGroup>
+        <DBNavigationItem icon={icon} key={`router-leaf-${path ?? title}`}>
+            <a
+                href={path}
+                aria-current={path ? getAriaCurrent(path) : undefined}
+                data-icon-trailing={iconTrailing}
+            >
+                {title}
+            </a>
+        </DBNavigationItem>
     );
-  }
-
-  return (
-    <DBNavigationItem icon={icon} key={`router-path-${path}-${title}`}>
-      <a
-        href={path}
-        aria-current={getAriaCurrent(path)}
-        data-icon-trailing={iconTrailing}
-      >
-        {title}
-      </a>
-    </DBNavigationItem>
-  );
 };
 
 export default NavItem;

template/types/global.d.ts

@@ -43,11 +43,11 @@ declare interface NavigationItem {
    * The title of the navigation item.
    */
   title: string;
-  /*
+  /**
    * An optional icon that can be used to represent the navigation item.
    */
   icon?: string;
-  /*
+  /**
    * An optional icon that can be used to represent the navigation item.
    */
   iconTrailing?: string;
@@ -62,9 +62,9 @@ declare interface NavigationItem {
    */
   children?: NavigationItem[];
   /**
-   * An optional sub navigation.
+   * If true, the children will be rendered as sub-navigation items.
    */
-  subNavigation?: NavigationItem[];
+  isSubNavigation?: boolean;
 }
 
 /**

template/utils/navigation.utils.ts

@@ -2,56 +2,106 @@ import { appConfig } from "@root/app.config";
 import { appNavigation } from "@root/app.navigation";
 
 /**
- * Returns the parent of a navigation item based on the given pathname.
- * @param pathname - The pathname to find the parent for.
- * @returns The parent navigation item or undefined if none is found.
+ * Normalizes a path by removing trailing slashes.
+ *
+ * @param path - The path to normalize
+ * @returns The normalized path without trailing slashes
  */
-export function getNavigationItemParent(
-  pathname: string,
-): NavigationItem | undefined {
-  const { basePath } = appConfig;
-  const _pathname = pathname.replace(/\/+$/, "");
-
-  return appNavigation.filter((item) => {
-    const children = [...(item.children ?? []), ...(item.subNavigation ?? [])];
-    if (children.length > 0) {
-      return children.some((child) => {
-        const fullPath = `${basePath}${child.path}`.replace(/\/+$/, "");
-        return fullPath === _pathname;
-      });
-    }
-    return false;
-  })[0];
+const norm = (path: string) => path.replace(/\/+$/, "");
+
+/**
+ * Prepends the base path to a relative path and normalizes the result.
+ *
+ * @param relPath - The relative path to prepend the base path to
+ * @returns The normalized absolute path including the base path
+ */
+function withBase(relPath: string) {
+  const base = norm(appConfig.basePath || "/");
+  const rel = relPath.startsWith("/") ? relPath : `/${relPath}`;
+  return norm(`${base}${rel}`);
 }
 
 /**
- * Recursively searches for a subNavigation array with at least one entry for the given pathname.
- * @param pathname - The pathname to check.
- * @returns The subNavigation array if found, otherwise undefined.
+ * Returns the path of the first child navigation item, if any.
+ * @param children - An array of navigation items.
+ * @returns The path of the first child navigation item or undefined if there are no children.
  */
-export function findSubNavigation(
-  pathname: string,
-): NavigationItem[] | undefined {
-  const { basePath } = appConfig;
-  const _pathname = pathname.replace(/\/+$/, "");
+export function getFirstChildPath(children?: NavigationItem[]): string | undefined {
+  return children && children.length > 0 ? children[0]?.path : undefined;
+}
+
+/**
+ * Checks if a navigation item or any of its descendants covers the current path.
+ * A path is considered "covered" if it either exactly matches or is a sub-path of the navigation item's path.
+ *
+ * @param item - The navigation item to check
+ * @param currentPath - The current path to compare against
+ * @returns {boolean} True if the item or its descendants cover the current path, false otherwise
+ */
+export function covers(item: NavigationItem, currentPath: string): boolean {
+  if (item.path) {
+    const full = withBase(item.path);
+    if (currentPath === full || currentPath.startsWith(full + "/")) return true;
+  }
+  for (const child of item.children ?? []) {
+    if (covers(child, currentPath)) return true;
+  }
+  return false;
+}
 
-  function checkRecursive(item: NavigationItem | undefined): NavigationItem[] | undefined {
-    if (!item) return undefined;
-    const fullPath = `${basePath}${item.path}`.replace(/\/+$/, "");
-    if (fullPath === _pathname && Array.isArray(item.subNavigation) && item.subNavigation.length > 0) {
-      return item.subNavigation;
+/**
+ * Finds the children of the deepest sub-navigation item that covers the current pathname.
+ *
+ * @param currentPathname - The current pathname to find sub-navigation for
+ * @returns An array of navigation items if a matching sub-navigation is found, undefined otherwise
+ */
+export function findSubNavigation(currentPathname: string): NavigationItem[] | undefined {
+  const current = norm(currentPathname);
+  let match: { node: NavigationItem; depth: number } | undefined;
+
+  const walk = (node: NavigationItem, depth: number) => {
+    if (node.isSubNavigation && covers(node, current)) {
+      if (!match || depth > match.depth) match = { node, depth };
     }
-    const children = [...(item.children ?? []), ...(item.subNavigation ?? [])];
-    for (const child of children) {
-      const result = checkRecursive(child);
-      if (result) return result;
+    for (const child of node.children ?? []) walk(child, depth + 1);
+  };
+
+  for (const top of appNavigation) walk(top, 0);
+  return match?.node.children;
+}
+
+/**
+* Finds the parent navigation item for a given pathname.
+*
+* @param pathname - The pathname to find the parent for
+* @returns The parent navigation item if found, undefined otherwise
+*/
+export function getNavigationItemParent(pathname: string): NavigationItem | undefined {
+  const { basePath } = appConfig;
+  const norm = (p: string) => p.replace(/\/+$/, "");
+  const _pathname = norm(pathname);
+
+  const withBase = (relPath?: string) => {
+    if (!relPath) return undefined;
+    const base = norm(basePath || "/");
+    const rel = relPath.startsWith("/") ? relPath : `/${relPath}`;
+    return norm(`${base}${rel}`);
+  };
+
+  const findParent = (nodes: NavigationItem[]): NavigationItem | undefined => {
+    for (const node of nodes) {
+      const children = node.children ?? [];
+      for (const child of children) {
+        const full = withBase(child.path);
+        if (full && full === _pathname) {
+          return node;
+        }
+      }
+      const found = findParent(children);
+      if (found) return found;
     }
     return undefined;
-  }
+  };
 
-  for (const navItem of appNavigation) {
-    const result = checkRecursive(navItem);
-    if (result) return result;
-  }
-  return undefined;
+  return findParent(appNavigation);
 }