@servicetitan/navigation 14.2.0 → 14.3.0

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

@@ -1,12 +1,16 @@
-import { Divider, Icon, Popover, Text, ThemeProvider } from '@servicetitan/anvil2';
+import { Button, Divider, Icon, Popover, Text, ThemeProvider } from '@servicetitan/anvil2';
 import SvgClose from '@servicetitan/anvil2/assets/icons/material/round/close.svg';
+import SvgCollapseAll from '@servicetitan/anvil2/assets/icons/material/round/unfold_less.svg';
+import SvgExpandAll from '@servicetitan/anvil2/assets/icons/material/round/unfold_more.svg';
 import SvgCollapse from '@servicetitan/anvil2/assets/icons/st/gnav_menu_collapse.svg';
 import SvgExpand from '@servicetitan/anvil2/assets/icons/st/gnav_menu_expand.svg';
 import classNames from 'classnames';
 import { Children, FC, Fragment, ReactElement, isValidElement } from 'react';
 import { NavigationItemData, NavigationSubmenuData } from '../../utils/navigation';
 import { NavLinkComponentProps } from '../../utils/navigation-context';
+import { getModuleNotificationCount } from '../../utils/navigation-notifications';
 import { getCounterTag, getSubmenuGroupTag } from '../../utils/side-nav';
+import { PinnedNavigationConfig } from './interface';
 import { NavigationComponentProps } from './interface-internal';
 import { LayoutPlacementContext, useTitanLayoutContext } from './layout-context';
 import {
@@ -15,13 +19,30 @@ import {
     InternalSideNavigationLink,
 } from './layout-sidebar-links-internal';
 import * as Styles from './layout-sidebar.module.less';
+import { NavigationCatalogTrigger } from './navigation-catalog';
+import { NavigationScrollIndicators } from './navigation-scroll-indicators';
+import { useNavigationScroll } from './use-navigation-scroll';
 import { withTooltip } from './with-tooltip';
 
 export interface LayoutSidebarProps {
     className?: string;
     top?: ReactElement[];
+
+    /**
+     * Destinations rendered above the divider, ahead of `top`.
+     *
+     * Separate from `top` rather than widening it: that one takes elements a host builds itself
+     * and renders them as-is, which is what a bespoke control needs. This takes navigation items
+     * and puts them through the same renderer as `mainItems`, so one with pages beneath it is an
+     * expandable group instead of being flattened to a bare link.
+     */
+    topItems?: NavigationItemData[];
+
+    /** Whether the rail shows the scroll and overflow-notification indicators. */
+    scrollIndicators?: boolean;
     bottom?: ReactElement;
     mainItems?: NavigationItemData[];
+    pinnedNavigation?: PinnedNavigationConfig;
     barExpanded: boolean;
     submenusOpened: string[] | undefined;
     drawerOpened: boolean;
@@ -31,6 +52,7 @@ export interface LayoutSidebarProps {
     onBarExpandChange(expanded: boolean): void;
     onDrawerOpenChange(expanded: boolean): void;
     onSubmenuOpenChange(id: string, opened: boolean): void;
+    onSubmenusOpenChange?(ids: string[], opened: boolean): void;
     onNavigationLinkClick?(itemId: string, submenuItemId?: string): void;
 }
 
@@ -43,13 +65,19 @@ export const LayoutSidebar: FC<LayoutSidebarProps> = ({
     drawerOpened,
     onBarExpandChange,
     onSubmenuOpenChange,
+    onSubmenusOpenChange,
     onDrawerOpenChange,
     onNavigationLinkClick,
     mainItems,
+    pinnedNavigation,
     top,
+    topItems,
+    scrollIndicators,
     bottom,
     navigationComponent,
 }) => {
+    const { regionRef, scrollRef, revealNotification, ...scrollOverflow } =
+        useNavigationScroll(scrollIndicators);
     const closeDrawer = () => {
         if (mobile) {
             onDrawerOpenChange?.(false);
@@ -57,6 +85,90 @@ export const LayoutSidebar: FC<LayoutSidebarProps> = ({
     };
 
     const effectiveExpanded = mobile ? drawerOpened : barExpanded;
+    /*
+     * Both regions, because a destination above the divider expands exactly like one below it.
+     * Counting only `mainItems` would let Expand All skip those groups — and hide the control
+     * entirely on a rail whose only expandable modules sit up there.
+     */
+    const expandableIds = [...(topItems ?? []), ...(mainItems ?? [])]
+        .filter(item => item.submenu?.groups.some(group => group.links.length > 0))
+        .map(item => item.id);
+    const hasOpenSubmenus = expandableIds.some(id => submenusOpened?.includes(id));
+    const toggleAllLabel = hasOpenSubmenus ? 'Collapse All' : 'Expand All';
+    const toggleAll =
+        effectiveExpanded && expandableIds.length > 0 && onSubmenusOpenChange
+            ? withTooltip(
+                  <Button
+                      appearance="secondary"
+                      size="small"
+                      icon={hasOpenSubmenus ? SvgCollapseAll : SvgExpandAll}
+                      aria-label={toggleAllLabel}
+                      aria-expanded={hasOpenSubmenus}
+                      data-cy="navigation-toggle-all"
+                      data-pendo="navigation-toggle-all"
+                      onClick={event => {
+                          event.stopPropagation();
+                          onSubmenusOpenChange(expandableIds, !hasOpenSubmenus);
+                      }}
+                  />,
+                  toggleAllLabel,
+                  { placement: 'top' }
+              )
+            : undefined;
+
+    const scrollHeader = !mobile && !barExpanded;
+    const navigationHeader = (
+        <div className={Styles.navHeader}>
+            {mobile && (
+                <div className={Styles.navCloseWrapper}>
+                    <div className={Styles.navClose} onClick={() => onBarExpandChange(false)}>
+                        <Icon svg={SvgClose} size="large" />
+                    </div>
+                </div>
+            )}
+            {pinnedNavigation && (
+                <NavigationCatalogTrigger
+                    expanded={effectiveExpanded}
+                    {...pinnedNavigation}
+                    trailingAction={toggleAll}
+                />
+            )}
+            {!pinnedNavigation && toggleAll && <div className={Styles.navTools}>{toggleAll}</div>}
+        </div>
+    );
+
+    /*
+     * Shared by the region above the divider and the list below it, so a destination renders the
+     * same way wherever the host puts it. Two copies of this branch would drift.
+     */
+    const renderItems = (items: NavigationItemData[] | undefined) =>
+        items?.map(item =>
+            item.submenu ? (
+                <SideNavigationGroupItem
+                    key={item.id}
+                    item={item}
+                    barExpanded={effectiveExpanded}
+                    submenuOpened={!!item.id && !!submenusOpened?.includes(item.id)}
+                    onSubmenuOpen={onSubmenuOpenChange}
+                    navigationComponent={navigationComponent}
+                    onNavigationLinkClick={onNavigationLinkClick}
+                    touchDevice={touchDevice}
+                />
+            ) : (
+                <InternalSideNavigationLink
+                    key={item.id}
+                    id={item.id}
+                    to={item.to}
+                    title={effectiveExpanded ? item.title : (item.collapsedTitle ?? item.title)}
+                    isActive={item.isActive}
+                    icon={item.icon}
+                    iconActive={item.iconActive}
+                    className={item.className}
+                    tag={getSubmenuGroupTag(item.submenu, getCounterTag(item.counter, item.tag))}
+                    navigationComponent={navigationComponent}
+                />
+            )
+        );
 
     return (
         <LayoutPlacementContext.Provider value="side">
@@ -74,69 +186,46 @@ export const LayoutSidebar: FC<LayoutSidebarProps> = ({
                 data-cy="side-navigation"
                 onClick={closeDrawer}
             >
-                <ThemeProvider mode="dark" className={Styles.navMain}>
-                    {mobile && (
-                        <div className={Styles.navCloseWrapper}>
-                            <div
-                                className={Styles.navClose}
-                                onClick={() => onBarExpandChange(false)}
-                            >
-                                <Icon svg={SvgClose} size="large" />
+                <ThemeProvider mode="dark" className={Styles.navContent}>
+                    {!scrollHeader && navigationHeader}
+                    <div ref={regionRef} className={Styles.navScrollRegion}>
+                        <div ref={scrollRef} className={Styles.navMain} data-cy="navigation-scroll">
+                            <div>
+                                {scrollHeader && navigationHeader}
+                                {(!!top?.length || !!topItems?.length) && (
+                                    <SidebarTop>
+                                        {renderItems(topItems)}
+                                        {top}
+                                    </SidebarTop>
+                                )}
+
+                                <div className={Styles.navItems} data-cy="navigation-items">
+                                    {renderItems(mainItems)}
+                                </div>
+
+                                {!!bottom && <SidebarBottom>{bottom}</SidebarBottom>}
                             </div>
                         </div>
-                    )}
-                    {!!top?.length && <SidebarTop>{top}</SidebarTop>}
-
-                    <div data-cy="navigation-items">
-                        {mainItems?.map(item =>
-                            item.submenu ? (
-                                <SideNavigationGroupItem
-                                    key={item.id}
-                                    item={item}
-                                    barExpanded={effectiveExpanded}
-                                    submenuOpened={!!item.id && !!submenusOpened?.includes(item.id)}
-                                    onSubmenuOpen={onSubmenuOpenChange}
-                                    navigationComponent={navigationComponent}
-                                    onNavigationLinkClick={onNavigationLinkClick}
-                                    touchDevice={touchDevice}
-                                />
-                            ) : (
-                                <InternalSideNavigationLink
-                                    key={item.id}
-                                    id={item.id}
-                                    to={item.to}
-                                    title={
-                                        effectiveExpanded
-                                            ? item.title
-                                            : (item.collapsedTitle ?? item.title)
-                                    }
-                                    isActive={item.isActive}
-                                    icon={item.icon}
-                                    iconActive={item.iconActive}
-                                    className={item.className}
-                                    tag={getSubmenuGroupTag(
-                                        item.submenu,
-                                        getCounterTag(item.counter, item.tag)
-                                    )}
-                                    navigationComponent={navigationComponent}
-                                />
-                            )
+                        {scrollIndicators && (
+                            <NavigationScrollIndicators
+                                {...scrollOverflow}
+                                expanded={effectiveExpanded}
+                                onReveal={revealNotification}
+                            />
                         )}
                     </div>
-
-                    {!!bottom && <SidebarBottom>{bottom}</SidebarBottom>}
                 </ThemeProvider>
 
                 {!mobile && (
-                    <div className={Styles.navFooter}>
+                    <ThemeProvider mode="dark" className={Styles.navFooter}>
                         <div className={Styles.divider} />
                         <div className={Styles.toggleWrapper}>
                             <SideNavigationOptionsToggle
-                                appearance={barExpanded ? 'collapse-button' : 'expand'}
+                                expanded={barExpanded}
                                 onExpandedChange={() => onBarExpandChange(!barExpanded)}
                             />
                         </div>
-                    </div>
+                    </ThemeProvider>
                 )}
             </div>
         </LayoutPlacementContext.Provider>
@@ -146,43 +235,22 @@ LayoutSidebar.displayName = 'LayoutSidebar';
 
 /** Side Navigation options toggle */
 const SideNavigationOptionsToggle: FC<{
-    appearance: 'expand' | 'collapse' | 'collapse-button';
+    expanded: boolean;
     onExpandedChange?(expanded: boolean): void;
-}> = ({ appearance, onExpandedChange }) =>
+}> = ({ expanded, onExpandedChange }) =>
     withTooltip(
-        <div
-            role="button"
-            tabIndex={0}
+        <Button
+            appearance="ghost"
+            size="small"
+            icon={expanded ? SvgCollapse : SvgExpand}
             data-cy="navigation-left-options"
             data-pendo="navigation-left-options"
-            aria-label={appearance === 'expand' ? 'Expand Menu' : 'Collapse Menu'}
-            className={classNames(Styles.toggle)}
-            onClick={() => onExpandedChange?.(appearance === 'expand')}
-            onKeyDown={e => {
-                if (e.key === 'Enter' || e.key === ' ') {
-                    e.preventDefault();
-                    onExpandedChange?.(appearance === 'expand');
-                }
-            }}
-        >
-            <div className={Styles.toggleContent}>
-                <div className={Styles.toggleIconWrapper}>
-                    <Icon
-                        className={Styles.toggleIcon}
-                        svg={appearance === 'expand' ? SvgExpand : SvgCollapse}
-                    />
-                </div>
-
-                {appearance === 'collapse-button' && (
-                    <span className={Styles.toggleText}>Collapse Menu</span>
-                )}
-            </div>
-        </div>,
-        appearance === 'expand'
-            ? 'Expand Menu'
-            : appearance === 'collapse'
-              ? 'Collapse Menu'
-              : undefined,
+            aria-label={expanded ? 'Collapse Menu' : 'Expand Menu'}
+            aria-expanded={expanded}
+            className={Styles.toggle}
+            onClick={() => onExpandedChange?.(!expanded)}
+        />,
+        expanded ? 'Collapse Menu' : 'Expand Menu',
         { placement: 'right' }
     );
 
@@ -222,6 +290,7 @@ const SideNavigationGroupItem: FC<{
             iconActive={item.iconActive}
             className={item.className}
             tag={tag}
+            notificationCount={getModuleNotificationCount(item, submenuOpened)}
             submenuOpened={submenuOpened}
             onSubmenuOpen={onSubmenuOpen}
             navigationComponent={navigationComponent}
@@ -234,7 +303,13 @@ const SideNavigationGroupItem: FC<{
             />
         </InternalSideNavigationGroup>
     ) : (
-        <Popover placement="right-start" openOnHover={!touchDevice} delay={200} noPadding>
+        <Popover
+            placement="right-start"
+            openOnHover={!touchDevice}
+            delay={200}
+            noPadding
+            disableCaret
+        >
             <Popover.Trigger>
                 {(triggerProps: any) => (
                     <div {...triggerProps}>
@@ -250,6 +325,7 @@ const SideNavigationGroupItem: FC<{
                                 touchDevice && Styles.pointerEventsNone
                             )}
                             tag={tag}
+                            notificationCount={getModuleNotificationCount(item, false)}
                             navigationComponent={navigationComponent}
                         />
                     </div>
@@ -291,43 +367,42 @@ const SideNavigationGroupContent: FC<
 > = ({ groups, parentId, navigationComponent, onNavigationLinkClick }) => {
     return (
         <Fragment>
-            {groups.reduce((out, group, index) => {
+            {groups.map((group, index) => {
                 if (!group.links.length) {
-                    return out;
+                    return null;
                 }
 
                 const title = group.title?.trim() ?? '';
                 /* eslint-disable react/no-array-index-key */
-                if (title) {
-                    out.push(
-                        <div
-                            key={`:group:${parentId}:${index}:title`}
-                            className={Styles.submenuGroupHeader}
-                        >
-                            {title}
-                        </div>
-                    );
-                }
-                out.push(
-                    ...group.links.map((link, index) => (
-                        <InternalSideNavigationGroupLink
-                            key={`:${parentId}:${link.id}:${index}`}
-                            id={link.id}
-                            to={link.to}
-                            title={link.title}
-                            isActive={link.isActive}
-                            className={undefined}
-                            tag={getCounterTag(link.counter, link.tag)}
-                            parentId={parentId}
-                            navigationComponent={navigationComponent}
-                            onLinkClick={onNavigationLinkClick}
-                        />
-                    ))
+                return (
+                    <div key={`:group:${parentId}:${index}`} className={Styles.submenuGroup}>
+                        {title && (
+                            <Text
+                                variant="eyebrow"
+                                size="small"
+                                className={Styles.submenuGroupHeader}
+                            >
+                                {title}
+                            </Text>
+                        )}
+                        {group.links.map((link, index) => (
+                            <InternalSideNavigationGroupLink
+                                key={`:${parentId}:${link.id}:${index}`}
+                                id={link.id}
+                                to={link.to}
+                                title={link.title}
+                                isActive={link.isActive}
+                                className={undefined}
+                                tag={getCounterTag(link.counter, link.tag)}
+                                parentId={parentId}
+                                navigationComponent={navigationComponent}
+                                onLinkClick={onNavigationLinkClick}
+                            />
+                        ))}
+                    </div>
                 );
                 /* eslint-enable react/no-array-index-key */
-
-                return out;
-            }, [] as ReactElement[])}
+            })}
         </Fragment>
     );
 };
@@ -338,8 +413,9 @@ function SidebarTop({ children }: any) {
     });
     return list?.length ? (
         <ThemeProvider mode="dark" className={Styles.navTop} data-cy="navigation-items-top">
-            {list}
-            <div className={Styles.divider} />
+            <div className={Styles.navTopItems}>{list}</div>
+            {/* Anvil 2 spacing 3 resolves to the design's 12px above and below. */}
+            <Divider spacing={3} className={Styles.topDivider} />
         </ThemeProvider>
     ) : null;
 }

package/src/components/titan-layout/navigation-catalog/index.ts

@@ -0,0 +1,2 @@
+export * from './navigation-catalog';
+export * from './navigation-catalog-trigger';

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

@@ -0,0 +1,88 @@
+import { Button, Dialog, Text } from '@servicetitan/anvil2';
+import IconUndo from '@servicetitan/anvil2/assets/icons/material/round/undo.svg';
+import { FC, Fragment, useEffect, useId, useRef, useState } from 'react';
+import * as styles from './navigation-catalog.module.less';
+
+interface NavigationCatalogFooterProps {
+    /** Present only when the current favorites differ from the host's defaults. */
+    onRestore?: () => void;
+}
+
+export const NavigationCatalogFooter: FC<NavigationCatalogFooterProps> = ({ onRestore }) => {
+    const [confirming, setConfirming] = useState(false);
+    const cancelRef = useRef<HTMLButtonElement>(null);
+    const restoreRef = useRef<HTMLButtonElement>(null);
+    const returnFocus = useRef(false);
+    const confirmationId = useId();
+
+    useEffect(() => {
+        if (confirming) {
+            cancelRef.current?.focus();
+        } else if (returnFocus.current) {
+            restoreRef.current?.focus();
+            returnFocus.current = false;
+        }
+    }, [confirming]);
+
+    useEffect(() => {
+        if (!onRestore) {
+            setConfirming(false);
+        }
+    }, [onRestore]);
+
+    return (
+        <Dialog.Footer className={styles.footer} data-cy="navigation-catalog-footer">
+            {confirming && onRestore ? (
+                <Fragment>
+                    <Text size="small" id={confirmationId}>
+                        This action replaces your current favorites. You can favorite items again
+                        anytime.
+                    </Text>
+                    <div className={styles.footerActions}>
+                        <Button
+                            ref={cancelRef}
+                            appearance="secondary"
+                            size="xsmall"
+                            aria-describedby={confirmationId}
+                            onClick={() => {
+                                returnFocus.current = true;
+                                setConfirming(false);
+                            }}
+                        >
+                            Cancel
+                        </Button>
+                        <Button
+                            appearance="primary"
+                            size="xsmall"
+                            aria-describedby={confirmationId}
+                            onClick={() => {
+                                setConfirming(false);
+                                onRestore();
+                            }}
+                        >
+                            Restore
+                        </Button>
+                    </div>
+                </Fragment>
+            ) : (
+                <Fragment>
+                    <Text size="small" subdued>
+                        Add or remove items to your navigation by clicking the star icon to the
+                        right
+                    </Text>
+                    {onRestore && (
+                        <Button
+                            ref={restoreRef}
+                            appearance="secondary"
+                            size="xsmall"
+                            icon={IconUndo}
+                            onClick={() => setConfirming(true)}
+                        >
+                            Restore Default Favorites
+                        </Button>
+                    )}
+                </Fragment>
+            )}
+        </Dialog.Footer>
+    );
+};

package/src/components/titan-layout/navigation-catalog/navigation-catalog-trigger.module.less

@@ -0,0 +1,89 @@
+@import (reference) '@servicetitan/tokens/core/tokens.less';
+
+/*
+ * Scoped to `.anvil2.anvil2` so these rules outrank anvil2's own.
+ *
+ * anvil2 nests every component rule under `.anvil2`, giving it two classes of specificity,
+ * which a bare class here loses to. Doubling the scope wins outright and leaves the selectors
+ * inside it plain, rather than each one having to defend itself with `!important`.
+ */
+:global(.anvil2.anvil2) {
+    .container {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        padding: @spacing-1 @spacing-1 @spacing-2;
+
+        > :last-child:not(:first-child) {
+            flex-shrink: 0;
+        }
+    }
+
+    /*
+     * The rail stretches its children to its own width, so the button follows rather than sizing to
+     * its label. Everything else about the control — surface, border, radius, focus ring, hover — is
+     * the anvil2 secondary button's own.
+     */
+    .trigger {
+        width: 100%;
+        min-width: 0;
+        flex: 1;
+    }
+
+    // The reference uses the core subdued swatch (#bcbcbd).
+    .triggerLabel {
+        color: @color-neutral-70;
+        line-height: @spacing-2;
+        white-space: nowrap;
+    }
+
+    /*
+     * Held back from the label so the chord reads as an aside rather than as part of the name, and
+     * kept from wrapping when the rail is at its narrowest expanded width.
+     */
+    .shortcut {
+        --a2-mod-chip-min-height: @spacing-2;
+        --a2-mod-chip-inner-padding-block: 1px;
+
+        white-space: nowrap;
+        flex-shrink: 0;
+    }
+
+    .containerCollapsed {
+        // Together with the button's 6px bottom inset, keep 12px before Dashboard's icon box.
+        padding: @spacing-0 @spacing-0 6px;
+    }
+
+    .triggerCollapsed {
+        width: 60px;
+        min-width: 0;
+        min-height: 48px;
+        box-sizing: border-box;
+        padding: 5px @spacing-half;
+        flex-direction: column;
+        gap: 2px;
+        color: @color-white;
+
+        [data-anv='icon'] {
+            width: 24px;
+            height: 24px;
+            flex-shrink: 0;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+
+        svg {
+            width: 20px;
+            height: 20px;
+        }
+    }
+
+    .collapsedLabel {
+        font-family: @base-font-family;
+        font-size: @typescale-0;
+        font-weight: @font-weight-regular;
+        line-height: 10px;
+        white-space: nowrap;
+    }
+}

package/src/components/titan-layout/navigation-catalog/navigation-catalog-trigger.module.less.d.ts

@@ -0,0 +1,9 @@
+export const __esModule: true;
+export const collapsedLabel: string;
+export const container: string;
+export const containerCollapsed: string;
+export const shortcut: string;
+export const trigger: string;
+export const triggerCollapsed: string;
+export const triggerLabel: string;
+