@servicetitan/navigation 14.2.0 → 14.3.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,436 @@
+@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) {
+    /*
+     * The catalog's column geometry.
+     *
+     * `@catalog-column` is the *minimum* a column may be, not its width — the columns share out the
+     * dialog evenly and end up wider than this. Its job is to set how many there are: at `xlarge`
+     * (70rem) four of these plus their gaps fit and a fifth does not. The columns land at 248px, which
+     * still clears the widest row the catalog renders (229px including its star), so nothing clips.
+     *
+     * Width rather than `column-count: 4`, so a dialog narrowed by a small viewport drops to three
+     * columns and then two instead of squeezing four ever thinner. A fixed count gave 208px per column
+     * at a 768px viewport, under that 229px, which turned the longest labels into ellipses —
+     * "Batch/Export Transactions" and "Recurring Service Events" among them.
+     */
+    @catalog-column: 15rem;
+    @catalog-gap: 1.5rem;
+
+    // The dialog's own horizontal inset, shared by the search field's row and the footer.
+    @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%;
+        }
+    }
+
+    /**
+     * 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 {
+        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;
+    }
+
+    // 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.
+     *
+     * `.columns` stays at `height: auto` regardless — a multi-column box given a fixed height becomes a
+     * fragmentainer and spills overflow sideways into further columns instead of growing downwards, which
+     * is a horizontal scrollbar rather than the vertical one wanted here.
+     */
+    .results {
+        flex: 1;
+        min-height: 0;
+        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;
+    }
+
+    /**
+     * Column width rather than column count, so a narrow dialog drops a column instead of squeezing all
+     * three.
+     *
+     * The dialog tracks the viewport below its cap, so `column-count: 3` had to divide whatever it was
+     * given by three. At a 768px viewport that was 208px per column, narrower than the 229px the widest
+     * category wants, and `max-width: 100%` on the category turned the overflow into ellipses — "Batch/
+     * Export Transactions" and "Recurring Service Events" among them.
+     *
+     * Giving the width instead lets the count fall out of it: three columns at the cap, then two, then
+     * one, and never a clipped label at any width. It cannot reach four, because a fourth column and its
+     * gap need more room than the cap ever offers, which is what keeps the reference's three-column
+     * layout at every desktop size.
+     *
+     * Multi-column rather than grid so categories pack against one another and flow into the next column,
+     * instead of leaving a ragged row of half-empty grid cells whenever one category is much taller than
+     * its neighbours.
+     */
+
+    /*
+     * `column-rule` rather than a border on the categories, because the line belongs to the boundary
+     * between columns and not to any category. Multi-column draws it once per gap, only where a gap
+     * exists, and at the full height of the column block — so it disappears on its own when the dialog
+     * narrows to a single column, and a short last column still gets the full-height line to its left
+     * rather than one that stops where its content does.
+     *
+     * A translucent white rather than the `subdued` border token, for the same reason as the row hover:
+     * the token is a flat neutral grey, and a grey line on a navy surface reads as a slightly dirty
+     * seam. At 12% it lands about where the token's grey would in lightness, but tinted by the navy
+     * underneath it, so it belongs to the surface it divides.
+     */
+    .columns {
+        columns: @catalog-column;
+        column-gap: @catalog-gap;
+        column-rule: 1px solid rgba(255, 255, 255, 0.12);
+    }
+
+    /*
+     * A category and its heading stay in the same column.
+     *
+     * Without this a tall category flowed across a column boundary and its remainder arrived at the top
+     * of the next column with no heading over it, reading as though those destinations belonged to
+     * whatever was above them. `break-after` on the heading only keeps the heading with its first row;
+     * it says nothing about the rest.
+     *
+     * This is a preference, not a guarantee: a category taller than the column still has to break
+     * somewhere, and the browser will split it rather than overflow. That degrades to today's behaviour
+     * for the one or two largest categories and fixes it for the rest.
+     */
+
+    /*
+     * Full column width, so every star in the catalog lands on the column's right edge just inside the
+     * divider. The rows are flex containers with `flex: 1` on the link, so the star is pushed to
+     * whatever the category's right edge is; letting that edge be the column's puts all of them on one
+     * line down the whole column rather than one line per category.
+     */
+    .group {
+        break-inside: avoid;
+        margin-bottom: 1.5rem;
+    }
+
+    /*
+     * Level 1 of three. It shares its size with the module rows below it and is told apart by case,
+     * tracking and colour rather than by being bigger or smaller — the standard eyebrow treatment, and
+     * the one place a plain grey belongs.
+     *
+     * `break-after` keeps a heading from being stranded at the foot of a column.
+     *
+     * The colour is spelled out rather than taken from `--a2-foreground-color-subdued`, which resolves
+     * to `#c4c4c4` in dark mode: close enough to white that the heading competed with the destinations
+     * under it. This is `--a2-color-neutral-400`, a genuine mid grey, and it is the same value the rail
+     * headings use.
+     *
+     * Note that anvil2's colour tokens are spelled `foreground`, not `text`; a `--a2-text-color-*` name
+     * resolves to nothing and drops silently to the fallback. That matters here because this
+     * repository's LESS `@color-neutral` ramp runs dark-to-light, opposite to anvil2's, so a wrong
+     * guess lands on near-black text against a near-black dialog.
+     */
+    .groupTitle {
+        display: block;
+        break-after: avoid;
+        padding: @spacing-0 0.5rem;
+        margin-bottom: 0.5rem;
+        color: light-dark(
+            var(--a2-color-neutral-500, #707070),
+            var(--a2-color-neutral-400, #8b8b8b)
+        );
+        text-transform: uppercase;
+        letter-spacing: 0.06em;
+    }
+
+    /* A module and its pages are one unit and stay in the same column. */
+    .module-group {
+        break-inside: avoid;
+        margin-bottom: 0.75rem;
+    }
+
+    .row {
+        display: flex;
+        align-items: center;
+        gap: 0.25rem;
+    }
+
+    .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;
+
+        /*
+         * The rail's hover, not anvil2's. The token resolves to a flat neutral grey in dark mode, which
+         * on this navy replaces the surface's hue instead of lifting it. A translucent white tints
+         * whatever it covers, so the hovered row stays the same colour, just brighter — and it is the
+         * same value the rail uses on its own rows, which is what the user is comparing it against.
+         */
+        &:hover,
+        &:focus-visible {
+            background-color: @rail-hover;
+            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);
+    }
+
+    /* Indented to sit under the module's title rather than its icon. */
+    .childLink {
+        padding-left: 2rem;
+    }
+
+    /*
+     * Level 3 of three: below the module row, above the category heading, at regular weight and at the
+     * same full-strength foreground. It is still a destination, so it is not dimmed — size and weight
+     * are what place it under its module. Only the category heading is greyed.
+     *
+     * 13px is deliberately off the token scale, which jumps 0.75rem → 0.875rem with nothing in between.
+     * At 0.75rem this tied with the category heading and read as another label rather than as somewhere
+     * to go. It has to clear the heading and stay under the module row, and the gap between those two is
+     * one token wide, so the size is spelled out. It matches the rail's pinned pages, which are sized
+     * the same way and for the same reason.
+     */
+    .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: 0.8125rem;
+    }
+
+    /*
+     * 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;
+
+        &:focus-visible {
+            opacity: 1;
+        }
+    }
+
+    .row:hover .star {
+        opacity: 0.5;
+
+        &:hover {
+            opacity: 1;
+        }
+    }
+
+    .row:focus-within .star {
+        opacity: 0.5;
+    }
+
+    /*
+     * 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:focus-within .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,24 @@
+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 star: string;
+export const starActive: string;
+