@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/dist/components/core/tab-list/TabList.js

@@ -0,0 +1,124 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement, useCallback, useEffect, useLayoutEffect, useRef, useState, } from 'react';
+import './TabList.css';
+import './tab-list-impl.css';
+import { tabParts } from '../tab/Tab.types.js';
+import { tabListParts } from './TabList.types.js';
+/**
+ * Both handlers, the tab's own first.
+ *
+ * `cloneElement` replaces rather than merges, so a tab already reporting its own
+ * presses would silently stop — and that is the handler a page is most likely to
+ * have written, since it is how they learn which tab was pressed.
+ */
+function chain(theirs, ours) {
+    if (theirs === undefined)
+        return ours;
+    return (value) => {
+        theirs(value);
+        ours(value);
+    };
+}
+/**
+ * A strip of comparable versions of one thing, and the two things that belong to
+ * the set rather than to any tab: which is current, and where the bar sits.
+ *
+ * Controlled, and only controlled. The strip holds no selection state because the
+ * choice is not its to hold — the page renders whichever slice matches, so the
+ * page is where the answer lives. A private copy would be a second source of
+ * truth for the same question, and the two would disagree the first time the page
+ * set it from anywhere else. Product's keeps an uncontrolled mode because an app
+ * tab strip often has nothing else holding the view; here there always is.
+ *
+ * A `value` naming no tab selects none of them. Falling back to the first would
+ * tell the reader they are looking at a version they did not ask for, while the
+ * page beneath showed something else.
+ *
+ * `role="group"` with a name. Not `role="tablist"` — that names a widget whose
+ * tabs own panels through `aria-controls`, and the panels here belong to the
+ * page, so it is a promise this component cannot keep. Not `role="navigation"`
+ * either: a landmark says the items go places, and these change what is showing
+ * on the page the reader is already on.
+ */
+export function TabList({ label, value, onChange, children, ...rest }) {
+    const listRef = useRef(null);
+    const [bar, setBar] = useState(null);
+    const tabs = Children.toArray(children).filter((isValidElement));
+    /*
+      Seeded from whichever tab arrived selected, and from the first tab when none
+      did. A strip always has a current one: it is showing a slice of the page
+      either way, so a strip marking nothing would be a page whose content had no
+      heading over it.
+  
+      This is not the rule about a value naming no tab. That one is about a page
+      asking for something that is not here, which is a mistake worth showing
+      rather than papering over. This is about nobody having asked at all.
+    */
+    const [picked, setPicked] = useState(() => tabs.find((tab) => tab.props.selected === true)?.props.value ?? tabs[0]?.props.value ?? null);
+    const controlled = value !== undefined;
+    const current = controlled ? value : picked;
+    const active = tabs.findIndex((tab) => tab.props.value !== undefined && tab.props.value === current);
+    const measure = useCallback(() => {
+        const list = listRef.current;
+        if (list === null)
+            return;
+        if (active === -1) {
+            setBar(null);
+            return;
+        }
+        /*
+          Queried rather than indexed into `children`: the bar is a child of this
+          element too, so the nth child and the nth tab stopped being the same thing
+          the moment it arrived.
+    
+          The content box rather than the tab, so the mark is as wide as the words
+          instead of running out under the pill's padding. Read off Tab's own
+          generated constant rather than typed out here — the class belongs to
+          another component, and a literal would make this measurement depend on a
+          name nothing checks: rename the part and the bar stops working with every
+          gate still green.
+        */
+        const items = list.querySelectorAll(`:scope > .${tabParts.root}`);
+        const content = items[active]?.querySelector(`.${tabParts.content}`);
+        if (content === null || content === undefined) {
+            setBar(null);
+            return;
+        }
+        // offsetLeft is measured from the nearest positioned ancestor, which the
+        // contract makes the list — so this is content-relative and travels with the
+        // scroll rather than needing it subtracted.
+        setBar({ along: content.offsetLeft, length: content.offsetWidth });
+    }, [active]);
+    // Layout rather than a plain effect: between the two the bar would be painted
+    // at its previous place, which is a frame of the mark under the wrong tab.
+    useLayoutEffect(measure, [measure, tabs.length]);
+    /*
+      The strip changing shape moves the tab underneath the bar.
+  
+      Absent where there is no ResizeObserver rather than fatal — the bar stays
+      where the last measurement put it, which is correct until something resizes.
+      jsdom is the environment that asks: the generated behaviour test runs there.
+    */
+    useEffect(() => {
+        const list = listRef.current;
+        if (list === null)
+            return;
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(() => measure());
+        observer.observe(list);
+        return () => observer.disconnect();
+    }, [measure]);
+    return (_jsx("div", { ...rest, className: tabListParts.root, role: "group", "aria-label": label, children: _jsxs("div", { className: tabListParts.list, ref: listRef, children: [tabs.map((tab, index) => cloneElement(tab, {
+                    selected: index === active,
+                    onSelect: chain(tab.props.onSelect, (pressed) => {
+                        // The strip records the choice only when nobody else is holding it.
+                        // A controlled strip that also moved its own copy would have two
+                        // answers to one question and show the stale one for a frame.
+                        if (!controlled)
+                            setPicked(pressed);
+                        onChange?.(pressed);
+                    }),
+                })), _jsx("span", { className: tabListParts.indicator, hidden: bar === null, style: bar === null ? undefined : { inlineSize: `${bar.length}px`, translate: `${bar.along}px` } })] }) }));
+}

package/dist/components/core/tab-list/TabList.types.d.ts

@@ -0,0 +1,20 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface TabListOwnProps {
+    /** Always — a group with no name is a group a screen reader announces as nothing, and the reader is told there is a set without being told what it is a set of. Name what the tabs switch between rather than the act of switching: 'Billing period', not 'Choose a billing period' */
+    label: string;
+    /** The page is holding which tab is current, because the choice also drives what is rendered beneath the strip — the ordinary case here. Passing it makes the strip controlled: it shows what it is told and reports presses through onChange.
+  
+  Leave it off and the strip holds its own answer, seeded from whichever tab arrived selected and from the first tab when none did. That is for a strip whose slices are all on the page already and only need showing one at a time, and it is what Accordion does with its rows. */
+    value?: string;
+    /** Whenever value is — together they are how a page holds the choice. It is called with the pressed tab's value after that tab's own onSelect, so a tab that reports its own presses keeps doing so inside a set */
+    onChange?: (value: string) => void;
+    /** Allowed: Tab */
+    children: ReactNode;
+}
+export type TabListProps = TabListOwnProps & Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'label' | 'value' | 'onChange'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const tabListParts: {
+    readonly root: "dds-tablist";
+    readonly list: "dds-tablist__list";
+    readonly indicator: "dds-tablist__indicator";
+};

package/dist/components/core/tab-list/TabList.types.js

@@ -0,0 +1,7 @@
+// GENERATED from tab-list.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const tabListParts = {
+    root: 'dds-tablist',
+    list: 'dds-tablist__list',
+    indicator: 'dds-tablist__indicator',
+};

package/dist/components/core/tab-list/tab-list-impl.css

@@ -0,0 +1,56 @@
+/*
+ * Scoped to this package, like the generated sheet beside it.
+ *
+ * `:where([data-dds-context="marketing"])` confines these rules without contributing
+ * specificity, so every override below still ties or beats exactly what it did
+ * before — several here are written a class deeper than they look in order to
+ * match generated CSS, and a scope that carried weight would break all of them.
+ */
+
+/* Implementation CSS that the contract's staticCss cannot express. */
+
+/*
+ * The strip overlaps its own rail by the rail's own thickness.
+ *
+ * The rail is the root's `border-block-end` and the bar is the last thing inside the list,
+ * so by default they stack: a 1px line with a 4px bar sitting on top of it and a visible
+ * seam between the two. Pulling the list down by exactly the rail's width closes it — the
+ * border moves up under the list's last row, and a child paints over its parent's border,
+ * so the bar covers the line rather than butting against it. Where no tab is current the
+ * rail shows through unbroken, which is the point.
+ *
+ * On the list rather than on the bar, and that matters: the list is `overflow-x: auto`,
+ * which makes its block axis `auto` too, so a bar hanging 1px past the bottom would be
+ * clipped there or earn a vertical scrollbar. Moving the whole row keeps every box inside
+ * its own scroll container.
+ *
+ * Not a token and not expressible as one: this is the negation of another value rather than
+ * a value of its own, and it reads that value rather than repeating it — retune
+ * border.width.default and the overlap follows without anything here being touched. No
+ * contract can hold a negative dimension, which is why it is here at all.
+ */
+:where([data-dds-context="marketing"]) .dds-tablist .dds-tablist__list {
+  margin-block-end: calc(var(--border-width-default) * -1);
+}
+
+/*
+ * What the bar's travel is made of.
+ *
+ * `transition-property` is a list of property names, which no token can be — so it is here,
+ * while how long the travel takes and on what curve are decisions and live in the contract
+ * as motion.duration.normal and motion.easing.standard. The reduced-motion guard the
+ * generator writes covers `.dds-tablist *`, so this is switched off with everything else.
+ *
+ * `translate` and `inline-size` rather than `left` and `width`: those are the properties the
+ * bar is actually set with, and translate is the one a browser can animate without laying
+ * the row out again on every frame.
+ *
+ * Two classes deep. The emitter writes a `transition-property` of its own only for
+ * properties that vary by a state or a boolean axis, and nothing on this part varies by
+ * either today — so a bare class would win. That is luck rather than correctness: give this
+ * component any boolean axis reaching the bar and the generated rule appears at two classes,
+ * outranks a bare one, and the bar stops travelling with every gate still green.
+ */
+:where([data-dds-context="marketing"]) .dds-tablist .dds-tablist__indicator {
+  transition-property: translate, inline-size;
+}

package/dist/components/core/table/Table.css

@@ -0,0 +1,40 @@
+/* GENERATED from table.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-table {
+  box-sizing: border-box;
+  outline-style: solid;
+  overflow-x: auto;
+  overflow-y: visible;
+  outline-width: var(--border-width-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-table .dds-table__grid {
+  border-collapse: separate;
+  border-spacing: 0;
+  box-sizing: border-box;
+  inline-size: 100%;
+  color: var(--color-fg-default);
+  font-family: var(--font-body-md-family);
+}
+
+:where([data-dds-context="marketing"]) .dds-table[data-layout="auto"] .dds-table__grid {
+  table-layout: auto;
+}
+
+:where([data-dds-context="marketing"]) .dds-table[data-layout="fixed"] .dds-table__grid {
+  table-layout: fixed;
+}
+
+:where([data-dds-context="marketing"]) .dds-table .dds-table__caption {
+  font-family: var(--font-subtitle-family);
+  font-size: var(--font-subtitle-size);
+  font-weight: var(--font-subtitle-weight);
+  line-height: var(--font-subtitle-line-height);
+  padding-block-end: var(--space-gap-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-table:focus-visible {
+  outline-color: var(--color-border-focus);
+  outline-width: var(--border-width-focus);
+}
+

package/dist/components/core/table/Table.d.ts

@@ -0,0 +1,19 @@
+import './Table.css';
+import './table-impl.css';
+import { type TableProps } from './Table.types.js';
+export type { TableProps };
+export { useTableSort, type TableSort, type TableSortDirection } from './use-table-sort.js';
+/**
+ * Structured data in rows and columns, where every row has the same shape.
+ *
+ * It owns what the whole table shares and none of what any cell holds. `size` and `dividers` are
+ * declared here and drawn nowhere here — a table's air is its cells' padding and its rules are its
+ * rows' edges — so both are handed to the sections, which hand them on. The same cascade `List`
+ * makes to its items, one level deeper because a table has sections.
+ *
+ * It remembers nothing. Which column is sorted, which rows are picked and which columns are shown
+ * all outlive a render, so they arrive as hooks beside this component and what the table renders is
+ * whatever they answer. Composed without any of them it is a static grid, which is what a
+ * documentation page and a preview both need.
+ */
+export declare function Table({ layout, pinFirstColumn, size, dividers, hoverable, overflow, headerCase, caption, children, ...rest }: TableProps): import("react").JSX.Element;

package/dist/components/core/table/Table.js

@@ -0,0 +1,55 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement, useId } from 'react';
+import './Table.css';
+import './table-impl.css';
+import { given } from '../../given.js';
+import { tableDefaults, tableParts } from './Table.types.js';
+// The one table hook this package ships. Product has two more beside it — row selection and
+// column management — and neither comes over: they are how an application operates a table, and
+// a marketing table is read rather than operated.
+export { useTableSort } from './use-table-sort.js';
+/**
+ * Structured data in rows and columns, where every row has the same shape.
+ *
+ * It owns what the whole table shares and none of what any cell holds. `size` and `dividers` are
+ * declared here and drawn nowhere here — a table's air is its cells' padding and its rules are its
+ * rows' edges — so both are handed to the sections, which hand them on. The same cascade `List`
+ * makes to its items, one level deeper because a table has sections.
+ *
+ * It remembers nothing. Which column is sorted, which rows are picked and which columns are shown
+ * all outlive a render, so they arrive as hooks beside this component and what the table renders is
+ * whatever they answer. Composed without any of them it is a static grid, which is what a
+ * documentation page and a preview both need.
+ */
+export function Table({ layout = tableDefaults.layout, pinFirstColumn = tableDefaults.pinFirstColumn, size = tableDefaults.size, dividers = tableDefaults.dividers, hoverable = tableDefaults.hoverable, overflow = tableDefaults.overflow, headerCase = tableDefaults.headerCase, caption, children, ...rest }) {
+    const named = given(caption);
+    const captionId = `${useId()}-caption`;
+    return (
+    /*
+      The scroll container, and the reason this renders two elements. A table cannot scroll
+      itself — `display: table` establishes no scroll container — so the box that does has to
+      be around it. It matters most where the screen is narrowest: the surface a table sits on
+      clips, Card holding `overflow: hidden` to keep its corner, so a table wider than its card
+      was cut off at the edge with nothing to say so and no way to reach the rest.
+
+      The spread lands here rather than on the table, because this is the element the consumer
+      is handed — the same place `className` and a ref would go.
+    */
+    _jsx("div", { ...rest, className: tableParts.root, "data-layout": layout, "data-pin-first-column": String(pinFirstColumn), 
+        /*
+          A scroll region a pointer can move and a keyboard cannot is unreachable for anybody not
+          using a mouse, and on the screens this exists for that is most of the columns. The tab
+          stop is the cost of the scroller and not optional.
+        */
+        tabIndex: 0, role: "group", "aria-labelledby": named ? captionId : undefined, children: _jsxs("table", { className: tableParts.grid, children: [named ? (_jsx("caption", { id: captionId, className: tableParts.caption, children: caption })) : null, Children.toArray(children)
+                    .filter(isValidElement)
+                    .map((section, at) => cloneElement(section, {
+                    key: section.key ?? at,
+                    size,
+                    dividers,
+                    headerCase,
+                    hoverable,
+                    overflow,
+                }))] }) }));
+}

package/dist/components/core/table/Table.types.d.ts

@@ -0,0 +1,59 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface TableOwnProps {
+    /**
+     * `auto` — The default. Columns take their widths from what is in them, which is right when the content is known and varied — a name column wants more room than a status one and can say so itself
+     * `fixed` — Columns take an equal share of the width whatever they hold, and the table stops re-flowing as data changes. Reach for it when rows arrive over time: with auto widths every new page of results shifts every column and the reader loses the shape they had learnt.
+  
+  Equal shares is the whole of what it does here. `table-layout: fixed` exists to make declared column widths authoritative, and this component declares none — there is no per-column width to set — so three columns are a third each however unlike they are.
+     */
+    layout?: 'auto' | 'fixed';
+    /** The first column is what identifies the row — a market, a product, a plan — and the columns after it are the values being compared. Pinned, the name stays while the numbers scroll, so a reader who has scrolled three columns out still knows which row they are reading. It is worth asking for exactly when the table is wider than the screen it is read on, which on a marketing page is most tables on a phone */
+    pinFirstColumn?: boolean;
+    /** Where nothing else names the table. A table is announced as a grid of so many rows and columns, so a reader landing inside an unnamed one has to read a cell to find out what they are in — "Open positions", "October statements". It renders a real `<caption>`, which browsers centre above the grid in bold, so it is a visible heading rather than a hidden label.
+  
+  Most pages already have that heading, sitting above the table and styled by the page rather than by this component. Point at it with aria-labelledby and leave this out: two headings, one of them the browser's own idea of what a caption looks like, is worse than the one the page had. */
+    caption?: string;
+    /**
+     * `rows` — The default. A line between rows and none between columns, which is what stops the eye slipping from one row's start to another's end — the mistake a wide table invites and the one a reader never notices making
+     * `grid` — Lines both ways, for a table read as a matrix rather than as a list of records: a rate card, a comparison where the reader traces a column as often as a row. It is more lines than most tables need, so it should be asked for
+     * `none` — No lines at all. Right for two or three rows, where the rules are more structure than data, and for a table whose columns are already separated by their alignment
+     */
+    dividers?: 'rows' | 'grid' | 'none';
+    /**
+     * `upper` — The house setting: column names in capitals, at the role that suits them. A header is read once where the data under it is read many times, and capitals are what stop it competing
+     * `title` — Names drawn as they were written, at twelve pixels. Right where the names are long, are proper nouns whose own capitals would be flattened, or are in a script with no case at all
+     */
+    headerCase?: 'upper' | 'title';
+    /** On by default. A wash follows the pointer and says which row a press would land on, which a wide table needs and a narrow one is not harmed by: the further a row runs, the easier it is to be reading one and about to click another. Only on devices that have a pointer, which the row's own stylesheet gates */
+    hoverable?: boolean;
+    /**
+     * `wrap` — The default. Text too long for its column wraps and the row grows taller, so nothing is hidden — right whenever the value is the point and a reader has to read all of it
+     * `truncate` — Rows must stay one line high — a dense table a reader scans down, where a row that grew would break the rhythm they are scanning by. The value is clipped with an ellipsis and the whole of it is still reachable, so this trades seeing for scanning rather than losing anything
+     */
+    overflow?: 'wrap' | 'truncate';
+    /**
+     * `sm` — Compact. Dense data a reader scans rather than reads — a ledger, a positions table, anything where fitting more rows on screen is worth more than air around each one
+     * `md` — Balanced, and the default: rows a reader moves through at reading pace, with enough room that the eye does not slip between them
+     * `lg` — Spacious. Few rows, each carrying something substantial — a plan comparison, a summary of three accounts. Reach for it when the table is the page rather than a part of it
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /** Allowed: TableHead, TableBody */
+    children: ReactNode;
+}
+export type TableProps = TableOwnProps & Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'layout' | 'pinFirstColumn' | 'caption' | 'dividers' | 'headerCase' | 'hoverable' | 'overflow' | 'size'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const tableParts: {
+    readonly root: "dds-table";
+    readonly grid: "dds-table__grid";
+    readonly caption: "dds-table__caption";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const tableDefaults: {
+    readonly layout: "auto";
+    readonly pinFirstColumn: false;
+    readonly dividers: "rows";
+    readonly headerCase: "upper";
+    readonly hoverable: true;
+    readonly overflow: "wrap";
+    readonly size: "md";
+};

package/dist/components/core/table/Table.types.js

@@ -0,0 +1,9 @@
+// GENERATED from table.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const tableParts = {
+    root: 'dds-table',
+    grid: 'dds-table__grid',
+    caption: 'dds-table__caption',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const tableDefaults = { layout: 'auto', pinFirstColumn: false, dividers: 'rows', headerCase: 'upper', hoverable: true, overflow: 'wrap', size: 'md' };

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

@@ -0,0 +1,75 @@
+/*
+ * 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.
+ */
+
+/*
+ * The vertical rules, which the contract cannot bind.
+ *
+ * `border-inline-start-width` is not a property this system knows — `border-block-start-width` is,
+ * which is how a cell draws the line above it — so the horizontal rules are bindings and these are
+ * not. The measure is still the token: what is written here is which edge, not how thick.
+ *
+ * Scoped to `grid`, because that is the only value that asks for them. `rows` is a line between
+ * records and none between columns, which is what a table read as a list of records wants; `grid`
+ * is for one read as a matrix, where a reader traces a column as often as a row.
+ */
+:where([data-dds-context="marketing"]) .dds-table [data-dividers='grid'] {
+  border-inline-start-width: var(--border-width-hairline);
+  border-inline-end-width: 0;
+}
+
+/*
+ * Except the first cell in each row, which would otherwise draw a line down the table's own edge —
+ * inside a rounded corner, where it reads as a crack rather than as a rule.
+ */
+:where([data-dds-context="marketing"]) .dds-table .dds-tablerow > [data-dividers='grid']:first-child {
+  border-inline-start-width: 0;
+}
+
+/*
+ * The pinned first column.
+ *
+ * Nothing sticks until there is something to scroll, so this costs nothing on a table that fits —
+ * `position: sticky` is inert without an overflowing scroll container, and the one this table
+ * renders is the container it sticks inside.
+ *
+ * It has to be opaque, and that is the whole difficulty. A table paints nothing: the surface
+ * belongs to whatever put it there, which is the right arrangement everywhere except here, where a
+ * cell that stays put while the rest slides under it shows the sliding through itself. So the
+ * pinned cell paints the ground its card holds — the one colour it can name that a page will have
+ * put behind it.
+ *
+ * The row's own states cannot simply be inherited through it, because both are alpha: selected is
+ * eight percent black and hover is five, and a translucent cell over scrolled content is the same
+ * failure with a tint on it. So each is restated here over the opaque floor, the selected one as a
+ * colour and the hover one as an image layered above it. That is the arrangement FilterChip makes
+ * for exactly the same reason, and the second time this package has needed it.
+ *
+ * The stacking order is an integer with no unit and no token to name it — this package has one
+ * layer role and it is for popups, which this is not. One is enough: the pinned cell has to paint
+ * over its own row's later siblings and nothing else in the document.
+ */
+:where([data-dds-context="marketing"]) .dds-table[data-pin-first-column='true'] .dds-tablerow > :first-child {
+  position: sticky;
+  inset-inline-start: 0;
+  z-index: 1;
+  background-color: var(--color-bg-surface-raised);
+  border-inline-end-width: var(--border-width-hairline);
+}
+
+/* The chosen row keeps its ground where it is pinned, restated because an alpha cannot be inherited
+   onto a cell that has scrolled content behind it. */
+:where([data-dds-context="marketing"]) .dds-table[data-pin-first-column='true'] .dds-tablerow[data-selected='true'] > :first-child {
+  background-color: var(--color-bg-selected);
+}
+
+/* And the pointer's wash, as an image over the floor rather than instead of it — the layering
+   FilterChip uses, for the same reason: the token tints what it lands on rather than replacing it. */
+:where([data-dds-context="marketing"]) .dds-table[data-pin-first-column='true'] .dds-tablerow[data-hoverable='true']:hover > :first-child {
+  background-image: linear-gradient(var(--color-bg-hover), var(--color-bg-hover));
+}

package/dist/components/core/table/use-table-sort.d.ts

@@ -0,0 +1,43 @@
+/** Which way a column is ordered, in the words `aria-sort` uses. */
+export type TableSortDirection = 'none' | 'ascending' | 'descending';
+export interface TableSort {
+    /** The column the table is ordered by, or undefined while it is ordered by none. */
+    column: string | undefined;
+    /** Which way that column runs. `none` for every other column. */
+    direction: TableSortDirection;
+    /** What a header cell needs to draw itself: spread it onto the TableHeaderCell. */
+    columnProps: (column: string) => {
+        sortable: true;
+        sortDirection: TableSortDirection;
+        onSort: () => void;
+    };
+}
+/**
+ * Which column a table is ordered by, and which way.
+ *
+ * The table does not keep this and cannot: the order outlives a render, and a table holding it
+ * would be a second copy of something the page already has — the rows themselves are sorted by
+ * whatever fetched them, and the two disagree the first time either changes.
+ *
+ * So this owns the answer and the page owns the rows. It reports which column and which direction,
+ * and sorting the data is the caller's: a table built at request time passes the pair to whatever
+ * fetched the rows, and one sorted in the browser sorts an array with it. Neither is this hook's
+ * business, which is why it returns no rows.
+ *
+ * It is the only one of product's three table hooks this package ships. Row selection and column
+ * management are how an application operates a table; a marketing table is read rather than
+ * operated, and a page that needs a reader to pick rows out of a set is an application view.
+ *
+ * The cycle is ascending, descending, none. Three states rather than two because a table ordered
+ * by nothing is a real state — it is the order the data arrived in, which for a feed is the only
+ * meaningful one, and a two-state toggle makes it unreachable once a reader has pressed anything.
+ *
+ * ```tsx
+ * const sort = useTableSort()
+ * <TableHeaderCell {...sort.columnProps('balance')} align="end">Balance</TableHeaderCell>
+ * ```
+ */
+export declare function useTableSort(initial?: {
+    column: string;
+    direction: TableSortDirection;
+}): TableSort;

package/dist/components/core/table/use-table-sort.js

@@ -0,0 +1,51 @@
+'use client';
+import { useCallback, useState } from 'react';
+/**
+ * Which column a table is ordered by, and which way.
+ *
+ * The table does not keep this and cannot: the order outlives a render, and a table holding it
+ * would be a second copy of something the page already has — the rows themselves are sorted by
+ * whatever fetched them, and the two disagree the first time either changes.
+ *
+ * So this owns the answer and the page owns the rows. It reports which column and which direction,
+ * and sorting the data is the caller's: a table built at request time passes the pair to whatever
+ * fetched the rows, and one sorted in the browser sorts an array with it. Neither is this hook's
+ * business, which is why it returns no rows.
+ *
+ * It is the only one of product's three table hooks this package ships. Row selection and column
+ * management are how an application operates a table; a marketing table is read rather than
+ * operated, and a page that needs a reader to pick rows out of a set is an application view.
+ *
+ * The cycle is ascending, descending, none. Three states rather than two because a table ordered
+ * by nothing is a real state — it is the order the data arrived in, which for a feed is the only
+ * meaningful one, and a two-state toggle makes it unreachable once a reader has pressed anything.
+ *
+ * ```tsx
+ * const sort = useTableSort()
+ * <TableHeaderCell {...sort.columnProps('balance')} align="end">Balance</TableHeaderCell>
+ * ```
+ */
+export function useTableSort(initial) {
+    const [column, setColumn] = useState(initial?.column);
+    const [direction, setDirection] = useState(initial?.direction ?? 'none');
+    const columnProps = useCallback((name) => ({
+        sortable: true,
+        // Every other column reads `none`: a direction is a fact about the sorted column, and a
+        // header claiming one while another column is sorted tells the reader the data runs two ways.
+        sortDirection: column === name ? direction : 'none',
+        onSort: () => {
+            if (column !== name) {
+                setColumn(name);
+                setDirection('ascending');
+                return;
+            }
+            // Ascending, descending, then back to no order at all — which releases the column rather
+            // than leaving the table stuck between two states it can never leave.
+            const next = direction === 'ascending' ? 'descending' : direction === 'descending' ? 'none' : 'ascending';
+            setDirection(next);
+            if (next === 'none')
+                setColumn(undefined);
+        },
+    }), [column, direction]);
+    return { column, direction, columnProps };
+}

package/dist/components/core/table-body/TableBody.css

@@ -0,0 +1,6 @@
+/* GENERATED from tablebody.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-tablebody {
+  background-color: var(--color-bg-transparent);
+}
+

package/dist/components/core/table-body/TableBody.d.ts

@@ -0,0 +1,12 @@
+import './TableBody.css';
+import { type TableBodyProps } from './TableBody.types.js';
+export type { TableBodyProps };
+/**
+ * The rows of data, under the header.
+ *
+ * It is where the table's rules reach the rows: a line belongs between two data rows and nowhere
+ * else, so the section holding only data is the one that hands them out. It paints the surface the
+ * data sits on, which is the other half of the header's band — the names are tinted and the values
+ * are not, so the two read as different kinds of row without a second rule between them.
+ */
+export declare function TableBody({ size, dividers, hoverable, overflow, children, ...rest }: TableBodyProps): import("react").JSX.Element;

package/dist/components/core/table-body/TableBody.js

@@ -0,0 +1,26 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, cloneElement, isValidElement } from 'react';
+import './TableBody.css';
+import { tableBodyDefaults, tableBodyParts } from './TableBody.types.js';
+/**
+ * The rows of data, under the header.
+ *
+ * It is where the table's rules reach the rows: a line belongs between two data rows and nowhere
+ * else, so the section holding only data is the one that hands them out. It paints the surface the
+ * data sits on, which is the other half of the header's band — the names are tinted and the values
+ * are not, so the two read as different kinds of row without a second rule between them.
+ */
+export function TableBody({ size = tableBodyDefaults.size, dividers = tableBodyDefaults.dividers, hoverable = tableBodyDefaults.hoverable, overflow = tableBodyDefaults.overflow, children, ...rest }) {
+    return (_jsx("tbody", { ...rest, className: tableBodyParts.root, children: Children.toArray(children)
+            .filter(isValidElement)
+            .map((row, at) => cloneElement(row, {
+            key: row.key ?? at,
+            size,
+            // The first row's rule is the line under the header, so every row draws one and the
+            // table still ends clean — the edge is on the block-start side.
+            dividers,
+            hoverable,
+            overflow,
+        })) }));
+}