@cube-dev/ui-kit 0.158.0 → 0.160.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.160.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.160.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.160.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.160.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.160.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.160.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.160.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.160.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.160.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.160.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.160.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.160.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.160.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.160.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.158.0";
+const VERSION = "0.160.0";
 const TASTY_VERSION = "3.0.1";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/components/actions/Button.md

@@ -15,7 +15,7 @@ A versatile action component that triggers commands and navigates users.
 
 ## Properties
 
-- **`type`** `'primary' | 'outline' | 'outline-2' | 'clear' | 'link'` (default: `outline`) — Visual style variant of the button (`outline-2` is identical to `outline` but uses `#surface-3` as the base fill; not available for the `special` theme)
+- **`type`** `'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'current'` (default: `outline`) — Visual style variant of the button (`outline-2` is identical to `outline` but uses `#surface-3` as the base fill; not available for the `special` theme. `current` derives its colors from the inherited text color and ignores `theme`)
 - **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Semantic colour palette theme
 - **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'inline' | number` (default: `medium`) — Button size. Use `'inline'` for link-type buttons or a number/string for custom sizes (e.g. `64` or `'8x'`)
 - **`icon`** — Icon rendered before the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
@@ -82,6 +82,7 @@ The `mods` prop accepts the following modifiers you can override:
 - `outline` – Border with transparent background; `isSelected` adds brand-tinted fill.
 - `clear` – No border, transparent background; `isSelected` adds brand-tinted fill.
 - `link` – Styled as a textual link.
+- `current` – Fill, border and label are mixed from the inherited text color (`#current`), so the button adopts the color of whatever container it sits in. The resting chip is a `#current.03` fill inside a `#current.08` border, and hover, pressed and selected step the same alpha ramp up from there; the label stays fully opaque. The focus ring stays `#primary-accent-text`, like every other type. Theme-agnostic — there is a single variant, and `theme` has no effect. Use it inside colored containers (alerts, banners, dark overlays, tooltips). `Item` has a `current` type too, shaped like its neutral `item` type instead: borderless and invisible at rest.
 
 ### Themes. `theme` prop
 
@@ -179,8 +180,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 +228,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

@@ -22,7 +22,7 @@ A foundational component that provides a standardized layout and styling for ite
 - **`suffix`** `ReactNode` — Element rendered after the content (before rightIcon)
 - **`description`** `ReactNode` — Description text displayed with the item
 - **`descriptionPlacement`** `'inline' | 'block'` (default: `inline`) — How the description is positioned relative to the main content. Defaults to `'block'` for `type="card"` and `type="header"`
-- **`type`** `'item' | 'header' | 'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'card'` (default: `item`) — Visual style variant
+- **`type`** `'item' | 'header' | 'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'card' | 'current'` (default: `item`) — Visual style variant
 - **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Semantic colour palette theme
 - **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'inline' | number` (default: `medium`) — Item size. Accepts custom number or string values
 - **`shape`** `'card' | 'button' | 'sharp' | 'pill'` (default: `button`) — Shape of the item border radius. Defaults to `'card'` for `type="card"`
@@ -84,7 +84,7 @@ The `mods` property accepts the following modifiers:
 - **`disabled`** `boolean` — Applied when isDisabled is true or when loading
 - **`loading`** `boolean` — Applied when isLoading is true
 - **`size`** `string` — Applied based on size prop value (xsmall, small, medium, large, xlarge, inline)
-- **`type`** `string` — Applied based on type prop value (item, header, primary, outline, outline-2, clear, link, card)
+- **`type`** `string` — Applied based on type prop value (item, header, primary, outline, outline-2, clear, link, card, current)
 - **`theme`** `string` — Applied based on theme prop value (default, danger, success, special, warning, note)
 - **`shape`** `string` — Applied based on shape prop value (card, button, sharp, pill)
 
@@ -100,6 +100,7 @@ The `mods` property accepts the following modifiers:
 - `clear` - Transparent item with minimal styling; `isSelected` adds brand-tinted fill
 - `link` - Link-styled item appearance (does not support icons or loading state)
 - `card` - Card appearance for notifications (supports `default`, `success`, `danger`, `warning`, `note` themes; defaults to `shape="card"`, `descriptionPlacement="block"`, uses semantic heading tags via `level` prop, and has `.5x` padding)
+- `current` - Same shape as `item` — no border, nothing painted at rest — but every color is derived from the inherited text color (`#current`) instead of the fixed `#surface-text`, so the item adopts the color of whatever container it sits in. The fill steps in on hover (`.04`), pressed (`.06`) and selected (`.09` → `.15`); the label stays fully opaque. Theme-agnostic: only supports the `default` theme (any other theme warns, since there is nothing for it to change). Use it inside colored containers — alerts, banners, dark overlays, tooltips. `Button` has a `current` type too, shaped like a standalone control instead: a resting `#current.03` chip inside a `#current.08` border
 
 ### Themes
 
@@ -256,6 +257,20 @@ Like headers, card labels use semantic heading tags (h1-h6) controlled by the `l
 </Item>
 ```
 
+### Current Type
+
+Use `type="current"` inside a container that paints its own text color. The fill and label are mixed from that inherited color, so the item matches the container without picking a theme — and keeps matching it if the container's color changes:
+
+```jsx
+<Block fill="#note-surface" color="#note-accent-text" padding="1.5x" radius="1cr">
+  <Item type="current" icon={<IconInfo />}>Adopts the note color</Item>
+</Block>
+
+<Block fill="#fixed-dark" color="#white" padding="1.5x" radius="1cr">
+  <Item type="current" icon={<IconInfo />}>Adopts white on a dark banner</Item>
+</Block>
+```
+
 ### With Loading State
 
 The `isLoading` prop displays a loading indicator and disables the item. The `loadingSlot` prop controls which slot the loading icon replaces:
@@ -388,8 +403,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 +430,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/docs/components/layout/Board.md

@@ -153,6 +153,8 @@ 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.
+- **`pre-selected`** — a live marquee covers the widget, so releasing the pointer
+  will select it. Never set at the same time as `selected`.
 - **`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.
@@ -166,15 +168,17 @@ 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:
+out. `pre-selected` draws the same edge with the ring dimmed, so committing a
+lasso only changes the strength of something already on screen. To restyle
+either, override the same keys:
 
 ```jsx
 <Board
   selectionMode="multiple"
   widgetProps={{
     styles: {
-      border: { '': true, selected: '#note-border' },
-      shadow: { '': false, selected: '0 0 0 1bw #note' },
+      border: { '': true, 'pre-selected': '#note-border', selected: '#note-border' },
+      shadow: { '': false, 'pre-selected': '0 0 0 1bw #note.40', selected: '0 0 0 1bw #note' },
     },
   }}
 />
@@ -188,6 +192,8 @@ Supported hooks for tests, E2E, and building your own selection overlay:
 - **`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.
+- **`data-pre-selected`** on a host a live marquee currently covers.
+- **`data-marquee`** on the board element while a marquee gesture is in progress.
 
 ### Base Properties
 
@@ -293,19 +299,24 @@ 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.
+its shape, clamping against the grid edge as a unit rather than collapsing, and
+committing once. While the band is out, the widgets it covers show a dimmed
+version of the selected edge (`pre-selected`), and no text can be selected under
+it.
+
+A group reflows 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 — but it does so as one
+block. Its members keep their exact offsets for the whole drag, and the widgets
+standing where it lands move out of its way rather than being packed between its
+members — whether it is dragged against the compaction axis or across it. When
+the drag ends the board compacts normally, so a group whose members could each
+float further settles on release. Under `compact="free"` (or `null`) nothing compacts,
+so the block stays precisely where it was dropped.
 
 ### Interactive content keeps its clicks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.158.0",
+  "version": "0.160.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {