@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/dist/components/core/navbar-menu/navbar-menu-impl.css

@@ -0,0 +1,186 @@
+/*
+ * Scoped to this package, like the generated sheet beside it.
+ *
+ * `:where([data-dds-context="marketing"])` confines these rules without contributing
+ * specificity, so every override below still ties or beats exactly what it did
+ * before — several here are written a class deeper than they look in order to
+ * match generated CSS, and a scope that carried weight would break all of them.
+ */
+
+/* Implementation CSS that the contract's staticCss cannot express. */
+
+/*
+ * Where the panel hangs, which is three offsets a contract cannot hold: two of them
+ * negate the bar's own padding and the third is a percentage of nothing.
+ *
+ * `inset-block-start: 100%` puts it under the trigger. The inline half centres it on that
+ * trigger rather than hanging it from the trigger's leading edge — an 846px panel dropped
+ * from the left of a one-word name runs off the end of the page for the last section in the
+ * row, and reads as belonging to whatever is to its right rather than to the name above it.
+ *
+ * Centred on the trigger rather than on the bar, which is the same thing in practice and a
+ * far smaller claim. The destinations sit in a pill the bar centres, so a panel centred on
+ * one of them lands near the middle of the page anyway — and doing it this way keeps the
+ * component positioning against its own root, so a menu used outside a Navbar still knows
+ * where to put its panel.
+ *
+ * `translate` rather than a negative margin: it is the transform property, so it composes
+ * with anything else the panel is given instead of fighting a layout value for the same
+ * axis, and it costs no layout pass.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarmenu .dds-navbarmenu__surface {
+  inset-block-start: 100%;
+  inset-inline-start: 50%;
+  translate: -50%;
+}
+
+/*
+ * Above the bar it hangs from, which a contract cannot hold: an integer with no unit.
+ *
+ * `layer.popup` is the role for what leaves the flow and floats over the page. It sits
+ * below anything that interrupts the reader, so NavbarPanel at `layer.overlay` still
+ * covers this — which is right: the two never show at the same width, and if they ever
+ * did, the one covering the page should win.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarmenu .dds-navbarmenu__surface {
+  z-index: var(--layer-popup);
+}
+
+/*
+ * The chevron turns.
+ *
+ * A rotation is a transform, which is neither a token nor a structural keyword — no
+ * contract can hold it. How long it takes and on what curve are decisions, and those are
+ * in the contract as motion.duration.fast and motion.easing.standard; this is only the
+ * shape of the movement.
+ *
+ * `rotate` rather than `transform`, so it composes with anything else the glyph is given
+ * rather than replacing it. The reduced-motion guard the generator writes covers
+ * `.dds-navbarmenu *`, so this is switched off with everything else — and switched off it
+ * leaves the chevron pointing the way it always did, which is the end state rather than a
+ * frame of the travel.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarmenu__trigger[data-expanded='true'] .dds-navbarmenu__chevron {
+  rotate: 180deg;
+}
+
+/*
+ * Two columns, whatever the number of sets.
+ *
+ * A row of groups makes the panel as wide as however many sets it happens to hold — add a fourth
+ * and the feature card is pushed out of an 846px surface. Two columns is a decision about the
+ * panel rather than about the content, and it is the arrangement the design asks for: sets flow
+ * into the pair and a third wraps beneath the first.
+ *
+ * `columns` and not a grid track list, which is the correction rather than a preference. A grid
+ * aligns its rows: a set of one beside a set of seven is stretched to the taller one, and the next
+ * set down starts below both, leaving a hand's width of nothing under the short one. Multi-column
+ * packs each column in turn, so a set begins where the set above it ended and the two columns
+ * balance to roughly equal height.
+ *
+ * What it costs is the row gap, which multi-column does not have — the space under a set belongs
+ * to the set, as a margin on the group. `column-gap` still applies here and is bound in the
+ * contract, so only the one axis moved.
+ *
+ * Not expressible in the contract. The count is an integer with no unit, the same reason a
+ * stacking order lives here.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarmenu .dds-navbarmenu__groups {
+  columns: 2;
+}
+
+/*
+ * The column ends where its last set ends.
+ *
+ * A set carries the space beneath it as a margin, because multi-column has no row gap to put it
+ * in. That is right for every set with another below it and wrong for the last one in a column,
+ * which has nothing to be separated from — so the panel gained a set's worth of empty space under
+ * its tallest column, and read as taller than its contents for a reason nothing on screen
+ * explained.
+ *
+ * Pulled back on the container rather than cleared on the group, because the group cannot be
+ * picked out: `:last-child` is the last in the DOM, which is the last in the *second* column, and
+ * the column that sets the height is usually the first. A negative margin on the box cancels
+ * whichever group happens to be last in whichever column turned out tallest.
+ *
+ * Reads its own value rather than repeating it, so retuning the step moves both halves together.
+ * TabList closes the seam between its rail and its bar the same way, and for the same reason: no
+ * contract can hold a negative dimension.
+ *
+ * Floating only, which was found rather than reasoned. The trailing margin counts towards the
+ * column's height here because the sets sit inside their own padding — there is a box edge after it
+ * for the margin to push against. Inline there is no such padding, and multi-column truncates a
+ * margin that ends a column, so the space this cancels was never taken in the first place: the
+ * cancellation landed on the picture below instead and pulled it up by a full step. The gap between
+ * the sets and the picture was specified at thirty-two and drawn at about eight, which is what sent
+ * this looking.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarmenu[data-presentation='floating'] .dds-navbarmenu__groups {
+  margin-block-end: calc(var(--space-gap-lg) * -1);
+}
+
+/*
+ * Inside the panel, a section takes the whole row.
+ *
+ * In the bar a trigger is one name among several across a line, so it is as wide as its word. In
+ * the panel it is one row of a list read down, and a name that stopped at its own text would leave
+ * the rest of the row dead: nothing to press where a reader is already aiming, and a shape that
+ * reads as a chip rather than as a row.
+ *
+ * The root stretches on its own — it is a flex item in the panel's column and takes the cross axis
+ * by default — but the trigger inside it does not: it sits on that root's main axis, where a flex
+ * item is as wide as its contents and nothing stretches it. So the width has to be said twice, once
+ * for the box and once for the control in it.
+ *
+ * `space-between` sends the chevron to the far end, which is where a list puts the mark that says a
+ * row opens. Against the words it reads as punctuation; against the edge it reads as an affordance,
+ * and it lines up with every other row's.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarmenu[data-presentation='inline'] {
+  inline-size: 100%;
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarmenu[data-presentation='inline'] .dds-navbarmenu__trigger {
+  inline-size: 100%;
+  justify-content: space-between;
+}
+
+/*
+ * In the panel the surface is in the flow, which is the whole difference between the two
+ * presentations and was the one part of it the stylesheet never said.
+ *
+ * `position: absolute` above is right for the bar and wrong here in a way that renders as
+ * nothing at all: taken out of the flow, hung at `inset-block-start: 100%` from a row whose
+ * containing block is the panel's scrolling body, and shrink-to-fit because the width the
+ * floating half is given is bound to that presentation only. The trigger turned its chevron and
+ * reported `aria-expanded`, so every signal said the section had opened while the sets sat in a
+ * zero-width box under the fold. The contract has said "opens in the flow and pushes what
+ * follows it down" since it was written; this is the CSS finally agreeing with it.
+ *
+ * `translate: none` and not just a change of `position`, because `translate` applies to any
+ * element whatever its position — the -50% that centres the floating panel on its trigger would
+ * otherwise drag this one half its own width off the leading edge of the panel, which is the
+ * kind of half-fixed that looks like a different bug.
+ *
+ * The insets and the stacking order above need no undoing: `inset-*` is ignored on a static box
+ * and so is `z-index`. They are left where they are rather than reset here, because a rule that
+ * clears something already inert reads as load-bearing to whoever edits it next.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarmenu[data-presentation='inline'] .dds-navbarmenu__surface {
+  position: static;
+  translate: none;
+  flex-direction: column;
+  inline-size: 100%;
+}
+
+/*
+ * And the root becomes a column, so the surface lands under the trigger rather than beside it.
+ *
+ * The root is `inline-flex`, which is a row: in the bar that holds one control and the direction
+ * never comes up, because the panel beside it is out of the flow and takes no place in the line.
+ * Put the surface back in the flow without this and the two share a row — the sets appear to the
+ * right of the name that opened them, each squeezed to half a phone.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarmenu[data-presentation='inline'] {
+  flex-direction: column;
+}

package/dist/components/core/navbar-menu-group/NavbarMenuGroup.css

@@ -0,0 +1,26 @@
+/* GENERATED from navbarmenugroup.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-navbarmenugroup {
+  break-inside: avoid;
+  display: flex;
+  flex-direction: column;
+  min-inline-size: 0;
+  gap: var(--space-gap-md);
+  margin-block-end: var(--space-gap-lg);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarmenugroup .dds-navbarmenugroup__list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-gap-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarmenugroup .dds-navbarmenugroup__label {
+  color: var(--color-fg-muted);
+  font-family: var(--font-label-sm-family);
+  font-size: var(--font-label-sm-size);
+  font-weight: var(--font-label-sm-weight);
+  letter-spacing: var(--font-label-sm-letter-spacing);
+  line-height: var(--font-label-sm-line-height);
+}
+

package/dist/components/core/navbar-menu-group/NavbarMenuGroup.d.ts

@@ -0,0 +1,17 @@
+import './NavbarMenuGroup.css';
+import { type NavbarMenuGroupProps } from './NavbarMenuGroup.types.js';
+export type { NavbarMenuGroupProps };
+/**
+ * A named handful of destinations inside a section's panel.
+ *
+ * `role="group"` named through `aria-labelledby` rather than `aria-label`, so the
+ * word a reader sees and the name a reader hears are one string. An aria-label
+ * repeating the label is two copies of the same thing, and they come apart the
+ * first time somebody edits one of them.
+ *
+ * The label is a `<div>`. It reads as a heading and is not one: the panel is
+ * navigation furniture inside a page with its own outline, and an h-element here
+ * would put a level into that outline for a word which exists only while a panel
+ * is open.
+ */
+export declare function NavbarMenuGroup({ label, children, ...rest }: NavbarMenuGroupProps): import("react").JSX.Element;

package/dist/components/core/navbar-menu-group/NavbarMenuGroup.js

@@ -0,0 +1,22 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import './NavbarMenuGroup.css';
+import { navbarMenuGroupParts } from './NavbarMenuGroup.types.js';
+/**
+ * A named handful of destinations inside a section's panel.
+ *
+ * `role="group"` named through `aria-labelledby` rather than `aria-label`, so the
+ * word a reader sees and the name a reader hears are one string. An aria-label
+ * repeating the label is two copies of the same thing, and they come apart the
+ * first time somebody edits one of them.
+ *
+ * The label is a `<div>`. It reads as a heading and is not one: the panel is
+ * navigation furniture inside a page with its own outline, and an h-element here
+ * would put a level into that outline for a word which exists only while a panel
+ * is open.
+ */
+export function NavbarMenuGroup({ label, children, ...rest }) {
+    const labelId = useId();
+    return (_jsxs("div", { ...rest, className: navbarMenuGroupParts.root, role: "group", "aria-labelledby": labelId, children: [_jsx("div", { id: labelId, className: navbarMenuGroupParts.label, children: label }), _jsx("div", { className: navbarMenuGroupParts.list, children: children })] }));
+}

package/dist/components/core/navbar-menu-group/NavbarMenuGroup.types.d.ts

@@ -0,0 +1,14 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface NavbarMenuGroupOwnProps {
+    /** Always — it is the word over the list and the group's accessible name. Name what the set is rather than what to do with it: 'Markets', not 'Browse markets' */
+    label: string;
+    /** Allowed: Link */
+    children: ReactNode;
+}
+export type NavbarMenuGroupProps = NavbarMenuGroupOwnProps & Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'label'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const navbarMenuGroupParts: {
+    readonly root: "dds-navbarmenugroup";
+    readonly label: "dds-navbarmenugroup__label";
+    readonly list: "dds-navbarmenugroup__list";
+};

package/dist/components/core/navbar-menu-group/NavbarMenuGroup.types.js

@@ -0,0 +1,7 @@
+// GENERATED from navbar-menu-group.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const navbarMenuGroupParts = {
+    root: 'dds-navbarmenugroup',
+    label: 'dds-navbarmenugroup__label',
+    list: 'dds-navbarmenugroup__list',
+};

package/dist/components/core/navbar-panel/NavbarPanel.css

@@ -0,0 +1,87 @@
+/* GENERATED from navbarpanel.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  inset: 0;
+  position: fixed;
+  background-color: var(--color-bg-page);
+  color: var(--color-fg-default);
+  gap: var(--space-gap-sm);
+  padding-block-end: var(--space-inset-md);
+  padding-block-start: var(--space-inset-xs);
+  padding-inline: var(--space-inset-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__header {
+  align-items: center;
+  display: flex;
+  flex-shrink: 0;
+  justify-content: space-between;
+  gap: var(--space-gap-sm);
+  min-block-size: var(--size-control-md);
+  padding-inline: var(--space-inset-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__mark {
+  align-items: center;
+  display: flex;
+  block-size: var(--icon-size-md);
+  gap: var(--space-gap-sm);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__close {
+  align-items: center;
+  appearance: none;
+  border-style: none;
+  color: inherit;
+  cursor: pointer;
+  display: inline-flex;
+  flex-shrink: 0;
+  justify-content: center;
+  outline-style: solid;
+  padding: 0;
+  background-color: var(--color-bg-transparent);
+  border-radius: var(--radius-control-sm);
+  min-block-size: var(--size-target-min);
+  min-inline-size: var(--size-target-min);
+  outline-width: var(--border-width-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__body {
+  display: flex;
+  flex: auto;
+  flex-direction: column;
+  min-block-size: 0;
+  overflow-y: auto;
+  position: relative;
+  gap: var(--space-gap-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__destinations {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-gap-xs);
+  padding-block-start: var(--space-inset-sm);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__preferences {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-gap-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__footer {
+  display: flex;
+  flex-direction: column;
+  flex-shrink: 0;
+  gap: var(--space-gap-sm);
+  padding-block-start: var(--space-inset-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__close:focus-visible {
+  outline-color: var(--color-border-focus);
+  outline-width: var(--border-width-focus);
+}
+

package/dist/components/core/navbar-panel/NavbarPanel.d.ts

@@ -0,0 +1,34 @@
+import { type RefObject } from 'react';
+import './NavbarPanel.css';
+import './navbar-panel-impl.css';
+import { type NavbarPanelProps } from './NavbarPanel.types.js';
+export type { NavbarPanelProps };
+/**
+ * What opened the panel, so focus can go back to it.
+ *
+ * Optional, and absent is not a failure: a panel opened by something that has
+ * since unmounted — a route change, a bar that collapsed — has nowhere to return
+ * focus to, and the hook declines rather than sending it to the body, which is
+ * the top of a document the reader had scrolled away from.
+ */
+export interface NavbarPanelOwnerProps extends NavbarPanelProps {
+    openerRef?: RefObject<HTMLElement | null>;
+}
+/**
+ * The whole of a site's navigation at a width the bar cannot hold it.
+ *
+ * Rendered by Navbar rather than by a page. A page composing this itself would be
+ * wiring an open state to a threshold it cannot see — the bar is the thing that
+ * knows when its ends stopped fitting. It is contracted separately because it is
+ * a separate thing to judge, not a separate thing to assemble.
+ *
+ * The three obligations of a surface covering the page — focus held inside,
+ * Escape closing it, the document beneath holding still — are the hook's. They
+ * begin and end together, which is why they are one hook and not three.
+ *
+ * The `<nav>` is here, and the bar does not render its own at the widths this
+ * appears at. Two landmarks naming the same destinations tells a reader the site
+ * has two navigations, and the one they cannot see is the one they are offered
+ * first.
+ */
+export declare function NavbarPanel({ label, preferences, closeLabel, onClose, brand, footer, openerRef, children, ...rest }: NavbarPanelOwnerProps): import("react").JSX.Element;

package/dist/components/core/navbar-panel/NavbarPanel.js

@@ -0,0 +1,46 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement, useRef } from 'react';
+import { XmarkRegularIcon } from '@deriv-com/quill-icons-web';
+import './NavbarPanel.css';
+import './navbar-panel-impl.css';
+import { Icon } from '../icon/Icon.js';
+import { NavbarMenu } from '../navbar-menu/NavbarMenu.js';
+import { NavbarSwitcher } from '../navbar-switcher/NavbarSwitcher.js';
+import { navbarPanelParts } from './NavbarPanel.types.js';
+import { useNavbarPanel } from './use-navbar-panel.js';
+/**
+ * The whole of a site's navigation at a width the bar cannot hold it.
+ *
+ * Rendered by Navbar rather than by a page. A page composing this itself would be
+ * wiring an open state to a threshold it cannot see — the bar is the thing that
+ * knows when its ends stopped fitting. It is contracted separately because it is
+ * a separate thing to judge, not a separate thing to assemble.
+ *
+ * The three obligations of a surface covering the page — focus held inside,
+ * Escape closing it, the document beneath holding still — are the hook's. They
+ * begin and end together, which is why they are one hook and not three.
+ *
+ * The `<nav>` is here, and the bar does not render its own at the widths this
+ * appears at. Two landmarks naming the same destinations tells a reader the site
+ * has two navigations, and the one they cannot see is the one they are offered
+ * first.
+ */
+export function NavbarPanel({ label, preferences, closeLabel, onClose, brand, footer, openerRef, children, ...rest }) {
+    const panelRef = useRef(null);
+    const fallbackOpener = useRef(null);
+    useNavbarPanel({
+        // Always open: this component is not rendered otherwise, which is what keeps
+        // the bar's `aria-expanded` honest — there is no state here that could
+        // disagree with whether the element exists.
+        open: true,
+        panelRef,
+        triggerRef: openerRef ?? fallbackOpener,
+        onClose,
+    });
+    return (_jsxs("div", { ...rest, ref: panelRef, className: navbarPanelParts.root, children: [_jsxs("div", { className: navbarPanelParts.header, children: [brand !== undefined && brand !== null && (_jsx("div", { className: navbarPanelParts.mark, children: brand })), _jsx("button", { type: "button", className: navbarPanelParts.close, "aria-label": closeLabel, onClick: onClose, children: _jsx(Icon, { size: "md", children: _jsx(XmarkRegularIcon, {}) }) })] }), _jsxs("div", { className: navbarPanelParts.body, children: [_jsx("nav", { className: navbarPanelParts.destinations, "aria-label": label, children: Children.map(children, (child) => isValidElement(child) && child.type === NavbarMenu
+                            ? cloneElement(child, { presentation: 'inline' })
+                            : child) }), preferences !== undefined && preferences !== null && (_jsx("div", { className: navbarPanelParts.preferences, children: Children.map(preferences, (child) => isValidElement(child) && child.type === NavbarSwitcher
+                            ? cloneElement(child, { presentation: 'panel' })
+                            : child) }))] }), footer !== undefined && footer !== null && (_jsx("div", { className: navbarPanelParts.footer, children: footer }))] }));
+}

package/dist/components/core/navbar-panel/NavbarPanel.types.d.ts

@@ -0,0 +1,29 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface NavbarPanelOwnProps {
+    /** Always — it names the navigation landmark inside the panel, and this is the only one on the page while the panel is open. Name the set rather than the act: 'Main', not 'Main navigation', because the role already supplies the word */
+    label: string;
+    /** Always — it names the close button, which draws a glyph and no text and is the only visible way out of a surface covering the whole page. 'Close' is enough; what it closes is the only thing open */
+    closeLabel: string;
+    /** Always. It is called by the close button and by Escape, so whatever holds the panel open hears both ways it can be dismissed */
+    onClose: () => void;
+    /** Whatever the bar carries as its mark, passed straight through. Absent only where the bar has none either */
+    brand?: ReactNode;
+    /** The bar has switchers, which it hands over when it collapses. They are drawn under the destinations and above the foot */
+    preferences?: ReactNode;
+    /** The bar's utility end has something worth keeping at this width — the conversion, and the language or theme controls. They are drawn across the foot here rather than in a row, because there is width for one control and no room for three */
+    footer?: ReactNode;
+    /** Allowed: NavbarItem, NavbarMenu */
+    children: ReactNode;
+}
+export type NavbarPanelProps = NavbarPanelOwnProps & Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'label' | 'closeLabel' | 'onClose' | 'brand' | 'preferences' | 'footer'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const navbarPanelParts: {
+    readonly root: "dds-navbarpanel";
+    readonly header: "dds-navbarpanel__header";
+    readonly mark: "dds-navbarpanel__mark";
+    readonly close: "dds-navbarpanel__close";
+    readonly body: "dds-navbarpanel__body";
+    readonly destinations: "dds-navbarpanel__destinations";
+    readonly preferences: "dds-navbarpanel__preferences";
+    readonly footer: "dds-navbarpanel__footer";
+};

package/dist/components/core/navbar-panel/NavbarPanel.types.js

@@ -0,0 +1,12 @@
+// GENERATED from navbar-panel.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const navbarPanelParts = {
+    root: 'dds-navbarpanel',
+    header: 'dds-navbarpanel__header',
+    mark: 'dds-navbarpanel__mark',
+    close: 'dds-navbarpanel__close',
+    body: 'dds-navbarpanel__body',
+    destinations: 'dds-navbarpanel__destinations',
+    preferences: 'dds-navbarpanel__preferences',
+    footer: 'dds-navbarpanel__footer',
+};

package/dist/components/core/navbar-panel/navbar-panel-impl.css

@@ -0,0 +1,104 @@
+/*
+ * Scoped to this package, like the generated sheet beside it.
+ *
+ * `:where([data-dds-context="marketing"])` confines these rules without contributing
+ * specificity, so every override below still ties or beats exactly what it did
+ * before — several here are written a class deeper than they look in order to
+ * match generated CSS, and a scope that carried weight would break all of them.
+ */
+
+/* Implementation CSS that the contract's staticCss cannot express. */
+
+/*
+ * Above everything the page lays out, which a contract cannot hold: an integer with no
+ * unit.
+ *
+ * A fixed box at `z-index: auto` still loses to any positioned element painted after it,
+ * and this one is rendered inside a sticky bar near the top of the document — so every
+ * positioned section below it in source order outranks it. The failure is not subtle: a
+ * surface meant to cover the page has the page showing through it.
+ *
+ * `layer.overlay` is the role for what interrupts the reader, and it is the one
+ * BottomSheet takes. Sitting level with a sheet is correct rather than a collision: the
+ * two are alternatives, and a site that opened both at once has a bug this ordering would
+ * only hide.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarpanel {
+  z-index: var(--layer-overlay);
+}
+
+/*
+ * And whatever the slot was given fills that height, keeping its own shape.
+ *
+ * The height is bound on the part, and the part is a wrapper — so alone it would constrain a box
+ * around a mark that went on drawing itself at whatever size it arrived at. Quill's marks carry
+ * `width` and `height` attributes, and a presentation attribute is what a CSS declaration outranks.
+ *
+ * `inline-size: auto` against a bound block size is what keeps the ratio: a wordmark is three times
+ * wider than it is tall, and pinning both axes would letterbox it.
+ *
+ * The bar says the same thing about its own copy. Two components drawing one mark have to agree on
+ * its measure separately, because neither contains the other.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__mark > * {
+  align-items: center;
+  block-size: 100%;
+  display: flex;
+  inline-size: auto;
+}
+
+/*
+ * And it survives the anchor around it, which is the shape the contract asks for.
+ *
+ * The rule above reaches one level. That was enough while the slot held a mark and stopped being
+ * enough the moment it held the thing the guidance actually describes — "an `<a href="/">` around
+ * an SVG, in practice" — because the child it sizes is then the link rather than the picture. A
+ * link is `display: inline`, and `block-size` does not apply to a non-replaced inline box: the
+ * height was not overridden so much as ignored, the mark went on drawing itself at whatever size
+ * the page handed it, and an inline box sits on a text baseline, so it was off centre as well as
+ * too big.
+ *
+ * `display: flex` on the wrapper is what makes the height apply at all, and centres what is in it.
+ * Then the same two declarations again, one level deeper, for the mark itself.
+ *
+ * Two levels and not a descendant selector. A wrapper around the mark is the documented case and
+ * worth handling; anything deeper is a structure this component cannot reason about, and a rule
+ * that reset the size of everything inside the slot would be one that reached into a page's markup
+ * without knowing what it was touching.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__mark > * > * {
+  block-size: 100%;
+  inline-size: auto;
+}
+
+/*
+ * The destinations line up with the mark above them.
+ *
+ * The panel insets its contents, and a destination insets its own words on top of that — so the
+ * mark sat on the panel's measure and every row sat a step further in, which reads as a list that
+ * has been indented under a heading it does not belong to.
+ *
+ * Pulled back by exactly what a row pads itself, so the words land on the panel's own edge while
+ * the row keeps the padding its hover and current fills are drawn against. Clearing the padding
+ * instead would align the words and collapse the fills onto them.
+ *
+ * It pulls back by half what a row pads itself, not all of it, and that half is the whole argument.
+ *
+ * Pulled back by the full measure the words landed exactly under the mark — and the fill a row
+ * draws when it is hovered or open ran to the panel's own edge, because the row's box started
+ * there. An expanded section is a filled pill bleeding off both sides of the surface, which reads
+ * as a mistake whatever it was traded for.
+ *
+ * At half, every fill sits `space.inset.xs` inside the panel and every word sits the same step in
+ * from the mark. The words no longer line up with it, which is a real loss and the smaller one:
+ * they line up with each other, and a column of rows that agree is what a reader is actually
+ * scanning. Closing both would mean the panel's rows padding themselves less than the bar's do,
+ * which needs a presentation on NavbarItem that it does not have.
+ *
+ * Reads the step rather than repeating the number, so retuning it moves both halves together —
+ * the same reason TabList closes the seam between its rail and its bar this way. No contract can
+ * hold a negative dimension.
+ */
+:where([data-dds-context="marketing"]) .dds-navbarpanel .dds-navbarpanel__body {
+  margin-inline: calc(var(--space-inset-xs) * -1);
+}

package/dist/components/core/navbar-panel/use-navbar-panel.d.ts

@@ -0,0 +1,26 @@
+import { type RefObject } from 'react';
+/**
+ * What a surface covering the page owes the reader.
+ *
+ * Three obligations, kept together because they begin and end at the same moment
+ * and because separating them is how one of them gets forgotten: focus stays
+ * inside the panel, Escape closes it, and the document underneath holds still.
+ *
+ * Exported from the package. A site building its own covering surface needs the
+ * same three, and the alternative to handing them this is a fourth
+ * implementation with a different set of mistakes in it.
+ */
+export interface NavbarPanelOptions {
+    /** Whether the panel is showing. Everything here is inert while it is not. */
+    open: boolean;
+    /** The panel element. Focus is held inside this subtree. */
+    panelRef: RefObject<HTMLElement | null>;
+    /**
+     * What opened the panel. Focus returns here on close — to the control the
+     * reader pressed, rather than to the top of a document they have not seen.
+     */
+    triggerRef: RefObject<HTMLElement | null>;
+    /** Called by Escape. The panel's own close button calls it directly. */
+    onClose: () => void;
+}
+export declare function useNavbarPanel({ open, panelRef, triggerRef, onClose }: NavbarPanelOptions): void;