@brendanbank/atrium-host-types 0.16.1 → 0.18.0

package/README.md

@@ -32,8 +32,8 @@ your `.npmrc`, delete it — npmjs.org is the default registry.
 
 ## Versioning
 
-The package version tracks atrium's image version. Pin `^0.16` for
-"compatible with atrium 0.16.x"; bump together with the atrium image
+The package version tracks atrium's image version. Pin `^0.18` for
+"compatible with atrium 0.18.x"; bump together with the atrium image
 to pick up new registry slots. New slots land as **optional** members
 on `AtriumRegistry` first so a host that hasn't bumped yet still
 type-checks.

package/dist/index.d.ts

@@ -44,6 +44,33 @@ export interface AdminUserRow {
     role_ids: number[];
     roles: string[];
 }
+/** Detail payload of the ``atrium:userchange`` window CustomEvent
+ *  atrium dispatches whenever the signed-in user identity changes —
+ *  login, logout, logout-all, impersonation start/stop, same-tab
+ *  re-login as a different user. ``previous`` and ``current`` are user
+ *  ids; ``null`` means signed out (or, for ``previous``, transitioning
+ *  out of the signed-out state). ``nonce`` is a monotonic per-event
+ *  counter. The event does NOT fire on first identity observation
+ *  after a page load (the user has not changed).
+ *
+ *  Available since atrium 0.18. The canonical use is host bundles
+ *  clearing their own QueryClient cache when the user changes — atrium
+ *  clears its own cache via ``qc.clear()`` on logout, but a host bundle
+ *  runs a separate QueryClient (by design — see
+ *  ``@brendanbank/atrium-host-bundle-utils/react``) and needs an
+ *  external signal:
+ *
+ *  ```ts
+ *  window.addEventListener('atrium:userchange', () => {
+ *    hostQueryClient.clear();
+ *  });
+ *  ```
+ */
+export interface AtriumUserChangeDetail {
+    previous: number | null;
+    current: number | null;
+    nonce: number;
+}
 /** A single notification row as the SPA sees it. `kind` is host-defined;
  *  `payload` is opaque JSON. `read_at` is null until the user clears the
  *  bell; `created_at` is the server-side timestamp. */
@@ -107,6 +134,13 @@ export interface NavItem {
      *  Notifications and Admin. Available since atrium 0.16. */
     order?: number;
 }
+/** Sidebar bucket an admin tab lives in. `admin` is the default and
+ *  groups every atrium-shipped admin surface plus host admin tooling.
+ *  `settings` is a parallel sibling group above Admin reserved for
+ *  application-level preferences — atrium ships zero items here, so
+ *  the Settings parent hides entirely until a host registers into it.
+ *  Available since atrium 0.17. */
+export type AdminSection = 'admin' | 'settings';
 export interface AdminTab {
     key: string;
     label: string;
@@ -114,17 +148,22 @@ export interface AdminTab {
     /** Permission code; the tab is hidden for users without it. Omit to
      *  show the tab to every viewer with admin access. */
     perm?: string;
+    /** Sidebar bucket. Default `'admin'`. Set `'settings'` to push a
+     *  host-app preference page into the Settings group instead.
+     *  Available since atrium 0.17. */
+    section?: AdminSection;
     /** Returns a fresh element each time the tab is selected. Strongly
      *  preferred — see `RouteEntry.render`. Exactly one of `render` /
      *  `element` must be supplied. */
     render?: () => ReactElement;
     /** @deprecated Pass `render: () => element` instead. */
     element?: ReactElement;
-    /** Optional sort key. Lower values render further left. Items
-     *  without `order` keep registration order, sorted **after** every
-     *  item that has one. Atrium's built-in tabs use 100..900 in steps
-     *  of 100; a host tab with `order: 750` would slot between Email
-     *  templates (700) and Reminders (800). Available since atrium 0.16. */
+    /** Optional sort key. Lower values render higher in the sidebar
+     *  group. Items without `order` keep registration order, sorted
+     *  **after** every item that has one. Atrium's built-in admin tabs
+     *  use 100..900 in steps of 100; a host tab with `order: 750`
+     *  would slot between Email templates (700) and Reminders (800).
+     *  Available since atrium 0.16. */
     order?: number;
 }
 /** Insertion slot inside `ProfilePage`'s vertical card stack. Default
@@ -188,6 +227,13 @@ export interface AtriumRegistry {
     registerRoute: (route: RouteEntry) => void;
     registerNavItem: (item: NavItem) => void;
     registerAdminTab: (tab: AdminTab) => void;
+    /** Relocate one of atrium's built-in admin tabs into a different
+     *  sidebar group, and optionally re-rank it within that group. Pass
+     *  the tab's stable atrium key (e.g. `'branding'`, `'emails'`,
+     *  `'outbox'`, `'reminders'`, `'translations'`); the perm gate the
+     *  built-in already declares is preserved. Available since atrium
+     *  0.17. */
+    setBuiltinAdminTabSection?: (key: string, section: AdminSection, order?: number) => void;
     registerProfileItem: (item: ProfileItem) => void;
     registerNotificationKind: (renderer: NotificationKindRenderer) => void;
     registerLocale: (overlay: LocaleOverlay) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brendanbank/atrium-host-types",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "TypeScript declarations for the atrium host-extension contract: AtriumRegistry, UserContext, AdminUserRow, AtriumNotification, AtriumEvent. Source-of-truth shapes a host bundle types against, kept in sync with atrium's published image major.minor.",
   "license": "BSD-2-Clause",
   "type": "module",