@servicetitan/navigation 14.3.0 → 14.5.0

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

@@ -4,42 +4,34 @@ import IconStar from '@servicetitan/anvil2/assets/icons/material/round/star.svg'
 import IconStarBorder from '@servicetitan/anvil2/assets/icons/material/round/star_border.svg';
 import classNames from 'classnames';
 import { FC, Fragment, MouseEvent, useMemo, useRef, useState } from 'react';
+import {
+    filterCatalogGroups,
+    getCatalogChildren,
+    getCatalogSubmenuGroups,
+} from '../../../utils/catalog-groups';
 import { NavigationItemData } from '../../../utils/navigation';
 import { getCounterTag } from '../../../utils/side-nav';
 import { BadgeTag } from '../../badge-tag';
-import { NavigationCatalogGroup, PinnedNavigationConfig } from '../interface';
+import { PinnedNavigationConfig } from '../interface';
 import { useTitanLayoutContext } from '../layout-context';
 import { NavigationCatalogFooter } from './navigation-catalog-footer';
 import * as styles from './navigation-catalog.module.less';
 
-/** The pages beneath an item, flattened out of its submenu groups. */
-const childrenOf = (item: NavigationItemData) => {
-    const seen = new Set<string>();
-
-    return (item.submenu?.groups ?? []).flatMap(group =>
-        (group.links ?? []).filter(link => {
-            if (seen.has(link.id)) {
-                return false;
-            }
-
-            seen.add(link.id);
-            return true;
-        })
-    );
-};
-
 /** Shown in place of the pin control for a destination the user may not unpin. */
 const LockedPin: FC = () => (
     <Tooltip>
         <Tooltip.Trigger>
             <Icon svg={IconLock} className={styles.lock} />
         </Tooltip.Trigger>
-        <Tooltip.Content>Cannot be removed from Favorites</Tooltip.Content>
+        <Tooltip.Content style={{ pointerEvents: 'none' }}>
+            Cannot be removed from Favorites
+        </Tooltip.Content>
     </Tooltip>
 );
 
 interface PinToggleProps {
-    pinned: boolean;
+    /** Mixed modules stay highlighted but use an outline until all pages are pinned. */
+    pinned: boolean | 'mixed';
     label: string;
     onToggle: () => void;
 }
@@ -58,16 +50,20 @@ const PinToggle: FC<PinToggleProps> = ({ pinned, label, onToggle }) => {
                 <Button
                     appearance="ghost"
                     size="small"
-                    icon={pinned ? IconStar : IconStarBorder}
-                    // Only a control that covers nothing but pinned rows is lit.
+                    icon={pinned === true ? IconStar : IconStarBorder}
                     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>
-                {pinned ? 'Remove from Favorites' : 'Add to Favorites'}
+            <Tooltip.Content style={{ pointerEvents: 'none' }}>
+                {pinned === 'mixed'
+                    ? 'Add this module to Favorites'
+                    : pinned
+                      ? 'Remove from Favorites'
+                      : 'Add to Favorites'}
             </Tooltip.Content>
         </Tooltip>
     );
@@ -100,7 +96,7 @@ const CatalogRows: FC<CatalogRowsProps> = ({
     onNavigate,
 }) => {
     const { NavigationComponent } = useTitanLayoutContext();
-    const children = childrenOf(item);
+    const submenuGroups = getCatalogSubmenuGroups(item);
 
     /*
      * Minus anything locked — locked destinations are always present, so the module's control
@@ -108,6 +104,7 @@ const CatalogRows: FC<CatalogRowsProps> = ({
      */
     const everything = scopeIds.filter(id => !isLocked(id));
     const anyPinned = everything.some(isPinned);
+    const allPinned = everything.length > 0 && everything.every(isPinned);
     const tag = getCounterTag(item.counter, item.tag);
 
     return (
@@ -120,9 +117,9 @@ const CatalogRows: FC<CatalogRowsProps> = ({
                     aria-label={item.title}
                 >
                     {item.icon && (
-                        <Icon svg={item.icon} size="small" className={styles.moduleIcon} />
+                        <Icon svg={item.icon} size="medium" className={styles.moduleIcon} />
                     )}
-                    <Text inline className={styles.moduleTitle}>
+                    <Text inline size="small" className={styles.moduleTitle}>
                         {item.title}
                     </Text>
                     {/*
@@ -136,110 +133,80 @@ const CatalogRows: FC<CatalogRowsProps> = ({
                  * One control for the whole module: favouriting it takes its pages with it, and
                  * unfavouriting it takes them away again.
                  *
-                 * Lit when *any* page under it is favourited, because that is exactly when the
-                 * module is on the rail — the star reports whether the module is there, not
-                 * whether every page under it is. Reporting "all" instead would leave an unlit
-                 * star on a module the user can plainly see in the navigation.
+                 * 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.
                  */}
                 {isLocked(item.id) ? (
                     <LockedPin />
                 ) : (
                     <PinToggle
-                        pinned={anyPinned}
+                        pinned={allPinned ? true : anyPinned ? 'mixed' : false}
                         label={
-                            anyPinned
+                            allPinned
                                 ? `Unpin ${item.title} from the navigation`
                                 : `Pin ${item.title} to the navigation`
                         }
-                        onToggle={() => onToggleAll(everything, !anyPinned)}
+                        onToggle={() => onToggleAll(everything, !allPinned)}
                     />
                 )}
             </div>
-            {children.map(child => {
-                /*
-                 * Page titles are only unique within their item — "Settings" and "Reports" recur
-                 * across the catalog — and the row that tells them apart is a separate element, so
-                 * it is not part of any of these names. Anything reading the rows on their own, a
-                 * screen reader running through the links or a voice command naming one, would
-                 * otherwise be given the same name several times.
-                 */
-                const qualifiedTitle = `${item.title}: ${child.title}`;
-                const childPinned = isPinned(child.id);
-                const childTag = getCounterTag(child.counter, child.tag);
-
-                return (
-                    <div key={child.id} className={styles.row}>
-                        <NavigationComponent
-                            to={child.to}
-                            className={classNames(styles.link, styles.childLink)}
-                            onClick={onNavigate}
-                            aria-label={qualifiedTitle}
-                        >
-                            <Text inline className={styles.childTitle}>
-                                {child.title}
-                            </Text>
-                            {!!childTag && <BadgeTag data={childTag} className={styles.badge} />}
-                        </NavigationComponent>
-                        {isLocked(child.id) ? (
-                            <LockedPin />
-                        ) : (
-                            <PinToggle
-                                pinned={childPinned}
-                                label={
-                                    childPinned
-                                        ? `Unpin ${qualifiedTitle} from the navigation`
-                                        : `Pin ${qualifiedTitle} to the navigation`
-                                }
-                                onToggle={() => onTogglePin(child.id, item.id)}
-                            />
-                        )}
-                    </div>
-                );
-            })}
+            {submenuGroups.map(group => (
+                <div key={group.links[0].id}>
+                    {group.title && (
+                        <Text variant="eyebrow" size="small" className={styles.submenuTitle}>
+                            {group.title}
+                        </Text>
+                    )}
+                    {group.links.map(child => {
+                        /*
+                         * Page titles are only unique within their item — "Settings" and "Reports" recur
+                         * across the catalog — and the row that tells them apart is a separate element, so
+                         * it is not part of any of these names. Anything reading the rows on their own, a
+                         * screen reader running through the links or a voice command naming one, would
+                         * otherwise be given the same name several times.
+                         */
+                        const qualifiedTitle = `${item.title}: ${child.title}`;
+                        const childPinned = isPinned(child.id);
+                        const childTag = getCounterTag(child.counter, child.tag);
+
+                        return (
+                            <div key={child.id} className={styles.row}>
+                                <NavigationComponent
+                                    to={child.to}
+                                    className={classNames(styles.link, styles.childLink)}
+                                    onClick={onNavigate}
+                                    aria-label={qualifiedTitle}
+                                >
+                                    <Text inline className={styles.childTitle}>
+                                        {child.title}
+                                    </Text>
+                                    {!!childTag && (
+                                        <BadgeTag data={childTag} className={styles.badge} />
+                                    )}
+                                </NavigationComponent>
+                                {isLocked(child.id) ? (
+                                    <LockedPin />
+                                ) : (
+                                    <PinToggle
+                                        pinned={childPinned}
+                                        label={
+                                            childPinned
+                                                ? `Unpin ${qualifiedTitle} from the navigation`
+                                                : `Pin ${qualifiedTitle} to the navigation`
+                                        }
+                                        onToggle={() => onTogglePin(child.id, item.id)}
+                                    />
+                                )}
+                            </div>
+                        );
+                    })}
+                </div>
+            ))}
         </div>
     );
 };
 
-/**
- * Narrows the catalog to the entries matching `query`.
- *
- * Matching is literal and never cascades: a row survives only when its own title matches. An item
- * whose title matches is kept as a bare row without the pages beneath it, and a section is kept
- * only for whatever survived under it, so the list only ever shrinks as the query grows.
- */
-const filterGroups = (groups: NavigationCatalogGroup[], query: string) => {
-    const needle = query.trim().toLowerCase();
-
-    if (!needle) {
-        return groups;
-    }
-
-    return groups.reduce<NavigationCatalogGroup[]>((out, group) => {
-        const items = group.items.reduce<NavigationItemData[]>((kept, item) => {
-            const matchingChildren = childrenOf(item).filter(child =>
-                child.title.toLowerCase().includes(needle)
-            );
-
-            if (matchingChildren.length > 0) {
-                kept.push({
-                    ...item,
-                    submenu: { groups: [{ title: '', links: matchingChildren }] },
-                });
-            } else if (item.title.toLowerCase().includes(needle)) {
-                kept.push({ ...item, submenu: undefined });
-            }
-
-            return kept;
-        }, []);
-
-        if (items.length > 0) {
-            out.push({ ...group, items });
-        }
-
-        return out;
-    }, []);
-};
-
 export interface NavigationCatalogProps extends PinnedNavigationConfig {
     open: boolean;
     onClose: () => void;
@@ -261,6 +228,7 @@ export const NavigationCatalog: FC<NavigationCatalogProps> = ({
     onResetToDefaults,
 }) => {
     const [query, setQuery] = useState('');
+    const isSearching = query.trim().length > 0;
     const searchRef = useRef<HTMLInputElement>(null);
 
     /*
@@ -271,7 +239,7 @@ export const NavigationCatalog: FC<NavigationCatalogProps> = ({
     const resolvedGroups = useMemo(() => groups(), [groups]);
 
     const visibleGroups = useMemo(
-        () => filterGroups(resolvedGroups, query),
+        () => filterCatalogGroups(resolvedGroups, query),
         [resolvedGroups, query]
     );
 
@@ -284,7 +252,10 @@ export const NavigationCatalog: FC<NavigationCatalogProps> = ({
             new Map(
                 resolvedGroups
                     .flatMap(group => group.items)
-                    .map(item => [item.id, [item.id, ...childrenOf(item).map(child => child.id)]])
+                    .map(item => [
+                        item.id,
+                        [item.id, ...getCatalogChildren(item).map(child => child.id)],
+                    ])
             ),
         [resolvedGroups]
     );
@@ -385,7 +356,9 @@ export const NavigationCatalog: FC<NavigationCatalogProps> = ({
                         onClear={() => setQuery('')}
                         aria-label="Go to"
                     />
-                    <div className={styles.results}>
+                    <div
+                        className={classNames(styles.results, isSearching && styles.searchResults)}
+                    >
                         {visibleGroups.length === 0 ? (
                             <div className={styles.empty}>
                                 {/*
@@ -395,7 +368,7 @@ export const NavigationCatalog: FC<NavigationCatalogProps> = ({
                                  * quoting an empty query at the user does not describe it.
                                  */}
                                 <Text subdued>
-                                    {query.trim() ? (
+                                    {isSearching ? (
                                         <Fragment>
                                             No navigation items match &ldquo;{query}&rdquo;.
                                         </Fragment>
@@ -405,25 +378,25 @@ export const NavigationCatalog: FC<NavigationCatalogProps> = ({
                                 </Text>
                             </div>
                         ) : (
-                            <div className={styles.columns}>
+                            <div className={isSearching ? undefined : styles.columns}>
                                 {visibleGroups.map(group => (
-                                    <div key={group.title} className={styles.group}>
+                                    <div
+                                        key={group.title}
+                                        className={isSearching ? undefined : styles.group}
+                                    >
                                         {/*
-                                         * `medium` is 0.75rem, a step below the destinations under
-                                         * it. A heading that matches or beats its contents in size
-                                         * competes with them, and this one does not need the room:
-                                         * it is already set apart by case, tracking and a grey that
-                                         * nothing else on the surface uses. `small` is 0.625rem,
-                                         * too small to take in at a glance once uppercased and
-                                         * letter-spaced.
+                                         * Browse uses titled columns. Search stacks matches at full
+                                         * width, keeping only each module's own submenu headings.
                                          */}
-                                        <Text
-                                            variant="eyebrow"
-                                            size="medium"
-                                            className={styles.groupTitle}
-                                        >
-                                            {group.title}
-                                        </Text>
+                                        {!isSearching && (
+                                            <Text
+                                                variant="eyebrow"
+                                                size="medium"
+                                                className={styles.groupTitle}
+                                            >
+                                                {group.title}
+                                            </Text>
+                                        )}
                                         {group.items.map(item => (
                                             <CatalogRows
                                                 key={item.id}

package/src/utils/__tests__/catalog-groups.test.ts

@@ -0,0 +1,97 @@
+import {
+    filterCatalogGroups,
+    getCatalogChildren,
+    getCatalogSubmenuGroups,
+} from '../catalog-groups';
+import { NavigationItemData } from '../navigation';
+
+const marketing: NavigationItemData = {
+    id: 'marketing',
+    title: 'Marketing',
+    to: '/marketing',
+    icon: undefined,
+    iconActive: undefined,
+    submenu: {
+        groups: [
+            {
+                title: 'Analytics',
+                links: [
+                    { id: 'overview', title: 'Marketing Overview', to: '/marketing/overview' },
+                    { id: 'one-time', title: 'One-Time Campaigns', to: '/marketing/one-time' },
+                ],
+            },
+            {
+                title: 'Campaigns',
+                links: [
+                    { id: 'manager', title: 'Campaign Manager', to: '/marketing/manager' },
+                    { id: 'templates', title: 'Email Templates', to: '/marketing/templates' },
+                ],
+            },
+        ],
+    },
+};
+const catalog = [{ title: 'Demand', items: [marketing] }];
+
+describe('catalog submenu groups', () => {
+    it('keeps matching pages under their original headings and in source order', () => {
+        const result = filterCatalogGroups(catalog, ' CAMPAIGN ');
+        expect(result[0].items[0].submenu?.groups).toEqual([
+            { title: 'Analytics', links: [marketing.submenu!.groups[0].links[1]] },
+            { title: 'Campaigns', links: [marketing.submenu!.groups[1].links[0]] },
+        ]);
+    });
+
+    it('omits groups with no matches without changing the full module used for bulk favorites', () => {
+        const result = filterCatalogGroups(catalog, 'email');
+        expect(result[0].items[0].submenu?.groups).toEqual([
+            { title: 'Campaigns', links: [marketing.submenu!.groups[1].links[1]] },
+        ]);
+        expect(getCatalogChildren(marketing).map(child => child.id)).toEqual([
+            'overview',
+            'one-time',
+            'manager',
+            'templates',
+        ]);
+        expect(marketing.submenu!.groups.map(group => group.links.length)).toEqual([2, 2]);
+    });
+
+    it('renders duplicate pages once and omits groups left empty by deduplication', () => {
+        const groups = getCatalogSubmenuGroups({
+            ...marketing,
+            submenu: {
+                groups: [
+                    { ...marketing.submenu!.groups[0], title: ' Analytics ' },
+                    { title: 'Duplicate', links: marketing.submenu!.groups[0].links },
+                    { title: 'Empty', links: [] },
+                    marketing.submenu!.groups[1],
+                ],
+            },
+        });
+        expect(groups).toEqual(marketing.submenu!.groups);
+    });
+
+    it('retains ungrouped pages without introducing a blank heading', () => {
+        const [group] = getCatalogSubmenuGroups({
+            ...marketing,
+            submenu: { groups: [{ title: '   ', links: marketing.submenu!.groups[0].links }] },
+        });
+        expect(group.title).toBe('');
+        expect(group.links).toEqual(marketing.submenu!.groups[0].links);
+    });
+
+    it('keeps module-only matches without adding unrelated child pages', () => {
+        const result = filterCatalogGroups(catalog, 'Marketing Overview');
+        expect(result[0].items[0].submenu?.groups[0].title).toBe('Analytics');
+        const moduleOnly = filterCatalogGroups(
+            [{ title: 'Demand', items: [{ ...marketing, title: 'Marketing Pro' }] }],
+            'Marketing Pro'
+        );
+        expect(moduleOnly[0].items[0].submenu).toBeUndefined();
+    });
+
+    it('restores the full catalog on clear and removes empty results', () => {
+        expect(filterCatalogGroups(catalog, ' ')).toBe(catalog);
+        expect(filterCatalogGroups(catalog, 'no such destination')).toEqual([]);
+        expect(getCatalogSubmenuGroups({ ...marketing, submenu: undefined })).toEqual([]);
+    });
+});

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/catalog-groups.ts

@@ -0,0 +1,57 @@
+import { NavigationCatalogGroup } from '../components/titan-layout/interface';
+import { NavigationItemData } from './navigation';
+
+/** Preserve submenu headings while offering each page only once within its module. */
+export const getCatalogSubmenuGroups = (item: NavigationItemData) => {
+    const seen = new Set<string>();
+
+    return (item.submenu?.groups ?? []).flatMap(group => {
+        const links = (group.links ?? []).filter(link => {
+            if (seen.has(link.id)) {
+                return false;
+            }
+
+            seen.add(link.id);
+            return true;
+        });
+
+        return links.length ? [{ ...group, title: group.title?.trim() ?? '', links }] : [];
+    });
+};
+
+export const getCatalogChildren = (item: NavigationItemData) =>
+    getCatalogSubmenuGroups(item).flatMap(group => group.links);
+
+/** Match destination titles literally, retaining the headings of matching child pages. */
+export const filterCatalogGroups = (groups: NavigationCatalogGroup[], query: string) => {
+    const needle = query.trim().toLowerCase();
+
+    if (!needle) {
+        return groups;
+    }
+
+    return groups.reduce<NavigationCatalogGroup[]>((out, group) => {
+        const items = group.items.reduce<NavigationItemData[]>((kept, item) => {
+            const matchingGroups = getCatalogSubmenuGroups(item).flatMap(submenuGroup => {
+                const links = submenuGroup.links.filter(child =>
+                    child.title.toLowerCase().includes(needle)
+                );
+                return links.length ? [{ ...submenuGroup, links }] : [];
+            });
+
+            if (matchingGroups.length > 0) {
+                kept.push({ ...item, submenu: { groups: matchingGroups } });
+            } else if (item.title.toLowerCase().includes(needle)) {
+                kept.push({ ...item, submenu: undefined });
+            }
+
+            return kept;
+        }, []);
+
+        if (items.length > 0) {
+            out.push({ ...group, items });
+        }
+
+        return out;
+    }, []);
+};

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