@cube-dev/ui-kit 0.158.0 → 0.159.0

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useIsDarwin.ts

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { useMemo } from "react";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useCallback, useSyncExternalStore } from "react";
 

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { useCallback, useContext, useEffect, useRef } from "react";
 

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.158.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.159.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.158.0";
+const VERSION = "0.159.0";
 const TASTY_VERSION = "3.0.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/components/actions/Button.md

@@ -179,8 +179,23 @@ import { IconPlus } from '@tabler/icons-react';
 <Button tooltip={true} width="100px">
   This text will be truncated
 </Button>;
+
+{
+  /* Explain why the button is unavailable */
+}
+<Button isDisabled tooltip="Not enough permissions">
+  Delete
+</Button>;
 ```
 
+A disabled button keeps showing its tooltip. Browsers stop dispatching mouse
+events on elements carrying the native `disabled` attribute, so a button that
+has a tooltip is marked with `aria-disabled` instead and kept inert: `onPress`
+never fires and clicks (including the ones Enter and Space produce) do nothing.
+Such a button also stays in the tab order, so keyboard users can focus it and
+read the tooltip. Buttons rendered as links (`to`) are always marked this way,
+since `disabled` is not a valid attribute on an anchor.
+
 ### Custom Size
 
 ```jsx
@@ -212,6 +227,8 @@ import { IconPlus } from '@tabler/icons-react';
 
 - `aria-label`, `aria-labelledby` – Accessible name.
 - `aria-pressed` – Managed automatically when `isSelected` is used.
+- `aria-disabled` – Announces the disabled state whenever the native `disabled`
+  attribute cannot be used: on links, and on buttons that carry a tooltip.
 - Additional ARIA attributes supported by React Aria's `useButton`.
 
 ## Behaviour Inside Popovers

package/docs/components/content/Item.md

@@ -388,8 +388,15 @@ By default, Item shows an auto tooltip when content overflows.
 >
   This shows custom tooltip only when text overflows
 </Item>
+
+{/* Explain why the item is unavailable */}
+<Item isDisabled tooltip="Available on the Enterprise plan">
+  Row-level security
+</Item>
 ```
 
+A disabled item keeps showing its tooltip — that is usually where the reason for being unavailable is written. Browsers stop dispatching mouse events on elements carrying the native `disabled` attribute, so an item that has a tooltip is marked with `aria-disabled` instead and kept inert: activation handlers are dropped and clicks (including the ones Enter and Space produce) do nothing.
+
 ## Accessibility
 
 ### Keyboard Navigation
@@ -408,7 +415,7 @@ By default, Item shows an auto tooltip when content overflows.
 ### ARIA Properties
 
 - `aria-label` - Provides accessible label when no visible label exists
-- `aria-disabled` - Indicates disabled state
+- `aria-disabled` - Indicates disabled state. The native `disabled` attribute is only added on top of it when the item renders as a form control (`as="button"`, for instance) and has no tooltip to keep hoverable
 - `aria-selected` - Indicates selection state when applicable
 - `tabIndex` - Controls focus behavior
 

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,113 @@ succeeds.
 
 ### States
 
+### Sorting Affordance
+
+A sortable header shows nothing at rest. Hover it — or focus it from the keyboard
+— and the sort arrow fades in at 40%, pointing the way a press would sort it
+(ascending, for a column that is currently unsorted). Press it and the arrow goes
+solid and stays that way with the pointer gone, which is what separates a hint
+from a state.
+
+The arrow keeps its slot throughout, so none of this shifts the label. A
+non-sortable column has no arrow at all — the hint is not a reason to render one.
+
+### 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.158.0",
+  "version": "0.159.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {