nexus-shared 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,262 @@
+# Changelog
+
+Notable changes to `nexus-shared`. The **values** of exported constants count as API here: several of them are the
+Nexus backend's own numbers, and a value that differs from the backend by one does not fail loudly — it silently
+means the wrong thing on every record and every permission check.
+
+## 3.0.0
+
+**Breaking. This changes the value of exported constants, and `2.0.0` is on npm with the old ones.** Publishing it
+as a patch or a minor would hand `^2.0.0` consumers different numbers under a compatible-looking range, which is the
+worst way to ship this, so it takes a major. The owner chose the number on 2026-10-02, together with `nexus-public`
+and `nexus-admin`, which both depend on this package and so move to `3.0.0` with it; their `nexus-shared` range is
+now `^3.0.0`, because a bump of this one alone would leave them pulling the old, wrong constants.
+
+**`nexus-icons` must be installed at `1.1.0` or newer**, and the dependency range here says so. The chat components
+added in this version use `iconChecks`, `iconCornerUpLeft`, `iconMessageCircle`, `iconPaperclip`, `iconSend` and
+`iconUserPlus`, none of which exist in `nexus-icons@1.0.0`: with the old range a fresh install resolved to `1.0.0`
+and the build failed on six missing exports.
+
+### `NexusModule` — `Chat` added, and every module after it moved up one bit
+
+The backend's `EModules` gained `Chat` at bit 6, and everything after it shifted. `NexusModule` follows it exactly.
+A permission is a bitmask of these flags, so a package that kept the old numbers would grant and deny the wrong
+modules without any error to show for it.
+
+| Module | Was | Now |
+|---|---|---|
+| `None` | 0 | 0 |
+| `Migrations` | 1 | 1 |
+| `Configuration` | 2 | 2 |
+| `Identity` | 4 | 4 |
+| `Enterprise` | 8 | 8 |
+| `Drive` | 16 | 16 |
+| `Message` | 32 | 32 |
+| **`Chat`** | *(did not exist)* | **64** |
+| `Accounting` | 64 | **128** |
+| `Report` | 128 | **256** |
+| `Requisition` | 256 | **512** |
+| `Tenant` | 512 | **1024** |
+| `Subscription` | 1024 | **2048** |
+| `Reservation` | 2048 | **4096** |
+| `School` | 4096 | **8192** |
+| `Pharmacy` | 8192 | **16384** |
+| `Staffing` | 16384 | **32768** |
+| `Portfolio` | 32768 | **65536** |
+
+`NEXUS_MODULES` gained the matching entry (`key: "chat"`, `label: "Chat"`, `env: "API_CHAT"`), so `Chat` can be
+looked up, proxied and named in messages like every other module.
+
+**What to check when you upgrade.** Code that uses the names (`NexusModule.Reservation`) needs nothing. Anything
+that stored, transmitted or hard-coded a **number** has to be revisited:
+
+- permission masks saved in a database, a cache, a token claim or a settings file;
+- proxy URLs written with a number in place of a key (`/api/app/2048/…` is now `/api/app/4096/…`, and `reservation`
+  by key has always worked and still does);
+- a backend that has not taken the `Chat` shift yet — both sides move together or neither does.
+
+### `NEXUS_FLAGGED_STATUS` — 15 → 25
+
+The owner settled the record-status bands, and `ERecordStatus.Flagged` is seeded at **25**. `NexusCrudBackend`
+decides whether a row is flagged by comparing `recordStatus` to this constant, so a package on 15 while the backend
+writes 25 shows the wrong flag on every row, and flagging one writes a status the backend does not recognise.
+
+The bands, for anything that reasons about them:
+
+| Band | Range |
+|---|---|
+| Active | 0–39 |
+| — Active account | 0–29 |
+| — Flag | **25–29** |
+| — Pending, unverified, in review, approval required | 30–39 |
+| Trash | 40–59 |
+| Delete | 60 and above |
+
+`NEXUS_ACTIVE_STATUS` stays 0, and the `recordStatus < 40` reading of "a live record" that the rest of the code
+already assumes stays right.
+
+Note that **the flag is a range, 25–29, and this release still checks a single value.** Only the seeded member at 25
+has a meaning today, and the bands are about to become configurable per project, so a range-aware check belongs with
+that work rather than here. Do not read the single value as the final answer.
+
+### Removed: the archive
+
+The owner removed the archive on 2026-09-30: a record is live, in the trash, or deleted, and the way back from
+deleted lands it in the trash. The second put-away list and its second recovery path were the only reason the CRUD
+had both Restore and Recover, and the bands close up behind it — **Trash is 40–59 and Delete 60 and above**, so
+nothing stored keeps a meaning it no longer has. `recordStatus < 40` still reads "a live record".
+
+What goes, all of it breaking for anything that named it:
+
+- `CrudMode` loses `"archive"`, so a CRUD shows All, Flagged, Trash and Deleted.
+- `CrudRowActionName` and `CrudMassActionName` lose `"archive"` and `"restore"`. Recover, the trash's own way back,
+  is untouched: a CRUD that offered both now offers one.
+- `CrudEndpoints` loses `archive` and `restore`; `apiController` stops naming `Archive`, `Restore`, `MassArchive`,
+  `MassRestore`, `ArchiveListing` and `ArchivePagination`, and `lists`/`pages` lose their `archive` key.
+- `MessageActionName` loses `"archive"`, and the message builder its words and its "It can be restored from the
+  archive." confirmation detail. `"restore"` stays in the vocabulary: it is a plain verb, not the archive's.
+
+**What to check when you upgrade.** A CRUD that listed `"archive"` in `modes` or `actions` no longer compiles,
+which is the point — the endpoint behind it is gone from the backend too. A backend that still answers
+`ArchiveListing` is not asked for it any more.
+
+### Added: the chat
+
+A discussion on any record — a leave request the manager and a co-worker talk through, a purchase order, an
+applicant, a tender — behind one icon that says whether anything is waiting. Nothing that does not use it changes.
+
+- A conversation is named by three values, `ChatScope`: the **domain** (which kind of record), the **parent id** (the
+  record) and the **user id** (who is reading). The domain is the app's own enum, given either as a template
+  (`<Chat<EDomainTypes> …>`) or once in `ChatRegister`, the same way `ApiRegister` names the module enum. Without one
+  it is a plain number.
+- **No domain numbers are defined here.** They belong to the backend's `EDomainTypes`, and the warning at the top of
+  this file applies to them in full. `defineChatDomains` only gives an app's domains their names on screen.
+- `ChatButton` is an icon in three looks: quiet with no messages, the accent on its tint once there are messages, and
+  the accent filled with an unread badge once some are unread. One size in all three, with the badge over the corner,
+  so a column of them in a table does not move as the counts arrive.
+- `ChatSummaryCache` fills every icon that mounted in the same moment with **one call per domain**. A list whose rows
+  already carry their counts passes `summary` and makes no call at all.
+- `Chat` is the icon with the conversation in a popup; `ChatPanel` is the conversation on its own, for a record's own
+  page. Messages are **Markdown**: written in `MarkdownEditor` and drawn by `MarkdownView`. Enter sends and
+  Shift+Enter starts a line, except in a list or a code fence, where the editor keeps Enter; `sendKey="modifier"`
+  moves sending to Ctrl+Enter.
+- One mark where the time sits says how far a message of your own has got: a spinner while sending, a tick once the
+  server has it, two once `deliveredTo` holds somebody, two in the accent once `readBy` does.
+- Where the data comes from is one interface, `ChatSource`. `apiChatSource` goes through the app's `ChatBackend`
+  (`NexusChatBackend` by default); `localChatSource` keeps a conversation in memory for a demo or a test.
+- **The Nexus endpoints are the shape the Chat module is expected to take, not an API that answers today.**
+  `NexusModule.Chat` is a number and a proxy key; the controller is not built. Each difference, when it lands, is one
+  override on `NexusChatBackend`.
+- `check:themes` gained a rule: body text on the primary tint, which is a message bubble of your own. Every theme
+  clears AAA except catppuccin light at 6.84, so it is held to the AA 4.5 that applies to body text.
+- **A record holds many conversations.** `ChatScope` names the record; each conversation in it is a
+  `ChatConversation` with its own id and a type, `one-to-one` or `group`. `ChatPlaceSource` lists them and starts
+  them, `useChatPlace` is the hook, and `apiChatPlace` is the API one. A panel given a `source` still shows that one
+  conversation and no switch, so nothing that used the first round changes.
+- The panel's body has three views — the thread, the list of conversations, and New chat — and the bar moves between
+  them. With several conversations the title is the switch; with one it is just the title.
+- Starting a chat never asks for the type: one person makes a one-to-one, more make a group, and a name makes a
+  group either way. A one-to-one with somebody who already has one is expected to come back rather than be made
+  twice; `localChatPlace` keeps that rule.
+- `@` at the start of a word offers the people in the conversation, narrows as it is typed, and owns Enter while it
+  is open. A mention is plain `@Name`, or a Markdown link with `mentionHref`; either way the ids travel in the
+  draft's `mentions`.
+- `ChatSnapshot` gained `loaded`: a store that has read nothing yet holds empty counts, and a panel must not write
+  those over what a conversation list already knows.
+
+### Added: several at once, `TabButtons multiple`
+
+`TabButtons` picks one option; with `multiple` it picks several, so a list of choices that must be seen all at once
+(the weekdays a rule runs on, the letters or symbols a pattern allows) needs no second control. Nothing that does
+not pass it changes.
+
+- `value` is an array and `onChange` hands back the chosen values **in option order**, whatever order they were
+  clicked in. Values that match no option are ignored and never handed back.
+- The options are native checkboxes in a `role="group"`: Tab moves between them and Space toggles one. The group
+  still needs `aria-label` or `aria-labelledby`.
+- There is no sliding indicator: each chosen option is raised with the indicator's own colors, border and shadow,
+  and keeps the pointer, since a click takes it away again. An option that is not chosen sits flat on the track.
+- The options **wrap** onto more rows when they do not fit, each row as tall as a one-row track's options, and an
+  option is never narrower than it is tall, so a row of single letters lines up. On a touch screen
+  (`pointer: coarse`) every option is a medium control's height: 26 letters on a phone are 34px targets, not 22px.
+- Made and checked for the `nav` design (`/demo/tab-buttons`, "Several at once"); `design="list"` with `multiple`
+  renders checkboxes too, but has not been checked yet.
+
+### Added: inputs that follow others, `dependsOn`, and a row's own params, `cellParams`
+
+Two optional keys, added 2026-09-26 for the builder's class form, whose company model shows only when the class has a
+company or a branch and whose type arguments offer a key type in one row and a model in the next. Nothing that does
+not pass them changes.
+
+- **`dependsOn: ["hasCompany"]`** on an input's params (Form only). When a named input's value changes — typed, or
+  set from code — this input draws again **without mounting again** (nothing typed in it is lost) and its params are
+  read afresh, so getters for `hidden`, `readOnly`, `readOnlyMessage`, `label`, `hint` or `options` answer for the
+  values as they are now. Its rule is asked again too, so a `required` a getter switched on counts at once. An input
+  that names any is asked `hidden` each time it draws, so it can come and go; one that names none is asked once, when
+  the form draws, as before. Name the input itself to follow its own typing.
+- **`cellParams(row, name, index)`** on `TabularForm` and `GroupForm`: the params of one cell that differ from its
+  column's, such as a picker's `options` and `selectedOptions`. Asked as the row draws; return nothing for the
+  column's own params, and the **same object** for the same answer (the merged params are kept per answer, so the cell
+  does not draw again for nothing). Getters on either side stay getters. Rules still come from the column.
+
+### Added: a generated column in a tabular or group form
+
+Two optional props on `TabularForm` and `GroupForm`, for a column whose values a row's **position** decides rather
+than the user — a bitwise enum's value, a line number, a running total. Nothing that does not pass them changes.
+
+- `deriveRows(rows)` returns one patch per row and runs after every change, including a row being added, removed,
+  duplicated or **moved**. The patches are written as code writes, so only the cells whose value really changed
+  mount again and focus stays on the row's own menu: a keyboard can move a row twice in a row.
+- `cellReadOnly(row, name, index)` is asked for every cell as it renders and returns the reason a cell is
+  generated. The cell is locked and shows that reason as its read-only note. Because it is asked per render, a
+  column can lock and unlock while the form around it changes, which params cannot do — they are fixed once a form
+  opens.
+
+### Added: rows nobody may change, `rowReadOnly`
+
+One optional prop on `TabularForm` and `GroupForm`, for rows the user did not write and may not change — the fields
+a class inherits from its parent, shown first in the same grid as its own. Nothing that does not pass it changes.
+
+- `rowReadOnly(row, index)` returns the reason (or `true`). Every cell of such a row is read-only with that reason
+  as its note, the row's menu in a tabular form offers nothing (no insert, duplicate, move or remove), and the row
+  below it cannot move up past it. Nothing reorders the rows: keep the locked ones first.
+- A locked row says nothing about its columns: the column-header lock is worked out from the other rows in view, so
+  a grid of inherited rows and one own row does not put a lock on every header.
+
+### Added: a panel beside a CRUD form, `form.aside`
+
+An Add or Edit popup can show a panel next to its form: a preview of what a save would produce, a summary, a help
+panel. It takes a node, or a function handed `{ form, action, row }` — `form` being that popup's own `FormStore`, so
+a panel follows what is typed through `subscribeValue()` and the form around it never re-renders for it.
+
+The two are columns above 1000px, each scrolling on its own so a long form cannot push the panel off the screen, and
+they stack below that with the **form first**, in the DOM as well as on the screen. `--nx-crud-aside-width` sets the
+panel's share (default `clamp(20rem, 38%, 44rem)`). Pair it with a wide `form.size` — `xl` or `full`; a panel in a
+560px popup leaves the form nothing. A CRUD that passes no `aside` renders exactly what it did before, wrapper and
+all.
+
+### `TabularForm` reworked: one row control, rows that do not move, one lock per column
+
+The owner called the tabular design bad, from a screenshot of an 18-row table with one generated column. Every fault
+was in this component rather than in the page that used it, so every fix is here. Nothing needs a new prop, and a
+table that passed nothing new looks different — deliberately.
+
+**Breaking, visually and for tests.** Two things a consumer may be reaching for have moved:
+
+- **The remove column is gone.** Remove was a column of unlabelled `×` buttons at the end, beside a row menu that
+  already held Remove: two ways to act on one row, and a whole column spent on one of them. Now a row has one
+  control, the menu beside its number, holding Insert above, Insert below, Duplicate, Move up, Move down and Remove.
+  `removable` still decides whether Remove is offered. A test that clicked a button named `Remove <row>` opens the
+  row's menu instead: `Row 2 actions`, then the `Remove` item. `.nx-tabular__end` and `.nx-tabular__remove` are gone
+  from the DOM and the stylesheet; so is `--nx-tabular-end`, replaced by `--nx-tabular-menu` (the menu's slot width).
+- **The row number no longer opens the menu.** It used to *become* the menu on hover: the number faded out and dots
+  faded in over it, so the numbering looked broken and the grid felt unstable as the pointer crossed it. The number
+  now stays where it is, right-aligned, at every moment, and the menu button sits beside it in its own space,
+  always present. The number column is that much wider.
+
+**Fixed, with no change to how a table is written:**
+
+- **Every row is one line high, whatever it holds.** The row's grid track was sized by its tallest cell, so a single
+  `textarea` column of `rows: 2` made every cell of its row 20px taller than the row's own box — drawing the cells,
+  their edges and their focus rings over the rows below. One row of content therefore looked taller than its
+  neighbours, and a focus ring bled outside its cell. The row now has one track exactly its own height, cells keep
+  what they hold inside their bounds, and a `textarea` fills its cell and scrolls inside it.
+- **No resize grips in cells.** A `textarea` in a cell took `resize: vertical` from the multi-line input rule, so
+  every cell of such a column offered a grip that would break the alignment of its row. They are `resize: none` now.
+- **A filled cell and an empty one are drawn the same.** Same consequence as the above: only the cell with text was
+  tall enough to show what the overflow was doing.
+- **`maxHeight` comes down to whole rows.** The scroller used to end wherever the number fell, cutting the last row
+  in half, which reads as broken rather than as scrollable. The component measures its header, its frame and its
+  real row height and caps itself just under what was asked for. A number too small for one row is left alone.
+- **A generated column says so once.** `cellReadOnly` put a lock in every cell of the column it locked — eighteen
+  locks for one fact. The lock is now on the **column header**, with the reason as its title, and the cells keep the
+  read-only tint and their own reason, which still shows under the table when one is used. A lock that really is per
+  row (some rows locked, not all) leaves the header alone and is drawn per cell as before.
+- **Less chrome.** The frame is `--nx-border` rather than `--nx-border-strong`: the sheet draws every line it needs
+  inside itself, and in a popup or a panel the strong edge was a box around a box around boxes.
+
+## 2.0.0
+
+The rewrite: compiled `dist` with the entry points `.`, `/client`, `/server` and `/styles.css`, in place of 1.x's
+raw TypeScript from `src` with `.`, `/client` and `/interface`. A major version, so nobody on `^1.1.21` is moved
+into a different API.

package/README.md

@@ -97,7 +97,7 @@ All styles sit in `@layer nexus.*`, so an app's own CSS overrides any token or c
 | Component | Import | Notes |
 |---|---|---|
 | `Button` | `nexus-shared` | Variants `primary`, `secondary`, `ghost`, `danger`; sizes `sm`, `md`, `lg`; `icon`, `iconEnd`, `loading`, `block`; `hoverTone` |
-| `TabButtons` | `nexus-shared/client` | Pick one option; sliding indicator; sizes, `tone="primary"`, `labels="selected"` (icons, label on the selected option), `block`, disabled options; `design="list"` for a vertical list with descriptions and badges |
+| `TabButtons` | `nexus-shared/client` | Pick one option; sliding indicator; sizes, `tone="primary"`, `labels="selected"` (icons, label on the selected option), `block`, disabled options; `design="list"` for a vertical list with descriptions and badges; `multiple` to pick several, wrapping onto more rows |
 | `SplitButton` | `nexus-shared/client` | A main action with a menu of alternatives; the pick becomes the main button, and `storageKey` remembers it for the next visit |
 | `Menu`, `ContextMenu` | `nexus-shared/client` | A dropdown menu under a button, and a right-click menu: icons, shortcuts, descriptions, `tone="danger"`, links, `kind="radio"` or `"checkbox"` |
 | `Toaster`, `toast` | `nexus-shared/client` | Toast messages from anywhere: `toast.success(title, message)`, `toast.promise`, `toast.loading`, actions, positions; one `<Toaster />` in the layout |
@@ -126,14 +126,14 @@ All styles sit in `@layer nexus.*`, so an app's own CSS overrides any token or c
 | `FormButtons` | `nexus-shared/client` | A form's status line and buttons on their own, such as in a popup's footer |
 | `useForm`, `useFormValue`, `useFormValues`, `useFormStatus` | `nexus-shared/client` | A store for the page to hold, and hooks that render again when a value, any value, or the status changes |
 | `FormStore` | `nexus-shared` | The store and the form's handle: `getValue`, `getChanges`, `set`, `load` (with `keepChanged`), `reset`, `validate`, `setErrors`, `focus`, `submit` |
-| `DataTable`, `useTable` | `nexus-shared/client` | Rows with a search (rows per page inside it), sorting by column, pages, a selection with one split button of actions over the headings, icon buttons and a menu per row, columns the user orders, resizes, pins, and hides, an options menu (CSV, print, import), and loading, empty, and failed states; rows given, loaded once, or a page per query from a server; page size, sort, and the columns remembered with `stateKey` |
+| `DataTable`, `useTable` | `nexus-shared/client` | Rows with a search (rows per page inside it), sorting by column, pages, a selection with one split button of actions over the headings, icon buttons and a menu per row, columns the user orders, resizes, pins, and hides, a band of headings over the columns that belong together (`group`), an options menu (CSV, print, import), and loading, empty, and failed states; rows given, loaded once, or a page per query from a server; page size, sort, and the columns remembered with `stateKey` |
 | `TableStore` | `nexus-shared` | The table's state and handle, outside React: `reload`, `upsert`, `patch`, `remove`, `select`, `getSelected`, `setSearch`, `setSort`, `setPage` |
-| `Crud` | `nexus-shared/client` | A module's records in one component: a controller's endpoints, the table's columns, and the form's input params in; the lists (all, flagged, archived, trash, deleted) and actions the user may use, the records the user pinned above the list, Add and Edit popups on `ApiForm`, details, actions on one record or many, and a cache of lists while the page is open |
+| `Crud` | `nexus-shared/client` | A module's records in one component: a controller's endpoints, the table's columns, and the form's input params in; the lists (all, flagged, trash, deleted) and actions the user may use, the records the user pinned above the list, Add and Edit popups on `ApiForm`, details, actions on one record or many, and a cache of lists while the page is open |
 | `Permissions`, `NexusPermissions`, `definePermissions`, `canCall` | `nexus-shared` | May the user call this endpoint? The app registers its rules once; `NexusPermissions` reads the Nexus backend's access actions. Everything is allowed until then |
 | `CrudBackend`, `NexusCrudBackend`, `defineCrudBackend` | `nexus-shared` | How a CRUD talks to a backend beyond its endpoints: page requests and answers, mass action bodies, flag and pin marks. Nexus's by default |
 | `configureCrud`, `getCrudSettings` | `nexus-shared` | What every CRUD in the app follows: how many records a user may pin (100 by default) |
 | `queryRows`, `formatCellText`, `sortRows`, `pageButtons`, `CrudCache`, `crudRowActions` | `nexus-shared` | Pure helpers behind the table and the CRUD: search, sort, and page rows as the table does, a value as its cell writes it, the page buttons, the cache, and which actions a list offers |
-| `readApiResponse`, `sendApiRequest`, `matchFieldErrors` | `nexus-shared` | Pure helpers behind the API form: read an answer as success or failure, send a URL as it is, and match server field names to inputs |
+| `readApiResponse`, `readErrorMessages`, `sendApiRequest`, `matchFieldErrors`, `matchInputName`, `formErrorsFromResult` | `nexus-shared` | Pure helpers behind the API form: read an answer as success or failure, every problem it carries as one list, send a URL as it is, match server field names to inputs, and turn a failed answer into what a form shows |
 | `api`, `apiOptionsLoader`, `configureApi` | `nexus-shared/client` | API calls from the browser, through the app's proxy or straight to a module: toasts worded by the message builder, `api.confirm` to ask first, one request for the same GET at once; a dropdown's `loadOptions` from a pagination endpoint |
 | `serverApi`, `configureServerApi`, `createApiProxy` | `nexus-shared/server` | API calls from the server, straight to each module's root, with the user's token and Next.js caching; the proxy route the browser calls |
 | `ApiModules`, `NexusApiModules`, `defineApiModules`, `ApiRegister` | `nexus-shared` | An app's API modules: its own module enum (named once in `ApiRegister`, so endpoints take only those), where each root is, and the proxy on or off. Extend `ApiModules` for another backend |
@@ -179,6 +179,10 @@ import { TabButtons } from "nexus-shared/client";
   `icon`, a `description` on a second line, and a `badge` (a count) at the end. The selected row is tinted, marked
   by a bar at its start, and its label turns bold; `tone="primary"` tints it with the primary color. ↑ and ↓ move
   the selection. The nav design is the old project's `nav-tabs`, this one its `list-tabs`.
+- `multiple`: several at once. `value` is an array and `onChange` hands back the chosen values in option order.
+  Each chosen option is raised as the one choice's indicator is, the options wrap onto more rows when they do not
+  fit (never narrower than tall, so single letters line up), and on a touch screen each grows to a medium control's
+  height. They are checkboxes: Tab moves between them and Space toggles one.
 - Native radio buttons: arrow keys move the selection, and `name` makes it part of a form. Needs `aria-label` or `aria-labelledby`.
   `form` sets the form the choice belongs to, as in HTML; an id that matches no form keeps a switch that is not a
   value (the Markdown editor's views) out of the form around it.
@@ -715,9 +719,14 @@ const ROOM_INPUTS: InputParams[] = [
 - **One save at a time.** Save waits with a spinner; another click, Enter, or Ctrl+S does nothing until it ends. A save
   makes the values the form's own ("Unsaved changes" clears; values typed meanwhile stay changes). `onSubmit` returns
   `{ ok: false, errors, message }` to say why not, and a thrown error shows its message.
-- **Server messages.** `ApiForm` reads Nexus answers (`inputName` names the inputs) and ASP.NET Core problem details
-  (`errors` by field), matched to inputs without case and by the first part of a path (`Addresses[1].City`). Names that
-  match no input, and failures without fields, show beside the buttons. An input's message clears when its value changes.
+- **Server messages.** The server's own words are what the user reads. `ApiForm` shows **every** message a refusal
+  carried - a Nexus answer's `errorMessages` (a list, or one message object, or one message and its codes at the top
+  level) and ASP.NET Core problem details (`errors` by field) - each on the input its `inputName` names, matched without
+  case and by the first part of a path (`Addresses[1].City`). Names that match no input of this form, messages that name
+  none, and failures without fields show beside the buttons; nothing is swallowed and nothing is shown twice. A sentence
+  of ours by HTTP status ("Someone else changed this record…") is the fallback for an answer that explained nothing.
+  `messageCode` and `errorCode` ride along in `answer.errorMessages` for the log and for `onError` to react to, and are
+  never shown as the sentence. An input's message clears when its value changes.
 - **Nothing lost.** `draftKey` keeps unsaved changes in IndexedDB (after a 600 ms pause, and at once when the page hides
   or the form leaves) and brings them back with a note and Discard; drafts changed on the server since are named. Cancel
   asks before it drops changes, and the page asks before it closes with some (`confirmLeave`, on without a draft).
@@ -755,6 +764,10 @@ export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: r
   an endpoint has registered the modules on either side. `NexusApiModules` is the Nexus set (roots from `API_<MODULE>`,
   as in the previous project; `NexusModule.None` for the app's own `/api` routes) and runs when nothing is registered.
   The list is checked: keys and values must be unique, and keys fit in a URL.
+- **`NexusModule`'s numbers are the backend's `EModules` flags**, and a permission is a bitmask of them, so a value
+  that disagrees with the backend by one bit grants or denies the wrong module in silence. They changed after
+  2.0.0: `Chat` took bit 6 and `Accounting` through `Portfolio` each moved up one. Code that uses the names needs
+  nothing; anything holding a stored or hard-coded **number** does. [CHANGELOG.md](CHANGELOG.md) has the table.
 - **Module types from one place.** An app names its enum once, next to `defineApiModules`:
   `declare module "nexus-shared" { interface ApiRegister { module: HrModule } }`. Every endpoint, call, `ApiForm`,
   and CRUD then takes only those modules (`AppModule`), so `{ module: NexusModule.Reservation, … }` in an HR app is a
@@ -766,11 +779,37 @@ export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: r
   `proxies(module)` mixes the two, such as uploads straight to the Drive module and the rest through the proxy.
 - **One engine, two clients.** `api` and `serverApi` are two settings of `createApiClient`: it fills `{id}` in the path
   from `params` or the body, adds the query, headers, and token, waits up to `timeout` (60 s), tries a failed GET once
-  more (a save never twice), and reads every answer as an `ApiResult` (`ok`, `status`, `result`, `message`, `errors`,
-  `messageCode`, `errorCode`, `network`, `timeout`, `aborted`). A failed call is an answer, never a throw; an aborted one
-  shows nothing. Next.js's own signals (`headers()` while prerendering, `redirect()`) pass through untouched.
+  more (a save never twice), and reads every answer as an `ApiResult` (`ok`, `status`, `result`, `message`,
+  `errorMessages`, `errors`, `messageCode`, `errorCode`, `network`, `timeout`, `aborted`). A failed call is an answer,
+  never a throw; an aborted one shows nothing. Next.js's own signals (`headers()` while prerendering, `redirect()`) pass
+  through untouched.
+- **What the server said wins.** A refusal is shown in the backend's own words whenever it sent any:
+  `{ isSuccess, code, errorMessages: [{ message, messageCode, errorCode, inputName }] }` becomes
+  `result.errorMessages` in that order (one message object instead of a list, a single `errorMessage`, and an older
+  answer's one message at the top level all read into the same list), `result.errors` holds the ones that name an input,
+  and `result.message` is all of them joined for a toast. `messageCode` and `errorCode` are for the log and for a page to
+  react to - never the sentence a user reads. The messages built from the HTTP status are the fallback for an answer that
+  explained nothing.
+- **Answers of another shape.** Nexus answers and ASP.NET Core problem
+  details are read out of the box. A backend that answers its own envelope registers one reader for the whole app:
+
+  ```ts
+  // Reads { success, message, data, error: { code, message, fields } } — the answer becomes ok, result, message, errors
+  const read: ApiResponseReader = (body, status) => {
+    const answer = body as BackendAnswer | null;
+    if (answer?.success) return { ok: true, status, result: answer.data, message: answer.message };
+    const fields = Object.entries(answer?.error?.fields ?? {}).map(([name, list]) => [name, list.join(" ")]);
+    return { ok: false, status, message: answer?.error?.message, messageCode: answer?.error?.code, errors: Object.fromEntries(fields) };
+  };
+  configureApi({ read });          // the browser
+  configureServerApi({ read });    // and the server, so both sides read one envelope
+  ```
+
+  It is the fallback of every call that does not bring a `read` of its own, which is what the components that call
+  inside themselves need: a `Crud`'s lists and actions and an `ApiForm`'s save have no place to pass one. A call's own
+  `read`, and an `ApiForm`'s `readResponse`, still win.
 - **Toasts in the browser.** Errors always, successes for POST, PUT, PATCH, and DELETE; the same failure twice at once
-  shows once; `toast: false`, `true`, or `{ success, error, loading }` per call; `configureApi({ toast, headers,
+  shows once; `toast: false`, `true`, or `{ success, error, loading }` per call; `configureApi({ toast, headers, read,
   onSignedOut })` for the app. The server shows nothing and logs network failures, timeouts, and 5xx.
 - **One message builder.** `buildMessage(kind, { action, subject, count, status })` words every message, and
   `messages.success`, `.failure`, `.reason`, `.loading`, `.confirm`, `.label`, and `.forResult` are short ways to call
@@ -778,8 +817,8 @@ export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: r
   texts and action words are one table: `configureMessages` rewords or translates all of them at once, and an action
   of the app's own is its words (`{ verb: "check in", done: "checked in", doing: "Checking in", object: "the guest" }`).
 - **A controller's lists.** `apiController` names the lists as the Nexus backend does: `listing` and `pagination` are the
-  active records' (`NormalListing`, `NormalPagination`), and `lists.flag`, `lists.trash`, `pages.archive`, … the others
-  (`FlagListing`, `TrashListing`, `ArchivePagination`, …), for the CRUD component.
+  active records' (`NormalListing`, `NormalPagination`), and `lists.flag`, `lists.trash`, `pages.trash`, … the others
+  (`FlagListing`, `TrashListing`, `TrashPagination`, …), for the CRUD component.
 - `npm run test:api` checks the builder, routes, modules (another app's enum, the proxy on and off), the engine, the
   server client, and the proxy; `scripts/browser-checks/api-calls.cjs` in the template checks `/demo/api`.
 
@@ -792,7 +831,8 @@ import { DataTable, useTable } from "nexus-shared/client";
 const COLUMNS: TableColumn<Booking>[] = [
   { key: "no", label: "Booking", width: "7rem", movable: false, pinnable: false },   // stays first, and stays put
   { key: "guest.name", label: "Guest" },                                   // a path into the row
-  { key: "amount", label: "Amount", format: "money", prefix: "Rs. " },    // number, money, percent, date, time, date-time, boolean
+  { key: "amount", label: "Amount", format: "money", prefix: "Rs. ", group: "Amount details" },   // number, money, percent, date, …
+  { key: "due", label: "Due", format: "money", prefix: "Rs. ", group: "Amount details" },   // one heading over both: the header is two rows
   { key: "status", label: "Status", options: [{ value: 1, label: "Confirmed", tone: "success" }] },   // a tag
   { key: "paid", label: "Paid", format: "boolean", resizable: false },     // keeps its width
   { key: "created", label: "Booked", format: "date-time", hidden: true },  // shown from the Columns menu
@@ -806,11 +846,19 @@ const table = useTable<Booking>();
 table.upsert(saved); table.patch(7, { paid: true }, { flash: true }); table.remove([7, 8]); await table.reload();
 ```
 
-- **Columns are params**, one plain object each, as inputs are: `key` (a field or a path), `label`, `format`, `decimals`,
-  `prefix`, `suffix`, `options` (labels for an enum's values; a `tone` draws a tag with a dot of its color), `value`,
-  `render`, `text`, `width`, `minWidth`, `align`, `wrap`, `sortable`, `sortKey`, `searchable`, `hidden`, `hideable`,
-  `movable`, `resizable`, `pinnable`, `pinned`. Numbers line up at the end in tabular figures; dates and times follow the
-  user's settings; moments show in the user's zone once the page has hydrated; long text ends in … at the column's width.
+- **Columns are params**, one plain object each, as inputs are: `key` (a field or a path), `label`, `group`, `format`,
+  `decimals`, `prefix`, `suffix`, `options` (labels for an enum's values; a `tone` draws a tag with a dot of its color),
+  `value`, `render`, `text`, `width`, `minWidth`, `align`, `wrap`, `sortable`, `sortKey`, `searchable`, `hidden`,
+  `hideable`, `movable`, `resizable`, `pinnable`, `pinned`. Numbers line up at the end in tabular figures; dates and
+  times follow the user's settings; moments show in the user's zone once the page has hydrated; long text ends in … at
+  the column's width.
+- **Columns in bands.** `group` is the heading above a column (`{ key: "amount", label: "Total", group: "Amount
+  details" }`); the columns next to each other that name the same one share it, and the header reads in two rows, the
+  bands on top and the columns' own headings under them. A column with no group keeps one heading as tall as both rows,
+  and so do the numbers and checkbox column and the actions. A band is a heading and nothing more: it sorts nothing, has
+  no menu and no edge to drag, and the columns stay one flat list, so hiding, ordering, widths, pins and the export are
+  as they were. The bands are read off the order on screen: a column dragged out of its run takes its band's heading
+  with it, and the run it left draws that heading again. With no group anywhere the header is one row.
 - **Rows three ways.** Given (`rows`) or loaded once (`load`), the table searches, sorts, and pages them itself: every word
   must match, in any column, with or without accents, and 10,000 rows search in about 0.5 ms a keystroke. A page at a time
   (`load` with `paging="server"`), each search (after 300 ms without typing, or Enter), sort, and page is one request; a
@@ -865,7 +913,7 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
 />
 ```
 
-- **Lists.** All (`NormalListing` or `NormalPagination`), Flagged, Archived, Trash, and Deleted, as icon tabs with the
+- **Lists.** All (`NormalListing` or `NormalPagination`), Flagged, Trash, and Deleted, as icon tabs with the
   chosen one named. A list shows when it is in `modes`, has its endpoint, and the user may call it.
 - **Pinned records.** `PinListing` answers the records the user pinned: they sit in a section above the active list that
   folds open and shut, and in the list and its pages as well. One limit holds for every CRUD in the app
@@ -873,13 +921,12 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
   in the order they were picked, and says so; lowering the limit never unpins anything, so a user over it can still
   unpin and can pin again once they are under it.
 - **Actions.** On a record in the lists of active records: View details, Edit (an icon on the row), Flag, Pin,
-  Archive, Move to trash; in the archive: Restore; in the trash: Recover, Delete permanently; in the deleted list: Move
-  back to trash. On selected records: the same, plus a new Description for all of them. Each shows only when it is in
+  Move to trash; in the trash: Recover, Delete permanently; in the deleted list: Move back to trash. On selected records: the same, plus a new Description for all of them. Each shows only when it is in
   `actions`, has its endpoint, and is allowed. A controller without a trash (no endpoint, or left out of `actions`) offers
   Delete where Move to trash would be; a trash the user may not use never becomes Delete.
-- **Questions and messages.** Archive, Move to trash, and Delete ask first ("Move 3 guests to the trash?", "This cannot be
-  undone."); Flag, Pin, Restore, and Recover are undone by a click and do not ask. Toasts come from the message
-  builder ("Sita Sharma archived.", "3 guests unpinned.").
+- **Questions and messages.** Move to trash and Delete ask first ("Move 3 guests to the trash?", "This cannot be
+  undone."); Flag, Pin, and Recover are undone by a click and do not ask. Toasts come from the message
+  builder ("Sita Sharma moved to the trash.", "3 guests unpinned.").
 - **Rows from the answers.** A record that moves to another list leaves the one in view (and the pinned section); flags,
   pins, and saved values change in place; a new record goes first; a server page loads again in the background to fill up. When a mass
   answer lists the records it changed, only those change.
@@ -900,4 +947,54 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
 - `scripts/browser-checks/crud.cjs` in the template checks `/demo/crud`: every list and action, the popups, the roles, the
   cache, a phone, and contrast in every theme.
 
+### Excel import and export
+
+A model's records in and out of a spreadsheet, against the backend's Excel controller bases
+(`NexusExcelController<TContract>` and `NexusExcelExportController<TContract>`): `Excel/Settings`, `Excel/Template`,
+`Excel/Verify`, `Excel/Import`, and the model's own export action.
+
+```tsx
+export const CITIES = MODULES.controller(NexusModule.Configuration, "City", "city");
+export const CITY_SHEET = excelEndpoints(CITIES, { subject: "city" });        // the four, and Excel/Export
+
+openExcelImport({ endpoints: CITY_SHEET, subject: "city", onImported: reload });   // the panel as a window
+<ExcelImport endpoints={CITY_SHEET} subject="city" onImported={reload} />          // or in the page
+
+await downloadExcelTemplate(CITY_SHEET);
+await exportExcel(CITY_SHEET, { subject: "city", rows: table.matches, query: { search, sort: "cityName", direction: "asc", filters } });
+```
+
+- **The template** is the backend's file, downloaded under the name its `Content-Disposition` gives it. Every list in it
+  is a dropdown and the ids beside a choice fill themselves, so the person types no code and pastes no id.
+- **A verify writes nothing.** The file goes up as form data, and the answer is the rows, judged: what would be added,
+  what is already a record, and what is waiting on a fix.
+- **The review is two collapsible editors** over those rows - **New rows** (which includes the rows to fix, since a row
+  with a problem is not yet a record) and **Already there** - built from the sheet's columns with the rules the sheet
+  told the person about, so a fix made here is checked the way the file was. What the server found wrong is listed under
+  the rows, each entry naming the cell as a spreadsheet does (`B7 - City name`) and taking the caret to it.
+- **The import sends rows, never the file again**, or every fix made on screen would be lost; every check runs again on
+  the way in. **A duplicate is never updated**: one left alone is not sent at all, and editing one sends it as a new
+  record. An import writes what it can and names the rest; only one that wrote nothing at all is a failure.
+- **A choice travels as its key**, out and back. The plain id in the sheet is for the person to read and is never read
+  back, so nothing copied out of a file or out of an answer can be posted to an endpoint as an id.
+- **The export is the server's file**, written from the search, the sort and the filters on screen - not a CSV of the
+  rows this browser holds. The row limit is the backend's (`Excel/Settings`, 5,000 by default, kept for the page's life);
+  over it the person is asked first, and the answer's own headers say what was written and what was left out.
+- **Generic, like the rest.** `ExcelBackend` is the class an app on another backend registers
+  (`defineExcelBackend(new MyExcelBackend())`): the request shapes, how the answers read, the upload field, and the names
+  of a download's headers. `NexusExcelBackend` is the default. `readExcelResponse` reads a refusal's `errorMessages`, so
+  "no city could be written" reaches the person in the backend's own words.
+- **A column draws its own input**: text, note, whole number, decimal, amount, date, time, Yes/No, and a choice shown
+  read-only with the words the person picked. A **date and time** is a text box, not a picker: the sheet's moment is a
+  zone-less wall clock while a picker's value is a UTC moment, so a picker would shift every value by the reader's offset.
+- `scripts/test-excel.mts` checks the endpoints, the answers, the inputs and the round trip; the template's
+  `scripts/browser-checks/excel.cjs` checks `/demo/excel`: every state, the two rules about the wire, both downloads, the
+  warning before a capped export, a phone, and contrast in every theme.
+
+In a table, `excel={{ endpoints: CITY_SHEET, subject: "city" }}` is the whole of it: the options menu (⋮) then offers
+**Download template**, **Import from a spreadsheet** (the panel as a window, after which the table reads its rows
+again) and **Export to Excel**, which sends the table's own search and sort with the page's `filters()`. A `Crud`
+passes it through as `table={{ excel }}` and drops the lists it had kept once an import has written. It replaces
+`onImport`, which stays for a page that imports its own way.
+
 Planned, following the previous Nexus project: a page status layout, and in the CRUD, audit logs in the details view.

package/dist/Client.Index.d.ts

@@ -1,9 +1,17 @@
+export * from "./Components/Chats/Chat.tsx";
+export * from "./Components/Chats/ChatButton.tsx";
+export * from "./Components/Chats/ChatComposer.tsx";
+export * from "./Components/Chats/ChatConversations.tsx";
+export * from "./Components/Chats/ChatPanel.tsx";
+export * from "./Components/Chats/ChatParts.tsx";
+export * from "./Components/Chats/ChatThread.tsx";
 export * from "./Components/Documents/Menu.tsx";
 export * from "./Components/Documents/SplitButton.tsx";
 export * from "./Components/Documents/TabButtons.tsx";
 export * from "./Components/Forms/ApiForm.tsx";
 export * from "./Components/Forms/Crud.tsx";
 export * from "./Components/Forms/CrudParts.tsx";
+export * from "./Components/Forms/ExcelImport.tsx";
 export * from "./Components/Forms/Form.tsx";
 export * from "./Components/Forms/SubmitForm.tsx";
 export * from "./Components/Inputs/Calendar.tsx";
@@ -37,8 +45,11 @@ export * from "./Components/Layouts/ThemeSwitcher.tsx";
 export * from "./Components/Layouts/Toaster.tsx";
 export * from "./Components/Viewers/DataTable.tsx";
 export * from "./Components/Viewers/DataTableParts.tsx";
+export * from "./Helpers/ChatHooks.ts";
 export * from "./Helpers/DatePreferences.ts";
 export * from "./Helpers/DragHelpers.ts";
 export * from "./Helpers/PopoverHelpers.ts";
 export * from "./Services/BrowserApi.ts";
+export * from "./Services/ChatApi.ts";
+export * from "./Services/ExcelApi.ts";
 export * from "./Services/ThemeService.ts";

package/dist/Client.Index.js

@@ -1,12 +1,20 @@
 // Client components and browser services: files here start with "use client" or use browser APIs.
 // Import from "nexus-shared/client".
 // Components
+export * from "./Components/Chats/Chat.js";
+export * from "./Components/Chats/ChatButton.js";
+export * from "./Components/Chats/ChatComposer.js";
+export * from "./Components/Chats/ChatConversations.js";
+export * from "./Components/Chats/ChatPanel.js";
+export * from "./Components/Chats/ChatParts.js";
+export * from "./Components/Chats/ChatThread.js";
 export * from "./Components/Documents/Menu.js";
 export * from "./Components/Documents/SplitButton.js";
 export * from "./Components/Documents/TabButtons.js";
 export * from "./Components/Forms/ApiForm.js";
 export * from "./Components/Forms/Crud.js";
 export * from "./Components/Forms/CrudParts.js";
+export * from "./Components/Forms/ExcelImport.js";
 export * from "./Components/Forms/Form.js";
 export * from "./Components/Forms/SubmitForm.js";
 export * from "./Components/Inputs/Calendar.js";
@@ -41,9 +49,12 @@ export * from "./Components/Layouts/Toaster.js";
 export * from "./Components/Viewers/DataTable.js";
 export * from "./Components/Viewers/DataTableParts.js";
 // Helpers
+export * from "./Helpers/ChatHooks.js";
 export * from "./Helpers/DatePreferences.js";
 export * from "./Helpers/DragHelpers.js";
 export * from "./Helpers/PopoverHelpers.js";
 // Services
 export * from "./Services/BrowserApi.js";
+export * from "./Services/ChatApi.js";
+export * from "./Services/ExcelApi.js";
 export * from "./Services/ThemeService.js";

package/dist/Components/Chats/Chat.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import type { ChatDomainValue } from "../../Interfaces/ChatInterfaces.ts";
+import { type PopupSize } from "../Layouts/Popup.tsx";
+import { type ChatPanelProps } from "./ChatPanel.tsx";
+export interface ChatProps<TDomain extends ChatDomainValue = ChatDomainValue> extends Omit<ChatPanelProps<TDomain>, "scope" | "header" | "enabled" | "height"> {
+    /** Which kind of record: `EDomainTypes.Leave`. */
+    domain: TDomain;
+    /** The record's own id. */
+    parentId: string | number;
+    /** Who is reading and writing. */
+    userId: string | number;
+    /** What the icon is called, in its tooltip and for a screen reader. Default: the domain's name, else "Discussion". */
+    label?: string;
+    /** Default `md`, as the other controls in a row; `sm` for a dense table. */
+    buttonSize?: "sm" | "md";
+    /** How wide the popup is. Default `md` (560px). */
+    popupSize?: PopupSize;
+    /** How tall the conversation is inside the popup. Default `min(60vh, 520px)`. */
+    height?: number | string;
+    /** The popup's title bar. Default: the panel's `title`, else the domain's name and the record's id. */
+    popupTitle?: ReactNode;
+    /** Opened or closed. */
+    onOpenChange?: (open: boolean) => void;
+    /** Class of the trigger icon. */
+    className?: string;
+}
+/** The chat icon for a record, and the conversation in a popup. */
+export declare function Chat<TDomain extends ChatDomainValue = ChatDomainValue>({ domain, parentId, userId, label, buttonSize, popupSize, height, popupTitle, onOpenChange, className, summary, title, description, ...panel }: ChatProps<TDomain>): import("react").JSX.Element;

package/dist/Components/Chats/Chat.js

@@ -0,0 +1,19 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { iconMessageCircle, InlineIcon } from "nexus-icons";
+import { useState } from "react";
+import { chatDomainLabel } from "../../Helpers/ChatBackend.js";
+import { Popup } from "../Layouts/Popup.js";
+import { ChatButton } from "./ChatButton.js";
+import { ChatPanel } from "./ChatPanel.js";
+/** The chat icon for a record, and the conversation in a popup. */
+export function Chat({ domain, parentId, userId, label, buttonSize = "md", popupSize = "md", height, popupTitle, onOpenChange, className, summary, title, description, ...panel }) {
+    const [open, setOpen] = useState(false);
+    const scope = { domain, parentId, userId };
+    const named = title ?? (chatDomainLabel(domain) ? `${chatDomainLabel(domain)} · #${String(parentId)}` : `Discussion · #${String(parentId)}`);
+    const change = (next) => {
+        setOpen(next);
+        onOpenChange?.(next);
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(ChatButton, { scope: scope, summary: summary, label: label ?? chatDomainLabel(domain) ?? "Discussion", size: buttonSize, className: className, onClick: () => change(true) }), _jsx(Popup, { open: open, onClose: () => change(false), title: popupTitle ?? named, description: description, icon: _jsx(InlineIcon, { icon: iconMessageCircle }), variant: "window", size: popupSize, reopen: "restore", flush: true, closeOnBackdrop: false, children: _jsx(ChatPanel, { ...panel, scope: scope, summary: summary, title: named, header: false, enabled: open, height: height ?? "100%" }) })] }));
+}