@servicetitan/navigation 14.2.0 → 14.4.0

package/src/components/titan-layout/use-navigation-scroll.ts

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getOverflowNotifications } from '../../utils/navigation-notifications';
+
+/**
+ * Measures what the rail's scroller is hiding, for the overflow notification pills.
+ *
+ * `enabled` is false on navigation versions that do not show the indicators. The refs are still
+ * handed back so the caller's markup is unchanged, but nothing is observed and no state is kept —
+ * this effect measures on every scroll and resize, which is not work to do for a feature that is
+ * switched off.
+ */
+export function useNavigationScroll(enabled = true) {
+    const regionRef = useRef<HTMLDivElement>(null);
+    const scrollRef = useRef<HTMLDivElement>(null);
+    const aboveIndicatorRef = useRef<HTMLDivElement>(null);
+    const belowIndicatorRef = useRef<HTMLDivElement>(null);
+    const targets = useRef<{ above?: HTMLElement; below?: HTMLElement }>({});
+    const [overflow, setOverflow] = useState({
+        above: 0,
+        below: 0,
+        hasContentAbove: false,
+        hasContentBelow: false,
+    });
+
+    /*
+     * The counted area, inset from the scrolling box by whichever notification pills are on
+     * screen. The pills float over the rail's own edges, so a row one covers is hidden even
+     * though it still sits inside the scroller — without the inset the rail can report a count
+     * of zero while a pill is physically covering the row it should be counting. Only the pills
+     * inset: the scroll shadow is a separate element precisely so its 12px gradient, which
+     * hides nothing, does not shrink the area.
+     */
+    const getCountedViewport = useCallback((scroller: HTMLElement) => {
+        const { top, bottom } = scroller.getBoundingClientRect();
+        return {
+            top: top + (aboveIndicatorRef.current?.offsetHeight ?? 0),
+            bottom: bottom - (belowIndicatorRef.current?.offsetHeight ?? 0),
+        };
+    }, []);
+
+    useEffect(() => {
+        const scroller = scrollRef.current;
+        const region = regionRef.current;
+        if (!enabled || !scroller || !region) {
+            return;
+        }
+        let frame = 0;
+        const measure = () => {
+            frame = 0;
+            const viewport = getCountedViewport(scroller);
+            const rows = Array.from(
+                scroller.querySelectorAll<HTMLElement>('[data-navigation-notification-count]')
+            );
+            const { above, below, aboveIndex, belowIndex } = getOverflowNotifications(
+                rows.map(row => {
+                    const { top, bottom } = row.getBoundingClientRect();
+                    return {
+                        top,
+                        bottom,
+                        count: Number(row.dataset.navigationNotificationCount) || 0,
+                    };
+                }),
+                viewport
+            );
+            targets.current = { above: rows[aboveIndex], below: rows[belowIndex] };
+            const hasContentAbove = scroller.scrollTop > 1;
+            const hasContentBelow =
+                scroller.scrollHeight - scroller.clientHeight - scroller.scrollTop > 1;
+            setOverflow(previous =>
+                previous.above === above &&
+                previous.below === below &&
+                previous.hasContentAbove === hasContentAbove &&
+                previous.hasContentBelow === hasContentBelow
+                    ? previous
+                    : { above, below, hasContentAbove, hasContentBelow }
+            );
+        };
+        const scheduleMeasure = () => {
+            if (!frame) {
+                frame = requestAnimationFrame(measure);
+            }
+        };
+        const resizeObserver = new ResizeObserver(scheduleMeasure);
+        resizeObserver.observe(scroller);
+        if (scroller.firstElementChild) {
+            resizeObserver.observe(scroller.firstElementChild);
+        }
+        const mutationObserver = new MutationObserver(scheduleMeasure);
+        /*
+         * The whole region rather than just the scroller: the pills mount and unmount as siblings
+         * of the scrolling element, and their height feeds back into the counted area above. The
+         * pass this schedules settles immediately, since a pill's height does not change with the
+         * number it shows (the label cannot wrap).
+         */
+        mutationObserver.observe(region, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ['data-navigation-notification-count', 'class', 'style'],
+        });
+        scroller.addEventListener('scroll', scheduleMeasure, { passive: true });
+        scheduleMeasure();
+        return () => {
+            cancelAnimationFrame(frame);
+            resizeObserver.disconnect();
+            mutationObserver.disconnect();
+            scroller.removeEventListener('scroll', scheduleMeasure);
+        };
+    }, [enabled, getCountedViewport]);
+
+    const revealNotification = useCallback(
+        (direction: 'above' | 'below') => {
+            const scroller = scrollRef.current;
+            const target = targets.current[direction];
+            if (!scroller || !target) {
+                return;
+            }
+            // Centred within the counted area, so the row lands clear of both pills.
+            const viewport = getCountedViewport(scroller);
+            const row = target.getBoundingClientRect();
+            // Reveal the item without activating its link or changing the selected destination.
+            target.focus({ preventScroll: true });
+            scroller.scrollTo({
+                top:
+                    scroller.scrollTop +
+                    row.top -
+                    viewport.top -
+                    (viewport.bottom - viewport.top - row.height) / 2,
+                behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches
+                    ? 'auto'
+                    : 'smooth',
+            });
+        },
+        [getCountedViewport]
+    );
+
+    return {
+        regionRef,
+        scrollRef,
+        aboveIndicatorRef,
+        belowIndicatorRef,
+        ...overflow,
+        revealNotification,
+    };
+}

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__/navigation-notifications.test.ts

@@ -0,0 +1,70 @@
+import { NavigationItemData } from '../navigation';
+import {
+    getModuleNotificationCount,
+    getNotificationCount,
+    getOverflowNotifications,
+} from '../navigation-notifications';
+
+describe('navigation notification counts', () => {
+    it('counts dot badges and positive counters, ignoring empty and invalid counters', () => {
+        expect(getNotificationCount(true)).toBe(1);
+        expect(getNotificationCount(123)).toBe(123);
+        [undefined, false, 0, -1, NaN, Infinity].forEach(value => {
+            expect(getNotificationCount(value)).toBe(0);
+        });
+    });
+
+    it('counts child counters and tags once as a module opens and closes', () => {
+        const module: NavigationItemData = {
+            id: 'accounting',
+            title: 'Accounting',
+            to: '/accounting',
+            icon: undefined,
+            iconActive: undefined,
+            counter: 3,
+            submenu: {
+                groups: [
+                    {
+                        title: 'Financials',
+                        links: [
+                            { id: 'inbox', title: 'Inbox', to: '/inbox', counter: 2 },
+                            { id: 'bills', title: 'Bills', to: '/bills', tag: { value: true } },
+                        ],
+                    },
+                ],
+            },
+        };
+        expect(getModuleNotificationCount(module, false)).toBe(3);
+        expect(getModuleNotificationCount(module, true)).toBe(0);
+        expect(getModuleNotificationCount({ ...module, submenu: undefined }, true)).toBe(3);
+    });
+
+    it('sums fully hidden rows and selects the closest notification on either side', () => {
+        expect(
+            getOverflowNotifications(
+                [
+                    { top: 0, bottom: 20, count: 2 },
+                    { top: 20, bottom: 40, count: 1 },
+                    { top: 60, bottom: 80, count: 3 },
+                    { top: 120, bottom: 140, count: 1 },
+                    { top: 140, bottom: 160, count: 2 },
+                ],
+                { top: 40, bottom: 120 }
+            )
+        ).toEqual({ above: 3, below: 3, aboveIndex: 1, belowIndex: 3 });
+    });
+
+    it('excludes partially visible, hidden, and cleared notification rows', () => {
+        expect(
+            getOverflowNotifications(
+                [
+                    { top: 20, bottom: 60, count: 1 },
+                    { top: 100, bottom: 140, count: 1 },
+                    { top: 0, bottom: 0, count: 5 },
+                    { top: 140, bottom: 180, count: 0 },
+                ],
+                { top: 40, bottom: 120 }
+            )
+        ).toEqual({ above: 0, below: 0, aboveIndex: -1, belowIndex: -1 });
+    });
+});

package/src/utils/__tests__/submenu-state.test.ts

@@ -0,0 +1,39 @@
+import { updateOpenSubmenus } from '../submenu-state';
+
+describe('updateOpenSubmenus', () => {
+    it('expands a partially open rail without duplicating ids or mutating host state', () => {
+        const current = ['accounting', 'hidden-module'];
+        expect(updateOpenSubmenus(current, ['accounting', 'dispatch', 'inventory'], true)).toEqual([
+            'accounting',
+            'hidden-module',
+            'dispatch',
+            'inventory',
+        ]);
+        expect(current).toEqual(['accounting', 'hidden-module']);
+    });
+
+    it('collapses only the visible modules and preserves unpinned module state', () => {
+        expect(
+            updateOpenSubmenus(
+                ['accounting', 'hidden-module', 'dispatch'],
+                ['accounting', 'dispatch'],
+                false
+            )
+        ).toEqual(['hidden-module']);
+    });
+
+    it('keeps individual and bulk actions consistent across repeated toggles', () => {
+        const visible = ['accounting', 'dispatch'];
+        const expanded = updateOpenSubmenus([], visible, true);
+        const partial = updateOpenSubmenus(expanded, ['accounting'], false);
+        expect(partial).toEqual(['dispatch']);
+        const collapsed = updateOpenSubmenus(partial, visible, false);
+        expect(collapsed).toEqual([]);
+        expect(updateOpenSubmenus(collapsed, visible, true)).toEqual(visible);
+    });
+
+    it('leaves state unchanged when no visible modules have child pages', () => {
+        expect(updateOpenSubmenus(['hidden-module'], [], false)).toEqual(['hidden-module']);
+        expect(updateOpenSubmenus([], [], true)).toEqual([]);
+    });
+});

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/navigation-notifications.ts

@@ -0,0 +1,59 @@
+import { CounterTagValue } from './counter-tag';
+import { NavigationItemData } from './navigation';
+
+export const getNotificationCount = (value: CounterTagValue | undefined): number =>
+    value === true
+        ? 1
+        : typeof value === 'number' && Number.isFinite(value) && value > 0
+          ? value
+          : 0;
+
+/** A closed module summarizes its pages; an open module lets each page count itself. */
+export function getModuleNotificationCount(item: NavigationItemData, submenuOpened: boolean) {
+    const childCount = (item.submenu?.groups ?? []).reduce(
+        (total, group) =>
+            total +
+            group.links.reduce(
+                (sum, link) => sum + getNotificationCount(link.counter ?? link.tag?.value),
+                0
+            ),
+        0
+    );
+    return childCount > 0
+        ? submenuOpened
+            ? 0
+            : childCount
+        : getNotificationCount(item.counter ?? item.tag?.value);
+}
+
+export interface NotificationRowBounds {
+    top: number;
+    bottom: number;
+    count: number;
+}
+
+/** Only fully offscreen rows contribute; partially visible notifications are still discoverable. */
+export function getOverflowNotifications(
+    rows: NotificationRowBounds[],
+    viewport: { top: number; bottom: number }
+) {
+    let above = 0;
+    let below = 0;
+    let aboveIndex = -1;
+    let belowIndex = -1;
+    rows.forEach((row, index) => {
+        if (row.count <= 0 || row.bottom <= row.top) {
+            return;
+        }
+        if (row.bottom <= viewport.top) {
+            above += row.count;
+            aboveIndex = index;
+        } else if (row.top >= viewport.bottom) {
+            below += row.count;
+            if (belowIndex === -1) {
+                belowIndex = index;
+            }
+        }
+    });
+    return { above, below, aboveIndex, belowIndex };
+}

package/src/utils/side-nav.ts

@@ -14,7 +14,7 @@ export function getSubmenuGroupTag(
 
     for (const group of submenu.groups) {
         for (const link of group.links) {
-            const ltv: number | boolean | undefined = link.counter;
+            const ltv: number | boolean | undefined = link.counter ?? link.tag?.value;
 
             if (ltv) {
                 if (typeof ltv === 'number') {

package/src/utils/submenu-state.ts

@@ -0,0 +1,16 @@
+/** Update only the requested modules, preserving the state of modules outside the action. */
+export const updateOpenSubmenus = (
+    current: readonly string[],
+    moduleIds: readonly string[],
+    opened: boolean
+): string[] => {
+    const next = new Set(current);
+    moduleIds.forEach(id => {
+        if (opened) {
+            next.add(id);
+        } else {
+            next.delete(id);
+        }
+    });
+    return [...next];
+};