From 8eb83d13ecb291983070ee36e37e1928025f4852 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 16 Oct 2026 12:48:27 +0000
Subject: [PATCH 1/5] feat(apollo-vertex): backport invoice shell nav

Let a nav group link to a default child and stay active for its
prefix, while the matching child keeps the current pill. Resolve
nav labels from the app catalog before the vertex catalog.

Also let LocaleProvider take the app i18n init, keep ApolloShell on
the loading skeleton until the token query finishes, paint the
sidebar hairline with var(--border), and name the collapse button.
---
 .../content/docs/patterns/shell.mdx           |  25 ++-
 packages/apollo-vertex/registry.json          |   8 +
 .../registry/shell/shell-company.tsx          |   3 +-
 .../registry/shell/shell-locale-provider.tsx  |  18 +-
 .../registry/shell/shell-minimal-nav-item.tsx |   4 +-
 .../registry/shell/shell-nav-active.test.tsx  | 145 ++++++++++++++
 .../registry/shell/shell-nav-active.ts        |  30 +++
 .../registry/shell/shell-nav-label.ts         |  67 +++++++
 .../registry/shell/shell-sidebar.tsx          | 188 +++++++++---------
 .../registry/shell/shell-text.tsx             |   9 +-
 .../registry/shell/shell-translation-key.ts   |   6 +
 .../apollo-vertex/registry/shell/shell.tsx    |  33 ++-
 12 files changed, 421 insertions(+), 115 deletions(-)
 create mode 100644 packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
 create mode 100644 packages/apollo-vertex/registry/shell/shell-nav-active.ts
 create mode 100644 packages/apollo-vertex/registry/shell/shell-nav-label.ts

diff --git a/apps/apollo-vertex/content/docs/patterns/shell.mdx b/apps/apollo-vertex/content/docs/patterns/shell.mdx
index 51af506f41..0e966535b5 100644
--- a/apps/apollo-vertex/content/docs/patterns/shell.mdx
+++ b/apps/apollo-vertex/content/docs/patterns/shell.mdx
@@ -52,12 +52,35 @@ function App() {
 }
 ```
 
+## Nested navigation
+
+A group can set `to` and `subItems`. The row links to `to`, or to `path` when `to` is omitted, and stays in the active color for `path` and every route under it. The matching child gets the current background. While the sidebar is collapsed, that background stays off the parent: the parent icon keeps the active color.
+
+Labels are translation keys. A key in the app's default catalog is used first, including keys that are not in Apollo Vertex. Vertex keys such as `dashboard` still resolve when the app catalog does not define them.
+
+```tsx
+{
+  path: '/rules',
+  to: '/rules/exceptions',
+  label: 'rules',
+  icon: ListTree,
+  subItems: [
+    { path: '/rules/feedback', label: 'feedback' },
+    { path: '/rules/exceptions', label: 'exceptions' },
+  ],
+}
+```
+
+## App translations
+
+Pass `configureI18n` to `ApolloShell` or `LocaleProvider` when the app initializes i18next itself. The shell then runs that function instead of replacing the app catalog with the Vertex one.
+
 ## Adding Authentication
 
 To enable built-in OAuth2 authentication with PKCE, wrap the shell with `ShellAuthProvider`.
 Both `ShellAuthProvider` and `ApolloShell` must be inside a `QueryClientProvider` from `@tanstack/react-query`.
 
-When a `ShellAuthProvider` is present, the shell automatically shows a login screen until the user is authenticated.
+When a `ShellAuthProvider` is present, the shell automatically shows a login screen until the user is authenticated. While the token is still loading, it shows the loading skeleton instead of that login screen.
 
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
diff --git a/packages/apollo-vertex/registry.json b/packages/apollo-vertex/registry.json
index 64fca8247a..2399496085 100644
--- a/packages/apollo-vertex/registry.json
+++ b/packages/apollo-vertex/registry.json
@@ -2406,6 +2406,14 @@
           "path": "registry/shell/shell-sidebar.tsx",
           "type": "registry:ui"
         },
+        {
+          "path": "registry/shell/shell-nav-active.ts",
+          "type": "registry:ui"
+        },
+        {
+          "path": "registry/shell/shell-nav-label.ts",
+          "type": "registry:ui"
+        },
         {
           "path": "registry/shell/shell-company.tsx",
           "type": "registry:ui"
diff --git a/packages/apollo-vertex/registry/shell/shell-company.tsx b/packages/apollo-vertex/registry/shell/shell-company.tsx
index 28eb021202..ea0cd790c5 100644
--- a/packages/apollo-vertex/registry/shell/shell-company.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-company.tsx
@@ -2,7 +2,6 @@ import { Link } from "@tanstack/react-router";
 import { AnimatePresence, motion } from "framer-motion";
 import { PanelLeft } from "lucide-react";
 import { useState } from "react";
-import { useVertexTranslation } from "@/lib/vertex-translation";
 import { Button } from "@/components/ui/button";
 import { useSidebar } from "@/components/ui/sidebar";
 import {
@@ -12,6 +11,7 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip";
 import { cn } from "@/lib/utils";
+import { useVertexTranslation } from "@/lib/vertex-translation";
 import type { CompanyLogo } from "./shell";
 import {
   fastFadeTransition,
@@ -187,6 +187,7 @@ export const Company = ({
                   <Button
                     variant="ghost"
                     size="icon-sm"
+                    aria-label={t("close_sidebar")}
                     onClick={toggleSidebar}
                     className="ml-auto shrink-0 text-sidebar-foreground/70 hover:bg-sidebar-accent hover:text-sidebar-foreground cursor-pointer"
                   >
diff --git a/packages/apollo-vertex/registry/shell/shell-locale-provider.tsx b/packages/apollo-vertex/registry/shell/shell-locale-provider.tsx
index 5e22ea6c93..526c4be14a 100644
--- a/packages/apollo-vertex/registry/shell/shell-locale-provider.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-locale-provider.tsx
@@ -7,13 +7,14 @@ import {
   useEffectEvent,
   useState,
 } from "react";
-import { useVertexTranslation } from "@/lib/vertex-translation";
 import { Spinner } from "@/components/ui/spinner";
 import { configurei18n } from "@/lib/i18n";
+import { useVertexTranslation } from "@/lib/vertex-translation";
 import { LANGUAGE_CHANGED_EVENT } from "./shell-constants";
 
 interface LocaleProviderProps {
   loadingElement?: ReactNode;
+  configureI18n?: () => Promise<void>;
 }
 
 export const LocaleProviderComponent = ({ children }: PropsWithChildren) => {
@@ -50,16 +51,19 @@ export const LocaleProviderComponent = ({ children }: PropsWithChildren) => {
 export const LocaleProvider = ({
   children,
   loadingElement,
+  configureI18n = configurei18n,
 }: PropsWithChildren<LocaleProviderProps>) => {
   const [isConfigured, setIsConfigured] = useState(false);
-  const configure = async () => {
-    await configurei18n();
-    setIsConfigured(true);
-  };
 
   useEffect(() => {
-    void configure();
-  }, []);
+    let cancelled = false;
+    void configureI18n().then(() => {
+      if (!cancelled) setIsConfigured(true);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [configureI18n]);
 
   if (!isConfigured)
     return (
diff --git a/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx b/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
index 04c1ebde89..f8abcff598 100644
--- a/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
@@ -1,11 +1,11 @@
 import { Link, useLocation } from "@tanstack/react-router";
 import { cn } from "@/lib/utils";
 import { Text } from "./shell-text";
-import type { TranslationKey } from "./shell-translation-key";
+import type { ShellNavLabel } from "./shell-translation-key";
 
 interface MinimalNavItemProps {
   to: string;
-  label: TranslationKey;
+  label: ShellNavLabel;
 }
 
 export const MinimalNavItem = ({ to, label }: MinimalNavItemProps) => {
diff --git a/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx b/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
new file mode 100644
index 0000000000..7978bd261a
--- /dev/null
+++ b/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
@@ -0,0 +1,145 @@
+import { describe, expect, it } from "vitest";
+import { VERTEX_NAMESPACE } from "@/lib/vertex-translation";
+import {
+  navItemIsCurrent,
+  navItemState,
+  navPathIsActive,
+} from "./shell-nav-active";
+import { type NavCatalog, readNavLabel } from "./shell-nav-label";
+
+describe("navPathIsActive", () => {
+  it("matches the path and its nested pages", () => {
+    expect(navPathIsActive("/rules/exceptions", "/rules/exceptions")).toBe(
+      true,
+    );
+    expect(
+      navPathIsActive(
+        "/rules/exceptions/currency-mismatch",
+        "/rules/exceptions",
+      ),
+    ).toBe(true);
+  });
+
+  it("does not match a sibling page", () => {
+    expect(navPathIsActive("/rules/feedback", "/rules/exceptions")).toBe(false);
+    expect(navPathIsActive("/rules/feedback/abc", "/rules/exceptions")).toBe(
+      false,
+    );
+  });
+
+  it("keeps a parent prefix active on nested child pages", () => {
+    expect(navPathIsActive("/rules/exceptions", "/rules")).toBe(true);
+    expect(navPathIsActive("/rules/feedback", "/rules")).toBe(true);
+  });
+
+  it("matches the root only exactly", () => {
+    expect(navPathIsActive("/", "/")).toBe(true);
+    expect(navPathIsActive("/dashboard", "/")).toBe(false);
+  });
+});
+
+describe("navItemIsCurrent", () => {
+  const invoiceChildren = ["/invoices/rejected"];
+
+  it("marks a parent page current on its own pages", () => {
+    expect(navItemIsCurrent("/invoices", "/invoices", invoiceChildren)).toBe(
+      true,
+    );
+    expect(
+      navItemIsCurrent("/invoices/abc-123", "/invoices", invoiceChildren),
+    ).toBe(true);
+  });
+
+  it("hands current to the child on the child's page", () => {
+    expect(
+      navItemIsCurrent("/invoices/rejected", "/invoices", invoiceChildren),
+    ).toBe(false);
+    expect(navItemIsCurrent("/invoices/rejected", "/invoices/rejected")).toBe(
+      true,
+    );
+  });
+
+  it("keeps a group parent like Rules off while a child is open", () => {
+    expect(
+      navItemIsCurrent("/rules/exceptions", "/rules", [
+        "/rules/feedback",
+        "/rules/exceptions",
+      ]),
+    ).toBe(false);
+  });
+});
+
+describe("navItemState", () => {
+  it("links a group to its default child and keeps the prefix active", () => {
+    expect(
+      navItemState("/rules/exceptions", {
+        path: "/rules",
+        to: "/rules/exceptions",
+        childPaths: ["/rules/feedback", "/rules/exceptions"],
+      }),
+    ).toEqual({
+      href: "/rules/exceptions",
+      prefixActive: true,
+      current: false,
+    });
+  });
+
+  it("uses path as the link when the group has no default child", () => {
+    expect(
+      navItemState("/invoices", {
+        path: "/invoices",
+        childPaths: ["/invoices/rejected"],
+      }).href,
+    ).toBe("/invoices");
+  });
+});
+
+function catalog(bundles: Record<string, Record<string, string>>): NavCatalog {
+  return {
+    defaultNamespace: "translation",
+    exists: (key, namespace) => Object.hasOwn(bundles[namespace] ?? {}, key),
+    translate: (key, namespace) => bundles[namespace]?.[key] ?? key,
+  };
+}
+
+describe("readNavLabel", () => {
+  it("reads an app key that is not in the vertex catalog", () => {
+    expect(
+      readNavLabel(
+        catalog({
+          translation: { queue: "My work" },
+          [VERTEX_NAMESPACE]: { dashboard: "Dashboard" },
+        }),
+        "queue",
+      ),
+    ).toBe("My work");
+  });
+
+  it("prefers the app catalog when both define the key", () => {
+    expect(
+      readNavLabel(
+        catalog({
+          translation: { dashboard: "Home" },
+          [VERTEX_NAMESPACE]: { dashboard: "Dashboard" },
+        }),
+        "dashboard",
+      ),
+    ).toBe("Home");
+  });
+
+  it("falls back to the vertex catalog", () => {
+    expect(
+      readNavLabel(
+        catalog({
+          translation: {},
+          [VERTEX_NAMESPACE]: { dashboard: "Dashboard" },
+        }),
+        "dashboard",
+      ),
+    ).toBe("Dashboard");
+  });
+
+  it("returns the raw key when neither catalog has it", () => {
+    expect(readNavLabel(catalog({ translation: {} }), "queue")).toBe("queue");
+  });
+});
diff --git a/packages/apollo-vertex/registry/shell/shell-nav-active.ts b/packages/apollo-vertex/registry/shell/shell-nav-active.ts
new file mode 100644
index 0000000000..040c1f1f61
--- /dev/null
+++ b/packages/apollo-vertex/registry/shell/shell-nav-active.ts
@@ -0,0 +1,30 @@
+export function navPathIsActive(pathname: string, path: string): boolean {
+  if (path === "/") return pathname === "/";
+  return pathname === path || pathname.startsWith(`${path}/`);
+}
+
+// A parent is the current page only while none of its children is.
+// Collapsed mode uses the same rule: the parent keeps the prefix color,
+// and the current pill stays with the child even while that row is hidden.
+export function navItemIsCurrent(
+  pathname: string,
+  path: string,
+  childPaths: readonly string[] = [],
+): boolean {
+  return (
+    navPathIsActive(pathname, path) &&
+    !childPaths.some((childPath) => navPathIsActive(pathname, childPath))
+  );
+}
+
+export function navItemState(
+  pathname: string,
+  item: { path: string; to?: string; childPaths?: readonly string[] },
+): { href: string; prefixActive: boolean; current: boolean } {
+  const childPaths = item.childPaths ?? [];
+  return {
+    href: item.to ?? item.path,
+    prefixActive: navPathIsActive(pathname, item.path),
+    current: navItemIsCurrent(pathname, item.path, childPaths),
+  };
+}
diff --git a/packages/apollo-vertex/registry/shell/shell-nav-label.ts b/packages/apollo-vertex/registry/shell/shell-nav-label.ts
new file mode 100644
index 0000000000..53e57b5de3
--- /dev/null
+++ b/packages/apollo-vertex/registry/shell/shell-nav-label.ts
@@ -0,0 +1,67 @@
+import { VERTEX_NAMESPACE } from "@/lib/vertex-translation";
+
+export interface NavCatalog {
+  defaultNamespace: string;
+  exists: (key: string, namespace: string) => boolean;
+  translate: (key: string, namespace: string) => string;
+}
+
+interface NamespacedI18n {
+  options: { defaultNS?: string | false | readonly string[] };
+  exists: (key: string, options?: { ns?: string }) => boolean;
+  t: (key: string, options?: { ns?: string }) => unknown;
+}
+
+function defaultNamespaceOf(
+  defaultNS?: string | false | readonly string[],
+): string {
+  if (typeof defaultNS === "string" && defaultNS.length > 0) return defaultNS;
+  return "translation";
+}
+
+function isNamespacedI18n(value: object): value is NamespacedI18n {
+  return (
+    "options" in value &&
+    "exists" in value &&
+    typeof value.exists === "function" &&
+    "t" in value &&
+    typeof value.t === "function"
+  );
+}
+
+export function navCatalogFromHook(i18n: object): NavCatalog {
+  if (!isNamespacedI18n(i18n)) {
+    return {
+      defaultNamespace: "translation",
+      exists: () => false,
+      translate: (key) => key,
+    };
+  }
+
+  return {
+    defaultNamespace: defaultNamespaceOf(i18n.options.defaultNS),
+    exists: (key, namespace) => i18n.exists(key, { ns: namespace }),
+    translate: (key, namespace) => {
+      const value = i18n.t(key, { ns: namespace });
+      return typeof value === "string" ? value : key;
+    },
+  };
+}
+
+// App catalog first, then the vertex catalog. A missing key stays the raw key.
+export function readNavLabel(catalog: NavCatalog, key: string): string {
+  const { defaultNamespace } = catalog;
+  if (
+    defaultNamespace !== VERTEX_NAMESPACE &&
+    catalog.exists(key, defaultNamespace)
+  ) {
+    return catalog.translate(key, defaultNamespace);
+  }
+  if (catalog.exists(key, VERTEX_NAMESPACE)) {
+    return catalog.translate(key, VERTEX_NAMESPACE);
+  }
+  if (catalog.exists(key, defaultNamespace)) {
+    return catalog.translate(key, defaultNamespace);
+  }
+  return key;
+}
diff --git a/packages/apollo-vertex/registry/shell/shell-sidebar.tsx b/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
index 3c66630648..ce76ee76d1 100644
--- a/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
@@ -4,7 +4,6 @@ import { Link, useLocation } from "@tanstack/react-router";
 import { AnimatePresence, motion } from "framer-motion";
 import { ChevronDown } from "lucide-react";
 import { useEffect, useState } from "react";
-import { useVertexTranslation } from "@/lib/vertex-translation";
 import {
   Collapsible,
   CollapsibleContent,
@@ -26,6 +25,7 @@ import {
   useSidebar,
 } from "@/components/ui/sidebar";
 import { cn } from "@/lib/utils";
+import { useVertexTranslation } from "@/lib/vertex-translation";
 import type { CompanyLogo, ShellNavItem } from "./shell";
 import {
   fastFadeTransition,
@@ -35,13 +35,19 @@ import {
 import { Company } from "./shell-company";
 import { MinimalCompany } from "./shell-minimal-company";
 import { MinimalNavItem } from "./shell-minimal-nav-item";
+import { navItemState } from "./shell-nav-active";
+import { navCatalogFromHook, readNavLabel } from "./shell-nav-label";
 import { Text } from "./shell-text";
+import type { ShellNavLabel } from "./shell-translation-key";
 import { UserProfile } from "./shell-user-profile";
 
 const activeNavClass =
   "text-sidebar-foreground/85 hover:text-sidebar-foreground data-[active=true]:text-primary-700 dark:data-[active=true]:text-primary-400 data-[active=true]:font-semibold data-[active=true]:bg-primary-100/40 dark:data-[active=true]:bg-primary-900/30";
 const navButtonClass = `font-medium ${activeNavClass}`;
 const subButtonClass = activeNavClass;
+const prefixActiveClass =
+  "text-primary-700 dark:text-primary-400 font-semibold";
+const currentPillClass = "bg-primary-100/40 dark:bg-primary-900/30";
 
 interface ShellSidebarProps {
   companyName: string;
@@ -72,7 +78,7 @@ export const ShellSidebar = ({
             {navItems.map((item) => (
               <MinimalNavItem
                 key={item.path}
-                to={item.path}
+                to={item.to ?? item.path}
                 label={item.label}
               />
             ))}
@@ -113,8 +119,9 @@ function SidebarNav({
   companyLogo,
   navItems,
 }: SidebarNavProps) {
-  const { t } = useVertexTranslation();
-  const { state, toggleSidebar } = useSidebar();
+  const { t, i18n } = useVertexTranslation();
+  const catalog = navCatalogFromHook(i18n);
+  const { state } = useSidebar();
   const { pathname } = useLocation();
   const isCollapsed = state === "collapsed";
   const [sidebarHovered, setSidebarHovered] = useState(false);
@@ -147,36 +154,17 @@ function SidebarNav({
     setExpandedItems(expanded);
   }, [pathname, navItems]);
 
-  const handleMenuClick = (path: string) => {
-    if (isCollapsed) {
-      toggleSidebar();
-      setExpandedItems((prev) => new Set(prev).add(path));
-    } else {
-      setExpandedItems((prev) => {
-        const next = new Set(prev);
-        if (next.has(path)) {
-          next.delete(path);
-        } else {
-          next.add(path);
-        }
-        return next;
-      });
-    }
-  };
-
-  const isActive = (path: string) => {
-    if (path === "/") {
-      return pathname === "/";
-    }
-    return pathname === path || pathname.startsWith(`${path}/`);
-  };
-
-  const isParentActive = (item: ShellNavItem) => {
-    return item.subItems?.some((sub) => isActive(sub.path)) ?? false;
+  const toggleGroup = (path: string) => {
+    setExpandedItems((prev) => {
+      const next = new Set(prev);
+      if (next.has(path)) next.delete(path);
+      else next.add(path);
+      return next;
+    });
   };
 
-  const getTooltipText = (label: ShellNavItem["label"]): string => {
-    if (typeof label === "string") return t(label);
+  const getTooltipText = (label: ShellNavLabel): string => {
+    if (typeof label === "string") return readNavLabel(catalog, label);
     return t(label.i18nKey, label.values);
   };
 
@@ -203,87 +191,107 @@ function SidebarNav({
             <SidebarMenu>
               {navItems.map((item) => {
                 const Icon = item.icon;
-                const active = isActive(item.path);
-                const parentActive = isParentActive(item);
                 const isExpanded = expandedItems.has(item.path);
+                const childPaths = item.subItems?.map((sub) => sub.path) ?? [];
+                const row = navItemState(pathname, {
+                  path: item.path,
+                  to: item.to,
+                  childPaths,
+                });
 
                 if (item.subItems && item.subItems.length > 0) {
-                  const showParentActive = isCollapsed && parentActive;
-
                   return (
                     <Collapsible
                       key={item.path}
                       open={isExpanded && !isCollapsed}
-                      onOpenChange={() => handleMenuClick(item.path)}
+                      onOpenChange={() => toggleGroup(item.path)}
                       className="group/collapsible"
                     >
                       <SidebarMenuItem>
-                        <CollapsibleTrigger asChild>
+                        <div
+                          className={cn(
+                            "flex w-full min-w-0 items-center rounded-md",
+                            !isCollapsed && row.current && currentPillClass,
+                            !isCollapsed &&
+                              !row.current &&
+                              "hover:bg-sidebar-accent/50",
+                          )}
+                        >
                           <SidebarMenuButton
+                            asChild
                             tooltip={getTooltipText(item.label)}
-                            isActive={showParentActive}
-                            className={navButtonClass}
+                            isActive={isCollapsed && row.current}
+                            className={cn(
+                              navButtonClass,
+                              row.prefixActive && prefixActiveClass,
+                              !isCollapsed &&
+                                "w-auto min-w-0 flex-1 bg-transparent hover:bg-transparent",
+                            )}
                           >
-                            <motion.span
-                              className="inline-flex items-center justify-center shrink-0"
-                              {...(isCollapsed
-                                ? { whileHover: iconHoverScale }
-                                : {})}
-                            >
-                              <Icon className="size-4 shrink-0" />
-                            </motion.span>
-                            <AnimatePresence initial={false}>
-                              {!isCollapsed && (
-                                <motion.span
-                                  key="text"
-                                  variants={textFadeVariants}
-                                  initial="initial"
-                                  animate="animate"
-                                  exit="exit"
-                                  transition={fastFadeTransition}
-                                  className="whitespace-nowrap truncate"
-                                >
-                                  <Text value={item.label} />
-                                </motion.span>
-                              )}
-                            </AnimatePresence>
-                            <AnimatePresence initial={false}>
-                              {!isCollapsed && (
-                                <motion.div
-                                  key="chevron"
-                                  variants={textFadeVariants}
-                                  initial="initial"
-                                  animate="animate"
-                                  exit="exit"
-                                  transition={fastFadeTransition}
-                                  className="ml-auto"
-                                >
-                                  <ChevronDown
-                                    className={cn(
-                                      "size-4 transition-transform duration-200",
-                                      isExpanded && "rotate-180",
-                                    )}
-                                  />
-                                </motion.div>
-                              )}
-                            </AnimatePresence>
+                            <Link to={row.href}>
+                              <motion.span
+                                className="inline-flex items-center justify-center shrink-0"
+                                {...(isCollapsed
+                                  ? { whileHover: iconHoverScale }
+                                  : {})}
+                              >
+                                <Icon className="size-4 shrink-0" />
+                              </motion.span>
+                              <AnimatePresence initial={false}>
+                                {!isCollapsed && (
+                                  <motion.span
+                                    key="text"
+                                    variants={textFadeVariants}
+                                    initial="initial"
+                                    animate="animate"
+                                    exit="exit"
+                                    transition={fastFadeTransition}
+                                    className="whitespace-nowrap truncate"
+                                  >
+                                    <Text value={item.label} />
+                                  </motion.span>
+                                )}
+                              </AnimatePresence>
+                            </Link>
                           </SidebarMenuButton>
-                        </CollapsibleTrigger>
+                          {!isCollapsed && (
+                            <CollapsibleTrigger asChild>
+                              <button
+                                type="button"
+                                aria-expanded={isExpanded}
+                                aria-label={
+                                  isExpanded ? t("collapse") : t("expand")
+                                }
+                                className="flex size-8 shrink-0 items-center justify-center text-sidebar-foreground/70 hover:text-sidebar-foreground"
+                              >
+                                <ChevronDown
+                                  className={cn(
+                                    "size-4 transition-transform duration-200",
+                                    isExpanded && "rotate-180",
+                                  )}
+                                />
+                              </button>
+                            </CollapsibleTrigger>
+                          )}
+                        </div>
                         <CollapsibleContent>
                           <SidebarMenuSub className="ml-4 mr-0 mt-1 gap-0.5 pl-3 pr-0">
                             {item.subItems.map((subItem) => {
-                              const subActive = isActive(subItem.path);
+                              const sub = navItemState(pathname, {
+                                path: subItem.path,
+                                to: subItem.to,
+                              });
                               return (
                                 <SidebarMenuSubItem key={subItem.path}>
                                   <SidebarMenuSubButton
                                     asChild
-                                    isActive={subActive}
+                                    isActive={sub.current}
                                     className={cn(
                                       "cursor-pointer whitespace-nowrap",
                                       subButtonClass,
                                     )}
                                   >
-                                    <Link to={subItem.path}>
+                                    <Link to={sub.href}>
                                       <Text value={subItem.label} />
                                     </Link>
                                   </SidebarMenuSubButton>
@@ -301,11 +309,11 @@ function SidebarNav({
                   <SidebarMenuItem key={item.path}>
                     <SidebarMenuButton
                       tooltip={getTooltipText(item.label)}
-                      isActive={active}
+                      isActive={row.current}
                       asChild
                       className={navButtonClass}
                     >
-                      <Link to={item.path}>
+                      <Link to={row.href}>
                         <motion.span
                           className="inline-flex items-center justify-center shrink-0"
                           {...(isCollapsed
@@ -347,7 +355,7 @@ function SidebarNav({
         className="absolute inset-0 pointer-events-none"
         style={{
           boxShadow:
-            "inset -1px 0 0 0 color-mix(in srgb, var(--color-border) 50%, transparent)",
+            "inset -1px 0 0 0 color-mix(in srgb, var(--border) 50%, transparent)",
         }}
       />
     </Sidebar>
diff --git a/packages/apollo-vertex/registry/shell/shell-text.tsx b/packages/apollo-vertex/registry/shell/shell-text.tsx
index eea2388aed..58c3d80c71 100644
--- a/packages/apollo-vertex/registry/shell/shell-text.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-text.tsx
@@ -3,12 +3,13 @@ import {
   useVertexTranslation,
   VERTEX_NAMESPACE,
 } from "@/lib/vertex-translation";
-import type { TranslationKey } from "./shell-translation-key";
+import { navCatalogFromHook, readNavLabel } from "./shell-nav-label";
+import type { ShellNavLabel } from "./shell-translation-key";
 
-export const Text = ({ value }: { value: TranslationKey }) => {
-  const { t } = useVertexTranslation();
+export const Text = ({ value }: { value: ShellNavLabel }) => {
+  const { i18n } = useVertexTranslation();
   if (typeof value === "string") {
-    return t(value);
+    return readNavLabel(navCatalogFromHook(i18n), value);
   }
   return (
     <Trans
diff --git a/packages/apollo-vertex/registry/shell/shell-translation-key.ts b/packages/apollo-vertex/registry/shell/shell-translation-key.ts
index ca26013ed5..77ffc9fd37 100644
--- a/packages/apollo-vertex/registry/shell/shell-translation-key.ts
+++ b/packages/apollo-vertex/registry/shell/shell-translation-key.ts
@@ -8,3 +8,9 @@ export type TranslationKey =
       components: Record<string, ReactElement>;
     }
   | ParseKeys;
+
+type TranslationObject = Extract<TranslationKey, { i18nKey: ParseKeys }>;
+
+// Plain strings are app-catalog keys or vertex keys. Vertex keys are strings,
+// so they still typecheck; the app catalog is what makes invoice labels resolve.
+export type ShellNavLabel = string | TranslationObject;
diff --git a/packages/apollo-vertex/registry/shell/shell.tsx b/packages/apollo-vertex/registry/shell/shell.tsx
index 8425c7b4c0..f7fef7543a 100644
--- a/packages/apollo-vertex/registry/shell/shell.tsx
+++ b/packages/apollo-vertex/registry/shell/shell.tsx
@@ -8,9 +8,18 @@ import { AuthContext, useAuth } from "./shell-auth-provider";
 import { ShellLayout } from "./shell-layout";
 import { LocaleProvider } from "./shell-locale-provider";
 import { ShellLogin } from "./shell-login";
-import type { TranslationKey } from "./shell-translation-key";
+import type { ShellNavLabel } from "./shell-translation-key";
 import { ShellUserProvider } from "./shell-user-provider";
 
+function ShellLoadingSkeleton() {
+  return (
+    <div className="flex h-screen gap-4 p-4 bg-background dark:bg-sidebar">
+      <Skeleton className="h-full w-[280px]" />
+      <Skeleton className="h-full flex-1 rounded-lg" />
+    </div>
+  );
+}
+
 export interface CompanyLogo {
   url: string;
   darkUrl?: string;
@@ -20,12 +29,14 @@ export interface CompanyLogo {
 
 export interface ShellSubNavItem {
   path: string;
-  label: TranslationKey;
+  to?: string;
+  label: ShellNavLabel;
 }
 
 export interface ShellNavItem {
   path: string;
-  label: TranslationKey;
+  to?: string;
+  label: ShellNavLabel;
   icon: LucideIcon;
   subItems?: ShellSubNavItem[];
 }
@@ -37,6 +48,7 @@ export interface ApolloShellProps extends PropsWithChildren {
   companyLogo?: CompanyLogo;
   navItems: ShellNavItem[];
   loginDescription?: string;
+  configureI18n?: () => Promise<void>;
 }
 
 const ApolloShellContent: FC<ApolloShellProps> = ({
@@ -49,7 +61,11 @@ const ApolloShellContent: FC<ApolloShellProps> = ({
   loginDescription,
 }) => {
   const authContext = useContext(AuthContext);
-  const { accessToken } = useAuth();
+  const { accessToken, isLoading } = useAuth();
+
+  if (authContext && isLoading) {
+    return <ShellLoadingSkeleton />;
+  }
 
   if (authContext && !accessToken) {
     return <ShellLogin title={productName} description={loginDescription} />;
@@ -78,15 +94,12 @@ export const ApolloShell: FC<ApolloShellProps> = ({
   variant,
   navItems,
   loginDescription,
+  configureI18n,
 }) => {
   return (
     <LocaleProvider
-      loadingElement={
-        <div className="flex h-screen gap-4 p-4 bg-background dark:bg-sidebar">
-          <Skeleton className="h-full w-[280px]" />
-          <Skeleton className="h-full flex-1 rounded-lg" />
-        </div>
-      }
+      configureI18n={configureI18n}
+      loadingElement={<ShellLoadingSkeleton />}
     >
       <ApolloShellContent
         companyName={companyName}

From 57d6f6de3e9819a65bacd37786468e08ebf8b056 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 16 Oct 2026 12:59:03 +0000
Subject: [PATCH 2/5] fix(apollo-vertex): keep nav labels and active color

Walk a defaultNS list in order before the vertex catalog. Keep a
prefix-active parent's primary color on hover and press. Highlight
minimal nav items by path, and use to only as the link target.
---
 .../content/docs/patterns/shell.mdx           |  2 +-
 .../registry/shell/shell-minimal-nav-item.tsx |  6 +-
 .../registry/shell/shell-nav-active.test.tsx  | 68 ++++++++++++++++++-
 .../registry/shell/shell-nav-label.ts         | 52 ++++++++------
 .../registry/shell/shell-sidebar.tsx          |  8 ++-
 5 files changed, 108 insertions(+), 28 deletions(-)

diff --git a/apps/apollo-vertex/content/docs/patterns/shell.mdx b/apps/apollo-vertex/content/docs/patterns/shell.mdx
index 0e966535b5..66dc24faf5 100644
--- a/apps/apollo-vertex/content/docs/patterns/shell.mdx
+++ b/apps/apollo-vertex/content/docs/patterns/shell.mdx
@@ -54,7 +54,7 @@ function App() {
 
 ## Nested navigation
 
-A group can set `to` and `subItems`. The row links to `to`, or to `path` when `to` is omitted, and stays in the active color for `path` and every route under it. The matching child gets the current background. While the sidebar is collapsed, that background stays off the parent: the parent icon keeps the active color.
+A group can set `to` and `subItems`. The row links to `to`, or to `path` when `to` is omitted, and stays in the active color for `path` and every route under it, including on hover and press. The matching child gets the current background. While the sidebar is collapsed, that background stays off the parent: the parent icon keeps the active color. The minimal header uses the same path match. `to` is only the link target.
 
 Labels are translation keys. A key in the app's default catalog is used first, including keys that are not in Apollo Vertex. Vertex keys such as `dashboard` still resolve when the app catalog does not define them.
 
diff --git a/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx b/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
index f8abcff598..893fdadc29 100644
--- a/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
@@ -1,16 +1,18 @@
 import { Link, useLocation } from "@tanstack/react-router";
 import { cn } from "@/lib/utils";
+import { navPathIsActive } from "./shell-nav-active";
 import { Text } from "./shell-text";
 import type { ShellNavLabel } from "./shell-translation-key";
 
 interface MinimalNavItemProps {
   to: string;
+  path: string;
   label: ShellNavLabel;
 }
 
-export const MinimalNavItem = ({ to, label }: MinimalNavItemProps) => {
+export const MinimalNavItem = ({ to, path, label }: MinimalNavItemProps) => {
   const { pathname } = useLocation();
-  const isActive = pathname === to;
+  const isActive = navPathIsActive(pathname, path);
 
   return (
     <Link
diff --git a/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx b/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
index 7978bd261a..d387b753a5 100644
--- a/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
@@ -5,7 +5,11 @@ import {
   navItemState,
   navPathIsActive,
 } from "./shell-nav-active";
-import { type NavCatalog, readNavLabel } from "./shell-nav-label";
+import {
+  type NavCatalog,
+  navCatalogFromHook,
+  readNavLabel,
+} from "./shell-nav-label";
 
 describe("navPathIsActive", () => {
   it("matches the path and its nested pages", () => {
@@ -95,13 +99,29 @@ describe("navItemState", () => {
 });
 
 function catalog(bundles: Record<string, Record<string, string>>): NavCatalog {
+  const configured = Object.keys(bundles).filter(
+    (namespace) => namespace !== VERTEX_NAMESPACE,
+  );
   return {
-    defaultNamespace: "translation",
+    namespaces: [...configured, VERTEX_NAMESPACE],
     exists: (key, namespace) => Object.hasOwn(bundles[namespace] ?? {}, key),
     translate: (key, namespace) => bundles[namespace]?.[key] ?? key,
   };
 }
 
+function hookI18n(
+  defaultNS: string | false | readonly string[] | undefined,
+  bundles: Record<string, Record<string, string>>,
+) {
+  return {
+    options: { defaultNS },
+    exists: (key: string, options?: { ns?: string }) =>
+      Object.hasOwn(bundles[options?.ns ?? ""] ?? {}, key),
+    t: (key: string, options?: { ns?: string }) =>
+      bundles[options?.ns ?? ""]?.[key] ?? key,
+  };
+}
+
 describe("readNavLabel", () => {
   it("reads an app key that is not in the vertex catalog", () => {
     expect(
@@ -143,3 +163,47 @@ describe("readNavLabel", () => {
     expect(readNavLabel(catalog({ translation: {} }), "queue")).toBe("queue");
   });
 });
+
+describe("navCatalogFromHook", () => {
+  it("walks an array defaultNS in order before the vertex catalog", () => {
+    const resolved = navCatalogFromHook(
+      hookI18n(["billing", "shared"], {
+        shared: { queue: "My work" },
+        [VERTEX_NAMESPACE]: { queue: "Queue" },
+      }),
+    );
+
+    expect(readNavLabel(resolved, "queue")).toBe("My work");
+  });
+
+  it("keeps an app-only namespace instead of replacing the list with translation", () => {
+    const resolved = navCatalogFromHook(
+      hookI18n(["invoice"], {
+        invoice: { queue: "My work" },
+      }),
+    );
+
+    expect(readNavLabel(resolved, "queue")).toBe("My work");
+  });
+
+  it("prefers an earlier configured namespace over a later one", () => {
+    const resolved = navCatalogFromHook(
+      hookI18n(["first", "second"], {
+        first: { queue: "First" },
+        second: { queue: "Second" },
+      }),
+    );
+
+    expect(readNavLabel(resolved, "queue")).toBe("First");
+  });
+
+  it("falls back to the vertex catalog when no configured namespace has the key", () => {
+    const resolved = navCatalogFromHook(
+      hookI18n(["billing", "shared"], {
+        [VERTEX_NAMESPACE]: { dashboard: "Dashboard" },
+      }),
+    );
+
+    expect(readNavLabel(resolved, "dashboard")).toBe("Dashboard");
+  });
+});
diff --git a/packages/apollo-vertex/registry/shell/shell-nav-label.ts b/packages/apollo-vertex/registry/shell/shell-nav-label.ts
index 53e57b5de3..ef9ed55e11 100644
--- a/packages/apollo-vertex/registry/shell/shell-nav-label.ts
+++ b/packages/apollo-vertex/registry/shell/shell-nav-label.ts
@@ -1,7 +1,7 @@
 import { VERTEX_NAMESPACE } from "@/lib/vertex-translation";
 
 export interface NavCatalog {
-  defaultNamespace: string;
+  namespaces: readonly string[];
   exists: (key: string, namespace: string) => boolean;
   translate: (key: string, namespace: string) => string;
 }
@@ -12,11 +12,29 @@ interface NamespacedI18n {
   t: (key: string, options?: { ns?: string }) => unknown;
 }
 
-function defaultNamespaceOf(
-  defaultNS?: string | false | readonly string[],
-): string {
-  if (typeof defaultNS === "string" && defaultNS.length > 0) return defaultNS;
-  return "translation";
+function configuredNamespaces(
+  defaultNS: string | false | readonly string[] | undefined,
+): readonly string[] {
+  if (typeof defaultNS === "string") {
+    return defaultNS.length > 0 ? [defaultNS] : ["translation"];
+  }
+  if (!Array.isArray(defaultNS)) return ["translation"];
+
+  const namespaces: string[] = [];
+  for (const namespace of defaultNS) {
+    if (typeof namespace === "string" && namespace.length > 0) {
+      namespaces.push(namespace);
+    }
+  }
+  return namespaces.length > 0 ? namespaces : ["translation"];
+}
+
+function lookupNamespaces(
+  defaultNS: string | false | readonly string[] | undefined,
+): readonly string[] {
+  const configured = configuredNamespaces(defaultNS);
+  if (configured.includes(VERTEX_NAMESPACE)) return configured;
+  return [...configured, VERTEX_NAMESPACE];
 }
 
 function isNamespacedI18n(value: object): value is NamespacedI18n {
@@ -32,14 +50,14 @@ function isNamespacedI18n(value: object): value is NamespacedI18n {
 export function navCatalogFromHook(i18n: object): NavCatalog {
   if (!isNamespacedI18n(i18n)) {
     return {
-      defaultNamespace: "translation",
+      namespaces: ["translation", VERTEX_NAMESPACE],
       exists: () => false,
       translate: (key) => key,
     };
   }
 
   return {
-    defaultNamespace: defaultNamespaceOf(i18n.options.defaultNS),
+    namespaces: lookupNamespaces(i18n.options.defaultNS),
     exists: (key, namespace) => i18n.exists(key, { ns: namespace }),
     translate: (key, namespace) => {
       const value = i18n.t(key, { ns: namespace });
@@ -48,20 +66,12 @@ export function navCatalogFromHook(i18n: object): NavCatalog {
   };
 }
 
-// App catalog first, then the vertex catalog. A missing key stays the raw key.
+// Configured namespaces in order, then the vertex catalog. A missing key stays the raw key.
 export function readNavLabel(catalog: NavCatalog, key: string): string {
-  const { defaultNamespace } = catalog;
-  if (
-    defaultNamespace !== VERTEX_NAMESPACE &&
-    catalog.exists(key, defaultNamespace)
-  ) {
-    return catalog.translate(key, defaultNamespace);
-  }
-  if (catalog.exists(key, VERTEX_NAMESPACE)) {
-    return catalog.translate(key, VERTEX_NAMESPACE);
-  }
-  if (catalog.exists(key, defaultNamespace)) {
-    return catalog.translate(key, defaultNamespace);
+  for (const namespace of catalog.namespaces) {
+    if (catalog.exists(key, namespace)) {
+      return catalog.translate(key, namespace);
+    }
   }
   return key;
 }
diff --git a/packages/apollo-vertex/registry/shell/shell-sidebar.tsx b/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
index ce76ee76d1..545b64f6dc 100644
--- a/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
@@ -45,8 +45,11 @@ const activeNavClass =
   "text-sidebar-foreground/85 hover:text-sidebar-foreground data-[active=true]:text-primary-700 dark:data-[active=true]:text-primary-400 data-[active=true]:font-semibold data-[active=true]:bg-primary-100/40 dark:data-[active=true]:bg-primary-900/30";
 const navButtonClass = `font-medium ${activeNavClass}`;
 const subButtonClass = activeNavClass;
-const prefixActiveClass =
-  "text-primary-700 dark:text-primary-400 font-semibold";
+const prefixActiveClass = [
+  "font-semibold text-primary-700 dark:text-primary-400",
+  "hover:text-primary-700 dark:hover:text-primary-400",
+  "active:text-primary-700 dark:active:text-primary-400",
+].join(" ");
 const currentPillClass = "bg-primary-100/40 dark:bg-primary-900/30";
 
 interface ShellSidebarProps {
@@ -79,6 +82,7 @@ export const ShellSidebar = ({
               <MinimalNavItem
                 key={item.path}
                 to={item.to ?? item.path}
+                path={item.path}
                 label={item.label}
               />
             ))}

From 7282e091362aa2fd541ea9b1f9c7cab5e2998150 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 16 Oct 2026 13:07:36 +0000
Subject: [PATCH 3/5] fix(apollo-vertex): pick one minimal nav item

Highlight only the longest matching minimal-header path, so a section
does not also select its landing page. Name each group disclosure
button with the translated group label.
---
 .../content/docs/patterns/shell.mdx           |  2 +-
 packages/apollo-vertex/locales/en.json        |  2 ++
 .../registry/shell/shell-minimal-nav-item.tsx | 12 +++----
 .../registry/shell/shell-nav-active.test.tsx  | 33 +++++++++++++++++++
 .../registry/shell/shell-nav-active.ts        | 14 ++++++++
 .../registry/shell/shell-sidebar.tsx          | 18 +++++++---
 6 files changed, 67 insertions(+), 14 deletions(-)

diff --git a/apps/apollo-vertex/content/docs/patterns/shell.mdx b/apps/apollo-vertex/content/docs/patterns/shell.mdx
index 66dc24faf5..4c642cd365 100644
--- a/apps/apollo-vertex/content/docs/patterns/shell.mdx
+++ b/apps/apollo-vertex/content/docs/patterns/shell.mdx
@@ -54,7 +54,7 @@ function App() {
 
 ## Nested navigation
 
-A group can set `to` and `subItems`. The row links to `to`, or to `path` when `to` is omitted, and stays in the active color for `path` and every route under it, including on hover and press. The matching child gets the current background. While the sidebar is collapsed, that background stays off the parent: the parent icon keeps the active color. The minimal header uses the same path match. `to` is only the link target.
+A group can set `to` and `subItems`. The row links to `to`, or to `path` when `to` is omitted, and stays in the active color for `path` and every route under it, including on hover and press. The matching child gets the current background. While the sidebar is collapsed, that background stays off the parent: the parent icon keeps the active color. The minimal header highlights only the most specific matching path, so a landing page is not selected together with a section under it. A nested page still highlights that section. `to` is only the link target.
 
 Labels are translation keys. A key in the app's default catalog is used first, including keys that are not in Apollo Vertex. Vertex keys such as `dashboard` still resolve when the app catalog does not define them.
 
diff --git a/packages/apollo-vertex/locales/en.json b/packages/apollo-vertex/locales/en.json
index 13e05ef3fd..7578e8f4bd 100644
--- a/packages/apollo-vertex/locales/en.json
+++ b/packages/apollo-vertex/locales/en.json
@@ -186,6 +186,8 @@
   "more_pages": "More pages",
   "multi_line_too_few_metrics": "Multi-line needs two distinct metrics, but the request resolved to fewer than two.",
   "my_template": "My Template",
+  "nav_collapse": "Collapse {{label}}",
+  "nav_expand": "Expand {{label}}",
   "need_help": "Need help? Contact your administrator",
   "new_conversation": "New conversation",
   "new_conversation_confirm_description": "This will clear all messages and cannot be undone.",
diff --git a/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx b/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
index 893fdadc29..6f2a099ea2 100644
--- a/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-minimal-nav-item.tsx
@@ -1,25 +1,21 @@
-import { Link, useLocation } from "@tanstack/react-router";
+import { Link } from "@tanstack/react-router";
 import { cn } from "@/lib/utils";
-import { navPathIsActive } from "./shell-nav-active";
 import { Text } from "./shell-text";
 import type { ShellNavLabel } from "./shell-translation-key";
 
 interface MinimalNavItemProps {
   to: string;
-  path: string;
+  active: boolean;
   label: ShellNavLabel;
 }
 
-export const MinimalNavItem = ({ to, path, label }: MinimalNavItemProps) => {
-  const { pathname } = useLocation();
-  const isActive = navPathIsActive(pathname, path);
-
+export const MinimalNavItem = ({ to, active, label }: MinimalNavItemProps) => {
   return (
     <Link
       to={to}
       className={cn(
         "px-4 py-1.5 rounded-full text-sm font-medium transition-colors duration-200 shrink-0 whitespace-nowrap",
-        isActive
+        active
           ? "bg-[oklch(0.92_0.035_218)] dark:bg-primary-900/30 text-primary-700 dark:text-primary-400 font-semibold"
           : "text-muted-foreground hover:text-foreground hover:bg-black/[0.04] dark:hover:bg-white/[0.06]",
       )}
diff --git a/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx b/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
index d387b753a5..78eecfdc98 100644
--- a/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { VERTEX_NAMESPACE } from "@/lib/vertex-translation";
 import {
+  mostSpecificActivePath,
   navItemIsCurrent,
   navItemState,
   navPathIsActive,
@@ -73,6 +74,38 @@ describe("navItemIsCurrent", () => {
   });
 });
 
+describe("mostSpecificActivePath", () => {
+  const header = [
+    "/preview/shell-minimal",
+    "/preview/shell-minimal/projects",
+    "/preview/shell-minimal/analytics",
+  ];
+
+  it("selects the section and not the landing page", () => {
+    expect(
+      mostSpecificActivePath("/preview/shell-minimal/projects", header),
+    ).toBe("/preview/shell-minimal/projects");
+  });
+
+  it("keeps prefix highlighting for a nested detail route", () => {
+    expect(
+      mostSpecificActivePath("/preview/shell-minimal/projects/42", header),
+    ).toBe("/preview/shell-minimal/projects");
+  });
+
+  it("selects the landing page on its own route", () => {
+    expect(mostSpecificActivePath("/preview/shell-minimal", header)).toBe(
+      "/preview/shell-minimal",
+    );
+  });
+
+  it("highlights a group when no more specific item exists", () => {
+    expect(mostSpecificActivePath("/rules/exceptions", ["/rules"])).toBe(
+      "/rules",
+    );
+  });
+});
+
 describe("navItemState", () => {
   it("links a group to its default child and keeps the prefix active", () => {
     expect(
diff --git a/packages/apollo-vertex/registry/shell/shell-nav-active.ts b/packages/apollo-vertex/registry/shell/shell-nav-active.ts
index 040c1f1f61..3017dd6067 100644
--- a/packages/apollo-vertex/registry/shell/shell-nav-active.ts
+++ b/packages/apollo-vertex/registry/shell/shell-nav-active.ts
@@ -17,6 +17,20 @@ export function navItemIsCurrent(
   );
 }
 
+// Among prefix matches, the longest path wins. A detail route highlights its
+// section without also selecting a shorter landing-page link.
+export function mostSpecificActivePath(
+  pathname: string,
+  paths: readonly string[],
+): string | null {
+  let match: string | null = null;
+  for (const path of paths) {
+    if (!navPathIsActive(pathname, path)) continue;
+    if (match === null || path.length > match.length) match = path;
+  }
+  return match;
+}
+
 export function navItemState(
   pathname: string,
   item: { path: string; to?: string; childPaths?: readonly string[] },
diff --git a/packages/apollo-vertex/registry/shell/shell-sidebar.tsx b/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
index 545b64f6dc..58e1e3f931 100644
--- a/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-sidebar.tsx
@@ -35,7 +35,7 @@ import {
 import { Company } from "./shell-company";
 import { MinimalCompany } from "./shell-minimal-company";
 import { MinimalNavItem } from "./shell-minimal-nav-item";
-import { navItemState } from "./shell-nav-active";
+import { mostSpecificActivePath, navItemState } from "./shell-nav-active";
 import { navCatalogFromHook, readNavLabel } from "./shell-nav-label";
 import { Text } from "./shell-text";
 import type { ShellNavLabel } from "./shell-translation-key";
@@ -67,7 +67,14 @@ export const ShellSidebar = ({
   companyLogo,
   navItems,
 }: ShellSidebarProps) => {
+  const { pathname } = useLocation();
+
   if (variant === "minimal") {
+    const activePath = mostSpecificActivePath(
+      pathname,
+      navItems.map((item) => item.path),
+    );
+
     return (
       <header className="relative flex items-center justify-between px-4 sm:px-6 lg:px-8 py-6 transition-[padding] duration-300 ease-in-out">
         <MinimalCompany
@@ -82,7 +89,7 @@ export const ShellSidebar = ({
               <MinimalNavItem
                 key={item.path}
                 to={item.to ?? item.path}
-                path={item.path}
+                active={item.path === activePath}
                 label={item.label}
               />
             ))}
@@ -263,9 +270,10 @@ function SidebarNav({
                               <button
                                 type="button"
                                 aria-expanded={isExpanded}
-                                aria-label={
-                                  isExpanded ? t("collapse") : t("expand")
-                                }
+                                aria-label={t(
+                                  isExpanded ? "nav_collapse" : "nav_expand",
+                                  { label: getTooltipText(item.label) },
+                                )}
                                 className="flex size-8 shrink-0 items-center justify-center text-sidebar-foreground/70 hover:text-sidebar-foreground"
                               >
                                 <ChevronDown

From 46b102ecf5e473ccecb04d6069414c9016b92dbb Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 16 Oct 2026 13:14:30 +0000
Subject: [PATCH 4/5] fix(apollo-vertex): keep parent color for outside
 children

A collapsed group stays in the active color when a child route matches,
even if that child is outside the parent path. The parent pill stays off.
---
 .../registry/shell/shell-nav-active.test.tsx  | 19 +++++++++++++++++++
 .../registry/shell/shell-nav-active.ts        |  8 +++++---
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx b/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
index 78eecfdc98..6b9e4ba1b4 100644
--- a/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
+++ b/packages/apollo-vertex/registry/shell/shell-nav-active.test.tsx
@@ -121,6 +121,25 @@ describe("navItemState", () => {
     });
   });
 
+  it("keeps the parent color when a child is outside the parent prefix", () => {
+    expect(
+      navItemState("/invoices", {
+        path: "/work",
+        childPaths: ["/invoices"],
+      }),
+    ).toEqual({
+      href: "/work",
+      prefixActive: true,
+      current: false,
+    });
+    expect(
+      navItemState("/invoices/abc", {
+        path: "/work",
+        childPaths: ["/invoices"],
+      }),
+    ).toMatchObject({ prefixActive: true, current: false });
+  });
+
   it("uses path as the link when the group has no default child", () => {
     expect(
       navItemState("/invoices", {
diff --git a/packages/apollo-vertex/registry/shell/shell-nav-active.ts b/packages/apollo-vertex/registry/shell/shell-nav-active.ts
index 3017dd6067..8c5639991c 100644
--- a/packages/apollo-vertex/registry/shell/shell-nav-active.ts
+++ b/packages/apollo-vertex/registry/shell/shell-nav-active.ts
@@ -4,8 +4,7 @@ export function navPathIsActive(pathname: string, path: string): boolean {
 }
 
 // A parent is the current page only while none of its children is.
-// Collapsed mode uses the same rule: the parent keeps the prefix color,
-// and the current pill stays with the child even while that row is hidden.
+// The pill uses this even when the sidebar is collapsed.
 export function navItemIsCurrent(
   pathname: string,
   path: string,
@@ -36,9 +35,12 @@ export function navItemState(
   item: { path: string; to?: string; childPaths?: readonly string[] },
 ): { href: string; prefixActive: boolean; current: boolean } {
   const childPaths = item.childPaths ?? [];
+  const childActive = childPaths.some((childPath) =>
+    navPathIsActive(pathname, childPath),
+  );
   return {
     href: item.to ?? item.path,
-    prefixActive: navPathIsActive(pathname, item.path),
+    prefixActive: navPathIsActive(pathname, item.path) || childActive,
     current: navItemIsCurrent(pathname, item.path, childPaths),
   };
 }

From 94d3f2d616d0a0b331918eec1c24f40fbf62f02c Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 16 Oct 2026 13:33:33 +0000
Subject: [PATCH 5/5] docs(apollo-vertex): group shell headings and show nested
 nav

Nest navigation, translations, and the minimal header under Usage, and
role lookup under group access. Open the nested example on the default
child so that row is current and the parent keeps the prefix color.
---
 .../content/docs/patterns/shell.mdx           | 48 +++++++++++--------
 .../templates/shell/ShellRoot.tsx             | 11 ++++-
 .../templates/shell/ShellRoutes.tsx           | 12 +++++
 .../templates/shell/ShellTemplate.tsx         | 24 ++++++++--
 packages/apollo-vertex/locales/en.json        |  2 +
 5 files changed, 70 insertions(+), 27 deletions(-)

diff --git a/apps/apollo-vertex/content/docs/patterns/shell.mdx b/apps/apollo-vertex/content/docs/patterns/shell.mdx
index 4c642cd365..ba6e070f75 100644
--- a/apps/apollo-vertex/content/docs/patterns/shell.mdx
+++ b/apps/apollo-vertex/content/docs/patterns/shell.mdx
@@ -11,14 +11,6 @@ import { PreviewFullScreen } from '../../../app/_components/preview-full-screen'
     <ShellTemplate />
 </PreviewFullScreen>
 
-## Minimal Header Variant
-
-Use the `variant="minimal"` prop to render a horizontal header layout instead of the default sidebar.
-
-<PreviewFullScreen title="Shell minimal preview">
-    <ShellTemplate variant="minimal" />
-</PreviewFullScreen>
-
 ## Features
 
 - **Optional OAuth2 Authentication**: Plug-and-play authorization code flow with PKCE
@@ -52,29 +44,43 @@ function App() {
 }
 ```
 
-## Nested navigation
+### Nested navigation
 
-A group can set `to` and `subItems`. The row links to `to`, or to `path` when `to` is omitted, and stays in the active color for `path` and every route under it, including on hover and press. The matching child gets the current background. While the sidebar is collapsed, that background stays off the parent: the parent icon keeps the active color. The minimal header highlights only the most specific matching path, so a landing page is not selected together with a section under it. A nested page still highlights that section. `to` is only the link target.
+A group sets `path` for the prefix and `to` for the link. This preview opens on Active. That child has the current background. Projects stays in the active color for `/preview/shell/projects` and the routes under it, and does not take that background.
 
-Labels are translation keys. A key in the app's default catalog is used first, including keys that are not in Apollo Vertex. Vertex keys such as `dashboard` still resolve when the app catalog does not define them.
+<PreviewFullScreen title="Nested navigation preview">
+    <ShellTemplate initialPath="/preview/shell/projects/active" />
+</PreviewFullScreen>
 
 ```tsx
-{
-  path: '/rules',
-  to: '/rules/exceptions',
-  label: 'rules',
-  icon: ListTree,
+import { FolderOpen } from 'lucide-react';
+
+const projects = {
+  path: '/preview/shell/projects',
+  to: '/preview/shell/projects/active',
+  label: 'projects',
+  icon: FolderOpen,
   subItems: [
-    { path: '/rules/feedback', label: 'feedback' },
-    { path: '/rules/exceptions', label: 'exceptions' },
+    { path: '/preview/shell/projects/active', label: 'active' },
+    { path: '/preview/shell/projects/archive', label: 'archive' },
   ],
-}
+};
 ```
 
-## App translations
+Labels are translation keys. A key in the app's default catalog is used first, including keys that are not in Apollo Vertex. Vertex keys such as `dashboard` still resolve when the app catalog does not define them.
+
+### App translations
 
 Pass `configureI18n` to `ApolloShell` or `LocaleProvider` when the app initializes i18next itself. The shell then runs that function instead of replacing the app catalog with the Vertex one.
 
+### Minimal header
+
+Use `variant="minimal"` for a horizontal header instead of the sidebar. The header highlights only the most specific matching path, so a landing page is not selected together with a section under it. A nested page still highlights that section. `to` is only the link target.
+
+<PreviewFullScreen title="Shell minimal preview">
+    <ShellTemplate variant="minimal" />
+</PreviewFullScreen>
+
 ## Adding Authentication
 
 To enable built-in OAuth2 authentication with PKCE, wrap the shell with `ShellAuthProvider`.
@@ -189,7 +195,7 @@ Names that don't resolve are denied. Requires `@uipath/vs-core` 4.4.0 or later.
 </GroupMembershipGuard>
 ```
 
-## Resolving group ids by role
+### Resolving group ids by role
 
 `GroupMembershipGuard` and `useIsGroupMember` need group ids, but applications
 typically reason in terms of roles whose backing group names are known ahead of
diff --git a/apps/apollo-vertex/templates/shell/ShellRoot.tsx b/apps/apollo-vertex/templates/shell/ShellRoot.tsx
index 0eedb8f70b..1c78561c76 100644
--- a/apps/apollo-vertex/templates/shell/ShellRoot.tsx
+++ b/apps/apollo-vertex/templates/shell/ShellRoot.tsx
@@ -6,7 +6,16 @@ import { ShellThemeProvider } from "./ShellThemeProvider";
 
 const navItems: ShellNavItem[] = [
   { path: "/preview/shell/dashboard", label: "dashboard", icon: Home },
-  { path: "/preview/shell/projects", label: "projects", icon: FolderOpen },
+  {
+    path: "/preview/shell/projects",
+    to: "/preview/shell/projects/active",
+    label: "projects",
+    icon: FolderOpen,
+    subItems: [
+      { path: "/preview/shell/projects/active", label: "active" },
+      { path: "/preview/shell/projects/archive", label: "archive" },
+    ],
+  },
   { path: "/preview/shell/analytics", label: "analytics", icon: BarChart3 },
   { path: "/preview/shell/team", label: "team", icon: Users },
   { path: "/preview/shell/settings", label: "settings", icon: Settings },
diff --git a/apps/apollo-vertex/templates/shell/ShellRoutes.tsx b/apps/apollo-vertex/templates/shell/ShellRoutes.tsx
index 03fbbc8bb4..601a36cfe1 100644
--- a/apps/apollo-vertex/templates/shell/ShellRoutes.tsx
+++ b/apps/apollo-vertex/templates/shell/ShellRoutes.tsx
@@ -39,6 +39,18 @@ export const shellProjectsRoute = createRoute({
   component: () => <PlaceholderPage title="Projects" />,
 });
 
+export const shellProjectsActiveRoute = createRoute({
+  getParentRoute: () => shellRoute,
+  path: "/projects/active",
+  component: () => <PlaceholderPage title="Active" />,
+});
+
+export const shellProjectsArchiveRoute = createRoute({
+  getParentRoute: () => shellRoute,
+  path: "/projects/archive",
+  component: () => <PlaceholderPage title="Archive" />,
+});
+
 export const shellAnalyticsRoute = createRoute({
   getParentRoute: () => shellRoute,
   path: "/analytics",
diff --git a/apps/apollo-vertex/templates/shell/ShellTemplate.tsx b/apps/apollo-vertex/templates/shell/ShellTemplate.tsx
index 8dbc2022dc..d3a841a671 100644
--- a/apps/apollo-vertex/templates/shell/ShellTemplate.tsx
+++ b/apps/apollo-vertex/templates/shell/ShellTemplate.tsx
@@ -22,6 +22,8 @@ import {
   shellDashboardRoute,
   shellIndexRoute,
   shellInvoiceDetailRoute,
+  shellProjectsActiveRoute,
+  shellProjectsArchiveRoute,
   shellProjectsRoute,
   shellRoute,
   shellSettingsRoute,
@@ -31,6 +33,7 @@ import { rootRoute } from "./ShellRouteTree";
 
 export interface ShellTemplateProps {
   variant?: "minimal";
+  initialPath?: string;
 }
 
 const SHELL_PREVIEW_PATH_KEY = "shell-preview-path";
@@ -54,6 +57,8 @@ const routeTree = rootRoute.addChildren([
     shellDashboardRoute,
     shellInvoiceDetailRoute,
     shellProjectsRoute,
+    shellProjectsActiveRoute,
+    shellProjectsArchiveRoute,
     shellAnalyticsRoute,
     shellTeamRoute,
     shellSettingsRoute,
@@ -68,7 +73,12 @@ const routeTree = rootRoute.addChildren([
   catchAllRoute,
 ]);
 
-function getInitialEntry(storageKey: ShellPreviewPathKey, variant?: "minimal") {
+function getInitialEntry(
+  storageKey: ShellPreviewPathKey,
+  variant?: "minimal",
+  initialPath?: string,
+) {
+  if (initialPath) return initialPath;
   const stored = localStorage.getItem(storageKey);
   if (stored) return stored;
   return variant === "minimal" ? "/preview/shell-minimal" : "/preview/shell";
@@ -77,26 +87,30 @@ function getInitialEntry(storageKey: ShellPreviewPathKey, variant?: "minimal") {
 function createShellRouter(
   storageKey: ShellPreviewPathKey,
   variant?: "minimal",
+  initialPath?: string,
 ) {
   const history = createMemoryHistory({
-    initialEntries: [getInitialEntry(storageKey, variant)],
+    initialEntries: [getInitialEntry(storageKey, variant, initialPath)],
   });
   return createRouter({ routeTree, history });
 }
 
-export function ShellTemplate({ variant }: ShellTemplateProps) {
+export function ShellTemplate({ variant, initialPath }: ShellTemplateProps) {
   const storageKey =
     variant === "minimal"
       ? SHELL_MINIMAL_PREVIEW_PATH_KEY
       : SHELL_PREVIEW_PATH_KEY;
-  const [router] = useState(() => createShellRouter(storageKey, variant));
+  const [router] = useState(() =>
+    createShellRouter(storageKey, variant, initialPath),
+  );
 
   useEffect(() => {
+    if (initialPath) return;
     const unsubscribe = router.subscribe("onResolved", ({ toLocation }) => {
       localStorage.setItem(storageKey, toLocation.pathname);
     });
     return unsubscribe;
-  }, [router, storageKey]);
+  }, [router, storageKey, initialPath]);
   return (
     <QueryClientProvider client={queryClient}>
       <RouterProvider router={router} />
diff --git a/packages/apollo-vertex/locales/en.json b/packages/apollo-vertex/locales/en.json
index 7578e8f4bd..86086d6c62 100644
--- a/packages/apollo-vertex/locales/en.json
+++ b/packages/apollo-vertex/locales/en.json
@@ -3,6 +3,7 @@
   "access_denied": "Access Denied",
   "access_denied_description": "You don't have access to this application. Ask your administrator to add you to the users group.",
   "actions": "Actions",
+  "active": "Active",
   "actual_input": "Actual input",
   "actual_output": "Actual output",
   "add_attachment": "Add attachment",
@@ -24,6 +25,7 @@
   "analytics": "Analytics",
   "apollo_vertex": "Apollo Vertex",
   "apollo_vertex_description": "- UiPath Apollo Vertex",
+  "archive": "Archive",
   "are_you_sure": "Are you sure?",
   "asc": "Asc",
   "ask_ai": "Ask AI",