@deriv-com/dds-marketing 0.1.0 → 1.0.0

package/dist/components/core/bottom-sheet/BottomSheet.js

@@ -0,0 +1,359 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from 'react';
+import { ButtonIcon } from '../button-icon/ButtonIcon.js';
+import { XmarkSolidIcon } from '@deriv-com/quill-icons-web';
+import './BottomSheet.css';
+import './bottom-sheet-impl.css';
+import { given } from '../../given.js';
+import { visuallyHidden } from '../../visually-hidden.js';
+import { bottomSheetDefaults, bottomSheetParts } from './BottomSheet.types.js';
+/**
+ * How far down the sheet has to be pulled before letting go dismisses it.
+ *
+ * A share of the sheet's own height rather than a distance, because the same distance means
+ * different things on different sheets. A fixed one was the first answer here, and the same
+ * number came to two fifths of a short sheet and a twelfth of a full-screen one — a heave on one
+ * and a twitch on the other. A third is far enough that resting a finger on the handle does not
+ * throw the task away, on either.
+ *
+ * Floored, because a third of a very short sheet is a few pixels and a sheet should not come away
+ * in your hand. Neither number is a design token: nothing here is drawn, and no brand or mode has
+ * a different idea of how far a flick is.
+ */
+const DRAG_FRACTION = 0.3;
+const DRAG_FLOOR = 32;
+/** Everything focus can rest on, for holding it inside the sheet while the sheet is open. */
+/**
+ * Things that answer a pointer themselves, and so are never the start of a sheet drag.
+ *
+ * A Slider takes its own pointerdown and moves a thumb with it; without this the same gesture
+ * bubbled to the sheet and pulled that too, so setting a value halfway threw the task away. The
+ * rest are here for the smaller version of the same thing: a press that slides off a button is a
+ * press the reader changed their mind about, not a dismissal.
+ *
+ * Matched on what an element is rather than on whether it has a handler, there being no way to
+ * ask. A consumer's own draggable widget is not covered and cannot be — the escape hatch for that
+ * is to stop the event before it reaches the sheet.
+ */
+const OWNS_ITS_GESTURE = 'button, a, input, select, textarea, [role="slider"], [draggable="true"]';
+const FOCUSABLE = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+/**
+ * A panel that rises from the bottom edge to hold one focused task.
+ *
+ * Mounted whether it is open or not, which is the decision everything else here follows from.
+ * A sheet that mounts on opening has no previous state to animate out of, so the reveal would
+ * be a jump — and the contract's `open` axis is what the stylesheet varies, which it cannot do
+ * to an element that is not there. What keeps a shut sheet out of the reading order and out of
+ * the tab order is `visibility: hidden` in the generated CSS rather than anything written here:
+ * an `aria-hidden` or an `inert` set from this file would say the same thing twice, and the two
+ * would disagree the first time one of them changed.
+ *
+ * It owns none of its own openness. Every way out — the close button, the scrim, Escape, the
+ * drag — reports through `onOpenChange` and changes nothing, so a page that does not answer that
+ * callback has a sheet that cannot be closed. That is the same shape every other controlled
+ * component in this package takes, and the reason is the same: two things holding one fact
+ * disagree eventually, and the consumer is the one that has to win.
+ */
+export function BottomSheet(props) {
+    const { open = bottomSheetDefaults.open, height = bottomSheetDefaults.height, title, showTitle = bottomSheetDefaults.showTitle, description, back, action, showClose = bottomSheetDefaults.showClose, showHandle = bottomSheetDefaults.showHandle, onOpenChange, children, id, ...rest } = props;
+    const fallbackId = useId();
+    const rootId = id ?? fallbackId;
+    const titleId = `${rootId}-title`;
+    const descriptionId = `${rootId}-description`;
+    /**
+     * The box holding the panel and the controls above it, which is the sheet as far as everything
+     * here is concerned: what carries the dialog role, what focus is held inside, and what moves.
+     *
+     * The panel is not any of those things, and that is the point of the box. The controls sit
+     * outside the panel because the panel clips, and an element outside the thing that declares
+     * `aria-modal` is outside the task — a close button announced by nothing and reached by no Tab.
+     * Trapping on the box puts them back inside the one root that both answers to.
+     */
+    const frame = useRef(null);
+    /**
+     * Where focus was before the sheet took it, so it can be given back.
+     *
+     * A ref rather than state: nothing renders from it, and writing it would otherwise re-render
+     * the sheet at the exact moment it is being opened. Returned on close rather than on unmount,
+     * because this component does not unmount — see the note above.
+     */
+    const returnFocusTo = useRef(null);
+    /**
+     * Whether the sheet was open on the last render, so focus moves on a change and not on mount.
+     *
+     * Initialised to the first render's own value, which is what keeps a sheet that mounts *already*
+     * open from taking focus. That is a specimen — a documentation page, the preview's gallery — and
+     * a specimen that grabs focus on mount is worse than it sounds: the browser scrolls whatever
+     * gains focus into view, so a page of open sheets opens scrolled to the last of them.
+     *
+     * The same guard DropdownMenu carries, arrived at from the same failure. Nothing is lost for a
+     * consumer: a sheet is mounted shut and then opened, which is a change and still moves focus.
+     */
+    const wasOpen = useRef(open);
+    /** The content, so a gesture beginning in it can be told from one beginning on the chrome. */
+    const body = useRef(null);
+    /** What a gesture in progress needs to be judged by, or null while there is none. */
+    const drag = useRef(null);
+    /**
+     * How far the sheet has been pulled, as a share of its own height, or null when nothing is
+     * pulling it.
+     *
+     * A percentage rather than a distance, and the same one the stylesheet uses: a shut sheet is
+     * translated `0 100%`, so a finger halfway down is `0 50%` and the gesture and the animation
+     * are speaking the same unit. Nothing has to convert, and there is no pixel measure written
+     * into this file for a component that may not carry one.
+     */
+    const [pulled, setPulled] = useState(null);
+    const describes = given(description);
+    /**
+     * What each end of the line above the sheet has in it, or nothing.
+     *
+     * Both ends used to arrive together whether or not either had anything to hold, because each
+     * was reserving the other's width and an empty slot was what kept a centred title on the
+     * sheet's centre line. Ranged against the frame rather than sitting in the row, an end holds
+     * nothing open — so an empty one is a positioned box with no content and no reason to exist.
+     *
+     * Neither end decides whether the sheet can be left. A press outside it and Escape always work:
+     * they are what a reader tries when a sheet offers them nothing else, and a surface that answers
+     * neither is a trap rather than a decision.
+     */
+    const goesBack = back !== undefined && back !== null;
+    const acts = action !== undefined && action !== null;
+    /** The trailing end holds the exit, whatever else is in it — so either fills it. */
+    const trails = showClose || acts;
+    /**
+     * Focus into the sheet on opening, and back to the opener on closing.
+     *
+     * The first focusable thing inside, or the sheet itself where there is nothing — a dialog with
+     * focus left outside it is one a screen-reader user is told about and cannot reach, and a
+     * keyboard user tabs into the page behind the scrim rather than into the task.
+     *
+     * Keyed on `open` alone. The effect must not run when the content inside changes, or a sheet
+     * whose body re-renders steals focus back to its first control while somebody is typing in
+     * its third.
+     */
+    useEffect(() => {
+        const changed = wasOpen.current !== open;
+        wasOpen.current = open;
+        if (!changed)
+            return;
+        if (open) {
+            const previous = document.activeElement;
+            returnFocusTo.current = previous instanceof HTMLElement ? previous : null;
+            const first = frame.current?.querySelector(FOCUSABLE);
+            if (first !== null && first !== undefined)
+                first.focus();
+            else
+                frame.current?.focus();
+            return;
+        }
+        // Only what this sheet took. Without the check, a sheet that has never been open returns
+        // focus to whatever the page was doing on first render and steals it on mount.
+        const opener = returnFocusTo.current;
+        returnFocusTo.current = null;
+        opener?.focus();
+    }, [open]);
+    /**
+     * Escape, listened for on the document rather than on the sheet.
+     *
+     * Focus is inside the sheet while it is open, so a handler on the surface would catch it —
+     * until something inside opens a menu of its own, or the reader clicks the scrim and focus
+     * lands on the body. The document hears it either way, and the listener is bound only while
+     * the sheet is open, so a page holding six sheets is not running six handlers on every key.
+     */
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key !== 'Escape')
+                return;
+            // Not if something inside already answered it. A DropdownMenu open inside the sheet calls
+            // preventDefault on its own Escape, and without this check one press shuts the list and
+            // throws the sheet away with it — the reader loses the task for correcting the answer.
+            if (event.defaultPrevented)
+                return;
+            onOpenChange(false, 'escape');
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    });
+    /**
+     * Tab held inside the sheet, wrapping at both ends.
+     *
+     * Read at the moment of the keystroke rather than kept in a list, because what is focusable
+     * inside a task changes as the task is done — a disabled submit becomes enabled, a row is
+     * added. A list captured on open would send the reader to an element that is no longer there.
+     */
+    const onKeyDown = (event) => {
+        if (event.key !== 'Tab' || !open)
+            return;
+        const found = frame.current?.querySelectorAll(FOCUSABLE);
+        const focusable = found === undefined ? [] : Array.from(found);
+        if (focusable.length === 0) {
+            // Nothing to move to, so the only correct thing is to stay. Letting it through would put
+            // focus on the page behind a scrim that refuses the pointer.
+            event.preventDefault();
+            return;
+        }
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        const on = document.activeElement;
+        if (event.shiftKey && (on === first || on === frame.current)) {
+            event.preventDefault();
+            last.focus();
+        }
+        else if (!event.shiftKey && on === last) {
+            event.preventDefault();
+            first.focus();
+        }
+    };
+    /**
+     * A drag on the sheet's chrome, which the sheet follows.
+     *
+     * Not on the content, and that line is the browser's rather than a preference. The content
+     * scrolls, and a touch gesture beginning in a scroll container belongs to the scroller: the
+     * browser claims every downward swipe that starts there, cancels ours one move in, and does it
+     * whether or not there is anything to scroll. The whole surface did answer a pull once — but
+     * only ever with a mouse, because on a phone the content half of that rule could not run at all.
+     *
+     * So it is one sentence on every input: pull the header, scroll the content. A mouse can no
+     * longer dismiss from a place a finger cannot, which is worth more than the gesture it costs.
+     * The alternative is a component whose behaviour has to be described per device, and a reader
+     * who learns the sheet on a phone and is wrong about it on a laptop.
+     *
+     * It still waits for the first move rather than claiming the gesture on contact, because upward
+     * is never a pull — there is nothing above the sheet to bring it into. Decided once and not
+     * revisited, so a finger that wanders back up mid-pull does not hand the sheet away.
+     */
+    const onPointerDown = (event) => {
+        const target = event.target;
+        if (target.closest?.(OWNS_ITS_GESTURE) !== null)
+            return;
+        // The content's gestures are the scroller's. Asked of the element, not of `scrollTop`: a list
+        // with nothing to scroll is still a scroll container, and the browser treats it as one.
+        if (body.current?.contains(target) === true)
+            return;
+        drag.current = {
+            from: event.clientY,
+            // Measured once. The sheet cannot change height mid-gesture, and asking for it on every
+            // frame would be a layout read in the one place that has to keep up with a finger.
+            height: frame.current?.offsetHeight ?? 0,
+            pulling: false,
+        };
+    };
+    /**
+     * How far down this pointer is from where it started, floored at nothing.
+     *
+     * The start is passed in rather than read off the ref, and that is not a style choice: the
+     * release handler clears the ref before it works out what the gesture meant, so a version of
+     * this that reached for `drag.current` measured from the top of the window instead. Every pull
+     * cleared the threshold, and a sheet nudged a few pixels dismissed itself.
+     */
+    const travelled = (event, from) => Math.max(0, event.clientY - from);
+    const onPointerMove = (event) => {
+        const held = drag.current;
+        if (held === null)
+            return;
+        if (!held.pulling) {
+            // Still deciding. Anything but a downward pull hands the gesture back for good.
+            if (event.clientY <= held.from) {
+                drag.current = null;
+                return;
+            }
+            held.pulling = true;
+            /*
+               Captured here rather than on contact, which matters more than it looks. Capturing on
+               pointerdown takes every gesture the sheet is touched by — including a scroll — and the
+               list underneath then never moves. Claimed only once this is known to be a drag.
+      
+               It is also what makes the release land: without it the handler ran only when the finger
+               happened to still be over the sheet, so a firm flick past the sheet's own edge released
+               onto the page behind and did nothing. Measured, before and after.
+            */
+            event.currentTarget.setPointerCapture?.(event.pointerId);
+        }
+        const share = held.height === 0 ? 0 : (travelled(event, held.from) / held.height) * 100;
+        setPulled(Math.min(100, share));
+    };
+    const onPointerUp = (event) => {
+        const held = drag.current;
+        drag.current = null;
+        event.currentTarget.releasePointerCapture?.(event.pointerId);
+        // Let go of the offset either way: from here the stylesheet owns where the sheet is, and it
+        // carries it the rest of the way down or back to rest, from wherever the finger left it.
+        setPulled(null);
+        // A gesture that never became a drag is a press, or a scroll. Neither dismisses.
+        if (held === null || !held.pulling)
+            return;
+        const far = Math.max(held.height * DRAG_FRACTION, DRAG_FLOOR);
+        if (travelled(event, held.from) >= far)
+            onOpenChange(false, 'drag');
+    };
+    /** A gesture the system took over — a back-swipe, a notification pulled down. Not a dismissal. */
+    const onPointerCancel = () => {
+        drag.current = null;
+        setPulled(null);
+    };
+    /**
+     * The pull, which the sheet always answers.
+     *
+     * Not conditioned on the handle being drawn, for the reason the scrim and Escape are not: a
+     * reader pulls a sheet down because it is a sheet, and whether a bar was painted at the top is
+     * not something they consulted first. `showHandle` draws the affordance; the way out is the
+     * sheet's either way.
+     */
+    const dragging = { onPointerDown, onPointerMove, onPointerUp, onPointerCancel };
+    /**
+     * The way out, in one place whatever the sheet holds: above the panel, at the trailing corner,
+     * and last in its end so nothing is drawn outside it.
+     *
+     * It used to move with the title — opposite a centred one, gathered with the action once the
+     * title started at the leading edge — because both were competing for the same row. Out of that
+     * row there is nothing to move around, and the corner is the one place worth pinning it to: an
+     * exit that shifts to make room for whatever else the screen adds is an exit somewhere else on
+     * every sheet, and a reader who has learnt one is wrong about the next.
+     */
+    const close = (_jsx(ButtonIcon
+    /* No ring. The sheet is already a surface that has said what it is — a panel over a
+       scrim — so an edge around its exit would be the loudest thing in the header. This is
+       the variant ButtonIcon gained for it; Pagination wanted the same thing and had to draw
+       its own button, which is the gap this closes. */
+    , { 
+        /* No ring. The sheet is already a surface that has said what it is — a panel over a
+           scrim — so an edge around its exit would be the loudest thing in the header. This is
+           the variant ButtonIcon gained for it; Pagination wanted the same thing and had to draw
+           its own button, which is the gap this closes. */
+        variant: "plain", 
+        /* The compact step. A sheet's exit sits on the row that names it, beside a title at the
+           smallest heading step — at the default size the button stood taller than the words it
+           sat next to and read as the loudest thing in the header. */
+        size: "sm", label: `Close ${title}`, 
+        /* The bare glyph, not wrapped in an Icon. Which step belongs in a button of this size is
+           ButtonIcon's own rule and it applies it by cloning — an Icon around it puts `dds-icon`
+           on the svg at Icon's own default instead, which is a step and a half larger and beats
+           the binding. That is how the exit came to stand at twenty-four pixels beside a sixteen
+           pixel back arrow handed in bare. */
+        icon: _jsx(XmarkSolidIcon, {}), onClick: () => onOpenChange(false, 'close-button') }));
+    return (_jsxs("div", { className: bottomSheetParts.root, "data-open": String(open), "data-height": height, onKeyDown: onKeyDown, ...rest, children: [_jsx("div", { className: bottomSheetParts.scrim, onClick: () => onOpenChange(false, 'scrim') }), _jsx("div", { ref: frame, className: bottomSheetParts.frame, role: "dialog", "aria-modal": "true", "aria-labelledby": titleId, "aria-describedby": describes ? descriptionId : undefined, 
+                /* So focus has somewhere to land in a sheet holding nothing focusable — a task that is
+                   text and a single action still has to be readable from the top. Not a tab stop: -1
+                   takes focus from script and never from Tab, so it costs the reader nothing. */
+                tabIndex: -1, 
+                /* Where the finger has it, and no easing while the finger is there: the generated rule
+                   carries a 300ms ease-out, which applied to every move would leave the sheet trailing
+                   a third of a second behind the hand. The duration is the token that means "does not
+                   animate at all" rather than a number written here, and it is gone the moment the
+                   gesture is — so the stylesheet resumes owning both the position and the reduced-motion
+                   guard that comes with it. */
+                style: pulled === null
+                    ? undefined
+                    : { translate: `0 ${pulled}%`, transitionDuration: 'var(--motion-duration-instant)' }, children: _jsxs("div", { className: bottomSheetParts.surface, ...dragging, children: [showHandle ? (_jsx("div", { className: bottomSheetParts.handle, "aria-hidden": "true" })) : null, _jsxs("header", { className: bottomSheetParts.header, children: [goesBack ? _jsx("div", { className: bottomSheetParts.leading, children: back }) : null, _jsxs("div", { className: bottomSheetParts.heading, children: [_jsx("h2", { className: bottomSheetParts.title, id: titleId, style: showTitle ? undefined : visuallyHidden, children: title }), describes ? (_jsx("p", { className: bottomSheetParts.description, id: descriptionId, children: description })) : null] }), trails ? (_jsxs("div", { className: bottomSheetParts.trailing, children: [action, showClose ? close : null] })) : null] }), _jsx("div", { ref: body, className: bottomSheetParts.body, children: children })] }) })] }));
+}

package/dist/components/core/bottom-sheet/BottomSheet.types.d.ts

@@ -0,0 +1,67 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface BottomSheetOwnProps {
+    /** The sheet is showing. The consumer owns this outright — the sheet never sets it, and asks to be closed through onOpenChange instead.
+  
+  Flipping it is the whole animation. The layer fades from opacity.hidden and the sheet scales up from motion.scale.enter about its own bottom edge, over motion.duration.slow on motion.easing.enter, so it reads as rising from the screen's edge rather than appearing over the middle of it. Shutting is not animated: transition-duration is motion.duration.instant while closed, because the reader has already asked to be somewhere else. Do not write a transition of your own — the stylesheet declares transition-property from what this axis changes, and a second declaration would both override that list and escape the prefers-reduced-motion guard generated with it. */
+    open?: boolean;
+    /** Always. It is the sheet's accessible name as well as its heading, so a sheet without one is announced as a dialog and nothing else. A noun phrase naming the task, in sentence case: "Filter results", not "Would you like to filter these results?" */
+    title: string;
+    /** The default, and almost always right. Turn it off where the content immediately under the header already names the task and a second visible name would say it twice — a picker whose first row is the heading, a sheet that is one photograph. The title is still rendered and still announced either way; only its pixels go. */
+    showTitle?: boolean;
+    /** The title needs qualifying — what the task applies to, or what it still needs before it can be done. "Date and both airports required", or the account a transfer is coming from. It sits directly under the title and is announced with it. */
+    description?: string;
+    /** The sheet is a step rather than the whole task — one of a sequence, or a panel reached from another panel — and the reader needs the step before it. One control, icon-only, at the leading edge above the sheet, opposite the way out.
+  
+  It is your ButtonIcon, so the glyph and the variant are yours; secondary is what sits level with the close button. The size is not — see below.
+  
+  It does not close the sheet and is not reported through onOpenChange: going back is the consumer's own navigation between whatever the sheet is showing, and a sheet that treated it as a way out would throw the task away on the one press that meant "not this bit". */
+    back?: ReactNode;
+    /** The screen needs one more control above the sheet — a confirm for a form the sheet is collecting, help for a task that needs explaining. One control, icon-only, at the trailing end beside the way out and immediately before it: the close button keeps the corner, and this sits inside it.
+  
+  It is your ButtonIcon, so its variant is yours: primary for a confirm that has to carry weight, destructive for one that removes something, secondary to sit level with the close. The size is not — see below.
+  
+  It asks for `showClose`, and the reason is the corner: an action alone at the trailing end sits exactly where a reader reaches for the exit, and is pressed by somebody who meant to leave. Where the sheet is a step in a sequence, the control that goes back belongs at the other end — that is `back`, not this. */
+    action?: ReactNode;
+    /** Always. The sheet does not close itself, so this is the only way out — write the first argument straight back to `open`. Named the way DropdownMenu names its own, because a reader who has wired one controlled disclosure in this package should not have to learn a second word for the same job.
+  
+  The second argument is which of the four ways out the reader took, for a page that treats an abandoned task differently from a finished one. It is only ever called with false today — a sheet is opened by whatever opens it, never by itself — and the boolean is first anyway, so the shape does not have to change if that ever stops being true. */
+    onOpenChange: (open: boolean, reason: 'close-button' | 'scrim' | 'escape' | 'drag') => void;
+    /** Allowed: any content */
+    children: ReactNode;
+}
+export type BottomSheetProps = BottomSheetOwnProps & Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'open' | 'height' | 'title' | 'showTitle' | 'description' | 'showClose' | 'back' | 'action' | 'showHandle' | 'onOpenChange'> & ({
+    showHandle?: boolean;
+    showClose?: false;
+} | {
+    showHandle: false;
+    showClose?: boolean;
+}) & ({
+    height?: 'hug' | 'tall' | 'full';
+    showClose: true;
+} | {
+    height?: Exclude<'hug' | 'tall' | 'full', 'full'>;
+    showClose?: boolean;
+});
+/** The class each part carries. Apply these — do not retype them. */
+export declare const bottomSheetParts: {
+    readonly root: "dds-bottomsheet";
+    readonly scrim: "dds-bottomsheet__scrim";
+    readonly frame: "dds-bottomsheet__frame";
+    readonly surface: "dds-bottomsheet__surface";
+    readonly handle: "dds-bottomsheet__handle";
+    readonly header: "dds-bottomsheet__header";
+    readonly leading: "dds-bottomsheet__leading";
+    readonly heading: "dds-bottomsheet__heading";
+    readonly title: "dds-bottomsheet__title";
+    readonly trailing: "dds-bottomsheet__trailing";
+    readonly description: "dds-bottomsheet__description";
+    readonly body: "dds-bottomsheet__body";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const bottomSheetDefaults: {
+    readonly open: false;
+    readonly height: "hug";
+    readonly showTitle: true;
+    readonly showClose: false;
+    readonly showHandle: true;
+};

package/dist/components/core/bottom-sheet/BottomSheet.types.js

@@ -0,0 +1,18 @@
+// GENERATED from bottom-sheet.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const bottomSheetParts = {
+    root: 'dds-bottomsheet',
+    scrim: 'dds-bottomsheet__scrim',
+    frame: 'dds-bottomsheet__frame',
+    surface: 'dds-bottomsheet__surface',
+    handle: 'dds-bottomsheet__handle',
+    header: 'dds-bottomsheet__header',
+    leading: 'dds-bottomsheet__leading',
+    heading: 'dds-bottomsheet__heading',
+    title: 'dds-bottomsheet__title',
+    trailing: 'dds-bottomsheet__trailing',
+    description: 'dds-bottomsheet__description',
+    body: 'dds-bottomsheet__body',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const bottomSheetDefaults = { open: false, height: 'hug', showTitle: true, showClose: false, showHandle: true };

package/dist/components/core/bottom-sheet/bottom-sheet-impl.css

@@ -0,0 +1,57 @@
+/*
+ * 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.
+ */
+
+/*
+ * Above the page this interrupts, which a contract cannot hold either: an integer with no unit.
+ *
+ * The root is `position: fixed; inset: 0` and carried no z-index at all, on the assumption that a
+ * sheet is the last thing in the document and painting order alone puts it over the page. Two
+ * components already documented that assumption failing rather than fixing it: DatePicker and
+ * DateRangePicker mount a sheet in the middle of a form, and both had to mark their own root and
+ * lift it from their own stylesheet, because a fixed box at `z-index: auto` loses to any
+ * positioned element after it — the next field down painted straight through the sheet.
+ *
+ * That workaround was the sheet's bug being paid for by its callers, and every future caller
+ * would have paid it again. `layer.overlay` puts the order where the thing being ordered is.
+ * The two pickers still lift their fields — a host that has to sit at the overlay's level so the
+ * overlay inside it is not trapped below what follows — but they now read the same role rather
+ * than a literal, so the two can no longer drift apart.
+ *
+ * The role for anything that interrupts the reader, which today is this alone: nothing should outrank
+ * another by an accident of stylesheet order. Whatever reports from elsewhere would sit above it at
+ * `layer.notification`.
+ */
+:where([data-dds-context="marketing"]) .dds-bottomsheet {
+  z-index: var(--layer-overlay);
+}
+
+/*
+ * The title centres when there is a way back at the leading end, and ranges to the start when
+ * there is not.
+ *
+ * Which is a relationship rather than a prop, and so cannot be a binding: what decides it is
+ * whether the header holds a leading end, and `back` is a slot the page fills rather than a value
+ * the contract can switch on. `:has()` asks the question directly — the same kind of positional
+ * fact the head of a table asks about its second row.
+ *
+ * It is worth the asymmetry because the two rows are different objects. With a control at each
+ * end the header reads as a bar between them, and a title ranged to one edge sits against a button
+ * rather than in the row. With nothing at the leading end there is no bar to be between: a centred
+ * title would float with the whole left of the row empty behind it, which reads as a mistake.
+ *
+ * It centres in the space the ends leave rather than on the sheet, which is off true by half the
+ * difference between them. That is the honest limit of doing this in flow, and it is small where
+ * it applies — a row with a way back has a control at both ends, and the two are close to the same
+ * width. It was not small when the alignment was a prop that could be asked for on a row with one
+ * end, which is why that prop is gone.
+ */
+:where([data-dds-context="marketing"]) .dds-bottomsheet__header:has(.dds-bottomsheet__leading) .dds-bottomsheet__title,
+:where([data-dds-context="marketing"]) .dds-bottomsheet__header:has(.dds-bottomsheet__leading) .dds-bottomsheet__description {
+  text-align: center;
+}

package/dist/components/core/breadcrumb/Breadcrumb.css

@@ -0,0 +1,19 @@
+/* GENERATED from breadcrumb.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-breadcrumb .dds-breadcrumb__list {
+  align-items: center;
+  display: flex;
+  flex-wrap: wrap;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  gap: var(--space-gap-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-breadcrumb .dds-breadcrumb__separator {
+  align-items: center;
+  display: flex;
+  flex: none;
+  color: var(--color-fg-tertiary);
+}
+

package/dist/components/core/breadcrumb/Breadcrumb.d.ts

@@ -0,0 +1,16 @@
+import './Breadcrumb.css';
+import { type BreadcrumbProps } from './Breadcrumb.types.js';
+export type { BreadcrumbProps };
+/**
+ * A `<nav>` holding an ordered list of the levels above the current page.
+ *
+ * The separators are this component's, not the item's. An item cannot know
+ * whether it is first, so a chevron it rendered for itself would either need its
+ * position passed in or a `li + li` selector, which the generated stylesheet
+ * has no way to express. Interleaving here keeps both problems out of
+ * BreadcrumbItem and out of the CSS.
+ *
+ * Each separator is its own `<li>` because an `<ol>` may contain nothing else,
+ * and it is `aria-hidden` because it is punctuation.
+ */
+export declare function Breadcrumb({ label, children, ...rest }: BreadcrumbProps): import("react").JSX.Element;

package/dist/components/core/breadcrumb/Breadcrumb.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, Fragment } from 'react';
+import { ChevronRightRegularIcon } from '@deriv-com/quill-icons-web';
+import { Icon } from '../icon/Icon.js';
+import './Breadcrumb.css';
+import { breadcrumbDefaults, breadcrumbParts } from './Breadcrumb.types.js';
+/**
+ * A `<nav>` holding an ordered list of the levels above the current page.
+ *
+ * The separators are this component's, not the item's. An item cannot know
+ * whether it is first, so a chevron it rendered for itself would either need its
+ * position passed in or a `li + li` selector, which the generated stylesheet
+ * has no way to express. Interleaving here keeps both problems out of
+ * BreadcrumbItem and out of the CSS.
+ *
+ * Each separator is its own `<li>` because an `<ol>` may contain nothing else,
+ * and it is `aria-hidden` because it is punctuation.
+ */
+export function Breadcrumb({ label = breadcrumbDefaults.label, children, ...rest }) {
+    const levels = Children.toArray(children);
+    return (_jsx("nav", { className: breadcrumbParts.root, "aria-label": label, ...rest, children: _jsx("ol", { className: breadcrumbParts.list, children: levels.map((level, index) => (_jsxs(Fragment, { children: [index > 0 && (_jsx("li", { className: breadcrumbParts.separator, "aria-hidden": "true", children: _jsx(Icon, { size: "xs", children: _jsx(ChevronRightRegularIcon, {}) }) })), level] }, index))) }) }));
+}

package/dist/components/core/breadcrumb/Breadcrumb.types.d.ts

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface BreadcrumbOwnProps {
+    /** Always, and the default is almost always right. It names the landmark rather than the page — a screen reader user listing the landmarks on a page hears this, and "Breadcrumb" is the word they are listening for */
+    label?: string;
+    /** Allowed: BreadcrumbItem */
+    children: ReactNode;
+}
+export type BreadcrumbProps = BreadcrumbOwnProps & Omit<HTMLAttributes<HTMLElement>, 'className' | 'label'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const breadcrumbParts: {
+    readonly root: "dds-breadcrumb";
+    readonly list: "dds-breadcrumb__list";
+    readonly separator: "dds-breadcrumb__separator";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const breadcrumbDefaults: {
+    readonly label: "Breadcrumb";
+};

package/dist/components/core/breadcrumb/Breadcrumb.types.js

@@ -0,0 +1,9 @@
+// GENERATED from breadcrumb.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const breadcrumbParts = {
+    root: 'dds-breadcrumb',
+    list: 'dds-breadcrumb__list',
+    separator: 'dds-breadcrumb__separator',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const breadcrumbDefaults = { label: 'Breadcrumb' };

package/dist/components/core/breadcrumb-item/BreadcrumbItem.css

@@ -0,0 +1,34 @@
+/* GENERATED from breadcrumbitem.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-breadcrumbitem {
+  align-items: center;
+  display: flex;
+  font-family: var(--font-label-sm-family);
+  font-size: var(--font-label-sm-size);
+  letter-spacing: var(--font-label-sm-letter-spacing);
+  line-height: var(--font-label-sm-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-breadcrumbitem .dds-breadcrumbitem__link {
+  outline-style: solid;
+  text-decoration-line: none;
+  border-radius: var(--radius-subtle);
+  color: var(--color-fg-muted);
+  font-weight: var(--font-body-sm-weight);
+  outline-width: var(--border-width-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-breadcrumbitem .dds-breadcrumbitem__current {
+  color: var(--color-fg-default);
+  font-weight: var(--font-label-sm-weight);
+}
+
+:where([data-dds-context="marketing"]) .dds-breadcrumbitem .dds-breadcrumbitem__link:hover {
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-breadcrumbitem .dds-breadcrumbitem__link:focus-visible {
+  outline-color: var(--color-border-focus);
+  outline-width: var(--border-width-focus);
+}
+

package/dist/components/core/breadcrumb-item/BreadcrumbItem.d.ts

@@ -0,0 +1,12 @@
+import './BreadcrumbItem.css';
+import { type BreadcrumbItemProps } from './BreadcrumbItem.types.js';
+export type { BreadcrumbItemProps };
+/**
+ * One level of a trail: a link back to it, or the current page as plain text.
+ *
+ * `current` wins over `href`. The two together ask for a link from the page to
+ * itself — a tab stop that goes nowhere — so the component declines.
+ *
+ * `aria-current="page"` is what identifies the current level to a screen reader.
+ */
+export declare function BreadcrumbItem({ label, href, current, ...rest }: BreadcrumbItemProps): import("react").JSX.Element;