@cube-dev/ui-kit 0.0.0-canary-1a77404 → 0.0.0-canary-ff8c3d6

package/docs/components/data/DataTable.md

@@ -61,7 +61,8 @@ and everything it knows about the query, in Cloud.
 
 - **`shape`** `'plain' | 'card'` (default: `'plain'`)
 - **`size`** `SizeName` (default: `'small'`) — An analytical grid packs more rows than a list.
-- **`rowHeight`** `number` — Overrides the height implied by `size`.
+- **`rowSize`** `'small' | 'medium' | 'large'` — Row height as a named step: 28px / 32px / 40px. Rows only; the header keeps answering to `size`. Unset, the height comes from `size`.
+- **`rowHeight`** `number` — An exact height, when none of the named steps is the answer. Wins over both `rowSize` and `size`.
 - **`headerHeight`** `number`
 - **`isStriped`** `boolean` (default: `true`) — Banding is what makes a wide row readable across.
 - **`isHeaderHidden`** `boolean`
@@ -109,6 +110,20 @@ and everything it knows about the query, in Cloud.
 - **`columnWidths`** `Record<string, number>`
 - **`defaultColumnWidths`** `Record<string, number>`
 - **`onColumnResize`** `(columnKey: string, width: number, all: Record<string, number>) => void`
+- **`isColumnReorderable`** `boolean` (default: `false`) — Drag column headers sideways to reorder them.
+- **`columnOrder`** `string[]` — Controlled order, as column keys. Works with or without dragging.
+- **`defaultColumnOrder`** `string[]`
+- **`onColumnOrderChange`** `(order: string[]) => void` — The full key list, including hidden and pinned columns.
+
+Per column, on `CubeDataTableColumn`: `isReorderable`, `color` and `colorScope` —
+see [Column Colors](#column-colors) for the last two.
+
+#### Column menu
+
+- **`columnContextMenu`** `boolean | 'context-only'` (default: `true`) — Where a column's `header.menu` is exposed.
+- **`onColumnMenuAction`** `(action: string, columnKey: string) => void` — The pressed key, as written.
+- **`columnMenuTriggerProps`** `Record<string, any>`
+- **`columnMenuProps`** `Record<string, any>`
 
 #### Virtualization
 
@@ -119,7 +134,7 @@ and everything it knows about the query, in Cloud.
 #### Other
 
 - **`getRowProps`** `(ctx: CubeTableRowContext<T>) => Record<string, any>` — Per-row mods, styles and height.
-- **`storageKey`** `string` — Persists page size and column widths.
+- **`storageKey`** `string` — Persists page size, column widths and column order.
 - **`ariaLabel`** `string`
 
 #### `dataType`
@@ -286,12 +301,102 @@ succeeds.
 
 ### States
 
+### Column Menu
+
+A column exposes a menu through `header.menu`, opened from a `⋮` trigger in the
+header, by right-click, or with `Shift`+`F10`. The contents are opaque — the grid
+mounts the node and reports the pressed key back through `onColumnMenuAction`,
+which is what keeps Cube vocabulary out of the kit.
+
+Sorting is the exception, because it is the one thing the table itself can do.
+`columnSortMenu()` returns `sort-asc` / `sort-desc` / `clear-sort` items that the
+table labels from the current locale, disables when they would do nothing, and
+applies before telling the consumer. Everything else is yours:
+
+```tsx
+import { columnSortMenu, Menu } from '@cube-dev/ui-kit';
+
+const columns = [
+  {
+    key: 'revenue',
+    title: 'Revenue',
+    isSortable: true,
+    header: {
+      menu: (
+        <>
+          {columnSortMenu()}
+          <Menu.Item key="pin">Pin column</Menu.Item>
+        </>
+      ),
+    },
+  },
+];
+
+<DataTable
+  columns={columns}
+  onColumnMenuAction={(action, columnKey) => {
+    if (action === 'pin') pinColumn(columnKey);
+  }}
+/>;
+```
+
+Pressing the trigger never sorts the column: the header's `Item` swallows the
+click, which is why it sits *inside* the `<th>` rather than being it.
+
+### Column Reordering
+
+`isColumnReorderable` lets a user drag a header sideways, or move the focused
+column with `Alt`+`←` / `→`. Clicking still sorts and the resize handle still
+resizes.
+
+Structural and pinned columns stay put — `pin` is already the ordering authority
+for a pinned column — and a single column opts out with `isReorderable: false`.
+`columnOrder` works on its own too, so a column manager elsewhere in the page can
+drive the order without any dragging.
+
+A stale order is safe: keys for columns that no longer exist are ignored, and a
+column missing from the list lands after the neighbour it had in `columns`
+rather than being swept to the end.
+
+### Column Colors
+
+`column.color` tints a whole column — header, cells and pinned totals. It takes a
+palette theme name, any CSS color, a `{ hue, saturation }` seed, or a
+`{ fill, text }` pair for full manual control.
+
+Every form but the last is *derived*: only the hue and saturation are kept, and
+the tone ramp plus an AA/AAA text floor are re-solved for light, dark and
+high-contrast. A column cannot end up unreadable in a scheme nobody checked.
+
+```tsx
+const columns = [
+  { key: 'orders', title: 'Orders', color: 'note' },
+  { key: 'revenue', title: 'Revenue', color: 'success' },
+  { key: 'conversion', title: 'Conversion', color: '#0ea5e9' },
+  // Header only, cells left neutral.
+  { key: 'region', title: 'Region', color: 'danger', colorScope: ['header'] },
+];
+```
+
+Row banding survives inside a tinted column: the tint carries its own band one
+tone step away, so the stripe still reads down the column instead of being
+painted over.
+
+Under the hood each distinct color becomes a small adaptive theme named by a hash
+of its config, registered once per document — so ten columns sharing a color cost
+one set of tokens. That machinery is public as `useColorTheme` if you want it
+elsewhere.
+
 ## Accessibility
 
 The table is a `role="grid"` with document-absolute `aria-rowindex` /
 `aria-colindex`, and `aria-rowcount` counts pinned rows. Every sorted column
 carries `aria-sort`, not just the first.
 
+A header cell takes a tab stop when it is interactive — sortable, carrying a
+menu, or reorderable. `Shift`+`F10` opens the column menu from the keyboard, and
+`Alt`+`←` / `→` moves a reorderable column, so neither needs a pointer.
+
 ## Related Components
 
 - ItemTable — a list of things to act on.

package/docs/components/data/ItemTable.md

@@ -189,6 +189,14 @@ pivots, totals. Use `ListBox` when there is only one column.
 - **`defaultColumnWidths`** `Record<string, number>` — Initial widths.
 - **`onColumnResize`** `(columnKey, width, all) => void` — Fires once the
   gesture ends, not on every pixel.
+- **`columnContextMenu`** `boolean | 'context-only'` (default: `true`) — Where a
+  column's `header.menu` is exposed: a `⋮` trigger plus right-click and
+  Shift+F10, right-click only, or nowhere.
+- **`onColumnMenuAction`** `(action, columnKey) => void` — The pressed
+  `Menu.Item` key, as written. Fires for the reserved sort keys too, after the
+  table has applied them.
+- **`columnMenuTriggerProps`** `Record<string, any>` — Props for the `⋮` trigger.
+- **`columnMenuProps`** `Record<string, any>` — Props for the `Menu`.
 - **`storageKey`** `string` — Persists the table's own state under
   `cube-ui-kit:table:${storageKey}`. Controlled state is never stored — a
   controlled `pageSize` or `sort` belongs to the page, and restoring it would
@@ -225,7 +233,7 @@ interface CubeItemTableColumn<T> {
   cellProps?: (ctx) => Record<string, any> | undefined;
 
   align?: 'start' | 'center' | 'end';
-  isSortable?: boolean;
+  isSortable?: boolean;     // opt in per column (default false)
   isSearchable?: boolean;   // include in the built-in search (default true)
   isCopyable?: boolean;     // include in TSV copy (default true)
   autoHeight?: boolean;     // wrap text and let the row grow
@@ -405,10 +413,11 @@ search sets it for you.
 
 ### Sorting
 
-Mark columns `isSortable` and clicking a header cycles
-`ascending → descending → unsorted`. The third state matters whenever the source
-order is meaningful, which is why it is the default cycle; set
-`disallowSortRemoval` on a column to reduce it to `asc ↔ desc`.
+Sorting is **opt in, per column**: a table with no `isSortable` column has inert
+headers and `sortMode` resolves to `'off'`. Mark columns `isSortable` and
+clicking a header cycles `ascending → descending → unsorted`. The third state
+matters whenever the source order is meaningful, which is why it is the default
+cycle; set `disallowSortRemoval` on a column to reduce it to `asc ↔ desc`.
 
 ```jsx
 <ItemTable
@@ -422,6 +431,29 @@ order is meaningful, which is why it is the default cycle; set
 />
 ```
 
+#### A fixed order the user cannot change
+
+For a list that arrives in a meaningful order — most of them — leave every column
+alone and pass the order you want. `sortMode="client"` keeps the engine sorting
+while the headers stay inert, so nothing is clickable and no header takes a tab
+stop:
+
+```jsx
+<ItemTable
+  data={rows}
+  columns={[{ key: 'name', title: 'Name' }]}
+  sortMode="client"
+  sort={{ columnKey: 'name', direction: 'asc' }}
+/>
+```
+
+The sorted column still carries `aria-sort`, so a screen reader announces the
+order even though the header cannot be operated. It is **not** drawn — the sort
+arrow belongs to the clickable affordance — so add your own marker through
+`header.suffix` if sighted users need to see which column the order follows.
+
+Data already in the right order needs none of this: pass it and set nothing.
+
 Client-side sorting compares raw `getValue` results — numerically for numbers,
 chronologically for dates — and falls back to a locale-aware collator over the
 column's display text, so a formatted column sorts the way it reads. `compare`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.0.0-canary-1a77404",
+  "version": "0.0.0-canary-ff8c3d6",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -157,7 +157,7 @@
     "prettier": "^3.2.5",
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
-    "react-router": "^7.18.2",
+    "react-router": "^6.22.3",
     "react-test-renderer": "^19.1.1",
     "remark-gfm": "^4.0.1",
     "rimraf": "^6.0.1",