@servicetitan/navigation 14.2.0 → 14.3.0

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

@@ -15,7 +15,9 @@ import {
 } from 'react';
 import { NavigationItemData } from '../../utils/navigation';
 import { DefaultNavLinkComponent, NavLinkComponentProps } from '../../utils/navigation-context';
+import { updateOpenSubmenus } from '../../utils/submenu-state';
 import { useTitanBreakpoint } from '../../utils/use-breakpoint';
+import { PinnedNavigationConfig } from './interface';
 import {
     LayoutContext,
     LayoutPlacementContext,
@@ -50,6 +52,12 @@ export type TitanLayoutProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'
     /** data for main navigation links */
     navigationMainItems?: NavigationItemData[];
 
+    /**
+     * Turns the navigation catalog on: renders a trigger in the sidebar and the dialog behind it.
+     * Omit it and the navigation is unchanged.
+     */
+    pinnedNavigation?: PinnedNavigationConfig;
+
     /** data for overflow navigation links (used only with top variant) */
     navigationOverflowItems?: NavigationItemData[];
 
@@ -65,6 +73,13 @@ export type TitanLayoutProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'
     openSubmenus?: string[];
     /** submenu accordion open state change handler */
     onOpenSubmenuChange?: (id: string, opened: boolean) => void;
+    /**
+     * Receives the complete next set of open modules for individual and bulk actions.
+     * Preferred over onOpenSubmenuChange when provided, so bulk updates are atomic.
+     * Required for the rail's `Expand All` / `Collapse All` control, which is hidden
+     * for hosts that supply only the per-module `onOpenSubmenuChange`.
+     */
+    onOpenSubmenusChange?: (ids: string[]) => void;
 
     /** navigation link click handler */
     onNavigationLinkClick?: (itemId: string, submenuItemId?: string) => void;
@@ -78,6 +93,23 @@ export type TitanLayoutProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'
     /** top links for side navigation */
     sideTop?: ReactElement[];
 
+    /**
+     * Destinations pinned above the sidebar's divider, ahead of `sideTop`.
+     *
+     * Rendered with the same machinery as `navigationMainItems`, so one with pages beneath it is
+     * an expandable group rather than a bare link. `sideTop` is unchanged and still takes elements
+     * the host builds itself; the two can be used together.
+     */
+    sideTopItems?: NavigationItemData[];
+
+    /**
+     * Whether the sidebar shows the scroll and overflow-notification indicators.
+     *
+     * Defaults on, so a host that says nothing keeps them. Navigation versions that predate the
+     * indicators pass `false`.
+     */
+    navigationScrollIndicators?: boolean;
+
     /**
      * profile element for layout
      * @see ProfileDropdown
@@ -165,7 +197,9 @@ function TitanLayoutComponent({
     logo,
     onExpandedChange,
     onOpenSubmenuChange,
+    onOpenSubmenusChange,
     navigationMainItems,
+    pinnedNavigation,
     navigationOverflowItems,
     onNavigationLinkClick,
     extraLinks,
@@ -174,6 +208,8 @@ function TitanLayoutComponent({
     minContentWidth,
     noResponsive,
     sideTop,
+    sideTopItems,
+    navigationScrollIndicators = true,
 }: TitanLayoutProps) {
     const breakpoint = useTitanBreakpoint(noResponsive);
     const context: TitanLayoutContextType = useMemo(
@@ -194,7 +230,10 @@ function TitanLayoutComponent({
     const hasSideBar =
         !contentOnly &&
         (navVariant === 'left' || (navVariant === 'top' && isMobile)) &&
-        (!!navigationMainItems?.length || !!sideTop?.length);
+        (!!navigationMainItems?.length ||
+            !!sideTop?.length ||
+            !!sideTopItems?.length ||
+            !!pinnedNavigation);
     const hasTopBar = !contentOnly;
 
     useEffect(() => {
@@ -230,9 +269,26 @@ function TitanLayoutComponent({
     );
     const onSubmenuOpenChange = useCallback(
         (id: string, opened: boolean) => {
-            onOpenSubmenuChange?.(id, opened);
+            if (onOpenSubmenusChange) {
+                onOpenSubmenusChange(updateOpenSubmenus(openSubmenus ?? [], [id], opened));
+            } else {
+                onOpenSubmenuChange?.(id, opened);
+            }
+        },
+        [onOpenSubmenuChange, onOpenSubmenusChange, openSubmenus]
+    );
+    /*
+     * Bulk actions require `onOpenSubmenusChange`, which takes the whole next set at once.
+     * They are deliberately not emulated with `onOpenSubmenuChange`: that contract is one
+     * call per user action, so a host deriving its next list from the current one would see
+     * the same stale list on every call of a loop and keep only the last module. `Expand All`
+     * is hidden entirely when a host supplies only the per-module callback.
+     */
+    const onSubmenusOpenChange = useCallback(
+        (ids: string[], opened: boolean) => {
+            onOpenSubmenusChange?.(updateOpenSubmenus(openSubmenus ?? [], ids, opened));
         },
-        [onOpenSubmenuChange]
+        [onOpenSubmenusChange, openSubmenus]
     );
     const sidebarNavItems = useMemo(() => {
         if (!hasSideBar) {
@@ -246,10 +302,24 @@ function TitanLayoutComponent({
         return [...(navigationMainItems ?? []), ...(navigationOverflowItems ?? [])];
     }, [hasSideBar, navigationMainItems, navigationOverflowItems, navVariant]);
 
+    /*
+     * The burger badge speaks for the whole drawer, so it has to count what sits above the
+     * divider as well. A permanent destination asking for attention would otherwise go unseen
+     * while the drawer is closed.
+     */
+    const badgeNavItems = useMemo(
+        /*
+         * Gated on `hasSideBar`, not `sidebarNavItems`: on the left variant a rail that exists
+         * only for `sideTopItems` still has `sidebarNavItems` (i.e. `navigationMainItems`) undefined.
+         */
+        () => (hasSideBar ? [...(sideTopItems ?? []), ...(sidebarNavItems ?? [])] : undefined),
+        [hasSideBar, sideTopItems, sidebarNavItems]
+    );
+
     const hasMenuNotifications = useMemo(() => {
         try {
             return (
-                sidebarNavItems?.some(item => {
+                badgeNavItems?.some(item => {
                     if (item.counter || item.tag?.value) {
                         return true;
                     } else if (item.submenu) {
@@ -263,7 +333,7 @@ function TitanLayoutComponent({
         } catch {
             return false;
         }
-    }, [sidebarNavItems]);
+    }, [badgeNavItems]);
 
     const limitContentWidth = useMemo(() => {
         if (view.isAnvil2 || !minContentWidth) {
@@ -395,9 +465,15 @@ function TitanLayoutComponent({
                                 onBarExpandChange={onBarExpandChange}
                                 submenusOpened={openSubmenus}
                                 onSubmenuOpenChange={onSubmenuOpenChange}
+                                onSubmenusOpenChange={
+                                    onOpenSubmenusChange ? onSubmenusOpenChange : undefined
+                                }
                                 drawerOpened={mobileDrawerOpened}
                                 onDrawerOpenChange={setMobileDrawerOpened}
                                 top={sideTop}
+                                topItems={sideTopItems}
+                                scrollIndicators={navigationScrollIndicators}
+                                pinnedNavigation={pinnedNavigation}
                                 mainItems={sidebarNavItems}
                                 navigationComponent={context.NavigationComponent}
                                 onNavigationLinkClick={onNavigationLinkClick}

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__/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/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];
+};