# @exxatdesignux/ui — upgrade notes (bundled)

> **Agents:** read this before porting shell after `pnpm add @exxatdesignux/ui@…` / `npm install`.
> Default is **install only**. Run `exxat-ui upgrade` only when the notes (or the user) ask for shell sync.
> Binding rule: `exxat-consumer-package-upgrade`. Skill: `exxat-package-upgrade`.
>
> This file is the **latest 5 releases** only. Full history:
> https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/packages/ui/RELEASES.md
>
> Also available as `docs/exxat-ds/latest-release.md` after `exxat-ui sync-extras`.

## 1.9.0 — 2026-10-26

`DataTable` can now be reordered without a mouse: columns by keyboard, and rows
by drag, keyboard or menu. Security patches for vite, vitest and ip-address.

### Added

- **Keyboard column reorder.** `Alt`+`←`/`→` on a focused column header moves the
  column one visible slot (RTL-aware), and the column menu has Move Left / Move
  Right. Moves are announced politely. Pinned and locked columns stay put.
- **Row reorder (opt-in).** Pass `onRowsReorder(next, change)` and add the drag
  column with `withRowDragColumn(columns)`. Each row gets a grip, shown on hover
  or focus: drag it, press `Alt`+`↑`/`↓` on it, or open its Move menu (up, down,
  top, bottom). The callback receives the full dataset in its new order; rows
  hidden by search or filters keep their slots. The grip is inert, with a reason
  in its title, while the table is sorted or grouped.
- Design OS docs: DataTable shows sortable headers, Row reorder and Pagination.

- **Email composer.** One composer rail for every surface that emails people
  (`templates/email-*`): From and Reply to, To, Cc and Bcc as badges that fit the
  width, Subject with a Template menu, an email header and footer, the message,
  and Send, Schedule and Send test email. Selections with more than one group open
  on a Recipients page first. Mount `EmailComposerProvider` once, then open it with
  `useEmailComposer()` or the app's `useEmailHubAction`.
- **Merge fields.** `{{key}}` fields draw as badge chips in `RichTextEditor`
  (`mergeFields`) and in `MergeTagInput`, inserted with `@` or a searchable menu;
  clicking a chip shows what it means and what it becomes for one person.
- `RichTextEditor` gains `bare` (no box, fills its surface), `toolbarEnd` and
  `describeMergeField`. `FloatingSheetPanelToolbar` gains a `leading` slot so a
  rail's title can sit on the toolbar row.

### Changed

- Pagination buttons use the design-system `rounded-md` radius.

### Security

- vite 6.4.4, vitest 4.1.12 (`@vitest/mocker` 4.1.12) and an `ip-address`
  override of 10.7.4 or newer close eight Dependabot alerts.

### Upgrading from 1.8.1

```bash
pnpm add @exxatdesignux/ui@1.9.0
npx exxat-ui upgrade
npx exxat-ui doctor
```

## 1.8.1 — 2026-10-26

The utility bar's divider now lines up with the sidebar, and the Design OS docs
show the utility bar, breadcrumb and app shell as they really are.

### Fixed

- **Utility bar divider.** In the flush shell the toggle cell was the full
  icon-rail width and the divider added a pixel on top, so the divider sat 1px
  past the sidebar's right border. The cell is now 1px narrower and the divider
  lands on that border.

### Changed

- **Design OS docs.** The utility bar page covers every breadcrumb mode
  (ancestors only, current page, switcher, collapsed trail, long labels), the
  comfort and dense bars with a real breadcrumb, and Back mode scrolled. The
  Breadcrumb page shows the product trail's shapes and how it collapses and
  truncates. The App shell page is rebuilt for the compact shell, with expanded
  and reflow variants. Preview bars no longer draw a doubled bottom rule.
- `UtilityBarBackLeadingCluster` takes an optional `scrolled` prop, used only to
  show the scrolled look in the docs.

### Upgrading from 1.8.0

```bash
pnpm add @exxatdesignux/ui@1.8.1
npx exxat-ui upgrade
npx exxat-ui doctor
```

## 1.8.0 — 2026-10-23

Collapsed icon rails now preview themselves: hover or focus the rail and the full
panel floats over the page, like the mobile flyout without the scrim.

### Added

- **`useHoverPeek`** hook for hover and keyboard-focus peeks on collapsed rails.
  Opens after a short intent delay, closes after a short grace period, ignores
  touch, opens on `:focus-visible`, and closes on Escape.
- **Hover peek on the primary sidebar and the compact secondary panel.** Both open
  as a flush, square sheet with a sheet shadow over the page; the page does not
  reflow. The drill-in section (Settings, Tokens) uses the primary peek.
- **`rail-peek-reveal`** clip animation. It reveals the sheet from the rail's own
  width and is off under `prefers-reduced-motion`.
- **Agent context.** `exxat-rail-hover-peek` rule, the rail hover peek pattern doc,
  and a "Shipping a new pattern" checklist, mirrored for Claude, Cursor and
  Antigravity (`npx exxat-ui sync-extras`).

### Changed

- Mobile and 200 percent zoom keep the scrim flyout; there is no peek on touch.

### Security

- `follow-redirects` is pinned to 1.16.1.

### Upgrading from 1.7.1

```bash
pnpm add @exxatdesignux/ui@1.8.0
npx exxat-ui upgrade
npx exxat-ui doctor
```

## 1.7.1 — 2026-10-22

`exxat-ui upgrade` no longer breaks apps that changed files it leaves alone, and
says so when an upgraded file needs a newer copy of one of theirs.

### Fixed

- **Duplicate `"exxat-design-os"` nav key.** The upgrade decided the Design OS
  entry was missing by matching the exact package-builder call, so an app that
  already had its own entry (a placeholder layout, a local builder, an inline
  object) got a second one, and `tsc` rejected the duplicate key. It now detects
  the key in any form and leaves the app's entry alone. `exxat-ui doctor` flags a
  duplicate key.
- **Missing exports after an upgrade.** A refreshed shell file can import a name
  from a file the upgrade did not touch (for example `requestOpenCommandMenu`
  from a customised `components/command-menu.tsx`). The upgrade now checks this
  and prints each unresolved import with its fix, even on a `--quiet`
  postinstall run. `exxat-ui doctor` runs the same check on shell files.

### Changed

- **Release gate.** The upgrade-path gate gains a `--customised` scenario (an app
  with its own `command-menu.tsx` and its own Design OS nav entry). It requires no
  duplicate key, the upgrade to name the broken import, and the printed remedy to
  produce a clean typecheck.

### Upgrading from 1.7.0

```bash
pnpm add @exxatdesignux/ui@1.7.1
npx exxat-ui upgrade
npx exxat-ui doctor
```

If 1.7.0 already left you with a duplicate `"exxat-design-os"` key or a missing
`requestOpenCommandMenu` export, delete the extra nav entry (keep one, preferably
`buildDesignOsNavLayout(productSlug("exxat-design-os"))`) and run
`npx exxat-ui upgrade --only components/command-menu.tsx`, or add the export to
your own `command-menu.tsx`:

```tsx
export const OPEN_COMMAND_MENU_EVENT = "exxat:open-command-menu"
export function requestOpenCommandMenu() {
  window.dispatchEvent(new CustomEvent(OPEN_COMMAND_MENU_EVENT))
}
```

and have your menu open on that event.

## 1.7.0 — 2026-10-21

Leo can create data and components on any surface with one shared look and
behaviour, and `DataTable` gains split rows and a round of refinements.

### Added

- **Leo generation pattern.** `useLeoGeneration` and `useLeoGenerationGroup`
  hooks (`@exxatdesignux/ui/lib/leo-generation`), `LeoGenerationSurface`,
  `LeoGenerationSection`, `LeoGenerationStatus`, icon-only `LeoStopButton`, and
  `LeoBrandBackdrop`. One lifecycle (inited, thinking, completed), Stop until
  completed, and a section as the parent of its table.
- **`DataTable leoLoading`.** Flat Leo rows with per-row Stop and `splitCount`.
  The table owns no Leo lifecycle; the consumer passes rows and state.
- **Split rows.** `ColumnDef.split { items, cell, maxVisible }` renders grouped
  sub-rows inside one row as a list, 36px each, with "+N more" past four.
- **Avatar `xs` size** (20px) for one-line bands.
- **Agent context.** Rules `exxat-leo-generation` and `exxat-split-rows`, skill
  `exxat-leo-generation`, and a Leo generation pattern doc for Cursor, Claude,
  and Antigravity. Catalog entry: Leo Generation.

### Changed

- **Group bands inherit a declared status tone.** Every other column shares one
  grey wash; per-value hues are gone. The tint mixes in OKLab so amber no longer
  renders pink.
- **Column header** uses a washed-out grey (`--dt-header-bg`).
- **Group header** shows the count as a badge on the right. Group labels for
  multi-value cells come from each item's name or label instead of
  "[object Object]".
- **`StatusCell` defaults to the large badge** (`size="md"`); tag chips are 24px.
- **User chat `Bubble`** default is a washed-out grey.

### Fixed

- **Column menu** shows "Filter by this column" for columns defined by
  `cellKind` alone (people, status, tags).
- **Security.** Resolves 27 Dependabot alerts: `@tiptap/*` to `^3.31.4`, vitest 4
  for development, and raised overrides for transitive packages.

### Upgrading from 1.6.4

```bash
pnpm add @exxatdesignux/ui@1.7.0
npx exxat-ui upgrade
npx exxat-ui doctor
```

Check any hand-rolled Leo loading state: prefer `LeoGenerationSurface` or
`DataTable leoLoading`. If you rely on the old per-value group colours, declare
`tone` on the column's filter options for status or pill columns.
