@servicetitan/navigation 14.2.0 → 14.4.0

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

@@ -0,0 +1,170 @@
+import { Button, Chip, Flex, Text, ThemeProvider } from '@servicetitan/anvil2';
+import IconSearch from '@servicetitan/anvil2/assets/icons/material/round/search.svg';
+import classNames from 'classnames';
+import { FC, Fragment, ReactNode, useCallback, useEffect, useRef, useState } from 'react';
+import { PinnedNavigationConfig } from '../interface';
+import { NavigationCatalog } from './navigation-catalog';
+
+import * as styles from './navigation-catalog-trigger.module.less';
+
+/**
+ * True when the keystroke should open the catalog rather than reach the focused control.
+ *
+ * The shortcut is deliberately a modifier chord: a bare key would be swallowed by, or would steal
+ * from, every text field on the page.
+ */
+const isCatalogShortcut = (event: KeyboardEvent): boolean =>
+    (event.metaKey || event.ctrlKey) && !event.altKey && event.key.toLowerCase() === 'k';
+
+/**
+ * The chord as the user's own keyboard prints it.
+ *
+ * The listener accepts either modifier on every platform, so this only decides which one to
+ * advertise. `platform` is deprecated but is still the only reliable signal here; the user agent is
+ * the fallback and a wrong guess costs nothing but a mislabelled badge.
+ */
+const shortcutLabel = (): string => {
+    const platform =
+        typeof window.navigator === 'undefined'
+            ? ''
+            : window.navigator.platform || window.navigator.userAgent;
+
+    return /Mac|iPod|iPhone|iPad/.test(platform) ? '⌘ K' : 'Ctrl K';
+};
+
+export interface NavigationCatalogTriggerProps extends PinnedNavigationConfig {
+    /** Whether the rail is expanded; the compact trigger keeps its label below the icon. */
+    expanded: boolean;
+    /** Optional sidebar action beside the expanded search trigger. */
+    trailingAction?: ReactNode;
+}
+
+/**
+ * Sidebar entry point for the navigation catalog.
+ *
+ * Presented as a labelled control rather than a bare icon: the catalog is the only route to an
+ * unpinned destination, so the affordance has to read as "search everything" at a glance. It is a
+ * button and not an input — the real field lives in the dialog and takes focus on open, and two
+ * inputs would mean typing in one and getting results in the other.
+ *
+ * The catalog is never opened automatically; an unpinned navigation is a deliberate state, and this
+ * trigger plus its shortcut are what keep the user from being stranded there.
+ */
+export const NavigationCatalogTrigger: FC<NavigationCatalogTriggerProps> = ({
+    expanded,
+    trailingAction,
+    ...catalog
+}) => {
+    const [isOpen, setIsOpen] = useState(false);
+    const triggerRef = useRef<HTMLButtonElement>(null);
+    const wasOpen = useRef(false);
+
+    const close = useCallback(() => setIsOpen(false), []);
+    const toggle = useCallback(() => setIsOpen(open => !open), []);
+
+    useEffect(() => {
+        // The dialog unmounts on close, so restore focus after its modal content is removed.
+        if (wasOpen.current && !isOpen) {
+            triggerRef.current?.focus();
+        }
+        wasOpen.current = isOpen;
+    }, [isOpen]);
+
+    useEffect(() => {
+        const handler = (event: KeyboardEvent) => {
+            if (!isCatalogShortcut(event)) {
+                return;
+            }
+
+            event.preventDefault();
+            toggle();
+        };
+
+        window.addEventListener('keydown', handler);
+        return () => window.removeEventListener('keydown', handler);
+    }, [toggle]);
+
+    /*
+     * Labelled explicitly so the name stays "Go to" whether or not the text is rendered, and so the
+     * shortcut badge never reads out as part of it.
+     */
+    const buttonProps = {
+        /*
+         * Not `navigation-item-*`: that prefix belongs to the rail's links, and this is a control
+         * that opens a dialog rather than a destination, so sharing the namespace invites a
+         * selector written for a link to match it.
+         */
+        'data-cy': 'navigation-catalog-trigger',
+        'data-pendo': 'navigation-catalog-trigger',
+        'appearance': 'secondary',
+        'size': 'small',
+        'aria-label': 'Go to',
+        'aria-haspopup': 'dialog',
+        'aria-expanded': isOpen,
+        'aria-keyshortcuts': 'Meta+K Control+K',
+        'onClick': toggle,
+    } as const;
+
+    return (
+        <Fragment>
+            <div className={classNames(styles.container, !expanded && styles.containerCollapsed)}>
+                {expanded ? (
+                    <Button
+                        {...buttonProps}
+                        ref={triggerRef}
+                        icon={{ before: IconSearch }}
+                        className={styles.trigger}
+                    >
+                        <Flex alignItems="center" justifyContent="space-between" gap={1} grow={1}>
+                            {/* The ellipsis is part of the label, matching the field in the dialog. */}
+                            <Text inline size="small" className={styles.triggerLabel}>
+                                Go to...
+                            </Text>
+                            {/* Decorative: the chord is already on the button as aria-keyshortcuts. */}
+                            <Chip
+                                label={shortcutLabel()}
+                                size="small"
+                                className={styles.shortcut}
+                            />
+                        </Flex>
+                    </Button>
+                ) : (
+                    <Button
+                        {...buttonProps}
+                        ref={triggerRef}
+                        appearance="ghost"
+                        icon={IconSearch}
+                        className={styles.triggerCollapsed}
+                    >
+                        <span className={styles.collapsedLabel}>Go to...</span>
+                    </Button>
+                )}
+                {expanded && trailingAction}
+            </div>
+            {/*
+             * Mounted only while open, so a host that resolves its catalog lazily is not asked for
+             * it on every page load, and a second navigation tree is not held inside the sidebar's
+             * subtree for a dialog nobody opened.
+             *
+             * Dark, because the catalog belongs to the rail rather than to the page. The rail paints
+             * itself dark whatever the application's mode is, and this is the rail's own menu — the
+             * same `ThemeProvider` the rail uses on its own sections.
+             *
+             * A `ThemeProvider` rather than a second `AnvilProvider`: the latter is the
+             * application-level provider, and mounting a nested one alongside the host's meant its
+             * unmount tore down state the outer one was still relying on, so closing the catalog
+             * left the rail unstyled.
+             *
+             * This only sets the mode, which is what makes the *text* tokens light. The surface is
+             * matched to the rail separately, in `navigation-catalog.module.less` — anvil2's dark is
+             * a neutral grey and the rail's is a navy, so the mode alone would leave two visibly
+             * different darks.
+             */}
+            {isOpen && (
+                <ThemeProvider mode="dark">
+                    <NavigationCatalog open onClose={close} {...catalog} />
+                </ThemeProvider>
+            )}
+        </Fragment>
+    );
+};

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

@@ -0,0 +1,379 @@
+@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) {
+    // Four readable columns fit the desktop dialog; narrower dialogs wrap whole groups.
+    @catalog-column: 15rem;
+    @catalog-gap: 1.5rem;
+    @catalog-padding: @spacing-2;
+
+    /*
+     * The rail's own background, from `@bg-color` in `@servicetitan/navigation`'s
+     * `layout-sidebar.module.less`, its hover on top of it, and the trigger chip this catalog opens
+     * from.
+     *
+     * Repeated as literals because they are LESS variables private to that package, not custom
+     * properties, so there is nothing to reference at runtime. The rail paints them unconditionally and
+     * has done since it was written, so the risk of drift is low and the failure is cosmetic.
+     *
+     * They are here because the catalog is the rail's menu and should read as part of it. anvil2's dark
+     * mode is a neutral grey (#1a1a1a) and the rail is a navy, so taking the mode alone would put two
+     * different darks side by side on screen.
+     *
+     * Translucent white rather than a mixed-down navy throughout: a translucent layer tints whatever it
+     * covers, so these keep the surface's hue and only lift it, which is what makes them read as part of
+     * the same surface rather than as patches on it.
+     */
+    @rail-surface: #0f1d26;
+    @rail-hover: rgba(255, 255, 255, 0.08);
+    @rail-field: rgba(255, 255, 255, 0.06);
+    @rail-field-border: rgba(255, 255, 255, 0.16);
+
+    /**
+     * Repaints the dialog in the rail's navy instead of anvil2's neutral dark, and lightens its
+     * backdrop instead of anvil2's default near-black scrim.
+     *
+     * `--a2-dialog-background-color`, `--a2-dialog-border-color` and `--a2-dialog-backdrop-color` are
+     * the hooks anvil2's Dialog reads inside its own `var()` chains, ahead of the tokens they otherwise
+     * fall back to. Setting those rather than `background-color`/`::backdrop` directly means no
+     * specificity contest — nothing else defines these properties, they are only read — and the
+     * background one reaches the header and content panels too, which paint from the same variable.
+     *
+     * The border goes with the background. Left alone it resolves to a flat `#404040`, which is the
+     * last neutral grey on the surface and outlines the whole dialog in it. The same translucent white
+     * the field's edge uses puts the outline back in the surface's own colour.
+     *
+     * `--a2-color-neutral-0` for the backdrop is the same override anvil2's own `fullScreen` variant
+     * uses in place of its default `neutral-900` — a supported swap, not a hack.
+     */
+    .dialog {
+        --a2-dialog-background-color: @rail-surface;
+        --a2-dialog-border-color: @rail-field-border;
+        --a2-dialog-backdrop-color: var(--a2-color-neutral-0, #ffffff);
+
+        /*
+         * Pins the dialog's size to the viewport instead of its content, so opening it, searching, and
+         * clearing the search all leave it exactly where it was.
+         *
+         * anvil2 centres the dialog by giving it `inset: 0` and `margin: auto`; overriding `top` and
+         * `height` here (with the matching margins zeroed so they cannot re-introduce the auto-centring
+         * they replace) fixes the vertical position and size, while `left`/`right` stay on the anvil2
+         * default and keep centring horizontally. `--nav-offset-top` is the rail's own top-nav height
+         * custom property, already threaded through this package for the same purpose.
+         *
+         * `> *` reaches anvil2's own content wrapper, which otherwise sizes to its content rather than
+         * to this now-fixed height — there is no class hook for it, but the dialog only ever has that
+         * one child.
+         */
+        top: calc(var(--nav-offset-top) + 10px);
+        bottom: auto;
+        height: calc(100vh - 112px);
+        margin-top: @spacing-0;
+        margin-bottom: @spacing-0;
+
+        > * {
+            height: 100%;
+            padding-bottom: @spacing-0;
+        }
+    }
+
+    /**
+     * Stacks the search above the columns.
+     *
+     * `Dialog.Content` is `display: flex` with the default row direction, so its children line up
+     * side by side. Without this the search field became a flex item next to the column block and sat
+     * in the left third of the dialog, reading as a fourth column.
+     */
+    .body {
+        container-type: inline-size;
+        display: flex;
+        flex: 1;
+        min-width: 0;
+        flex-direction: column;
+    }
+
+    /**
+     * Lets the results area, rather than the dialog's own scroller, take the overflow.
+     *
+     * `Dialog.Content` is a flex item of that scroller, and a flex item will not shrink below its
+     * content by default. Without this the scroller is the thing that overflows, which scrolls the
+     * search field off the top along with the results.
+     */
+    .content {
+        min-height: 0;
+        padding-inline: @catalog-padding;
+        padding-bottom: @spacing-0;
+    }
+
+    // Results scroll above the full-width footer; allow its content to wrap on narrow screens.
+    .footer {
+        box-sizing: border-box;
+        min-height: 56px;
+        flex: none;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: center;
+        gap: @spacing-1 @spacing-3;
+        padding: 12px @catalog-padding;
+        background-color: var(--a2-background-color-secondary);
+        text-align: center;
+    }
+
+    .footerActions {
+        display: flex;
+        flex: none;
+        gap: @spacing-1;
+    }
+
+    /*
+     * Matched to the rail's own "Go to" field, which is what the user clicked to get here — the same
+     * control, so it should not change colour on the way.
+     *
+     * anvil2's field is an opaque neutral (#1a1a1a on a #545454 border) which, like the row hover, is
+     * the right lightness but the wrong hue against the navy. The rail's translucent white gives the
+     * same lift while keeping the surface's colour, and these are its exact values.
+     */
+    .search {
+        --a2-text-field-input-wrapper-background-color: @rail-field;
+        --a2-text-field-input-wrapper-border-color-default: @rail-field-border;
+
+        width: 100%;
+        margin-bottom: 1.5rem;
+    }
+
+    /*
+     * Fills whatever the now fixed-height dialog leaves under the search field, instead of sizing to
+     * its own content, so browse, a narrowed search, and the empty state all hold the same height.
+     */
+    .results {
+        flex: 1;
+        min-height: 0;
+        // Overlay scrollbars ignore scrollbar-gutter; keep the last column's stars clear of them.
+        padding-right: @spacing-2;
+        overflow-y: auto;
+
+        /*
+         * Reserve the scrollbar's width whether or not it is showing, so a query that stops the results
+         * overflowing does not shift the columns sideways as the scrollbar disappears.
+         */
+        scrollbar-gutter: stable;
+    }
+
+    // Match the input's width; let either scrollbar style occupy the dialog's right padding.
+    .searchResults {
+        padding-right: @spacing-0;
+        margin-right: -@catalog-padding;
+        scrollbar-gutter: auto;
+
+        > div {
+            width: 100cqw;
+        }
+    }
+
+    /*
+     * Each group owns a column, regardless of its length. In particular, Projects & Field starts
+     * beside Demand rather than flowing beneath it. The minimum shrinks to the available width
+     * on small screens. Search uses a plain single-column list instead of this grid.
+     */
+    .columns {
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(min(100%, @catalog-column), 1fr));
+        gap: @catalog-gap;
+        overflow: hidden;
+    }
+
+    /*
+     * Grid items stretch to the tallest group so dividers span the row. Place each divider in the
+     * preceding gap; the grid clips the one before its first column, including after wrapping.
+     */
+    .group {
+        position: relative;
+        min-width: 0;
+
+        &::before {
+            position: absolute;
+            top: 0;
+            bottom: 0;
+            left: -(@catalog-gap / 2);
+            width: 1px;
+            background: rgba(255, 255, 255, 0.12);
+            content: '';
+        }
+    }
+
+    // Keep eyebrow medium typography and use the catalog's specified subdued colour.
+    .groupTitle {
+        --a2-text-foreground-color-subdued: @color-neutral-70;
+
+        display: block;
+        padding: @spacing-0 0.5rem;
+        margin-bottom: 0.5rem;
+    }
+
+    .module-group {
+        margin-bottom: 0.75rem;
+    }
+
+    // Match the sidebar's small, subdued headings and spacing above each page group.
+    .submenuTitle {
+        --a2-text-foreground-color-subdued: @color-neutral-70;
+
+        display: block;
+        padding: 12px @spacing-1 @spacing-half 2rem;
+        margin: @spacing-0;
+    }
+
+    .row {
+        display: flex;
+        align-items: center;
+        gap: 0.25rem;
+        border-radius: var(--a2-border-radius-medium, 4px);
+
+        // Share the highlight while keeping the link and favorite button independently focusable.
+        &:hover,
+        &:has(:focus-visible) {
+            background-color: @rail-hover;
+        }
+    }
+
+    .link {
+        display: flex;
+        flex: 1;
+        min-width: 0;
+        align-items: center;
+        gap: 0.5rem;
+        padding: 0.25rem 0.5rem;
+        border-radius: var(--a2-border-radius-medium, 4px);
+        text-decoration: none;
+
+        &:hover,
+        &:focus-visible {
+            text-decoration: none;
+        }
+    }
+
+    .moduleIcon {
+        flex: none;
+    }
+
+    /*
+     * Level 2 of three, and the anchor of the scale: full-strength foreground at the body size, which
+     * everything else is set against. The destination is the usable part of the row, so it carries the
+     * weight and the brighter colour; the category heading above it is deliberately quieter.
+     */
+    .moduleTitle {
+        flex: 1;
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        color: var(--a2-foreground-color-default, light-dark(#040404, #ffffff));
+        font-weight: var(--a2-font-weight-semibold, 600);
+        line-height: 1rem;
+    }
+
+    // As in the sidebar, page text sits 8px farther in than its group heading.
+    .childLink {
+        padding: @spacing-1 @spacing-1 @spacing-1 2.5rem;
+    }
+
+    // Match the expanded sidebar's child-page typography.
+    .childTitle {
+        flex: 1;
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        color: var(--a2-foreground-color-default, light-dark(#040404, #ffffff));
+        font-size: @typescale-2;
+        font-weight: @font-weight-semibold;
+        line-height: 20px;
+    }
+
+    /*
+     * anvil2 positions a Badge absolutely with a translate, because its usual job is to overlay the
+     * corner of an icon. Here it is a sibling in a row and has to sit in the flow, so the position
+     * and the transform are both undone — the same override the rail applies to its own submenu
+     * counters in `layout-sidebar.module.less`.
+     *
+     * No `!important` needed: anvil2 nests its rule as `.anvil2 ._badge_x`, and the enclosing
+     * `.anvil2.anvil2` scope already outranks that.
+     *
+     * `flex: none` because the title beside it takes the slack — without it a long name would
+     * squeeze the count instead of truncating itself, and a truncated count is worse than a
+     * truncated name.
+     */
+    .badge[data-anv][data-anv] {
+        position: relative;
+        transform: none;
+        flex: none;
+    }
+
+    // 2rem to match the star button's box, so both align down the column. Always visible, unlike
+    // the star, and #707070 to match the Pantheon frame.
+    .lock {
+        display: inline-flex;
+        width: 2rem;
+        height: 2rem;
+        flex: none;
+        align-items: center;
+        justify-content: center;
+        color: var(--a2-color-neutral-500, #707070);
+    }
+
+    .star {
+        flex: none;
+        opacity: 0;
+    }
+
+    // Mouse clicks retain focus after leaving the row; only keyboard focus should reveal a star.
+    .row:hover .star,
+    .row:has(:focus-visible) .star {
+        opacity: 0.5;
+
+        &:hover,
+        &:focus-visible {
+            opacity: 1;
+        }
+    }
+
+    /*
+     * After the hover rules, which match at the same specificity, so a pinned star stays lit.
+     *
+     * The token's dark value, `yellow-300`, is a pale gold that clears the surface below at 13.5:1.
+     * Note that the light value on the other side of this token is `yellow-500` (#ffbe00), which only
+     * manages 1.66:1 on white — under the 3:1 WCAG 1.4.11 asks of a graphical control. That branch is
+     * unreachable while the catalog follows the rail, but it is the thing to fix first if this surface
+     * is ever made light.
+     */
+    .starActive,
+    .row:hover .starActive,
+    .row:has(:focus-visible) .starActive {
+        color: var(--a2-status-color-warning, light-dark(#ffbe00, #ffe278));
+        opacity: 1;
+    }
+
+    /*
+     * Centred in the fixed-height results area rather than left stranded against its top edge.
+     *
+     * `border-box` so the padding is counted inside the `100%`. Under the default `content-box` the
+     * vertical padding is added to it, and the message ended up 64px taller than the area it sits in —
+     * enough to raise a scrollbar next to a single line of text.
+     */
+    .empty {
+        display: flex;
+        box-sizing: border-box;
+        height: 100%;
+        align-items: center;
+        justify-content: center;
+        padding: 2rem 0.5rem;
+        text-align: center;
+        color: var(--a2-foreground-color-subdued, light-dark(#707070, #c4c4c4));
+    }
+}

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

@@ -0,0 +1,26 @@
+export const __esModule: true;
+export const badge: string;
+export const body: string;
+export const childLink: string;
+export const childTitle: string;
+export const columns: string;
+export const content: string;
+export const dialog: string;
+export const empty: string;
+export const footer: string;
+export const footerActions: string;
+export const group: string;
+export const groupTitle: string;
+export const link: string;
+export const lock: string;
+export const moduleGroup: string;
+export const moduleIcon: string;
+export const moduleTitle: string;
+export const results: string;
+export const row: string;
+export const search: string;
+export const searchResults: string;
+export const star: string;
+export const starActive: string;
+export const submenuTitle: string;
+