@tristan2828/ui-foundation 3.28.1 → 3.29.0

package/dist/components/app/app-shell-nav.d.ts

@@ -0,0 +1,34 @@
+import type { ComponentType } from 'react';
+export type NavItem = {
+    /** The route this entry links to. */
+    to: string;
+    label: string;
+    icon: ComponentType;
+    /** Active only on an exact match (use for '/'); otherwise on any sub-path too. */
+    end?: boolean;
+};
+/** A labelled group of sidebar entries: one module's pages, say. */
+export type NavSection = {
+    label: string;
+    items: readonly NavItem[];
+};
+/** One entry of `AppShell`'s `nav`: a page, or a labelled section of pages. */
+export type NavEntry = NavItem | NavSection;
+export declare function isNavSection(entry: NavEntry): entry is NavSection;
+/** A sidebar group as rendered: an optional label over its items. */
+export type NavGroup = {
+    label?: string;
+    items: readonly NavItem[];
+};
+/**
+ * The sidebar groups for a nav, in order. A flat nav (no sections) is the
+ * one "Navigation" group it always was. Otherwise each section is its own
+ * labelled group, and each run of plain items between them an unlabelled one.
+ */
+export declare function navGroups(nav: readonly NavEntry[]): NavGroup[];
+/**
+ * The `to` of the one entry to mark active: the most specific that matches.
+ * With '/tasks' and '/tasks/categories' both in the nav, '/tasks/categories/2'
+ * marks Categories only, and '/tasks/3' marks Tasks.
+ */
+export declare function activeNavTo(nav: readonly NavEntry[], pathname: string): string | undefined;

package/dist/components/app/app-shell-nav.js

@@ -0,0 +1,52 @@
+export function isNavSection(entry) {
+    return 'items' in entry;
+}
+/**
+ * The sidebar groups for a nav, in order. A flat nav (no sections) is the
+ * one "Navigation" group it always was. Otherwise each section is its own
+ * labelled group, and each run of plain items between them an unlabelled one.
+ */
+export function navGroups(nav) {
+    if (!nav.some(isNavSection))
+        return [{ label: 'Navigation', items: nav }];
+    const groups = [];
+    let run = [];
+    for (const entry of nav) {
+        if (isNavSection(entry)) {
+            if (run.length)
+                groups.push({ items: run });
+            run = [];
+            groups.push({ label: entry.label, items: entry.items });
+        }
+        else {
+            run.push(entry);
+        }
+    }
+    if (run.length)
+        groups.push({ items: run });
+    return groups;
+}
+function matches(item, pathname) {
+    if (item.end)
+        return pathname === item.to;
+    if (pathname === item.to)
+        return true;
+    // On a path-segment boundary: '/tasks' is active on '/tasks/3', not on
+    // '/tasks-archive'.
+    return pathname.startsWith(item.to.endsWith('/') ? item.to : `${item.to}/`);
+}
+/**
+ * The `to` of the one entry to mark active: the most specific that matches.
+ * With '/tasks' and '/tasks/categories' both in the nav, '/tasks/categories/2'
+ * marks Categories only, and '/tasks/3' marks Tasks.
+ */
+export function activeNavTo(nav, pathname) {
+    let best;
+    for (const entry of nav) {
+        for (const item of isNavSection(entry) ? entry.items : [entry]) {
+            if (matches(item, pathname) && (best === undefined || item.to.length > best.length))
+                best = item.to;
+        }
+    }
+    return best;
+}

package/dist/components/app/app-shell.d.ts

@@ -1,17 +1,17 @@
-import { type ComponentType, type ReactNode } from 'react';
-export type NavItem = {
-    /** The route this entry links to. */
-    to: string;
-    label: string;
-    icon: ComponentType;
-    /** Active only on an exact match (use for '/'); otherwise on any sub-path too. */
-    end?: boolean;
-};
+import { type ReactNode } from 'react';
+import { type NavEntry } from './app-shell-nav.js';
+export type { NavEntry, NavItem, NavSection } from './app-shell-nav.js';
 export type AppShellProps = {
     /** Shown at the top of the sidebar (hidden on the collapsed icon rail). */
     title: string;
-    /** The app's primary navigation, in order. */
-    nav: readonly NavItem[];
+    /**
+     * The app's primary navigation, in order: pages, and labelled sections of
+     * pages (`{ label, items }`, one per module, say). A nav with no sections
+     * is the single "Navigation" group. One entry is marked active: the most
+     * specific whose route matches, so '/tasks' and '/tasks/categories' can
+     * both be listed.
+     */
+    nav: readonly NavEntry[];
     /**
      * More sidebar groups under the primary nav — reference links, say. Built
      * from the sidebar primitives (`@tristan2828/ui-foundation/ui/sidebar`).

package/dist/components/app/app-shell.js

@@ -2,8 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { LogOutIcon, MoonIcon, SunIcon } from 'lucide-react';
 import { useTheme } from 'next-themes';
 import { useEffect, useState } from 'react';
-import { NavLink, Navigate, Outlet, useLocation } from 'react-router';
+import { Link, Navigate, Outlet, useLocation } from 'react-router';
 import { useAuth } from '../../auth/use-auth.js';
+import { activeNavTo, navGroups } from './app-shell-nav.js';
 import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
 import { Skeleton } from '../ui/skeleton.js';
@@ -64,12 +65,14 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }
         const from = `${location.pathname}${location.search}${location.hash}`;
         return _jsx(Navigate, { to: "/login", replace: true, state: isLoggingOut ? undefined : { from } });
     }
-    return (_jsxs(TooltipProvider, { children: [_jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [_jsxs(SidebarGroup, { children: [_jsx(SidebarGroupLabel, { children: "Navigation" }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: nav.map(({ to, label, icon: Icon, end }) => {
-                                                            const isActive = end
-                                                                ? location.pathname === to
-                                                                : location.pathname.startsWith(to);
-                                                            return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActive, tooltip: label, render: _jsx(NavLink, { to: to, end: end }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }, to));
-                                                        }) }) })] }), sidebarExtra] }), _jsx(SidebarFooter, { children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+    const activeTo = activeNavTo(nav, location.pathname);
+    return (_jsxs(TooltipProvider, { children: [_jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: group.items.map(({ to, label, icon: Icon }) => {
+                                                            // A plain Link, not NavLink: NavLink marks every
+                                                            // matching entry current, and only the most specific
+                                                            // one should be (activeNavTo).
+                                                            const isActive = to === activeTo;
+                                                            return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActive, tooltip: label, render: _jsx(Link, { to: to, "aria-current": isActive ? 'page' : undefined }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }, to));
+                                                        }) }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsx(SidebarFooter, { children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
                                                     setIsLoggingOut(true);
                                                     // A failed request still ends the session on screen
                                                     // (AuthProvider), so this stays a deliberate logout: a

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AppShell, type AppShellProps, type NavItem } from './components/app/app-shell.js';
+export { AppShell, type AppShellProps, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type DataTableWidth, type SortingState } from './components/app/data-table.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.28.1",
+  "version": "3.29.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {