twico-ui 1.43.0 → 1.45.0

package/dist/index.d.cts

@@ -1951,6 +1951,65 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  This prop is the initial state — when enabled, users can hide/show the column from the toolbar's
    *  **Columns** panel ("Row number"). @default false */
   rowNumbers?: boolean;
+  /**
+   * #481: style a whole row from its own state — the row-level counterpart to a column's `cellStyle`.
+   * Without it, marking a row meant assigning `cellStyle` to **every** column: O(columns) for a
+   * row-level fact, hand-composed against whatever else already used `cellStyle`, and with no fixed
+   * column list to decorate at all when the columns come from a schema.
+   *
+   * Called `(row, index)`, the same shape as `rowKey`. **`index` is the row's 0-based position among
+   * the rows currently rendered** — after sorting and filtering, and **within the current page**. It is
+   * therefore *not* the number the `rowNumbers` column shows, which continues across pages; if you need
+   * an absolute position, read it off `row` rather than from this argument.
+   *
+   * A `background` (or `backgroundColor`) is forwarded to the row's CELLS through the `--twc-dt-row-bg`
+   * custom property, because `.twc-dt__td` paints an opaque surface of its own — without that it would
+   * be invisible — and is **removed** from what reaches the `<tr>`, since a row box paints below its
+   * cells and a leftover copy there would composite with the tint rather than hide behind it. Every
+   * other declaration lands on the `<tr>`, except `border` (ignored on row boxes under
+   * `border-collapse: separate`) and `backgroundImage` (painted under the cells' opaque surface) — both
+   * need {@link getRowClassName} and a `… .twc-dt__td` rule. Sticky positioning and measured row height
+   * are applied after yours, so a hook cannot break row pinning or row resizing.
+   *
+   * **Layering — one rule, not a bespoke order:** the row tint is the **bottom** layer above the
+   * cell's plain surface, and **every** built-in state background covers it. The base `.twc-dt__td`
+   * rule is the lowest-specificity background in the component, so hover, row selection,
+   * `activeRowId`, a pinned row, a grabbed row, the diff add/remove/modify washes, cell
+   * selection/active and inline editing all outrank it — and an inline per-cell `cellStyle` outranks
+   * those. A row tint is a *data-derived* wash; nothing data-derived should be able to hide an
+   * interaction state. So selection still reads on a tinted row, hover feedback is never lost, and a
+   * per-cell state wins with nothing to compose on your side.
+   *
+   * Need a tint that survives hover? Use {@link getRowClassName} with a rule outranking `(0,3,0)` —
+   * note `.twc-dt__row.my-row .twc-dt__td` is itself `(0,3,0)`, a tie decided by source order, so add
+   * an element: `tr.twc-dt__row.my-row .twc-dt__td` is `(0,3,1)`, and `… .twc-dt__td[data-pin]` is
+   * `(0,4,1)` for the pinned-column twins. You are then choosing to cover the hover cue on those rows.
+   *
+   * **Stripes:** there are none to layer against. Datatable does not zebra-stripe its data rows —
+   * the only `data-zebra` rules in the component style the PIVOT grid's cells, and the hook does not
+   * apply to pivot rows. So a row tint never has to compete with a stripe.
+   *
+   * **Which rows:** every data row. That includes rows pinned with the row ⋮ menu (the hook runs and
+   * the class/non-background declarations apply, though the pinned-row highlight covers a background
+   * tint for as long as the row is pinned, exactly like selection), and cells in a pinned COLUMN pick
+   * the tint up, so a tinted row shows no hole where a frozen column scrolls over it. NOT group-header
+   * rows or the pivot grid's aggregate rows: those have no `row` object to pass. Skeleton rows shown
+   * while `loading` are untouched.
+   */
+  getRowStyle?: (row: T, index: number) => React.CSSProperties | undefined;
+  /**
+   * #481: a class on the row's `<tr>`, appended to `twc-dt__row` (never replacing it). Same
+   * `(row, index)` signature as {@link getRowStyle}.
+   *
+   * **Which to reach for.** `getRowStyle` is the default: its *background* does not land inline on the
+   * cells — it is routed through `--twc-dt-row-bg` and read by the `(0,1,0)` base rule, so it is the
+   * **lowest** layer and every built-in state covers it, which is almost always what a row tint should
+   * do. (Its *non-background* declarations — opacity, font-weight, text-decoration — are ordinary
+   * inline styles on the `<tr>` and do win.) Reach for `getRowClassName` when you deliberately want the
+   * tint to **outrank** those cues, since your own rule picks its specificity: beat `(0,3,0)`, e.g.
+   * `tr.twc-dt__row.my-row .twc-dt__td`. You are then choosing to cover the hover cue on those rows.
+   */
+  getRowClassName?: (row: T, index: number) => string | undefined;
   /** Restrict the toolbar quick-search to these column `field`s (client mode); defaults to every
    *  visible column. Mirrors `runDatatableQuery`'s `options.searchFields`. */
   searchFields?: string[];
@@ -2624,6 +2683,20 @@ interface DatatableBatchAction<T = any> {
   /** #322: hide the action entirely when the predicate returns true (e.g. `(_, rows) => rows.every(r => r.isGroup)`
    *  drops "Mark as new thread" when only group rows are selected). A static `true` always hides it. */
   hidden?: boolean | ((keys: Array<string | number>, rows: T[]) => boolean);
+  /** #479: why the action is disabled, shown as the button's tooltip — the batch mirror of the row-action
+   *  `disabledReason` (#399/#419). It may be a **predicate over the selection**, because that is where the
+   *  answer usually lives: a batch is refused for selection-dependent reasons ("that selection is 5.1 GB; the
+   *  limit is 4 GB", "at most 50 items per batch") that the label cannot carry and the user cannot infer from
+   *  a greyed-out button.
+   *
+   *  When a reason is present the button renders `aria-disabled` rather than native `disabled`, so it stays in
+   *  the tab order and the reason is reachable by hover AND keyboard; click and Enter/Space stay blocked. With
+   *  no reason the tooltip would only repeat the label, so the button stays natively disabled and out of the
+   *  tab order — the same rule as the row-action path. There is deliberately no `hiddenReason`: a hidden
+   *  action explains nothing. */
+  disabledReason?:
+    | React.ReactNode
+    | ((keys: Array<string | number>, rows: T[]) => React.ReactNode);
 }
 
 declare function Datatable<T = any>(props: DatatableProps<T>): React.JSX.Element;
@@ -2688,8 +2761,19 @@ interface CardGridSortOption {
 interface CardGridProps<Row = any> extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
   /** The rows: the full set in client mode, or the current page in `serverMode`. */
   rows?: Row[];
-  /** Render one card for a row. Required. */
-  renderCard: (row: Row, index: number) => React.ReactNode;
+  /**
+   * Render one card for a row. Required.
+   *
+   * #478: with `checkboxSelection`, the third argument carries that card's selection state so a
+   * consumer can put the control inside their own layout (set `selectionPlacement="none"` to drop the
+   * grid's overlay) without re-implementing any selection state. It is `undefined` when
+   * `checkboxSelection` is off.
+   */
+  renderCard: (
+    row: Row,
+    index: number,
+    selection?: { selected: boolean; toggle: () => void },
+  ) => React.ReactNode;
   /** Stable key per row: a field name or an accessor. @default "id" */
   rowKey?: string | ((row: Row) => React.Key);
   /** Min card width for the responsive auto-fill grid (Grid `minChildWidth`). @default "18rem" */
@@ -2752,6 +2836,86 @@ interface CardGridProps<Row = any> extends Omit<React.HTMLAttributes<HTMLDivElem
   emptyState?: React.ReactNode;
   /** Optional heading above the grid. */
   label?: React.ReactNode;
+
+  /**
+   * #478: show a selection checkbox on each card and a selection toolbar when anything is picked —
+   * the same prop name, and the same behaviour, as `Datatable`. A card grid is what you reach for
+   * when the rows are visual (assets, previews, renders), where "pick several and do one thing to
+   * them" is most of the point.
+   * @default false
+   */
+  checkboxSelection?: boolean;
+  /**
+   * Actions shown in the selection toolbar, with the same shape as `DatatableBatchAction` — including
+   * `disabled` / `hidden` / `disabledReason` as predicates over the current selection (#479), and
+   * `ctx.anchorEl` so an action can anchor a popover to its own button.
+   */
+  batchActions?: CardGridBatchAction<Row>[];
+  /** Fired when the selection changes — `(keys, rows)`, matching `Datatable.onRowSelectionChange`. */
+  onRowSelectionChange?: (keys: Array<string | number>, rows: Row[]) => void;
+  /**
+   * Where the grid draws its checkbox over each card. `"none"` suppresses the overlay entirely for
+   * consumers who render the control themselves from `renderCard`'s third argument.
+   * @default "top-start"
+   */
+  selectionPlacement?: "top-start" | "top-end" | "bottom-start" | "bottom-end" | "none";
+  /**
+   * Per-card `aria-label` for the checkbox. Worth setting: unlike a table row, a card's own content is
+   * not necessarily announced with the control, so the default `"Select item"` is the same for every
+   * card. @default (row, index) => "Select item"
+   */
+  selectionLabel?: (row: Row, index: number) => string;
+  /** Show the page-scoped "Select all on this page" control. @default true */
+  showSelectAll?: boolean;
+  /**
+   * Retain the row OBJECTS of off-page selections so `batchActions` and `onRowSelectionChange` receive
+   * them for a selection spanning several pages. `keys` is always the authoritative cross-page
+   * selection (as in `Datatable`); this exists because the grid only renders one page, which is the
+   * `Map<id, row>` consumers were otherwise hand-rolling.
+   *
+   * Opt-in because it holds references the host may expect to be released, and **bounded**: `true`
+   * retains up to 1000 rows, or pass a number for your own cap. Past the cap it stops retaining and
+   * those keys simply resolve to nothing in `rows`, so re-fetch by key.
+   * @default false
+   */
+  retainSelectedRows?: boolean | number;
+}
+
+/** Extra context handed to a CardGrid batch action's `onClick`. */
+interface CardGridBatchActionContext {
+  /** The toolbar button that was clicked — anchor a popover or panel to it. */
+  anchorEl: HTMLElement;
+}
+
+/** A batch action shown in CardGrid's selection toolbar. Mirrors `DatatableBatchAction`. */
+interface CardGridBatchAction<Row = any> {
+  /** Button label. */
+  label: string;
+  /** Leading icon node. */
+  icon?: React.ReactNode;
+  /** Handler: `(selectedKeys, selectedRows, clearSelection, ctx)`. */
+  onClick?: (
+    keys: Array<string | number>,
+    rows: Row[],
+    clearSelection: () => void,
+    ctx: CardGridBatchActionContext,
+  ) => void;
+  /** Render in danger color. */
+  danger?: boolean;
+  /** Disable the action — a static boolean, or a predicate over the current selection. */
+  disabled?: boolean | ((keys: Array<string | number>, rows: Row[]) => boolean);
+  /** Hide the action entirely — a static boolean, or a predicate over the current selection. */
+  hidden?: boolean | ((keys: Array<string | number>, rows: Row[]) => boolean);
+  /**
+   * Why the action is disabled, shown as the button's tooltip (#479). May be a predicate over the
+   * selection, because that is usually where the answer lives ("that selection is 5.1 GB; the limit is
+   * 4 GB"). With a reason present the button renders `aria-disabled` rather than native `disabled`, so
+   * it stays focusable and the reason is keyboard-reachable; without one it stays natively disabled and
+   * out of the tab order.
+   */
+  disabledReason?:
+    | React.ReactNode
+    | ((keys: Array<string | number>, rows: Row[]) => React.ReactNode);
 }
 
 declare function CardGrid<Row = any>(props: CardGridProps<Row>): React.JSX.Element;
@@ -4961,4 +5125,4 @@ declare function useFilePicker(options?: UseFilePickerOptions): {
   getInputProps: () => React.InputHTMLAttributes<HTMLInputElement> & { ref: React.RefObject<HTMLInputElement | null> };
 };
 
-export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableBatchUpdateDetail, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableState, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, ImageViewer, type ImageViewerControlsApi, type ImageViewerProps, type ImageViewerState, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, ToggleGroup, type ToggleGroupItem, type ToggleGroupProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFilePickerOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseLocalStorageOptions, type UseMediaQueryOptions, type UseWindowSizeOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFilePicker, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridBatchAction, type CardGridBatchActionContext, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableBatchUpdateDetail, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableState, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, ImageViewer, type ImageViewerControlsApi, type ImageViewerProps, type ImageViewerState, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, ToggleGroup, type ToggleGroupItem, type ToggleGroupProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFilePickerOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseLocalStorageOptions, type UseMediaQueryOptions, type UseWindowSizeOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFilePicker, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };

package/dist/index.d.ts

@@ -1951,6 +1951,65 @@ interface DatatableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivEleme
    *  This prop is the initial state — when enabled, users can hide/show the column from the toolbar's
    *  **Columns** panel ("Row number"). @default false */
   rowNumbers?: boolean;
+  /**
+   * #481: style a whole row from its own state — the row-level counterpart to a column's `cellStyle`.
+   * Without it, marking a row meant assigning `cellStyle` to **every** column: O(columns) for a
+   * row-level fact, hand-composed against whatever else already used `cellStyle`, and with no fixed
+   * column list to decorate at all when the columns come from a schema.
+   *
+   * Called `(row, index)`, the same shape as `rowKey`. **`index` is the row's 0-based position among
+   * the rows currently rendered** — after sorting and filtering, and **within the current page**. It is
+   * therefore *not* the number the `rowNumbers` column shows, which continues across pages; if you need
+   * an absolute position, read it off `row` rather than from this argument.
+   *
+   * A `background` (or `backgroundColor`) is forwarded to the row's CELLS through the `--twc-dt-row-bg`
+   * custom property, because `.twc-dt__td` paints an opaque surface of its own — without that it would
+   * be invisible — and is **removed** from what reaches the `<tr>`, since a row box paints below its
+   * cells and a leftover copy there would composite with the tint rather than hide behind it. Every
+   * other declaration lands on the `<tr>`, except `border` (ignored on row boxes under
+   * `border-collapse: separate`) and `backgroundImage` (painted under the cells' opaque surface) — both
+   * need {@link getRowClassName} and a `… .twc-dt__td` rule. Sticky positioning and measured row height
+   * are applied after yours, so a hook cannot break row pinning or row resizing.
+   *
+   * **Layering — one rule, not a bespoke order:** the row tint is the **bottom** layer above the
+   * cell's plain surface, and **every** built-in state background covers it. The base `.twc-dt__td`
+   * rule is the lowest-specificity background in the component, so hover, row selection,
+   * `activeRowId`, a pinned row, a grabbed row, the diff add/remove/modify washes, cell
+   * selection/active and inline editing all outrank it — and an inline per-cell `cellStyle` outranks
+   * those. A row tint is a *data-derived* wash; nothing data-derived should be able to hide an
+   * interaction state. So selection still reads on a tinted row, hover feedback is never lost, and a
+   * per-cell state wins with nothing to compose on your side.
+   *
+   * Need a tint that survives hover? Use {@link getRowClassName} with a rule outranking `(0,3,0)` —
+   * note `.twc-dt__row.my-row .twc-dt__td` is itself `(0,3,0)`, a tie decided by source order, so add
+   * an element: `tr.twc-dt__row.my-row .twc-dt__td` is `(0,3,1)`, and `… .twc-dt__td[data-pin]` is
+   * `(0,4,1)` for the pinned-column twins. You are then choosing to cover the hover cue on those rows.
+   *
+   * **Stripes:** there are none to layer against. Datatable does not zebra-stripe its data rows —
+   * the only `data-zebra` rules in the component style the PIVOT grid's cells, and the hook does not
+   * apply to pivot rows. So a row tint never has to compete with a stripe.
+   *
+   * **Which rows:** every data row. That includes rows pinned with the row ⋮ menu (the hook runs and
+   * the class/non-background declarations apply, though the pinned-row highlight covers a background
+   * tint for as long as the row is pinned, exactly like selection), and cells in a pinned COLUMN pick
+   * the tint up, so a tinted row shows no hole where a frozen column scrolls over it. NOT group-header
+   * rows or the pivot grid's aggregate rows: those have no `row` object to pass. Skeleton rows shown
+   * while `loading` are untouched.
+   */
+  getRowStyle?: (row: T, index: number) => React.CSSProperties | undefined;
+  /**
+   * #481: a class on the row's `<tr>`, appended to `twc-dt__row` (never replacing it). Same
+   * `(row, index)` signature as {@link getRowStyle}.
+   *
+   * **Which to reach for.** `getRowStyle` is the default: its *background* does not land inline on the
+   * cells — it is routed through `--twc-dt-row-bg` and read by the `(0,1,0)` base rule, so it is the
+   * **lowest** layer and every built-in state covers it, which is almost always what a row tint should
+   * do. (Its *non-background* declarations — opacity, font-weight, text-decoration — are ordinary
+   * inline styles on the `<tr>` and do win.) Reach for `getRowClassName` when you deliberately want the
+   * tint to **outrank** those cues, since your own rule picks its specificity: beat `(0,3,0)`, e.g.
+   * `tr.twc-dt__row.my-row .twc-dt__td`. You are then choosing to cover the hover cue on those rows.
+   */
+  getRowClassName?: (row: T, index: number) => string | undefined;
   /** Restrict the toolbar quick-search to these column `field`s (client mode); defaults to every
    *  visible column. Mirrors `runDatatableQuery`'s `options.searchFields`. */
   searchFields?: string[];
@@ -2624,6 +2683,20 @@ interface DatatableBatchAction<T = any> {
   /** #322: hide the action entirely when the predicate returns true (e.g. `(_, rows) => rows.every(r => r.isGroup)`
    *  drops "Mark as new thread" when only group rows are selected). A static `true` always hides it. */
   hidden?: boolean | ((keys: Array<string | number>, rows: T[]) => boolean);
+  /** #479: why the action is disabled, shown as the button's tooltip — the batch mirror of the row-action
+   *  `disabledReason` (#399/#419). It may be a **predicate over the selection**, because that is where the
+   *  answer usually lives: a batch is refused for selection-dependent reasons ("that selection is 5.1 GB; the
+   *  limit is 4 GB", "at most 50 items per batch") that the label cannot carry and the user cannot infer from
+   *  a greyed-out button.
+   *
+   *  When a reason is present the button renders `aria-disabled` rather than native `disabled`, so it stays in
+   *  the tab order and the reason is reachable by hover AND keyboard; click and Enter/Space stay blocked. With
+   *  no reason the tooltip would only repeat the label, so the button stays natively disabled and out of the
+   *  tab order — the same rule as the row-action path. There is deliberately no `hiddenReason`: a hidden
+   *  action explains nothing. */
+  disabledReason?:
+    | React.ReactNode
+    | ((keys: Array<string | number>, rows: T[]) => React.ReactNode);
 }
 
 declare function Datatable<T = any>(props: DatatableProps<T>): React.JSX.Element;
@@ -2688,8 +2761,19 @@ interface CardGridSortOption {
 interface CardGridProps<Row = any> extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange"> {
   /** The rows: the full set in client mode, or the current page in `serverMode`. */
   rows?: Row[];
-  /** Render one card for a row. Required. */
-  renderCard: (row: Row, index: number) => React.ReactNode;
+  /**
+   * Render one card for a row. Required.
+   *
+   * #478: with `checkboxSelection`, the third argument carries that card's selection state so a
+   * consumer can put the control inside their own layout (set `selectionPlacement="none"` to drop the
+   * grid's overlay) without re-implementing any selection state. It is `undefined` when
+   * `checkboxSelection` is off.
+   */
+  renderCard: (
+    row: Row,
+    index: number,
+    selection?: { selected: boolean; toggle: () => void },
+  ) => React.ReactNode;
   /** Stable key per row: a field name or an accessor. @default "id" */
   rowKey?: string | ((row: Row) => React.Key);
   /** Min card width for the responsive auto-fill grid (Grid `minChildWidth`). @default "18rem" */
@@ -2752,6 +2836,86 @@ interface CardGridProps<Row = any> extends Omit<React.HTMLAttributes<HTMLDivElem
   emptyState?: React.ReactNode;
   /** Optional heading above the grid. */
   label?: React.ReactNode;
+
+  /**
+   * #478: show a selection checkbox on each card and a selection toolbar when anything is picked —
+   * the same prop name, and the same behaviour, as `Datatable`. A card grid is what you reach for
+   * when the rows are visual (assets, previews, renders), where "pick several and do one thing to
+   * them" is most of the point.
+   * @default false
+   */
+  checkboxSelection?: boolean;
+  /**
+   * Actions shown in the selection toolbar, with the same shape as `DatatableBatchAction` — including
+   * `disabled` / `hidden` / `disabledReason` as predicates over the current selection (#479), and
+   * `ctx.anchorEl` so an action can anchor a popover to its own button.
+   */
+  batchActions?: CardGridBatchAction<Row>[];
+  /** Fired when the selection changes — `(keys, rows)`, matching `Datatable.onRowSelectionChange`. */
+  onRowSelectionChange?: (keys: Array<string | number>, rows: Row[]) => void;
+  /**
+   * Where the grid draws its checkbox over each card. `"none"` suppresses the overlay entirely for
+   * consumers who render the control themselves from `renderCard`'s third argument.
+   * @default "top-start"
+   */
+  selectionPlacement?: "top-start" | "top-end" | "bottom-start" | "bottom-end" | "none";
+  /**
+   * Per-card `aria-label` for the checkbox. Worth setting: unlike a table row, a card's own content is
+   * not necessarily announced with the control, so the default `"Select item"` is the same for every
+   * card. @default (row, index) => "Select item"
+   */
+  selectionLabel?: (row: Row, index: number) => string;
+  /** Show the page-scoped "Select all on this page" control. @default true */
+  showSelectAll?: boolean;
+  /**
+   * Retain the row OBJECTS of off-page selections so `batchActions` and `onRowSelectionChange` receive
+   * them for a selection spanning several pages. `keys` is always the authoritative cross-page
+   * selection (as in `Datatable`); this exists because the grid only renders one page, which is the
+   * `Map<id, row>` consumers were otherwise hand-rolling.
+   *
+   * Opt-in because it holds references the host may expect to be released, and **bounded**: `true`
+   * retains up to 1000 rows, or pass a number for your own cap. Past the cap it stops retaining and
+   * those keys simply resolve to nothing in `rows`, so re-fetch by key.
+   * @default false
+   */
+  retainSelectedRows?: boolean | number;
+}
+
+/** Extra context handed to a CardGrid batch action's `onClick`. */
+interface CardGridBatchActionContext {
+  /** The toolbar button that was clicked — anchor a popover or panel to it. */
+  anchorEl: HTMLElement;
+}
+
+/** A batch action shown in CardGrid's selection toolbar. Mirrors `DatatableBatchAction`. */
+interface CardGridBatchAction<Row = any> {
+  /** Button label. */
+  label: string;
+  /** Leading icon node. */
+  icon?: React.ReactNode;
+  /** Handler: `(selectedKeys, selectedRows, clearSelection, ctx)`. */
+  onClick?: (
+    keys: Array<string | number>,
+    rows: Row[],
+    clearSelection: () => void,
+    ctx: CardGridBatchActionContext,
+  ) => void;
+  /** Render in danger color. */
+  danger?: boolean;
+  /** Disable the action — a static boolean, or a predicate over the current selection. */
+  disabled?: boolean | ((keys: Array<string | number>, rows: Row[]) => boolean);
+  /** Hide the action entirely — a static boolean, or a predicate over the current selection. */
+  hidden?: boolean | ((keys: Array<string | number>, rows: Row[]) => boolean);
+  /**
+   * Why the action is disabled, shown as the button's tooltip (#479). May be a predicate over the
+   * selection, because that is usually where the answer lives ("that selection is 5.1 GB; the limit is
+   * 4 GB"). With a reason present the button renders `aria-disabled` rather than native `disabled`, so
+   * it stays focusable and the reason is keyboard-reachable; without one it stays natively disabled and
+   * out of the tab order.
+   */
+  disabledReason?:
+    | React.ReactNode
+    | ((keys: Array<string | number>, rows: Row[]) => React.ReactNode);
 }
 
 declare function CardGrid<Row = any>(props: CardGridProps<Row>): React.JSX.Element;
@@ -4961,4 +5125,4 @@ declare function useFilePicker(options?: UseFilePickerOptions): {
   getInputProps: () => React.InputHTMLAttributes<HTMLInputElement> & { ref: React.RefObject<HTMLInputElement | null> };
 };
 
-export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableBatchUpdateDetail, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableState, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, ImageViewer, type ImageViewerControlsApi, type ImageViewerProps, type ImageViewerState, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, ToggleGroup, type ToggleGroupItem, type ToggleGroupProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFilePickerOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseLocalStorageOptions, type UseMediaQueryOptions, type UseWindowSizeOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFilePicker, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };
+export { Accordion, type AccordionItem, type AccordionProps, type ActionTone, Alert, type AlertProps, Anchor, type AnchorProps, AppShell, type AppShellProps, Avatar, AvatarMenu, type AvatarMenuProps, type AvatarProps, Badge, type BadgeProps, type BarTone, Box, type BoxOwnProps, type BoxProps, Boxplot, type BoxplotDatum, type BoxplotProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, BubbleChart, type BubbleChartProps, Button, type ButtonProps, Candlestick, type CandlestickDatum, type CandlestickProps, Card, CardGrid, type CardGridBatchAction, type CardGridBatchActionContext, type CardGridFilter, type CardGridProps, type CardGridQuery, type CardGridSort, type CardGridSortOption, type CardProps, Carousel, type CarouselProps, Chart, type ChartDatum, type ChartProps, Checkbox, type CheckboxProps, Code, type CodeProps, ColorPicker, type ColorPickerProps, ColorSchemeScript, type ColorSchemeScriptOptions, type ColorSchemeScriptProps, Combobox, type ComboboxGroup, type ComboboxOption, type ComboboxProps, type Command, CommandPalette, type CommandPaletteProps, Container, type ContainerOwnProps, type ContainerProps, Currency, CurrencyField, type CurrencyFieldProps, type CurrencyOption, type CurrencyProps, Datatable, type DatatableBatchAction, type DatatableBatchActionContext, type DatatableBatchUpdateDetail, type DatatableColumn, type DatatableFilter, type DatatableFilterOp, type DatatableNumberOp, type DatatableProps, type DatatableQuery, type DatatableRowAction, type DatatableState, type DatatableStringOp, DatePicker, type DatePickerProps, type DateRange, DateRangePicker, type DateRangePickerProps, DateTimePicker, type DateTimePickerProps, Dialog, type DialogProps, type DiffOp, DiffTable, type DiffTableColumn, type DiffTableProps, Divider, type DividerProps, DonutChart, type DonutChartDatum, type DonutChartProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, Field, type FieldProps, FileUpload, type FileUploadProps, FilterBar, type FilterBarProps, type FilterClause, type FilterField, type FilterFieldType, type FilterValues, Form, type FormProps, FunnelChart, type FunnelChartProps, type FunnelDatum, Gauge, type GaugeProps, type GaugeSeries, Grid, type GridOwnProps, type GridProps, Heading, type HeadingOwnProps, type HeadingProps, type HeadingSize, Heatmap, type HeatmapDatum, type HeatmapProps, IconButton, type IconButtonProps, Image, type ImageProps, ImageViewer, type ImageViewerControlsApi, type ImageViewerProps, type ImageViewerState, Input, type InputProps, Kanban, type KanbanCard, type KanbanColumn, type KanbanProps, Kbd, type KbdProps, Label, type LabelProps, List, type ListItemData, type ListProps, Menu, type MenuItemDef, type MenuProps, MultiSelect, type MultiSelectGroup, type MultiSelectOption, type MultiSelectProps, Navbar, type NavbarLink, type NavbarProps, type Option, type OptionGroup, Pagination, type PaginationProps, PieChart, type PieChartDatum, type PieChartProps, PolarAreaChart, type PolarAreaChartProps, type PolarAreaDatum, type PolymorphicAs, type PolymorphicComponent, type PolymorphicProps, type PolymorphicPropsWithRef, type PolymorphicRef, Popover, type PopoverProps, Portal, type PortalProps, Pre, type PreProps, Progress, type ProgressProps, RadarChart, type RadarChartProps, type RadarDatum, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, RangeChart, type RangeChartProps, type RangeDatum, Rating, type RatingProps, type ResponsiveColumns, ScatterChart, type ScatterChartProps, type ScatterPoint, type ScatterSeries, Select, type SelectGroup, type SelectOption, type SelectProps, Sidebar, type SidebarItem, type SidebarProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Sparkline, type SparklineDatum, type SparklineProps, Spinner, type SpinnerProps, Stack, type StackOwnProps, type StackProps, Stat, type StatProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, type Sx, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Tag, type TagProps, Text, type TextOwnProps, type TextProps, type TextTone, Textarea, type TextareaProps, type Theme, ThemeProvider, type ThemeProviderProps, type ThemeTokens, TimePicker, type TimePickerProps, Timeline, type TimelineItem, type TimelineProps, Toast, type ToastApi, type ToastOptions, type ToastProps, ToastProvider, type ToastProviderProps, type ToastTone, ToastViewport, type ToastViewportProps, ToggleGroup, type ToggleGroupItem, type ToggleGroupProps, type Tone, Tooltip, type TooltipProps, type TreeNode, TreeView, type TreeViewProps, Treemap, type TreemapDatum, type TreemapProps, TwicoProvider, type TwicoProviderProps, type UseColorSchemeOptions, type UseFilePickerOptions, type UseFocusTrapOptions, type UseKeyPressOptions, type UseLocalStorageOptions, type UseMediaQueryOptions, type UseWindowSizeOptions, VisuallyHidden, type VisuallyHiddenProps, type WithSx, createTheme, getColorSchemeScript, runDatatableQuery, useClickOutside, useColorScheme, useControllableState, useCopyToClipboard, useDebouncedCallback, useDebouncedValue, useDisclosure, useEventListener, useFilePicker, useFocusTrap, useHover, useId, useIntersectionObserver, useInterval, useIsomorphicLayoutEffect, useKeyPress, useLocalStorage, useMediaQuery, useMounted, usePortal, usePrefersReducedMotion, usePrevious, useScrollLock, useTimeout, useToast, useToggle, useWindowSize };