portal-mojo 0.1.0

package/docs/markdown.md

@@ -0,0 +1,203 @@
+# markdown — server-rendered markdown + the trust model
+
+```tsx
+import { MarkdownView } from 'portal-mojo/ui';
+import {
+    renderMarkdown, peekMarkdown, clearMarkdownCache,
+    sanitizeMarkdownHtml, safeLinkUrl, safeImgUrl,
+    MarkdownFallback, markdownToNodes, markdownToHtml,
+    MARKDOWN_RENDER_ENDPOINT, MAX_MARKDOWN_BYTES, type SanitizeDrop,
+} from 'portal-mojo/client';
+```
+
+django-mojo owns the markdown renderer. The portal asks it instead of
+shipping a second one that drifts from the docs system — and keeps a
+dependency-free client renderer behind it so a missing endpoint, an offline
+tab or a cold first frame still shows the document.
+
+## `<MarkdownView>`
+
+| Prop | Default | Meaning |
+|---|---|---|
+| `source` | — | The markdown text. |
+| `renderer` | `'server'` | `'server'` calls `/api/docit/render` and sanitizes the answer; `'client'` never touches the wire (previews of text being typed; feeds that must not fan out one request per item). |
+| `debounceMs` | `0` | Wait this long after `source` stops changing before calling the server. Set it for text that grows token by token (a streaming assistant reply) so one reply is one request. |
+| `className` | — | Extra classes on the wrapper. `md` is always present. |
+
+Renders one `<div class="md">`. Styling lives in the consuming app —
+`apps/portal/src/theme/markdown.css`, tokens only, both themes; both render
+paths emit the same element set, so one stylesheet dresses both.
+
+### No loading jump, by construction
+
+1. Source already rendered? The module cache answers **synchronously** — the
+   server HTML is on the first frame, no request, no transition.
+2. Otherwise the **client fallback paints immediately** (real content at
+   roughly the right height, `aria-busy`, class `md-pending`), and the server
+   HTML swaps in under the same wrapper when it lands.
+3. If the render fails, the fallback simply stays, with one `console.warn`
+   saying why.
+
+There is no spinner and no empty state at any point. `md-pending` fades in
+after a 250 ms delay, so a fast answer never flickers and a slow one never
+moves.
+
+## Wire contract
+
+`mojo/apps/docit/rest/render.py` — read, not assumed:
+
+```
+POST /api/docit/render     {markdown: string}     @requires_auth
+→ {status: true, code: 200, data: {html: string}}
+```
+
+The handler returns a bare dict, so `mojo/decorators/http.py` wraps it into
+the standard envelope — unwrapped at the **one boundary** (`mojoCall`). Do
+not reintroduce web-mojo's `resp.data.data.html || resp.data.html` sniff; it
+existed in three copies there and is on the do-not-recreate list.
+
+Errors: `400` markdown field is required · `405` non-POST · `413` over
+`MAX_MARKDOWN_BYTES` (400 000 bytes; `renderMarkdown` rejects locally rather
+than spend a round trip on a guaranteed 413).
+
+The server runs mistune with `hard_wrap=True` (a single newline is a `<br>`)
+and `escape=True` (raw HTML in the SOURCE becomes text). Its plugin set adds
+tables, task lists, strikethrough, footnotes, abbr, mark, math, spoiler and
+pygments syntax highlighting.
+
+The mock (`client/mock.ts`) answers the same route with the same envelope and
+the same error codes, running the client parser as its renderer — so mock and
+live differ in fidelity, never in shape. **The mock's HTML goes through the
+sanitizer exactly like a real backend's. There is no trusted lane.**
+
+## THE TRUST MODEL
+
+> **Server HTML is untrusted.** django-mojo escapes raw HTML in the markdown
+> source, but a portal must not be one backend regression away from stored
+> XSS. Nothing is trusted because of where it came from.
+
+Two render paths, two different guarantees:
+
+### Path A — server HTML → `sanitizeMarkdownHtml` → `dangerouslySetInnerHTML`
+
+`MarkdownView` is the **only** sanctioned `dangerouslySetInnerHTML` in
+portal-mojo, and the only string it can ever receive is the return value of
+`renderMarkdown`, which sanitizes *before it resolves*. Unsanitized server
+HTML never leaves `client/markdown.ts`, so no caller can hold it.
+
+The sanitizer (`client/markdown-sanitize.ts`):
+
+1. Parses with `DOMParser('text/html')` — an **inert** document: no script
+   runs, no image loads, no `onerror` fires. (Assigning to a live element's
+   `innerHTML` would already have fetched `<img src=x onerror=…>`.)
+2. Walks the tree. Every element is one of three things:
+   - **allowlisted** → kept, attributes then scrubbed to an allowlist
+   - **dangerous** → removed **with its whole subtree**
+   - **anything else** → **unwrapped**: the element goes, its (already
+     sanitized) children stay. Text is never lost — which is what keeps a
+     pygments `<div class=highlight><span class=k>` block readable after its
+     markup is stripped.
+3. Serializes with the browser's own serializer (`body.innerHTML`).
+
+| | Set |
+|---|---|
+| **Kept** | `p br hr h1-h6 ul ol li strong em del code pre blockquote a img table thead tbody tr th td input mark sup sub` |
+| **Removed with subtree** | `script style iframe object embed applet noscript template link meta base title frame frameset form button select textarea svg math` — plus any element outside the XHTML namespace |
+| **Unwrapped** | everything else (`div span section sup-wrappers …`) |
+| **Attributes kept** | `a[href]`, `img[src alt]`, `input[type checked disabled]`, and `class` — **`md-` prefixed values only** |
+| **Attributes dropped** | every other attribute, which is how `on*` handlers, `style`, `srcset`, `formaction`, `xlink:href`, `id` and `data-*` all go |
+
+Value rules on top of the attribute allowlist:
+
+- `a[href]` — `http:` / `https:` / `mailto:` / `#fragment` only. Rejected
+  hrefs are removed but the **link text stays** (never render nothing).
+  `http(s)` links are rewritten with `target="_blank" rel="noopener noreferrer"`.
+- `img[src]` — `http:` / `https:` only. `data:image/svg+xml` is a script
+  vector, not an image. An image with no usable `src` is dropped entirely.
+- `input` — must be `type=checkbox` (task lists); anything else is a phishing
+  surface and is dropped. `disabled` is forced on, `checked` is preserved.
+- URL vetting **normalizes first, then allowlists**: control and zero-width
+  characters are stripped (that is how `java&#9;script:` is smuggled) and
+  only then is the scheme matched. Unrecognized or scheme-less → dropped.
+
+### Path B — the client fallback → React elements
+
+`MarkdownFallback` / `markdownToNodes` emit React elements directly. No HTML
+string is produced and `innerHTML` is never touched, so there is nothing for
+a sanitizer to do: the only way a `<script>` in the source could become a
+script is if React rendered one, and React only renders the elements that
+file names. Text is escaped by React itself.
+
+**The one thing React does not make safe is URLs** — it will happily render
+`href="javascript:…"`. Both link and image URLs on this path go through the
+*same* `safeLinkUrl` / `safeImgUrl` used by the sanitizer; a rejected link
+degrades to plain text, a rejected image to its alt text.
+
+### Consequences worth knowing
+
+- Server syntax highlighting **survives as text, not colour**: pygments
+  classes are not `md-` prefixed, so they are stripped and the wrappers
+  unwrapped. Shipping a monokai stylesheet would fight both themes.
+- Table alignment from the server is lost (`style="text-align:…"` is an
+  attribute drop).
+- **Relative links and images are dropped** — inside a hash-routed portal
+  they resolve against the current route, which is never what the author
+  meant. Use absolute `https://` URLs in markdown that the portal renders.
+- `mark`, `sup` and `sub` are on the allowlist beyond the base set because
+  the backend's plugin list emits them and all three are inert.
+
+## `renderMarkdown(source)`
+
+Returns the **sanitized** HTML for `source`.
+
+- **REJECTS on any failure** — endpoint missing, offline, 401, oversized
+  body, a response without `html`, no DOM to sanitize with. It never resolves
+  a fallback as success: the fallback path renders React *elements*, so a
+  string could not say which renderer produced it. The fallback decision
+  belongs to the component.
+- **Cached** in a module-level `Map` keyed by an FNV-1a hash of the source
+  plus its length. Every entry stores its source and is verified on hit, so a
+  hash collision costs a re-render, never a wrong document. 200 entries,
+  oldest evicted.
+- **Single-flight**: two mounts of the same message are one request. A chat
+  feed re-rendering 50 cached messages is zero.
+
+`peekMarkdown(source)` reads the cache synchronously (`null` on a miss) —
+that is what lets a cache hit paint on the first frame.
+`clearMarkdownCache()` drops it.
+
+## Files
+
+| File | Job |
+|---|---|
+| `ui/MarkdownView.tsx` | the component; the one `dangerouslySetInnerHTML` |
+| `client/markdown.ts` | the wire call, cache, single-flight, size guard; public re-exports |
+| `client/markdown-sanitize.ts` | the allowlist sanitizer — the security boundary |
+| `client/markdown-parse.ts` | markdown → block AST, plus the HTML emitter the **mock** uses |
+| `client/markdown-fallback.tsx` | AST → React elements (the fallback path) |
+| `apps/portal/src/theme/markdown.css` | `.md` styling, tokens only, both themes |
+
+## Fallback coverage
+
+One parser feeds both the React emitter and the mock's HTML emitter, so what
+you see under the mock is what the fallback renders live: headings,
+paragraphs (hard-wrap `<br>`), `hr`, fenced code, blockquotes, nested and
+task lists, GFM tables (including escaped `\|`), bold/italic/bold-italic
+(`*` and `_`, with `snake_case_words` left alone), inline code,
+strikethrough, links, images, `<autolinks>` and bare URLs.
+
+Server-only, and degrading to their literal text on the fallback path:
+footnotes, math, abbr, spoiler, syntax highlighting.
+
+## Pitfalls
+
+- **Do not add a second `dangerouslySetInnerHTML`.** If you need to show
+  rendered markdown, use `MarkdownView`; if you need to show what the
+  sanitizer produced, show it as text (the playground demo does).
+- **Do not pass user HTML to `MarkdownView`** — pass *markdown*. Raw HTML in
+  the source is escaped to text by both renderers, deliberately.
+- Don't call `renderMarkdown` in a render body; it is a promise. The
+  component already owns the lifecycle.
+- One request per distinct source, not per component: with a streaming
+  source set `debounceMs`, or render `renderer="client"` while it streams and
+  switch to `'server'` once it settles.

package/docs/menus-and-access.md

@@ -0,0 +1,89 @@
+# menus & access — global Admin, product menus, permissions, group context
+
+```ts
+import { registerMenus, setDefaultMenu, SidebarNav, Guarded, RequiresGroup, GroupSwitcher } from 'portal-mojo/ui';
+import { useMe, useCan, useAuthSnapshot, useActiveGroup, GroupProvider, hasPermission, registerPermissionCategories } from 'portal-mojo/client';
+```
+
+## Menu registry + SidebarNav (A4)
+
+Menus are DATA registered once (`registerMenus([...])`); the active menu is
+**derived** from (route, active group, me) — no mutable menu state.
+
+```ts
+registerMenus([
+    { name: 'admin', scope: 'global', presentation: 'accordion', items: [
+        { divider: 'Main' },
+        { id: 'identity', label: 'Identity & Access', icon: 'bi-people', children: [
+            { label: 'Users', route: '/users', permissions: 'view_users' },
+        ]},
+    ]},
+    { name: 'project', scope: 'group', groupKind: 'any', items: [ /* product menu */ ] },
+]);
+setDefaultMenu('admin');
+```
+
+Resolution: route containment in registration order (group menus eligible
+only under a kind-matched active group) → defaultMenu → first non-group
+visible. Items support `permissions` (any-of) ∧ `requiresGroupKind`;
+dividers with no visible children drop; a parent lights when a child route
+is active. `scope: 'admin' | 'group' | 'account' | 'global'` makes ownership
+explicit; legacy `groupKind` menus still infer group scope. Static rendering
+remains the default for compatibility. `presentation: 'accordion'` enables
+searchable, single-open-section navigation. Give accordion parents stable
+`id` values; `keywords` add non-rendered search terms, and
+`permissionClauses` express AND-across / any-within checks when both a section
+and its route have gates.
+
+The standalone Admin app registers one global accordion menu and does not
+mount `GroupProvider` or `GroupSwitcher`. Admin is system-wide: selecting a
+group must never change which Admin pages or grants are visible. A product
+portal owns its group-scoped menus and switcher. When it embeds Admin sections,
+those routes still run inside a global-scope boundary so active-member grants
+cannot satisfy `sys.*` or Admin section permission checks.
+
+Until the identity bundle is fully consolidated, the app-local `/users` and
+`/groups` routes must carry their own system-pinned route and menu clauses in
+addition to nested control gates. A Group opened from `/groups` is inspected
+route data only: it must not call `setActiveGroup`, add `?group=`, or treat an
+active product membership as Admin authority.
+
+`<SidebarNav collapsed onRequestExpand>` provides the compact icon rail.
+Collapsed category buttons expose CSS tooltips and expand on click, Enter, or
+Space. Accordion search matches labels plus `keywords` and reports its result
+count through a live status region.
+
+Admin section bundles contribute through `adminSectionsMenu`. Use
+`{grouped: true, presentation: 'accordion'}` for the domain-grouped Admin
+experience. Routes remain mount-relative; multiple embedded root sections
+share one `/system` landing instead of emitting duplicate index routes.
+
+## Permissions (A2) — client gates, server authority
+
+`Me.permissions` is a dict; truthy `true` OR `1` grants. Semantics
+(`hasPermission`):
+- `is_superuser` → everything.
+- system `admin` → full client-side grant (NOTE: the BACKEND does not
+  honor `admin` as a wildcard — only `is_superuser` and category rollup.
+  The client is deliberately more permissive; the server re-checks).
+- category → granular rollup (`users` grants `view_users`… — one-way);
+  apps extend via `registerPermissionCategories({cat: [perms]})`.
+- `sys.`-prefixed checks never consult the group member.
+- Otherwise the ACTIVE GROUP MEMBER's permissions fold in (member `admin`
+  grants within the group only).
+
+`useCan(permission | permissions[]) → {can, loading}`;
+`<Guarded permission="view_admin" fallback?>…</Guarded>` renders nothing
+(or fallback) without the grant — fail-closed.
+
+## Group context (A3)
+
+Product portals place `<GroupProvider>` at the app root. `useActiveGroup() → {group, member,
+loading, setActiveGroup, clearActiveGroup}`. The active group id rides the
+REAL `?group=` search param (hash-safe, deep-linkable) with localStorage
+fallback; activating a group fetches the caller's member record
+(`/api/group/<id>/member`) whose permissions feed `useCan`.
+`GroupSwitcher` is the searchable tree picker (300ms server search,
+embedded-parent rows, kind chips); `RequiresGroup` wraps pages that need a
+group and shows the pick-a-group state otherwise. Do not install these in the
+standalone Admin shell; they belong to group-scoped product navigation.

package/docs/multiselect-dropdown.md

@@ -0,0 +1,153 @@
+# MultiSelectDropdown — static-options checkbox dropdown
+
+```tsx
+import {
+    MultiSelectDropdown,
+    type MultiSelectOption,
+    type MultiSelectValue,
+} from 'portal-mojo/ui';
+```
+
+A trigger that summarizes the picks over a checkbox menu that **stays open
+while you tick**; `Done` closes it. The static-options sibling of
+[`CollectionMultiSelect`](collection-multiselect.md) (same selection
+contract, but over an `options` array instead of live model data, and folded
+into a dropdown instead of an always-visible panel). Ported from web-mojo
+`src/core/forms/inputs/MultiSelectDropdown.js`.
+
+```tsx
+const [statuses, setStatuses] = useState<MultiSelectValue[]>(['open']);
+
+<MultiSelectDropdown
+    options={[
+        { value: 'new', label: 'New' },
+        { value: 'open', label: 'Open' },
+        { value: 'closed', label: 'Closed', disabled: true },
+    ]}
+    value={statuses}
+    onChange={setStatuses}
+    label="Status"
+    required
+/>
+```
+
+## Props
+
+| Prop | Behavior |
+|---|---|
+| `options` | `Array<string \| MultiSelectOption>`. Bare strings normalize to `{ value: s, label: s }`. Option shape: `{ value: string \| number, label?, text?, disabled? }` — `label` wins, `text` is the source's alias (accepted, don't reach for it), else `String(value)`. An option with no `value` warns and is dropped. |
+| `value` / `onChange` | **Controlled.** `value` takes an array, a bare scalar (coerced to one pick), or `null`/`undefined` (none). `onChange` always receives the full next **array**; every toggle is a commit. Values keep their caller-side types (a numeric `2` comes back as `2`); comparisons are normalized. |
+| `label` / `required` / `help` / `error` | House field chrome (`.field-label` / `.field-help` / `.field-error`; `error` replaces `help`). The label is a `<div id>` the trigger points at with `aria-labelledby` — a `<label htmlFor>` cannot target a button. The trigger references **both** that id and its own, so the accessible name keeps the summary (`"Status, New, Open"`). |
+| `placeholder` | Trigger text while nothing is selected, rendered muted. Default `'Select...'`. |
+| `maxHeight` | px before the option list scrolls. Default 300. |
+| `showSelectedLabels` | Summarize with labels (default true). `false` → always `"N selected"`. |
+| `maxLabelsToShow` | Picks above this switch the trigger to `"N selected"`. Default 3. |
+| `disabled` | Locks the trigger and every row. |
+| `placement` | Menu placement against the trigger — `Popover`'s `PopoverPlacement`. Default `'bottom-start'`. |
+| `id` / `className` | `id` lands on the trigger button; `className` on the field wrapper. |
+
+Not ported: `name` (served only the legacy change-event payload and per-row
+DOM id generation — React callers close over their own field), `getValue` /
+`setValue` / `setOptions` / `clear` / `getFormValue` / `setFormValue` (the
+whole imperative surface is the `value`/`onChange` pair), and `placeHolder`
+(the source accepted both casings; one spelling survives).
+
+## Trigger summarization
+
+```
+0 picks                                     → placeholder, muted
+≤ maxLabelsToShow and showSelectedLabels    → labels, comma-joined
+otherwise                                   → "N selected"
+```
+
+Labels list in **selection order**, not option order (source parity) — the
+summary reads back what the user did. A selected value matching no option
+falls back to its own `String()` form **with a one-time `console.warn`**
+(unknown-value rule) — the trigger never renders a blank slot.
+
+## Menu
+
+- Mounts in the shared [`Popover`](popover.md): portalled to the top layer,
+  so it escapes overflow containers and stacks above open native-`<dialog>`
+  modals. The menu width is measured from the trigger (the source's `w-100`)
+  at open and kept in sync by a `ResizeObserver` while open.
+- The **whole row** is the click target. Toggling never closes the menu —
+  `Done`, Escape, and an outside click do.
+- Per-option `disabled` refuses the toggle by click **and** by keyboard, and
+  arrow navigation skips the row.
+- No options → a single `"No options available"` line and **no Done footer**
+  (source parity); close with Escape or an outside click.
+
+## Keyboard
+
+| Key | Effect |
+|---|---|
+| `Enter` / `Space` / `ArrowDown` on the trigger | Open. Focus moves to the first enabled row — the menu is portalled to the end of `<body>`, so Tab from the trigger could never reach it. |
+| `Tab` | Walks the rows in order, then the `Done` button (every enabled row is `tabIndex=0`, matching `CollectionMultiSelect`). |
+| `ArrowDown` / `ArrowUp` | Move between **enabled** rows, wrapping. |
+| `Home` / `End` | First / last enabled row. |
+| `Space` / `Enter` on a row | Toggle (`preventDefault` — no page scroll). |
+| `Escape` | Closes and returns focus to the trigger. Inside a modal the first Escape closes only the menu (`Popover`'s capture-phase handler). |
+
+`Done` and Escape always hand focus back to the trigger. An outside click
+only does when focus is still parked inside the menu — never fight the
+element the user just clicked.
+
+## Invariants
+
+1. **One value pipeline.** The ROW is the checkbox widget
+   (`role="checkbox"` + `aria-checked`); the `<input type="checkbox">` is
+   display-only — `pointer-events: none`, `readOnly`, `aria-hidden`,
+   `tabIndex={-1}` — and renders straight from `value`. A row click and a
+   keyboard `Space` call the identical `toggle()`. There is no second event
+   source that could move the DOM without moving state.
+2. **Identity never round-trips through DOM attributes.** Toggles close over
+   the option object; every comparison goes through one `String()`
+   normalization (`keyOf`). String and number values, and mixes, work by
+   construction.
+3. `null`/`undefined` are the only "nothing selected" — `0` and `''` are
+   selections.
+4. Both themes, tokens only: `apps/portal/src/theme/multiselect-dropdown.css`
+   (reuses `.tbl-check`, `.btn`, `.field-*`; the popover shell supplies the
+   surface/border/shadow).
+
+## The bug this port kills
+
+web-mojo tracked selection in a private `item.selected` flag driven **only by
+row-click delegation**, then wrote `checkbox.checked` by hand — while each row
+also contained a real focusable `<input type="checkbox">` and a row-wide
+`<label for>`. Any toggle the delegation didn't originate (keyboard `Space`
+on the focused checkbox; the label's synthesized click) moved the DOM without
+moving the tracked selection, or moved it twice. The rendered boxes and the
+value drifted apart, and the drift survived — the view re-rendered from the
+same desynced flags.
+
+Two smaller ones die with it:
+
+- **Numeric values were emitted as strings.** The source read
+  `element.getAttribute('data-value')` (always a string) and pushed *that*
+  into `selectedValues`, then rebuilt rows with
+  `selectedValues.includes(optionValue)` against the raw numbers — so a
+  numeric option ticked once could never be seen as selected again.
+- **Falsy scalars vanished.** The constructor dropped a non-array `value`
+  outright, and `setValue` coerced with a truthy test, so `0` and `''` were
+  silently discarded.
+
+## Pitfalls
+
+- The menu is `position: fixed` in the top layer. Don't try to clip, cover
+  or z-index it from an ancestor — see [popover.md](popover.md).
+- `maxLabelsToShow={0}` is honored (always the count). The source's `|| 3`
+  quietly rewrote a 0.
+- Duplicate values in `value` collapse on the next toggle of that row (the
+  removal filters every copy). Pass a de-duplicated array.
+- Options are static and rendered in the order given — there is no search and
+  no client-side filtering. Reach for `CollectionMultiSelect` once the list is
+  server data or long enough to need search.
+- **Cousin, not yet reconciled:** `FilterBar`'s `multiselect` filter type
+  renders its own checkbox list (`.check-list` / `.check-row`) inside the
+  filter modal, with the same job and a different implementation — see
+  `FilterForm` in `packages/portal-mojo/src/ui/FilterBar.tsx`. Collapsing the
+  two onto this component is a follow-up **decision** (the filter dialog
+  commits on submit, this one commits per toggle), deliberately not attempted
+  here. Change one, look at the other.

package/docs/params.md

@@ -0,0 +1,73 @@
+# params — the table-state store (single source of truth)
+
+```ts
+import {
+    useTableParams, PAGE_SIZES, registerNonFilterParams,
+    readTableState, writeTableState, clearTableState,
+} from 'portal-mojo/client';
+```
+
+**THE architecture rule:** one flat params object owns search, sort,
+filters and paging for a table. It is URL-synced (real search string, hash
+router safe), drives the server query, the pills, preset matching, and
+persistence. Components read it; nothing else holds table state.
+
+## `useTableParams(defaults?) → TableParamsApi`
+
+State: `search`, `sort` (`'field' | '-field' | ''`, default `'-created'`
+unless `defaults.sort`), `page` (1-based), `size`.
+
+`wire` — the params to hand to `mojoList`: `{start, size, sort?, search?,
+...filters}` where `start = (page-1)*size`.
+
+| Method | Semantics |
+|---|---|
+| `setSearch(term)` | writes `search`, resets page 1 |
+| `cycleSort(field)` | asc → desc (`-field`) → off |
+| `setFilter(key, value)` | string \| string[] \| null. Arrays collapse: 1 value → `field=`, 2+ → `field__in=a,b`. A field never carries both forms. null clears |
+| `setDateRange(field, start, end)` | writes the `dr_field/dr_start/dr_end` triple — ONE active range by construction |
+| `removeFilter(f)` / `clearFilters()` | pills & clear-all |
+| `applyPreset(params)` / `presetActive(params)` | mutually-exclusive bundles; active state is DERIVED by matching, never stored |
+| `setPage(n)` / `setSize(n)` | paging (`PAGE_SIZES = [5,10,25,50,100]`) |
+| `applySaved(saved)` | one-shot rehydrate from a persistence blob (below) |
+
+Every write goes through the URL (`replace`), so table state deep-links and
+survives reloads by construction.
+
+## `registerNonFilterParams(...keys)` — params the PAGE owns
+
+Everything in the query string that isn't `search/sort/page/size` is treated
+as a Django lookup. That is deliberate (any `field__lookup=` deep-links with
+no client schema), but it means a **host page's own query param becomes a
+filter**: `#/components?demo=filters` shipped `demo=filters` to
+`/api/group` — zero rows on the mock, `FieldError` on a live backend — and
+kept the "All" preset from ever matching.
+
+Declare such keys once, at module load, before any table renders:
+
+```ts
+registerNonFilterParams('demo');   // the component playground's rail key
+```
+
+Registered keys are excluded from `filters`, `wire` and the pills, and are
+**re-emitted on every write** (each write rebuilds the whole query string,
+so without this they would silently vanish the first time a filter changed).
+Do not register a name that is also a model field.
+
+## Persistence blob (used by ModelTable's `persistState`)
+
+`readTableState/writeTableState/clearTableState(key)` store
+`{v: 2, sort?, size?, search?, filters?, hidden?}` at
+`localStorage["mojo:tableview:" + key]`.
+
+Precedence on restore: **URL > saved > defaults** per key — except `size`,
+a per-user viewing preference the URL merely echoes, where **saved wins**.
+Corrupt or other-version blobs are discarded AND cleared. `sort: ''`
+(deliberately un-sorted) is not persisted — the default sort returns.
+
+## Pitfalls
+
+- Values are strings on the wire — booleans as `'true'/'false'`.
+- Never mutate `wire`; it's derived.
+- Don't store table state anywhere else (component state, context, redux
+  patterns) — that's the exact drift this store exists to prevent.

package/docs/popover.md

@@ -0,0 +1,130 @@
+# Popover — the anchored top-layer primitive
+
+```ts
+import { Popover, type PopoverPlacement, type PopoverCloseReason } from 'portal-mojo/ui';
+```
+
+The shared surface every dropdown-style control mounts in — date/time
+pickers, autocomplete, multi-selects, kebab menus. Ported from web-mojo's
+`CalendarPopover.js`. Portal-mounted so it escapes overflow/clipping
+containers; anchor-positioned; closes on outside-mousedown and Escape;
+repositions on any scroll (capture phase), resize, and anchor/content
+size change.
+
+```tsx
+const btnRef = useRef<HTMLButtonElement>(null);
+const [open, setOpen] = useState(false);
+
+<button ref={btnRef} onClick={() => setOpen(v => !v)}>Pick…</button>
+<Popover anchorRef={btnRef} open={open} onClose={() => setOpen(false)}>
+    {/* content brings its own padding/width — the shell is bare */}
+</Popover>
+```
+
+## API
+
+| Prop | Type | Notes |
+|---|---|---|
+| `anchorRef` | `RefObject<HTMLElement \| null>` | Trigger element. Re-read on every reposition — swap `.current` to re-point the popover (one instance can serve many triggers). |
+| `open` | `boolean` | Controlled. The popover never closes itself. |
+| `onClose` | `(reason: 'outside' \| 'escape') => void` | Flip `open` false here. The reason lets pickers commit-on-outside vs revert-on-escape. |
+| `placement?` | `'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end'` | Default `bottom-start`. Unknown values fall back to the default WITH a `console.warn`. |
+| `gap?` | `number` | px between anchor and popover, default 6. |
+| …rest | `HTMLAttributes<HTMLDivElement>` | Spread onto the shell (`id`, `aria-*`, `style`, …). `role` defaults to `"dialog"`, overridable. `className` merges after `mojo-popover`. |
+
+Children are `ReactNode` (never HTML strings — house rule). There is no
+imperative reposition handle: layout effects + capture-phase scroll +
+resize + `ResizeObserver` (on both popover and anchor) cover every
+reposition trigger, including async content growth.
+
+The source's `portal: false` inline mode is deliberately not an option:
+in React, "inline" is just rendering the content where you want it (an
+inline calendar renders `<Calendar/>` directly). `Popover` exists only
+for the anchored, floating case.
+
+## The dialog problem (why this is not a z-indexed div)
+
+portal-mojo modals are native `<dialog showModal>` — members of the
+browser **top layer**, which paints above the whole document regardless of
+z-index. A body-portaled `z-index: 10000` div (web-mojo's approach)
+renders UNDER an open modal, so a picker inside a modal form would be
+invisible.
+
+**Decision:** the popover joins the top layer itself via the HTML Popover
+API — the shell carries `popover="manual"` and is shown with
+`showPopover()`. Top-layer members paint in promotion order, so a popover
+opened after the modal stacks above it. `manual` (never `auto`) opts out
+of UA light-dismiss: close behavior stays this component's own
+outside-mousedown + Escape, identical semantics to the web-mojo source.
+
+**Fallback** (browsers without the API — pre-2024): a plain portaled div.
+When the anchor sits inside an open `<dialog>`, the portal target becomes
+that dialog instead of `document.body` — a descendant paints with its
+top-layer host, and `position: fixed` children are not clipped by ancestor
+overflow — so pickers-in-modals still work there too.
+
+## Positioning contract
+
+- The shell is `position: fixed` in both paths; all math is
+  **viewport-relative** (deliberate translation from the source's
+  `absolute` + `scrollX/Y` — the top layer does not scroll with the page,
+  so page coordinates would be wrong there).
+- Placement math, then a horizontal viewport clamp (8px inset), then a
+  vertical flip: any placement that would overflow the bottom flips above
+  the anchor when there is room — the source's exact rule.
+- Reposition triggers: open, placement/gap change, any capture-phase
+  scroll, window resize, popover or anchor resize.
+
+## Focus
+
+Opening NEVER moves focus — `showPopover()` only focuses `autofocus`
+content, and the shell has none. Typing in an anchored input keeps
+working (the autocomplete precondition). Keeping input focus while
+clicking options (`preventDefault` on option `mousedown`) is the
+consuming control's job, not the shell's.
+
+## Escape layering
+
+The Escape listener runs in the **capture phase** and calls
+`preventDefault()` + `stopPropagation()`: with the anchor inside an open
+modal, the first Escape closes only the popover (preventing the dialog's
+cancel), the second closes the modal. (Deviation from source, which
+predates native `<dialog>`: it neither prevented nor stopped — carrying
+that here would close both layers on one keypress.)
+
+Outside-mousedown does NOT stop propagation: the click still activates
+whatever was under it (click a second trigger → this popover closes and
+that one opens). Clicks on the anchor are never "outside" — the anchor's
+own click handler owns its toggle. The listener attach is deferred one
+tick so the interaction that opened the popover can't immediately close
+it (source parity).
+
+## Styling
+
+`.mojo-popover` lives in `apps/portal/src/theme/popover.css` — tokens
+only, both themes. It neutralizes the UA `[popover]` stylesheet
+(`inset: 0` centering, `margin: auto`, border, padding, Canvas colors)
+and restores the mission-control look (`.filter-menu` family: `--surface`
+bg, `--line` border, radius 10, `--shadow-pop`).
+
+The shell is **unpadded and unsized** (`width: max-content`): content
+brings its own padding, width, and scrolling. (The web-mojo source shell
+baked in 20px padding + 260px min-width for its one tenant, the calendar
+— the calendar port carries those itself.)
+
+## Pitfalls
+
+- **Don't wrap the shell in `overflow: hidden` styling assumptions** —
+  it's in the top layer; nothing ancestral clips or covers it. Anything
+  that must paint ABOVE an open popover has to join the top layer later.
+- **Toasts render under open modals** (`.toast-host` is z-index 60, not
+  top layer). Don't signal from popover content inside a modal via toast;
+  show it in the modal body.
+- **One value pipeline:** the popover is presentation only. Commit
+  semantics (`change` on select/Enter/blur, never per keystroke) belong
+  to the consuming control.
+- The opening interaction can be `click` or `mousedown`-driven; both are
+  safe. But if you open programmatically and simultaneously flip other
+  document state, remember listeners attach a tick later.
+- Placement flips only bottom→top (per source). If content can be taller
+  than the viewport, cap and scroll it in YOUR content styles.