@deriv-com/dds-marketing 0.1.0 → 1.0.0

package/dist/components/core/navbar/Navbar.d.ts

@@ -0,0 +1,52 @@
+import { type ReactNode } from 'react';
+import './Navbar.css';
+import './navbar-impl.css';
+import './navbar-material.css';
+import { type NavbarProps } from './Navbar.types.js';
+export type { NavbarProps };
+/**
+ * Whether the bar is gathered, given what it was and how far the page has moved.
+ *
+ * Lifted out of the listener and exported because it is the one part of the scroll behaviour that
+ * can be checked without a browser: jsdom has no scrolling, no layout and no pointer, so the hook
+ * around this can only be run, not observed. The rule it encodes — that the two thresholds differ,
+ * and which way round — is exactly the part that was wrong before and would be wrong again quietly.
+ */
+export declare function gathered(was: boolean, offset: number): boolean;
+/**
+ * A slot's contents as one flat list, with every fragment opened.
+ *
+ * A page hands a pair of actions over as `<>…</>` and a list of switchers the same way, and
+ * `Children.map` does not look inside a fragment — so a fragment reached anything that matched on
+ * type, NavbarPanel's switcher-to-row swap included, as one opaque element. Opened here, once,
+ * each control is a child of its own wherever the slot is drawn.
+ *
+ * Every element comes out with a key unique across the whole list. `Children.toArray` keys each
+ * level from `.0` again, so the children of two fragments side by side would share keys and React
+ * could hand one control's state — an open switcher, say — to another. Each key is prefixed with
+ * the path of fragments it came through, the way React keys nested arrays itself.
+ */
+export declare function flattened(node: ReactNode, path?: string): ReactNode[];
+/**
+ * The bar across the top of a marketing page: the mark, the places the site has,
+ * and the things a reader reaches for rather than navigates to.
+ *
+ * It holds no destinations of its own — what goes in it is what the page
+ * composes. What this owns is the bar, and running out of room is the whole of
+ * its behaviour: below the width its three regions fit in, the destinations and
+ * the utilities stop being drawn and the trigger takes their place.
+ *
+ * Which section is open is the bar's, not each menu's. A menu cannot see its
+ * neighbours, so left to themselves two of them open at once and two surfaces
+ * overlap in front of the page. Injected the way TabList injects `selected`, and
+ * for the same reason.
+ *
+ * The rail paints nothing and the row inside it is the container a reader sees.
+ * That split is why there is no line under the bar: what separates it from the
+ * page is a surface of its own with air around it.
+ *
+ * No `role="banner"`. A `<header>` outside a sectioning element already is that
+ * landmark, and writing it as well says so a second time in a way that goes stale
+ * if the element is ever nested.
+ */
+export declare function Navbar({ tone, label, menuLabel, closeLabel, brand, utilities, compactAction, preferences, showThemeToggle, theme, onThemeChange, themeToggleLabel, menuOpen, onMenuOpenChange, children, ...rest }: NavbarProps): import("react").JSX.Element;

package/dist/components/core/navbar/Navbar.js

@@ -0,0 +1,498 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, Children, Fragment, cloneElement, isValidElement, useCallback, useEffect, useRef, useState, } from 'react';
+import { BarsRegularIcon, MoonRegularIcon, SunBrightRegularIcon, XmarkRegularIcon, } from '@deriv-com/quill-icons-web';
+import './Navbar.css';
+import './navbar-impl.css';
+import './navbar-material.css';
+import { Button } from '../button/Button.js';
+import { buttonDefaults } from '../button/Button.types.js';
+import { ButtonIcon } from '../button-icon/ButtonIcon.js';
+import { milliseconds } from '../../css-time.js';
+import { DropdownMenu } from '../dropdown-menu/DropdownMenu.js';
+import { Icon } from '../icon/Icon.js';
+import { NavbarItem } from '../navbar-item/NavbarItem.js';
+import { NavbarMenu } from '../navbar-menu/NavbarMenu.js';
+import { NavbarPanel } from '../navbar-panel/NavbarPanel.js';
+import { NavbarSwitcher } from '../navbar-switcher/NavbarSwitcher.js';
+import { navbarDefaults, navbarParts } from './Navbar.types.js';
+/**
+ * Both handlers, the menu's own first.
+ *
+ * `cloneElement` replaces rather than merges, so a menu already reporting its own
+ * state would silently stop — and that is the handler a page is most likely to
+ * have written, since it is how they learn which section was opened.
+ */
+function chain(theirs, ours) {
+    if (theirs === undefined)
+        return ours;
+    return (open) => {
+        theirs(open);
+        ours(open);
+    };
+}
+/**
+ * Whether anything beneath the bar has been scrolled.
+ *
+ * The window is the usual answer and not the only one: a bar inside a box with
+ * its own `overflow` — a preview stage, a split layout, an embedded view —
+ * travels with that box, and the window beneath it never moves at all. So the
+ * question is asked of every ancestor rather than of one guessed node.
+ *
+ * Listened for in the capture phase on the document, because a scroll event
+ * does not bubble: a listener on the window hears the window and nothing else,
+ * which is precisely the case that was already broken.
+ *
+ * Absent outside a browser rather than fatal. The bar renders at rest on a
+ * server and in jsdom, which is where the generated behaviour test runs it, and
+ * at rest is the correct first frame either way.
+ */
+/** How far the page travels before the bar gathers, and how far back before it lets go. */
+const CONDENSE_AT = 32;
+const RESTORE_AT = 0;
+/**
+ * Whether the bar is gathered, given what it was and how far the page has moved.
+ *
+ * Lifted out of the listener and exported because it is the one part of the scroll behaviour that
+ * can be checked without a browser: jsdom has no scrolling, no layout and no pointer, so the hook
+ * around this can only be run, not observed. The rule it encodes — that the two thresholds differ,
+ * and which way round — is exactly the part that was wrong before and would be wrong again quietly.
+ */
+export function gathered(was, offset) {
+    return was ? offset > RESTORE_AT : offset > CONDENSE_AT;
+}
+function useScrolled(root) {
+    const [scrolled, setScrolled] = useState(false);
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const read = () => {
+            let offset = window.scrollY;
+            for (let node = root.current?.parentElement ?? null; node !== null; node = node.parentElement) {
+                offset = Math.max(offset, node.scrollTop);
+            }
+            /*
+              Two thresholds, not one. A single boundary at nought meant one pixel of
+              travel rearranged the whole bar — and a trackpad resting against the top
+              of a page, or a rubber-band easing back, crosses that boundary repeatedly
+              in both directions: the bar flickered between its two arrangements while
+              the reader was not scrolling at all.
+      
+              Gathering needs a deliberate scroll; returning needs the top of the page.
+              The gap between the two is what makes the state sticky in the ordinary
+              sense of the word — once it changes, small movements cannot change it
+              back.
+            */
+            setScrolled((was) => gathered(was, offset));
+        };
+        // Once before listening. A reader arriving at an anchor deep in the page, or
+        // returning to one the browser has restored the scroll position of, is
+        // already past the top and never fires a scroll event to say so.
+        read();
+        // Passive: this only reads, and saying so lets the browser scroll without
+        // waiting to find out whether the handler means to cancel it.
+        document.addEventListener('scroll', read, { capture: true, passive: true });
+        return () => document.removeEventListener('scroll', read, { capture: true });
+    }, [root]);
+    return scrolled;
+}
+/**
+ * A box that comes and goes, by collapsing in place rather than leaving.
+ *
+ * The bar holds two copies of the mark and two of the actions — one pair at the row's ends, one
+ * pair inside the pill — and exactly one of each is showing. What makes the change between them
+ * smooth is not how the copies are hidden but that they are hidden *in the flow*: a box whose width
+ * travels to nothing takes the row with it, so the pill grows into the space as it is given up and
+ * the destinations slide along on their own. Nothing has to be measured afterwards and moved back.
+ *
+ * Everything this replaces was a workaround for having prevented that. Taking the copies out of the
+ * flow stopped the row reflowing, so the pill's growth had to be faked by drawing its shape in, and
+ * the words inside it had to be caught mid-jump and played backwards. Three mechanisms, each with
+ * its own bugs, standing in for the one the layout does by itself.
+ *
+ * The width has to be measured because CSS cannot travel between a length and `auto`, and the
+ * steady states are `0` and whatever the contents come to. The layout effect runs after React has
+ * written the change and before the browser paints it, so the element is already at its new size:
+ * expanding, that is the size to arrive at; collapsing, the size to leave from is the one held from
+ * last time.
+ *
+ * The gap goes with it. A flex container puts its gap either side of every item including one that
+ * is nought wide, so a collapsed copy would leave the space it used to occupy — the pill would sit
+ * a gap wider than its contents at rest. The margin against that gap travels to minus it, on the
+ * side the gap is on, which is the end the box is at.
+ *
+ * `overflow: hidden` only while it runs. Permanently, it would clip a focus ring on the button
+ * inside; for the four hundred milliseconds the box is narrower than what it holds, it is the
+ * difference between contents that are revealed and contents that spill.
+ */
+function useCollapse(element, collapsed, gapSide) {
+    const width = useRef(null);
+    const inset = useRef(null);
+    const settled = useRef(false);
+    const latest = useRef(null);
+    useLayoutEffect(() => {
+        const node = element.current;
+        if (node === null)
+            return;
+        const measured = node.getBoundingClientRect().width;
+        const previous = width.current;
+        const held = inset.current;
+        if (!collapsed) {
+            width.current = measured;
+            // Read while it is showing: collapsed, the stylesheet has already taken it to nothing, and a
+            // keyframe built from that would travel from nothing to nothing.
+            const shown = getComputedStyle(node);
+            inset.current = `${shown.paddingInlineStart} ${shown.paddingInlineEnd}`;
+        }
+        /*
+          The first pass is the page arriving, not the bar changing. Without this the copies that are
+          showing on load would travel in from nothing, which is an entrance nobody asked for and a
+          flash on every render.
+        */
+        const first = !settled.current;
+        settled.current = true;
+        if (first)
+            return;
+        /*
+          And a width to leave from is only needed when leaving. Expanding, the size to arrive at is the
+          one just measured — the element is already at it, because CSS has stopped collapsing it and
+          the browser has not painted yet.
+    
+          That distinction is the whole of a glitch that showed once per page. The pill's pair is
+          collapsed when the bar first renders, so nothing measured it, so the guard that waits for a
+          previous width caught them on the first gather and they appeared in one frame while the row's
+          pair collapsed smoothly beside them. Only once, and only ever on the way out.
+        */
+        if (collapsed && previous === null)
+            return;
+        /*
+          Absent outside a browser that draws: jsdom implements neither, and the generated tests render
+          this component. Asking for the feature rather than for an environment.
+        */
+        if (typeof window === 'undefined')
+            return;
+        if (typeof window.matchMedia !== 'function')
+            return;
+        if (typeof node.animate !== 'function')
+            return;
+        if (window.matchMedia('(prefers-reduced-motion: reduce)').matches)
+            return;
+        const style = getComputedStyle(node);
+        const duration = milliseconds(style.getPropertyValue('--motion-duration-shift')) ?? 400;
+        const easing = style.getPropertyValue('--motion-easing-shift').trim() || 'ease';
+        const gap = style.getPropertyValue('--space-gap-md').trim() || '0';
+        const margin = gapSide === 'start' ? 'marginInlineStart' : 'marginInlineEnd';
+        /*
+          The inset travels with the width, because `box-sizing: border-box` will not take a box below
+          its own padding: a mark collapsed to nothing still held the twelve pixels it insets itself by,
+          and left them standing at the pill's leading edge.
+        */
+        const padding = (collapsed ? held : inset.current) ?? '0';
+        const open = {
+            inlineSize: `${collapsed ? (previous ?? measured) : measured}px`,
+            [margin]: '0',
+            opacity: 1,
+            paddingInline: padding,
+        };
+        const shut = { inlineSize: '0', [margin]: `calc(${gap} * -1)`, opacity: 0, paddingInline: '0' };
+        node.style.overflow = 'hidden';
+        /*
+          `fill: backwards` is what stops the flicker, and it is one frame long.
+    
+          The effect below runs before the browser paints, but an animation does not take hold until the
+          frame after it is started — so for exactly one frame the element is drawn at whatever the
+          stylesheet says, which is the state it is travelling *to*. Expanding, that is a mark at full
+          width appearing for a frame and then starting again from nothing. Backwards fill applies the
+          first keyframe from the moment the animation exists rather than from the moment it starts.
+        */
+        const running = node.animate(collapsed ? [open, shut] : [shut, open], {
+            duration,
+            easing,
+            fill: 'backwards',
+        });
+        /*
+          Put the overflow back whether it finished or was cut short — a second scroll cancels the first
+          animation, which rejects `finished`, and a box left clipped would clip the focus ring on the
+          button inside it for the rest of the session.
+    
+          Only if this is still the animation in force, though. Scrolling up and down quickly starts a
+          second before the first has resolved, and the first one's cleanup would otherwise unclip a box
+          that the second is still narrowing — which is the content spilling out of it and back in, once
+          per change of mind.
+        */
+        latest.current = running;
+        const restore = () => {
+            if (latest.current !== running)
+                return;
+            node.style.overflow = '';
+        };
+        running.finished.then(restore).catch(restore);
+    }, [element, collapsed, gapSide]);
+}
+/** The two of this package's own components a page is likely to put in a switcher slot. */
+const TONED = [DropdownMenu, ButtonIcon, NavbarSwitcher];
+/**
+ * The tone, pressed on a switcher or a secondary action the page passed in.
+ *
+ * A slot is the page's and this component does not dress what goes in one — that rule is why the
+ * mark is the page's to make legible. This is the exception, and it earns it: what the tone has to
+ * answer is the ground *this* component painted, and it changes on scroll, which no page can see
+ * without writing a second scroll listener against the bar it is already inside.
+ *
+ * A secondary Button is told too, and only a secondary one. Its `inverse` tone is a fill for a dark
+ * ground, and a page that set it for the hero left it white-on-white once the bar gathered into its
+ * pill. A primary is coral on either ground and carries its own, so it is left as it was handed.
+ *
+ * And every Button in the bar's action slots is drawn at `md`, whatever the page passed: the bar's
+ * items stand at size.control.md, and a button a step taller than the row it sits in pushes the
+ * bar taller with it. The collapsed panel's foot is not the bar, so it keeps the page's size.
+ *
+ * Matched by type rather than hoped for. Anything else the slot is handed goes through untouched,
+ * because pressing the prop on a component that does not declare it would put an unknown attribute
+ * on a DOM node, which React says out loud and a reader then has to go and disprove.
+ *
+ * Each of several, not only a lone one. The slot is for "a language picker, a theme toggle", and
+ * handed both as a list the second used to go through undressed — dark ink on a dark hero.
+ */
+function toned(children, dressing) {
+    // An empty slot stays empty rather than becoming `[]`, which every "is there anything here"
+    // check downstream — NavbarPanel's among them, and the bar's own — would read as something to
+    // draw a box for. `false` from a `{signedIn && <Button/>}` flattens to nothing, so it is empty too.
+    return children.length === 0 ? undefined : children.map((child) => dressed(child, dressing));
+}
+/**
+ * A slot's contents as one flat list, with every fragment opened.
+ *
+ * A page hands a pair of actions over as `<>…</>` and a list of switchers the same way, and
+ * `Children.map` does not look inside a fragment — so a fragment reached anything that matched on
+ * type, NavbarPanel's switcher-to-row swap included, as one opaque element. Opened here, once,
+ * each control is a child of its own wherever the slot is drawn.
+ *
+ * Every element comes out with a key unique across the whole list. `Children.toArray` keys each
+ * level from `.0` again, so the children of two fragments side by side would share keys and React
+ * could hand one control's state — an open switcher, say — to another. Each key is prefixed with
+ * the path of fragments it came through, the way React keys nested arrays itself.
+ */
+export function flattened(node, path = '') {
+    return Children.toArray(node).flatMap((child) => {
+        if (!isValidElement(child))
+            return [child];
+        const key = `${path}${String(child.key)}`;
+        if (child.type === Fragment)
+            return flattened(child.props.children, `${key}/`);
+        return [path === '' ? child : cloneElement(child, { key })];
+    });
+}
+/**
+ * The bar's actions are a pair, and a page that hands it more is told.
+ *
+ * At most two Buttons: one primary, and one secondary beside it — the conversion and the way back
+ * in. A lone Button is the primary. A third, or a second of either rank, is the bar asking the
+ * reader to choose between things it should have ranked; the `navbar-actions-are-a-pair` rule has
+ * the reasoning. Nothing checks a page's JSX yet, so this is where it is caught.
+ *
+ * Said, not refused. The bar still draws what it was handed — a page mid-build that lost its
+ * buttons would be worse than one with a third — and says so once for each shape of mistake, the
+ * way product's charts warn about a crowded palette.
+ */
+const warned = new Set();
+function warnIfActionsAreNotAPair(utilities) {
+    const variants = utilities
+        .filter((child) => isValidElement(child) && child.type === Button)
+        .map((button) => button.props.variant ?? buttonDefaults.variant);
+    const problem = variants.length > 2
+        ? `was handed ${variants.length} Buttons`
+        : variants.length === 1 && variants[0] !== 'primary'
+            ? `was handed a single ${variants[0]} Button`
+            : variants.length === 2 && !(variants.includes('primary') && variants.includes('secondary'))
+                ? `was handed two Buttons that are ${variants.join(' and ')}`
+                : undefined;
+    if (problem === undefined || warned.has(problem))
+        return;
+    warned.add(problem);
+    // eslint-disable-next-line no-console
+    console.warn(`Navbar ${problem} in utilities. The bar holds at most two: one primary, and one secondary ` +
+        'beside it — a lone Button is the primary. A third action belongs somewhere on the page, ' +
+        'not in the bar. See the navbar-actions-are-a-pair rule.');
+}
+/**
+ * One control, dressed for where it stands.
+ *
+ * Only what the dressing sets is written. `openOnHover` in particular is a page's to decide in a
+ * slot the bar has no view on, and cloning `{ openOnHover: undefined }` would reset it rather than
+ * leave it — an explicit `undefined` is an override to `cloneElement`, not an absence.
+ *
+ * A Button takes the bar's tone whatever its variant. On a secondary the tone is the fill; on the
+ * others it is only the focus ring, which has to follow the ground as much as any fill does — a
+ * primary keeping `inverse` from the hero would draw a white ring on the white pill.
+ */
+function dressed(node, { tone, openOnHover, size }) {
+    if (!isValidElement(node))
+        return node;
+    if (node.type === Button) {
+        return cloneElement(node, { tone, ...(size === undefined ? {} : { size }) });
+    }
+    if (!TONED.includes(node.type))
+        return node;
+    const hover = node.type === DropdownMenu && openOnHover !== undefined ? { openOnHover } : {};
+    return cloneElement(node, { tone, ...hover });
+}
+/**
+ * The bar across the top of a marketing page: the mark, the places the site has,
+ * and the things a reader reaches for rather than navigates to.
+ *
+ * It holds no destinations of its own — what goes in it is what the page
+ * composes. What this owns is the bar, and running out of room is the whole of
+ * its behaviour: below the width its three regions fit in, the destinations and
+ * the utilities stop being drawn and the trigger takes their place.
+ *
+ * Which section is open is the bar's, not each menu's. A menu cannot see its
+ * neighbours, so left to themselves two of them open at once and two surfaces
+ * overlap in front of the page. Injected the way TabList injects `selected`, and
+ * for the same reason.
+ *
+ * The rail paints nothing and the row inside it is the container a reader sees.
+ * That split is why there is no line under the bar: what separates it from the
+ * page is a surface of its own with air around it.
+ *
+ * No `role="banner"`. A `<header>` outside a sectioning element already is that
+ * landmark, and writing it as well says so a second time in a way that goes stale
+ * if the element is ever nested.
+ */
+export function Navbar({ tone = navbarDefaults.tone, label, menuLabel, closeLabel, brand, utilities, compactAction, preferences, showThemeToggle = navbarDefaults.showThemeToggle, theme, onThemeChange, themeToggleLabel, menuOpen, onMenuOpenChange, children, ...rest }) {
+    /*
+      The theme toggle, drawn by the bar and placed after whatever the page put in preferences.
+  
+      A ButtonIcon rather than a switcher: two themes are a toggle, not a choice among many, so a
+      menu listing both is a step nobody needs. `plain` so it is one of the pill's own items, and
+      `md` because that square is size.control.md — the height every item, menu and switcher in the
+      pill stands at, and the size the bar's buttons are. The glyph is the theme a press moves to; the name stays the theme it turns on
+      and aria-pressed carries the state, so a screen reader hears one name whichever way it is.
+  
+      Joined to preferences as a list rather than drawn in a box of its own, so it takes the same
+      tone on the hero and in the pill, and the collapsed panel draws it at its foot beside the
+      rest — both come for free from how that slot is already handled.
+    */
+    /*
+      Drawn only once it can be named. The pairing is enforced by the types, which a consumer
+      writing JavaScript never sees — and a glyph-only toggle with no label is a button a screen
+      reader announces with nothing after it. Absent is the honest failure; unnamed is not.
+    */
+    const themeToggle = showThemeToggle && theme !== undefined && themeToggleLabel !== undefined && themeToggleLabel !== '' ? (_jsx(ButtonIcon, { variant: "plain", size: "md", label: themeToggleLabel, "aria-pressed": theme === 'dark', icon: theme === 'dark' ? _jsx(SunBrightRegularIcon, {}) : _jsx(MoonRegularIcon, {}), onClick: () => onThemeChange?.(theme === 'dark' ? 'light' : 'dark') }, "dds-navbar-theme-toggle")) : null;
+    /*
+      Each slot opened into one flat list, once per render — the warning, the bar and the panel all
+      read these rather than each walking the fragments again.
+    */
+    const preferenceList = themeToggle === null ? flattened(preferences) : [...flattened(preferences), themeToggle];
+    const utilityList = flattened(utilities);
+    const compactList = flattened(compactAction);
+    const rootRef = useRef(null);
+    const condensed = useScrolled(rootRef);
+    const gathered = condensed ? 'true' : undefined;
+    /*
+      The tone the bar is actually wearing, which is not always the one it was given.
+  
+      `inverse` describes a ground: it is set because the first section of the page painted itself
+      dark and the bar is standing on it. Scrolling takes the bar off that section, so it gathers
+      into the same white pill a light bar does — and everything on it has to agree, at once.
+  
+      Derived here rather than in the stylesheet, which is where it was and where it could only ever
+      be half a fix. A rule can repaint this component's own parts; it cannot reach the `tone` a
+      destination was handed, because that is a prop. So the bar went white while the items on it
+      went on tinting their hovers for a dark ground — a hover nobody could see, which is exactly
+      what a light-ground hover looks like on light ground.
+  
+      One value, read by the attribute the stylesheet matches and by every child that is told a tone.
+    */
+    const worn = condensed ? 'default' : tone;
+    /*
+      Each slot dressed once, for the ground it stands on. The utilities are drawn in two places —
+      inside the pill once it gathers, and at the trailing end before — and both show the same
+      element, so they share one dressing rather than keeping two in step by hand.
+    */
+    const barSwitchers = toned(preferenceList, { tone: worn, openOnHover: true });
+    warnIfActionsAreNotAPair(utilityList);
+    const barUtilities = toned(utilityList, { tone: worn, size: 'md' });
+    const barCompact = toned(compactList, { tone: worn, size: 'md' });
+    const triggerRef = useRef(null);
+    /*
+      The pill's pair, which is the half of this that JavaScript has to do.
+  
+      The row's pair is a share of the row, so it collapses by taking that share to nothing — a number,
+      which CSS can transition, so the stylesheet owns it. These two are sized by what they hold, and
+      a width cannot travel between a length and `auto`, so their measure has to be taken. Each
+      collapses against the gap on the side it is at: the mark at a leading edge, the actions at a
+      trailing one.
+    */
+    const pillBrandRef = useRef(null);
+    const pillActionsRef = useRef(null);
+    useCollapse(pillBrandRef, !condensed, 'end');
+    useCollapse(pillActionsRef, !condensed, 'start');
+    /*
+      Controlled when told, its own answer otherwise. A private copy alongside a
+      passed one would be two answers to a question with one truth, and would show
+      the stale one for a frame the first time a page set it from anywhere else.
+    */
+    const [held, setHeld] = useState(false);
+    const controlled = menuOpen !== undefined;
+    const open = controlled ? menuOpen : held;
+    const setOpen = useCallback((next) => {
+        if (!controlled)
+            setHeld(next);
+        onMenuOpenChange?.(next);
+    }, [controlled, onMenuOpenChange]);
+    const close = useCallback(() => setOpen(false), [setOpen]);
+    // Which section is showing, by position in the row. Positions rather than
+    // labels: two sections can share a name in a way nothing here should have an
+    // opinion about, and an index is stable for as long as the row is.
+    const [section, setSection] = useState(null);
+    /*
+      Which section was open before this render, so a menu can be told whether it is arriving or
+      taking another's place. Written in an effect rather than during render, so what it holds is the
+      value the last committed render was drawn with — which is exactly the question being asked.
+    */
+    const previous = useRef(null);
+    useEffect(() => {
+        previous.current = section;
+    }, [section]);
+    const items = Children.toArray(children);
+    const governed = items.map((child, index) => {
+        if (!isValidElement(child) || child.type !== NavbarMenu) {
+            // A destination takes the tone as well. It is not governed — nothing about it
+            // opens — so it is cloned for this alone rather than passed through untouched.
+            return isValidElement(child) && child.type === NavbarItem
+                ? cloneElement(child, { tone: worn })
+                : child;
+        }
+        return cloneElement(child, {
+            /*
+              The tone travels with the open state, and for the same reason: a row
+              where one trigger is inverse and its neighbours are not is a row whose
+              hovers half disappear. The bar is the only thing that knows what it is
+              standing on, so it tells them rather than asking the page to tell each.
+            */
+            tone: worn,
+            open: section === index,
+            replacing: section === index && previous.current !== null && previous.current !== index,
+            onOpenChange: chain(child.props.onOpenChange, (next) => {
+                setSection(next ? index : null);
+            }),
+        });
+    });
+    return (_jsxs("header", { ...rest, ref: rootRef, className: navbarParts.root, "data-tone": worn, "data-condensed": gathered, "data-dds-pinned-surface": open ? 'open' : undefined, children: [_jsxs("div", { className: navbarParts.inner, "data-condensed": gathered, children: [_jsx("div", { className: navbarParts.ground, "data-condensed": gathered }), brand !== undefined && brand !== null && (_jsx("div", { className: navbarParts.brand, "data-condensed": gathered, children: brand })), _jsxs("div", { className: navbarParts.cluster, "data-condensed": gathered, children: [brand !== undefined && brand !== null && (_jsx("div", { ref: pillBrandRef, className: navbarParts.brand, children: brand })), _jsx("nav", { className: navbarParts.nav, "aria-label": label, children: governed }), barSwitchers !== undefined && (_jsx("div", { className: navbarParts.preferences, children: barSwitchers })), barUtilities !== undefined && (_jsx("div", { ref: pillActionsRef, className: navbarParts.utilities, children: barUtilities }))] }), barUtilities !== undefined && (_jsx("div", { className: navbarParts.utilities, "data-condensed": gathered, children: barUtilities })), barCompact !== undefined && (_jsx("div", { className: navbarParts['compact-action'], children: barCompact })), _jsx("button", { ref: triggerRef, type: "button", className: navbarParts.trigger, "aria-label": menuLabel, "aria-expanded": open, onClick: () => setOpen(!open), children: _jsx(Icon, { size: "md", children: open ? _jsx(XmarkRegularIcon, {}) : _jsx(BarsRegularIcon, {}) }) })] }), open && (_jsx("div", { className: navbarParts['panel-host'], children: _jsx(NavbarPanel, { label: label, closeLabel: closeLabel, onClose: close, brand: brand, 
+                    /*
+                      Both, because the pill they were drawn in is not drawn at this width and
+                      the foot is where everything that was in the bar has gone. What a reader
+                      sets comes first: the actions are the last thing the panel offers, and a
+                      switcher underneath them would be a preference hidden below a conversion.
+                    */
+                    /*
+                      At the panel's tone, not the bar's. The panel is paper whatever the bar is standing
+                      on, and this is the same element drawn in the pill — told `inverse` there and wrong
+                      here, where a hover tinted for a dark ground lands on white and disappears.
+        
+                      And not told to open on hover: in a panel a switcher is a row read down with a
+                      finger, and the panel is the thing that turns it into one.
+                    */
+                    preferences: toned(preferenceList, { tone: 'default', openOnHover: false }), footer: toned(utilityList, { tone: 'default' }), openerRef: triggerRef, children: children }) }))] }));
+}

package/dist/components/core/navbar/Navbar.types.d.ts

@@ -0,0 +1,68 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface NavbarOwnProps {
+    /**
+     * `default` — The page begins on a light ground, which is most marketing pages. The bar paints in ink and the pill is paper
+     * `inverse` — The first section of the page paints its own dark ground and the bar stands on it — a dark hero, a photograph, a brand-coloured takeover. The bar's ink runs light, and the pill and the collapsed bar take the dark see-through material — a near-opaque black base, a white tint and a blur — so a light photograph behind cannot wash them out
+     */
+    tone?: 'default' | 'inverse';
+    /** Always — it names the navigation landmark, and a page with an unnamed one tells a screen-reader user there is navigation here without saying which navigation. Name the set rather than the act: 'Main', not 'Main navigation' — the role already supplies the word, and a name carrying it is announced as 'main navigation navigation' */
+    label: string;
+    /** Always — the trigger is an icon-only button and this is the only name it has, at the width where it is the only way through the site. Name what it reveals rather than its state: 'Menu', not 'Open menu', because aria-expanded already says which way it is and a name that also said so would contradict itself every other press */
+    menuLabel: string;
+    /** Always — it names the panel's close button, which is the only visible way out of a surface covering the whole page. 'Close' is enough; the panel it closes is the only thing open */
+    closeLabel: string;
+    /** Effectively always on a real site — the mark, and usually an anchor to the home page wrapped around it. It is drawn twice: in the bar, and again in the panel's header, where it is the only thing left saying whose site this is */
+    brand?: ReactNode;
+    /** The bar's trailing end has the site's actions in it: one Button, which is primary, or two — one primary and one secondary, the conversion beside the way back in. A switcher is a DropdownMenu with the current choice on its trigger, which is what DropdownMenu's own guidance describes and why it is accepted here alongside the two controls. They are drawn in the row at wide widths and across the foot of the panel once it collapses. The bar dresses what it is handed: every Button here is drawn at md and takes the tone of the ground the bar is on at that scroll position — inverse on the hero, default once the pill gathers — and a ButtonIcon or a DropdownMenu takes the tone too. That reaches the controls handed in directly, or in a fragment; a control inside a component of the page's own is past it, so a wrapper takes tone and size as props and passes them down */
+    utilities?: ReactNode;
+    /** The one thing a reader should still be able to do once the bar has collapsed and everything else has gone into the panel — a sign-up, usually. Drawn beside the control that opens the panel, and only at the widths where that control is drawn. Dressed like utilities: a Button here is drawn at md and takes the bar's tone */
+    compactAction?: ReactNode;
+    /** A switcher that belongs with the destinations rather than with the conversion — a language picker, a theme toggle. It is drawn inside the pill, beside the sections, at every scroll position. A NavbarSwitcher is the one built for it: in the pill it is a trigger and a menu, and in the collapsed panel the same element becomes a row that opens a page of its own with a way back, because a dropdown inside a surface already covering the screen is a surface inside a surface */
+    preferences?: ReactNode;
+    /** The page is holding whether the panel is open, because something else depends on it — a route change that should close it, a surface of its own that must not open at the same time. Passing it makes the bar controlled: it shows what it is told and reports presses through onMenuOpenChange.
+  
+  Leave it off and the bar holds its own answer, which is the ordinary case: a narrow-width navigation panel is opened and closed by the reader and by nothing else */
+    menuOpen?: boolean;
+    /** Whenever menuOpen is — together they are how a page holds the panel. It is called with the state being moved to, by the trigger, by the close button and by Escape, so a page listening to it hears every way the panel can change */
+    onMenuOpenChange?: (open: boolean) => void;
+    /** Allowed: NavbarItem, NavbarMenu */
+    children: ReactNode;
+}
+export type NavbarProps = NavbarOwnProps & Omit<HTMLAttributes<HTMLElement>, 'className' | 'tone' | 'label' | 'menuLabel' | 'closeLabel' | 'brand' | 'utilities' | 'compactAction' | 'preferences' | 'showThemeToggle' | 'theme' | 'onThemeChange' | 'themeToggleLabel' | 'menuOpen' | 'onMenuOpenChange'> & ({
+    showThemeToggle?: boolean;
+    theme: 'light' | 'dark';
+} | {
+    showThemeToggle?: false;
+    theme?: 'light' | 'dark';
+}) & ({
+    showThemeToggle?: boolean;
+    onThemeChange: (theme: 'light' | 'dark') => void;
+} | {
+    showThemeToggle?: false;
+    onThemeChange?: (theme: 'light' | 'dark') => void;
+}) & ({
+    showThemeToggle?: boolean;
+    themeToggleLabel: string;
+} | {
+    showThemeToggle?: false;
+    themeToggleLabel?: string;
+});
+/** The class each part carries. Apply these — do not retype them. */
+export declare const navbarParts: {
+    readonly root: "dds-navbar";
+    readonly inner: "dds-navbar__inner";
+    readonly ground: "dds-navbar__ground";
+    readonly brand: "dds-navbar__brand";
+    readonly nav: "dds-navbar__nav";
+    readonly preferences: "dds-navbar__preferences";
+    readonly utilities: "dds-navbar__utilities";
+    readonly 'compact-action': "dds-navbar__compact-action";
+    readonly trigger: "dds-navbar__trigger";
+    readonly 'panel-host': "dds-navbar__panel-host";
+    readonly cluster: "dds-navbar__cluster";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const navbarDefaults: {
+    readonly tone: "default";
+    readonly showThemeToggle: false;
+};

package/dist/components/core/navbar/Navbar.types.js

@@ -0,0 +1,17 @@
+// GENERATED from navbar.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const navbarParts = {
+    root: 'dds-navbar',
+    inner: 'dds-navbar__inner',
+    ground: 'dds-navbar__ground',
+    brand: 'dds-navbar__brand',
+    nav: 'dds-navbar__nav',
+    preferences: 'dds-navbar__preferences',
+    utilities: 'dds-navbar__utilities',
+    'compact-action': 'dds-navbar__compact-action',
+    trigger: 'dds-navbar__trigger',
+    'panel-host': 'dds-navbar__panel-host',
+    cluster: 'dds-navbar__cluster',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const navbarDefaults = { tone: 'default', showThemeToggle: false };