@servicetitan/navigation 14.2.0 → 14.3.0

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

@@ -0,0 +1,458 @@
+import { Button, Dialog, Icon, SearchField, Text, Tooltip } from '@servicetitan/anvil2';
+import IconLock from '@servicetitan/anvil2/assets/icons/material/round/lock.svg';
+import IconStar from '@servicetitan/anvil2/assets/icons/material/round/star.svg';
+import IconStarBorder from '@servicetitan/anvil2/assets/icons/material/round/star_border.svg';
+import classNames from 'classnames';
+import { FC, Fragment, MouseEvent, useMemo, useRef, useState } from 'react';
+import { NavigationItemData } from '../../../utils/navigation';
+import { getCounterTag } from '../../../utils/side-nav';
+import { BadgeTag } from '../../badge-tag';
+import { NavigationCatalogGroup, PinnedNavigationConfig } from '../interface';
+import { useTitanLayoutContext } from '../layout-context';
+import { NavigationCatalogFooter } from './navigation-catalog-footer';
+import * as styles from './navigation-catalog.module.less';
+
+/** The pages beneath an item, flattened out of its submenu groups. */
+const childrenOf = (item: NavigationItemData) => {
+    const seen = new Set<string>();
+
+    return (item.submenu?.groups ?? []).flatMap(group =>
+        (group.links ?? []).filter(link => {
+            if (seen.has(link.id)) {
+                return false;
+            }
+
+            seen.add(link.id);
+            return true;
+        })
+    );
+};
+
+/** Shown in place of the pin control for a destination the user may not unpin. */
+const LockedPin: FC = () => (
+    <Tooltip>
+        <Tooltip.Trigger>
+            <Icon svg={IconLock} className={styles.lock} />
+        </Tooltip.Trigger>
+        <Tooltip.Content>Cannot be removed from Favorites</Tooltip.Content>
+    </Tooltip>
+);
+
+interface PinToggleProps {
+    pinned: boolean;
+    label: string;
+    onToggle: () => void;
+}
+
+const PinToggle: FC<PinToggleProps> = ({ pinned, label, onToggle }) => {
+    const toggle = (event: MouseEvent) => {
+        // The control sits inside the row but is not a navigation affordance.
+        event.preventDefault();
+        event.stopPropagation();
+        onToggle();
+    };
+
+    return (
+        <Tooltip delay={300}>
+            <Tooltip.Trigger>
+                <Button
+                    appearance="ghost"
+                    size="small"
+                    icon={pinned ? IconStar : IconStarBorder}
+                    // Only a control that covers nothing but pinned rows is lit.
+                    className={classNames(styles.star, pinned && styles.starActive)}
+                    aria-label={label}
+                    aria-pressed={pinned}
+                    onClick={toggle}
+                />
+            </Tooltip.Trigger>
+            <Tooltip.Content>
+                {pinned ? 'Remove from Favorites' : 'Add to Favorites'}
+            </Tooltip.Content>
+        </Tooltip>
+    );
+};
+
+interface CatalogRowsProps {
+    item: NavigationItemData;
+    /**
+     * Every id the module's own control covers, taken from the unfiltered item.
+     *
+     * `item` may have been narrowed by the search, so deriving this from it would let the control
+     * act on only the pages that happen to be visible — silently stranding the rest.
+     */
+    scopeIds: string[];
+    isPinned: (id: string) => boolean;
+    isLocked: (id: string) => boolean;
+    /** `ownerId` is the module the page belongs to; omitted for the module's own row. */
+    onTogglePin: (id: string, ownerId?: string) => void;
+    onToggleAll: (ids: string[], shouldPin: boolean) => void;
+    onNavigate: () => void;
+}
+
+const CatalogRows: FC<CatalogRowsProps> = ({
+    item,
+    scopeIds,
+    isPinned,
+    isLocked,
+    onTogglePin,
+    onToggleAll,
+    onNavigate,
+}) => {
+    const { NavigationComponent } = useTitanLayoutContext();
+    const children = childrenOf(item);
+
+    /*
+     * Minus anything locked — locked destinations are always present, so the module's control
+     * neither reports on them nor acts on them.
+     */
+    const everything = scopeIds.filter(id => !isLocked(id));
+    const anyPinned = everything.some(isPinned);
+    const tag = getCounterTag(item.counter, item.tag);
+
+    return (
+        <div className={styles.moduleGroup}>
+            <div className={styles.row}>
+                <NavigationComponent
+                    to={item.to}
+                    className={styles.link}
+                    onClick={onNavigate}
+                    aria-label={item.title}
+                >
+                    {item.icon && (
+                        <Icon svg={item.icon} size="small" className={styles.moduleIcon} />
+                    )}
+                    <Text inline className={styles.moduleTitle}>
+                        {item.title}
+                    </Text>
+                    {/*
+                     * The same counter the rail shows, so a destination that is asking for
+                     * attention still says so here — the catalog is the only place an unfavourited
+                     * one is visible at all.
+                     */}
+                    {!!tag && <BadgeTag data={tag} className={styles.badge} />}
+                </NavigationComponent>
+                {/*
+                 * One control for the whole module: favouriting it takes its pages with it, and
+                 * unfavouriting it takes them away again.
+                 *
+                 * Lit when *any* page under it is favourited, because that is exactly when the
+                 * module is on the rail — the star reports whether the module is there, not
+                 * whether every page under it is. Reporting "all" instead would leave an unlit
+                 * star on a module the user can plainly see in the navigation.
+                 */}
+                {isLocked(item.id) ? (
+                    <LockedPin />
+                ) : (
+                    <PinToggle
+                        pinned={anyPinned}
+                        label={
+                            anyPinned
+                                ? `Unpin ${item.title} from the navigation`
+                                : `Pin ${item.title} to the navigation`
+                        }
+                        onToggle={() => onToggleAll(everything, !anyPinned)}
+                    />
+                )}
+            </div>
+            {children.map(child => {
+                /*
+                 * Page titles are only unique within their item — "Settings" and "Reports" recur
+                 * across the catalog — and the row that tells them apart is a separate element, so
+                 * it is not part of any of these names. Anything reading the rows on their own, a
+                 * screen reader running through the links or a voice command naming one, would
+                 * otherwise be given the same name several times.
+                 */
+                const qualifiedTitle = `${item.title}: ${child.title}`;
+                const childPinned = isPinned(child.id);
+                const childTag = getCounterTag(child.counter, child.tag);
+
+                return (
+                    <div key={child.id} className={styles.row}>
+                        <NavigationComponent
+                            to={child.to}
+                            className={classNames(styles.link, styles.childLink)}
+                            onClick={onNavigate}
+                            aria-label={qualifiedTitle}
+                        >
+                            <Text inline className={styles.childTitle}>
+                                {child.title}
+                            </Text>
+                            {!!childTag && <BadgeTag data={childTag} className={styles.badge} />}
+                        </NavigationComponent>
+                        {isLocked(child.id) ? (
+                            <LockedPin />
+                        ) : (
+                            <PinToggle
+                                pinned={childPinned}
+                                label={
+                                    childPinned
+                                        ? `Unpin ${qualifiedTitle} from the navigation`
+                                        : `Pin ${qualifiedTitle} to the navigation`
+                                }
+                                onToggle={() => onTogglePin(child.id, item.id)}
+                            />
+                        )}
+                    </div>
+                );
+            })}
+        </div>
+    );
+};
+
+/**
+ * Narrows the catalog to the entries matching `query`.
+ *
+ * Matching is literal and never cascades: a row survives only when its own title matches. An item
+ * whose title matches is kept as a bare row without the pages beneath it, and a section is kept
+ * only for whatever survived under it, so the list only ever shrinks as the query grows.
+ */
+const filterGroups = (groups: NavigationCatalogGroup[], query: string) => {
+    const needle = query.trim().toLowerCase();
+
+    if (!needle) {
+        return groups;
+    }
+
+    return groups.reduce<NavigationCatalogGroup[]>((out, group) => {
+        const items = group.items.reduce<NavigationItemData[]>((kept, item) => {
+            const matchingChildren = childrenOf(item).filter(child =>
+                child.title.toLowerCase().includes(needle)
+            );
+
+            if (matchingChildren.length > 0) {
+                kept.push({
+                    ...item,
+                    submenu: { groups: [{ title: '', links: matchingChildren }] },
+                });
+            } else if (item.title.toLowerCase().includes(needle)) {
+                kept.push({ ...item, submenu: undefined });
+            }
+
+            return kept;
+        }, []);
+
+        if (items.length > 0) {
+            out.push({ ...group, items });
+        }
+
+        return out;
+    }, []);
+};
+
+export interface NavigationCatalogProps extends PinnedNavigationConfig {
+    open: boolean;
+    onClose: () => void;
+}
+
+/**
+ * Every destination the host offers, grouped into sections, with a star on every row.
+ *
+ * The catalog shows what it is given and nothing more — the host has already resolved what this
+ * user may reach, so the catalog cannot offer a destination they do not have.
+ */
+export const NavigationCatalog: FC<NavigationCatalogProps> = ({
+    open,
+    onClose,
+    groups,
+    pinnedIds,
+    lockedIds,
+    onPinnedIdsChange,
+    onResetToDefaults,
+}) => {
+    const [query, setQuery] = useState('');
+    const searchRef = useRef<HTMLInputElement>(null);
+
+    /*
+     * Resolved here rather than by the host, so a catalog that costs requests to enumerate is paid
+     * for on opening the dialog and not on every page load. This component is mounted only while
+     * open, so the call happens once per open unless the host changes the function.
+     */
+    const resolvedGroups = useMemo(() => groups(), [groups]);
+
+    const visibleGroups = useMemo(
+        () => filterGroups(resolvedGroups, query),
+        [resolvedGroups, query]
+    );
+
+    /*
+     * The pin scope of every item, keyed by id and built before the search narrows anything, so a
+     * module's control still covers the pages a query is currently hiding.
+     */
+    const scopeById = useMemo(
+        () =>
+            new Map(
+                resolvedGroups
+                    .flatMap(group => group.items)
+                    .map(item => [item.id, [item.id, ...childrenOf(item).map(child => child.id)]])
+            ),
+        [resolvedGroups]
+    );
+    const pinnedSet = useMemo(() => new Set(pinnedIds), [pinnedIds]);
+    const lockedSet = useMemo(() => new Set(lockedIds ?? []), [lockedIds]);
+
+    const isPinned = (id: string) => pinnedSet.has(id);
+    const isLocked = (id: string) => lockedSet.has(id);
+
+    /**
+     * Favourites or unfavourites one row, carrying its module with it.
+     *
+     * A page is reached through its module, so the two travel together: favouriting a page brings
+     * the module along when it is not already there, and unfavouriting the last one takes the
+     * module with it. Leaving the module behind on its own would not read as an emptier
+     * navigation — it would put the module back carrying every page it has.
+     *
+     * Locked ids never reach a proposal. The controls that would move them are not rendered, so
+     * that part is belt and braces — but the host's list is the thing that gets persisted, and a
+     * locked destination has no business appearing in or disappearing from it.
+     */
+    const togglePin = (id: string, ownerId?: string) => {
+        if (lockedSet.has(id)) {
+            return;
+        }
+
+        /** The module, when it is a separate row that this page can legitimately move. */
+        const owner = ownerId !== id && ownerId && !lockedSet.has(ownerId) ? ownerId : undefined;
+
+        if (pinnedSet.has(id)) {
+            const removing = new Set([id]);
+
+            if (owner) {
+                const siblings = (scopeById.get(owner) ?? []).filter(
+                    scoped => scoped !== owner && scoped !== id
+                );
+
+                if (!siblings.some(sibling => pinnedSet.has(sibling))) {
+                    removing.add(owner);
+                }
+            }
+
+            onPinnedIdsChange(pinnedIds.filter(pinned => !removing.has(pinned)));
+            return;
+        }
+
+        // Module first, so it reads ahead of its own page in the saved order.
+        const additions = owner && !pinnedSet.has(owner) ? [owner, id] : [id];
+
+        onPinnedIdsChange([...pinnedIds, ...additions]);
+    };
+
+    /*
+     * One proposal for the whole set rather than one per row, so a host that persists on every
+     * change writes once, and every intermediate list — states the user never asked for — never
+     * exists.
+     */
+    const toggleAll = (ids: string[], shouldPin: boolean) => {
+        const actionable = ids.filter(id => !lockedSet.has(id));
+
+        if (!shouldPin) {
+            const removing = new Set(actionable);
+
+            onPinnedIdsChange(pinnedIds.filter(pinned => !removing.has(pinned)));
+            return;
+        }
+
+        const additions = actionable.filter(id => !pinnedSet.has(id));
+
+        if (additions.length > 0) {
+            onPinnedIdsChange([...pinnedIds, ...additions]);
+        }
+    };
+
+    const close = () => {
+        setQuery('');
+        onClose();
+    };
+
+    return (
+        <Dialog
+            open={open}
+            onClose={close}
+            size="xlarge"
+            aria-label="All Navigation"
+            className={styles.dialog}
+            data-cy="navigation-catalog-dialog"
+        >
+            <Dialog.Content className={styles.content}>
+                <div className={styles.body}>
+                    <SearchField
+                        ref={searchRef}
+                        size="small"
+                        className={styles.search}
+                        placeholder="Go to ..."
+                        value={query}
+                        onChange={event => setQuery(event.target.value)}
+                        onClear={() => setQuery('')}
+                        aria-label="Go to"
+                    />
+                    <div className={styles.results}>
+                        {visibleGroups.length === 0 ? (
+                            <div className={styles.empty}>
+                                {/*
+                                 * Two different nothings: a search that matched no row, and a host
+                                 * that offered no rows at all. The second is a real state — the
+                                 * catalog is reachable whether or not there is anything in it — and
+                                 * quoting an empty query at the user does not describe it.
+                                 */}
+                                <Text subdued>
+                                    {query.trim() ? (
+                                        <Fragment>
+                                            No navigation items match &ldquo;{query}&rdquo;.
+                                        </Fragment>
+                                    ) : (
+                                        'There are no navigation items to show.'
+                                    )}
+                                </Text>
+                            </div>
+                        ) : (
+                            <div className={styles.columns}>
+                                {visibleGroups.map(group => (
+                                    <div key={group.title} className={styles.group}>
+                                        {/*
+                                         * `medium` is 0.75rem, a step below the destinations under
+                                         * it. A heading that matches or beats its contents in size
+                                         * competes with them, and this one does not need the room:
+                                         * it is already set apart by case, tracking and a grey that
+                                         * nothing else on the surface uses. `small` is 0.625rem,
+                                         * too small to take in at a glance once uppercased and
+                                         * letter-spaced.
+                                         */}
+                                        <Text
+                                            variant="eyebrow"
+                                            size="medium"
+                                            className={styles.groupTitle}
+                                        >
+                                            {group.title}
+                                        </Text>
+                                        {group.items.map(item => (
+                                            <CatalogRows
+                                                key={item.id}
+                                                item={item}
+                                                scopeIds={scopeById.get(item.id) ?? [item.id]}
+                                                isPinned={isPinned}
+                                                isLocked={isLocked}
+                                                onTogglePin={togglePin}
+                                                onToggleAll={toggleAll}
+                                                onNavigate={close}
+                                            />
+                                        ))}
+                                    </div>
+                                ))}
+                            </div>
+                        )}
+                    </div>
+                </div>
+            </Dialog.Content>
+            <NavigationCatalogFooter
+                onRestore={
+                    onResetToDefaults &&
+                    (() => {
+                        onResetToDefaults();
+                        // The control disappears with the host's reset; keep focus in the dialog.
+                        searchRef.current?.focus();
+                    })
+                }
+            />
+        </Dialog>
+    );
+};

package/src/components/titan-layout/navigation-scroll-indicators.tsx

@@ -0,0 +1,80 @@
+import { Button } from '@servicetitan/anvil2';
+import SvgArrowDown from '@servicetitan/anvil2/assets/icons/material/round/arrow_downward.svg';
+import SvgArrowUp from '@servicetitan/anvil2/assets/icons/material/round/arrow_upward.svg';
+import classNames from 'classnames';
+import { Fragment, RefObject } from 'react';
+import * as Styles from './layout-sidebar.module.less';
+
+export function NavigationScrollIndicators({
+    expanded,
+    above,
+    below,
+    hasContentAbove,
+    hasContentBelow,
+    aboveIndicatorRef,
+    belowIndicatorRef,
+    onReveal,
+}: {
+    expanded: boolean;
+    above: number;
+    below: number;
+    hasContentAbove: boolean;
+    hasContentBelow: boolean;
+    aboveIndicatorRef: RefObject<HTMLDivElement>;
+    belowIndicatorRef: RefObject<HTMLDivElement>;
+    onReveal(direction: 'above' | 'below'): void;
+}) {
+    return (
+        <Fragment>
+            {(['above', 'below'] as const).map(direction => {
+                const isAbove = direction === 'above';
+                const count = isAbove ? above : below;
+                const hasContent = isAbove ? hasContentAbove : hasContentBelow;
+                const label = `${count} ${count === 1 ? 'notification' : 'notifications'}`;
+                return (
+                    <Fragment key={direction}>
+                        {/*
+                         * Its own element rather than the pill's background: the pill's height
+                         * insets the rail's counted area, and this gradient hides nothing, so it
+                         * must not. See `useNavigationScroll`.
+                         */}
+                        {hasContent && (
+                            <div
+                                className={classNames(
+                                    Styles.scrollShadow,
+                                    isAbove ? Styles.scrollShadowAbove : Styles.scrollShadowBelow
+                                )}
+                            />
+                        )}
+                        {count > 0 && (
+                            <div
+                                ref={isAbove ? aboveIndicatorRef : belowIndicatorRef}
+                                className={classNames(
+                                    Styles.scrollIndicator,
+                                    isAbove
+                                        ? Styles.scrollIndicatorAbove
+                                        : Styles.scrollIndicatorBelow
+                                )}
+                            >
+                                <Button
+                                    appearance="secondary"
+                                    size="xsmall"
+                                    icon={{ before: isAbove ? SvgArrowUp : SvgArrowDown }}
+                                    className={Styles.notificationButton}
+                                    data-cy={`navigation-notifications-${direction}`}
+                                    aria-label={`${label} ${direction}. Show nearest notification`}
+                                    onClick={event => {
+                                        event.stopPropagation();
+                                        onReveal(direction);
+                                    }}
+                                >
+                                    {expanded ? label : count >= 100 ? '99+' : count}
+                                </Button>
+                            </div>
+                        )}
+                    </Fragment>
+                );
+            })}
+        </Fragment>
+    );
+}

package/src/components/titan-layout/titan-layout.module.less

@@ -82,7 +82,8 @@
     }
 
     &.layout-desktop.layout-nav-wide {
-        --nav-offset-left: 212px;
+        // Figma 042. Pantheon: the expanded rail is 220 wide (a 204 row column inset 8 each side).
+        --nav-offset-left: 220px;
     }
 
     .top {