@brendanbank/atrium-host-types 0.15.0

package/LICENCE.md

@@ -0,0 +1,25 @@
+# BSD 2-Clause License
+
+Copyright (c) 2026, Brendan Bank
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,81 @@
+# `@brendanbank/atrium-host-types`
+
+TypeScript declarations for the [atrium](https://github.com/brendanbank/atrium)
+host-extension contract.
+
+```ts
+import type {
+  AtriumRegistry,
+  AtriumNotification,
+  AtriumEvent,
+  UserContext,
+  AdminUserRow,
+} from '@brendanbank/atrium-host-types';
+
+const reg = window.__ATRIUM_REGISTRY__ as AtriumRegistry;
+reg.registerHomeWidget({ key: 'my-card', render: () => /* ... */ });
+```
+
+The package is **types-only** — no runtime, no JS payload at runtime.
+Bundlers strip it from the production output.
+
+## Installation
+
+The package is published on **GitHub Packages**, not the public npm
+registry. Add an `.npmrc` to your host project that points the
+`@brendanbank` scope at GitHub Packages:
+
+```
+# .npmrc
+@brendanbank:registry=https://npm.pkg.github.com
+```
+
+GitHub Packages requires an authenticated install even for public
+packages — give npm a token with at least the `read:packages` scope:
+
+```
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+In CI, `GITHUB_TOKEN` is provided automatically by Actions; locally,
+generate a [classic PAT](https://github.com/settings/tokens) with
+`read:packages` and export it. Then:
+
+```bash
+pnpm add -D @brendanbank/atrium-host-types
+```
+
+## Versioning
+
+The package version tracks atrium's image version. Pin `^0.15` for
+"compatible with atrium 0.15.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.
+
+## What ships
+
+- `AtriumRegistry` — every `register*` slot atrium exposes plus
+  `subscribeEvent`.
+- `UserContext` — `/users/me/context` shape.
+- `AdminUserRow` — `/admin/users` row shape.
+- `AtriumNotification` — notification row body.
+- `AtriumEvent` / `AtriumEventHandler` — SSE typed event shape.
+- Per-slot option-bag types: `HomeWidget`, `RouteEntry`, `NavItem`,
+  `AdminTab`, `ProfileItem`, `NotificationKindRenderer`,
+  `LocaleOverlay`.
+- `ProfileSlot`, `HomeWidgetWidth` — string unions.
+- A `declare global` block that types `window.React`,
+  `window.__ATRIUM_VERSION__`, and `window.__ATRIUM_REGISTRY__`.
+
+## See also
+
+- [`@brendanbank/atrium-host-bundle-utils`](../host-bundle-utils/) —
+  runtime helpers, Vite preset, and React hooks. Re-exports the types
+  from this package, so a host adding only one dep still gets the
+  declarations.
+- [`docs/published-images.md`](../../docs/published-images.md) — the
+  full host-extension contract (image catalogue, loader behaviour,
+  registry semantics).
+- [`docs/compat-matrix.md`](../../docs/compat-matrix.md) — which
+  atrium release added which slot.

package/dist/index.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Source-of-truth TypeScript declarations for the atrium host-extension
+ * contract. A host bundle imports these types so its registration calls
+ * are checked against the same shapes atrium's own consumer components
+ * read.
+ *
+ * The package version tracks atrium's image version (`^0.14` of this
+ * package implies "compatible with atrium 0.14.x"). New registry slots
+ * land here when they ship in atrium; bumping the package picks them
+ * up. A host that calls a method missing on the pinned major gets a
+ * TypeScript error before runtime — the runtime Proxy on
+ * `window.__ATRIUM_REGISTRY__` is a belt-and-braces fallback for
+ * version skew, not a substitute for typing.
+ */
+import type { ReactElement } from 'react';
+/** Shape of `GET /users/me/context` — the atrium-owned RBAC view of the
+ *  signed-in user. The bundled hook in `@brendanbank/atrium-host-bundle-utils/react`
+ *  returns this exact shape. */
+export interface UserContext {
+    id: number;
+    email: string;
+    full_name: string;
+    is_active: boolean;
+    roles: string[];
+    permissions: string[];
+    impersonating_from: {
+        id: number;
+        email: string;
+        full_name: string;
+    } | null;
+}
+/** Shape of `GET /admin/users` rows (and `/admin/users/{id}` responses).
+ *  Hosts that render their own admin UIs against atrium's user list
+ *  read this shape. The patch endpoint accepts `role_ids`; the read
+ *  shape carries both `role_ids` and the human-readable `roles` codes. */
+export interface AdminUserRow {
+    id: number;
+    email: string;
+    is_active: boolean;
+    is_verified: boolean;
+    full_name: string;
+    phone: string | null;
+    preferred_language: 'en' | 'nl';
+    role_ids: number[];
+    roles: string[];
+}
+/** 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. */
+export interface AtriumNotification {
+    id: number;
+    kind: string;
+    payload: Record<string, unknown>;
+    read_at: string | null;
+    created_at: string;
+}
+/** SSE `notification` event published by `app.services.notifications.notify_user`.
+ *  Same wire shape as the row's body — `kind` matches what
+ *  `registerNotificationKind` listens on. */
+export interface AtriumEvent {
+    kind: string;
+    payload: Record<string, unknown>;
+}
+export type AtriumEventHandler = (event: AtriumEvent) => void;
+/** Layout width for a home-page widget. `narrow` matches atrium's default
+ *  680px column; `wide` extends to a comfortable dashboard column; `full`
+ *  takes the whole panel inside `AppShell.Main`. Default `narrow`. */
+export type HomeWidgetWidth = 'narrow' | 'wide' | 'full';
+export interface HomeWidget {
+    key: string;
+    render: () => ReactElement;
+    width?: HomeWidgetWidth;
+}
+export interface RouteEntry {
+    key: string;
+    path: string;
+    /** Returns a fresh element each time the route mounts. Strongly
+     *  preferred — see the host-bundle wrapper-element rationale in
+     *  `docs/published-images.md`. Exactly one of `render` / `element`
+     *  must be supplied. */
+    render?: () => ReactElement;
+    /** @deprecated Pass `render: () => element` instead. Captured
+     *  elements share the same DOM node across navigations and can carry
+     *  stale state. Kept for back-compat with hosts built against
+     *  pre-0.12 atrium. */
+    element?: ReactElement;
+    /** Default `true`. Set false for public routes (e.g. host landing pages). */
+    requireAuth?: boolean;
+    /** Default `'shell'`. `'bare'` skips atrium's AppLayout wrapper. */
+    layout?: 'shell' | 'bare';
+}
+export interface NavItem {
+    key: string;
+    label: string;
+    to: string;
+    icon?: ReactElement;
+    /** Optional visibility predicate. Default: always visible. `me` is
+     *  null until the SPA's auth probe resolves. */
+    condition?: (ctx: {
+        me: UserContext | null;
+    }) => boolean;
+}
+export interface AdminTab {
+    key: string;
+    label: string;
+    icon?: ReactElement;
+    /** Permission code; the tab is hidden for users without it. Omit to
+     *  show the tab to every viewer with admin access. */
+    perm?: string;
+    /** 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;
+}
+/** Insertion slot inside `ProfilePage`'s vertical card stack. Default
+ *  `'after-roles'` — the natural place for extra preferences. */
+export type ProfileSlot = 'after-profile' | 'after-password' | 'after-2fa' | 'after-roles' | 'after-sessions' | 'before-delete';
+export interface ProfileItem {
+    key: string;
+    /** Insertion slot. Default `'after-roles'`. */
+    slot?: ProfileSlot;
+    /** Optional visibility predicate. The profile page early-returns on a
+     *  missing user, so `me` is never null when this fires. */
+    condition?: (ctx: {
+        me: UserContext;
+    }) => boolean;
+    render: () => ReactElement;
+}
+/** Per-kind renderer for a notification row. Atrium emits `{kind,
+ *  payload}` rows but ships no built-in formatting — host apps register
+ *  one renderer per kind they care about. */
+export interface NotificationKindRenderer {
+    /** Notification `kind` string this renderer handles. Match is exact;
+     *  no glob / prefix matching. Duplicate registrations for the same
+     *  kind warn and last-write-wins. */
+    kind: string;
+    /** Detail-modal body. Receives the full row. */
+    render: (n: AtriumNotification) => ReactElement;
+    /** Compact summary for the bell + inbox row line and the modal title. */
+    title?: (n: AtriumNotification) => string;
+    /** App-internal href. When set, the row click navigates instead of
+     *  opening the detail modal. */
+    href?: (n: AtriumNotification) => string;
+}
+/** Locale overlay registered by a host. `strings` is a flat
+ *  i18next-style bundle (dot-paths or nested object — both accepted).
+ *  Layered on top of atrium's shipped locale + admin overrides;
+ *  precedence is shipped < admin overrides < host overlay. */
+export interface LocaleOverlay {
+    locale: string;
+    strings: Record<string, unknown>;
+}
+/** The runtime-discovered registry exposed at `window.__ATRIUM_REGISTRY__`.
+ *
+ *  Optional methods are slots that landed in a later atrium release
+ *  than the one that introduced this type — type-narrow before calling
+ *  if you intend to support older images, or use the runtime
+ *  `__ATRIUM_VERSION__` global for explicit gating. The Proxy on the
+ *  registry already turns calls to missing methods into a console
+ *  warning + no-op; this is for clean TypeScript checking on top of
+ *  that runtime safety net.
+ *
+ *  When atrium adds a new slot, this type bumps and the slot becomes
+ *  optional first; once a release window has passed and `^0.X` no
+ *  longer covers the pre-slot images, the slot becomes required. */
+export interface AtriumRegistry {
+    registerHomeWidget: (widget: HomeWidget) => void;
+    registerRoute: (route: RouteEntry) => void;
+    registerNavItem: (item: NavItem) => void;
+    registerAdminTab: (tab: AdminTab) => void;
+    registerProfileItem: (item: ProfileItem) => void;
+    registerNotificationKind: (renderer: NotificationKindRenderer) => void;
+    registerLocale: (overlay: LocaleOverlay) => void;
+    subscribeEvent: (kind: string, handler: AtriumEventHandler) => () => void;
+}
+declare global {
+    interface Window {
+        /** atrium's React instance. Host bundles read this so their
+         *  wrapper elements can call `React.createElement(...)` without
+         *  bundling a second React copy that atrium's reconciler would
+         *  refuse to render. Available since the host-bundle pattern
+         *  shipped (atrium 0.10+). */
+        React?: typeof import('react');
+        /** Backend version string (e.g. "0.14.0") mirrored from
+         *  `GET /app-config` before the host bundle is imported, so
+         *  import-time code can branch on it. Available since atrium
+         *  0.14.0; treat as best-effort on older images. */
+        __ATRIUM_VERSION__?: string;
+        /** The registry. Populated by atrium before the host bundle
+         *  imports; host bundles read it and call its `register*` methods
+         *  at module init. */
+        __ATRIUM_REGISTRY__?: AtriumRegistry;
+    }
+}
+export {};

package/dist/index.js

@@ -0,0 +1,3 @@
+// Copyright (c) 2026 Brendan Bank
+// SPDX-License-Identifier: BSD-2-Clause
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@brendanbank/atrium-host-types",
+  "version": "0.15.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",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brendanbank/atrium.git",
+    "directory": "packages/host-types"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  }
+}