@cube-dev/ui-kit 0.155.0 → 0.157.0

package/docs/components/fields/FilterPicker.md

@@ -32,7 +32,7 @@ Choose a different component when the interaction has another shape:
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether to allow entering custom values that are not present in the predefined options
 - **`isClearable`** `boolean` (default: `false`) — Whether the filter picker is clearable using a clear button in the rightIcon slot
 - **`isLoadingItems`** `boolean` (default: `false`) — Whether items are currently loading. Shows a loading spinner in the search input suffix inside the popover. Unlike `isLoading`, does not disable the trigger.
-- **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection
+- **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection. In single selection mode, re-selecting the current item becomes a no-op: `onSelectionChange` is not fired and the popover closes
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`items`** `Iterable<T>` — Array of items to render when using the render function pattern for large datasets with dynamic content
 - **`placeholder`** `string` — Placeholder text when no selection is made

package/docs/components/fields/ListBox.md

@@ -147,6 +147,10 @@ The `mods` property accepts the following modifiers you can override:
 - When `true`, prevents the user from deselecting the last selected item
 - Ensures at least one item is always selected in single selection mode
 
+**allowDuplicateSelectionEvents** (`boolean`, default: `false`)
+- When `true`, `onSelectionChange` fires even when the new selection equals the current one (React Stately suppresses such duplicate events by default)
+- Used by popover-based wrappers (Picker, FilterPicker) together with `disallowEmptySelection` to close the popover when the user re-selects the current item
+
 **disableSelectionToggle** (`boolean`, default: `false`)
 - When `true`, clicking an already-selected item keeps it selected instead of toggling it off
 - Useful when embedding ListBox inside components like ComboBox

package/docs/components/fields/PasswordInput.md

@@ -18,6 +18,7 @@ A password input is a specialized text field that masks user input to protect se
 
 - **`value`** `string` — The password value in controlled mode
 - **`defaultValue`** `string` — The default password value in uncontrolled mode
+- **`isBuffered`** `boolean` (default: `true`) — Whether typed text is held locally until the controlled `value` catches up. This is what keeps the caret in place when the value round-trips through a store that re-renders a pass late; `onChange` still fires on every keystroke. Set to `false` for a caller that must see the field snap back to its own `value` the moment it declines a keystroke.
 - **`placeholder`** `string` — Placeholder text when input is empty
 - **`icon`** — Icon element rendered before the input
 - **`prefix`** — Input decoration before the main input

package/docs/components/fields/Picker.md

@@ -45,7 +45,7 @@ Choose a different component when the interaction has another shape:
 - **`isCheckable`** `boolean` (default: `false`) — Whether to show checkboxes for multiple selection mode
 - **`showSelectAll`** `boolean` (default: `false`) — Whether to show "Select All" option in multiple selection mode
 - **`selectAllLabel`** `ReactNode` (default: `Select All`) — Label for the "Select All" option
-- **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection
+- **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection. In single selection mode, re-selecting the current item becomes a no-op: `onSelectionChange` is not fired and the popover closes
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`isClearable`** `boolean` (default: `false`) — Whether the picker shows a clear button when a selection is made
 - **`onClear`** `() => void` — Callback called when the clear button is pressed

package/docs/components/fields/SearchInput.md

@@ -18,6 +18,7 @@ A search input provides a specialized text field for search functionality, featu
 
 - **`value`** `string` — The search value in controlled mode
 - **`defaultValue`** `string` — The default search value in uncontrolled mode
+- **`isBuffered`** `boolean` (default: `true`) — Whether typed text is held locally until the controlled `value` catches up. This is what keeps the caret in place when the value round-trips through a store that re-renders a pass late; `onChange` still fires on every keystroke. Set to `false` for a caller that must see the field snap back to its own `value` the moment it declines a keystroke.
 - **`placeholder`** `string` — Placeholder text when input is empty
 - **`icon`** `ReactElement` — Icon element rendered before the input (default: search icon)
 - **`prefix`** `ReactNode` — Content rendered before the input

package/docs/components/fields/TextArea.md

@@ -39,6 +39,7 @@ These properties allow direct style application without using the `styles` prop:
 - **`rows`** `number` (default: `3`) — Number of visible text rows
 - **`value`** `string` — The text value in controlled mode
 - **`defaultValue`** `string` — The default text value in uncontrolled mode
+- **`isBuffered`** `boolean` (default: `true`) — Whether typed text is held locally until the controlled `value` catches up. This is what keeps the caret in place when the value round-trips through a store that re-renders a pass late; `onChange` still fires on every keystroke. Set to `false` for a caller that must see the field snap back to its own `value` the moment it declines a keystroke.
 - **`placeholder`** `string` — Placeholder text when input is empty
 - **`icon`** `ReactElement` — Icon element rendered before the input
 - **`prefix`** `ReactNode` — Input decoration before the main input

package/docs/components/fields/TextInput.md

@@ -18,6 +18,7 @@ A text input component that allows users to input custom text entries with a key
 
 - **`value`** `string` — The text value in controlled mode
 - **`defaultValue`** `string` — The default text value in uncontrolled mode
+- **`isBuffered`** `boolean` (default: `true`) — Whether typed text is held locally until the controlled `value` catches up. This is what keeps the caret in place when the value round-trips through a store that re-renders a pass late; `onChange` still fires on every keystroke. Set to `false` for a caller that must see the field snap back to its own `value` the moment it declines a keystroke.
 - **`placeholder`** `string` — Placeholder text when input is empty
 - **`icon`** — Icon element rendered before the input
 - **`prefix`** — Input decoration before the main input

package/docs/components/layout/Board.md

@@ -32,6 +32,16 @@ clipped by an ancestor's `overflow: hidden`.
   widget is placed exactly where you drop it and its neighbours are never pushed
   or swapped; without `allowOverlap` a drop onto an occupied cell is blocked, and
   with `allowOverlap` widgets may stack for a fully free canvas.
+- **Selection** — off by default. Pressing a widget selects it and arms a drag
+  of the selection: selecting and grabbing are one gesture, so move the pointer
+  and it drags, stay still and it was just a selection. <kbd>Shift</kbd> (or
+  <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>) toggles a widget's membership. Keys are layout
+  item ids, scoped to a single board, and always reported in layout order.
+- **Selection is focus-like** — it tracks what the user is working with, and
+  touching anything else moves it on: pressing another widget makes *that* the
+  selection, pressing a control inside a widget drops it, and so does focus
+  leaving the board. With `'multiple'`, pressing an already-selected widget
+  keeps the selection so a drag moves the whole block.
 
 ## Properties
 
@@ -58,6 +68,13 @@ clipped by an ancestor's `overflow: hidden`.
 - **`dragHandle`** `string` — CSS selector for the only elements from which a pointer drag may start. Can be overridden per widget.
 - **`showGridLines`** `boolean | 'drag'` (default: `false`) — Show grid lines behind the widgets. `true` always, `'drag'` only while a widget is being dragged or resized. A nested board that does not set this inherits an enabled ancestor's grid lines, showing its own while a drag is in progress.
 - **`isAligned`** `boolean` (default: `false`) — Align a nested board with its ancestor `Board`'s layout. Only takes effect when the board is nested inside another `Board`'s widget. When set, every cell matches the parent's cell size exactly: the board inherits the parent's column pitch (deriving its own column count from its measured width so cells stay parent-sized as the container is resized) and uses the parent's row height verbatim. It never shrinks rows to fit — pair it with an `isAutoHeight` container so the widget grows to fit its rows at that height. `cols`/`rowHeight` then act as fallbacks used only until the parent metrics resolve.
+- **`selectionMode`** `'none' | 'single' | 'multiple'` (default: `'none'`) — Whether widgets can be selected, and how many at a time. `'multiple'` also enables the marquee and rigid group movement.
+- **`selectedKeys`** `string[]` — Controlled selection. Keys are layout item ids (`LayoutItem.i`).
+- **`defaultSelectedKeys`** `string[]` — Initial selection for uncontrolled usage.
+- **`onSelectionChange`** `(keys: string[]) => void` — Called when the selection changes. Keys are deduped and returned in the board's layout order, never in click order.
+- **`selectionCancel`** `string` (default: `BOARD_SELECTION_CANCEL`) — CSS selector marking interactive descendants. A press on one never selects and never starts a drag, so the control keeps its own click *and* its native focus; it also drops the selection, since interacting with a widget's content means the user has moved on. On a selectable board this doubles as the drag guard, so form controls stay usable without also configuring `dragCancel`. The default covers native form controls, links, and the common ARIA widget roles, plus `[data-no-select]` as an escape hatch. Pass `''` to disable the guard. Can be overridden per widget.
+- **`allowMarqueeSelection`** `boolean` (default: `selectionMode === 'multiple'`) — Draw a rubber-band selection when a drag starts on empty board space. A press on a widget selects and drags instead, so the lasso owns empty canvas only. Hold <kbd>Shift</kbd> or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> to add to the existing selection rather than replacing it.
+- **`onWidgetsDelete`** `(keys: string[]) => void` — Called when <kbd>Delete</kbd>/<kbd>Backspace</kbd> is pressed with a non-empty selection and focus is not in an editable field. **Board never mutates the layout itself** — removing the widgets is yours to do, which is what lets you make it undoable. Board only handles these keys when this handler is set.
 - **`constraints`** `LayoutConstraint[]` — Grid/item layout constraints.
 - **`width`** `number` — Explicit width (disables measurement; useful for SSR/tests).
 - **`widgetProps`** `Partial<Board.Widget props>` — Default props applied to every widget this board hosts (per-widget `Board.Widget` props override these). Use it to add a card border to every widget (`widgetProps={{ isCard: true }}`) or set shared `styles`/sizing defaults without repeating them on each widget.
@@ -82,6 +99,16 @@ clipped by an ancestor's `overflow: hidden`.
 - **`isAutoHeight`** `boolean` (default: `false`) — Grow this widget's height in its board to fit its content (only ever increases, never shrinks). Pair it with a nested `Board isAligned` so the container expands until the inner board's rows fit at the parent's row height. It also pins the widget's resize floor: you cannot drag the widget shorter than the height its content currently needs.
 - **`dragCancel`** `string` — Override the board's `dragCancel` selector for this widget.
 - **`dragHandle`** `string` — Override the board's `dragHandle` selector for this widget.
+- **`isSelectable`** `boolean` — Disable selection for this widget while the board's `selectionMode` is on.
+- **`selectionCancel`** `string` — Override the board's `selectionCancel` selector for this widget.
+- **`aria-label`** `string` — Accessible name for the widget. Falls back to `qa`, then the layout item id — both developer-facing, so set this whenever the widget is user-visible. Also what the selection announcement reads out.
+
+A widget clips its content to its grid cell, card or not — otherwise a nested
+board with more rows than currently fit, or a mid-drag reflow, would paint over
+its neighbours. The cost is that a descendant's `outline` is cropped at the edge
+(an outline is clipped by an *ancestor's* overflow, not its own), so a widget
+whose content must paint outside — a control drawing its own active ring — sets
+`overflow="visible"`, or draws the ring inset with a negative `outlineOffset`.
 
 ### Board.Provider
 
@@ -119,6 +146,48 @@ container's measured width, mirroring react-grid-layout's `Responsive` +
 A breakpoint with no layout is synthesized from the nearest available one,
 corrected into bounds and compacted for the target column count.
 
+### Modifiers
+
+Every widget host exposes these as `data-*` attributes, and any style map passed
+through `widgetProps.styles` or a per-widget `styles` resolves against them.
+
+- **`selected`** — the widget is in the board's selection.
+- **`card`** — the widget draws a card border (`isCard`).
+- **`draggable`** — the widget can be dragged and no drag is in flight.
+- **`drag`** — the widget is being dragged.
+- **`floating`** — this is the clone floating in the drag overlay.
+- **`resizing`** — the widget is being resized.
+- **`static`** — the layout item is `static`.
+- **`hovered`**, **`focus-visible`** — pointer and keyboard-focus states.
+- **`settled`** — the board has painted its widgets once, so position changes animate.
+
+Selection is an *edge* treatment — a `#primary-border` border plus a `#primary`
+ring — because it reads as a focus-like state rather than a fill. `outline` stays
+reserved for the real focus ring, which is what keeps the two legible together:
+they use different tokens and the focus outline sits one border-width further
+out. To restyle it, override the same keys:
+
+```jsx
+<Board
+  selectionMode="multiple"
+  widgetProps={{
+    styles: {
+      border: { '': true, selected: '#note-border' },
+      shadow: { '': false, selected: '0 0 0 1bw #note' },
+    },
+  }}
+/>
+```
+
+### Data attributes
+
+Supported hooks for tests, E2E, and building your own selection overlay:
+
+- **`data-board-id`** on the board element — the board's `id`.
+- **`data-board-widget-host`** on every widget host — presence only, "this is a widget host".
+- **`data-board-widget-id`** on every widget host — which widget.
+- **`data-selected`** on a selected host.
+
 ### Base Properties
 
 Supports [Base properties](../../BaseProperties.md).
@@ -221,14 +290,76 @@ mounted so the tab a widget is dragged out of (and the board owning the in-fligh
 drag) is not unmounted mid-gesture. Spring-loading works with mouse and pen;
 touch drags capture the pointer, so they do not trigger it.
 
+### Selection
+
+Click to select, Shift/Cmd/Ctrl-click to add or remove, and drag from empty board
+Press a widget to select it, <kbd>Shift</kbd>-press to add or remove one, and
+drag from empty board space to lasso. Because the press both selects and arms the
+drag, grabbing a widget you have not selected simply makes it the selection and
+moves it; grabbing one that *is* selected moves the whole block rigidly — keeping
+its shape horizontally, clamping against the grid edge as a unit rather than
+collapsing, and committing once.
+
+A group reflows exactly like a single widget: it is compacted by the same rules,
+so on a `vertical` board it can no more be parked in empty space than one widget
+can, and the widgets around it close the gap in the same frame. Under
+`compact="free"` (or `null`) nothing compacts, so the block stays precisely where
+it was dropped.
+
+### Interactive content keeps its clicks
+
+### Controlled selection and deleting widgets
+
+### Restyling the selection
+
 ## Accessibility
 
-- Widgets are focusable when draggable. Press <kbd>Tab</kbd> to focus a widget,
-  then use the arrow keys to move it one cell at a time. Arrow keys only move
-  the widget when the widget host itself is focused — not when focus is inside
-  a nested control (e.g. an <kbd>input</kbd> or <kbd>textarea</kbd>).
-- Dragging, resizing, and keyboard movement are all handled by React Aria's
-  `useMove`, which normalizes mouse, touch, and keyboard interactions.
+### Keyboard Navigation
+
+| Key | Action |
+| --- | --- |
+| <kbd>Tab</kbd> | Move focus to the next widget. |
+| <kbd>Arrow</kbd> keys | Move the focused widget one cell. With a selection, moves the whole selection. |
+| <kbd>Space</kbd> | Toggle the focused widget's selection (`selectionMode` only). |
+| <kbd>Shift</kbd> / <kbd>Cmd</kbd> / <kbd>Ctrl</kbd> + press | Add or remove a widget from the selection. |
+| <kbd>Escape</kbd> | Clear the selection. |
+| <kbd>Delete</kbd> / <kbd>Backspace</kbd> | Request deletion of the selection via `onWidgetsDelete`. |
+
+Arrow keys and <kbd>Space</kbd> only act when the widget host **itself** is
+focused, never when focus is inside a nested control, so an `input`,
+`textarea`, or `button` inside a widget keeps every key it needs. Board's own
+keys are handled on the board element rather than on `document`, and are only
+consumed when they actually do something — an <kbd>Escape</kbd> with nothing
+selected still reaches an ancestor Dialog, and <kbd>Backspace</kbd> stays
+available for text editing and browser-back.
+
+Every draggable or selectable widget is its own tab stop. Roving tabindex would
+be an improvement on a large board, but arrow keys are already claimed for
+movement, so it needs a navigation key set of its own — see below.
+
+### Screen Reader Support
+
+Each widget host is a `group` with an accessible name, taken from
+`aria-label`, then `qa`, then the layout item id — set `aria-label` on any
+user-visible widget, since the other two are developer-facing. Draggable widgets
+carry a localized `aria-roledescription`, and selectable ones advertise
+`aria-keyshortcuts="Space"`.
+
+Selection state is conveyed two ways: a selected widget is described as
+"Selected" via `aria-describedby`, and every selection change is announced
+through a polite live region owned by the board ("Revenue selected", "3 widgets
+selected", "Selection cleared"). A marquee announces once, on release — not once
+per pointer frame.
+
+### ARIA Properties
+
+Board deliberately does **not** use a collection role. `aria-selected` is only
+valid on `option`, `gridcell`, `row`, `treeitem` and friends, and every one of
+those requires presentational children — but a Board widget hosts arbitrary
+interactive content (nested boards, tabs, inputs), and a `grid`'s keyboard model
+would fight `useMove`'s arrow keys. Rather than ship ARIA that lies about the
+structure, selection is exposed through the name, description, and live region
+described above. Set `aria-label` on your widgets and this reads correctly.
 
 ## Not yet supported
 
@@ -240,6 +371,23 @@ touch drags capture the pointer, so they do not trigger it.
   placeholder, and new `onDrop`/`droppingItem` props). Add widgets
   programmatically (render a new `Board.Widget` and add its layout item), or drag
   between boards with `Board.Provider`.
+- **Cross-board group transfer** — a group drag never leaves its source board.
+  Cross-board transfer is single-item throughout (`WidgetTransferInfo`, the
+  carried preview, the free-slot fallback), and landing a group on a board with a
+  different column count has no obvious right answer. Degrading to a
+  single-widget transfer would silently split a selection the user made, so the
+  gesture is confined instead. Drag widgets across one at a time.
+- **Collection ARIA semantics** — `role="grid"`/`option`, `aria-selected` and
+  `aria-multiselectable`, for the reason above.
+- **Roving tabindex** — needs a widget-navigation key set that does not collide
+  with `useMove`'s arrow keys.
+- **<kbd>Cmd/Ctrl</kbd>+<kbd>A</kbd>** — select all.
+- **Cross-board marquee and cross-board selection** — selection is per board; a
+  `Board.Provider` shares drag, not selection.
+- **Windows High Contrast Mode** — no component in the kit styles for
+  `forced-colors` yet. The selected state uses a tint, a border *and* an extra
+  ring, so it does not rely on hue alone, but a full forced-colors pass is a
+  system-wide change.
 
 ## Attribution
 

package/docs/components/navigation/Pagination.md

@@ -0,0 +1,245 @@
+# Pagination
+
+Pagination is the control for moving through a paged collection. It renders a
+bounded run of page buttons, optional first/last jumps, an optional page-size
+selector, and an optional item-range summary.
+
+It is a pure control: it owns no data. Client-side slicing lives in the
+companion `usePagination` hook, and `ItemTable` composes the two.
+
+## When to Use
+
+- Paging through a list, table, or grid where the user needs to jump around
+  rather than scroll.
+- Cursor pagination with an unknown total — supply `hasNextPage` and omit
+  `total`/`totalPages`, and the control degrades to prev/next.
+- Anywhere you need a page-size selector wired to the same state.
+
+Prefer infinite scroll when the collection is a feed the user skims, and
+pagination when they need stable, addressable positions.
+
+## Component
+
+### Properties
+
+- **`page`** `number` — Controlled current page, 1-based. Pair with
+  `onPageChange`.
+- **`defaultPage`** `number` (default: `1`) — Initial page for uncontrolled
+  usage.
+- **`onPageChange`** `(page: number) => void` — Never fires with a page outside
+  `1…totalPages` when the total is known.
+- **`total`** `number` — Total items across all pages. Preferred over
+  `totalPages`; it also powers the range summary and the `select` type's range
+  labels.
+- **`totalPages`** `number` — Total pages. Only needed when the item count is
+  genuinely unavailable. Wins over the value derived from `total` + `pageSize`.
+- **`pageSize`** `number` — Controlled page size.
+- **`defaultPageSize`** `number` (default: `50`) — Initial page size for
+  uncontrolled usage.
+- **`onPageSizeChange`** `(pageSize: number) => void` — Changing the size also
+  resets to page 1, because the old page index no longer refers to the same
+  items.
+- **`pageSizeOptions`** `number[]` — Supplying this **and** `onPageSizeChange`
+  renders the size selector.
+- **`type`** `'numbers' | 'select' | 'compact'` (default: `'numbers'`) — How the
+  page control is rendered. `numbers` is the default because it is the only mode
+  whose rendered element count is independent of the page count; `select`
+  materializes one entry per page, so above a safety cap the component falls
+  back to `compact` on its own.
+- **`siblingCount`** `number` (default: `1`) — Page buttons either side of the
+  current page.
+- **`boundaryCount`** `number` (default: `1`) — Page buttons pinned at each end.
+  Together with `siblingCount` this bounds the rendered count at
+  `boundaryCount * 2 + siblingCount * 2 + 3`.
+- **`size`** `'small' | 'medium'` (default: `'small'`) — Control size.
+- **`isDisabled`** `boolean` — Disable every control.
+- **`hasNextPage`** `boolean` — Keeps "next" enabled when the total is unknown.
+  Ignored once `total` or `totalPages` is supplied — a known total is always
+  authoritative.
+- **`isCompact`** `boolean` (default: `false`) — Hide the first/last jump
+  buttons.
+- **`summary`** `boolean | ((info: CubeTablePageInfo) => ReactNode)` (default:
+  `false`) — `true` renders the localized `1–50 of 1,204`, with numbers
+  formatted for the active locale. Pass a function for full control.
+- **`labelFormatter`** `(info: CubeTablePageInfo) => ReactNode` — Labels the
+  entries of `type="select"`. Receives the page info with `page` set to the
+  entry being labelled.
+- **`ariaLabel`** `string` — Labels the `<nav>` landmark. Defaults to the
+  localized "Pagination".
+
+#### `CubeTablePageInfo`
+
+Handed to `summary` and `labelFormatter`:
+
+```ts
+interface CubeTablePageInfo {
+  page: number;       // 1-based
+  pageSize: number;
+  totalPages: number;
+  total: number;      // 0 when unknown
+  from: number;       // 1-based index of the first item on this page
+  to: number;         // 1-based index of the last item on this page
+}
+```
+
+### Base Properties
+
+Supports Base Properties.
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element.
+
+**Sub-elements:**
+
+- `Summary` — the range summary and the `compact` page label
+- `Controls` — the row of nav and page buttons
+- `Gap` — the `…` between two runs of page numbers
+
+#### pageSizeSelectStyles
+
+Customizes the page-size `Select`.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`
+
+### Modifiers
+
+| Modifier | Type | Description |
+| -------- | ---- | ----------- |
+| `size` | `'small' \| 'medium'` | Control size |
+
+## Examples
+
+### Basic Usage
+
+```jsx
+const [page, setPage] = useState(1);
+
+<Pagination page={page} pageSize={50} total={1204} onPageChange={setPage} />;
+```
+
+### With a Summary
+
+```jsx
+<Pagination page={3} pageSize={50} total={1204} summary onPageChange={setPage} />
+```
+
+### Many Pages
+
+A million rows at 50 per page is 20 000 pages — and still ~7 buttons.
+
+```jsx
+<Pagination page={9421} pageSize={50} total={1000000} summary onPageChange={setPage} />
+```
+
+### Page Size Selector
+
+```jsx
+const [page, setPage] = useState(1);
+const [pageSize, setPageSize] = useState(50);
+
+<Pagination
+  page={page}
+  pageSize={pageSize}
+  total={1204}
+  pageSizeOptions={[10, 20, 50, 100, 500]}
+  summary
+  onPageChange={setPage}
+  onPageSizeChange={setPageSize}
+/>;
+```
+
+### Unknown Total (Cursor Pagination)
+
+```jsx
+<Pagination page={page} hasNextPage={hasNextPage} onPageChange={setPage} />
+```
+
+### Compact
+
+```jsx
+<Pagination type="compact" page={3} pageSize={50} total={1204} summary />
+```
+
+### Client-side Slicing with `usePagination`
+
+```jsx
+const { pageItems, page, pageSize, total, setPage, setPageSize } =
+  usePagination(items, { defaultPageSize: 10 });
+
+return (
+  <>
+    {pageItems.map((item) => (
+      <Text key={item}>{item}</Text>
+    ))}
+    <Pagination
+      page={page}
+      pageSize={pageSize}
+      total={total}
+      pageSizeOptions={[5, 10, 25]}
+      summary
+      onPageChange={setPage}
+      onPageSizeChange={setPageSize}
+    />
+  </>
+);
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` — moves through the controls in visual order.
+- `Enter` / `Space` — activates the focused button.
+
+Every control is a real `<button>`, so there is nothing bespoke to learn.
+
+### Screen Reader Support
+
+- The root is a `<nav>` landmark labelled "Pagination" (override with
+  `ariaLabel`).
+- The current page button carries `aria-current="page"`.
+- Every button has an explicit `aria-label` — "Page 3", "Next page", and so on
+  — so an icon-only button is never announced as unlabelled.
+- The `…` gap is `aria-hidden`; it conveys nothing a screen reader user needs.
+
+### ARIA Properties
+
+| Property | Applied to |
+| -------- | ---------- |
+| `aria-label` | The `<nav>` and every button |
+| `aria-current="page"` | The current page button |
+| `aria-hidden="true"` | The `…` gap |
+
+## Best Practices
+
+- Do: pass `total` rather than `totalPages` when you know the item count — the
+  summary and range labels both need it.
+- Do: use `type="numbers"` (the default) for anything that can grow. It is the
+  only mode whose cost does not scale with the page count.
+- Do: reset to page 1 whenever the underlying query changes (a new search term,
+  a new filter). A stale page index against a smaller result set shows an empty
+  page.
+- Don't: render `type="select"` over a large page count. It builds one
+  collection item per page.
+- Don't: pass both `hasNextPage` and a known total and expect the former to win
+  — it doesn't.
+
+## Suggested Improvements
+
+- A "jump to page" input for very large page counts.
+- Optional URL synchronization, so a page is linkable.
+
+## Related Components
+
+- ItemTable — composes `Pagination` in its footer
+- [Select](../fields/Select.md) — used for the page-size selector
+- [Button](../actions/Button.md) — used for every nav and page control

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.155.0",
+  "version": "0.157.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -48,6 +48,7 @@
     "@react-aria/ssr": "^3.9.10",
     "@react-aria/utils": "^3.32.0",
     "@react-spectrum/utils": "^3.12.10",
+    "@react-stately/selection": "^3.20.7",
     "@react-stately/utils": "^3.11.0",
     "@react-types/shared": "^3.32.1",
     "@tabler/icons-react": "^3.31.0",
@@ -104,7 +105,9 @@
     "@types/react-test-renderer": "^18.0.7",
     "@uiw/react-codemirror": "^4.25.4",
     "@vitejs/plugin-react": "^6.0.0",
-    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/browser": "^4.1.10",
+    "@vitest/browser-playwright": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.10",
     "best-effort-json-parser": "^1.2.1",
     "bytes": "^3.1.2",
     "chromatic": "^13.1.4",
@@ -117,6 +120,7 @@
     "markdown-table": "^3.0.3",
     "npm-run-all": "^4.1.5",
     "oxlint": "^1.72.0",
+    "playwright": "^1.62.1",
     "prettier": "^3.2.5",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
@@ -131,7 +135,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.6.3",
     "vite": "^8.0.0",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.10"
   },
   "browserslist": [
     "last 2 Chrome versions",
@@ -148,6 +152,7 @@
     "build": "tsdown",
     "watch": "tsdown --watch",
     "test": "vitest run",
+    "test:browser": "vitest run --config vitest.browser.config.ts",
     "test-cover": "vitest run --coverage",
     "test-watch": "vitest",
     "prettier": "prettier --check \"src/**/*.{js,jsx,ts,tsx}\"",

package/dist/components/organisms/FileTabs/FileTabs.d.ts

@@ -1,54 +0,0 @@
-
-import { CubeActionProps } from "../../actions/Action/Action.js";
-import "../../actions/index.js";
-import { CubeFlexProps } from "../../layout/Flex.js";
-import { Styles } from "@tenphi/tasty";
-import { ReactNode } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
-
-//#region src/components/organisms/FileTabs/FileTabs.d.ts
-/**
- * @deprecated consider using <Tabs /> instead
- */
-interface FileTabProps extends Omit<CubeActionProps, 'id'> {
-  isDirty?: boolean;
-  isDisabled?: boolean;
-  children?: ReactNode;
-  isClosable?: boolean;
-  onClose?: () => void;
-}
-interface CubeFileTabsProps extends CubeFlexProps {
-  /** The initial active key in the tabs (uncontrolled). */
-  defaultActiveKey?: string;
-  /** The currently active key in the tabs (controlled). */
-  activeKey?: string | number;
-  /** Handler that is called when the tab is clicked. */
-  onTabClick?: (string: any) => void;
-  /** Handler that is called when the tab is closed. */
-  onTabClose?: (string: any) => void;
-  /** Styles for each tab pane */
-  paneStyles?: Styles;
-  /** Whether the tabs are closable */
-  isClosable?: boolean;
-  children?: ReactNode;
-}
-declare function FileTabs({
-  defaultActiveKey,
-  activeKey: activeKeyProp,
-  onTabClick,
-  onTabClose,
-  paneStyles,
-  isClosable,
-  children,
-  ...props
-}: CubeFileTabsProps): react_jsx_runtime0.JSX.Element;
-declare namespace FileTabs {
-  var TabPane: (allProps: CubeFileTabProps) => react_jsx_runtime0.JSX.Element;
-}
-interface CubeFileTabProps extends FileTabProps {
-  id: string | number;
-  title: string;
-}
-//#endregion
-export { CubeFileTabProps, FileTabs };
-//# sourceMappingURL=FileTabs.d.ts.map