@deriv-com/dds-marketing 0.1.0 → 0.2.0

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

@@ -0,0 +1,406 @@
+'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 marks the dots variant will draw.
+ *
+ * Twice the set size the variant asks for, so nothing anyone should be using it on comes
+ * near it. It is a guard rather than a design threshold: the marks are decoration, and one
+ * target per page meant a total wired straight from a result count built that many
+ * controls and took the page with it. Past this the marks give way to the readout in
+ * words, which is a degrade a reader can see — an empty row is not one.
+ */
+const DOT_LIMIT = 20;
+/**
+ * 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, which depends on how much the consumer knows.
+ *
+ * A range against a total is the better sentence and the one the count variant exists for,
+ * but it needs both halves: `pageSize` to know how wide a page is, and `totalItems` to know
+ * what it is a fraction of. Given one without the other it falls back to counting pages
+ * rather than guessing — a total this component invented would be indistinguishable, to the
+ * reader, from one the consumer supplied.
+ *
+ * The upper bound is clamped to the total because the last page is rarely full: 24 pages of
+ * 10 across 235 items ends at 235, and a readout claiming 240 of 235 is arithmetic the
+ * reader can see is wrong.
+ */
+function readout(variant, current, last, totalItems, pageSize) {
+    // Compact is a bare position, and the terseness is the point rather than a saving: the
+    // variant is chosen for a place with no width. It is also what keeps the two readouts
+    // from being the same sentence, count falling back to counting pages when it has no total.
+    if (variant === 'compact')
+        return `${String(current)} / ${String(last)}`;
+    if (totalItems === undefined || pageSize === undefined) {
+        return `Page ${String(current)} of ${String(last)}`;
+    }
+    const from = (current - 1) * pageSize + 1;
+    const to = Math.min(current * pageSize, totalItems);
+    return `${String(from)}–${String(to)} of ${String(totalItems)}`;
+}
+/**
+ * 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 is an anchor with a required href and 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`. The marks under `dots` are always
+ * buttons: a slide has no address.
+ */
+export function Pagination({ variant = paginationDefaults.variant, showSteps = paginationDefaults.showSteps, page = paginationDefaults.page, totalPages = paginationDefaults.totalPages, onPageChange, pageHref, totalItems, pageSize, 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;
+    /*
+      Whether the steps are drawn, which is showSteps under dots and true everywhere else.
+  
+      Inert outside dots rather than obeyed, in the way this component's other
+      variant-specific props already are. What makes dots the exception is that its middle is
+      the only one holding targets of its own — every position is a mark and every mark is a
+      button — so the row still works when the steps go. Under count and compact the steps are
+      the whole of what there is to press, and under pages the numbers reach the two ends and
+      the window between them, with stepping the way to anything else.
+    */
+    const steps = variant === 'dots' ? showSteps : true;
+    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
+            // count or 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, "data-show-steps": showSteps, ...rest, children: [steps && 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 === 'dots' && (_jsx("div", { className: paginationParts.list, ref: listRef, children: last <= DOT_LIMIT ? (Array.from({ length: last }, (_, index) => index + 1).map((to) => (_jsx("button", { className: paginationParts.dot, type: "button", "aria-label": `Page ${String(to)}`, "aria-current": to === current ? 'page' : undefined, "data-current": to === current ? 'true' : undefined, onClick: go(to), children: _jsx("span", { className: paginationParts['dot-mark'] }) }, to)))) : (_jsx("span", { className: paginationParts.summary, children: readout('count', current, last, totalItems, pageSize) })) })), (variant === 'count' || variant === 'compact') && (_jsx("span", { className: paginationParts.summary, children: readout(variant, current, last, totalItems, pageSize) })), steps && stepControl(current + 1, nextLabel, atEnd, _jsx(ChevronRightRegularIcon, {}))] }));
+}

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

@@ -0,0 +1,59 @@
+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
+     * `count` — A long set where the reader's real question is how much is left rather than which page they are on — "page 3" says nothing until you know whether there are four pages or four hundred. Pass totalItems so the readout can answer it. The steps take pageHref where the pages have addresses and fall back to onPageChange where they do not
+     * `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 count, its steps are anchors given pageHref and buttons without it
+     * `none` — The two steps and nothing between them, for a place where position is either obvious or beside the point — a lightbox moving through images, a set of two. It is the least this component can be, and choosing it is a claim that the reader does not need to know where they are, which on a page with an address per position is a claim worth making deliberately
+     * `dots` — A carousel of cards, a testimonial slider, a walkthrough — a short visual sequence where the reader cares where they are rather than what that position is called. The marks are always buttons and the press is always the page's to handle, a slide having no address to link to; pageHref is ignored here rather than obeyed. The case it was built for is a set the reader swipes: pass showSteps={false} there and the row is marks alone, which is also the only variant still offering a target once the steps are gone. Keep the set under about ten — a dot carries no number, so beyond a handful the reader is counting marks too small and too many to count
+     */
+    variant?: 'pages' | 'count' | 'compact' | 'none' | 'dots';
+    /** Whether the two step controls are drawn, under the dots variant. True wherever this component is the way through the set, which is nearly all of them. False for a set the reader moves through some other way and this only reports — a carousel they swipe, a gallery with its own arrows — where a second pair underneath competes with the first. Dropping them also buys the width that lets a long row of marks fit a phone */
+    showSteps?: boolean;
+    /** 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 dots variant always, 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 or count 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 results there are altogether, where that is known. It is what turns the count variant's readout from a position into a measure — "1–10 of 240" rather than "page 1 of 24" — which is the fact that tells a reader whether to keep stepping or narrow their filter instead */
+    totalItems?: number;
+    /** How many items each page holds, which is what lets the count variant work out the range on screen from the page number alone. Pass it alongside totalItems; on its own it has nothing to be a fraction of. It reports the size in force and does not offer to change it — a control for that is the consumer's to place, beside this one */
+    pageSize?: number;
+    /** 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' | 'showSteps' | 'page' | 'totalPages' | 'onPageChange' | 'pageHref' | 'totalItems' | 'pageSize' | '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 dot: "dds-pagination__dot";
+    readonly 'dot-mark': "dds-pagination__dot-mark";
+    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 showSteps: true;
+    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,14 @@
+// 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',
+    dot: 'dds-pagination__dot',
+    'dot-mark': 'dds-pagination__dot-mark',
+    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', showSteps: true, 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/removable-chip/RemovableChip.css

@@ -0,0 +1,125 @@
+/* GENERATED from removablechip.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-removablechip {
+  transition-property: opacity;
+  align-items: center;
+  border-style: solid;
+  box-sizing: border-box;
+  cursor: default;
+  display: inline-flex;
+  max-inline-size: 100%;
+  background-color: var(--color-bg-brand-strong);
+  border-color: var(--color-bg-brand-strong);
+  border-radius: var(--radius-pill);
+  border-width: var(--border-width-default);
+  color: var(--color-fg-on-brand-strong);
+  gap: var(--space-gap-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip .dds-removablechip__icon {
+  align-items: center;
+  display: flex;
+  flex: none;
+  justify-content: center;
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip .dds-removablechip__label {
+  min-inline-size: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip .dds-removablechip__remove {
+  transition-property: background-color, outline-color, outline-width;
+  align-items: center;
+  appearance: none;
+  background-color: transparent;
+  border-style: none;
+  cursor: pointer;
+  display: inline-flex;
+  flex: none;
+  justify-content: center;
+  outline-style: solid;
+  padding: unset;
+  border-radius: var(--radius-pill);
+  color: var(--color-fg-on-brand-strong);
+  min-block-size: var(--size-target-min);
+  min-inline-size: var(--size-target-min);
+  outline-width: var(--border-width-none);
+  transition-duration: var(--motion-duration-fast);
+  transition-timing-function: var(--motion-easing-standard);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip .dds-removablechip__remove-icon {
+  flex: none;
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip .dds-removablechip__remove:hover:where(:not(:disabled)) {
+  background-color: var(--color-bg-hover-inverse);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip .dds-removablechip__remove:active {
+  background-color: var(--color-bg-active-inverse);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip .dds-removablechip__remove:focus-visible {
+  outline-color: var(--color-border-focus);
+  outline-width: var(--border-width-focus);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-disabled="true"] {
+  opacity: var(--opacity-disabled);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-size="md"] {
+  block-size: var(--size-control-md);
+  padding-inline-end: var(--space-inset-sm);
+  padding-inline-start: var(--space-inset-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-size="md"] .dds-removablechip__icon {
+  block-size: var(--icon-size-sm);
+  inline-size: var(--icon-size-sm);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-size="md"] .dds-removablechip__label {
+  font-family: var(--font-label-md-family);
+  font-size: var(--font-label-md-size);
+  font-weight: var(--font-label-md-weight);
+  line-height: var(--font-label-md-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-size="md"] .dds-removablechip__remove-icon {
+  block-size: var(--icon-size-sm);
+  inline-size: var(--icon-size-sm);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-size="sm"] {
+  block-size: var(--size-control-sm);
+  padding-inline-end: var(--space-inset-xs);
+  padding-inline-start: var(--space-inset-sm);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-size="sm"] .dds-removablechip__icon {
+  block-size: var(--icon-size-xs);
+  inline-size: var(--icon-size-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-size="sm"] .dds-removablechip__label {
+  font-family: var(--font-label-sm-family);
+  font-size: var(--font-label-sm-size);
+  font-weight: var(--font-label-sm-weight);
+  line-height: var(--font-label-sm-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-removablechip[data-size="sm"] .dds-removablechip__remove-icon {
+  block-size: var(--icon-size-xs);
+  inline-size: var(--icon-size-xs);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) .dds-removablechip,
+  :where([data-dds-context="marketing"]) .dds-removablechip * { transition: none; }
+}
+