material-plus-ui 1.5.0 → 1.7.0

package/dist/components/confirm/MPConfirmProvider.d.ts

@@ -0,0 +1,143 @@
+import * as React from 'react';
+import type { MPColor, MPSize } from '../../types.js';
+/** What a confirmation asks, and how it is drawn. */
+export interface MPConfirmOptions {
+    /** The question, as a heading. */
+    title?: React.ReactNode;
+    /** The sentence under it — what happens, and to what. */
+    description?: React.ReactNode;
+    /** A glyph above the title, the way `MPDialog` draws one. */
+    icon?: React.ReactNode;
+    /**
+     * Anything else the dialog should hold — a field, a list of what is about to
+     * be deleted, a checkbox that says "do not ask again".
+     */
+    children?: React.ReactNode;
+    /** What the yes button says. @default the translation of `Confirm` */
+    confirmLabel?: React.ReactNode;
+    /** What the no button says. @default the translation of `Cancel` */
+    cancelLabel?: React.ReactNode;
+    /**
+     * The accent the yes button is drawn in.
+     *
+     * `'error'` is what a destructive confirmation wants, and it is not the
+     * default: most confirmations are not destructive, and a red button on every
+     * one of them stops being a warning.
+     * @default 'primary'
+     */
+    color?: MPColor;
+    /** @default 'md' */
+    size?: MPSize;
+    /**
+     * Whether Escape and a press outside answer **no**.
+     *
+     * On by default, because a dialog a reader cannot leave is a trap and because
+     * the safe answer to "are you sure" is no. Switch it off for a question that
+     * genuinely has to be answered — and be sure it does, because the reader then
+     * has exactly two ways out and both of them are your buttons.
+     * @default true
+     */
+    dismissible?: boolean;
+}
+export interface MPConfirmResult {
+    /**
+     * Asks, and resolves with the answer.
+     *
+     * `true` for the confirm button, `false` for cancel — and `false` for Escape,
+     * a press outside, and anything else that closes the dialog. There is no third
+     * answer, so a caller writes one `if`.
+     */
+    confirm: (options: MPConfirmOptions) => Promise<boolean>;
+    /**
+     * Tells, and resolves once it has been acknowledged.
+     *
+     * One button, because there is nothing to refuse. `Promise<void>` rather than
+     * `Promise<boolean>` for the same reason: an acknowledgement has no answer,
+     * and a boolean nobody can vary is a value a caller would have to learn to
+     * ignore.
+     */
+    alert: (options: MPConfirmOptions) => Promise<void>;
+}
+export interface MPConfirmProviderProps {
+    /**
+     * Defaults for every confirmation raised under this — a `size` to match the
+     * application, an accent, a `cancelLabel` in your own words. Each call still
+     * says whatever it needs to and wins.
+     */
+    defaults?: Omit<MPConfirmOptions, 'title' | 'description' | 'children'>;
+    children?: React.ReactNode;
+}
+/**
+ * Holds the one dialog every `confirm()` in the application is drawn in.
+ *
+ * Wrap the application, the way `MPSnackbarProvider` is wrapped, and for the
+ * same reason: what a caller has at the moment a question is warranted is a
+ * click handler, not a place in the tree.
+ *
+ * ```tsx
+ * <MPConfirmProvider>
+ *   <App />
+ * </MPConfirmProvider>
+ * ```
+ *
+ * ## One at a time
+ *
+ * A second `confirm()` raised while one is open **replaces** it, and the first
+ * promise resolves `false`. Not a queue, deliberately: a queue would ask a
+ * question about something the reader has already moved on from, and the answer
+ * to a stale question is not information. Two confirmations racing is a bug in
+ * the calling code, and resolving the first as *no* is the safe reading of it.
+ */
+export declare function MPConfirmProvider({ defaults, children }: MPConfirmProviderProps): React.JSX.Element;
+/**
+ * Asks a question and waits for the answer.
+ *
+ * ```tsx
+ * const { confirm } = useMPConfirm();
+ *
+ * async function remove() {
+ *   const sure = await confirm({
+ *     title: 'Delete this project?',
+ *     description: 'Everything in it goes too, and it cannot be undone.',
+ *     confirmLabel: 'Delete',
+ *     color: 'error'
+ *   });
+ *
+ *   if (sure) {
+ *     await api.delete(id);
+ *   }
+ * }
+ * ```
+ *
+ * ## Why this rather than a dialog of your own
+ *
+ * Because the dialog is not the hard part. "Are you sure" needs a piece of open
+ * state, a piece of state for *what* is being confirmed, two handlers, and a
+ * dialog kept mounted somewhere it does not belong — per call site. What the
+ * caller actually has at that moment is a click handler, and what they want back
+ * is a boolean.
+ *
+ * It is the same trade `useMPSnackbar` makes, run the other way: a snackbar is
+ * something to say, this is something to ask.
+ *
+ * ## `false` is every other answer
+ *
+ * The confirm button resolves `true`; the cancel button, Escape, a press outside
+ * and any other close resolve `false`. There is no third outcome and the promise
+ * never rejects, so a caller writes an `if` and not a `try`.
+ *
+ * `alert()` is the one-button form and resolves `void` once it has been
+ * acknowledged — an acknowledgement has nothing to refuse, and a boolean nobody
+ * can vary is a value a caller would have to learn to ignore.
+ *
+ * ## Sharp edges
+ *
+ * - **It needs an `MPConfirmProvider` above it.** Without one the hook throws,
+ *   rather than returning a function that silently never resolves — a promise
+ *   that never settles is the hardest possible way to be told about a missing
+ *   provider.
+ * - **One at a time.** A second `confirm()` raised while one is open replaces it
+ *   and resolves the first `false`. See the provider for why that is not a queue.
+ * - **Do not `await` it inside a render.** It is a click handler's tool.
+ */
+export declare function useMPConfirm(): MPConfirmResult;

package/dist/components/confirm/MPConfirmProvider.js

@@ -0,0 +1,2 @@
+"use client";
+import{jsx as e,Fragment as r,jsxs as n}from"react/jsx-runtime";import*as o from"react";import{MPButton as i}from"../button/MPButton.js";import{MPDialog as t}from"../dialog/MPDialog.js";import{useMPLocale as l,useMPMessages as c}from"../../internal/locale.js";import{CONFIRM as a}from"../../internal/messages/confirm.js";const s=/*@__PURE__*/o.createContext(null);export function MPConfirmProvider({defaults:m,children:u}){const[d,f]=o.useState(null),p=c(a,l()),h=o.useRef(null),C=o.useCallback((e,r)=>new Promise(n=>{h.current?.(!1),h.current=n,f({...m,...e,acknowledge:r})}),[m]),P=o.useMemo(()=>({confirm:e=>C(e,!1),alert:e=>C(e,!0).then(()=>{})}),[C]),x=e=>{h.current?.(e),h.current=null,f(null)},g=d?.acknowledge??!1;return n(s.Provider,{value:P,children:[u,e(t,{open:null!==d,onOpenChange:e=>{e||x(g)},icon:d?.icon,title:d?.title,description:d?.description,size:d?.size??"md",color:d?.color??"primary",dismissible:d?.dismissible??!0,actions:n(r,{children:[g?null:e(i,{variant:"text",onClick:()=>x(!1),children:d?.cancelLabel??p.cancel}),e(i,{variant:"text",color:d?.color??"primary",onClick:()=>x(!0),children:d?.confirmLabel??(g?p.ok:p.confirm)})]}),children:d?.children})]})}export function useMPConfirm(){const e=o.useContext(s);if(!e)throw new Error("useMPConfirm was called outside an <MPConfirmProvider>. Wrap the application in one — the provider is what holds the dialog every confirm() is drawn in.");return e}

package/dist/components/confirm/index.d.ts

@@ -0,0 +1,2 @@
+export { MPConfirmProvider, useMPConfirm } from './MPConfirmProvider.js';
+export type { MPConfirmProviderProps, MPConfirmOptions, MPConfirmResult } from './MPConfirmProvider.js';

package/dist/components/confirm/index.js

@@ -0,0 +1 @@
+export{MPConfirmProvider,useMPConfirm}from"./MPConfirmProvider.js";

package/dist/components/container/MPContainer.d.ts

@@ -1,16 +1,23 @@
 import * as React from 'react';
 import { useRender } from '@base-ui/react/use-render';
-import type { MPSize } from '../../types.js';
+import type { MPMeasure, MPResponsive, MPSize } from '../../types.js';
 export interface MPContainerProps extends React.ComponentPropsWithoutRef<'div'> {
     /**
      * How wide the content is allowed to get, on a ladder pinned to MD3's window
      * size classes — `sm` 600dp, `md` 840dp, `lg` 1200dp, `xl` 1600dp, `xs` 480dp.
      *
+     * Or a CSS length of your own: `maxWidth="60ch"` is the measure a paragraph
+     * actually wants, and no ladder of window widths can spell it.
+     *
+     * Responsive, like the grid's props: `maxWidth={{ compact: 'none', expanded: 'lg' }}`
+     * is edge to edge on a phone and held to 1200dp from 840 up. Each entry applies
+     * from its own window class upward.
+     *
      * `none`, the default, is no limit: a container's job is the margin, and a
      * measure is a second decision that a page should have to ask for.
      * @default 'none'
      */
-    maxWidth?: MPSize | 'none';
+    maxWidth?: MPResponsive<MPMeasure>;
     /**
      * The page margin. Turn it off to keep the centring and the measure without
      * the gutter — a full-bleed hero, a section that pads itself.

package/dist/components/container/MPContainer.js

@@ -1 +1,2 @@
-import*as e from"react";import{useRender as r}from"@base-ui/react/use-render";import{MEASURE as n,SHEET_PAD_X as o}from"../../internal/scale.js";export const MPContainer=/*@__PURE__*/e.forwardRef(function({maxWidth:e="none",padded:a=!0,size:t="md",centered:i=!0,render:d,className:m,children:s,...c},l){return r({render:d,ref:l,props:{"data-mp-size":t,className:["mp-container block w-full","box-border","none"===e?"":n[e],i?"mx-auto":"",a?o[t]:"",m??""].filter(Boolean).join(" "),children:s,...c}})});
+"use client";
+import*as e from"react";import{useRender as r}from"@base-ui/react/use-render";import{SHEET_PAD_X as n}from"../../internal/scale.js";import{measureValue as o}from"../../internal/measure.js";import{useWindowMins as t}from"../../internal/window-class.js";import{responsiveSlots as a,withBaseline as s}from"../../internal/responsive.js";import{useMPSize as i}from"../../internal/config.js";export const MPContainer=/*@__PURE__*/e.forwardRef(function({maxWidth:e="none",padded:m=!0,size:l,centered:c=!0,render:p,className:d,style:f,children:u,...j},b){const w=i(l),x=t(),h="none"!==e;return r({render:p,ref:b,props:{"data-mp-size":w,className:["mp-container block w-full","box-border",h?"mp-measure":"",c?"mx-auto":"",m?n[w]:"",d??""].filter(Boolean).join(" "),style:h?{...a("measure",s(e,"none"),e=>o(e,x)),...f}:f,children:u,...j}})});

package/dist/components/data-list/MPDataList.d.ts

@@ -0,0 +1,82 @@
+import * as React from 'react';
+import type { MPDensity, MPOrientation, MPSize } from '../../types.js';
+export interface MPDataListProps extends Omit<React.ComponentPropsWithoutRef<'dl'>, 'color'> {
+    /**
+     * Where the label sits.
+     *
+     * - `horizontal` — beside the value, in a column of its own. The default, and
+     *   the shape a details panel takes.
+     * - `vertical` — above it. For a narrow column, and for values long enough
+     *   that a label beside them would leave most of the row empty.
+     * @default 'horizontal'
+     */
+    orientation?: MPOrientation;
+    /**
+     * How wide the label column is when `horizontal`. A number is pixels, a
+     * string is any CSS length.
+     *
+     * Left out it is as wide as the widest label, which is what keeps every value
+     * in the list starting at the same place without anybody measuring anything.
+     */
+    labelWidth?: number | string;
+    /** Draws a hairline between the rows. @default false */
+    dividers?: boolean;
+    /** @default 'md' */
+    size?: MPSize;
+    /**
+     * Tightens the gaps between rows and columns, and nothing else. The type
+     * scale does not move.
+     * @default 0
+     */
+    density?: MPDensity;
+    /** The pairs. */
+    children?: React.ReactNode;
+}
+export interface MPDataListItemProps {
+    /** What the value is called. */
+    label: React.ReactNode;
+    /** The value. A node, so a chip, a link or a piece of code all fit. */
+    children?: React.ReactNode;
+}
+/**
+ * One pair: what it is called, and what it is.
+ *
+ * A fragment rather than an element, so the `<dt>` and the `<dd>` land as direct
+ * children of the `<dl>` and the grid can line every label up against every
+ * other. It has no `size` or `density` of its own — those belong to the list,
+ * because a details panel with one row set tighter than its neighbours is not a
+ * thing anybody wants.
+ */
+export declare function MPDataListItem({ label, children }: MPDataListItemProps): React.JSX.Element;
+/**
+ * A list of things and what they are called — a details panel, the summary of a
+ * record, the metadata under a heading.
+ *
+ * ```tsx
+ * <MPDataList>
+ *   <MPDataListItem label="Status">Active</MPDataListItem>
+ *   <MPDataListItem label="Owner">Priya Raman</MPDataListItem>
+ * </MPDataList>
+ * ```
+ *
+ * ## Why not a two-column `MPTable`
+ *
+ * Because they are read differently, and the difference is the whole reason
+ * this is a component. A table is a grid of **rows**, all of the same shape,
+ * and a screen reader walks it as a grid — announcing column headers, offering
+ * cell-by-cell navigation, counting rows. This is a set of **pairs**, and each
+ * one is announced as "label, value", which is what a details panel actually
+ * is.
+ *
+ * So it is a real `<dl>` of real `<dt>`/`<dd>` pairs, and `MPDataListItem`
+ * renders a fragment rather than a wrapper: the two elements have to be direct
+ * children of the `<dl>` for the grid to line every label up against every
+ * other, and a `<div>` between them would take the grid with it.
+ *
+ * ## It draws no surface
+ *
+ * No sheet, no padding, no corner. Put it in an `MPCard` when one is wanted,
+ * which is what makes the same list work inside a card, inside a popover, and
+ * loose under a heading.
+ */
+export declare const MPDataList: React.ForwardRefExoticComponent<MPDataListProps & React.RefAttributes<HTMLDListElement>>;

package/dist/components/data-list/MPDataList.js

@@ -0,0 +1,2 @@
+"use client";
+import{jsx as t,jsxs as e}from"react/jsx-runtime";import*as a from"react";import{cssLength as i}from"../../internal/length.js";import{META_TEXT as n,PROSE_TEXT as r,hasContent as l}from"../../internal/scale.js";import{useMPDensity as o,useMPSize as s}from"../../internal/config.js";const m=/*@__PURE__*/a.createContext({size:"md",orientation:"horizontal"}),d={xs:12,sm:16,md:20,lg:24,xl:32},p={xs:8,sm:10,md:12,lg:14,xl:16};function c(t,e,a){return Math.max(a,t+4*e)}export function MPDataListItem({label:i,children:o}){const{size:s,orientation:d}=a.useContext(m),p="vertical"===d;return e(a.Fragment,{children:[t("dt",{className:["mp-data-list__label text-mp-on-surface-variant min-w-0",n,p?"mt-(--_mp-data-list-row) first:mt-0":""].filter(Boolean).join(" "),children:i}),t("dd",{className:`mp-data-list__value text-mp-on-surface m-0 min-w-0 ${r[s]}`,children:l(o)?o:null})]})}export const MPDataList=/*@__PURE__*/a.forwardRef(function({orientation:e="horizontal",labelWidth:n,dividers:r=!1,size:l,density:f,className:x,style:h,children:u,..._},j){const b=s(l),g=o(f),v="vertical"===e,w=a.useMemo(()=>({size:b,orientation:e}),[b,e]);return t(m.Provider,{value:w,children:t("dl",{ref:j,"data-mp-size":b,className:["mp-data-list m-0 min-w-0",v?"flex flex-col":["grid items-baseline","[grid-template-columns:var(--_mp-data-list-label)_minmax(0,1fr)]","gap-x-(--_mp-data-list-col) gap-y-(--_mp-data-list-row)"].join(" "),r?["border-mp-outline-variant","[&>dt:nth-of-type(n+2)]:border-t [&>dt:nth-of-type(n+2)]:pt-(--_mp-data-list-row)",v?"":"[&>dd:nth-of-type(n+2)]:border-t [&>dd:nth-of-type(n+2)]:pt-(--_mp-data-list-row)"].filter(Boolean).join(" "):"",x??""].filter(Boolean).join(" "),style:{"--_mp-data-list-label":i(n)??"max-content","--_mp-data-list-col":`${c(d[b],g,8)}px`,"--_mp-data-list-row":`${c(p[b],g,4)}px`,...h},..._,children:u})})});

package/dist/components/data-list/index.d.ts

@@ -0,0 +1,2 @@
+export { MPDataList, MPDataListItem } from './MPDataList.js';
+export type { MPDataListItemProps, MPDataListProps } from './MPDataList.js';

package/dist/components/data-list/index.js

@@ -0,0 +1 @@
+export{MPDataList,MPDataListItem}from"./MPDataList.js";

package/dist/components/data-table/MPDataTable.d.ts

@@ -0,0 +1,295 @@
+import * as React from 'react';
+import { type MPDataTableSort } from '../../internal/data-table.js';
+import type { MPAlign, MPColor, MPDensity, MPElevation, MPSize, MPSlots, MPVariant } from '../../types.js';
+export type { MPDataTableSort, MPSortDirection } from '../../internal/data-table.js';
+/** How many rows may be chosen at once. */
+export type MPDataTableSelectionMode = 'none' | 'single' | 'multiple';
+/** The parts an `MPDataTable` draws that a `className` cannot reach. */
+export type MPDataTableSlot = 'toolbar' | 'table' | 'head' | 'row' | 'cell' | 'footer';
+/**
+ * A column: its heading, how wide it is, how to get a value out of a row and how
+ * to draw one.
+ *
+ * The split between `value` and `render` is the whole shape of this type. A
+ * `render` decides what a reader sees; a `value` decides what the sort and the
+ * search see. Most columns need neither — the cell is `row[key]`, and that is
+ * what is compared and matched. A column that draws an `MPChip` needs `render`,
+ * and it needs `value` as well the moment it is sortable, because a React
+ * element has no order.
+ */
+export interface MPDataTableColumn<Row> {
+    /**
+     * Identifies the column — to `sort`, to `columnWidths`, and unless `value` or
+     * `render` says otherwise, it names the property to read off each row.
+     */
+    key: string;
+    /** The heading. Defaults to the `key`, which is usually not what you want. */
+    label?: React.ReactNode;
+    /**
+     * How wide, in pixels.
+     *
+     * Pixels rather than any CSS length, because a resize drag does arithmetic on
+     * this number. Columns that do not say are `160`, and see `resizable` for what
+     * turning it on does to the layout.
+     */
+    width?: number;
+    /** How narrow a drag may make it. @default 48 */
+    minWidth?: number;
+    /**
+     * Which edge the cells line up against. Numbers usually want `end` so their
+     * digits line up in a column.
+     * @default 'start'
+     */
+    align?: MPAlign;
+    /** Whether this column can be sorted. Defaults to the table's `sortable`. */
+    sortable?: boolean;
+    /** Whether this column can be dragged wider. Defaults to the table's `resizable`. */
+    resizable?: boolean;
+    /** Whether the search looks in this column. @default true */
+    searchable?: boolean;
+    /**
+     * The value behind the cell: what is sorted, and what the search is matched
+     * against. Defaults to `row[key]`.
+     */
+    value?: (row: Row) => unknown;
+    /**
+     * Orders two rows by this column, for a value the default comparison cannot
+     * rank — a status that goes `draft`, `review`, `live` rather than
+     * alphabetically. Always written ascending; the table reverses it.
+     */
+    compare?: (a: Row, b: Row) => number;
+    /**
+     * Draws the cell. `index` is the row's place in the sorted, searched order and
+     * is counted across every page, so `(row, index) => index + 1` is a running
+     * row number.
+     */
+    render?: (row: Row, index: number) => React.ReactNode;
+    /**
+     * What a download writes for this cell.
+     *
+     * Defaults to `value`, and then to `row[key]`. It is separate from `render` on
+     * purpose: a cell that draws a chip, an avatar or a progress bar has no text
+     * to put in a file, and `render`'s return is a React element rather than
+     * something a spreadsheet can hold.
+     */
+    exportValue?: (row: Row) => unknown;
+    /** Leaves this column out of a download. @default true */
+    exportable?: boolean;
+}
+export interface MPDataTableProps<Row> extends Omit<React.ComponentPropsWithoutRef<'div'>, 'color' | 'children' | 'onSelect'> {
+    /** The columns, in the order they appear. */
+    headers: readonly MPDataTableColumn<Row>[];
+    /** The rows. */
+    items: readonly Row[];
+    /**
+     * A stable identity per row, and the value `selected` is a list of.
+     *
+     * Defaults to the row's index in `items`, which is enough for a table that
+     * only ever displays. The moment rows can be chosen, sorted or searched it is
+     * required in practice: an index identifies a position, and every one of those
+     * three changes which row is in it.
+     */
+    getRowKey?: (row: Row, index: number) => React.Key;
+    /** Shown above the table, and read out as its accessible name. */
+    caption?: React.ReactNode;
+    /** What to show instead of rows when nothing is left. */
+    empty?: React.ReactNode;
+    /**
+     * Which language the table's own words are in — the ticks' names, the count
+     * under the rows, the download button.
+     *
+     * It is also what the default sort compares strings with. Pass it whenever the
+     * markup is rendered on a server: without it the comparison follows the
+     * runtime's own locale, and a server that disagrees with the browser about
+     * that produces two different row orders for the same table.
+     */
+    locale?: string;
+    /**
+     * Makes every column sortable. A column overrides it either way with its own
+     * `sortable`.
+     * @default false
+     */
+    sortable?: boolean;
+    /**
+     * Whether more than one column can be sorted at a time. With `multiple`, a
+     * Shift-press adds a column to the sort instead of replacing it, and each
+     * sorted heading carries its place in the order.
+     * @default 'single'
+     */
+    sortMode?: 'single' | 'multiple';
+    /** The sort. Use with `onSortChange` for a controlled one. */
+    sort?: readonly MPDataTableSort[];
+    /** What it starts as, for an uncontrolled table. */
+    defaultSort?: readonly MPDataTableSort[];
+    onSortChange?: (sort: MPDataTableSort[]) => void;
+    /** Draws a field above the table that filters the rows. @default false */
+    searchable?: boolean;
+    /** The query. Use with `onSearchChange` for a controlled field. */
+    search?: string;
+    /** What it starts as, for an uncontrolled one. */
+    defaultSearch?: string;
+    onSearchChange?: (search: string) => void;
+    /**
+     * Overrides the word on the field, which is also its accessible name.
+     *
+     * It is a label rather than a placeholder because a placeholder is not a name:
+     * a field whose only word disappears the moment somebody types in it is a
+     * field a screen reader announces as nothing.
+     */
+    searchLabel?: string;
+    /**
+     * A filter of your own, applied after the search. Return `false` to drop a
+     * row. `index` is the row's place in `items`.
+     */
+    filter?: (row: Row, index: number) => boolean;
+    /** Content at the end of the bar the search field sits in. */
+    toolbar?: React.ReactNode;
+    /**
+     * Hands the rows out a page at a time, and puts the pages in the footer.
+     *
+     * Every row is rendered otherwise, and there is no windowing — the same
+     * ceiling `MPTable` states, and this is the answer to it. A few hundred rows
+     * is nothing, a few thousand is a visible pause, and past that a table wants
+     * either this or a narrower list.
+     * @default false
+     */
+    paged?: boolean;
+    /** The current page, 1-based. Use with `onPageChange`. */
+    page?: number;
+    /** @default 1 */
+    defaultPage?: number;
+    onPageChange?: (page: number) => void;
+    /** How many rows a page holds. Use with `onPageSizeChange`. */
+    pageSize?: number;
+    /** @default 25 */
+    defaultPageSize?: number;
+    onPageSizeChange?: (pageSize: number) => void;
+    /**
+     * What the footer's page-size control offers. An empty list drops the control.
+     * @default [10, 25, 50, 100]
+     */
+    pageSizeOptions?: readonly number[];
+    /**
+     * Lets a heading be dragged wider or narrower, and gives the handle between
+     * two columns to the keyboard as well.
+     *
+     * **It also changes how the columns are laid out, and it has to.** Without it
+     * the browser balances the columns against their contents, which is what makes
+     * a plain table read well; but a balanced column springs back from a drag,
+     * because a width in that layout is a hint rather than a measurement. Turning
+     * this on fixes the layout, so `width` becomes exact and a column that has not
+     * said how wide it is takes 160.
+     * @default false
+     */
+    resizable?: boolean;
+    /** The widths, keyed by column. Use with `onColumnWidthsChange`. */
+    columnWidths?: Readonly<Record<string, number>>;
+    /** What they start as, for an uncontrolled table. */
+    defaultColumnWidths?: Readonly<Record<string, number>>;
+    onColumnWidthsChange?: (widths: Record<string, number>) => void;
+    /**
+     * How many rows may be chosen.
+     * @default 'none'
+     */
+    selectionMode?: MPDataTableSelectionMode;
+    /** The chosen rows, as their keys. Use with `onSelectedChange`. */
+    selected?: readonly React.Key[];
+    /** Which start chosen, for an uncontrolled table. */
+    defaultSelected?: readonly React.Key[];
+    /**
+     * The keys, and the rows behind them — including rows the search has hidden
+     * and rows on other pages, which are still chosen and still have to be handed
+     * back.
+     */
+    onSelectedChange?: (selected: React.Key[], rows: Row[]) => void;
+    /**
+     * Adds a column of ticks, and one in the heading that takes the whole page at
+     * once.
+     *
+     * It also decides which of the row and the tick is the keyboard's route into
+     * the row — see the note on the component.
+     * @default false
+     */
+    checkboxes?: boolean;
+    /** Fires on every press of a row, before the selection changes. */
+    onRowClick?: (row: Row, index: number) => void;
+    /**
+     * Adds a button that writes the rows out as a CSV file.
+     *
+     * **Every row the reader is currently looking at, not the page they are on.**
+     * The search and the sort are applied and the paging is not, because a file of
+     * page three is not a file anybody asked for.
+     * @default false
+     */
+    exportable?: boolean;
+    /** What the downloaded file is called. @default 'table.csv' */
+    exportFileName?: string;
+    /**
+     * Takes the CSV instead of downloading it — to post it somewhere, to open it
+     * in a viewer of your own, or to put a sheet around it.
+     */
+    onExport?: (csv: string) => void;
+    /** Tints every other row. @default false */
+    striped?: boolean;
+    /** Lights the row under the pointer. @default false */
+    hoverable?: boolean;
+    /**
+     * Pins the heading while the body scrolls. Only does anything if something
+     * around the table actually constrains its height.
+     * @default false
+     */
+    stickyHeader?: boolean;
+    /**
+     * How much surface the sheet around the table paints.
+     * @default 'outlined'
+     */
+    variant?: MPVariant;
+    /** How far off the page the sheet is lifted, on MD3's own scale. */
+    elevation?: MPElevation;
+    /** @default 'md' */
+    size?: MPSize;
+    /**
+     * Which accent family the sort arrow, the ticks and a chosen row read. The
+     * cells themselves stay neutral.
+     * @default 'primary'
+     */
+    color?: MPColor;
+    /** Takes room out of every cell without changing what it is set in. @default 0 */
+    density?: MPDensity;
+    classNames?: MPSlots<MPDataTableSlot>;
+}
+/**
+ * A grid of data with the four things a reader does to one: put it in order,
+ * cut it down, step through it and take some of it away.
+ *
+ * ```tsx
+ * <MPDataTable headers={columns} items={rows} sortable searchable paged />
+ * ```
+ *
+ * It is a separate component from [MPTable](table) rather than a mode of it.
+ * `MPTable` is the presentational half: it
+ * draws what it is given, in the order it is given, and a page that only shows a
+ * grid should not carry a comparator, a CSV writer and a page clamp to do it.
+ * What the two do share is the geometry — `internal/table.ts` holds the cells'
+ * room and the type they are set in — so a data table never sits a pixel off the
+ * plain table beside it.
+ *
+ * ## What it does to the rows, and in what order
+ *
+ * Search, then `filter`, then sort, then the page. The order is the only one
+ * that makes each step mean what it says: sorting before searching would order
+ * rows nobody is going to see, and paging before either would cut a page out of
+ * a list the reader has not asked for yet. `render`'s `index` counts along the
+ * sorted, searched order across every page, so it is a running row number rather
+ * than a position on the screen.
+ *
+ * ## Who holds the keyboard
+ *
+ * A row that answers a press has to answer a keyboard, and a table of two
+ * hundred rows that each did would be two hundred tab stops. So there is exactly
+ * one route into a row and `checkboxes` is what picks it: with ticks, the tick
+ * is the control and the row is not in the tab order; without them, the row is.
+ * `onRowClick` on its own always puts the row in the tab order, because then
+ * there is nothing else to press.
+ */
+export declare function MPDataTable<Row>({ headers, items, getRowKey, caption, empty, locale: localeProp, sortable, sortMode, sort: sortProp, defaultSort, onSortChange, searchable, search: searchProp, defaultSearch, onSearchChange, searchLabel, filter, toolbar, paged, page: pageProp, defaultPage, onPageChange, pageSize: pageSizeProp, defaultPageSize, onPageSizeChange, pageSizeOptions, resizable, columnWidths: columnWidthsProp, defaultColumnWidths, onColumnWidthsChange, selectionMode, selected: selectedProp, defaultSelected, onSelectedChange, checkboxes, onRowClick, exportable, exportFileName, onExport, striped, hoverable, stickyHeader, variant, elevation, size: sizeProp, color: colorProp, density: densityProp, className, style, classNames, ...props }: MPDataTableProps<Row>): React.JSX.Element;

package/dist/components/data-table/MPDataTable.js

@@ -0,0 +1,2 @@
+"use client";
+import{jsx as e,jsxs as t}from"react/jsx-runtime";import*as a from"react";import{MPButton as n}from"../button/MPButton.js";import{MPCheckbox as r}from"../checkbox/MPCheckbox.js";import{MPIcon as o}from"../icon/MPIcon.js";import{MPPagination as l}from"../pagination/MPPagination.js";import{MPSelect as s}from"../select/MPSelect.js";import{MPTextField as i}from"../text-field/MPTextField.js";import{ArrowDownIcon as c,ArrowUpIcon as d,SearchIcon as m}from"../../constants/icons.js";import{accentSlots as u}from"../../internal/accent.js";import{containerSurface as p}from"../../internal/elevation.js";import{useMPColor as f,useMPDensity as h,useMPSize as y}from"../../internal/config.js";import{useMPLocale as g,useMPMessages as b}from"../../internal/locale.js";import{fillMessage as v}from"../../internal/i18n.js";import{DATA_TABLE as x}from"../../internal/messages/data-table.js";import{TABLE as k}from"../../internal/messages/table.js";import{TRANSFER as w}from"../../internal/messages/transfer.js";import{CONTROL_ICON as S,META_TEXT as N}from"../../internal/scale.js";import{VISUALLY_HIDDEN as j}from"../../internal/visually-hidden.js";import{CELL_TEXT as C,HEAD_TEXT as z,ROW as _,cellPadX as M,cellPadY as P,drawableCell as L}from"../../internal/table.js";import{DEFAULT_COLUMN_WIDTH as D,MIN_COLUMN_WIDTH as E,compareValues as $,downloadText as A,keysBetween as I,nextSort as K,pageBounds as W,searchHaystack as R,searchText as T,sortRows as B,toCsv as V}from"../../internal/data-table.js";function F(e,t){return e.value?e.value(t):t[e.key]}const H={xs:36,sm:40,md:48,lg:52,xl:60},X=/*@__PURE__*/["group/sort -m-1 flex w-full cursor-pointer items-center gap-1 rounded-mp-xs p-1","appearance-none border-0 bg-transparent font-[inherit] text-inherit text-start","transition-[color] duration-(--mp-sys-motion-duration-short4) ease-mp-standard","hover:text-mp-on-surface","outline-mp-secondary focus-visible:outline-2 focus-visible:outline-offset-1","focus-visible:outline-solid outline-none"].join(" "),O=/*@__PURE__*/["mp-data-table__resize absolute inset-y-0 end-0 z-10 w-2 translate-x-1/2 rtl:-translate-x-1/2","cursor-col-resize touch-none select-none appearance-none border-0 bg-transparent p-0","after:absolute after:inset-y-1 after:start-1/2 after:w-px after:bg-transparent","after:transition-[background-color] after:duration-(--mp-sys-motion-duration-short4)","hover:after:bg-mp-primary data-dragging:after:bg-mp-primary","outline-mp-secondary focus-visible:outline-2 focus-visible:outline-solid outline-none"].join(" ");export function MPDataTable({headers:q,items:G,getRowKey:J,caption:Q,empty:U,locale:Y,sortable:Z=!1,sortMode:ee="single",sort:te,defaultSort:ae,onSortChange:ne,searchable:re=!1,search:oe,defaultSearch:le,onSearchChange:se,searchLabel:ie,filter:ce,toolbar:de,paged:me=!1,page:ue,defaultPage:pe,onPageChange:fe,pageSize:he,defaultPageSize:ye,onPageSizeChange:ge,pageSizeOptions:be=[10,25,50,100],resizable:ve=!1,columnWidths:xe,defaultColumnWidths:ke,onColumnWidthsChange:we,selectionMode:Se="none",selected:Ne,defaultSelected:je,onSelectedChange:Ce,checkboxes:ze=!1,onRowClick:_e,exportable:Me=!1,exportFileName:Pe="table.csv",onExport:Le,striped:De=!1,hoverable:Ee=!1,stickyHeader:$e=!1,variant:Ae="outlined",elevation:Ie,size:Ke,color:We,density:Re,className:Te,style:Be,classNames:Ve,...Fe}){const He=y(Ke),Xe=f(We),Oe=h(Re),qe=g(Y),Ge=b(x,qe),Je=b(k,qe),Qe=b(w,qe),Ue=M(He,Oe),Ye=P(He,Oe),[Ze,et]=a.useState(()=>[...ae??[]]),tt=te??Ze,[at,nt]=a.useState(le??""),rt=oe??at,[ot,lt]=a.useState(pe??1),st=ue??ot,[it,ct]=a.useState(ye??25),dt=he??it,[mt,ut]=a.useState(()=>({...ke})),pt=xe??mt,[ft,ht]=a.useState(()=>[...je??[]]),yt=Ne??ft,gt=a.useMemo(()=>new Set(yt.map(e=>String(e))),[yt]),bt=a.useRef(null),vt=a.useMemo(()=>G.map((e,t)=>{const a=J?J(e,t):t;return{row:e,identity:a,key:String(a),origin:t}}),[G,J]),xt=a.useMemo(()=>{const e=q.filter(e=>!1!==e.searchable);return vt.map(t=>R(e.map(e=>F(e,t.row))))},[vt,q]),kt=T(rt.trim()),wt=a.useMemo(()=>{const e=""===kt?vt:vt.filter((e,t)=>xt[t].includes(kt));return ce?e.filter(e=>ce(e.row,e.origin)):e},[vt,xt,kt,ce]),St=a.useMemo(()=>new Intl.Collator(qe,{numeric:!0,sensitivity:"base"}),[qe]),Nt=a.useMemo(()=>B(wt,tt,(e,t)=>{const a=q.find(t=>t.key===e);if(!a)return null;const n="desc"===t,r=a.compare;return r?(e,t)=>n?-r(e.row,t.row):r(e.row,t.row):(e,t)=>$(F(a,e.row),F(a,t.row),St,n)}),[wt,tt,q,St]),jt=W(Nt.length,st,dt),Ct=me?Nt.slice(jt.start,jt.end):Nt,zt=e=>{void 0===ue&&lt(e),fe?.(e)},_t=e=>{void 0===xe&&ut(e),we?.(e)},Mt=e=>{const t=new Set(e),a=[],n=[];for(const e of vt)t.has(e.key)&&(n.push(e.identity),a.push(e.row));void 0===Ne&&ht(n),Ce?.(n,a)},Pt="none"!==Se,Lt="multiple"===Se,Dt=ze&&Pt,Et=(e,t,a)=>{if(_e?.(e.row,jt.start+t),Pt){if(!Lt)return Mt(gt.has(e.key)?[]:[e.key]),void(bt.current=e.key);if(a&&null!==bt.current){const t=I(Ct.map(e=>e.key),bt.current,e.key);return void Mt([...new Set([...gt,...t])])}bt.current=e.key,Mt(gt.has(e.key)?[...gt].filter(t=>t!==e.key):[...gt,e.key])}},$t=Ct.map(e=>e.key),At=$t.filter(e=>gt.has(e)).length,It=$t.length>0&&At===$t.length,Kt=e=>pt[e.key]??e.width??D,Wt=a.useRef(null);a.useEffect(()=>()=>{null!==Wt.current&&(document.body.style.userSelect=Wt.current,Wt.current=null)},[]);const Rt=(e,t)=>{const a=Math.max(E,e.minWidth??E);_t({...pt,[e.key]:Math.max(a,Kt(e)+t)})},Tt=e=>{const t={...pt};delete t[e.key],_t(t)},Bt={padding:`${Ye} ${Ue}`},Vt={...Bt,backgroundColor:"var(--_mp-color-surface-container)"},Ft={borderTop:"1px solid var(--_mp-color-outline-variant)",backgroundColor:"var(--_mp-row)"},Ht=q.length+(Dt?1:0),Xt=Boolean(_e)||Pt&&!Dt,Ot=Ee||Pt||Boolean(_e),qt=re||Me||void 0!==de,Gt=me||Pt,Jt=(...e)=>e.filter(Boolean).join(" ");return t("div",{"data-mp-size":He,"data-mp-variant":Ae,className:Jt("mp-data-table rounded-mp-md flex flex-col",p(Ae,Ie),Te),style:{...u(Xe),...Be},...Fe,children:[qt?t("div",{className:Jt("mp-data-table__toolbar flex flex-wrap items-center gap-2",Ve?.toolbar),style:{padding:`${Ye} ${Ue}`},children:[re?e(i,{size:He,value:rt,onChange:e=>{void 0===oe&&nt(e),zt(1),se?.(e)},label:ie??Qe.search,startIcon:e(o,{icon:m,size:S[He]}),className:"mp-data-table__search min-w-0 flex-1"}):e("div",{className:"min-w-0 flex-1"}),de,Me?e(n,{size:He,variant:"text",color:Xe,onClick:()=>{const e=q.filter(e=>!1!==e.exportable),t=e.map(e=>"string"==typeof e.label?e.label:e.key),a=Nt.map(t=>e.map(e=>e.exportValue?e.exportValue(t.row):F(e,t.row))),n=V([t,...a]);Le?Le(n):A(n,Pe,"text/csv;charset=utf-8")},startIcon:e(o,{icon:c,size:S[He]}),children:Ge.download}):null]}):null,e("div",{className:"mp-data-table__scroll min-h-0 flex-1 overflow-auto",children:t("table",{className:Jt("text-mp-on-surface w-full text-start",C[He],Ve?.table),style:{borderCollapse:"collapse",...ve?{tableLayout:"fixed",minWidth:q.reduce((e,t)=>e+Kt(t),Dt?H[He]:0)}:void 0},children:[Q?e("caption",{className:`text-mp-on-surface-variant ${N}`,style:{...Bt,textAlign:"start"},children:Q}):null,t("colgroup",{children:[Dt?e("col",{style:{width:H[He]}}):null,q.map(t=>e("col",{style:ve||void 0!==pt[t.key]||void 0!==t.width?{width:Kt(t)}:void 0},t.key))]}),e("thead",{className:Ve?.head,children:t("tr",{children:[Dt?e("th",{scope:"col",className:Jt("whitespace-nowrap",$e&&"sticky top-0 z-20"),style:Vt,children:e(r,{size:He,color:Xe,checked:It,indeterminate:At>0&&!It,onCheckedChange:()=>{Mt(It?[...gt].filter(e=>!$t.includes(e)):[...new Set([...gt,...$t])])},label:e("span",{className:j,children:Ge.selectAll}),disabled:!Lt||0===$t.length})}):null,q.map(a=>{const n=a.sortable??Z,r=(l=a.key,tt.findIndex(e=>e.key===l));var l;const s=-1===r?void 0:tt[r],i=a.resizable??ve,c=a.align??"start";return t("th",{scope:"col","aria-sort":n?void 0===s?"none":"asc"===s.direction?"ascending":"descending":void 0,className:Jt("text-mp-on-surface-variant relative whitespace-nowrap",z[He],$e&&"sticky top-0 z-10"),style:{...Vt,textAlign:c},children:[n?t("button",{type:"button",className:Jt(X,"end"===c&&"justify-end","center"===c&&"justify-center"),onClick:e=>((e,t)=>{const a=K(tt,e,t&&"multiple"===ee);void 0===te&&et(a),ne?.(a)})(a.key,e.shiftKey),children:[e("span",{className:"min-w-0 truncate",children:a.label??a.key}),e(o,{icon:d,size:S[He]-6,className:Jt("shrink-0 transition-[rotate,opacity]","duration-(--mp-sys-motion-duration-short4) ease-mp-standard",void 0===s?"opacity-0 group-hover/sort:opacity-38":"text-mp-primary opacity-100","desc"===s?.direction&&"rotate-180")}),tt.length>1&&-1!==r?e("span",{className:"text-mp-primary shrink-0 tabular-nums",children:r+1}):null]}):a.label??a.key,i?e("button",{type:"button","aria-label":Ge.resize,className:O,onPointerDown:e=>((e,t)=>{const a=t.currentTarget;try{a.setPointerCapture(t.pointerId)}catch{}a.dataset.dragging="true";const n=document.body.style.userSelect;Wt.current=n,document.body.style.userSelect="none";const r=t.clientX,o=Kt(e),l="rtl"===getComputedStyle(a).direction?-1:1,s=Math.max(E,e.minWidth??E),i=t=>{_t({...pt,[e.key]:Math.max(s,Math.round(o+(t.clientX-r)*l))})},c=()=>{a.removeEventListener("pointermove",i),a.removeEventListener("pointerup",c),a.removeEventListener("pointercancel",c),delete a.dataset.dragging,null!==Wt.current&&(document.body.style.userSelect=Wt.current,Wt.current=null)};a.addEventListener("pointermove",i),a.addEventListener("pointerup",c),a.addEventListener("pointercancel",c)})(a,e),onDoubleClick:()=>Tt(a),onKeyDown:e=>{const t=e.shiftKey?32:8;"ArrowRight"===e.key?(e.preventDefault(),Rt(a,t)):"ArrowLeft"===e.key?(e.preventDefault(),Rt(a,-t)):"Home"===e.key&&(e.preventDefault(),Tt(a))}}):null]},a.key)})]})}),e("tbody",{children:0===Ct.length?e("tr",{className:_,style:Ft,children:e("td",{colSpan:Ht,className:"text-mp-on-surface-variant",style:{padding:`2rem ${Ue}`,textAlign:"center"},children:U??Je.empty})}):Ct.map((a,n)=>{const o=gt.has(a.key);return t("tr",{"aria-selected":Pt?o:void 0,className:Jt(_,Ve?.row,De&&(jt.start+n)%2==1?"[--_mp-row:var(--_mp-color-surface-container-low)]":"",o?"[--_mp-row:var(--_mp-color-secondary-container)]":"",Ot&&!o?"hover:[--_mp-row:var(--_mp-color-surface-container)]":"",(Pt||_e)&&"cursor-pointer",Xt&&["outline-mp-secondary focus-visible:outline-2","focus-visible:-outline-offset-2 focus-visible:outline-solid outline-none"].join(" ")),style:Ft,tabIndex:Xt?0:void 0,onClick:e=>Et(a,n,e.shiftKey),onKeyDown:Xt?e=>{"Enter"!==e.key&&" "!==e.key||e.target===e.currentTarget&&(e.preventDefault(),Et(a,n,e.shiftKey))}:void 0,children:[Dt?e("td",{style:Bt,children:e(r,{size:He,color:Xe,checked:o,onCheckedChange:()=>Et(a,n,!1),label:e("span",{className:j,children:Ge.selectRow})})}):null,q.map(t=>e("td",{className:Ve?.cell,style:{...Bt,textAlign:t.align??"start"},children:t.render?t.render(a.row,jt.start+n):L(F(t,a.row))},t.key))]},a.key)})})]})}),Gt?t("div",{className:Jt("mp-data-table__footer border-mp-outline-variant flex flex-wrap items-center gap-3","text-mp-on-surface-variant border-t",N,Ve?.footer),style:{padding:`${Ye} ${Ue}`},children:[e("span",{className:"mp-data-table__count",children:v(Ge.total,{total:String(Nt.length)})}),gt.size>0?e("span",{className:"mp-data-table__selected text-mp-primary",children:v(Ge.selected,{count:String(gt.size)})}):null,e("span",{className:"flex-1"}),me&&be.length>0?e(s,{size:"xs",label:Ge.perPage,floatingLabel:!1,value:dt,onValueChange:e=>(e=>{void 0===he&&ct(e),zt(1),ge?.(e)})(Number(e)),items:be.map(e=>({value:e})),className:"mp-data-table__page-size",style:{minWidth:"9.5rem"}}):null,me?e(l,{size:"xs",color:Xe,count:jt.pages,page:jt.page,onPageChange:zt,locale:qe}):null]}):null]})}

package/dist/components/data-table/index.d.ts

@@ -0,0 +1,2 @@
+export { MPDataTable } from './MPDataTable.js';
+export type { MPDataTableColumn, MPDataTableProps, MPDataTableSelectionMode, MPDataTableSlot, MPDataTableSort, MPSortDirection } from './MPDataTable.js';

package/dist/components/data-table/index.js

@@ -0,0 +1 @@
+export{MPDataTable}from"./MPDataTable.js";