nexus-shared 1.1.20 → 2.0.0

package/README.md

@@ -0,0 +1,903 @@
+# nexus-shared
+
+Lightweight React components, helpers, and design tokens for Nexus apps. No runtime dependencies besides
+React and `nexus-icons`.
+
+```
+npm install nexus-shared nexus-icons
+```
+
+```tsx
+// Once, in the root layout
+import "nexus-shared/styles.css";
+
+import { Button } from "nexus-shared";
+import { InlineIcon, iconPlus } from "nexus-icons";
+
+<Button variant="primary" icon={<InlineIcon icon={iconPlus} />}>New booking</Button>
+```
+
+## Entry points
+
+| Import | Contains |
+|---|---|
+| `nexus-shared` | Components and helpers that work in server and client components |
+| `nexus-shared/client` | Client components and browser services |
+| `nexus-shared/server` | Server-only code |
+| `nexus-shared/styles.css` | Tokens, base styles, and component styles |
+
+## Themes
+
+Seven themes, each with a light and a dark palette that meets WCAG AA contrast:
+**Nexus** (default), **GitHub**, **Nord**, **Dracula**, **Solarized**, **Catppuccin**, and **Rosé Pine**.
+The mode is Light, Dark, or System (follows the operating system).
+
+```tsx
+// app/layout.tsx
+import "nexus-shared/styles.css";
+import { ThemeScript } from "nexus-shared";
+import { ThemeSwitcher } from "nexus-shared/client";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <ThemeScript />
+      </head>
+      <body>
+        <header>… <ThemeSwitcher /></header>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+- `ThemeScript` applies the saved choice before the page paints, so there is no flash of the default theme.
+  Options: `defaultTheme`, `defaultMode`, `themes`, `nonce`. It sets attributes on `<html>`, hence `suppressHydrationWarning`.
+- `ThemeSwitcher` is a palette button with a popover; `ThemePicker` is the same picker placed in a page.
+- `useTheme()` returns `{ theme, mode, resolvedMode, setTheme, setMode }` for custom controls.
+- The choice is saved in `localStorage` (`nx-theme`, `nx-mode`) and shared by open tabs.
+
+Without JavaScript, set the attributes yourself: `<html data-nx-theme="nord" data-nx-mode="dark">`.
+Without `data-nx-mode`, the system setting applies. `data-nx-theme` also works on any element, which then
+draws in that theme (the picker's previews use this).
+
+### How it works
+
+- `Nexus.Themes.css` gives each theme its colors once, as `light-dark(light, dark)`; the page's `color-scheme` picks the side.
+- `Nexus.Tokens.css` holds sizes, spacing, and type, and derives hover colors, soft backgrounds, and the focus ring from the palette.
+- Components use only `--nx-*` variables, so every component follows the theme with no extra code.
+- `npm run check:themes` checks every theme in both modes against WCAG contrast. Run it after changing a color.
+
+### Custom themes
+
+A theme is one CSS block. List it for the script and the picker:
+
+```css
+[data-nx-theme="brand"] {
+  --nx-primary: light-dark(#0f766e, #2dd4bf);        /* the accent as text and lines */
+  --nx-primary-solid: light-dark(#0f766e, #0d7a70);  /* the accent as a fill behind white text: buttons, checks */
+  --nx-primary-text: light-dark(#ffffff, #ffffff);
+  /* …any other --nx-* color: bg, surface, surface-2, surface-hover, border, border-strong,
+     text, text-muted, text-subtle, danger, danger-solid, danger-text, success, warning, info */
+}
+```
+
+```tsx
+const themes = [...NEXUS_THEMES, { id: "brand", name: "Brand", description: "Our colors" }];
+<ThemeScript themes={themes} defaultTheme="brand" />
+<ThemeSwitcher themes={themes} />
+```
+
+All styles sit in `@layer nexus.*`, so an app's own CSS overrides any token or component style without `!important`.
+
+## Components
+
+| 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 |
+| `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 |
+| `Popup` | `nexus-shared/client` | A modal window on the native dialog, with the buttons of a desktop window: minimize (a bar at the bottom right, content kept), maximize, close; moved by its title bar inside the window; title, description, scrolling body, footer, sizes `xs` to `full`, close reasons |
+| `PopupHost`, `openPopup` | `nexus-shared/client` | Popups opened from code with a handle (`close`, `update`, `minimize`, `maximize`, `restore`, `windowState`, `closed`), one per `key` (replaced or restored); one `<PopupHost />` in the layout, which also shows the minimized popups |
+| `definePopupRules` | `nexus-shared/client` | Rules for popups by key or `prefix-*` pattern, set once: `reopen` (replace or restore), `minimizable`, `maximizable`, `movable`, how it closes, `size`, `defaultWindowState` |
+| `useDraggable`, `makeDraggable`, `startDrag`, `moveWithin`, `clampToBounds` | `nexus-shared/client` | Move any element with the pointer (or the keyboard), kept inside bounds: the window, the parent, an element, or a box; by a handle, along one axis, partly outside; Esc puts it back |
+| `messageBox` | `nexus-shared/client` | `alert`, `confirm`, `prompt`, and `show` with any buttons, each returning a promise |
+| `TextBox` | `nexus-shared/client` | Text input: label designs `standard`, `outlined`, `inbox`; sizes; icons; `prefix`, `suffix`; `clearable`; show password; `showCount`; validation |
+| `TextArea` | `nexus-shared/client` | Multi-line text with the same field features; `autoResize` between `rows` and `maxRows` |
+| `CheckBox`, `Switch` | `nexus-shared/client` | One checkbox or on/off switch: `label`, `description`, `required` (must be checked), `indeterminate`, `readOnly`, `labelPosition` |
+| `CheckBoxGroup` | `nexus-shared/client` | Many choices from `options`: `min`, `max` (disables the rest at the limit), `selectAll`, `columns`, `design="cards"` |
+| `RadioGroup` | `nexus-shared/client` | One choice from `options`: arrow keys, `orientation`, `columns`, `design="cards"` |
+| `Dropdown` | `nexus-shared/client` | One value, or several with `multiple`, from `options` or server pages (`loadOptions`: search, infinite scroll, loaders, Retry); rows as `columns` like a data table (avatar, image, icon, code); saved values the list no longer offers (`selectedOptions`, `resolveOptions`, inactive items) show and cannot be picked again |
+| `Slider`, `RangeSlider` | `nexus-shared/client` | Pick a number or a range: `min`, `max`, `step`, number format with `prefix`/`suffix`, `marks`, `tooltip`, `minDistance`, `onValueCommit` |
+| `NumberBox` | `nexus-shared/client` | Numbers only: `min`, `max`, `decimals`, `fixedDecimals`, `grouping` by `locale`, `prefix`, `suffix`, `stepper`, `clamp`; the same field shell |
+| `DatePicker` | `nexus-shared/client` | Type or pick a date in the English (AD) or Nepali (BS) calendar from the user's settings; `min`, `max`, `isDateDisabled`; the value is always a Gregorian ISO date |
+| `DateRangePicker` | `nexus-shared/client` | A start and an end in one box, picked in a two-month calendar or typed; `startName` and `endName` send two fields; `minDistance`, `maxDistance` in days; booked nights cannot be included |
+| `TimePicker` | `nexus-shared/client` | Type or pick a time on a 12- or 24-hour clock from the user's settings: columns of hours and minutes or `view="list"` slots; `min`, `max` (past midnight too), `step` in seconds, `isTimeDisabled`; the value is always an ISO time |
+| `DateTimePicker` | `nexus-shared/client` | Type or pick a day and a time: each user sees their own local time in their date and time settings, and the value is always the UTC moment; `timeZone` for a place's zone, `min`, `max`, `minTime`, `maxTime`, `step`, `isDateDisabled`, `isTimeDisabled` |
+| `Calendar` | `nexus-shared/client` | The month grid on its own: single or `mode="range"`, `months={2}` side by side, month and year menus, arrow keys, `renderDay` for event markers, `weekStart` |
+| `useDatePreferences`, `setDatePreferences` | `nexus-shared/client` | The user's calendar, format, script, and time format, saved in local storage and followed by every date and time component |
+| `Form` | `nexus-shared/client` | A list of input params (`InputParams[]`) on a 12-column grid (`span`), with the values in a store outside React; `onFieldChange` for derived values, `validate` for rules across inputs, `draftKey` for unsaved changes that survive a reload, `loading` placeholders |
+| `SubmitForm` | `nexus-shared/client` | A `Form` that checks every value on Save and focuses the first problem, then runs `onSubmit` once at a time; a status line with links to what needs attention; Save, Cancel (asks first), Reset; Ctrl+S |
+| `ApiForm` | `nexus-shared/client` | A `SubmitForm` that sends to an API (an endpoint such as `ROOMS.update`, `{ url, method }`, or the app's own client), loads the record first (`loadValue`), and shows the server's messages on their inputs: Nexus responses and ASP.NET Core problem details |
+| `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` |
+| `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 |
+| `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 |
+| `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 |
+| `apiController`, `apiEndpoint`, `unwrapApiResult` | `nexus-shared` | Endpoints defined once by module: a controller's standard actions (`NormalListing`, `Detail/{id}`, `Create`, `Update`, `Delete/{id}`, each list's `lists.trash` and `pages.trash`, …); an answer's result, or an `ApiError` |
+| `messages`, `buildMessage`, `configureMessages` | `nexus-shared` | Every success, failure, reason, loading, question, and button text from one table: "3 rooms deleted.", "You do not have permission to delete Room 204."; reworded all at once |
+| `createApiClient` | `nexus-shared` | The engine behind `api` and `serverApi`, for an API of another shape |
+| `Field` | `nexus-shared` | The frame of every input (label, box, icons, hint or error), for building custom inputs |
+| `validateText`, `TEXT_PATTERNS` | `nexus-shared` | Pure text validation and common patterns with their messages |
+| `validateCheck`, `validateSelection` | `nexus-shared` | Pure checks for a checkbox and for chosen values (`required`, `min`, `max`) |
+| `validateNumber`, `formatNumber`, `parseNumber` | `nexus-shared` | Pure number validation, and number text in any locale (`roundDecimal`, `stepNumber` too) |
+| `formatDate`, `parseDateText`, `toIsoDate`, `validateDate` | `nexus-shared` | Pure date helpers: ISO dates in and out, either calendar, any format, Devanagari digits; `toCalendar` and `fromCalendar` convert AD and BS |
+| `formatDateRange`, `parseDateRangeText`, `toDateRange`, `validateDateRange` | `nexus-shared` | The same for a range: "2026-09-17 – 2026-09-24" in and out, typed with a dash, an arrow, or "to"; rules on both ends and on the days between |
+| `filterItems`, `matchesSearch`, `indexItems`, `optionKey`, `initials` | `nexus-shared` | Pure helpers behind the dropdown: search every word with or without accents, index items by value, compare ids from APIs and forms, and initials for avatars |
+| `formatTime`, `parseTimeText`, `toIsoTime`, `validateTime` | `nexus-shared` | Pure time helpers: ISO times in and out, 12- or 24-hour formats, Devanagari digits, typed text on either clock; `addMinutes`, `isTimeInRange`, `listTimeSlots` |
+| `toUtcDateTime`, `toLocalDateTime`, `fromLocalDateTime`, `formatDateTime`, `parseDateTimeText`, `validateDateTime` | `nexus-shared` | Pure date-time helpers: UTC values in and out, the date and time a moment shows in any IANA zone (daylight saving included), typed text in both calendars; `describeTimeZone`, `getBrowserTimeZone` |
+| `ThemeScript` | `nexus-shared` | Applies the saved theme before paint; goes in `<head>` |
+| `ThemeSwitcher` | `nexus-shared/client` | Palette button with the theme picker in a popover |
+| `ThemePicker` | `nexus-shared/client` | Mode control and theme cards with live previews |
+
+### Tab buttons
+
+```tsx
+import { TabButtons } from "nexus-shared/client";
+
+<TabButtons
+  aria-label="View"
+  value={view}
+  onChange={setView}
+  options={[
+    { value: "grid", label: "Grid", icon: <InlineIcon icon={iconLayoutGrid} /> },
+    { value: "list", label: "List", icon: <InlineIcon icon={iconList} /> },
+  ]}
+/>
+```
+
+- An indicator slides to the selected option. In light mode the track is a soft tint with no frame and the indicator
+  is lifted by a shadow; in dark mode the indicator is lighter than the track, with a visible edge. The selected icon
+  takes the primary color, so the choice is clear in every theme.
+- `size` (`sm`, `md`, `lg`), `tone="primary"` for a solid primary indicator, `block` to fill the width, `disabled` per option.
+- `labels="selected"`: icons only, and the selected option grows to show its label. Every option needs an icon;
+  hidden labels are still read by screen readers and shown as tooltips.
+- `design="list"`: the options stacked as full-width rows, for settings pages and side panels. Each row takes an
+  `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`.
+- 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.
+- For choosing a value. For switching page panels, use tabs with panels (planned).
+
+### Split button
+
+```tsx
+import { SplitButton } from "nexus-shared/client";
+
+<SplitButton storageKey="pull-request" onAction={value => create(value)} options={[
+  { value: "create", label: "Create pull request", description: "Open a pull request that is ready for review" },
+  { value: "draft", label: "Create draft pull request", description: "Cannot be merged until marked ready for review" },
+]} />
+```
+
+- The main button runs the chosen action; the arrow opens the alternatives as a radio menu. Picking one makes it the
+  main button, and with `storageKey` the browser remembers it (`localStorage`, `nx-split:<key>`), so the next visit
+  starts with it. `runOnSelect` also runs the pick at once, for Save / Save and close.
+- `variant`, `size`, `loading`, `disabled`, `block` as `Button`; `type="submit"` with `name` submits a form and sends
+  the chosen value; `value` and `onValueChange` for a controlled choice; `align` and `menuLabel` for the menu.
+
+### Menus
+
+```tsx
+import { ContextMenu, Menu } from "nexus-shared/client";
+
+<Menu items={[
+  { value: "edit", label: "Edit", icon: <InlineIcon icon={iconPencil} />, shortcut: "Ctrl+E" },
+  { separator: true },
+  { value: "delete", label: "Delete", icon: <InlineIcon icon={iconTrash} />, tone: "danger" },
+]} onSelect={value => run(value)}>
+  <Button iconEnd={<InlineIcon icon={iconChevronDown} />}>Actions</Button>
+</Menu>
+
+<ContextMenu items={rowItems} onSelect={value => run(value, row)}>
+  <table>…</table>
+</ContextMenu>
+```
+
+- **Native popovers.** The list is a `[popover]` element: it sits above everything, closes with Esc or a click
+  outside, and needs no library. It opens under its button (above it when there is no room), lined up with the
+  button's `align="start"` or `"end"` edge, and follows the page as it scrolls.
+- **Items are params:** `{ value, label, description?, icon?, shortcut?, tone?: "danger", disabled?, href?, target?, checked?, title? }`,
+  plus `{ separator: true }` and `{ heading }`. An item with `href` is a link. The trigger is any element that
+  renders a button and passes its props on, such as `Button`.
+- `kind="radio"` or `"checkbox"` adds a check column and `aria-checked`; `closeOnSelect={false}` keeps a checkbox
+  menu open while options are toggled.
+- **Keys:** arrows move between items (wrapping, skipping disabled ones), Home and End jump, a letter jumps to the
+  next item starting with it, Enter or Space chooses, Esc closes and returns focus to the button, Tab closes and
+  moves on. Focus follows a moving pointer, so the keys carry on from the hovered item.
+- `ContextMenu` opens at the pointer on right-click, or under the focused element on Shift+F10. Its wrapper takes no
+  space (`display: contents`), so wrap a table once and note the clicked row in the row's own `onContextMenu`.
+- `placeUnderAnchor`, `placeAtPoint`, and `followAnchor` (`nexus-shared/client`) place custom popovers the same way.
+
+### Toast messages
+
+```tsx
+import { Toaster, toast } from "nexus-shared/client";
+
+// Once, in the root layout
+<Toaster position="top-right" />
+
+// Anywhere: components, services, fetch helpers
+toast.success("Booking confirmed", "Room 204, 3 nights");
+toast.error("Could not save", { message: error.message, action: { label: "Retry", onClick: save } });
+toast.promise(saveBooking(), { loading: "Saving…", success: "Saved", error: e => `Not saved: ${e.message}` });
+```
+
+- `toast(title, options?)`, `toast.info`, `.success`, `.warning`, `.error`, `.loading` (spinner, no timer), and
+  `.promise`. Options: `message`, `duration` (default 5000 ms, 0 keeps it; pauses while hovered or focused), `action`,
+  `closable`, `icon`, `position`, `onClose`, and `id` to update a toast in place. `toast.dismiss(id?)` closes one or all.
+- Each toast is a native popover of its own, so it sits above open dialogs; the newest is nearest the edge, and at
+  most `max` (default 5) show per position. Warnings and errors use `role="alert"`, the rest `role="status"`.
+
+### Popup
+
+```tsx
+import { Popup, definePopupRules, openPopup } from "nexus-shared/client";
+
+<Popup open={open} onClose={() => setOpen(false)} title="Edit booking" description="NX-2048 · Room 204"
+  footer={<><Button onClick={() => setOpen(false)}>Cancel</Button><Button type="submit" form="booking" variant="primary">Save</Button></>}>
+  <form id="booking" onSubmit={save}>…</form>
+</Popup>
+
+// From code, with a handle; needs <PopupHost /> in the layout. Never two popups with one key: opening the key again
+// replaces its popup (a fresh one), or with reopen: "restore" brings it back as it was.
+const popup = openPopup({ key: "room-edit-204", reopen: "restore", title: "Room 204", content: <RoomDetails id={204} />, footer: p => <Button onClick={() => p.close()}>Close</Button> });
+popup.minimize(); popup.restore(); popup.maximize();
+await popup.closed;
+
+// Rules by key, once, in a client module; options given to openPopup win over them
+definePopupRules({
+  "room-new": { reopen: "replace" },                  // Add: a fresh form every time (the default)
+  "room-edit-*": { reopen: "restore" },               // Edit: back as it was, with what was typed
+  "night-report": { minimizable: false, maximizable: false, movable: false },
+});
+
+// The page in charge of the window state
+<Popup open={open} windowState={state} onWindowStateChange={setState} … />
+```
+
+- Built on the native `<dialog>` shown modally: above everything, the page behind dimmed and locked (without a layout
+  shift), Tab kept inside, focus returned on close. `onClose(reason)` says whether the close button, Esc, the
+  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.
+- 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**,
+  **maximize** (restore down when maximized), **close** (red on hover). `variant="dialog"` gives the larger heading
+  instead (the icon in a circle, the description under the title), which message boxes use. `minimizable` (default: when `closable`, so a popup that must be answered cannot be put aside),
+  `maximizable` and `movable` (default true); message boxes have only close.
+- **Minimized**, the dialog closes so the page can be used, and a bar waits at the bottom right with the popup's icon and
+  title; its content stays mounted, so typed text, scroll, and the focused field are there when the bar brings it back
+  (maximized again if it was). Several stack behind the newest with a count that opens the whole list (Esc or a press
+  elsewhere closes it). An open popup's backdrop covers the dock. `<PopupHost />` renders the dock; without a host
+  there is no minimize button. Bottom-right toasts stack above it (`--nx-dock-space`).
+- **Maximized**, it fills the window edge to edge; a double-click on the title bar does the same, and restore down puts
+  it back where it was.
+- **Moved** by its title bar (not its buttons), kept inside the window, pulled back in when the window shrinks; Esc
+  during a drag puts it back; dragging a maximized popup restores it under the pointer, as desktop windows do. Each
+  opening starts centered in `defaultWindowState`.
+- **Opened again** while it is still open or minimized, a popup never doubles up. `openPopup` with a `key` whose popup
+  is there closes that popup (`onClose` and `closed` say `replaced`) and opens a fresh one: `reopen: "replace"`, the
+  default, right for an Add form, so Add, minimize, Add again cannot pile up popups. `reopen: "restore"` brings the
+  old one back as it was and returns its handle, right for editing one record. A page popup opens again through the
+  button that opened it, with the same `reopen` choice. Popups without a key are separate every time.
+- **Asking before a close**: `openPopup({ beforeClose })` runs when the user closes the popup (its close button, Esc,
+  the backdrop, or its bar on the dock); return `false`, or a promise of it, to keep it open, such as after
+  `confirmDiscard(form)` asked "Discard your changes?". Closing from code does not ask.
+- **Rules by key**: `definePopupRules({ "booking-new": {…}, "booking-edit-*": {…} })` sets `reopen`, `minimizable`,
+  `maximizable`, `movable`, `closable`, `closeOnEscape`, `closeOnBackdrop`, `size`, and `defaultWindowState` for every
+  `openPopup` with that key. A name ending in `*` matches keys that start with the rest (`*` alone, every key); all
+  matching rules apply, an exact key over a pattern and a longer pattern over a shorter one; options given to
+  `openPopup` win. It returns a function that removes the rules; `popupRuleFor(key)` shows what a key gets.
+- With motion, minimize flies to the dock and maximize grows from the old box; with reduced motion, both happen in the
+  same frame.
+
+### Drag helpers
+
+```tsx
+import { clampToBounds, makeDraggable, moveWithin, useDraggable, viewportBounds } from "nexus-shared/client";
+
+useDraggable(cardRef, { bounds: "parent" }); // the card moves, kept inside its positioned parent
+useDraggable(barRef, { target: () => cardRef.current, bounds: "parent", axis: "x", keepVisible: 40 });
+const stop = makeDraggable(titleBar, { target: panel, bounds: document.querySelector(".board") }); // without React
+moveWithin(card, { x: 10, y: 0 }, { bounds: "parent" }); // the keyboard way
+clampToBounds({ left: -20, top: 40, width: 300, height: 200 }, viewportBounds()); // { x: 0, y: 40 }
+```
+
+- The popup's title bar is built on these; any component can use them. `bounds`: `viewport` (default), `parent`,
+  an element (inside its borders), a box, a function, or `null`. `margin`, `keepVisible` (how much must stay
+  inside when it may partly leave), `axis`, `threshold` (default 3 px, so clicks stay clicks), `cancel` (controls in
+  the handle that do not drag).
+- The position is an offset from the element's place in the layout, written to CSS `translate` by default, or to CSS
+  variables (`cssVariablePosition`), or anywhere through `position: { get, set }`, so a move never shifts the layout.
+- `onStart` may cancel or change the target first; `onEnd` says whether Esc cancelled. A drag selects no text, and
+  the click that ends it does not reach what lies under the pointer. The handle needs `touch-action: none`
+  (`makeDraggable` and `useDraggable` set it).
+
+### Message box
+
+```tsx
+import { messageBox } from "nexus-shared/client";
+
+if (await messageBox.confirm({ title: "Delete booking NX-2048?", message: "This cannot be undone.", tone: "danger", confirmLabel: "Delete" })) …
+await messageBox.alert({ title: "Saved", tone: "success" });
+const name = await messageBox.prompt({ title: "Rename the room", label: "Name", defaultValue: room.name });
+const choice = await messageBox.show({ title: "Unsaved changes", tone: "warning", buttons: [{ value: "discard", label: "Don't save" }, { value: "save", label: "Save" }] });
+```
+
+- Small popups through `<PopupHost />`, the tone in the icon: `info` (alert default), `question` (confirm default),
+  `success`, `warning`, `danger`, or `neutral` for none. A danger box makes the last button red and focuses the first
+  one, so Enter cannot delete by accident.
+- `confirm` resolves `false` and `show` resolves `null` when the box is dismissed with Esc, the close button, or a
+  click outside; `prompt` resolves `null` when cancelled and refuses an empty answer while `required` (the default).
+
+### Button hover tones
+
+`hoverTone` keeps a `secondary` or `ghost` button neutral until it is hovered or focused from the keyboard, then
+colors its border, a light background, and its text. Tones: `primary`, `danger`, `success`, `warning`, `info`.
+Good for rows of actions, where full-color buttons would be too loud:
+
+```tsx
+<Button hoverTone="danger" icon={<InlineIcon icon={iconTrash} />}>Delete</Button>
+<Button variant="ghost" size="sm" hoverTone="primary" aria-label="Edit" icon={<InlineIcon icon={iconPencil} />} />
+```
+
+Every tone meets WCAG AA contrast on its light background in all themes.
+
+### Text box
+
+```tsx
+import { TEXT_PATTERNS } from "nexus-shared";
+import { TextBox, TextArea } from "nexus-shared/client";
+
+<form onSubmit={save}>
+  <TextBox name="email" type="email" label="Email" required pattern={TEXT_PATTERNS.email} icon={<InlineIcon icon={iconMail} />} />
+  <TextBox name="password" type="password" label="Password" required minLength={8} />
+  <TextArea name="notes" label="Notes" maxLength={500} showCount autoResize />
+  <Button type="submit" variant="primary">Save</Button>
+</form>
+```
+
+- **Uncontrolled by default**, so typing re-renders nothing. `onValueChange(value)` reports each change; `value` makes it controlled.
+- **Validation:** `required`, `minLength`, `maxLength`, `pattern` (a `TEXT_PATTERNS` entry carries its own message), and
+  `validate(value)` for custom rules. Messages show after a field is left with text in it (`validateOn`: `blur`, `change`,
+  `submit`). Inside a `<form>`, an invalid field blocks submit, every message shows, and the first invalid field takes focus.
+  `error` shows a message from outside, such as the server.
+- **Read-only says why.** Every input with `readOnly` shows a lock, and a short note for 2.5 seconds when someone tries
+  to change it anyway, so a click that does nothing does not look like a bug. The value is still sent with a form, and
+  selecting and copying text work as usual. Esc, leaving the field, or the timeout hide the note; `readOnlyMessage`
+  changes its text.
+
+  | Input | Lock | Tries that show the note | Default note |
+  |---|---|---|---|
+  | `TextBox`, `TextArea` | End of the box | A click, typing, Backspace, Delete, Ctrl+V, Ctrl+X (and Enter in a text area) | Read-only: this field cannot be changed. |
+  | `NumberBox` | In place of the − and + buttons | The same, and ↑ ↓ Page Up Page Down | Read-only: this number cannot be changed. |
+  | `DatePicker`, `DateRangePicker` | In place of the calendar button | The same as a text box, and ↓ | Read-only: this date (these dates) cannot be changed. |
+  | `TimePicker` | In place of the clock button | The same as a text box, and ↓ | Read-only: this time cannot be changed. |
+  | `DateTimePicker` | In place of the calendar and clock button | The same as a text box, and ↓ | Read-only: this date and time cannot be changed. |
+  | `Dropdown` | In place of the list button; chips lose their remove buttons | A click on the box or a chip, a typed key, ↓ or ↑ | Read-only: this choice (these choices) cannot be changed. |
+  | `CheckBox`, `Switch` | After the label | A click or Space | Read-only: this option (this setting) cannot be changed. |
+  | `CheckBoxGroup`, `RadioGroup` | After the group label | A click, Space, or an arrow key, under that option | Read-only: these options (this choice) cannot be changed. |
+  | `Slider`, `RangeSlider` | After the label | A press on the track or a mark, the arrow keys, Page Up/Down, Home, End | Read-only: this value (this range) cannot be changed. |
+
+  Nothing renders until an attempt, and an attempt re-renders only the note, so read-only forms of any size cost
+  nothing extra. `useReadOnlyNotice` gives a custom control the same lock and note.
+- **Props are params:** plain, named like HTML attributes, and serializable, so forms and CRUD pages can describe
+  fields as objects. Design notes for inputs, forms, and CRUD: [src/Components/Inputs/README.md](src/Components/Inputs/README.md).
+
+### Number box
+
+```tsx
+import { NumberBox } from "nexus-shared/client";
+
+<NumberBox name="nights" label="Nights" stepper="split" required min={1} max={30} defaultValue={1} />
+<NumberBox name="rate" label="Rate per night" prefix="Rs" required min={500} decimals={2} fixedDecimals grouping locale="en-IN" />
+<NumberBox name="discount" label="Discount" suffix="%" stepper min={0} max={50} step={5} />
+```
+
+- **Only a number gets in.** Typing accepts digits, one decimal separator, and a minus sign when `min` is below 0 (or
+  not set). `decimals` stops typing after that many decimals; pasted text such as "Rs 1,250.50" keeps its number, and
+  text with no single clear number is ignored rather than guessed at.
+- **Formats by locale:** `grouping` shows 12,50,000.00 (`en-IN`) or 1.250.000,00 (`de-DE`) while the box is not
+  being edited; separators come off on focus. The default locale is `en-US`, so server and browser render the same text.
+  Inside a `<form>`, a grouped box sends the plain number through a hidden input with its `name`.
+- **Steps:** ↑ and ↓ (Shift or Page Up/Down for ten), and `stepper` buttons that repeat while held. Values move along
+  the grid of `step` from `min` and stay within the limits.
+- **Values:** `onValueChange(value)` gets a `number`, or `null` when empty; `validate(value)` too. `clamp` moves an
+  out-of-range value to the nearest limit on blur instead of showing a message.
+- `npm run test:numbers` checks the number helpers (formatting, parsing, paste, rounding, stepping, messages).
+
+### Checkbox and radio
+
+```tsx
+import { CheckBox, CheckBoxGroup, RadioGroup, Switch } from "nexus-shared/client";
+
+<RadioGroup name="roomType" label="Room type" required design="cards" columns={3} options={roomTypes} />
+<CheckBoxGroup name="amenityIds" label="Amenities" columns={3} selectAll options={amenities.map(a => ({ value: a.id, label: a.name }))} />
+<Switch name="breakfast" label="Breakfast included" labelPosition="start" />
+<CheckBox name="terms" label="I accept the booking terms" required />
+```
+
+- **Native inputs, drawn with CSS.** Each option is one `<input>`, so forms, arrow keys (radios), and screen readers
+  work as usual. Box edges use the subtle text color, which meets 3:1 contrast on panels in every theme.
+- **Options are params:** `{ value, label, description?, icon?, disabled? }`. Values can be strings or numbers and
+  come back from `onValueChange` with their type.
+- **Limits:** `required`, `min`, `max`, `validate`. At `max` a checkbox group disables the other options and shows a
+  count. Messages follow the text box: after leaving a changed group, or on submit, where the first invalid option takes focus.
+- **Fast:** uncontrolled by default, so clicking re-renders nothing; 10,000 checkboxes mount in 0.5 to 0.7 s
+  in the development build.
+
+### Slider
+
+```tsx
+import { RangeSlider, Slider } from "nexus-shared/client";
+
+<Slider name="discount" label="Discount" max={50} suffix="%" defaultValue={10} />
+<RangeSlider name="price" label="Price per night" min={1000} max={30000} step={500} minDistance={1000}
+  prefix="Rs " grouping locale="en-IN" onValueCommit={([from, to]) => loadRooms(from, to)} />
+```
+
+- **Native range inputs** under a drawn track, so arrow keys, Page Up/Down, Home/End, touch, and screen readers work.
+  Each thumb announces its formatted value (`aria-valuetext`).
+- **Values read like a number box:** `prefix`, `suffix`, `decimals`, `grouping`, `locale`, or a `format` function.
+- **`onValueChange`** follows every step; **`onValueCommit`** fires once when a thumb is released or a key step ends,
+  the moment to call an API from a filter.
+- **Range:** two thumbs that never cross and keep `minDistance` apart; a click on the track moves the nearer thumb.
+  A form receives two values under the name.
+- **Marks** label points under the track and move the thumb when clicked; **`tooltip`** shows the value above the thumb.
+- Dragging writes the fill and the text straight to the DOM, so nothing re-renders.
+
+### Date picker and date range picker
+
+```tsx
+import { todayIsoDate } from "nexus-shared";
+import { Calendar, DatePicker, DateRangePicker, setDatePreferences } from "nexus-shared/client";
+
+<DatePicker name="checkIn" label="Check-in" required min={todayIsoDate()} onValueChange={iso => …} />
+<DatePicker name="fiscalYearStart" label="Fiscal year start" calendar="bs" format="YYYY/MM/DD" />
+<DateRangePicker startName="checkIn" endName="checkOut" label="Stay" required min={todayIsoDate()} minDistance={1} maxDistance={30} />
+<Calendar mode="range" months={2} range={range} onRangeChange={setRange} min={todayIsoDate()} />
+
+// A settings page
+setDatePreferences({ calendar: "bs", format: "D MMMM YYYY", script: "devanagari" });
+```
+
+- **The value is a day, not a time.** An ISO date `"2026-09-17"` in the Gregorian calendar, whatever calendar is
+  shown: what a form sends (through a hidden input with the field's `name`), what an API stores (`DateOnly`), and
+  what means the same day in every time zone. `toIsoDate` reads a `Date` in local time and an ISO date-time with a
+  zone as the local day of that instant; `isoDateToDate(iso)` gives UTC midnight, `isoDateToDate(iso, "local")` local midnight.
+- **English or Nepali from the user's settings.** `useDatePreferences` reads `nx-date-calendar` (`ad` or `bs`),
+  `nx-date-format`, and `nx-date-script` (`latin` or `devanagari`) from local storage, with the English calendar in
+  `YYYY-MM-DD` as the default; `setDatePreferences` changes every date component on the page, and other tabs follow.
+  A box can fix its own `calendar`, `format`, or `script`.
+- **Formats** use the tokens `YYYY` `YY` `MMMM` `MMM` `MM` `M` `DD` `D` `dddd` `ddd`. Typing follows the format's
+  order and is lenient: `17/9/2026`, `Sep 17, 2026`, `1 asoj 2083`, `२०८३-०६-०१`; a four-digit number is the year wherever it stands.
+- **Bikram Sambat** covers BS 1975 to 2100 (AD 1918 to 2044), as the majority of five published tables
+  (`NepaliCalendar.ts`), converted through day numbers with no `Date` objects. `npm run test:dates` checks known
+  dates and round-trips every day.
+- **DateRangePicker** holds a start and an end in one box, written as "2026-09-17 – 2026-09-24" in the user's
+  format. Pick the start and then the end in a calendar of two months (one when the window is narrow), with the
+  days between lit as the pointer moves, or type both dates around a dash, an arrow, or "to". The values are two
+  ISO dates: `onValueChange` gives `[start, end]` (`null` for an end not chosen yet), and a form sends `startName`
+  and `endName` as two fields, or both under `name`. Rules: `required`, `min`, `max`, `minDistance` and
+  `maxDistance` (days from start to end, the nights of a stay), and `isDateDisabled`, which also refuses a range
+  that includes such a day (a booked night). `validateDateRange` is the pure check behind it.
+- **Read-only** boxes have no calendar: a lock sits where the calendar button was, and a click, a typed key, or ↓
+  shows a note under the box, as in every read-only input (see [Text box](#text-box)).
+- **Calendar** is the pickers' panel and a component of its own: month and year menus, arrow keys (Page Up and Page
+  Down for months, with Shift for years), `min`, `max`, `isDateDisabled`, `weekStart`, `weekendDays` (Saturday is
+  red in the Nepali calendar), `mode="range"` with a live preview, `months={2}` side by side (a page passes 1 on
+  a phone; the calendar does not measure), `month` and `onMonthChange` to load a month's events, and `renderDay`
+  to draw markers in a cell.
+
+### Time picker
+
+```tsx
+import { TimePicker, setDatePreferences } from "nexus-shared/client";
+
+<TimePicker name="arrival" label="Arrival" required min="14:00" max="22:00" step={1800} view="list" onValueChange={iso => …} />
+<TimePicker name="shiftStart" label="Shift start" min="22:00" max="06:00" format="HH:mm" />
+<TimePicker name="spa" label="Spa slot" view="list" step={1800} isTimeDisabled={iso => booked.has(iso)} />
+
+// A settings page
+setDatePreferences({ timeFormat: "HH:mm" });
+```
+
+- **The value is a time of day, not an instant.** An ISO time on a 24-hour clock, `"14:30"` (`"14:30:15"` when
+  `step` has seconds), with no date and no zone: what a form sends through a hidden input with the field's `name`,
+  and what a .NET `TimeOnly` stores. `toIsoTime` reads `"9:05"`, `"14:30:00.000"`, a `Date` (its local time), and an
+  ISO date-time (with a zone, the local time of that instant; without one, its time part).
+- **12 or 24 hours from the user's settings.** `nx-time-format` in local storage, next to the date settings, holds
+  a format of tokens `HH` `H` `hh` `h` `mm` `m` `ss` `s` `A` `a`; the default is `hh:mm A` (02:30 PM).
+  `useDatePreferences` returns it as `timeFormat`, and `setDatePreferences({ timeFormat })` changes every time picker
+  on the page. Nepali dates in Devanagari bring Nepali digits and पूर्वाह्न/अपराह्न. A box can fix its own `format` or `script`.
+- **Typing** works on either clock: `2:30 pm`, `2.30p`, `230pm`, `14:30`, `1430`, `9`, `१४:३०`. Without AM or PM the
+  hours are read on a 24-hour clock. Leaving the box writes the time in the format.
+- **Columns** (the default) show hours, minutes, seconds when the step needs them, and AM/PM; the chosen items line
+  up on the middle row, a pick in any column changes the time at once, and ↑ ↓ ← → Home End Page Up/Down move through
+  them. **`view="list"`** shows one slot per `step` (every 30 minutes for steps under 5 minutes); a click or Enter
+  picks and closes.
+- **Rules:** `required`, `min` and `max` (with `max` earlier than `min` the range runs past midnight, 22:00 to 06:00),
+  `step` in seconds counted from midnight as in HTML, `isTimeDisabled` for booked slots, and `validate`. Items outside
+  the rules are dimmed in the panel; a typed time outside them gets a message such as "Arrival must be in steps of 30
+  minutes, like 02:00 PM or 02:30 PM." `validateTime` is the pure check behind it. `npm run test:times` checks the helpers.
+- **Read-only** boxes have no panel: a lock sits where the clock button was, as in every read-only input.
+
+### Date and time picker
+
+```tsx
+import { DateTimePicker } from "nexus-shared/client";
+
+<DateTimePicker name="pickupAt" label="Airport pickup" required min={new Date()} step={900} minTime="05:00" maxTime="23:00" />
+<DateTimePicker name="checkInAt" label="Check-in" timeZone="Asia/Kathmandu" defaultTime="14:00" />
+<DateTimePicker name="spaAt" label="Spa slot" view="list" step={1800} isTimeDisabled={(time, date) => booked.has(`${date} ${time}`)} />
+```
+
+- **The value is a moment, in UTC.** `"2026-09-17T08:45:00.000Z"`, the shape `toISOString` writes, is what the hidden
+  input sends and `onValueChange` gives, whatever the user sees; the same moment is 02:30 PM in Kathmandu and 04:45 AM
+  in New York, so no time zone can move a saved value. Store it as UTC: a .NET `DateTimeOffset`, or a `DateTime` of
+  kind `Utc`. For a day with no time use `DatePicker`; for a time of day with no date, `TimePicker`.
+- **Values in** (`toUtcDateTime`): an ISO date-time with `Z` or an offset is that moment; one **without a zone is read
+  as UTC**, the way a UTC `DateTime` loaded from a database often arrives without its `Z`; a date alone is the first
+  moment of that day where the user is; a `Date` or milliseconds are that moment. .NET's seven digits of fractions are read.
+- **Shown in the user's zone and settings.** The browser's time zone, and the date (`nx-date-calendar`,
+  `nx-date-format`, `nx-date-script`) and time (`nx-time-format`) settings of the other pickers: "2026-09-17 02:30 PM",
+  or "२०८३-०६-०१ ०२:३० अपराह्न". The panel names the zone ("Kathmandu · UTC+05:45"). `timeZone` fixes a zone, such as a
+  hotel's, and writes its city in the box. The server does not know the user's zone, so a box shows its text right
+  after hydration rather than another zone's time for a moment; the hidden input holds the value from the start.
+- **No data loss.** A value changes only when the user changes what it shows: seconds and milliseconds the box does not
+  show stay as they came (a stamp from the server is sent back exactly), and retyping or re-picking what it shows keeps
+  the moment. Where clocks go back, one hour happens twice: a box holds whichever it was given, an edit inside that hour
+  keeps its offset, and a new pick is the first of the two. Where clocks go forward, a skipped time moves on (02:30
+  becomes 03:30), as `Date` and Temporal do.
+- **Typing:** a date in the user's format, then a time on either clock: `2026-09-17 2:30 pm`, `17/09/2026 14:30`,
+  `Sep 17, 2026 at 2:30 PM`, `2026-09-17T14:30`, `२०८३-०६-०१ १४:३०`. A date alone takes `defaultTime` (default
+  `minTime`, or midnight). Leaving the box writes it in the settings.
+- **The panel** is the calendar and the time columns (or `view="list"` slots) side by side, as tall as each other, with
+  Now, the zone, and Done. A picked day keeps the time; ↓ opens it on the chosen day, Enter on a day moves on to the
+  hours, and Tab runs through the calendar, the columns, and the buttons. On a phone the time goes under the calendar,
+  and a panel taller than the room scrolls, moving to the time once a day is picked.
+- **Rules:** `required`; `min` and `max` as moments (days outside are dimmed, and times outside on the first and last
+  day); `minTime` and `maxTime` as opening hours on every day (past midnight when `maxTime` is earlier); `step` in
+  seconds from each midnight; `isDateDisabled(date)` and `isTimeDisabled(time, date)` with ISO dates and times where the
+  user is; `validate`. Messages read like the box: "Airport pickup must be between 05:00 AM and 11:00 PM."
+  `validateDateTime(value, rules, fieldName, options)` is the pure check. `npm run test:datetimes` checks the helpers
+  against `Date` in eight zones, including half-hour daylight saving and a skipped day.
+- **Read-only** boxes have no panel: a lock sits where the button was, as in every read-only input.
+
+### Dropdown
+
+```tsx
+import { Dropdown } from "nexus-shared/client";
+
+<Dropdown name="roomType" label="Room type" required options={roomTypes} />
+<Dropdown name="amenities" label="Amenities" multiple max={6} options={amenities} />   // { value, label, icon: "wifi" }
+
+// Rows like a data table
+<Dropdown name="assignee" label="Assign to" options={staff} valueKey="id" labelKey="fullName"
+  columns={[{ key: "photo", type: "avatar" }, { key: "username", header: "Username" }, { key: "fullName", header: "Full name" }]} />
+<Dropdown name="country" label="Country" options={countries} valueKey="code" labelKey="name"
+  columns={[{ key: "flag", type: "image" }, { key: "code", header: "Code", type: "code" }, { key: "name", header: "Country" }]} />
+
+// A server list, editing a saved value
+<Dropdown name="guestId" label="Guest" valueKey="id" labelKey="fullName" defaultValue={booking.guestId} selectedOptions={[booking.guest]}
+  loadOptions={({ search, skip, pageSize, signal }) => api.guests({ search, skip, take: pageSize }, signal)} />  // { items, total }
+```
+
+- **Options are any objects.** `{ value, label, description, icon, disabled }` by default (a `ChoiceOption`), or API rows
+  read through `valueKey`, `labelKey`, `descriptionKey`, and `iconKey`. Values keep their type; a number and its text
+  are the same value, so id 7 from an API matches "7" from a form. A form gets hidden inputs named `name`, one per value.
+- **Columns** turn rows into cells that line up down the list (one grid with subgrid rows), with headings that stay on top.
+  Types: `text`, `muted`, `code`, `avatar` (a photo URL, or initials of the label on a soft tone), `image` (4:3: flags,
+  logos), and `icon` (a Tabler name); `width`, `align`, and `render` for the rest. The first picture leads the value in
+  the box and in chips.
+- **Search** matches every typed word in any order, with or without Latin accents, in the label, description, value, and
+  text columns (`searchKeys` to change). It is on with `loadOptions` or more than 8 options; without it, letters jump to
+  an option as in a native select. A local list renders 100 rows and adds more while it scrolls: 10,000 options open in
+  about 30 ms.
+- **Server pages:** `loadOptions({ search, page, pageSize, skip, signal })` returns `{ items, total?, hasMore? }`. The first
+  page loads when the list opens (placeholder rows, a spinner in the box), the next near the end ("Loading more…"), a new
+  search 250 ms after typing stops, aborting the request before it. A failure shows Retry. `loadKey` drops the loaded
+  pages, for a list that depends on another field. `loading` shows the same loaders when the page fetches `options` itself.
+- **Saved values the list can no longer offer** always show, and are never offered again once removed:
+  - on a server page not loaded: `selectedOptions` gives their items (a record usually carries the name), or
+    `resolveOptions(values)` looks them up (a placeholder shows until it answers);
+  - inactive items (`inactive: true` or `isActive: false`, or `isOptionInactive`): never in the list, shown only as a value;
+  - values missing from `options`: tagged **Unavailable**, or **Not found** when nothing is known but the value.
+
+  In the list they sit on top under **Selected** with their tag; in the box they carry the tag, or show as dashed chips.
+  A value only on another server page has no tag: a search finds it as a normal option.
+- **Rules:** `required`, `min` and `max` for several (at `max` the other options are disabled), and `validate`, through
+  `validateSelection`. A pick follows the same message timing as typing. `npm run test:dropdown` checks the helpers.
+- **Keys:** ↓ ↑ Page Up/Down Home End move past rows that cannot be picked, Enter picks, Space picks without search,
+  Backspace in an empty box removes the last value, Esc closes (then clears the search), Tab closes and moves on.
+- **Read-only** boxes have no list: a lock sits where the list button was, chips lose their remove buttons, and a click or
+  a key shows the note, as in every read-only input.
+
+### Markdown editor
+
+```tsx
+import { MarkdownView } from "nexus-shared";
+import { MarkdownEditor } from "nexus-shared/client";
+
+<MarkdownEditor name="description" label="Room description" defaultValue={room.description} defaultMode="split"
+  height={320} heightKey="room-description" maxLength={5000} required />
+
+// Wherever the text is shown, also in a server component
+<MarkdownView value={room.description} />
+```
+
+- **Write, split, and preview.** `defaultMode` (or `mode` with `onModeChange`) picks the view, and `modes` the views
+  offered. The switch is small tab buttons with `labels="selected"`: icons, and the label of the selected view. Split puts the preview beside the text and keeps the two scrolled together; under 560 px wide it stacks
+  them. The preview renders as a React transition, so typing stays within a frame in a 2,000-line document.
+- **Toolbar and shortcuts:** heading, bold (Ctrl+B), italic (Ctrl+I), strikethrough (Ctrl+Shift+X), quote
+  (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.
+- **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
+  the height as it changes; its grip takes ↑ ↓ (Shift for more), Page Up/Down, Home, and End; a double-click goes back
+  to `height`. `heightKey` remembers the user's height in local storage. Dragging writes straight to the DOM.
+- **Full screen** (`fullscreen`, on by default) lifts the editor into the top layer over a dimmed page, without
+  moving it in the DOM, so undo history and the form stay. Tab stays inside, and Esc closes it.
+- **A form field like `TextArea`:** `name`, `required`, `minLength`, `maxLength`, `pattern`, `validate`, the status bar's
+  word and character count, and read-only (a lock in the bar and a note under it). An invalid submit while the preview
+  shows brings the text back and focuses it. The view switch belongs to no form (`TabButtons` `form`), so it is never sent.
+- **Safe to show anyone's text.** `parseMarkdown` (GitHub-flavored: tables, tasks, strikethrough, autolinks) never
+  renders raw HTML, and `safeUrl` keeps only http, https, mailto, tel, and relative addresses for links, and raster
+  data URLs for images. Links to other sites get `rel="nofollow noopener noreferrer"`.
+- **Helpers:** `markdownToPlainText` for excerpts and search, and the editing commands `applyMarkdownTool`,
+  `continueMarkdownList`, `toggleMarkdownTask`, and `linkPastedUrl` for a custom editor. `npm run test:markdown`
+  checks the parser and every command.
+
+### Forms
+
+```tsx
+import { TEXT_PATTERNS, type InputParams } from "nexus-shared";
+import { ApiForm, SubmitForm } from "nexus-shared/client";
+
+const ROOM_INPUTS: InputParams[] = [
+  { type: "text", name: "number", label: "Room number", required: true, pattern: TEXT_PATTERNS.digits, span: 4 },
+  { type: "number", name: "floor", label: "Floor", required: true, min: 0, span: 4 },
+  { type: "dropdown", name: "type", label: "Type", required: true, options: ROOM_TYPES, span: 4 },
+  { type: "tabular", name: "beds", label: "Beds", itemLabel: "Bed", inputs: BED_INPUTS },   // a list is an input too
+];
+
+<ApiForm
+  inputs={ROOM_INPUTS}
+  loadValue={signal => api.get(ROOMS.details, { params: { id }, signal, toast: false }).then(unwrapApiResult)}
+  api={ROOMS.update}   // or in place: { module: NexusModule.Reservation, path: "Room/Update", method: "PUT" }
+  draftKey={`hotel-3:user-8:room:${id}`}
+  onSuccess={room => table.updateRow(room)}
+  onCancel={close}
+/>
+```
+
+- **Params in, values out.** Every input is an entry of `inputs`, so a page, a CRUD component, or a server can describe a
+  form with plain objects. Values come in as each input reports them (a date-time from an API becomes a date, "12.5"
+  becomes 12.5), and fields the record came with (an `id`) stay in the values.
+- **Fast at any size.** The values live in a `FormStore` outside React. Typing renders only the input typed in; an input
+  renders again only when a message it shows changes, or code sets its value. A keystroke costs about 5 µs in the store
+  for a form of 200 inputs, and a list of 10,000 rows is not checked again on each keystroke (it checks itself).
+- **Checks on Save.** Each input's own rules (they also catch text that is not a date yet), the form's `validate` across
+  inputs, and rows not on the page. Every message shows, the first problem takes focus (a table scrolls to its row), and
+  the status line lists what needs attention, each name a link to its input. A rule message on an input shows once the
+  input was left, and on Save.
+- **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.
+- **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).
+  `form.load(values, { keepChanged: true })` refreshes a record without touching what the user changed.
+- `npm run test:forms` checks the store and the API helpers; `scripts/browser-checks/forms.cjs` in the template checks the
+  three demo pages.
+
+### API calls
+
+```ts
+// api-modules.ts: the app's modules and where each one's root is (shared by the browser and the server)
+import { defineApiModules, NexusApiModules, NexusModule } from "nexus-shared";
+
+export const MODULES = defineApiModules(new NexusApiModules({ useProxy: process.env.NEXT_PUBLIC_API_PROXY !== "false" }));
+export const ROOMS = MODULES.controller(NexusModule.Reservation, "Room", "room");
+
+// In the browser
+import { api } from "nexus-shared/client";
+const rooms = await api.get<Room[]>(ROOMS.listing);                    // GET /api/app/reservation/Room/NormalListing
+await api.put(ROOMS.update, values, { subject: "Room 204" });          // toast: "Room 204 saved." or what failed and why
+await api.confirm(ROOMS.delete, { params: { id }, subject: "Room 204" });   // asks "Delete Room 204?" first
+
+// On the server (a server component, a route handler, a server action)
+import { serverApi } from "nexus-shared/server";
+const list = await serverApi.get<Room[]>(ROOMS.listing, { revalidate: 60, tags: ["rooms"] });   // straight to API_RESERVATION
+
+// app/api/app/[module]/[...path]/route.ts: the browser's way to every module
+export const { GET, HEAD, POST, PUT, PATCH, DELETE } = createApiProxy({ token: readAccessToken });
+```
+
+- **Modules are the app's.** `ApiModules<TModule>` is an abstract class over the app's own module enum: implement
+  `modules` (each module's value, its key in proxy URLs, its label for messages, where its root comes from) and
+  `serverRoot(module)` (from the environment, a settings service, anything; may be async). Register it once with
+  `defineApiModules`, and define endpoints through it (`MODULES.controller`, `MODULES.endpoint`), so a file that calls
+  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.
+- **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
+  type error. Without it, the modules are `NexusModule`.
+- **The proxy, on or off.** With `useProxy` (the default), the browser calls `/api/app/<module>/<path>` and the proxy
+  route sends it on to the module's root with the user's token, which never reaches the browser; it strips the app's
+  cookies and the backend's hop headers, refuses `..`, rewrites the backend's redirects, and answers failures the way
+  the backend does. Off, the browser calls each module's `browserRoot` (public) and the proxy serves none.
+  `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.
+- **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,
+  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
+  it: "3 rooms deleted.", "Could not move Room 204 to the trash.", "You do not have permission to delete Room 204.". The
+  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.
+- `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`.
+
+### Data table
+
+```tsx
+import type { TableColumn } from "nexus-shared";
+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: "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
+];
+
+const table = useTable<Booking>();
+<DataTable table={table} aria-label="Bookings" columns={COLUMNS} rows={bookings} selectable massActions={MASS} rowActions={row => ACTIONS(row)} stateKey="bookings" />
+<DataTable columns={COLUMNS} paging="server" load={(query, signal) => fetchPage(query, signal)} />   // { search, sort, page, pageSize }
+<DataTable columns={COLUMNS} rows={bookings} onImport={askForFile} moreActions={[{ id: "report", label: "Monthly report", onSelect: open }]} />
+
+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.
+- **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
+  newer query stops the one before, so a late answer never shows. A loader may answer without a promise (a cache), and
+  the rows then paint with the table. `loadKey` starts over for another list behind the same table.
+- **What it shows while it waits.** Placeholders in the shape of the rows for the first rows; afterwards the rows stay,
+  with a thin bar under the headings, and dim only if a load takes a moment. A failed load says why, with Retry; an empty
+  list has its own message and action; a search that finds nothing offers Clear search.
+- **The columns are the user's.** Drag a heading to another place, drag its right edge for its width (double-click the
+  edge, or "Fit to content", to fit it, never under the column's `minWidth`), and use the caret on the heading to sort,
+  pin it left or right, move it, or hide it; the Columns menu shows and hides them. A column opts out with
+  `movable`, `resizable`, or `pinnable: false`, and `pinned` starts it on a side. The table itself can refuse all three
+  (`reorderable`, `resizable`, `pinnable`). Once a width is set the columns are laid out from those widths, so one edge
+  moves alone; "Reset columns" in the options menu puts everything back.
+- **One options menu (⋮)**: the columns shown as a CSV (`exportable`, named by `exportName` or the table's label), a
+  print view of the same in a frame of its own (`printable`), Import (`onImport`), and any `moreActions` of the page.
+  A client table writes every row the search left; a server table writes the page it has, and says so.
+- **Selection.** The first column counts the rows (`numbered`, on by default when `selectable`) and turns into the row's
+  checkbox under the pointer; once anything is selected every row shows its checkbox and the heading shows the box that
+  selects the page (partly checked when some are). Shift+click selects a range, up to `maxSelection` (500). While rows
+  are selected, a bar with the count, one split button holding every `massAction`, and Clear covers the headings, so
+  nothing moves: the menu makes the action picked the button, and the next click runs it, with a spinner while it does.
+- **Row actions**: `inline` ones as icon buttons, the rest in the row's menu; while one runs (a promise), the row is busy.
+  `onRowOpen` for a double-click. A row added or saved is highlighted for a moment (steadily, with reduced motion).
+- **A pinned section.** `pinnedRows` puts rows in a band above the page with a button that folds them open and shut
+  (`pinnedLabel`, `pinnedMax` beside the count, `pinnedLoading` while they come); with a `stateKey` the choice is
+  remembered on the device. They are the same records as in the list below, and each wears a pin where the rows of the
+  page show their number.
+- **Wide tables** scroll inside their frame, with the numbers and checkbox column on the left, the actions on the right,
+  any pinned columns beside them, and the headings on top staying in place, and a soft shadow where columns scroll under
+  them. Under the table: "Showing 41–50 of 234" (and how many the search left out) on the left, "Page 5 of 24" and the
+  pager on the right; rows per page sits inside the search box. At 520px and less the page buttons go; at 560px the
+  search takes its own line.
+- `npm run test:table` checks the helpers, the store, and the CRUD rules; `scripts/browser-checks/data-table.cjs` in the
+  template checks `/demo/data-table`.
+
+### CRUD
+
+```tsx
+import { Crud } from "nexus-shared/client";
+
+export const GUESTS = MODULES.controller(NexusModule.Reservation, "Guest", "guest");   // every list and action
+
+<Crud<Guest>
+  api={GUESTS}
+  columns={GUEST_COLUMNS}                                 // as a DataTable takes them
+  inputs={GUEST_INPUTS}                                   // or { create, edit }, or (action, row) => inputs
+  paging="server"                                         // default "client": each list loaded once
+  form={{ load: "details", newValues: { country: "Nepal" } }}
+  details={{ columns: GUEST_DETAILS }}
+  onChange={({ action, rows, mode }) => audit(action, rows)}
+/>
+```
+
+- **Lists.** All (`NormalListing` or `NormalPagination`), Flagged, Archived, 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
+  (`configureCrud({ maxPins: 100 })`, 100 by default). Pinning a selection bigger than the room left pins as many as fit,
+  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
+  `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.").
+- **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.
+- **Add and Edit** open popups built on `ApiForm`, with the Save bar in the footer and the server's messages on their
+  inputs. Keys keep them one each: pressing Add again brings back an Add form with changes (minimized or not), or opens a
+  fresh one; Edit of a record already open brings that popup back as it was. Closing a form with changes (its close
+  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.
+- **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.
+- **Permissions** come from the app's rules: `definePermissions(new NexusPermissions())` once, then `setActions(accessActions)`
+  after sign-in. While the rules load, the table shows placeholders; a user with no list sees a message. Rules for
+  another backend extend `Permissions` (`can(endpoint)`), and its page and mass shapes extend `CrudBackend`.
+- `ref` gives `table`, `mode`, `setMode`, `reload`, `create(values)`, `edit(row)`, and `view(row)`.
+- `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.
+
+Planned, following the previous Nexus project: a page status layout, and in the CRUD, audit logs in the details view.