@servicetitan/navigation 14.2.0 → 14.4.0

package/dist/utils/navigation-notifications.js

@@ -0,0 +1,39 @@
+export const getNotificationCount = (value)=>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, submenuOpened) {
+    var _ref, _item_counter;
+    var _item_submenu, _item_tag;
+    const childCount = ((_ref = (_item_submenu = item.submenu) === null || _item_submenu === void 0 ? void 0 : _item_submenu.groups) !== null && _ref !== void 0 ? _ref : []).reduce((total, group)=>total + group.links.reduce((sum, link)=>{
+            var _link_counter;
+            var _link_tag;
+            return sum + getNotificationCount((_link_counter = link.counter) !== null && _link_counter !== void 0 ? _link_counter : (_link_tag = link.tag) === null || _link_tag === void 0 ? void 0 : _link_tag.value);
+        }, 0), 0);
+    return childCount > 0 ? submenuOpened ? 0 : childCount : getNotificationCount((_item_counter = item.counter) !== null && _item_counter !== void 0 ? _item_counter : (_item_tag = item.tag) === null || _item_tag === void 0 ? void 0 : _item_tag.value);
+}
+/** Only fully offscreen rows contribute; partially visible notifications are still discoverable. */ export function getOverflowNotifications(rows, viewport) {
+    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
+    };
+}
+
+//# sourceMappingURL=navigation-notifications.js.map

package/dist/utils/navigation-notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/navigation-notifications.ts"],"sourcesContent":["import { CounterTagValue } from './counter-tag';\nimport { NavigationItemData } from './navigation';\n\nexport const getNotificationCount = (value: CounterTagValue | undefined): number =>\n    value === true\n        ? 1\n        : typeof value === 'number' && Number.isFinite(value) && value > 0\n          ? value\n          : 0;\n\n/** A closed module summarizes its pages; an open module lets each page count itself. */\nexport function getModuleNotificationCount(item: NavigationItemData, submenuOpened: boolean) {\n    const childCount = (item.submenu?.groups ?? []).reduce(\n        (total, group) =>\n            total +\n            group.links.reduce(\n                (sum, link) => sum + getNotificationCount(link.counter ?? link.tag?.value),\n                0\n            ),\n        0\n    );\n    return childCount > 0\n        ? submenuOpened\n            ? 0\n            : childCount\n        : getNotificationCount(item.counter ?? item.tag?.value);\n}\n\nexport interface NotificationRowBounds {\n    top: number;\n    bottom: number;\n    count: number;\n}\n\n/** Only fully offscreen rows contribute; partially visible notifications are still discoverable. */\nexport function getOverflowNotifications(\n    rows: NotificationRowBounds[],\n    viewport: { top: number; bottom: number }\n) {\n    let above = 0;\n    let below = 0;\n    let aboveIndex = -1;\n    let belowIndex = -1;\n    rows.forEach((row, index) => {\n        if (row.count <= 0 || row.bottom <= row.top) {\n            return;\n        }\n        if (row.bottom <= viewport.top) {\n            above += row.count;\n            aboveIndex = index;\n        } else if (row.top >= viewport.bottom) {\n            below += row.count;\n            if (belowIndex === -1) {\n                belowIndex = index;\n            }\n        }\n    });\n    return { above, below, aboveIndex, belowIndex };\n}\n"],"names":["getNotificationCount","value","Number","isFinite","getModuleNotificationCount","item","submenuOpened","childCount","submenu","groups","reduce","total","group","links","sum","link","counter","tag","getOverflowNotifications","rows","viewport","above","below","aboveIndex","belowIndex","forEach","row","index","count","bottom","top"],"mappings":"AAGA,OAAO,MAAMA,uBAAuB,CAACC,QACjCA,UAAU,OACJ,IACA,OAAOA,UAAU,YAAYC,OAAOC,QAAQ,CAACF,UAAUA,QAAQ,IAC7DA,QACA,EAAE;AAEd,sFAAsF,GACtF,OAAO,SAASG,2BAA2BC,IAAwB,EAAEC,aAAsB;cAc5DD;QAbPA,eAauBA;IAb3C,MAAME,aAAa,UAACF,gBAAAA,KAAKG,OAAO,cAAZH,oCAAAA,cAAcI,MAAM,uCAAI,EAAE,EAAEC,MAAM,CAClD,CAACC,OAAOC,QACJD,QACAC,MAAMC,KAAK,CAACH,MAAM,CACd,CAACI,KAAKC;gBAAoCA;gBAAgBA;mBAA3CD,MAAMd,sBAAqBe,gBAAAA,KAAKC,OAAO,cAAZD,2BAAAA,iBAAgBA,YAAAA,KAAKE,GAAG,cAARF,gCAAAA,UAAUd,KAAK;WACzE,IAER;IAEJ,OAAOM,aAAa,IACdD,gBACI,IACAC,aACJP,sBAAqBK,gBAAAA,KAAKW,OAAO,cAAZX,2BAAAA,iBAAgBA,YAAAA,KAAKY,GAAG,cAARZ,gCAAAA,UAAUJ,KAAK;AAC9D;AAQA,kGAAkG,GAClG,OAAO,SAASiB,yBACZC,IAA6B,EAC7BC,QAAyC;IAEzC,IAAIC,QAAQ;IACZ,IAAIC,QAAQ;IACZ,IAAIC,aAAa,CAAC;IAClB,IAAIC,aAAa,CAAC;IAClBL,KAAKM,OAAO,CAAC,CAACC,KAAKC;QACf,IAAID,IAAIE,KAAK,IAAI,KAAKF,IAAIG,MAAM,IAAIH,IAAII,GAAG,EAAE;YACzC;QACJ;QACA,IAAIJ,IAAIG,MAAM,IAAIT,SAASU,GAAG,EAAE;YAC5BT,SAASK,IAAIE,KAAK;YAClBL,aAAaI;QACjB,OAAO,IAAID,IAAII,GAAG,IAAIV,SAASS,MAAM,EAAE;YACnCP,SAASI,IAAIE,KAAK;YAClB,IAAIJ,eAAe,CAAC,GAAG;gBACnBA,aAAaG;YACjB;QACJ;IACJ;IACA,OAAO;QAAEN;QAAOC;QAAOC;QAAYC;IAAW;AAClD"}

package/dist/utils/side-nav.js

@@ -5,7 +5,9 @@ export function getSubmenuGroupTag(submenu, defaultTag) {
     let tagValue = undefined;
     for (const group of submenu.groups){
         for (const link of group.links){
-            const ltv = link.counter;
+            var _link_counter;
+            var _link_tag;
+            const ltv = (_link_counter = link.counter) !== null && _link_counter !== void 0 ? _link_counter : (_link_tag = link.tag) === null || _link_tag === void 0 ? void 0 : _link_tag.value;
             if (ltv) {
                 if (typeof ltv === 'number') {
                     if (typeof tagValue !== 'number') {

package/dist/utils/side-nav.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/side-nav.ts"],"sourcesContent":["import { CounterTagProps } from '../components/counter-tag';\nimport { CounterTagData, CounterTagValue } from './counter-tag';\nimport { NavigationSubmenuData } from './navigation';\n\nexport function getSubmenuGroupTag(\n    submenu: NavigationSubmenuData | undefined,\n    defaultTag: CounterTagProps | undefined\n): CounterTagProps | undefined {\n    if (!submenu) {\n        return defaultTag;\n    }\n\n    let tagValue: number | boolean | undefined = undefined;\n\n    for (const group of submenu.groups) {\n        for (const link of group.links) {\n            const ltv: number | boolean | undefined = link.counter;\n\n            if (ltv) {\n                if (typeof ltv === 'number') {\n                    if (typeof tagValue !== 'number') {\n                        tagValue = 0;\n                    }\n                    tagValue += ltv;\n                } else if (typeof tagValue !== 'number') {\n                    tagValue = true;\n                }\n            }\n        }\n    }\n\n    return tagValue ? getCounterTag(tagValue) : defaultTag;\n}\n\nexport const getCounterTag = (\n    counter: CounterTagValue | undefined,\n    tag?: CounterTagData\n): CounterTagProps | undefined => {\n    const value = counter ?? tag?.value;\n\n    return value ? { value, className: '' } : undefined;\n};\n"],"names":["getSubmenuGroupTag","submenu","defaultTag","tagValue","undefined","group","groups","link","links","ltv","counter","getCounterTag","tag","value","className"],"mappings":"AAIA,OAAO,SAASA,mBACZC,OAA0C,EAC1CC,UAAuC;IAEvC,IAAI,CAACD,SAAS;QACV,OAAOC;IACX;IAEA,IAAIC,WAAyCC;IAE7C,KAAK,MAAMC,SAASJ,QAAQK,MAAM,CAAE;QAChC,KAAK,MAAMC,QAAQF,MAAMG,KAAK,CAAE;YAC5B,MAAMC,MAAoCF,KAAKG,OAAO;YAEtD,IAAID,KAAK;gBACL,IAAI,OAAOA,QAAQ,UAAU;oBACzB,IAAI,OAAON,aAAa,UAAU;wBAC9BA,WAAW;oBACf;oBACAA,YAAYM;gBAChB,OAAO,IAAI,OAAON,aAAa,UAAU;oBACrCA,WAAW;gBACf;YACJ;QACJ;IACJ;IAEA,OAAOA,WAAWQ,cAAcR,YAAYD;AAChD;AAEA,OAAO,MAAMS,gBAAgB,CACzBD,SACAE;IAEA,MAAMC,QAAQH,oBAAAA,qBAAAA,UAAWE,gBAAAA,0BAAAA,IAAKC,KAAK;IAEnC,OAAOA,QAAQ;QAAEA;QAAOC,WAAW;IAAG,IAAIV;AAC9C,EAAE"}
+{"version":3,"sources":["../../src/utils/side-nav.ts"],"sourcesContent":["import { CounterTagProps } from '../components/counter-tag';\nimport { CounterTagData, CounterTagValue } from './counter-tag';\nimport { NavigationSubmenuData } from './navigation';\n\nexport function getSubmenuGroupTag(\n    submenu: NavigationSubmenuData | undefined,\n    defaultTag: CounterTagProps | undefined\n): CounterTagProps | undefined {\n    if (!submenu) {\n        return defaultTag;\n    }\n\n    let tagValue: number | boolean | undefined = undefined;\n\n    for (const group of submenu.groups) {\n        for (const link of group.links) {\n            const ltv: number | boolean | undefined = link.counter ?? link.tag?.value;\n\n            if (ltv) {\n                if (typeof ltv === 'number') {\n                    if (typeof tagValue !== 'number') {\n                        tagValue = 0;\n                    }\n                    tagValue += ltv;\n                } else if (typeof tagValue !== 'number') {\n                    tagValue = true;\n                }\n            }\n        }\n    }\n\n    return tagValue ? getCounterTag(tagValue) : defaultTag;\n}\n\nexport const getCounterTag = (\n    counter: CounterTagValue | undefined,\n    tag?: CounterTagData\n): CounterTagProps | undefined => {\n    const value = counter ?? tag?.value;\n\n    return value ? { value, className: '' } : undefined;\n};\n"],"names":["getSubmenuGroupTag","submenu","defaultTag","tagValue","undefined","group","groups","link","links","ltv","counter","tag","value","getCounterTag","className"],"mappings":"AAIA,OAAO,SAASA,mBACZC,OAA0C,EAC1CC,UAAuC;IAEvC,IAAI,CAACD,SAAS;QACV,OAAOC;IACX;IAEA,IAAIC,WAAyCC;IAE7C,KAAK,MAAMC,SAASJ,QAAQK,MAAM,CAAE;QAChC,KAAK,MAAMC,QAAQF,MAAMG,KAAK,CAAE;gBACcD;gBAAgBA;YAA1D,MAAME,OAAoCF,gBAAAA,KAAKG,OAAO,cAAZH,2BAAAA,iBAAgBA,YAAAA,KAAKI,GAAG,cAARJ,gCAAAA,UAAUK,KAAK;YAEzE,IAAIH,KAAK;gBACL,IAAI,OAAOA,QAAQ,UAAU;oBACzB,IAAI,OAAON,aAAa,UAAU;wBAC9BA,WAAW;oBACf;oBACAA,YAAYM;gBAChB,OAAO,IAAI,OAAON,aAAa,UAAU;oBACrCA,WAAW;gBACf;YACJ;QACJ;IACJ;IAEA,OAAOA,WAAWU,cAAcV,YAAYD;AAChD;AAEA,OAAO,MAAMW,gBAAgB,CACzBH,SACAC;IAEA,MAAMC,QAAQF,oBAAAA,qBAAAA,UAAWC,gBAAAA,0BAAAA,IAAKC,KAAK;IAEnC,OAAOA,QAAQ;QAAEA;QAAOE,WAAW;IAAG,IAAIV;AAC9C,EAAE"}

package/dist/utils/submenu-state.d.ts

@@ -0,0 +1,3 @@
+/** Update only the requested modules, preserving the state of modules outside the action. */
+export declare const updateOpenSubmenus: (current: readonly string[], moduleIds: readonly string[], opened: boolean) => string[];
+//# sourceMappingURL=submenu-state.d.ts.map

package/dist/utils/submenu-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submenu-state.d.ts","sourceRoot":"","sources":["../../src/utils/submenu-state.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,eAAO,MAAM,kBAAkB,GAC3B,SAAS,SAAS,MAAM,EAAE,EAC1B,WAAW,SAAS,MAAM,EAAE,EAC5B,QAAQ,OAAO,KAChB,MAAM,EAUR,CAAC"}

package/dist/utils/submenu-state.js

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

package/dist/utils/submenu-state.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/submenu-state.ts"],"sourcesContent":["/** Update only the requested modules, preserving the state of modules outside the action. */\nexport const updateOpenSubmenus = (\n    current: readonly string[],\n    moduleIds: readonly string[],\n    opened: boolean\n): string[] => {\n    const next = new Set(current);\n    moduleIds.forEach(id => {\n        if (opened) {\n            next.add(id);\n        } else {\n            next.delete(id);\n        }\n    });\n    return [...next];\n};\n"],"names":["updateOpenSubmenus","current","moduleIds","opened","next","Set","forEach","id","add","delete"],"mappings":"AAAA,2FAA2F,GAC3F,OAAO,MAAMA,qBAAqB,CAC9BC,SACAC,WACAC;IAEA,MAAMC,OAAO,IAAIC,IAAIJ;IACrBC,UAAUI,OAAO,CAACC,CAAAA;QACd,IAAIJ,QAAQ;YACRC,KAAKI,GAAG,CAACD;QACb,OAAO;YACHH,KAAKK,MAAM,CAACF;QAChB;IACJ;IACA,OAAO;WAAIH;KAAK;AACpB,EAAE"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/navigation",
-    "version": "14.2.0",
+    "version": "14.4.0",
     "description": "Navigation components",
     "repository": {
         "type": "git",
@@ -35,5 +35,5 @@
         "less": true,
         "webpack": false
     },
-    "gitHead": "d1f4e9cbaf1ec2c270dc2d3fdb21b862ae5ee1f7"
+    "gitHead": "b64111bc6e95671da2480fa57b27a09c85520c4b"
 }

package/src/components/titan-layout/__tests__/layout-sidebar-links-internal.test.tsx

@@ -0,0 +1,225 @@
+import { ButtonHTMLAttributes, useState } from 'react';
+import { Root, createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { NavLinkComponentProps } from '../../../utils/navigation-context';
+import {
+    InternalSideNavigationGroup,
+    InternalSideNavigationGroupLink,
+} from '../layout-sidebar-links-internal';
+
+jest.mock('@servicetitan/anvil2', () => ({
+    Button: ({
+        appearance,
+        size,
+        icon,
+        ...props
+    }: ButtonHTMLAttributes<HTMLButtonElement> & {
+        appearance?: string;
+        size?: string;
+        icon?: unknown;
+    }) => <button {...props} />,
+    Icon: () => null,
+}));
+
+jest.mock('../with-tooltip', () => ({ withTooltip: (element: unknown) => element }));
+
+let container: HTMLDivElement;
+let root: Root;
+const actEnvironment = globalThis as typeof globalThis &
+    Record<'IS_REACT_ACT_ENVIRONMENT', boolean | undefined>;
+const previousActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
+
+beforeAll(() => {
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+afterAll(() => {
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+});
+
+beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+});
+
+afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+});
+
+function click(element: Element) {
+    act(() => {
+        element.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
+    });
+}
+
+function pressKey(element: Element, key: string) {
+    const event = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true });
+    act(() => {
+        element.dispatchEvent(event);
+    });
+    return event;
+}
+
+const getChildLink = () =>
+    container.querySelector('[data-cy="navigation-item-pricebook--services"]');
+
+function renderGroup(to: string | undefined = '/pricebook', initialOpened = false) {
+    const navigate = jest.fn();
+    const closeDrawer = jest.fn();
+    const onSubmenuOpen = jest.fn();
+
+    // Like a host router, this link owns its click handler and does not consult defaultPrevented.
+    const NavigationLink = ({
+        to: destination,
+        isActive,
+        activeClassName,
+        ...props
+    }: NavLinkComponentProps) => (
+        <a
+            {...props}
+            href={destination}
+            onClick={event => {
+                event.preventDefault();
+                navigate(destination);
+            }}
+        />
+    );
+
+    function Fixture() {
+        const [opened, setOpened] = useState(initialOpened);
+        return (
+            <div onClick={closeDrawer}>
+                <InternalSideNavigationGroup
+                    id="pricebook"
+                    to={to}
+                    title="Pricebook"
+                    isActive={undefined}
+                    icon={undefined}
+                    iconActive={undefined}
+                    className={undefined}
+                    tag={undefined}
+                    submenuOpened={opened}
+                    onSubmenuOpen={(id, nextOpened) => {
+                        onSubmenuOpen(id, nextOpened);
+                        setOpened(nextOpened);
+                    }}
+                    navigationComponent={NavigationLink}
+                >
+                    <InternalSideNavigationGroupLink
+                        id="services"
+                        parentId="pricebook"
+                        to="/pricebook/services"
+                        title="Services"
+                        isActive={undefined}
+                        className={undefined}
+                        tag={undefined}
+                        navigationComponent={NavigationLink}
+                    />
+                </InternalSideNavigationGroup>
+            </div>
+        );
+    }
+
+    act(() => root.render(<Fixture />));
+    const moduleTrigger = container.querySelector<HTMLElement>(
+        '[data-cy="navigation-item-pricebook"]'
+    )!;
+    return { moduleTrigger, navigate, closeDrawer, onSubmenuOpen };
+}
+
+it.each(['/pricebook', '/pricebook/materials'])(
+    'opens on the module name and navigates to the configured %p route',
+    to => {
+        const { moduleTrigger, navigate, closeDrawer, onSubmenuOpen } = renderGroup(to);
+
+        click(moduleTrigger);
+        expect(getChildLink()).toBeTruthy();
+        expect(moduleTrigger.getAttribute('href')).toBe(to);
+        expect(moduleTrigger.getAttribute('role')).toBeNull();
+        expect(moduleTrigger.getAttribute('aria-expanded')).toBe('true');
+        expect(document.getElementById(moduleTrigger.getAttribute('aria-controls')!)).toBeTruthy();
+
+        // The chevron is the only control that collapses an open module.
+        click(container.querySelector('button[aria-label="Collapse Pricebook submenu"]')!);
+        expect(getChildLink()).toBeNull();
+        expect(moduleTrigger.getAttribute('aria-expanded')).toBe('false');
+
+        click(container.querySelector('button[aria-label="Expand Pricebook submenu"]')!);
+        expect(getChildLink()).toBeTruthy();
+        expect(onSubmenuOpen.mock.calls).toEqual([
+            ['pricebook', true],
+            ['pricebook', false],
+            ['pricebook', true],
+        ]);
+        expect(navigate.mock.calls).toEqual([[to]]);
+        expect(closeDrawer).not.toHaveBeenCalled();
+    }
+);
+
+it.each(['/pricebook', '/pricebook/materials'])(
+    'keeps an open module open and still navigates to %p from its name',
+    to => {
+        const { moduleTrigger, navigate, onSubmenuOpen } = renderGroup(to, true);
+
+        expect(getChildLink()).toBeTruthy();
+
+        click(moduleTrigger);
+        expect(getChildLink()).toBeTruthy();
+        expect(moduleTrigger.getAttribute('aria-expanded')).toBe('true');
+        expect(navigate.mock.calls).toEqual([[to]]);
+        expect(onSubmenuOpen).not.toHaveBeenCalled();
+
+        click(moduleTrigger);
+        expect(getChildLink()).toBeTruthy();
+        expect(navigate.mock.calls).toEqual([[to], [to]]);
+        expect(onSubmenuOpen).not.toHaveBeenCalled();
+    }
+);
+
+it.each(['Enter', ' '])('opens and navigates to the module destination with the %p key', key => {
+    const { moduleTrigger, navigate, closeDrawer, onSubmenuOpen } = renderGroup();
+
+    moduleTrigger.focus();
+    expect(pressKey(moduleTrigger, key).defaultPrevented).toBe(true);
+    expect(getChildLink()).toBeTruthy();
+    expect(document.activeElement).toBe(moduleTrigger);
+
+    pressKey(moduleTrigger, key);
+    expect(getChildLink()).toBeTruthy();
+    expect(onSubmenuOpen).toHaveBeenCalledTimes(1);
+    expect(navigate.mock.calls).toEqual([['/pricebook'], ['/pricebook']]);
+    expect(closeDrawer).not.toHaveBeenCalled();
+});
+
+it('still navigates and closes the drawer when a child page is selected', () => {
+    const { moduleTrigger, navigate, closeDrawer, onSubmenuOpen } = renderGroup();
+
+    click(moduleTrigger);
+    navigate.mockClear();
+    click(getChildLink()!);
+
+    expect(navigate).toHaveBeenCalledWith('/pricebook/services');
+    expect(navigate).toHaveBeenCalledTimes(1);
+    expect(closeDrawer).toHaveBeenCalledTimes(1);
+    expect(onSubmenuOpen).toHaveBeenCalledTimes(1);
+});
+
+// A group with no destination has nothing to navigate to, so its name stays a plain toggle.
+it('still lets groups without a destination toggle from their name', () => {
+    const { moduleTrigger, onSubmenuOpen } = renderGroup('');
+
+    expect(moduleTrigger.tabIndex).toBe(0);
+    click(moduleTrigger);
+
+    expect(getChildLink()).toBeTruthy();
+    expect(onSubmenuOpen).toHaveBeenCalledTimes(1);
+
+    click(moduleTrigger);
+    expect(getChildLink()).toBeNull();
+    expect(onSubmenuOpen.mock.calls).toEqual([
+        ['pricebook', true],
+        ['pricebook', false],
+    ]);
+});

package/src/components/titan-layout/__tests__/navigation-catalog-reset.test.tsx

@@ -0,0 +1,190 @@
+import { ComponentPropsWithoutRef, PropsWithChildren } from 'react';
+import { Root, createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import {
+    NavigationCatalog,
+    NavigationCatalogProps,
+} from '../navigation-catalog/navigation-catalog';
+
+// Keep the real catalog/confirmation logic; substitute only Anvil's browser-dependent primitives.
+jest.mock('@servicetitan/anvil2', () => {
+    const { forwardRef } = jest.requireActual<typeof import('react')>('react');
+    const Box = ({ children }: PropsWithChildren) => <div>{children}</div>;
+
+    return {
+        Dialog: Object.assign(({ children }: PropsWithChildren) => <div>{children}</div>, {
+            Content: Box,
+            Footer: Box,
+        }),
+        Text: Box,
+        Icon: () => null,
+        Tooltip: Object.assign(Box, { Trigger: Box, Content: () => null }),
+        Button: forwardRef<
+            HTMLButtonElement,
+            ComponentPropsWithoutRef<'button'> & {
+                appearance?: string;
+                size?: string;
+                icon?: unknown;
+            }
+        >(function MockButton({ appearance, size, icon, ...props }, ref) {
+            return <button ref={ref} {...props} />;
+        }),
+        SearchField: forwardRef<
+            HTMLInputElement,
+            Omit<ComponentPropsWithoutRef<'input'>, 'size'> & {
+                size?: string;
+                onClear?: () => void;
+            }
+        >(function MockSearchField({ size, onClear, ...props }, ref) {
+            return <input ref={ref} {...props} />;
+        }),
+    };
+});
+
+let container: HTMLDivElement;
+let root: Root;
+const actEnvironment = globalThis as typeof globalThis &
+    Record<'IS_REACT_ACT_ENVIRONMENT', boolean | undefined>;
+const previousActEnvironment = actEnvironment.IS_REACT_ACT_ENVIRONMENT;
+
+beforeAll(() => {
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = true;
+});
+afterAll(() => {
+    actEnvironment.IS_REACT_ACT_ENVIRONMENT = previousActEnvironment;
+});
+beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+});
+afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+});
+
+const pinned = ['marketing', 'overview'];
+const groups: NavigationCatalogProps['groups'] = () => [
+    {
+        title: 'Demand',
+        items: [
+            {
+                id: 'marketing',
+                title: 'Marketing',
+                to: '/marketing',
+                icon: undefined,
+                iconActive: undefined,
+                submenu: {
+                    groups: [
+                        {
+                            title: 'Analytics',
+                            links: [
+                                { id: 'overview', title: 'Overview', to: '/marketing/overview' },
+                                { id: 'campaigns', title: 'Campaigns', to: '/marketing/campaigns' },
+                            ],
+                        },
+                    ],
+                },
+            },
+        ],
+    },
+];
+
+const renderCatalog = (overrides: Partial<NavigationCatalogProps> = {}) => {
+    const props = {
+        open: true,
+        onClose: jest.fn(),
+        groups,
+        pinnedIds: pinned,
+        onPinnedIdsChange: jest.fn(),
+        onResetToDefaults: jest.fn(),
+        ...overrides,
+    };
+    act(() => root.render(<NavigationCatalog {...props} />));
+    return props;
+};
+const button = (text: string) =>
+    [...container.querySelectorAll('button')].find(element => element.textContent === text);
+const click = (element: Element) => {
+    act(() => element.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })));
+};
+const marketingStar = () => container.querySelector('button[aria-label*="Marketing"]')!;
+
+it('reports only a confirmed reset, without proposing a list of its own', () => {
+    const props = renderCatalog();
+    click(button('Restore Default Favorites')!);
+    expect(props.onResetToDefaults).not.toHaveBeenCalled();
+    expect(document.activeElement).toBe(button('Cancel'));
+
+    click(button('Cancel')!);
+    expect(props.onResetToDefaults).not.toHaveBeenCalled();
+    expect(props.onPinnedIdsChange).not.toHaveBeenCalled();
+    expect(document.activeElement).toBe(button('Restore Default Favorites'));
+
+    click(button('Restore Default Favorites')!);
+    click(button('Restore')!);
+    expect(props.onResetToDefaults).toHaveBeenCalledTimes(1);
+    expect(props.onResetToDefaults).toHaveBeenCalledWith();
+    expect(props.onPinnedIdsChange).not.toHaveBeenCalled();
+    expect(document.activeElement).toBe(container.querySelector('input'));
+});
+
+it('leaves favorites untouched until the host applies the reset', () => {
+    const props = renderCatalog();
+    click(button('Restore Default Favorites')!);
+    click(button('Restore')!);
+    /*
+     * Fully controlled: the catalog has proposed nothing, so the rows still read as they did —
+     * `mixed` here, because two of Marketing's three ids are favourited and not the third.
+     */
+    expect(marketingStar().getAttribute('aria-pressed')).toBe('mixed');
+    expect(props.onPinnedIdsChange).not.toHaveBeenCalled();
+});
+
+it('keeps star edits on onPinnedIdsChange without calling the reset handler', () => {
+    const props = renderCatalog();
+    // A partly favourited module completes itself rather than clearing: campaigns joins the list.
+    click(marketingStar());
+    expect(props.onPinnedIdsChange).toHaveBeenCalledWith(['marketing', 'overview', 'campaigns']);
+    expect(props.onResetToDefaults).not.toHaveBeenCalled();
+});
+
+it('hides restore when the host does not offer one', () => {
+    renderCatalog({ onResetToDefaults: undefined });
+    expect(button('Restore Default Favorites')).toBeUndefined();
+});
+
+it('drops a pending confirmation when the host withdraws the handler', () => {
+    const props = renderCatalog();
+    click(button('Restore Default Favorites')!);
+    renderCatalog({ ...props, onResetToDefaults: undefined });
+    expect(button('Restore')).toBeUndefined();
+    expect(props.onResetToDefaults).not.toHaveBeenCalled();
+});
+
+it('calls the handler the host supplies now, not the one it confirmed against', () => {
+    const previous = renderCatalog();
+    click(button('Restore Default Favorites')!);
+    const current = renderCatalog({ ...previous, onResetToDefaults: jest.fn() });
+    click(button('Restore')!);
+    expect(current.onResetToDefaults).toHaveBeenCalledTimes(1);
+    expect(previous.onResetToDefaults).not.toHaveBeenCalled();
+});
+
+it('reports reset intent while search hides all destinations, preserving the query', () => {
+    const props = renderCatalog();
+    const input = container.querySelector('input')!;
+    act(() => {
+        Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')!.set!.call(
+            input,
+            'no matching page'
+        );
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+    expect(container.textContent).toContain('No navigation items match');
+    click(button('Restore Default Favorites')!);
+    click(button('Restore')!);
+    expect(props.onResetToDefaults).toHaveBeenCalledTimes(1);
+    expect(props.onPinnedIdsChange).not.toHaveBeenCalled();
+    expect(input.value).toBe('no matching page');
+});

package/src/components/titan-layout/interface.ts

@@ -1,6 +1,7 @@
 import { IconProps } from '@servicetitan/anvil2';
 import { ComponentPropsWithoutRef, FC, ReactNode } from 'react';
 import { CounterTagData, CounterTagValue } from '../../utils/counter-tag';
+import { NavigationItemData } from '../../utils/navigation';
 import { TitanLayoutSidebarContextType } from './layout-context';
 
 export interface TitanLayoutLinkWrapperProps {
@@ -11,6 +12,78 @@ export interface TitanLayoutLinkWrapperProps {
 
 export type TitanLayoutLinkWrapper = FC<TitanLayoutLinkWrapperProps>;
 
+/** A titled section of the navigation catalog. */
+export interface NavigationCatalogGroup {
+    /** section heading */
+    title: string;
+
+    /**
+     * The destinations in this section.
+     *
+     * `id` is treated as an opaque pin id and is compared verbatim against `pinnedIds`, so the host
+     * is responsible for handing over ids in whatever form it stores them. Any `submenu` links are
+     * offered as separately pinnable pages beneath their item, and their `id`s are pin ids too.
+     */
+    items: NavigationItemData[];
+}
+
+/**
+ * Turns the navigation catalog on.
+ *
+ * Supplying this renders a catalog trigger in the sidebar and the dialog behind it; omitting it
+ * leaves the navigation exactly as it was. The layout owns the dialog, its open state and the
+ * keyboard shortcut, and nothing else about pinning: it proposes a new list, or reports that the
+ * user confirmed a reset, and the host decides what to do with either.
+ */
+export interface PinnedNavigationConfig {
+    /**
+     * Every destination on offer, resolved on demand.
+     *
+     * A function rather than an array because resolving a catalog is not free for every host: one
+     * whose submenus are dynamic pays a request per module to enumerate its pages. The dialog is
+     * mounted only while open, so taking the groups as a thunk keeps that cost — and any failure
+     * in it — inside the dialog instead of on every page load of the shell.
+     *
+     * Called once per open, and again only if the function's identity changes, so a host should
+     * memoize it against whatever its resolution actually depends on.
+     */
+    groups: () => NavigationCatalogGroup[];
+
+    /** The pinned ids, in display order. */
+    pinnedIds: string[];
+
+    /**
+     * Ids the user may not pin or unpin.
+     *
+     * A locked destination is always present in the navigation whether or not it appears in
+     * `pinnedIds`, so the catalog shows a lock where the pin control would be and never proposes a
+     * list that adds or removes one.
+     */
+    lockedIds?: string[];
+
+    /**
+     * The list the user just asked for through a star control, in full.
+     *
+     * Fully controlled: nothing changes until `pinnedIds` comes back different. A host that
+     * declines the proposal simply does not apply it, and the control returns to its previous
+     * state on its own. Confirming a reset calls `onResetToDefaults` instead.
+     */
+    onPinnedIdsChange: (pinnedIds: string[]) => void;
+
+    /**
+     * Called once the user confirms Restore Default Favorites.
+     *
+     * The catalog reports the intent and proposes nothing: what the defaults are, whether locked
+     * destinations survive and how the reset is persisted are all the host's. Favourites move only
+     * when the host sends new `pinnedIds` down, and the catalog does not also call
+     * `onPinnedIdsChange`.
+     *
+     * Omit it to hide the restore control — including when the host offers defaults but the user
+     * has not strayed from them, which only the host can know.
+     */
+    onResetToDefaults?: () => void;
+}
+
 export interface TitanLayoutLinkExtraProps {
     /** link's title should be shown (for extra links we show icon only by default) */
     showTitle?: boolean;