@servicetitan/navigation 14.2.0 → 14.3.0

package/package.json

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

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,186 @@
+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.
+    expect(marketingStar().getAttribute('aria-pressed')).toBe('true');
+    expect(props.onPinnedIdsChange).not.toHaveBeenCalled();
+});
+
+it('keeps star edits on onPinnedIdsChange without calling the reset handler', () => {
+    const props = renderCatalog();
+    click(marketingStar());
+    expect(props.onPinnedIdsChange).toHaveBeenCalledWith([]);
+    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;