nexus-shared 1.1.21 → 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bijay Adhikari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.