@deriv-com/dds-marketing 0.1.0 → 1.0.0

package/dist/components/core/pagination/Pagination.js

@@ -0,0 +1,366 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeftRegularIcon, ChevronRightRegularIcon, EllipsisRegularIcon } from '@deriv-com/quill-icons-web';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { DropdownMenu } from '../dropdown-menu/DropdownMenu.js';
+import { Icon } from '../icon/Icon.js';
+import { MenuItem } from '../menu-item/MenuItem.js';
+import './Pagination.css';
+// Second, and it adds rather than corrects: the row stops clipping while a break's menu is
+// open, which is a rule about two elements and cannot be a binding.
+import './pagination-impl.css';
+import { paginationDefaults, paginationParts } from './Pagination.types.js';
+/**
+ * The glyph inside a step control.
+ *
+ * A constant rather than a map, the size axis having gone: there is one control measure
+ * here and so one mark that fits it. Written down rather than left to the glyph because a
+ * raw Quill icon ships its own width and height, and passing one straight through is how a
+ * step draws at the wrong size while every gate still passes.
+ */
+const GLYPH_SIZE = 'xs';
+/**
+ * The most pages a break will offer in one menu.
+ *
+ * Fifty rows already outruns the surface and scrolls, which is the point at which a list stops
+ * being read and starts being searched — and a break in a set of five thousand stands for nearly
+ * all of them, so there is no length at which listing the run whole is honest. Past this the menu
+ * lists an evenly spaced sample of the run instead: the reader lands near the page they were after,
+ * and the break beside where they land stands for a shorter run and so steps through it more finely.
+ */
+const JUMP_LIMIT = 50;
+/**
+ * The pages a break stands for, read off the numbers either side of it.
+ *
+ * The break itself carries no range. It does not need to: a gap sits between two numbered slots by
+ * construction, and everything between those two numbers is exactly what the row had no room to
+ * draw — so the range is a fact about the row rather than about the slot, and deriving it here is
+ * what keeps it true however the window arithmetic changes.
+ */
+function hidden(before, after) {
+    if (typeof before !== 'number' || typeof after !== 'number')
+        return [];
+    const from = before + 1;
+    const length = after - from;
+    if (length <= 0)
+        return [];
+    if (length <= JUMP_LIMIT)
+        return Array.from({ length }, (_, index) => from + index);
+    // Both ends of the run included, and evenly spaced between them. The stride is greater than one
+    // by definition here — the run is longer than the limit — so no two indexes can round onto the
+    // same page and the result is strictly increasing without being deduplicated.
+    const stride = (length - 1) / (JUMP_LIMIT - 1);
+    return Array.from({ length: JUMP_LIMIT }, (_, index) => from + Math.round(index * stride));
+}
+/**
+ * The pages worth showing, and where the row breaks.
+ *
+ * The first and last page are always offered, because they are the two a reader asks for
+ * by name — the start of the set and the end of it — and neither is reachable by stepping
+ * without pressing as many times as there are pages. Everything between is the window
+ * `siblingCount` opens around where the reader currently stands.
+ *
+ * The window is split rather than mirrored, and the odd one goes after the current page
+ * because forward is the direction the reader is travelling. At the default of one that
+ * makes the window the current page and the page after it, which is a row of six — and it
+ * holds the current page at the same place in that row on every page of the middle band,
+ * so the highlighted target stays put as the reader steps.
+ *
+ * The row holds the same number of targets on every page, which is why the arithmetic is
+ * shaped this way rather than the shorter form. That form let the ends of the set truncate
+ * the window, so a set of eight drew four targets on the first page and seven in the
+ * middle — and since the row is centred, those extra targets pushed both step controls
+ * outwards under the hand that had just pressed one.
+ *
+ * A break is drawn only where it stands for more than the page it replaced: `start > 3`
+ * means at least two pages sit unshown, and where only one does the row shows that page
+ * instead. An ellipsis occupying the width of the single page it names is punctuation that
+ * costs what it saves.
+ */
+function slots(current, last, siblings) {
+    const width = siblings + 5;
+    const before = Math.floor(siblings / 2);
+    const after = siblings - before;
+    const run = (from, to) => Array.from({ length: Math.max(0, to - from + 1) }, (_, index) => from + index);
+    if (last <= width)
+        return run(1, last);
+    const start = Math.max(2, current - before);
+    const end = Math.min(last - 1, current + after);
+    if (start <= 3)
+        return [...run(1, width - 2), 'gap', last];
+    if (end >= last - 2)
+        return [1, 'gap', ...run(last - width + 3, last)];
+    return [1, 'gap', ...run(start, end), 'gap', last];
+}
+/**
+ * What the row has to work with, measured, or null where there is nothing to measure.
+ *
+ * `overflowing` is the signal the decision hangs on, rather than a comparison of the room
+ * against the row's width. A `<nav>` in a block container takes the width it is given; a
+ * `<nav>` that is a flex item — a pagination row centred in a footer, which is most of
+ * them — is sized to its own contents instead, so `clientWidth` there is what the row
+ * already takes rather than what it may have. The list, though, only shrinks below its
+ * contents when something has constrained it, so its overflow is the one honest report of
+ * not fitting.
+ *
+ * Null where nothing can be measured. A width of zero is what an element out of the layout
+ * reports, and what jsdom reports for everything.
+ */
+function measurements(root, list) {
+    const rowGap = Number.parseFloat(getComputedStyle(root).columnGap) || 0;
+    const slotGap = Number.parseFloat(getComputedStyle(list).columnGap) || 0;
+    const steps = Array.from(root.children)
+        .filter((child) => child !== list)
+        .reduce((total, child) => total + child.offsetWidth + rowGap, 0);
+    const room = root.clientWidth - steps;
+    const widest = Array.from(list.children).reduce((most, child) => Math.max(most, child.offsetWidth), 0);
+    if (room <= 0 || widest <= 0)
+        return null;
+    return {
+        room,
+        holds: Math.floor((room + slotGap) / (widest + slotGap)),
+        // A pixel of tolerance, because a fractional layout rounds one way in the scroll width
+        // and the other in the client width.
+        overflowing: list.scrollWidth > list.clientWidth + 1,
+    };
+}
+/**
+ * What the readout says under compact: a bare position, and the terseness is the point rather
+ * than a saving — the variant is chosen for a place with no width.
+ */
+function readout(current, last) {
+    return `${String(current)} / ${String(last)}`;
+}
+/**
+ * A `<nav>` holding the ways through a set that has been divided into pages.
+ *
+ * Nothing about the reader's position is held here. `page` is the consumer's, because the
+ * results above this control are theirs too, and the two are one fact — a component keeping
+ * its own copy is how a row of numbers comes to disagree with what it describes.
+ *
+ * The one thing it does hold is how much of the window there is room for, which is not the
+ * reader's position but the container's width, and is a fact no consumer can pass because
+ * only the row can see it.
+ *
+ * Every control in the row is drawn here rather than borrowed, which is where this parts
+ * company with product's. There the steps are ButtonIcons and the numbered pages are
+ * Buttons; this package's ButtonIcon has no disabled state and says so in its own source,
+ * being a family of links, and a step at the end of the set has to be disabled rather than
+ * removed. Its Button was an anchor with a required href when this was built, and it has no quiet
+ * form, so a row of
+ * page numbers built from it would be a row of calls to action. Both are correct decisions
+ * for what those components are, and neither leaves anything to borrow.
+ *
+ * What a press is depends on the variant, and on `pageHref`. Given it, every route to a
+ * page is an anchor — the numbered targets and both steps — which is what gives a visitor
+ * cmd-click, a destination in the status bar and a link a crawler can follow. Without it
+ * they are buttons reporting through `onPageChange`.
+ */
+export function Pagination({ variant = paginationDefaults.variant, page = paginationDefaults.page, totalPages = paginationDefaults.totalPages, onPageChange, pageHref, siblingCount = paginationDefaults.siblingCount, label = paginationDefaults.label, previousLabel = paginationDefaults.previousLabel, nextLabel = paginationDefaults.nextLabel, morePagesLabel = paginationDefaults.morePagesLabel, ...rest }) {
+    // Clamped rather than trusted. A page beyond the set is what a consumer holds for the
+    // moment between a filter narrowing the results and their own state catching up, and a
+    // row that renders nothing during it reads as the component breaking rather than as the
+    // data moving. Truncated because nothing downstream means anything at 3.5.
+    // Truncated because nothing downstream — an index, a label, a comparison — means anything at
+    // 3.5, and floored at a real number because nothing downstream survives NaN or Infinity either:
+    // a total arriving as Math.ceil(total / size) is NaN for exactly as long as `total` is undefined,
+    // and a row built from it draws a page numbered NaN beside two empty menus.
+    const whole = (value, floor) => (Number.isFinite(value) ? Math.max(floor, Math.trunc(value)) : floor);
+    const last = whole(totalPages, 1);
+    const current = Math.min(whole(page, 1), last);
+    const siblings = whole(siblingCount, 0);
+    const atStart = current <= 1;
+    const atEnd = current >= last;
+    const rootRef = useRef(null);
+    const listRef = useRef(null);
+    /**
+     * How many siblings the row is drawing, which is the consumer's number until the width
+     * says otherwise. Null means nothing has been decided, and it is what every row starts
+     * at: a row that opened at its shortest and grew a moment later would be a visible flinch
+     * on every mount, and most containers have the room.
+     */
+    const [fit, setFit] = useState(null);
+    const shown = fit === null ? siblings : Math.min(siblings, fit);
+    /**
+     * The room the row had when it last gave something up.
+     *
+     * Overflow is the only honest signal that the row does not fit, and a folded row does not
+     * overflow — so once folded, the row cannot tell from its own width whether the container
+     * has since grown. This remembers the width that forced it, and anything wider is worth
+     * trying the full window at again. Monotonic on purpose, so the two decisions cannot
+     * chase each other.
+     */
+    const foldedAt = useRef(Number.POSITIVE_INFINITY);
+    const measure = useCallback(() => {
+        const root = rootRef.current;
+        const list = listRef.current;
+        if (root === null || list === null)
+            return;
+        /*
+          Not while a break's menu is open. The rule that keeps that menu out of the list's
+          scrollable overflow takes the clip away for as long as it is up, and overflow is the only
+          honest report of not fitting — so a measurement taken now would read a row that cannot clip
+          as a row with room to spare, and give the window back into a container that never had space
+          for it.
+    
+          Read off the DOM rather than off state, which is where this parts company with product's.
+          There the row holds which break is open because it spends that state on the trigger's own
+          look — an open break keeps a container the way the current page does. Nothing here needs
+          that: the break is a part of ours and its open state is already on the element, published
+          by DropdownMenu as `aria-expanded`. Holding a second copy would be keeping a fact this
+          component does not own purely to answer one question. It is the same attribute the
+          stylesheet reads to stop the row clipping, so there is one source rather than two.
+        */
+        if (list.querySelector('[aria-expanded="true"]') !== null)
+            return;
+        const measured = measurements(root, list);
+        if (measured === null)
+            return;
+        if (measured.overflowing) {
+            // A row of `holds` slots carries holds - 5 siblings once the four fixed slots and the
+            // current page are paid for. Never more than was asked for: this decides what the
+            // width forbids and the consumer decides the rest. Where even none of them fits there
+            // is nothing left to give up that would not cost the reader the page they are on or an
+            // end of the set, so the list scrolls — which is the point at which the column wanted
+            // compact rather than numbers.
+            const afford = Math.max(0, measured.holds - 5);
+            if (afford < shown) {
+                foldedAt.current = measured.room;
+                setFit(afford);
+            }
+            return;
+        }
+        if (fit !== null && measured.room > foldedAt.current)
+            setFit(null);
+    }, [fit, shown]);
+    // Layout rather than a plain effect: between the two the browser would paint the full
+    // window in a container that cannot hold it, which is the clipped page for one frame.
+    useLayoutEffect(() => {
+        if (variant !== 'pages')
+            return;
+        measure();
+    }, [measure, variant, last, shown]);
+    /**
+     * The container changing width changes how much of the window there is room for.
+     *
+     * Absent where there is no ResizeObserver rather than fatal — the row keeps the window the
+     * last measurement allowed. jsdom is the environment that asks: the generated behaviour
+     * test runs there and reports every width as zero, which `measurements` declines to answer.
+     */
+    useEffect(() => {
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        if (variant !== 'pages')
+            return;
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(() => {
+            measure();
+        });
+        observer.observe(root);
+        return () => {
+            observer.disconnect();
+        };
+    }, [measure, variant]);
+    /**
+     * What a press means, in one place.
+     *
+     * An anchor needs none of this — the browser follows its href and nothing here runs. This is for
+     * the presses that are not anchors: every target when no pageHref was given, and the rows of a
+     * break's menu always, MenuItem taking no href of its own. Where a page has an address and the
+     * press cannot carry it, this is what walks the reader there.
+     */
+    const goTo = (to) => {
+        if (onPageChange !== undefined)
+            onPageChange(to);
+        else if (pageHref !== undefined)
+            window.location.assign(pageHref(to));
+    };
+    const go = (to) => () => {
+        goTo(to);
+    };
+    // The row as slots, held here rather than mapped inside the JSX, because the arithmetic
+    // is a fact about the row rather than about any one slot.
+    const row = variant === 'pages' ? slots(current, last, shown) : [];
+    /**
+     * One step control, which is an anchor where there is a page to point at and a button
+     * otherwise.
+     *
+     * At either end of the set there is no page, so it is a disabled `<button>` even in link
+     * mode — the one place the two modes meet, and the reason this is drawn here rather than
+     * taken from ButtonIcon: a link cannot be disabled, which is exactly why that component
+     * declines to offer it.
+     */
+    const stepControl = (to, name, disabled, glyph) => {
+        const mark = _jsx(Icon, { size: GLYPH_SIZE, children: glyph });
+        if (pageHref !== undefined && !disabled) {
+            return (_jsx("a", { className: paginationParts.step, href: pageHref(to), "aria-label": name, onClick: go(to), children: mark }));
+        }
+        return (_jsx("button", { className: paginationParts.step, type: "button", "aria-label": name, disabled: disabled, onClick: go(to), children: mark }));
+    };
+    return (_jsxs("nav", { ref: rootRef, className: paginationParts.root, "aria-label": label, "data-variant": variant, ...rest, children: [stepControl(current - 1, previousLabel, atStart, _jsx(ChevronLeftRegularIcon, {})), variant === 'pages' && (_jsx("div", { className: paginationParts.list, ref: listRef, children: row.map((slot, index) => {
+                    if (slot === 'gap') {
+                        const stands = row[index - 1];
+                        /*
+                          The break, which presses.
+          
+                          It was a span, and aria-hidden with it, on the argument that it names no page —
+                          true, and the wrong half of the fact. What it stands for is every page the row had
+                          no room to draw, which is exactly the set a reader who cannot see the page they
+                          want is after, and the row was making them walk there.
+          
+                          A trigger handed to DropdownMenu, which that component did not accept until this
+                          needed it — its own chevron note named an icon-only trigger as the case product has
+                          the prop for and said neither case existed here. The menu behind it is
+                          DropdownMenu's rather than a surface of ours: what happens when a menu opens, where
+                          focus goes, what Escape does and what the arrow keys move through is described
+                          once, in the component that exists to describe it.
+          
+                          No chevron: a passed trigger is drawn by whoever passed it, and a break wearing one
+                          would read as a control with a set of its own rather than as the pages between two
+                          numbers.
+          
+                          Keyed by the number in front of it rather than by its position in the row, so a
+                          break whose range changes under a fold is a different break and takes its open menu
+                          with it.
+                        */
+                        return (_jsx(DropdownMenu, { label: morePagesLabel, trigger: 
+                            /*
+                              This component's own button rather than a ButtonIcon, which is what it was
+                              until the row was looked at. Product's break is a transparent secondary
+                              ButtonIcon; nothing here is transparent — secondary paints a border — so the
+                              break wore a ring none of the numbers beside it wear and read as a different
+                              kind of thing in the row. DropdownMenu never asked for a ButtonIcon: it wires
+                              whatever element it is handed, so this is a plain button carrying the break
+                              part, and the part carries the same ground, corner and states as the page
+                              targets either side of it.
+                            */
+                            _jsx("button", { className: paginationParts.break, type: "button", "aria-label": morePagesLabel, children: _jsx(Icon, { size: GLYPH_SIZE, children: _jsx(EllipsisRegularIcon, {}) }) }), children: hidden(stands, row[index + 1]).map((to) => (_jsx(MenuItem, { onSelect: () => {
+                                    // The same split every other route to a page makes, and it has to be made
+                                    // here rather than by the row: MenuItem takes no href, so a menu row cannot
+                                    // be an anchor the way a numbered target is. Without this the menu reported
+                                    // to a handler the pages variant is not obliged to have — so in the
+                                    // configuration that variant is documented for, every row did nothing.
+                                    goTo(to);
+                                }, children: String(to) }, to))) }, `gap-${String(stands ?? index)}`));
+                    }
+                    const isCurrent = slot === current;
+                    // aria-current rather than aria-selected: these are destinations in a set of
+                    // pages, not options in a listbox, and "page" is the token that says so. The
+                    // current page's own target stays enabled and in the tab order — a reader who
+                    // lands on it should hear which page they are on, and pressing it is a harmless
+                    // no-op rather than a dead end.
+                    //
+                    // data-current beside it, saying the same thing to a different reader. The
+                    // generated stylesheet selects on the data attribute, so without it the rule
+                    // that fills the current page matches nothing and every number renders alike —
+                    // which is exactly what shipped until it was looked at. The contract keeps them
+                    // apart on purpose: what the current page announces and what it looks like are
+                    // two decisions, and one should not be able to silently change the other.
+                    if (pageHref !== undefined) {
+                        return (_jsx("a", { className: paginationParts.page, href: pageHref(slot), "aria-current": isCurrent ? 'page' : undefined, "data-current": isCurrent ? 'true' : undefined, onClick: go(slot), children: slot }, slot));
+                    }
+                    return (_jsx("button", { className: paginationParts.page, type: "button", "aria-current": isCurrent ? 'page' : undefined, "data-current": isCurrent ? 'true' : undefined, onClick: go(slot), children: slot }, slot));
+                }) })), variant === 'compact' && (_jsx("span", { className: paginationParts.summary, children: readout(current, last) })), stepControl(current + 1, nextLabel, atEnd, _jsx(ChevronRightRegularIcon, {}))] }));
+}

package/dist/components/core/pagination/Pagination.types.d.ts

@@ -0,0 +1,47 @@
+import type { HTMLAttributes } from 'react';
+export interface PaginationOwnProps {
+    /**
+     * `pages` — An index or archive whose pages have addresses of their own — a blog listing, a news archive, a resource library. The only variant offering a numbered target, so the only one on which reaching page fourteen costs a single press rather than thirteen, and the only one a crawler can follow past page one. It draws Buttons, which in this package are anchors, so it needs pageHref and the pages it points at have to exist as URLs. A page too far out to be drawn is still not a walk: the break between two runs of numbers presses, and offers the pages it stands for
+     * `compact` — A place with no room for a row of numbers — a card footer, a sidebar, a column at a phone's width. Position and the two steps, and nothing else. Like pages, its steps are anchors given pageHref and buttons without it
+     */
+    variant?: 'pages' | 'compact';
+    /** Always — it is which page is on screen, counting from one, and the component renders around it rather than holding it. The consumer owns this because the results do: the page number and the rows beneath it are one fact, and a control keeping its own copy is how the two come to disagree. The default is the first page, which is where a set with nothing said about it starts */
+    page?: number;
+    /** How many pages the set has been divided into. It decides where the row ends, when the ellipsis appears, and when next goes disabled. The default of one is the honest answer for a set nothing has been said about, and it is also the case the component should not be used in at all — a single page has nothing to move between */
+    totalPages?: number;
+    /** What the page does when the reader asks for another one, counting from one. Required wherever the route to a page is a press rather than a destination: the numbered targets and the steps under any variant given no pageHref. Under pages it is the pageHref that carries the reader, so this is the reporting half rather than the moving one — useful for telling analytics, and unnecessary if nothing is listening. One of this and pageHref is needed; a component given neither draws a row nothing can move. */
+    onPageChange?: (page: number) => void;
+    /** The address of a page, given the page number. Passing it makes every route to a page an anchor: the numbered targets, and both steps. Required under the pages variant, which draws Buttons — and a Button in this package is an anchor with a destination, never a press the page handles. Pass it under compact too wherever the pages have real URLs, because an anchor is what gives a visitor cmd-click, a destination in the status bar, and a link a search engine can follow to page two. One of this and onPageChange is needed; a component given neither draws a row nothing can move. */
+    pageHref?: (page: number) => string;
+    /** How many numbered pages sit around the current one before the row breaks, under the pages variant. Around rather than either side: the window is split, with the odd one going forward, since the page the reader has not read is the one they most likely want. One is the current page and the one after it, a row of six; two is mirrored. The most it will show rather than a promise, since the row drops what the container cannot hold */
+    siblingCount?: number;
+    /** Always, and the default is almost always right. It names the landmark rather than the content — a screen reader user listing what is on a page hears this, and a nav with no name is one they cannot tell from the page's other navigation. Set it where a page carries two of these, so the two are distinguishable by what they page through */
+    label?: string;
+    /** The accessible name for the step-back control, which is a glyph and therefore announces nothing on its own. Override it to translate it, or where "page" is the wrong noun for what is being stepped through */
+    previousLabel?: string;
+    /** The accessible name for the step-forward control, for the reason previousLabel exists. Keep the two parallel: a pair reading "Next page" and "Go back" is two people's wording in one control */
+    nextLabel?: string;
+    /** The accessible name for the break between two runs of numbered pages — the control that opens a menu of the pages that break stands for. A glyph announces nothing, which is the position previousLabel and nextLabel are in, and this is passed the same way the two steps' names are, as the control's own accessible name. It names the menu as well as the control, so a reader who has opened it hears which menu they are in */
+    morePagesLabel?: string;
+}
+export type PaginationProps = PaginationOwnProps & Omit<HTMLAttributes<HTMLElement>, 'className' | 'variant' | 'page' | 'totalPages' | 'onPageChange' | 'pageHref' | 'siblingCount' | 'label' | 'previousLabel' | 'nextLabel' | 'morePagesLabel'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const paginationParts: {
+    readonly root: "dds-pagination";
+    readonly list: "dds-pagination__list";
+    readonly summary: "dds-pagination__summary";
+    readonly step: "dds-pagination__step";
+    readonly page: "dds-pagination__page";
+    readonly break: "dds-pagination__break";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const paginationDefaults: {
+    readonly variant: "pages";
+    readonly page: 1;
+    readonly totalPages: 1;
+    readonly siblingCount: 1;
+    readonly label: "Pagination";
+    readonly previousLabel: "Previous page";
+    readonly nextLabel: "Next page";
+    readonly morePagesLabel: "More pages";
+};

package/dist/components/core/pagination/Pagination.types.js

@@ -0,0 +1,12 @@
+// GENERATED from pagination.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const paginationParts = {
+    root: 'dds-pagination',
+    list: 'dds-pagination__list',
+    summary: 'dds-pagination__summary',
+    step: 'dds-pagination__step',
+    page: 'dds-pagination__page',
+    break: 'dds-pagination__break',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const paginationDefaults = { variant: 'pages', page: 1, totalPages: 1, siblingCount: 1, label: 'Pagination', previousLabel: 'Previous page', nextLabel: 'Next page', morePagesLabel: 'More pages' };

package/dist/components/core/pagination/pagination-impl.css

@@ -0,0 +1,17 @@
+/*
+ * What the contract cannot hold, which here is one rule about two elements.
+ *
+ * The row of targets scrolls when it cannot fit, which is the last resort after giving up
+ * siblings — and a scroll container clips. A break's menu is drawn inside that container, so
+ * the clip that saves the row from a half-drawn page also takes the top off the menu. The
+ * two cannot both be bindings: a binding carries one token for one part in one state, and
+ * this is the list's overflow answering to a descendant's aria-expanded.
+ *
+ * `:has` rather than a class the component toggles, because the fact is already in the DOM.
+ * DropdownMenu publishes `aria-expanded` on whatever trigger it was given, so the row does
+ * not have to hold a second copy of a state it does not own — and a copy is what would drift
+ * the first time a menu shut by a route the row did not hear about.
+ */
+:where([data-dds-context="marketing"]) .dds-pagination .dds-pagination__list:has([aria-expanded='true']) {
+  overflow: visible;
+}

package/dist/components/core/pagination-dots/PaginationDots.css

@@ -0,0 +1,60 @@
+/* GENERATED from paginationdots.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-paginationdots {
+  align-items: center;
+  display: flex;
+  flex-direction: row;
+  column-gap: var(--space-gap-sm);
+}
+
+:where([data-dds-context="marketing"]) .dds-paginationdots .dds-paginationdots__dot {
+  transition-property: outline-color, outline-width;
+  align-items: center;
+  appearance: none;
+  background-color: transparent;
+  box-sizing: border-box;
+  color: inherit;
+  cursor: pointer;
+  display: flex;
+  justify-content: center;
+  outline-style: solid;
+  padding: 0;
+  border-radius: var(--radius-pill);
+  border-width: var(--border-width-none);
+  min-block-size: var(--size-target-min);
+  min-inline-size: var(--size-dot-diameter);
+  outline-width: var(--border-width-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-paginationdots .dds-paginationdots__mark {
+  transition-property: inline-size, opacity;
+  background-color: currentcolor;
+  display: block;
+  flex: none;
+  block-size: var(--size-dot-diameter);
+  border-radius: var(--radius-pill);
+  inline-size: var(--size-dot-diameter);
+  opacity: var(--opacity-dot-rest);
+  transition-duration: var(--motion-duration-slow);
+  transition-timing-function: var(--motion-easing-shift);
+}
+
+:where([data-dds-context="marketing"]) .dds-paginationdots .dds-paginationdots__dot:focus-visible {
+  outline-color: var(--color-border-focus);
+  outline-width: var(--border-width-focus);
+}
+
+:where([data-dds-context="marketing"]) .dds-paginationdots .dds-paginationdots__mark[data-current="true"] {
+  inline-size: var(--size-dot-current);
+  opacity: var(--opacity-dot-current);
+}
+
+:where([data-dds-context="marketing"]) .dds-paginationdots[data-variant="accent"] .dds-paginationdots__dot {
+  color: var(--color-fg-brand-accent);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) .dds-paginationdots,
+  :where([data-dds-context="marketing"]) .dds-paginationdots * { transition: none !important; }
+}
+

package/dist/components/core/pagination-dots/PaginationDots.d.ts

@@ -0,0 +1,25 @@
+import './PaginationDots.css';
+import { type PaginationDotsProps } from './PaginationDots.types.js';
+export type { PaginationDotsProps };
+/**
+ * A row of marks, one per position in a short sequence, every one a button that moves there — and,
+ * under `autoplay`, a row that moves on its own.
+ *
+ * Split out of Pagination, where it was a variant. A set of results and a slider's slides are
+ * different questions — how far does this run, against where am I — and the one variant that
+ * answered the second was the one that needed none of Pagination's other props. Steps are not
+ * here: whatever holds the row puts previous and next beside it, where its own layout wants them.
+ *
+ * Drawn in the ground's own ink. The marks are currentcolor, the rest at opacity.dot-rest and the
+ * current one solid and stretched to size.dot.current, so one row reads on any band without
+ * naming a colour.
+ *
+ * Nothing about position is held here: `page` is the consumer's, because the slide in view is
+ * theirs too, and the two are one fact. Autoplay therefore moves nothing itself — every
+ * motion.duration.dwell it reports the next position through onPageChange and waits for `page` to
+ * come back. A reader who presses a mark stops it for good. It holds while `paused` says so — the
+ * holder's hover, focus, or its own stop — and never moves for a reader who asked for less motion.
+ * There is no pause control, by decision: a press is the way to stop it, and the contract says what
+ * that does and does not give WCAG 2.2.2.
+ */
+export declare function PaginationDots({ variant, page, totalPages, onPageChange, autoplay, paused, label, itemLabel, }: PaginationDotsProps): import("react").JSX.Element;

package/dist/components/core/pagination-dots/PaginationDots.js

@@ -0,0 +1,104 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import './PaginationDots.css';
+import { paginationDotsDefaults, paginationDotsParts, } from './PaginationDots.types.js';
+/**
+ * The most marks the row will draw.
+ *
+ * A guard rather than a design threshold — the row is for a handful, and its guidance says so.
+ * What it guards against is a total wired straight from a result count: five thousand of them
+ * built five thousand buttons and took the page with it. Past this the marks give way to the
+ * position written as numbers, which a reader can see, where an empty row would read as broken.
+ */
+const DOT_LIMIT = 20;
+/**
+ * A CSS time as milliseconds, the unit read rather than assumed: the same token arrives as `5000ms`
+ * from a dev server and `5s` once a minifier has been over it. Null for anything else, so the row
+ * holds still rather than inventing a timing.
+ */
+function milliseconds(value) {
+    const time = value.trim();
+    const amount = Number.parseFloat(time);
+    if (!Number.isFinite(amount))
+        return null;
+    if (/ms$/i.test(time))
+        return amount;
+    if (/s$/i.test(time))
+        return amount * 1000;
+    return null;
+}
+/**
+ * Whether the reader has asked for less motion, kept current if they change it. Until it has been
+ * read — on the server, before the first effect — the answer is yes, the safe one: a row that
+ * starts still and then moves is better than one that moves for a frame for a reader who said not to.
+ */
+function usePrefersLessMotion() {
+    const [less, setLess] = useState(true);
+    useEffect(() => {
+        if (typeof window.matchMedia !== 'function')
+            return;
+        const query = window.matchMedia('(prefers-reduced-motion: reduce)');
+        const update = () => setLess(query.matches);
+        update();
+        query.addEventListener('change', update);
+        return () => query.removeEventListener('change', update);
+    }, []);
+    return less;
+}
+/**
+ * A row of marks, one per position in a short sequence, every one a button that moves there — and,
+ * under `autoplay`, a row that moves on its own.
+ *
+ * Split out of Pagination, where it was a variant. A set of results and a slider's slides are
+ * different questions — how far does this run, against where am I — and the one variant that
+ * answered the second was the one that needed none of Pagination's other props. Steps are not
+ * here: whatever holds the row puts previous and next beside it, where its own layout wants them.
+ *
+ * Drawn in the ground's own ink. The marks are currentcolor, the rest at opacity.dot-rest and the
+ * current one solid and stretched to size.dot.current, so one row reads on any band without
+ * naming a colour.
+ *
+ * Nothing about position is held here: `page` is the consumer's, because the slide in view is
+ * theirs too, and the two are one fact. Autoplay therefore moves nothing itself — every
+ * motion.duration.dwell it reports the next position through onPageChange and waits for `page` to
+ * come back. A reader who presses a mark stops it for good. It holds while `paused` says so — the
+ * holder's hover, focus, or its own stop — and never moves for a reader who asked for less motion.
+ * There is no pause control, by decision: a press is the way to stop it, and the contract says what
+ * that does and does not give WCAG 2.2.2.
+ */
+export function PaginationDots({ variant = paginationDotsDefaults.variant, page = paginationDotsDefaults.page, totalPages = paginationDotsDefaults.totalPages, onPageChange, autoplay = paginationDotsDefaults.autoplay, paused = paginationDotsDefaults.paused, label = paginationDotsDefaults.label, itemLabel = paginationDotsDefaults.itemLabel, }) {
+    const count = Math.max(0, Math.floor(totalPages));
+    const current = Math.min(Math.max(1, Math.floor(page)), Math.max(1, count));
+    const root = useRef(null);
+    const lessMotion = usePrefersLessMotion();
+    /*
+      Stopped for good once the reader presses a mark. A reader who chose a position has said where
+      they want to be, and moving them on from it five seconds later would take that back — the WAI
+      carousel pattern's rule, and the way this row offers a reader a stop without a control for it.
+    */
+    const [stopped, setStopped] = useState(false);
+    const running = autoplay && !stopped && !paused && !lessMotion && count > 1 && onPageChange !== undefined;
+    // Read through a ref so a new handler on every render does not re-arm the timer.
+    const report = useRef(onPageChange);
+    report.current = onPageChange;
+    useEffect(() => {
+        if (!running || root.current === null)
+            return;
+        const dwell = milliseconds(getComputedStyle(root.current).getPropertyValue('--motion-duration-dwell'));
+        if (dwell === null)
+            return;
+        const timer = window.setTimeout(() => report.current?.((current % count) + 1), dwell);
+        return () => window.clearTimeout(timer);
+    }, [running, current, count]);
+    if (count > DOT_LIMIT) {
+        return (_jsx("div", { className: paginationDotsParts.root, "data-variant": variant, role: "group", "aria-label": label, ref: root, children: _jsx("span", { role: "status", children: `${String(current)} / ${String(count)}` }) }));
+    }
+    return (_jsx("div", { className: paginationDotsParts.root, "data-variant": variant, role: "group", "aria-label": label, ref: root, children: Array.from({ length: count }, (_, index) => index + 1).map((at) => {
+            const here = at === current;
+            return (_jsx("button", { type: "button", className: paginationDotsParts.dot, "aria-label": `${itemLabel} ${String(at)}`, "aria-current": here ? 'true' : undefined, onClick: () => {
+                    setStopped(true);
+                    onPageChange?.(at);
+                }, children: _jsx("span", { className: paginationDotsParts.mark, "data-current": here ? 'true' : undefined }) }, at));
+        }) }));
+}