portal-mojo 0.2.5 → 0.2.7

package/README.md

@@ -23,8 +23,8 @@ additional exports are required.
 |---|---|
 | `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/client/runtime` | Stable, narrow client boundary for first-party application runtime code. It omits eager mock-test controls; the mock transport itself loads on the first mock request. |
-| `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/ui/shell` | Stable, narrow boundary for application-shell primitives: theme, guards, menus/sidebar, right panel, modal/toast hosts, password helpers, and formatters. |
+| `portal-mojo/ui` | Mission-control UI: `ModelTable`, `FilterBar`/`FilterPills`, `SchemaForm`/`formModal`, `DetailView`, `RecordFeed`, `AttachmentQueue`/`UploadQueue`, `ImageEditor`/`imageEditorModal`, awaitable native-`<dialog>` `modal`, `toast`, `ThemeProvider`, `UserMenu` (top-nav account menu), `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/ui/shell` | Stable, narrow boundary for application-shell primitives: theme, guards, menus/sidebar, right panel, account menu (`UserMenu`), modal/toast hosts, password helpers, and formatters. |
 | `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/core` | Side-effect-light Admin contracts and host: `AdminSection`, the discriminated `AdminRoute` XOR, `adminSectionRoutes`, `adminSectionsMenu`, and `AdminLazyPage`. |
 | `portal-mojo/admin/registry` | Stable, narrow built-in `ADMIN_SECTIONS` roster for first-party hosts, without broad page barrels. It installs the optional Email→DNS adapter synchronously so communications routes work before DNS navigation. |

package/docs/README.md

@@ -51,6 +51,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [image-editor.md](image-editor.md) | Full-resolution crop/transform/filter composition, bounded history, PNG Blob results, modal helper, and ImageField pre-upload editing |
 | [loading.md](loading.md) | `Spinner`, `busy()`/`busyWhile()` blocking overlay, `ViewLoader`, `InlineLoader`, `Busy` — the anti-flash delay rule and skeleton-vs-loader guidance |
 | [popover.md](popover.md) | Anchored top-layer popover shell — placement, reposition, outside/Escape close, the dialog stacking story |
+| [user-menu.md](user-menu.md) | Top-nav account menu — avatar trigger, identity header, theme control, app items, pending Sign out, signed-out matrix, keyboard map |
 | [taginput.md](taginput.md) | Chip/tag entry — CSV wire shape, keyboard matrix, validation + inline errors |
 | [combobox.md](combobox.md) | The house autocomplete — options with descriptions/meta, commit-only change pipeline, allowCustom, ARIA |
 | [location-address.md](location-address.md) | Six-endpoint LocationClient, private provider sessions, stale guards, controlled AddressField, atomic form patching |

package/docs/admin-identity-directories-sources.json

@@ -0,0 +1,130 @@
+{
+  "package": "portal-mojo",
+  "package_version": "0.2.5",
+  "source_repository": "https://github.com/NativeMojo/portal-mojo",
+  "source_tag": "v0.2.5",
+  "source_commit": "93c7fdfeb3096d33010e72bd4483cf9ca6e3d6f5",
+  "license": "Apache-2.0",
+  "license_file": "packages/portal-mojo/LICENSE",
+  "files": [
+    {
+      "source_path": "apps/portal/src/group-permissions.ts",
+      "source_sha256": "6237ad45328ecb9637a1a07d8954dd27cd019e22fa32942f5e7d05a76037fb5c",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-permissions.ts",
+      "package_sha256": "b909f5a5cf029b8b910a70e6817fea8abd9ded6797af14a16170b2695c0c1699",
+      "adaptation": "Moves system-pinned group permission clauses into the canonical package identity surface."
+    },
+    {
+      "source_path": "apps/portal/src/models.ts",
+      "source_sha256": "0b98a906a774e572f9109703fe22444c3a2e190ca5e02c3a93dfbd02cc3fcb84",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/models.ts",
+      "package_sha256": "6ac12a64d00e409874bc1b13d7941cf54c38a715af5ebcfddd2b2e9257356759",
+      "adaptation": "Extracts the Group model/type and group kind options; shared User, Member and Log models remain owned by their package domains."
+    },
+    {
+      "source_path": "apps/portal/src/pages/ApiKeysPage.tsx",
+      "source_sha256": "3d338cf77c3110b72a9361565c1cced10a7fccc52c486e3dafda119d66c676b2",
+      "package_path": "packages/portal-mojo/src/admin/identity/users/PersonalApiKeysPage.tsx",
+      "package_sha256": "f377d8a97b5c0ccbce745c333fdd7e4a5fd5f5a89b868b058677b31e3efe64ff",
+      "adaptation": "Expanded row facts and actions are presented in a native DetailView modal that observes the current API key record."
+    },
+    {
+      "source_path": "apps/portal/src/pages/GroupDetail.tsx",
+      "source_sha256": "01a8a6032a59a337636ec28e5e2aef90717e5bc00656807135e02820a92a394b",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/GroupDetail.tsx",
+      "package_sha256": "e26943218e3e8f5ac79ddc7f1b0bd40736bcab0bd6e9c694e01830086349a4e2",
+      "adaptation": "Raw metadata is visible in the explicit Metadata section without a collapsible control."
+    },
+    {
+      "source_path": "apps/portal/src/pages/GroupsPage.tsx",
+      "source_sha256": "82e4aa5e7ebf67832bbd3bcf7e15dcfdeea64383039cc426591fa15262e4d4c8",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/GroupsPage.tsx",
+      "package_sha256": "e16f3d0630fdb1937cf667cd2abe8cd1aabc9bb2b731113112930e66bde2f1df",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/AuditSection.tsx",
+      "source_sha256": "49848f57e5050c0008aa83f7092af9abb8f55d262791a2591e525eaa6d741df4",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/AuditSection.tsx",
+      "package_sha256": "07a40636549a0a1d8636a115ee330313b84c0c82500890c6464301fd39de1e06",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/AuthConfigDialog.tsx",
+      "source_sha256": "f42e18a802f206a2b3f30248c30ad12887598b170deb73b532232a6bf89699dd",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/AuthConfigDialog.tsx",
+      "package_sha256": "e2280185bde7eab3ca7108f7d6da9e0e66c4f4d8323ec97f3fd7d49376932b65",
+      "adaptation": "Raw auth overrides remain visible in the explicit configuration dialog without collapsible content."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/EventsSection.tsx",
+      "source_sha256": "b8cb12ae99d7c8d5931a090b7be8ea4e0373ff4657e786094e9ac862167d43ec",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/EventsSection.tsx",
+      "package_sha256": "f0004605fbf7ceb2704adb42c0a3dd14dc5a468c445f0f94f2548fbc5f1bfeb4",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/GeofenceSection.tsx",
+      "source_sha256": "d0ce22f5ef922371d7a78c353e1a29e5d9ca4932e45814499e9c3cdeda7dc137",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/GeofenceSection.tsx",
+      "package_sha256": "227850a8ef844867ea55d599997144b462ee058967224c361dd821713d1b677a",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/IdentitySection.tsx",
+      "source_sha256": "cda776a26f1e21b73820ed88ab7dcbafdaf2b146c4c3ee4bf6b24dcbaeecc9f4",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/IdentitySection.tsx",
+      "package_sha256": "888ff5f7a70c80d8a868f13675b39af9a2a7076d6ea5fbc323493c0265ce9880",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/MembersSection.tsx",
+      "source_sha256": "dc2e99924b8ba856ce2ed48dffae082e98cac9ef78df3ddb1f05fe8a71f9725d",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/MembersSection.tsx",
+      "package_sha256": "abccb58bcdb62d0d1de2611cad080ca7237e0dfa781b10c5fc1d7e251398f628",
+      "adaptation": "Passes the group navigation callback into UserDetail to keep cross-record navigation available."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/OverviewSection.tsx",
+      "source_sha256": "fb395569018b89e6efd45cea241ba665b73efd15549802a6f0d98d90116ce894",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/OverviewSection.tsx",
+      "package_sha256": "08b460272af71ba6209fe388b71f37f79d94a9fecc21c0c2ee3abaf11f01372f",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/SubGroupsSection.tsx",
+      "source_sha256": "81074a2d74d80fda93e40379b87620807c31db7979736f90559e359bdafc0672",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/SubGroupsSection.tsx",
+      "package_sha256": "61e412e709afb4384fdcbaa1d8fbb6df6ba414634ecc6aaa8201c66cf722af93",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/auth-config.ts",
+      "source_sha256": "37d75dff84bca2577bcd1804c77aa0ef1519e4d913dcfdf7914266045fdbabe6",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/auth-config.ts",
+      "package_sha256": "37d75dff84bca2577bcd1804c77aa0ef1519e4d913dcfdf7914266045fdbabe6",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/geofence-data.ts",
+      "source_sha256": "169d5feb72fbe16a0463d591328ce49963e95f1bc0f5f7e5fa9ed271a5ace8e6",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/geofence-data.ts",
+      "package_sha256": "169d5feb72fbe16a0463d591328ce49963e95f1bc0f5f7e5fa9ed271a5ace8e6",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/models.ts",
+      "source_sha256": "ec6a2fd700a0a91e8f1d9e49c364ffe5466db340b435004971e719da08b49371",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/models.ts",
+      "package_sha256": "ec6a2fd700a0a91e8f1d9e49c364ffe5466db340b435004971e719da08b49371",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    },
+    {
+      "source_path": "apps/portal/src/pages/group-sections/shared.ts",
+      "source_sha256": "68aa819b14edcbbd8ae399d5c5a74360cc50ffd281b6d0d3be1c4f8ebc4e4f6c",
+      "package_path": "packages/portal-mojo/src/admin/identity/groups/group-sections/shared.ts",
+      "package_sha256": "68aa819b14edcbbd8ae399d5c5a74360cc50ffd281b6d0d3be1c4f8ebc4e4f6c",
+      "adaptation": "Moved into the package identity domain and updated package-relative imports."
+    }
+  ]
+}

package/docs/admin-identity-directories.md

@@ -0,0 +1,60 @@
+# Admin Groups and Personal API Keys
+
+The global Admin registry contributes Groups and Personal API Keys to the
+Identity & Access navigation group. `adminSectionRoutes()` and
+`adminSectionsMenu()` therefore mount the same pages in the standalone
+reference portal and in an embedded System Admin boundary:
+
+```tsx
+import {
+  GROUPS_ADMIN_SECTION,
+  GROUP_VIEW_PERMS,
+  GroupDetail,
+  GroupModel,
+  GroupsPage,
+  PERSONAL_API_KEYS_ADMIN_SECTION,
+  PersonalApiKeysPage,
+} from 'portal-mojo/admin/identity';
+```
+
+The registered routes are `/groups` and `/apikeys`; an embedded mount prefixes
+both routes. Group directory and detail access use the system-pinned
+`sys.groups | sys.view_groups` clause. Group mutations use
+`sys.groups | sys.manage_groups`. Active-group membership cannot satisfy
+these gates. The personal key section uses the system identity-view clause,
+while its API requests remain scoped to the signed-in user's own keys.
+
+## Groups
+
+`GroupsPage` retains the native server-owned `ModelTable` search, filters,
+presets, paging, sorting, column chooser, persistence and exports against
+`GET /api/group`. Opening a row presents `GroupDetail` in `modal.detail`.
+`GroupDetail` preserves the Overview, Identity, Members, Sub-Groups, API Keys,
+Webhooks, Geofencing, Events, Audit and Metadata surfaces, with each section's
+existing system permission gate and conditional queries. Parent, child, member
+and user navigation opens native detail modals while keeping the directory
+underneath.
+
+The group model and section code are adapted from the reference portal at
+`v0.2.5` commit `93c7fdfeb3096d33010e72bd4483cf9ca6e3d6f5`. The source hashes
+and corresponding package hashes are recorded in
+[`admin-identity-directories-sources.json`](admin-identity-directories-sources.json).
+The moved implementation retains the package Apache-2.0 license. Two raw JSON
+surfaces render their values directly in their explicit Metadata/Auth details;
+they do not use collapsible content.
+
+## Personal API Keys
+
+`PersonalApiKeysPage` uses the existing `ApiKeyModel` at
+`/api/account/api_keys` and the caller-only generation mutation at
+`/api/auth/generate_api_key`. The generated token is shown once and scrubbed
+before it can reach the query or mutation cache. Key facts and actions open in
+a native detail modal. Disable/enable remains reversible with an undo toast;
+revoke remains armed because it rotates the secret and cannot be undone. There
+is no delete action. This page does not use the separate group credential
+endpoint.
+
+The Personal API Keys route was added to the package identity section registry
+alongside Users, Members, Groups, Credentials and Sign-in. Compatibility page
+paths in the reference app re-export the package-owned pages, and its menu and
+route composition do not inject duplicate directory entries.

package/docs/admin-identity-users.md

@@ -25,7 +25,12 @@ reason per batch; rows already in the target state are ineligible.
 
 The detail preserves all 14 sections: Overview, Profile, Personal, Security,
 OAuth, Groups, Sys Perms, conditional App Perms, API Keys, Devices, Logins,
-Audit, Notifications, and Metadata. Subsidiary count/list queries are enabled
+Audit, Notifications, and Metadata. Permission sections are labeled **System
+permissions** and **Product permissions** in the UI. Consuming apps install
+their product tabs with `registerFormTabs(USER_APP_PERMS_TABSET, tabs)`; the
+section stays absent when none are registered. User grants can cover multiple
+groups; use a Member product permission for a single group.
+Subsidiary count/list queries are enabled
 only when their exact system permission is present. Logs use
 `sys.view_logs | sys.manage_logs | sys.security`; incident events use
 `sys.view_security | sys.security`. Permission revocation therefore removes

package/docs/admin-members.md

@@ -12,6 +12,7 @@ import {
   MEMBERS_ADMIN_SECTION,
   openMemberAdmissionDialog,
   registerMemberPermissions,
+  MEMBER_APP_PERMS_TABSET,
 } from 'portal-mojo/admin';
 ```
 
@@ -103,6 +104,16 @@ and read-only rather than disappearing. Permission switches autosave through
 `FormView`; a deployment's `MEMBER_PERMS_PROTECTION` remains authoritative,
 and rejected changes revert with the server error shown.
 
+For a larger product catalog, also register native `FormView` tabs under
+`MEMBER_APP_PERMS_TABSET` with `registerFormTabs` from `portal-mojo/ui`.
+Use dotted `permissions.<grant>` fields and retain the corresponding
+`registerMemberPermissions` definitions. A separate **Product permissions**
+detail section appears when this tabset is populated. Fields covered by those
+tabs leave the ordinary **Permissions** section, so each grant has one editor.
+Both forms save the same membership row with the same gates, partial-dict
+merge, escalation confirmation and rejection handling. The tabset creates no
+new grant semantics: the backend still decides what each key authorizes.
+
 ## Composition
 
 `MEMBERS_ADMIN_SECTION` is root-relative and dual-mounts as `/members` in the
@@ -110,3 +121,8 @@ standalone Admin and `/system/members` when embedded. It never consumes active
 group context. `GroupMembersPanel` is the reusable Group-detail composition;
 pass optional `onNavigateUser` and `onNavigateGroup` callbacks to connect
 sibling identity details without coupling the package to an app.
+
+Member product tabs only render `permissions.<grant>` fields whose grant is
+registered through `registerMemberPermissions()` and editable. System/derived
+grants, unregistered names and unrelated fields (such as `group` or `user`)
+are ignored; tabs with no valid fields do not appear.

package/docs/admin-network-security.md

@@ -163,7 +163,7 @@ flag is detected, `true` REQUIRES the flag (rare), absent/`null` means don't
 care.
 
 `geofence-data.ts` is the ONE definition of the lossy projection between that
-DSL and the friendly form. `apps/portal/src/pages/group-sections/geofence-data.ts`
+DSL and the friendly form. `packages/portal-mojo/src/admin/identity/groups/group-sections/geofence-data.ts`
 is a re-export shim over it, so the platform page and the group panel cannot
 drift. `GeofenceRuleEditor` is the ONE editor both render.
 

package/docs/menus-and-access.md

@@ -26,8 +26,10 @@ 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
+dividers with no visible children drop. Only the destination row is selected;
+an accordion parent is a neutral disclosure control and opens for its active
+child. `exact: true` end-matches both the visual selection and `aria-current`.
+`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
@@ -57,6 +59,8 @@ 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.
+Generated Admin destinations are exact matched, so an embedded mount’s root
+Dashboard cannot remain selected on every nested page.
 
 Import the route/menu machinery from `portal-mojo/admin/core`, then import only
 the registry domains the shell installs. The stable domains are `identity`,

package/docs/user-menu.md

@@ -0,0 +1,131 @@
+# UserMenu — the top-nav account menu
+
+```ts
+import { UserMenu, type UserMenuItem } from 'portal-mojo/ui';
+// also on the narrow shell boundary:
+import { UserMenu, type UserMenuItem } from 'portal-mojo/ui/shell';
+```
+
+The shared identity menu for every django-mojo portal's top bar — replaces
+hand-rolled "user chips" and the separate theme-cycle button. Ported from
+web-mojo's TopNav user dropdown (`src/core/views/navigation/TopNav.js`:
+avatar-or-icon trigger, end-aligned dropdown, divider rows) and
+`PortalApp._injectThemeToggleItems` (theme choice sits just above the
+trailing logout); the theme dialog becomes an inline Light/Dark/System
+segmented control.
+
+```tsx
+<header className="topnav">
+    <h2 className="topnav-title">Dashboard</h2>
+    <div className="topnav-right">
+        <UserMenu
+            authMode="inapp"
+            items={[
+                { label: 'My profile', icon: 'bi-person', to: '/profile' },
+                { label: 'Leave organization', icon: 'bi-box-arrow-left', danger: true, divider: true, onSelect: leave },
+            ]}
+            onSignOut={async () => { await revokeServerSession(); logout(); }}
+        />
+    </div>
+</header>
+```
+
+Live demo: showcase → Components → Overlays → **UserMenu**.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `items?` | `UserMenuItem[]` | App entries, rendered between the theme control and Sign out. |
+| `children?` | `ReactNode` | Rendered after `items`, above Sign out. Elements with `role="menuitem"` (and `tabIndex={-1}`, class `user-menu-item` for the look) join arrow-key navigation, and clicking one closes the menu. |
+| `authMode?` | `'inapp' \| 'hosted'` | Signed-out affordance (see matrix). The app knows its mode — the toolkit never imports app config. Unknown values warn once and render the signed-out chip. |
+| `onSignOut?` | `() => void \| Promise<void>` | Replaces the default `logout()`. Sign out shows a pending state ("Signing out…", spinner, `aria-busy`) until it settles; repeat clicks are ignored. A rejection toasts `Sign out failed: <message>` and leaves the menu open for a retry. |
+| `size?` | `'sm' \| 'md'` | Trigger density: 24px vs 28px avatar. Default `md`; unknown values warn once and fall back. |
+| `className?` | `string` | Appended to the trigger (or the signed-out element). |
+
+```ts
+interface UserMenuItem {
+    label: string;
+    icon?: string;          // bootstrap-icons class, e.g. 'bi-person'
+    to?: string;            // react-router <Link> destination
+    onSelect?: () => void;  // runs after the menu closes (also for `to` items)
+    danger?: boolean;       // danger tone
+    divider?: boolean;      // separator line ABOVE this item
+}
+```
+
+`divider` is a flag on the following item, not a standalone row (web-mojo's
+`{divider: true}` rows map to `divider: true` on the next entry).
+
+## Anatomy
+
+- **Trigger** — `<button>` with avatar (image, or `fmt.initials(name)` while
+  loading / without one / after an image error), display name, caret.
+  `aria-haspopup="menu"`, `aria-expanded`, `aria-controls` (while open), and
+  `aria-label="Account menu: <name>"` so the avatar-only phone trigger keeps
+  an accessible name. Under **720px** the name and caret hide.
+- **Popover** (`placement="bottom-end"`, 280px, clamped to the viewport):
+  identity header (42px avatar, name, email, `is_superuser` → "System admin"
+  chip), then the `role="menu"` list: Theme (three `menuitemradio`s wired to
+  `useTheme().setPref`), items, children, Sign out (danger tone).
+- Name = `me.display_name || me.email || token email || '…'`.
+
+## Wire contract
+
+- Identity: `useMe()` → `GET /api/user/me` (cache key `['me', uid]`, the row
+  is sanitized so `avatar` is `{id} | null`).
+- Avatar: when `me.avatar?.id` is set, `mojoCall('/api/fileman/file/<id>')`
+  runs **only while mounted** (AbortController on unmount/id change; failures
+  silent). The image is `thumbnail ?? url`, each through `safePreviewUrl`
+  (`ui/safe-url.ts`, shared with FileField): same-origin `/paths` or
+  credential-free `http(s)` only.
+- Sign out: `onSignOut()` or `logout()` (client-side; django-mojo has no
+  logout endpoint).
+
+## Invariants
+
+- The avatar URL is a **capability**: it lives in component state only and
+  is never written into any Query cache (the `me` cache holds `{id}` by
+  design). A previous identity's image can never render for the next
+  (state is keyed by avatar id).
+- No avatar request while signed out or when `avatar` is null.
+- Popover is controlled; outside-mousedown closes without moving focus.
+- Tokens only — `apps/portal/src/theme/user-menu.css`; both themes from the
+  token swap. Reuses `.seg`/`.seg-btn`, `.chip-primary`, `.spin`,
+  `.btn-primary`/`.btn-compact`, `.chip-muted`.
+
+## Signed-out matrix
+
+`useAuthSnapshot().authenticated === false` renders no menu:
+
+| `authMode` | Renders |
+|---|---|
+| `'inapp'` | `<Link to="/auth/login">` Sign in button |
+| `'hosted'` and `hostedAuthUrl()` resolves | Sign in button → `redirectToHostedAuth()` |
+| `'hosted'` with no API origin, or omitted | muted "Signed out" chip |
+
+## Keyboard
+
+| Where | Key | Effect |
+|---|---|---|
+| Trigger | Enter / Space / click | Toggle; on open focus the first item |
+| Trigger | ↓ / ↑ | Open (or enter the open menu) on the first / last item |
+| Menu | ↓ / ↑ | Next / previous item (wraps; includes the theme radios) |
+| Menu | Home / End | First / last item |
+| Theme control | ← / → | Previous / next theme option (wraps) |
+| Menu | Enter / Space | Activate (Space also activates `to` links) |
+| Menu | Escape | Close, focus back to the trigger (first Escape only closes the menu inside a modal) |
+| Menu | Tab / Shift+Tab | Close; focus continues from the trigger |
+
+Selecting an item or a `role="menuitem"` child closes the menu and returns
+focus to the trigger before `onSelect` runs (so dialogs opened from
+`onSelect` restore focus to a live element). A successful Sign out closes the
+menu. Theme picks apply immediately and keep the menu open.
+
+## Pitfalls
+
+- Needs a router context (items with `to`, and the in-app Sign in link) and
+  `ThemeProvider` for the theme control; `ToastHost` for the failure toast.
+- Don't also render a theme toggle button in the same bar — the menu owns it.
+- `onSignOut` that never settles leaves Sign out pending; resolve or reject.
+- Apps must ship `theme/user-menu.css` (the package ships no CSS).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.5",
+    "version": "0.2.7",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/admin/core/index.ts

@@ -207,8 +207,8 @@ export function adminSectionsMenu(sections: readonly AdminSection[], opts: {
             const labeled = section.routes.filter((route) => route.label);
             const destinations: MenuItem[] = labeled.length > 0 ? labeled.map((route) => ({
                 id: `admin:${section.id}:${route.path || 'index'}`, label: route.label!, keywords: [section.title],
-                route: absolutePath(base, route.path), permissionClauses: [section.permissions, ...(route.permissions ? [route.permissions] : [])],
-            })) : [{ id: `admin:${section.id}`, label: section.title, keywords: [section.title], route: absolutePath(base), permissionClauses: [section.permissions] }];
+                route: absolutePath(base, route.path), exact: true, permissionClauses: [section.permissions, ...(route.permissions ? [route.permissions] : [])],
+            })) : [{ id: `admin:${section.id}`, label: section.title, keywords: [section.title], route: absolutePath(base), exact: true, permissionClauses: [section.permissions] }];
             if (section.navigationGroup === null) {
                 items.push(...destinations.map((destination) => ({ ...destination, icon: section.icon })));
                 continue;
@@ -227,8 +227,8 @@ export function adminSectionsMenu(sections: readonly AdminSection[], opts: {
         const base = relativePath(mount, section.basePath ?? section.id);
         items.push({
             label: section.title, icon: section.icon, permissions: section.permissions,
-            ...(base ? { route: absolutePath(base) } : {}),
-            children: labeled.map((route) => ({ label: route.label!, route: absolutePath(base, route.path), permissions: route.permissions })),
+            ...(base ? { route: absolutePath(base), exact: true } : {}),
+            children: labeled.map((route) => ({ label: route.label!, route: absolutePath(base, route.path), exact: true, permissions: route.permissions })),
         });
     }
     return { name: opts.name ?? 'admin', scope: 'admin', presentation: opts.presentation ?? 'static', items };

package/src/admin/domains/identity.ts

@@ -3,6 +3,7 @@ import { GLOBAL_CREDENTIAL_PERMS } from '../credentials/models';
 import { MEMBER_READ_PERMISSIONS } from '../identity/members/models';
 import { USER_VIEW_PERMISSIONS } from '../identity/users/models';
 import { SIGNIN_ADMIN_PERMISSIONS } from '../signin/api';
+import { GROUP_VIEW_PERMS } from '../identity/groups/group-permissions';
 
 export const USERS_ADMIN_SECTION: AdminSection = {
     id: 'users', basePath: '', title: 'Users', icon: 'bi-people', navigationGroup: 'identity-access', permissions: USER_VIEW_PERMISSIONS,
@@ -27,4 +28,21 @@ export const SIGNIN_ADMIN_SECTION: AdminSection = {
     routes: [{ path: '', loadComponent: () => import('../signin/SigninPage').then(({ SigninPage }) => ({ default: SigninPage })), permissions: SIGNIN_ADMIN_PERMISSIONS }],
 };
 
-export const IDENTITY_ADMIN_SECTIONS = [USERS_ADMIN_SECTION, MEMBERS_ADMIN_SECTION, CREDENTIALS_ADMIN_SECTION, SIGNIN_ADMIN_SECTION] as const;
+export const GROUPS_ADMIN_SECTION: AdminSection = {
+    id: 'groups', basePath: '', title: 'Groups', icon: 'bi-diagram-3', navigationGroup: 'identity-access', permissions: GROUP_VIEW_PERMS,
+    routes: [{ path: 'groups', label: 'Groups', loadComponent: () => import('../identity/groups/GroupsPage').then(({ GroupsPage }) => ({ default: GroupsPage })), permissions: GROUP_VIEW_PERMS }],
+};
+
+export const PERSONAL_API_KEYS_ADMIN_SECTION: AdminSection = {
+    id: 'personal-api-keys', basePath: '', title: 'Personal API Keys', icon: 'bi-key', navigationGroup: 'identity-access', permissions: USER_VIEW_PERMISSIONS,
+    routes: [{ path: 'apikeys', label: 'Personal API Keys', loadComponent: () => import('../identity/users/PersonalApiKeysPage').then(({ PersonalApiKeysPage }) => ({ default: PersonalApiKeysPage })) }],
+};
+
+export const IDENTITY_ADMIN_SECTIONS = [
+    GROUPS_ADMIN_SECTION,
+    PERSONAL_API_KEYS_ADMIN_SECTION,
+    USERS_ADMIN_SECTION,
+    MEMBERS_ADMIN_SECTION,
+    CREDENTIALS_ADMIN_SECTION,
+    SIGNIN_ADMIN_SECTION,
+] as const;