portal-mojo 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,55 @@
+# portal-mojo (the package)
+
+The React portal toolkit for django-mojo. Ships as **TypeScript source** via
+subpath exports — consumers compile it with their own Vite + TS
+(`moduleResolution: "bundler"`); there is no package build step here.
+
+```bash
+npm install portal-mojo react react-dom react-router-dom @tanstack/react-query
+```
+
+**Per-component reference docs (written for AI context): [`docs/`](docs/README.md).**
+Live demos for everything: run `npm run dev:showcase` → **Develop → Components**.
+
+## Subpath surfaces
+
+| Subpath | Surface |
+|---|---|
+| `portal-mojo/client` | Typed django-mojo protocol layer: envelope unwrap at exactly one boundary (a failed save **rejects**), `start`/`size` paging, `'-field'` sort, Django lookups, the URL-synced `useTableParams` store (single source of truth for table state), TanStack Query hooks. Auth client: password / magic-link / passkey login, forgot/reset, cross-origin handoff (`?auth_code=` scrub-before-network), single-flight refresh + pre-request gate (synthetic-401 reject, `/api/token/refresh` recursion guard), `X-Mojo-UID` device header, `getAuthSnapshot`/`subscribeAuth` for React. Auth-challenged realtime transport: `RealtimeProvider`/`RealtimeClient`, refcounted topics, typed event projection, and a deterministic mock. Boot auth with `initAuth()`. The in-memory HTTP mock transport lives here too — it is the wire contract's executable spec and evolves in lockstep with the client (any seeded active user logs in with email + `"mojo"`). |
+| `portal-mojo/ui` | Mission-control UI: `ModelTable`, `FilterBar`/`FilterPills`, `SchemaForm`/`formModal`, `DetailView`, `RecordFeed`, `AttachmentQueue`/`UploadQueue`, `ImageEditor`/`imageEditorModal`, awaitable native-`<dialog>` `modal`, `toast`, `ThemeProvider`, `Guarded` (permission slot), `GroupSwitcher` (searchable tree selector), `RequiresGroup`, the sidebar engine (`registerMenus`/`setDefaultMenu` registry + `SidebarNav` — static or searchable accordion with a compact icon rail; global and group scopes are explicit), `Badge`/`MetricCard`/`Spark`, `fmt` formatter namespace. |
+| `portal-mojo/charts` | Dependency-free SVG charts: `SeriesChart` (line/bar/area, stacked bars, legend toggle, crosshair tooltip) and `MetricsChart` (granularity/range/type control bar for `/api/metrics/fetch`). |
+| `portal-mojo/admin` | Global Admin **section bundles**, dual-mount: the standalone back-office portal mounts all of them at root; a product portal embeds them under a global "System" area. `AdminSection` contract + `adminSectionsMenu()` (sections → domain-grouped sidebar menu, mount-point-relative, with section + route permission clauses). Admin scope masks active-group membership even when embedded. Reusable domains include credentials, monitoring, security operations, settings, Bouncer, Members, and the Assistant control plane with narrow realtime streaming plus authoritative REST fallback/reconciliation. |
+
+## What the consuming app must provide
+
+- **Theme tokens + component CSS.** Components render semantic classes
+  (`panel`, `chip`, `tbl`, …) styled by the app's `theme.css` under
+  `data-theme="light"` **and** `"dark"` (reference set:
+  `apps/portal/src/theme.css`).
+- **Tailwind scan of this package.** In an installed app's CSS:
+  `@source "../node_modules/portal-mojo/src";` (adjust the relative path from
+  that CSS file). Utility classes used in package components are generated by
+  the app's Tailwind pass. Monorepo development may scan
+  `../../../packages/portal-mojo/src` instead.
+- **bootstrap-icons.** Components emit `bi bi-*` classes; the app imports the
+  icon font once.
+- **Providers.** Every shell supplies `QueryClientProvider` (spread
+  `mojoQueryDefaults()` into its defaults), a hash router (`useTableParams` is
+  built on react-router's `useSearchParams`), `ThemeProvider`, `ModalHost`, and
+  `ToastHost`. Mount one auth-owned `RealtimeProvider` before any realtime hook
+  or Assistant surface; individual permission-gated consumers own topic/event
+  lifetimes, not the shared connection. Product portals additionally install
+  `GroupProvider` so their group-scoped pages and menus can fold active-member
+  permissions into `useCan`/`Guarded`. The standalone Admin shell deliberately
+  does not install group context; it does install one
+  `RightPanelProvider`/`RightPanelSlot` for the globally gated Assistant panel.
+- **`VITE_MOJO_API`.** Unset → the in-package mock transport (dev default);
+  set to a django-mojo origin → the real backend, same code path.
+
+## Rules
+
+The non-negotiables live in the repo root `PLAN.md` ("Architecture rules") and
+`CLAUDE.md`. Short list: params store owns table state; one envelope-unwrap
+boundary; failure is unmissable; controlled inputs only; models are
+definitions + hooks (TanStack Query owns cache); `ReactNode` slots, never
+trusted-HTML strings; both themes from day one.

package/docs/DetailView.md

@@ -0,0 +1,173 @@
+# DetailView — the UserView house style
+
+```ts
+import {
+    DetailView, Eyebrow, FlatRow, SecurityItem,
+    type Section, type RailEntry, type DetailMenuEntry, type DetailViewProps,
+} from 'portal-mojo/ui';
+```
+
+The record-detail surface: identity header (avatar, title, subtitle,
+chips, optional active switch, kebab menu, close) over a left rail of
+sections with side-label dividers. Open it inside `modal.detail(...)` for
+the standard row-click experience. Ported from web-mojo `SideNavView.js`
+(sections, gating, badges) + `ContextMenu.js` (the kebab).
+
+**Admin convention:** every record inspection launched from an Admin table
+uses this KISS detail-modal pattern unless the product explicitly specifies a
+different presentation. Top-level Admin resources remain pages in the global
+Admin sidenav; the selected record does not become a child route, drawer, or
+persistent right panel by default. Focused edit/action dialogs may stack above
+the detail through `modal.open` or `modal.confirm`.
+
+Because sections and menu entries can carry permissions, DetailView
+resolves the live session (`useMe` + active-group member) — like the rest
+of the toolkit it must render inside the app's `QueryClientProvider`
+(mount `GroupProvider` too if member permissions should fold in).
+
+```tsx
+<DetailView
+    avatarName={u.display_name || u.username}
+    title={...} subtitle={u.email}
+    chips={[{ icon: 'bi-patch-check-fill', text: 'Email', tone: 'success' }]}
+    active={{ value: u.is_active, onChange: (next) => ... }}
+    onClose={onClose}
+    badges={{ sessions: openSessions }}
+    menuContext={u}
+    contextMenu={[
+        { label: 'Resend invite', icon: 'bi-envelope-paper', when: (u) => u?.last_login == null, onSelect: ... },
+        { divider: true },
+        { label: 'Delete', icon: 'bi-trash', danger: true, permissions: ['manage_users', 'users'], onSelect: ... },
+    ]}
+    sections={[
+        { key: 'profile', label: 'Profile', icon: 'bi-person', render: () => <>…</> },
+        { divider: 'Security' },
+        { key: 'security', label: 'Security', icon: 'bi-shield-check', permissions: 'view_security', render: () => <>…</> },
+    ]}
+/>
+```
+
+- `active` is a CONTROLLED switch — cancelling a confirmation simply not
+  changing state snaps it back (the disable-flow pattern: off → collect
+  reason via `formModal`, cancelled → no state change).
+- `sections` mixes `{key, label, icon, render, permissions?}` entries with
+  `{divider: 'Label'}` side-labels.
+- `initialSection` picks the starting rail entry.
+
+## Permission-gated sections (fail-closed)
+
+`Section.permissions` is a permission name or an ANY-of array, resolved
+exactly like `useCan` (signed-in user + active-group member; `admin` and
+superuser pass everything; `sys.` pins to system level). **Fail-closed**:
+while `me` loads, while anonymous, and on a failed check the section is
+absent from the rail AND cannot be activated — there is no route to a
+gated section's content, and its content is never mounted (not even
+hidden).
+
+- **Orphan dividers drop.** After gating, a `{divider}` label survives
+  only if the next visible entry is a section — trailing and doubled
+  dividers disappear with their group (a leading divider with visible
+  content below it stays). Source rule: `SideNavView._visibleSectionConfigs`.
+- **Active self-heal.** If the ACTIVE section becomes invisible
+  (permission or schema change), selection falls back to the first visible
+  section — and the heal is STICKY (`_reconcileActiveSection` parity): the
+  old section regaining visibility does not steal selection back.
+
+## Rail badges (controlled)
+
+`badges?: Record<sectionKey, ReactNode>` — numbers, text, dots
+(`<span className="rail-dot" />`), or any node, rendered at the right edge
+of the rail entry. Primitive values (string/number — including `0`) get
+the source's default muted pill; elements render as given, so
+`<Badge tone>` owns its look. Nullish / `false` / `true` / `''` render
+nothing.
+
+**Deviation from web-mojo, by design:** the source's imperative
+`setBadge(key, value)` patched the DOM in place. Here badges are a
+CONTROLLED prop — React owns the state; update the prop and the rail
+follows. There is no imperative handle.
+
+## Header kebab menu
+
+`contextMenu?: Array<{ label, icon?, permissions?, when?, onSelect, danger? } | { divider: true }>`
+renders a three-dot button in the header gutter (before the close X) that
+opens a `Popover` menu (`placement: bottom-end`, top-layer — works inside
+`modal.detail`). Filtering is `ContextMenu.visibleItems` parity:
+
+- `permissions` — same any-of, fail-closed gate as sections.
+- `when(menuContext)` — visibility predicate over the `menuContext` prop
+  (by convention the record on display; `undefined` when not provided).
+  Re-evaluated every render, so entries track model state live.
+- Hidden entries drop; separators that end up leading, trailing, or
+  doubled collapse — the menu never shows an orphaned rule.
+- No surviving entries ⇒ no kebab button at all.
+- Select runs `onSelect()` then closes the menu (source order). Outside
+  mousedown and Escape close it too (Popover semantics).
+- `danger: true` styles the entry with `--bad` (destructive actions).
+
+`DetailView` is generic over the context: `DetailView<TCtx>` — `TCtx` is
+inferred from `menuContext`, and `when` receives `TCtx | undefined`.
+
+## Lazy mount + keep-alive
+
+A section's content mounts on FIRST activation and stays
+mounted-but-hidden afterwards (CSS `hidden`, not unmount), so section
+state — form drafts, scroll-free local state, in-flight queries —
+survives switching away and back. This is the source's
+unmount-not-destroy semantic translated to React.
+
+- Never-activated sections don't mount at all (lazy).
+- Permission revocation UNMOUNTS the revoked section entirely
+  (fail-closed beats keep-alive — revoked content must not linger in the
+  DOM); regaining the permission remounts it fresh, state gone.
+- A section removed from the `sections` array unmounts and loses state;
+  re-adding it starts fresh (source `removeSection` destroyed the view).
+- Components used inside `render` must be module-level (or otherwise
+  identity-stable) — an inline component literal re-created each parent
+  render remounts every time, defeating keep-alive.
+
+## Misconfiguration warns — never silence
+
+Invalid config falls back WITH a `console.warn` (once per problem per
+instance, not per render):
+
+| Problem | Fallback |
+|---|---|
+| `permissions` not a string/string[] (or non-string array entries) | treated as DENIED (fail-closed; superuser/`admin` still pass) |
+| `badges` key naming no section | ignored |
+| duplicate section `key` | warned (activation + keep-alive key on it) |
+| `initialSection` naming no section at all | falls back to first visible |
+| contextMenu entry without `label`/`onSelect` | dropped |
+| contextMenu `when` not a function | predicate ignored |
+
+A merely GATED `initialSection` heals silently — that is normal
+permission behavior, not misconfig.
+
+## Row/section primitives
+
+| Component | Use |
+|---|---|
+| `Eyebrow` | small uppercase section heading inside a panel |
+| `FlatRow` | label + value row; `action` adds the edit pencil (`actionIcon` to override, e.g. `bi-plus-lg` for empty values) |
+| `SecurityItem` | icon + title + description row with a trailing slot (badge/button) |
+
+Conventions from the Users proof: pencil actions open `formModal` with
+current values as `initial`; a danger action lives in a `.danger-zone`
+block at the bottom of a section; fields the wire doesn't carry for other
+users (me-graph only: `has_passkey`, `requires_mfa`) don't get rows.
+
+## Pitfalls
+
+- **Gated `initialSection` lands on the first visible section** and stays
+  there even after grants finish loading (fail-closed + sticky heal, per
+  source). Don't point `initialSection` at a gated section expecting it
+  to activate late.
+- **Hidden sections keep rendering** (they're mounted): their `render()`
+  closures re-run on every parent render and their queries stay live.
+  Keep section bodies pure-render; put expensive work behind hooks that
+  cache.
+- **Badges are state, not commands** — to "setBadge", change the value
+  your `badges` prop is built from.
+- The styles for the C1 chrome live in `apps/portal/src/theme/detailview.css`
+  (`.rail-badge`, `.rail-dot`, `.dv-menu*`, `.dv-keep`) — tokens only,
+  both themes.

package/docs/ModelTable.md

@@ -0,0 +1,128 @@
+# ModelTable — the server-driven table
+
+```ts
+import { ModelTable, ExpandingSearch, type Column, type Preset, type BatchAction, type RowId } from 'portal-mojo/ui';
+```
+
+## Row identity
+
+The row constraint is `T extends { id: RowId }` where `RowId = number | string`.
+Most django-mojo models use an integer pk, but some declare a 32-char uuid-hex
+`CharField` primary key (`jobs.Job`, `jobs.ScheduledTask`) — so selection,
+expansion, React keys and `BatchAction` targets are all keyed on the union. An
+integer-id table is unaffected; nothing narrows an id back to `number`.
+
+Every sort, filter, search and page is a **wire param the server answers**
+— there is no client-side row work (rule #1). Table state lives in the
+URL-synced params store. All features below are opt-in props; a bare
+`<ModelTable model={M} title columns />` renders the base table.
+
+```tsx
+<ModelTable<User>
+    model={UserModel}                 // or endpoint="/api/user"
+    title="Users" eyebrow="Account"
+    columns={COLUMNS} filters={FILTERS} presets={PRESETS}
+    defaultSort="-last_activity"
+    defaultParams={{ status__in: 'new,open' }}
+    selectable batchActions={BATCH}
+    columnChooser persistState persistKey="users"
+    exportFormats={['csv', 'json']}
+    exporter={safeExporter}
+    rowTone={(row) => row.priority >= 8 ? 'danger' : null}
+    autoRefresh={30}
+    rowExpand={(u) => <UserExpand u={u} />}
+    {...groupByRecency<User>('last_activity')}
+    onRowClick={(u) => openDetail(u.id)}
+    addLabel="Add User" onAdd={addUser}
+/>
+```
+
+## Columns
+
+`Column<T> = { key, label, sortable?, align?: 'start'|'center'|'end',
+hideable?, render?: (row) => ReactNode }`. `key` is the server field and
+drives the sort param. `render` is the ONE cell prop (no formatter/template
+aliases). `hideable: false` locks a column in the chooser (identity
+columns).
+
+## Filters (see also forms.md dialog types)
+
+`FilterDef` types: `text` (`__icontains`), `select`, `multiselect`
+(collapses to `field__in`), `boolean` (`trueLabel`/`falseLabel`), `number`
+(`__gte`), `daterange` (the `dr_*` triple). Applied filters render as
+editable pills; presets are param bundles with DERIVED active state.
+
+## Selection + batch
+
+`selectable` renders checkboxes independently of `batchActions` (decoupled
+by design). Select-all covers the current page, with an indeterminate
+state. Selection clears when the wire params change (page/sort/filter).
+
+`BatchAction<T>` accepts either `run(row, prepared)` or the mutually exclusive
+`runBatch(rows, prepared)`. Runner semantics: confirm → optional once-per-batch
+`prepare(rows)` (resolve null to cancel; its value is
+passed to every run — e.g. collect ONE disable reason) →
+`Promise.allSettled(rows.map(run))` → toasts `"Label: N item(s) updated"`
+/ `"N succeeded, M failed"` (warning) / `"failed for all N"` → always
+clear selection + invalidate.
+
+`runBatch` executes exactly once for selection-wide operations such as incident
+merge. A rejection produces one actionable error; cancellation mutates
+nothing. Selection clears and the endpoint invalidates after a non-cancelled
+attempt. `rowTone(row)` emits semantic danger/warning queue classes.
+
+## Column chooser + persistState
+
+`columnChooser` adds the Columns dropdown; hidden set is view state, never
+a mutation of your `columns` array. `persistState` remembers sort / size /
+search / filters / hidden columns per table (`persistKey`, else
+route+endpoint) — precedence URL > saved > defaults, saved `size` wins; the
+first fetch waits for the restore so it queries the restored view.
+"Reset to defaults" in the chooser clears the whole saved view.
+
+`defaultParams` supplies route defaults for any query key, including Django
+lookups such as `status__in`. They are part of the same params store as URL and
+persisted values. Precedence is URL > persisted > defaults; `defaultSort`
+remains the backwards-compatible sort shorthand and wins over
+`defaultParams.sort` when both are present.
+
+## autoRefresh
+
+Seconds (5s floor). A plain interval whose tick SKIPS while: tab hidden,
+window blurred, any `<dialog>` open, or a selection is active. No focus
+listeners — `refetchOnWindowFocus` is globally off; the next interval tick
+catches up. The refresh button spins on any fetch and its tooltip shows
+the cadence.
+
+## Row expand / groupBy
+
+`rowExpand(row) => ReactNode` adds the chevron column and a full-width
+detail row; single-open unless `rowExpandMultiple`; page changes collapse
+rows that left the page. `groupBy(row) => string | null` interleaves
+full-width header rows on key change — falsy = ungrouped tail (prior
+section continues); labels via `groupHeaderLabel`; styles
+`banner|mark|band|rule` (unknown → warn + banner). Labels are sticky so
+they stay visible on horizontally-scrolled tables. Use the
+`grouping-and-fmt.md` helpers; align the group field with `defaultSort` or
+headers repeat (that repetition is the defined behavior, not a bug).
+
+## Export
+
+`exportFormats={['csv','json']}` → server-side export of the WHOLE
+filtered set via `download_format` + `filename` (paging stripped).
+`exporter(format, normalizedParams)` overrides that path. It receives the same
+model-normalized params as the visible query, allowing sensitive domains to use
+bounded, immediately sanitized, allowlisted client exports.
+
+## Loading states
+
+Uncached loads (cold, page/sort/filter changes — `isPlaceholderData`)
+render the column-matched skeleton silhouette; cached pages render
+instantly; background refetches never blank the table. Errors render the
+server's message with a Retry. Empty-with-filters offers Clear filters.
+
+## Search
+
+`ExpandingSearch` (exported for reuse): icon at rest → input on focus →
+pinned open while holding text; `/` focuses globally; Escape blurs; 300ms
+debounce, Enter commits immediately.