nexus-shared 4.0.0 → 4.1.0

package/README.md

@@ -196,6 +196,13 @@ on this device, and reaches other open tabs:
 | `CrudTree` | `nexus-shared/client` | A controller's records as a lazy tree, with the `Crud`'s own Add and Edit forms and its trash, recover and delete calls: icons on each row, a toolbar Add New, and the picked record's fields and buttons for a panel the page draws; every change written into the tree and its kept pages, nothing read again |
 | `CrudTabFooter` | `nexus-shared/client` | The footer of a tab in a record's workspace: its words and Save in one bar that stays at the bottom of the tab while a long form scrolls, and sits in its place at the end; a plain bar elsewhere |
 | `RecordCards` | `nexus-shared/client` | One record that is not a list (a profile, my company) as a hero and cards of fields, of items with icon actions on the right, and of the page's own; every change in a popup (a form, steps such as a code sent then typed, a confirm), its answer drawn at once, and no Save on the page; loading held, a failed read per card with Try again, read-only, an ended session |
+| `MailThread`, `MailPeople`, `mailInboxColumns`, `mailRowUnread` | `nexus-shared/client` | A mail thread: its subject and people (From, To, Cc, Bcc as the backend shows them, folded to three names and "+2"), the record it is about, and the chat's own lines and reply box; a notification as an event line; the note a blind copy reads before replying; an inbox's columns and its strong unread row ([Mail thread](#mail-thread)) |
+| `MessageSource`, `apiMessageSource`, `localMessageSource`, `MessageBackend`, `NexusMessageBackend`, `defineMessageBackend` | `nexus-shared` (`apiMessageSource`: `/client`) | Where a mailbox's data comes from: the app's API through its backend (the Nexus Message module's `Mail` controller by default), or a mailbox in memory that keeps a backend's rules, for demos and tests |
+| `DomainCard`, `DomainCardFrame`, `DomainLine`, `useDomainCard` | `nexus-shared/client` | A record a message is about, as a card read live from its module: the kind an app gave a `card` on its `defineChatDomains` row (`domainCard({ load, view })`), drawn from params (title, code, state, fields, figures, lines, link) in every state - a placeholder that keeps its height, refused for 403 and 404, failed with Try again, read again when the record changes ([A record's card in a message](#a-records-card-in-a-message)) |
+| `MessageBell`, `useMessageUnread` | `nexus-shared/client` | The unread count on a top bar's button, one size whatever the count ("99+"), and the newest unread a click away; every bell of a page on one mailbox shares one read a minute, none while the tab is hidden ([Message bell](#message-bell)) |
+| `MessageUnreadPoller`, `messageUnreadPoller`, `refreshMessageUnread`, `mailUnreadWords` | `nexus-shared` | The page's one poller per mailbox, outside React, and the words a bell says |
+| `domainCardReads`, `refreshDomainCards`, `DomainCardRun`, `formatDays` | `nexus-shared` | One read of a record at a time, kept 30 seconds per reader; every card of a record read again when the page changed it; a card's read outside React; days written "1 day", "2.5 days" |
+| `pagedPicker`, `holdPickerItems`, `mailPeoplePicker`, `mailComposeDefaults` | `nexus-shared` | A dropdown over a server's search, paged, that names every value it holds (seen, handed over, looked up, or found in the first pages): people to send to; a new message's defaults for a CRUD's `form.createDefaults` |
 | `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) |
@@ -374,8 +381,9 @@ definePopupRules({
   backdrop, or code asked; the page decides by setting `open`. `closable`, `closeOnEscape`, `closeOnBackdrop` turn
   those off for a popup that must be answered.
 - `size`: `xs` 360, `sm` 440, `md` 560, `lg` 720, `xl` 960, `full`. The body scrolls while the title and footer
-  stay; `flush` removes the body padding for tables. `initialFocus` picks the first focused element (default: the
-  first control in the body or footer). The content mounts only while open, so forms start fresh.
+  stay; `flush` removes the body padding for tables. `initialFocus` picks the first focused element (default: an
+  element of the body or footer marked `data-nx-focus` - a mail thread marks its subject, so a long read opens at its
+  top - else the first control there). The content mounts only while open, so forms start fresh.
 - Popups open other popups and message boxes above themselves; Esc closes the top one.
 - A **title bar** like a desktop window's: 32px high (40px on touch screens), the icon, the title, and the description
   on one line (cut with …), and the window buttons filling its top right corner, 46 x 32 each: **minimize** (only when it asks),
@@ -450,6 +458,9 @@ const choice = await messageBox.show({ title: "Unsaved changes", tone: "warning"
   scrolls with the body while the buttons stay: `details: <CrudDetails row={order} columns={ORDER_COLUMNS} />` with a
   `size` of `lg` or `xl`. `closeOnBackdrop: false` keeps a box with much to read open through a stray click (Esc and ×
   still dismiss it, and the focus stays where it was); `signal` dismisses it when the page or form that asked goes.
+- The message and the details describe the box to a screen reader (`aria-describedby`), so they are read with the
+  title as the focus enters. A held Enter, or one within 300 ms of the Enter before it (the one that opened the box,
+  pressed twice), never answers a box; the next deliberate Enter does.
 
 ### Button hover tones
 
@@ -776,6 +787,9 @@ import { MarkdownEditor } from "nexus-shared/client";
   (Ctrl+Shift+.), code (Ctrl+E), code block, link (Ctrl+K), image, bulleted, numbered, and task lists (Ctrl+Shift+8,
   7, L), table, and horizontal line. Marks wrap the selection or the word at the caret and come off when applied
   again. Edits go through the browser's own editing, so Ctrl+Z undoes them. `toolbar` picks and orders the buttons.
+  Under 560 px they take a row of their own; `toolbarOverflow="menu"` keeps one row at any width instead, the buttons
+  that do not fit in a "More formatting" menu at its end (`fitToolbar` works out which) - a chat's reply box does, so a
+  phone keeps its room for the lines.
 - **While typing:** Enter continues a list (the next number, an empty task box) and ends it on an empty item; a URL
   pasted over selected text links it; a task ticked in the preview is ticked in the text.
 - **Height handle:** the status bar under the editor drags the height between `minHeight` and `maxHeight`, showing
@@ -959,7 +973,10 @@ const ROOM_INPUTS: InputParams[] = [
   change; a form reset after a save opens on the new choice. No `viewer`, nothing kept.
   `{ type: EInputTypes.RadioGroup, name: "paidBy", ..., remember: { key: "counter-paid-by", viewer: `${userId}|${companyId}`, preferred: settings.defaultPaymentMode } }`.
   - **A picker** (`...crudPicker(...)`, options from `loadOptions`) confirms a kept value by its key before it opens -
-    found, not inactive, inside its `narrowedBy` narrowing - with its spinner meanwhile; never over the person's own pick.
+    found, not inactive, inside its `narrowedBy` narrowing - with its spinner meanwhile (the box `aria-busy`, described
+    "Loading"; a person in the box keeps the focus when the value opens); never over the person's own pick. A picker
+    that cannot name a record by its key is looked through page by page in its own `pageSize`: a value not met in 20
+    pages, on a list that goes on, is kept for later but not opened - only the list's end makes it gone.
   - **`per: "subscriptionGroupId"`** keeps one value per value of that input (`nx-input:{key}-{group}:{viewer}`): a
     package per group. **`when: { name: "id", filled: false }`** remembers on a CRUD's Add only (Edit holds the key).
   - **In rows** (a tabular or group form): a new row's input opens on the kept value (give its first choice as the
@@ -968,8 +985,9 @@ const ROOM_INPUTS: InputParams[] = [
   checks, a question with what will be saved in full - `{ title: "Place this order?", message, details: (values, body) =>
   ({ row: body, columns, currency }), confirmLabel: "Place order", size: "xl", when }`. `body` is what is sent: an
   ApiForm's `transform` runs once, before the question, and that very body is sent after Confirm. The details are drawn
-  as a record's (`CrudDetails`), a section under a heading for each run of columns with one `group`. Confirm has the
-  focus, so Enter saves; Back to the form, Esc and × send nothing and leave the form as it was, the focus back where it
+  as a record's (`CrudDetails`), a section under a heading for each run of columns with one `group`, and are read out
+  with the title. Confirm has the focus, so a deliberate Enter saves (the Enter that asked, held or pressed twice,
+  does not); Back to the form, Esc and × send nothing and leave the form as it was, the focus back where it
   was; a click outside leaves it open. While it asks nothing else submits and nothing says "Saving…"; a throw while it
   is prepared shows under the form and asks nothing. `when` limits it to some saves.
 - **One save at a time.** Save waits with a spinner; another click, Enter, or Ctrl+S does nothing until it ends. A save
@@ -1054,6 +1072,8 @@ export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: r
   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.
+  `Inventory` (`API_INVENTORY`) was added at bit 17 in 4.0.0, after `Portfolio`, and moved nothing: a new module takes
+  the next bit at the end.
 - **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
@@ -1176,7 +1196,8 @@ table.upsert(saved); table.patch(7, { paid: true }, { flash: true }); table.remo
   `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.
+  the column's width. `table` (sub-columns) marks a list of rows: a record's details draw it as a small table across the line
+  (numbered rows, an option's tone as its tag, a yes or no in words, "None" for an empty list), the table its count.
 - **Money in the company's currency.** `<DataTable currency="Rs." />` (a `Crud`'s `table.currency`) writes every
   `money` column "Rs. 1,250.00" - in the cells, the details, the CSV and the print - with no `render` of the page's; a
   column's own `currency` (a text, or `row => row.currencyText`) wins. `formatMoney(value, { currency, locale })` writes
@@ -1300,7 +1321,9 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
   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.
 - **A save is never read back** (Nexus: an Add is one Create, an Edit one Update). The row is what was sent under what the
-  answer said, with the fields only the server keeps written by `CrudBackend.savedRow` (Nexus: Active, no marks, added
+  answer said (`crudSavedRecord`): the body `transform` made over the form's values, so a field sent as null is empty on
+  the row; and a value `showWhen` hid at the save shows only as the answer (a record) or else the body gives it, never
+  the hidden box's own copy. The fields only the server keeps are written by `CrudBackend.savedRow` (Nexus: Active, no marks, added
   now; an edit keeps them and was changed now), and the names the database joins written again by `crudJoinedNames` for
   each `crudColumns.dbJoin` column given `from` (the key's field): from the record the user picked in the form, one the
   page holds (`peekOption`), or the name the row had when the key did not change. An edit takes the status, the marks
@@ -1315,8 +1338,13 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
   button, Esc, the dock) asks "Discard your changes?". Edit opens with the row, the `details` endpoint's record
   (`form.load: "details"`, for fields a list leaves out), or a loader of your own.
 - **Details** (View, or a double-click) shows every column, hidden ones too, and the full record once `details` answers,
-  with Edit in its footer. Columns that name a `group` (a table's band) are drawn in sections, a small muted heading
-  over each run of them (`CrudDetails`, `crudDetailsRuns`); with no group anywhere the list is one grid, as before.
+  with Edit in its footer. Each field is a label and its value in a box, two pairs to a line where the details are
+  wide and one where they are not. Columns that name a `group` (a table's band) are drawn in sections under a numbered
+  heading, "01. Contact", "02. Account" (`CrudDetails`, `crudDetailsRuns`); with no group anywhere the list is one
+  grid. In a workspace (below) this footer is the Details tab's alone: every other tab runs to the popup's foot. A
+  section may change on its own: `details.sections: [{ group: "KYC details", edit: "edit" }, { group: "Contacts", edit:
+  "contacts" }]` (the Edit form, or a `rowForms` id) puts an Edit at the end of its heading; once saved the record is
+  read again and the focus comes back to the button.
 - **A record's workspace** (`details.profile`, `details.tabs`, `details.remember`): View, and a click on a row under
   `table.openOnClick`, open the record as a wide popup (`full` unless `size` says otherwise) - who it is and its tabs in
   a 20rem column on the left, the chosen tab on the right, scrolling inside itself. A page passes it in a few lines:
@@ -1345,8 +1373,9 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
     the chosen tab is drawn, and a switch never changes the popup's size.
   - `profile.fields` puts a few of the record's fields under the tags, a label and a value each, drawn as the table
     draws them (the person's date format, an option's tone, the column's `tag` after the value). A field is a column
-    given whole or a key of the details' `columns`; one with no value for the record is left out. The Details tab leaves
-    out every key named there, so no field shows twice. Beside the tabs they are a small grid in the 20rem column; on a
+    given whole or a key of the details' `columns`; one with no value for the record is left out. A field the list's
+    row does not carry keeps its line while the record is read (held) and says "Not loaded" if that read fails; it is
+    left out only once read and empty. The Details tab leaves out every key named there, so no field shows twice. Beside the tabs they are a small grid in the 20rem column; on a
     phone they follow the tags as one wrapped line.
 
     ```tsx
@@ -1409,6 +1438,12 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
   once and searched in the browser, and a saved value it does not offer looked up by key through `findListing`. A
   `valueKey` other than `id` - a person's account rather than their row's key - is looked up through `find`, an endpoint
   of its own that takes those values. Without it such a value is never looked up, since `findListing` takes keys.
+  **`list`** reads another listing in place of `activeListing` - a controller with none, such as a pay run's CRUD
+  endpoints (`crudPicker(PAY_RUNS, { list: PAY_RUNS.lists.normal, ... })`; with no `findListing`, nothing is looked
+  up) - **`usable`** says which records count as usable in place of the backend's rule (under 30): `run =>
+  run.recordStatus < NEXUS_TRASH_STATUS` offers a draft run (31); and **`option`** makes each record's option, keeping its
+  fields (`run => ({ ...run, label: run.monthName + " · " + run.runCode, state: STATES[run.payRunState] })`). A CRUD's
+  change on the controller marks the list old, as it does the active one.
 - **A record nobody may change here** (`rowLock={row => row.isLocked ? row.lockReason : null}`): its Edit, Flag, Move to
   trash, Recover and the deletes are listed switched off with that sentence under each, its details have no Edit, the
   handle's `edit` opens its details, and a selection holding it has those mass actions switched off. View, History, Pin
@@ -1456,8 +1491,18 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
   record. `writes` names the answer's fields that change the record (or is a function of the answer): only those, merged
   over the record as the CRUD holds it when the answer lands (an Edit made while the popup was minimized stays), written
   into the table, every list kept and the pinned sections with no list read again. The handle's `openRowForm(id, row)`
-  opens one.
-- **Options narrowed by another input** (`narrowedBy: { name: "subscriptionGroupId" }` on an input, Form only): a
+  opens one. **`confirm`** asks before the save, as a form's `confirm` does - the details in full, Confirm focused, read
+  out, a hasty Enter held - its params or a function of the record and what was read (`confirm: run => ({ title:
+  "Lock " + run.runCode + "?", details: () => ({ row: run, columns: TOTALS }) })`). **A row form with no `inputs` is its
+  question alone** (a pay run's Lock): no popup, the question (`confirm`, else "{label} {name}?", buttons the action's
+  word and "Cancel"), then the record as the list has it - or what `load` read - sent through `transform`; the API's
+  toasts say it was done or why not, and a refusal writes nothing.
+- **A record's history** (`api.audit`, so every row offers History; or `AuditHistory`/`openAuditHistory` on a page):
+  each entry says what was done, when and by whom - "by Sita Rai" when the answer carries `creatorName`, else the start
+  of the person's token ("User 3fA9b2…"), which still tells two people apart - and the columns it changed. An app whose
+  backend sends no names sets `setAuditActorNames(async (tokens, signal) => ({ [token]: "Sita Rai (sita.rai)" }))` once:
+  the history asks it once per page shown, for the tokens it has not had an answer for, and keeps the answers.
+- **Options narrowed by another input** (`narrowedBy: { name: "subscriptionGroupId" }` on an input, in a Form and its rows): a
   Package list only of the Group picked. Static `options` are filtered by the records' `key` field (default the other
   input's name); `loadOptions` is asked with `request.narrow`, which `crudPicker` answers from its kept list, or from
   the server with `crudPicker(PACKAGES, { labelKey, narrowQuery: "subscriptionGroupId" })`. While the other input is
@@ -1465,6 +1510,12 @@ export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "gues
   **Or by a fixed value** the page knows when the form opens (`narrowedBy: { key: "subscriptionGroupId", value:
   subscriber.subscriptionGroupId }`): nothing is followed or cleared, and a `null` value offers nothing. `orUnset: true`
   (both forms) also offers the options whose field is empty: the Fee list of the group, and the fees of every group.
+  **Several at once, and in rows**: `narrowedBy: [{ name: "storeId", from: "form" }, { name: "itemId" }]` on a line
+  table's Tags offers the units of the line's Item in the form's Store - the first empty one asked for, a loader told
+  every value (`request.narrows`), and `crudPicker({}, { list: UNITS, valueKey: "tagNumber", labelKey: "tagNumber" })`
+  over `StockBalance/Units/{storeId}/{itemId}` reads each pair once, the values in its path. A person's new Item clears
+  that line's tags, a new Store every line's; a saved document loading keeps them. `dependsOn: ["quantity"]` on a row
+  input redraws its row as the quantity changes, so `cellParams` can cap the picks (`{ max: row.quantity }`).
 - **Cache.** Lists are kept for 5 minutes while the page is open (`cache={{ lifetime }}`, or `false`): going back to a
   list paints it at once. After a change, the list in view keeps its rows and the others load again when shown; Reload
   and the handle's `reload()` go past the cache. The cache goes when the page does.
@@ -1596,7 +1647,7 @@ owner's `module`, the `category`, the `ownerId`, and for a picture its `aspect`,
 |---|---|---|
 | `EInputTypes.Picture` (`PictureInput`) | `nexus-shared` / `/client` | In a form: the owner's main picture, Upload, Edit, Remove, All pictures (a click on the picture opens them too); in a category that keeps one file, Replace and Delete. Changed at once: the form keeps no field for it (`holdsValue`), so a save sends nothing under its name, and it takes no `required`. `ownerId` null: "Save the record first". |
 | `PictureGallery`, `openPictureGallery` | `nexus-shared/client` | An owner's pictures in two panes: the main picture large with Upload and Remove and the count, then a grid of rounded squares, each with View, Make main, Edit and Delete inside it (on hover, on a keyboard's focus, always by touch; neither Make main nor Delete on the main one). Upload several, up to the category's count; edits are saved as new pictures. Under 560px the main picture sits small over the grid |
-| `DocumentList` | `nexus-shared/client` | The same as a list, for a category that takes PDF (the gallery picks it itself): kind, size, date, open, rename, delete |
+| `DocumentList` | `nexus-shared/client` | The same as a list, for a category that takes PDF (the gallery picks it itself): kind, size, date, open, rename, delete; `changes` for a record whose files are only added to |
 | `pictureColumn` | `nexus-shared/client` | A table column with each row's picture: the page's rows in one call (`primaryPictures`), a click opens the row's gallery |
 | `OwnerPicture`, `usePrimaryPicture`, `useOwnerFiles` | `nexus-shared/client` | The small picture, the kept main picture, and the files with every change, for a page's own layout |
 | `loadImageEditor`, `preloadImageEditor` | `nexus-shared/client` | The image editor, downloaded from the file backend the first time it is needed; never in the bundle |
@@ -1642,6 +1693,12 @@ columns: [pictureColumn({ ...LOGO, rowTitle: row => row.companyName }), ...];
 - **Read only, and why.** `lockReason: "The branch is closed."` makes the files read only with that sentence under
   them; a person the backend lets only look is told the backend's words (`OwnerFiles.readOnlyReason`), and the files
   of an owner not in use (trashed, ended) say so (`OWNER_NOT_IN_USE_REASON`).
+- **Only some changes.** `changes: receipt.isPosted ? ["add"] : undefined` with `changesReason: "Posted: a document can
+  be added; none is removed."` keeps Upload and offers no Rename, Delete, Make main or Remove (nor a Replace or an Edit
+  that deletes or marks) for a record whose files may only be added to; the reason is said under the files. The changes
+  are `FileChange` words, the core's `EFileChanges` one for one. A refusal that says so - the Nexus `API_X084`, read by
+  `FileAdapter.changesLeft` - narrows them the same way for that owner under the server's words, so a page read before
+  the record was posted stops offering what the server refuses. `ownerFileActions` is the rule, for a page's own buttons.
 - **Initials.** `pictureColumn({ ..., nameKey: "fullname" })` (or `OwnerPicture name`) shows an owner with no picture
   as the name's initials, on the shared `Avatar`'s tone for that name.
 - **The keyboard's focus stays.** While a change saves, the buttons stay focusable (`aria-disabled`, the press ignored:
@@ -1703,3 +1760,152 @@ follows, the hero too, with nothing read again).
 - **States** are the piece's: the cards held as they will be while they load, a failed read in each of its cards with
   Try again, `readOnly` with no button anywhere, and `signedOut` - an answer that ended the session closes the popups
   and leaves the page's words and its way back in.
+
+### Mail thread
+
+Mail inside the app: a **thread** with a subject, a sender and the people it went to (To, Cc, Bcc), whose first line is
+the mail and the rest are replies, drawn by the chat's own thread and reply box. A thread can be about a record (a
+leave request), and an app can write into it when something happens - a **notification**, drawn as a quiet event line
+among the replies. Everything comes through one interface, `MessageSource`, so a page passes params and the package
+does the rest.
+
+```tsx
+const mail = apiMessageSource(); // the app's MessageBackend: Nexus's Message module, Mail controller, by default
+const people = mailPeoplePicker(mail); // To, Cc and Bcc boxes that page the server and name what they hold
+
+<Crud<MailInboxRow>
+  api={{ pages: { normal: INBOX }, create: MAIL_CREATE }}
+  paging="server"
+  actions={["create", "view"]}
+  columns={mailInboxColumnList()}
+  inputs={[
+    { type: EInputTypes.Dropdown, name: "to", label: "To", multiple: true, required: true, ...people },
+    { type: EInputTypes.Dropdown, name: "cc", label: "Cc", multiple: true, ...people },
+    { type: EInputTypes.Dropdown, name: "bcc", label: "Bcc", multiple: true, ...people },
+    { type: EInputTypes.Text, name: "subject", label: "Subject", required: true, maxLength: 100 },
+    { type: EInputTypes.Markdown, name: "body", label: "Message", required: true, maxLength: 4000 },
+  ]}
+  form={{ newValues: () => ({ clientId: newMailClientId() }), createDefaults: mailComposeDefaults(mail, people) }}
+  details={{ size: "xl", render: row => <MailThread source={mail} threadId={row.id} userId={me.id} /> }}
+  table={{ rowStrong: mailRowUnread, openOnClick: true }}
+/>
+```
+
+- **The head** is a band at the top of the thread, scrolling with its lines (`ChatThread` `lead`), never in a box of
+  its own; the thread opens at its top. It holds the subject, the time, From, To and Cc, and Bcc **only as the source gives
+  it** (the sender sees every person copied unseen; a person copied unseen sees their own row; nobody else sees any).
+  Lists of people fold to three names and "+2", a button that opens the rest in place. A record the thread is about
+  is drawn as its card ([below](#a-records-card-in-a-message)) when its kind has one, read again when a notification
+  arrives, and folded to its title and figures while the thread is narrower than 480px (its real width, followed as
+  it changes, until the reader folds or unfolds it); otherwise as its kind (named by `defineChatDomains`) and its words.
+  `renderDomain` draws it instead.
+- **The lines** are a `ChatStore` on `source.threadSource(id)`: paging up, a reply on screen at once, Retry, read marks
+  (reading to the bottom marks the thread read; `onSummary` hands the page the new counts), polling.
+  `ChatMessage.kind` says what a line is: `chat`, `mail`, or `notification` (an event line with who acted, no bubble).
+- **A person copied unseen** reads "You were sent a blind copy. Replying shows you to everyone." over the reply box
+  (`mailBccNote`), and the reply box is described by it; once they reply the head is read again and shows them as a Cc.
+- **When someone else writes**, the head is read again (the people may have changed) and `onChanged` tells the page;
+  `reason: "notification"` means the record may have changed, and the record's slot is told too (`revision`).
+- **States**: the head held by bones while it loads, a failure with Try again in the head and in the thread, "This
+  message is not available to you." for a thread the reader is not on (403 or 404), a closed thread that is read and not
+  answered (`canSend: false`).
+- **`MessageBackend`** maps each action to an endpoint and reads each answer; `NexusMessageBackend` is the Message
+  module's `Mail` controller (POST `Inbox`, `History`, `Create`, `Reply`, `People`; GET `Thread/{id}`, `Unread`,
+  `Defaults`; PUT `Read`, `Archive`, `Unarchive`), reading a role (1 From, 2 To, 3 Cc, 4 Bcc) and a line's type (0 chat,
+  1 mail, 2 notification) as this package's words. Override `module` or any reader for another backend.
+- **`localMessageSource({ userId, people, threads })`** keeps a mailbox in memory with a backend's rules - who sees
+  whom, a blind copy's reply, archive and unread per person, a retried send written once - for a demo or a test;
+  `as(userId)` reads it as somebody else and `post` writes a module's notification.
+- **Three params any page can use**: `pagedPicker` (a dropdown over any server search, naming the values it holds),
+  `Crud` `form.createDefaults` (an Add form's values read as it opens; a failed read opens it on `newValues`), and
+  `DataTable` `rowStrong` (a row read strong while a field says so).
+
+### A record's card in a message
+
+A message about a record - a leave request, a requisition - shows that record as a **card**, read live from the module
+that owns it each time it is drawn, never a copy kept in the message. The package knows no module and no record kind:
+an app gives each kind it names with `defineChatDomains` a `card` - how to read the record and what to show of it - and
+every thread about that kind draws it at its head. Every kind looks alike, because a card is params.
+
+```tsx
+defineChatDomains([
+  {
+    domain: EDomainTypes.LeaveRequest,
+    key: "leave-request",
+    label: "Leave request",
+    card: domainCard({
+      // The owning module's card door, which checks the reader. 403 and 404 read "You cannot open this leave request."
+      load: (id, signal) => api.get<LeaveRequestCard>(REQUEST_CARD.leave, { params: { id }, signal, toast: false }).then(unwrapApiResult),
+      // `view` is typed by what `load` answers.
+      view: leave => ({
+        title: `${leave.leaveTypeName} · ${formatDays(leave.days)}`,
+        code: leave.requestCode,
+        state: { label: "In approval", tone: "info" },
+        fields: [
+          { label: "From", value: leave.startDate, kind: "date" },
+          { label: "To", value: leave.endDate, kind: "date", note: "half day" },
+        ],
+        figures: [
+          { label: "Available", value: leave.balance.availableDays, kind: "days" },
+          { label: "Held", value: leave.balance.heldDays, kind: "days", tone: "warning" },
+        ],
+        link: { href: "/admin/requisition/my-approvals", label: "Open My approvals" },
+      }),
+      held: { subtitle: true, fields: 2, figures: 2 }, // what its placeholder holds the first time
+    }),
+  },
+]);
+
+<DomainCard domain={EDomainTypes.LeaveRequest} id={token} label="LR2082-0007 · Puja Shrestha" viewer={me.id} />
+```
+
+- **The card** (`DomainCardParams`): the kind as a tag and the title; a quiet line under it with the code, a subtitle and
+  the link at its end; the state as a tag in its tone; figures first (large values in a row, two to a row on a phone,
+  a tone mark beside each, a hint under one keeping two lines); then its details: fields (a label over each value, as
+  many to a row as fit) and lines (a short table, numbers and
+  money at the end, the first column one line cut with "..."; "and 3 more"). Values are written by their kind with the
+  reader's settings: `date`, `datetime` (their zone), `days` (`formatDays`: "1 day", "2.5 days"), `money` (the card's
+  `currency`, `formatMoney`), `number`, `person`, `text`. A field with no value is left out unless it names `empty`.
+  `extra(data)` adds one more piece of this package's parts after the lines. A band, never a box: a mail thread's head
+  draws a line above it.
+  The fold button folds the details and keeps the figures (folded, a leave's card is its title, code and balance);
+  `collapsed` with `onCollapsedChange` lets a page hold the fold, `defaultCollapsed` starts it.
+- **Every state**: a placeholder of the card's own parts, in the shape of the kind's last card (or its `held`), so the
+  record lands without moving what is under it, at any width; the card; "You cannot open this leave request." for 403
+  and 404 alike (a stranger learns nothing from the difference); "Could not load this leave request." with Try again
+  for anything else; the kind and the record's words alone for a kind with no card or a message with no id. `view`
+  throwing on an answer is a failure too, never a broken thread.
+- **Read again**: when `revision` grows (a mail thread's notification), `ref.reload()`, or `refreshDomainCards(kind,
+  id)` (the page changed the record itself). The card stays while it is read, says "Updated 2:45 PM" when the record
+  turned out different, and "Not up to date" with Try again when the read failed; a refusal on a read again drops it.
+  A screen reader is told each.
+- **Reads** (`DomainCardReads`, `domainCardReads`): one read of a record at a time however many cards draw it, an
+  answer kept 30 seconds per reader (`lifetime`), a failure never kept, a read nobody waits for aborted, a read again
+  taking only a read started after the change and forgetting what other readers kept. `useDomainCard` and
+  `DomainCardRun` give a page the same read for a look of its own; `DomainCardFrame` draws a card from params a page
+  already holds, with no read.
+
+### Message bell
+
+How much internal mail waits, on a top bar's button: the count over its corner in the chat's badge (one size whatever
+the count, "99+" from 100 on) and the newest unread threads a click away, each a link into the inbox.
+
+```tsx
+const mail = apiMessageSource(); // one object for the page: every bell on it shares one poller
+
+<AdminLayout
+  utilities={[{ code: "notifications", label: "Messages", icon: "bell" }]}
+  renderUtility={item => (item.code === "notifications" ? <MessageBell source={mail} href="/admin/message/inbox" label={item.label} /> : undefined)}
+/>
+```
+
+- **One read however many bells.** `useMessageUnread(source)` joins the page's poller for that source: it reads when
+  the first bell appears, then every minute while the page is in front, at once when the window takes the focus or the
+  tab comes back, and never while the tab is hidden. A failure keeps the count read before. Call
+  `refreshMessageUnread(source)` after the page reads or archives threads, and every bell on it reads at once - or
+  right after the read on its way, which may have counted before the change (one more read, however many are asked).
+- **The menu**: the newest unread (subject; who wrote last, the record, when), a row opening `href?thread=<id>` (or
+  `threadHref(row)`), "Open inbox", and Try again after a failure. Opening it reads the count again.
+- **A screen reader** hears the button's name ("Messages: 3 unread messages") and, when the count goes up, the new
+  count once from one bell of the page - never on every read, never as the page loads.
+- **`Button` `badge`** is the piece underneath: a count over any button's corner that leaves its size alone.

package/dist/Client.Index.d.ts

@@ -3,15 +3,21 @@ 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/ChatPopup.tsx";
 export * from "./Components/Chats/ChatParts.tsx";
 export * from "./Components/Chats/ChatThread.tsx";
+export * from "./Components/Dashboards/DashboardBoard.tsx";
+export * from "./Components/Dashboards/DashboardWidgets.tsx";
+export * from "./Components/Dashboards/WidgetFrame.tsx";
 export * from "./Components/Documents/DocumentFrame.tsx";
+export * from "./Components/Domains/DomainCard.tsx";
 export * from "./Components/Documents/Menu.tsx";
 export * from "./Components/Documents/SplitButton.tsx";
 export * from "./Components/Documents/TabButtons.tsx";
 export * from "./Components/Documents/Tabs.tsx";
 export * from "./Components/Forms/ApiForm.tsx";
 export * from "./Components/Forms/Crud.tsx";
+export { openCrudForm, type CrudFormRequest } from "./Components/Forms/CrudActions.tsx";
 export * from "./Components/Forms/CrudHistory.tsx";
 export * from "./Components/Forms/CrudNarrowPicker.tsx";
 export * from "./Components/Forms/CrudParts.tsx";
@@ -52,6 +58,12 @@ export * from "./Components/Layouts/PopupRules.ts";
 export * from "./Components/Layouts/ThemePicker.tsx";
 export * from "./Components/Layouts/ThemeSwitcher.tsx";
 export * from "./Components/Layouts/Toaster.tsx";
+export * from "./Components/Messages/MailClient.tsx";
+export * from "./Components/Messages/MailColumns.tsx";
+export * from "./Components/Messages/MailCompose.tsx";
+export * from "./Components/Messages/MailReader.tsx";
+export * from "./Components/Messages/MailThread.tsx";
+export * from "./Components/Messages/MessageBell.tsx";
 export * from "./Components/Viewers/Avatar.tsx";
 export * from "./Components/Viewers/DataTable.tsx";
 export * from "./Components/Viewers/DataTableParts.tsx";
@@ -72,4 +84,5 @@ export * from "./Services/FileApi.ts";
 export * from "./Services/ImageEditorLoader.ts";
 export * from "./Services/ModuleImport.ts";
 export * from "./Services/JoinSources.ts";
+export * from "./Services/MessageApi.ts";
 export * from "./Services/ThemeService.ts";

package/dist/Client.Index.js

@@ -6,15 +6,21 @@ 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/ChatPopup.js";
 export * from "./Components/Chats/ChatParts.js";
 export * from "./Components/Chats/ChatThread.js";
+export * from "./Components/Dashboards/DashboardBoard.js";
+export * from "./Components/Dashboards/DashboardWidgets.js";
+export * from "./Components/Dashboards/WidgetFrame.js";
 export * from "./Components/Documents/DocumentFrame.js";
+export * from "./Components/Domains/DomainCard.js";
 export * from "./Components/Documents/Menu.js";
 export * from "./Components/Documents/SplitButton.js";
 export * from "./Components/Documents/TabButtons.js";
 export * from "./Components/Documents/Tabs.js";
 export * from "./Components/Forms/ApiForm.js";
 export * from "./Components/Forms/Crud.js";
+export { openCrudForm } from "./Components/Forms/CrudActions.js";
 export * from "./Components/Forms/CrudHistory.js";
 export * from "./Components/Forms/CrudNarrowPicker.js";
 export * from "./Components/Forms/CrudParts.js";
@@ -55,6 +61,12 @@ export * from "./Components/Layouts/PopupRules.js";
 export * from "./Components/Layouts/ThemePicker.js";
 export * from "./Components/Layouts/ThemeSwitcher.js";
 export * from "./Components/Layouts/Toaster.js";
+export * from "./Components/Messages/MailClient.js";
+export * from "./Components/Messages/MailColumns.js";
+export * from "./Components/Messages/MailCompose.js";
+export * from "./Components/Messages/MailReader.js";
+export * from "./Components/Messages/MailThread.js";
+export * from "./Components/Messages/MessageBell.js";
 export * from "./Components/Viewers/Avatar.js";
 export * from "./Components/Viewers/DataTable.js";
 export * from "./Components/Viewers/DataTableParts.js";
@@ -77,4 +89,5 @@ export * from "./Services/FileApi.js";
 export * from "./Services/ImageEditorLoader.js";
 export * from "./Services/ModuleImport.js";
 export * from "./Services/JoinSources.js";
+export * from "./Services/MessageApi.js";
 export * from "./Services/ThemeService.js";

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

@@ -1,3 +1,4 @@
+import { type ReactNode } from "react";
 import type { ChatSnapshot, ChatStore } from "../../Helpers/ChatStore.ts";
 import type { ChatMessage, ChatParticipant } from "../../Interfaces/ChatInterfaces.ts";
 import { type MarkdownToolbarItem } from "../Inputs/MarkdownEditor.tsx";
@@ -32,10 +33,15 @@ export interface ChatComposerProps {
     height?: number;
     /** Why the user may not write here. */
     readOnlyMessage?: string;
+    /**
+     * What the writer should know before sending, in a line over the writing area that the writing area is described by:
+     * "You were sent a blind copy. Replying shows you to everyone."
+     */
+    notice?: ReactNode;
     /** Most characters in one message. Default 4,000. */
     maxLength?: number;
     autoFocus?: boolean;
     className?: string;
 }
 /** Writes and sends a message, in Markdown. */
-export declare function ChatComposer({ store, state, draftKey, placeholder, files, replyTo, onCancelReply, sendKey, mentions, mentionHref, toolbar, height, readOnlyMessage, maxLength, autoFocus, className, }: ChatComposerProps): import("react").JSX.Element;
+export declare function ChatComposer({ store, state, draftKey, placeholder, files, replyTo, onCancelReply, sendKey, mentions, mentionHref, toolbar, height, readOnlyMessage, notice, maxLength, autoFocus, className, }: ChatComposerProps): import("react").JSX.Element;

package/dist/Components/Chats/ChatComposer.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { iconPaperclip, iconSend, iconX, InlineIcon } from "nexus-icons";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { iconInfoCircle, iconPaperclip, iconSend, iconX, InlineIcon } from "nexus-icons";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
 import { applyChatMention, chatFileSize, findChatMention, matchChatMentions, readChatMentions } from "../../Helpers/ChatHelpers.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { continueMarkdownList } from "../../Helpers/MarkdownEditing.js";
@@ -54,8 +54,9 @@ function insideCodeFence(value, caret) {
     return (before.match(/^```/gm) ?? []).length % 2 === 1;
 }
 /** Writes and sends a message, in Markdown. */
-export function ChatComposer({ store, state, draftKey, placeholder = "Write a message…", files = false, replyTo, onCancelReply, sendKey = "enter", mentions, mentionHref, toolbar = CHAT_TOOLBAR, height = 84, readOnlyMessage = "You can read this conversation, but not write in it.", maxLength = 4000, autoFocus = false, className, }) {
+export function ChatComposer({ store, state, draftKey, placeholder = "Write a message…", files = false, replyTo, onCancelReply, sendKey = "enter", mentions, mentionHref, toolbar = CHAT_TOOLBAR, height = 84, readOnlyMessage = "You can read this conversation, but not write in it.", notice, maxLength = 4000, autoFocus = false, className, }) {
     const boxRef = useRef(null);
+    const noticeId = useId();
     const fileRef = useRef(null);
     // The text lives here so Send, the draft, and clearing after a send all read the same thing. A message is short, so
     // a render per keystroke costs nothing — unlike the long documents the editor is otherwise built for.
@@ -169,9 +170,11 @@ export function ChatComposer({ store, state, draftKey, placeholder = "Write a me
         return (_jsx("div", { className: cx("nx-chat-composer nx-chat-composer--readonly", className), children: _jsx("p", { children: readOnlyMessage }) }));
     }
     const empty = text.trim() === "" && picked.length === 0;
-    return (_jsxs("div", { className: cx("nx-chat-composer", className), children: [replyTo && (_jsxs("div", { className: "nx-chat-composer__reply", children: [_jsxs("span", { className: "nx-chat-composer__reply-text", children: [_jsx("span", { className: "nx-chat-composer__reply-author", children: replyTo.authorName || "Unknown" }), _jsx("span", { children: markdownToPlainText(replyTo.body) })] }), _jsx("button", { type: "button", onClick: onCancelReply, "aria-label": "Stop replying", children: _jsx(InlineIcon, { icon: iconX }) })] })), picked.length > 0 && (_jsx("ul", { className: "nx-chat-composer__files", children: picked.map((file, index) => (_jsxs("li", { children: [_jsx("span", { className: "nx-chat-composer__file-name", children: file.name }), _jsx("span", { className: "nx-chat-composer__file-size", children: chatFileSize(file.size) }), _jsx("button", { type: "button", onClick: () => setPicked(held => held.filter((_, at) => at !== index)), "aria-label": `Remove ${file.name}`, children: _jsx(InlineIcon, { icon: iconX }) })] }, `${file.name}-${index}`))) })), picking && (_jsx("ul", { className: "nx-chat-mentions", role: "listbox", "aria-label": "People", children: offered.map((person, index) => (_jsx("li", { children: _jsxs("button", { type: "button", className: cx("nx-chat-mentions__item", index === at && "is-at"), role: "option", "aria-selected": index === at, 
+    return (_jsxs("div", { className: cx("nx-chat-composer", className), children: [notice && (_jsxs("p", { className: "nx-chat-composer__notice", id: noticeId, children: [_jsx(InlineIcon, { icon: iconInfoCircle }), _jsx("span", { children: notice })] })), replyTo && (_jsxs("div", { className: "nx-chat-composer__reply", children: [_jsxs("span", { className: "nx-chat-composer__reply-text", children: [_jsx("span", { className: "nx-chat-composer__reply-author", children: replyTo.authorName || "Unknown" }), _jsx("span", { children: markdownToPlainText(replyTo.body) })] }), _jsx("button", { type: "button", onClick: onCancelReply, "aria-label": "Stop replying", children: _jsx(InlineIcon, { icon: iconX }) })] })), picked.length > 0 && (_jsx("ul", { className: "nx-chat-composer__files", children: picked.map((file, index) => (_jsxs("li", { children: [_jsx("span", { className: "nx-chat-composer__file-name", children: file.name }), _jsx("span", { className: "nx-chat-composer__file-size", children: chatFileSize(file.size) }), _jsx("button", { type: "button", onClick: () => setPicked(held => held.filter((_, at) => at !== index)), "aria-label": `Remove ${file.name}`, children: _jsx(InlineIcon, { icon: iconX }) })] }, `${file.name}-${index}`))) })), picking && (_jsx("ul", { className: "nx-chat-mentions", role: "listbox", "aria-label": "People", children: offered.map((person, index) => (_jsx("li", { children: _jsxs("button", { type: "button", className: cx("nx-chat-mentions__item", index === at && "is-at"), role: "option", "aria-selected": index === at, 
                         // The editor must not lose the caret before the name goes in.
-                        onMouseDown: event => event.preventDefault(), onMouseEnter: () => setAt(index), onClick: () => putMention(person), children: [_jsx(ChatAvatar, { name: person.name, src: person.avatar, size: "sm" }), _jsx("span", { className: "nx-chat-mentions__name", children: person.name }), person.role && _jsx("span", { className: "nx-chat-mentions__role", children: person.role })] }) }, String(person.id)))) })), _jsx(MarkdownEditor, { ref: boxRef, className: "nx-chat-composer__editor", "aria-label": "Message", placeholder: placeholder, value: text, onValueChange: change, onKeyDown: keyDown, 
+                        onMouseDown: event => event.preventDefault(), onMouseEnter: () => setAt(index), onClick: () => putMention(person), children: [_jsx(ChatAvatar, { name: person.name, src: person.avatar, size: "sm" }), _jsx("span", { className: "nx-chat-mentions__name", children: person.name }), person.role && _jsx("span", { className: "nx-chat-mentions__role", children: person.role })] }) }, String(person.id)))) })), _jsx(MarkdownEditor, { ref: boxRef, className: "nx-chat-composer__editor", "aria-label": "Message", "aria-describedby": notice ? noticeId : undefined, placeholder: placeholder, value: text, onValueChange: change, onKeyDown: keyDown, 
                 // Moving the caret away from an `@…` closes the list, as clicking elsewhere in the text does.
-                onSelect: () => setMention(mentions ? findChatMention(boxRef.current?.value ?? "", boxRef.current?.selectionStart ?? 0) : null), onBlur: () => setMention(null), modes: ["write", "preview"], toolbar: toolbar, height: height, minHeight: 72, maxHeight: 360, heightKey: "nx-chat", showCount: false, maxLength: maxLength }), _jsxs("div", { className: "nx-chat-composer__row", children: [_jsx("span", { className: "nx-chat-composer__hint", children: sendKey === "enter" ? "Enter sends · Shift+Enter for a line" : "Ctrl+Enter sends" }), files && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "nx-chat-composer__attach", onClick: () => fileRef.current?.click(), "aria-label": "Attach a file", title: "Attach a file", children: _jsx(InlineIcon, { icon: iconPaperclip }) }), _jsx("input", { ref: fileRef, type: "file", multiple: true, hidden: true, onChange: addFiles })] })), _jsxs("button", { type: "button", className: "nx-chat-composer__send", onClick: send, disabled: empty, "aria-label": "Send", title: sendKey === "enter" ? "Send (Enter)" : "Send (Ctrl+Enter)", children: [_jsx(InlineIcon, { icon: iconSend }), _jsx("span", { children: "Send" })] })] })] }));
+                onSelect: () => setMention(mentions ? findChatMention(boxRef.current?.value ?? "", boxRef.current?.selectionStart ?? 0) : null), onBlur: () => setMention(null), modes: ["write", "preview"], toolbar: toolbar, 
+                // One row on a phone too: the buttons that do not fit go into a menu, so the thread above keeps its room.
+                toolbarOverflow: "menu", height: height, minHeight: 72, maxHeight: 360, heightKey: "nx-chat", showCount: false, maxLength: maxLength }), _jsxs("div", { className: "nx-chat-composer__row", children: [_jsx("span", { className: "nx-chat-composer__hint", children: sendKey === "enter" ? "Enter sends · Shift+Enter for a line" : "Ctrl+Enter sends" }), files && (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "nx-chat-composer__attach", onClick: () => fileRef.current?.click(), "aria-label": "Attach a file", title: "Attach a file", children: _jsx(InlineIcon, { icon: iconPaperclip }) }), _jsx("input", { ref: fileRef, type: "file", multiple: true, hidden: true, onChange: addFiles })] })), _jsxs("button", { type: "button", className: "nx-chat-composer__send", onClick: send, disabled: empty, "aria-label": "Send", title: sendKey === "enter" ? "Send (Enter)" : "Send (Ctrl+Enter)", children: [_jsx(InlineIcon, { icon: iconSend }), _jsx("span", { children: "Send" })] })] })] }));
 }

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

@@ -40,6 +40,15 @@ export declare function ChatSystemNote({ message, time }: {
     message: ChatMessage;
     time: ChatTimeOptions;
 }): import("react").JSX.Element;
+/**
+ * A notification (`kind: "notification"`): what an app wrote about an event, under the name of the person who acted -
+ * "Approved at Supervisor. Now with Accounts." It is a quiet line across the thread, not a bubble on a side: the bell,
+ * who acted and when, and the words under them, so a thread of replies reads around its events.
+ */
+export declare function ChatEventNote({ message, time }: {
+    message: ChatMessage;
+    time: ChatTimeOptions;
+}): import("react").JSX.Element;
 export interface ChatMessageProps {
     message: ChatMessage;
     /** This user wrote it: it sits on the right. */
@@ -76,10 +85,14 @@ export declare function ChatEmpty({ message, hint }: {
     message?: string;
     hint?: ReactNode;
 }): import("react").JSX.Element;
-/** Something that did not load, with a way to try again. */
-export declare function ChatFailure({ message, onRetry }: {
+/**
+ * Something that did not load, with a way to try again. `flat`: its tint without an edge, for a failure that already
+ * sits in a framed panel (a dashboard widget).
+ */
+export declare function ChatFailure({ message, onRetry, flat }: {
     message: string;
     onRetry?: () => void;
+    flat?: boolean;
 }): import("react").JSX.Element;
 /** Messages on their way in. */
 export declare function ChatLoading({ label }: {

package/dist/Components/Chats/ChatParts.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { iconAlertCircle, iconCheck, iconChecks, iconCornerUpLeft, iconFile, iconLoader2, iconRefresh, iconTrash, iconX, InlineIcon } from "nexus-icons";
+import { iconAlertCircle, iconBell, iconCheck, iconChecks, iconCornerUpLeft, iconFile, iconLoader2, iconRefresh, iconTrash, iconX, InlineIcon } from "nexus-icons";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { chatDeliveryState, chatFileSize, chatTimeLabel, sameChatId, CHAT_DELIVERY_LABELS } from "../../Helpers/ChatHelpers.js";
 import { markdownToPlainText } from "../../Helpers/MarkdownHelpers.js";
@@ -57,6 +57,14 @@ export function ChatQuote({ message, onOpen }) {
 export function ChatSystemNote({ message, time }) {
     return (_jsxs("div", { className: "nx-chat-note", children: [_jsx("span", { children: markdownToPlainText(message.body) }), _jsx("time", { dateTime: message.createdAt, children: chatTimeLabel(message.createdAt, time) })] }));
 }
+/**
+ * A notification (`kind: "notification"`): what an app wrote about an event, under the name of the person who acted -
+ * "Approved at Supervisor. Now with Accounts." It is a quiet line across the thread, not a bubble on a side: the bell,
+ * who acted and when, and the words under them, so a thread of replies reads around its events.
+ */
+export function ChatEventNote({ message, time }) {
+    return (_jsxs("div", { className: "nx-chat-event", children: [_jsx(InlineIcon, { icon: iconBell, className: "nx-chat-event__icon" }), _jsxs("div", { className: "nx-chat-event__text", children: [_jsxs("span", { className: "nx-chat-event__meta", children: [_jsx("span", { className: "nx-chat-event__author", children: message.authorName || "Unknown" }), _jsx("time", { dateTime: message.createdAt, children: chatTimeLabel(message.createdAt, time) })] }), message.body && _jsx(MarkdownView, { className: "nx-chat-event__body", value: message.body })] })] }));
+}
 /**
  * One message. Its own messages sit on the right in the primary tint, everyone else's on the left on a surface. The
  * actions are one row of icon buttons that appear on hover or keyboard focus — and never move the message, so a long
@@ -86,9 +94,12 @@ export function ChatParticipantList({ participants, userId, empty = "Nobody else
 export function ChatEmpty({ message = "No messages yet.", hint }) {
     return (_jsxs("div", { className: "nx-chat-empty", children: [_jsx("p", { children: message }), hint && _jsx("p", { className: "nx-chat-empty__hint", children: hint })] }));
 }
-/** Something that did not load, with a way to try again. */
-export function ChatFailure({ message, onRetry }) {
-    return (_jsxs("div", { className: "nx-chat-failure", role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: message }), onRetry && (_jsxs("button", { type: "button", onClick: onRetry, children: [_jsx(InlineIcon, { icon: iconRefresh }), " Try again"] }))] }));
+/**
+ * Something that did not load, with a way to try again. `flat`: its tint without an edge, for a failure that already
+ * sits in a framed panel (a dashboard widget).
+ */
+export function ChatFailure({ message, onRetry, flat = false }) {
+    return (_jsxs("div", { className: flat ? "nx-chat-failure nx-chat-failure--flat" : "nx-chat-failure", role: "alert", children: [_jsx(InlineIcon, { icon: iconAlertCircle }), _jsx("span", { children: message }), onRetry && (_jsxs("button", { type: "button", onClick: onRetry, children: [_jsx(InlineIcon, { icon: iconRefresh }), " Try again"] }))] }));
 }
 /** Messages on their way in. */
 export function ChatLoading({ label = "Loading…" }) {