@servicetitan/navigation 14.4.0 → 14.5.1

package/src/components/titan-layout/navigation-catalog/navigation-catalog.tsx

@@ -30,7 +30,7 @@ const LockedPin: FC = () => (
 );
 
 interface PinToggleProps {
-    /** Mixed modules stay highlighted but use an outline until all pages are pinned. */
+    /** `mixed` is a module on the rail with only some of its pages: an outline, still active. */
     pinned: boolean | 'mixed';
     label: string;
     onToggle: () => void;
@@ -54,15 +54,12 @@ const PinToggle: FC<PinToggleProps> = ({ pinned, label, onToggle }) => {
                     className={classNames(styles.star, pinned && styles.starActive)}
                     aria-label={label}
                     aria-pressed={pinned}
+                    data-pendo="global-nav-favorite-star"
                     onClick={toggle}
                 />
             </Tooltip.Trigger>
             <Tooltip.Content style={{ pointerEvents: 'none' }}>
-                {pinned === 'mixed'
-                    ? 'Add this module to Favorites'
-                    : pinned
-                      ? 'Remove from Favorites'
-                      : 'Add to Favorites'}
+                {pinned ? 'Remove from Favorites' : 'Add to Favorites'}
             </Tooltip.Content>
         </Tooltip>
     );
@@ -79,9 +76,8 @@ interface CatalogRowsProps {
     scopeIds: string[];
     isPinned: (id: string) => boolean;
     isLocked: (id: string) => boolean;
-    /** `ownerId` is the module the page belongs to; omitted for the module's own row. */
-    onTogglePin: (id: string, ownerId?: string) => void;
-    onToggleAll: (ids: string[], shouldPin: boolean) => void;
+    onToggleModule: (moduleId: string) => void;
+    onTogglePage: (id: string, moduleId: string) => void;
     onNavigate: () => void;
 }
 
@@ -90,20 +86,21 @@ const CatalogRows: FC<CatalogRowsProps> = ({
     scopeIds,
     isPinned,
     isLocked,
-    onTogglePin,
-    onToggleAll,
+    onToggleModule,
+    onTogglePage,
     onNavigate,
 }) => {
     const { NavigationComponent } = useTitanLayoutContext();
     const submenuGroups = getCatalogSubmenuGroups(item);
 
     /*
-     * Minus anything locked — locked destinations are always present, so the module's control
-     * neither reports on them nor acts on them.
+     * A pinned module id means the whole module, every page included. Pinned page ids without
+     * their module mean the module is on the rail carrying only those pages.
      */
-    const everything = scopeIds.filter(id => !isLocked(id));
-    const anyPinned = everything.some(isPinned);
-    const allPinned = everything.length > 0 && everything.every(isPinned);
+    const isWholeModule = isPinned(item.id);
+    const isOnRail = scopeIds.some(isPinned);
+    const pageIds = scopeIds.filter(id => id !== item.id && !isLocked(id));
+    const isFullyPinned = isWholeModule || (pageIds.length > 0 && pageIds.every(isPinned));
     const tag = getCounterTag(item.counter, item.tag);
 
     return (
@@ -129,24 +126,20 @@ const CatalogRows: FC<CatalogRowsProps> = ({
                     {!!tag && <BadgeTag data={tag} className={styles.badge} />}
                 </NavigationComponent>
                 {/*
-                 * One control for the whole module: favouriting it takes its pages with it, and
-                 * unfavouriting it takes them away again.
-                 *
-                 * A gold outline marks a partially favourited module. Fill the star only when
-                 * its full, unfiltered scope is favourited, including pages hidden by search.
-                 * Clicking the outline adds the remaining pages; clicking the filled star removes all.
+                 * Filled when every page is favourited, an outline when only some are. Either way
+                 * the module is on the rail, so one click takes it off with all of its pages.
                  */}
                 {isLocked(item.id) ? (
                     <LockedPin />
                 ) : (
                     <PinToggle
-                        pinned={allPinned ? true : anyPinned ? 'mixed' : false}
+                        pinned={isFullyPinned ? true : isOnRail ? 'mixed' : false}
                         label={
-                            allPinned
+                            isOnRail
                                 ? `Unpin ${item.title} from the navigation`
                                 : `Pin ${item.title} to the navigation`
                         }
-                        onToggle={() => onToggleAll(everything, !allPinned)}
+                        onToggle={() => onToggleModule(item.id)}
                     />
                 )}
             </div>
@@ -166,7 +159,7 @@ const CatalogRows: FC<CatalogRowsProps> = ({
                          * otherwise be given the same name several times.
                          */
                         const qualifiedTitle = `${item.title}: ${child.title}`;
-                        const childPinned = isPinned(child.id);
+                        const childPinned = isWholeModule || isPinned(child.id);
                         const childTag = getCounterTag(child.counter, child.tag);
 
                         return (
@@ -194,7 +187,7 @@ const CatalogRows: FC<CatalogRowsProps> = ({
                                                 ? `Unpin ${qualifiedTitle} from the navigation`
                                                 : `Pin ${qualifiedTitle} to the navigation`
                                         }
-                                        onToggle={() => onTogglePin(child.id, item.id)}
+                                        onToggle={() => onTogglePage(child.id, item.id)}
                                     />
                                 )}
                             </div>
@@ -264,69 +257,60 @@ export const NavigationCatalog: FC<NavigationCatalogProps> = ({
     const isPinned = (id: string) => pinnedSet.has(id);
     const isLocked = (id: string) => lockedSet.has(id);
 
-    /**
-     * Favourites or unfavourites one row, carrying its module with it.
-     *
-     * A page is reached through its module, so the two travel together: favouriting a page brings
-     * the module along when it is not already there, and unfavouriting the last one takes the
-     * module with it. Leaving the module behind on its own would not read as an emptier
-     * navigation — it would put the module back carrying every page it has.
+    /*
+     * The saved list follows the host's model: a module id pins the whole module, and page ids
+     * without their module pin the module carrying only those pages. A module id is therefore
+     * never saved next to its own page ids — the host would read that as the whole module.
      *
      * Locked ids never reach a proposal. The controls that would move them are not rendered, so
      * that part is belt and braces — but the host's list is the thing that gets persisted, and a
      * locked destination has no business appearing in or disappearing from it.
      */
-    const togglePin = (id: string, ownerId?: string) => {
-        if (lockedSet.has(id)) {
-            return;
-        }
-
-        /** The module, when it is a separate row that this page can legitimately move. */
-        const owner = ownerId !== id && ownerId && !lockedSet.has(ownerId) ? ownerId : undefined;
-
-        if (pinnedSet.has(id)) {
-            const removing = new Set([id]);
-
-            if (owner) {
-                const siblings = (scopeById.get(owner) ?? []).filter(
-                    scoped => scoped !== owner && scoped !== id
-                );
-
-                if (!siblings.some(sibling => pinnedSet.has(sibling))) {
-                    removing.add(owner);
-                }
-            }
 
-            onPinnedIdsChange(pinnedIds.filter(pinned => !removing.has(pinned)));
+    /** Takes a module off the rail with all of its pages, or puts the whole module on it. */
+    const toggleModule = (moduleId: string) => {
+        if (lockedSet.has(moduleId)) {
             return;
         }
 
-        // Module first, so it reads ahead of its own page in the saved order.
-        const additions = owner && !pinnedSet.has(owner) ? [owner, id] : [id];
+        const scope = (scopeById.get(moduleId) ?? [moduleId]).filter(id => !lockedSet.has(id));
+        const scopeSet = new Set(scope);
+        const withoutModule = pinnedIds.filter(pinned => !scopeSet.has(pinned));
 
-        onPinnedIdsChange([...pinnedIds, ...additions]);
+        onPinnedIdsChange(
+            scope.some(id => pinnedSet.has(id)) ? withoutModule : [...withoutModule, moduleId]
+        );
     };
 
-    /*
-     * One proposal for the whole set rather than one per row, so a host that persists on every
-     * change writes once, and every intermediate list — states the user never asked for — never
-     * exists.
+    /**
+     * Favourites or unfavourites a single page.
+     *
+     * Unstarring a page of a wholly favourited module narrows the module to the rest of its pages,
+     * in the module's place; unstarring its last page takes the module off the rail.
      */
-    const toggleAll = (ids: string[], shouldPin: boolean) => {
-        const actionable = ids.filter(id => !lockedSet.has(id));
-
-        if (!shouldPin) {
-            const removing = new Set(actionable);
-
-            onPinnedIdsChange(pinnedIds.filter(pinned => !removing.has(pinned)));
+    const togglePage = (id: string, moduleId: string) => {
+        if (lockedSet.has(id)) {
             return;
         }
 
-        const additions = actionable.filter(id => !pinnedSet.has(id));
+        const scope = scopeById.get(moduleId) ?? [moduleId];
+        const pages = scope.filter(scoped => scoped !== moduleId && !lockedSet.has(scoped));
+
+        if (pinnedSet.has(moduleId) && !lockedSet.has(moduleId)) {
+            const scopeSet = new Set(scope);
+            const rest = pages.filter(page => page !== id);
 
-        if (additions.length > 0) {
-            onPinnedIdsChange([...pinnedIds, ...additions]);
+            onPinnedIdsChange(
+                pinnedIds.flatMap(pinned =>
+                    pinned === moduleId ? rest : scopeSet.has(pinned) ? [] : [pinned]
+                )
+            );
+            return;
         }
+
+        onPinnedIdsChange(
+            pinnedSet.has(id) ? pinnedIds.filter(pinned => pinned !== id) : [...pinnedIds, id]
+        );
     };
 
     const close = () => {
@@ -403,8 +387,8 @@ export const NavigationCatalog: FC<NavigationCatalogProps> = ({
                                                 scopeIds={scopeById.get(item.id) ?? [item.id]}
                                                 isPinned={isPinned}
                                                 isLocked={isLocked}
-                                                onTogglePin={togglePin}
-                                                onToggleAll={toggleAll}
+                                                onToggleModule={toggleModule}
+                                                onTogglePage={togglePage}
                                                 onNavigate={close}
                                             />
                                         ))}

package/src/utils/__tests__/side-nav.test.ts

@@ -0,0 +1,77 @@
+import { getModuleActiveMatcher, getModuleDestination } from '../side-nav';
+
+describe('getModuleDestination', () => {
+    it('routes to the first link of the first non-empty group when a submenu exists', () => {
+        expect(
+            getModuleDestination('/dispatch/default', {
+                groups: [
+                    {
+                        title: 'Boards',
+                        links: [{ id: 'daily', title: 'Daily', to: '/dispatch/daily' }],
+                    },
+                ],
+            })
+        ).toBe('/dispatch/daily');
+    });
+
+    it('skips empty groups to find the first group that actually has links', () => {
+        expect(
+            getModuleDestination('/reports', {
+                groups: [
+                    { title: 'Empty', links: [] },
+                    {
+                        title: 'Reports',
+                        links: [{ id: 'sales', title: 'Sales', to: '/reports/sales' }],
+                    },
+                ],
+            })
+        ).toBe('/reports/sales');
+    });
+
+    it('falls back to the host-supplied destination when there is no submenu', () => {
+        expect(getModuleDestination('/dashboard', undefined)).toBe('/dashboard');
+    });
+
+    it('falls back to the host-supplied destination when the submenu has no links at all', () => {
+        expect(
+            getModuleDestination('/dashboard', { groups: [{ title: 'Empty', links: [] }] })
+        ).toBe('/dashboard');
+    });
+});
+
+describe('getModuleActiveMatcher', () => {
+    const submenu = {
+        groups: [
+            {
+                title: 'Boards',
+                links: [
+                    { id: 'daily', title: 'Daily', to: '/dispatch/daily' },
+                    { id: 'weekly', title: 'Weekly', to: '/dispatch/weekly' },
+                ],
+            },
+        ],
+    };
+
+    it('matches a sub-item page even though the row now navigates to a different sub-item', () => {
+        const isActive = getModuleActiveMatcher('', submenu)!;
+        expect(isActive('/dispatch/weekly')).toBe(true);
+        expect(isActive('/dispatch/daily')).toBe(true);
+    });
+
+    it('also matches the module own to, when it has one, alongside its sub-items', () => {
+        const isActive = getModuleActiveMatcher('/dispatch', submenu)!;
+        expect(isActive('/dispatch/routes')).toBe(true);
+    });
+
+    it('does not match an unrelated page', () => {
+        const isActive = getModuleActiveMatcher('', submenu)!;
+        expect(isActive('/accounting/invoices')).toBe(false);
+    });
+
+    it('returns undefined when there is nothing to match against', () => {
+        expect(getModuleActiveMatcher('', undefined)).toBeUndefined();
+        expect(
+            getModuleActiveMatcher('', { groups: [{ title: 'Empty', links: [] }] })
+        ).toBeUndefined();
+    });
+});

package/src/utils/side-nav.ts

@@ -2,6 +2,48 @@ import { CounterTagProps } from '../components/counter-tag';
 import { CounterTagData, CounterTagValue } from './counter-tag';
 import { NavigationSubmenuData } from './navigation';
 
+/**
+ * A module with sub-items always routes to the first one, in the nav's existing order, rather
+ * than whatever destination the host configured for the module row itself (3.5a). A host-supplied
+ * `to` only applies to modules with no submenu.
+ */
+export function getModuleDestination(
+    to: string,
+    submenu: NavigationSubmenuData | undefined
+): string {
+    for (const group of submenu?.groups ?? []) {
+        if (group.links.length > 0) {
+            return group.links[0].to;
+        }
+    }
+
+    return to;
+}
+
+/**
+ * Routing a module row to its first sub-item (see `getModuleDestination`) means the row's `to` no
+ * longer identifies the module for a host that has no explicit `isActive` of its own — the default
+ * "compare href to pathname" behavior would then only match the first sub-item's page, not the rest
+ * of the module. Synthesize an equivalent match across the module's own `to` and every sub-item
+ * instead, so the row still highlights on any of the module's pages, not just the first.
+ *
+ * Returns `undefined` when there's nothing to match, so a host can still supply its own `isActive`
+ * and take precedence (this only fills the gap left by the default behavior, it doesn't replace it).
+ */
+export function getModuleActiveMatcher(
+    to: string,
+    submenu: NavigationSubmenuData | undefined
+): ((pathname: string) => boolean) | undefined {
+    const candidates = [
+        ...(to ? [to] : []),
+        ...(submenu?.groups.flatMap(group => group.links.map(link => link.to)) ?? []),
+    ];
+
+    return candidates.length > 0
+        ? (pathname: string) => candidates.some(candidate => pathname.startsWith(candidate))
+        : undefined;
+}
+
 export function getSubmenuGroupTag(
     submenu: NavigationSubmenuData | undefined,
     defaultTag: CounterTagProps | undefined