@brendanbank/create-atrium-host 0.15.0

package/template/frontend/src/__BRAND_PASCAL__Widget.tsx

@@ -0,0 +1,117 @@
+/** Home-widget rendering of the demo state.
+ *
+ * Wraps itself in MantineProvider + QueryClientProvider + AtriumProvider
+ * so the host bundle's Mantine instance, TanStack cache, and atrium
+ * user-context query stay isolated from atrium's own copies. Two
+ * MantineProviders nested in the DOM is supported by Mantine.
+ *
+ * Permission gating uses `usePerm()` from
+ * `@brendanbank/atrium-host-bundle-utils/react` — a single TanStack
+ * Query subscription against atrium's `/users/me/context`, shared
+ * across this widget, the dedicated page, and the admin tab.
+ */
+import {
+  Badge,
+  Button,
+  Card,
+  Group,
+  Loader,
+  MantineProvider,
+  Stack,
+  Text,
+  Title,
+} from '@mantine/core';
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query';
+import {
+  AtriumProvider,
+  usePerm,
+} from '@brendanbank/atrium-host-bundle-utils/react';
+
+import {
+  bump__BRAND_PASCAL__,
+  get__BRAND_PASCAL__State,
+  type __BRAND_PASCAL__State,
+} from './api';
+import { queryClient } from './queryClient';
+
+const STATE_KEY = ['__HOST_PKG__', 'state'] as const;
+
+function __BRAND_PASCAL__WidgetInner() {
+  const qc = useQueryClient();
+  const { data, isLoading, error } = useQuery({
+    queryKey: STATE_KEY,
+    queryFn: get__BRAND_PASCAL__State,
+  });
+  const hasPerm = usePerm();
+  const canBump = hasPerm('__HOST_PKG__.write');
+  const bumpMutation = useMutation({
+    mutationFn: bump__BRAND_PASCAL__,
+    onSuccess: (next: __BRAND_PASCAL__State) => {
+      qc.setQueryData(STATE_KEY, next);
+    },
+  });
+
+  return (
+    <Card withBorder padding="lg" radius="md" data-testid="__HOST_NAME__-card">
+      <Stack gap="sm">
+        <Group justify="space-between" align="center">
+          <Title order={4}>__BRAND_NAME__</Title>
+          <Badge color={canBump ? 'teal' : 'gray'} variant="light">
+            {canBump ? 'editor' : 'viewer'}
+          </Badge>
+        </Group>
+        {isLoading && (
+          <Group gap="xs">
+            <Loader size="xs" />
+            <Text size="sm" c="dimmed">Loading…</Text>
+          </Group>
+        )}
+        {error && (
+          <Text c="red" size="sm">
+            Error: {(error as Error).message}
+          </Text>
+        )}
+        {data && (
+          <>
+            <Text size="lg" fw={500} data-testid="__HOST_NAME__-message">
+              {data.message}
+            </Text>
+            <Text
+              ff="monospace"
+              size="xl"
+              fw={700}
+              data-testid="__HOST_NAME__-counter"
+            >
+              {data.counter}
+            </Text>
+            <Button
+              onClick={() => bumpMutation.mutate()}
+              disabled={!canBump || bumpMutation.isPending}
+              data-testid="__HOST_NAME__-bump"
+              fullWidth
+            >
+              {canBump ? 'Bump counter' : 'Bump (admin only)'}
+            </Button>
+          </>
+        )}
+      </Stack>
+    </Card>
+  );
+}
+
+export function __BRAND_PASCAL__Widget() {
+  return (
+    <MantineProvider>
+      <QueryClientProvider client={queryClient}>
+        <AtriumProvider>
+          <__BRAND_PASCAL__WidgetInner />
+        </AtriumProvider>
+      </QueryClientProvider>
+    </MantineProvider>
+  );
+}

package/template/frontend/src/api.ts

@@ -0,0 +1,38 @@
+/** Plain fetch — no axios. `credentials: 'include'` carries atrium's
+ *  auth cookie so authenticated routes work the same as from atrium's
+ *  own SPA. Build with `VITE_API_BASE_URL=""` (the default in the
+ *  Dockerfile) so the bundle calls relative paths.
+ */
+const apiBase =
+  (import.meta as { env?: { VITE_API_BASE_URL?: string } }).env?.VITE_API_BASE_URL ??
+  '';
+
+async function jsonOrThrow<T>(res: Response): Promise<T> {
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`api ${res.status}: ${body}`);
+  }
+  return (await res.json()) as T;
+}
+
+export interface __BRAND_PASCAL__State {
+  message: string;
+  counter: number;
+}
+
+export async function get__BRAND_PASCAL__State(): Promise<__BRAND_PASCAL__State> {
+  const res = await fetch(`${apiBase}/__HOST_PKG__/state`, {
+    credentials: 'include',
+    headers: { Accept: 'application/json' },
+  });
+  return jsonOrThrow<__BRAND_PASCAL__State>(res);
+}
+
+export async function bump__BRAND_PASCAL__(): Promise<__BRAND_PASCAL__State> {
+  const res = await fetch(`${apiBase}/__HOST_PKG__/bump`, {
+    method: 'POST',
+    credentials: 'include',
+    headers: { Accept: 'application/json' },
+  });
+  return jsonOrThrow<__BRAND_PASCAL__State>(res);
+}

package/template/frontend/src/main.tsx

@@ -0,0 +1,55 @@
+/** Host bundle entry.
+ *
+ * Atrium loads this module via `import(system.host_bundle_url)` after
+ * the SPA boots. The import-time side-effects below populate the
+ * registry. The dual-tree mount pattern (atrium-React owns the
+ * wrapper, the host's React owns the subtree) is encapsulated in
+ * `makeWrapperElement` from `@brendanbank/atrium-host-bundle-utils`.
+ */
+import { IconHandStop } from '@tabler/icons-react';
+import {
+  type AtriumRegistry,
+  makeWrapperElement,
+} from '@brendanbank/atrium-host-bundle-utils';
+
+import { __BRAND_PASCAL__AdminTab } from './__BRAND_PASCAL__AdminTab';
+import { __BRAND_PASCAL__Page } from './__BRAND_PASCAL__Page';
+import { __BRAND_PASCAL__ProfileItem } from './__BRAND_PASCAL__ProfileItem';
+import { __BRAND_PASCAL__Widget } from './__BRAND_PASCAL__Widget';
+
+const reg = window.__ATRIUM_REGISTRY__ as AtriumRegistry | undefined;
+const AtriumReact = window.React;
+
+if (!reg || !AtriumReact) {
+  console.error(
+    '[__HOST_NAME__] window.__ATRIUM_REGISTRY__ or window.React missing — atrium SPA must mount before the host bundle loads',
+  );
+} else {
+  reg.registerHomeWidget({
+    key: '__HOST_NAME__-widget',
+    render: () => makeWrapperElement(<__BRAND_PASCAL__Widget />),
+  });
+  reg.registerRoute({
+    key: '__HOST_NAME__-page',
+    path: '/__HOST_NAME__',
+    render: () => makeWrapperElement(<__BRAND_PASCAL__Page />),
+  });
+  reg.registerNavItem({
+    key: '__HOST_NAME__-nav',
+    label: '__BRAND_NAME__',
+    to: '/__HOST_NAME__',
+    icon: AtriumReact.createElement(IconHandStop, { size: 18 }),
+  });
+  reg.registerAdminTab({
+    key: '__HOST_NAME__',
+    label: '__BRAND_NAME__',
+    icon: AtriumReact.createElement(IconHandStop, { size: 14 }),
+    perm: '__HOST_PKG__.write',
+    render: () => makeWrapperElement(<__BRAND_PASCAL__AdminTab />),
+  });
+  reg.registerProfileItem({
+    key: '__HOST_NAME__-profile',
+    slot: 'after-roles',
+    render: () => makeWrapperElement(<__BRAND_PASCAL__ProfileItem />),
+  });
+}

package/template/frontend/src/queryClient.ts

@@ -0,0 +1,11 @@
+import { QueryClient } from '@tanstack/react-query';
+
+/** Single QueryClient shared across every component this bundle
+ *  registers — they all wrap their tree in a QueryClientProvider that
+ *  points at this client so they share cache for the same query keys.
+ */
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { staleTime: 2_000, retry: 1 },
+  },
+});

package/template/frontend/src/test/__BRAND_PASCAL__Widget.test.tsx

@@ -0,0 +1,102 @@
+/** Worked example of testing a host bundle component with
+ *  `@brendanbank/atrium-test-utils`.
+ *
+ *  The widget calls `usePerm()` to gate the bump button on the
+ *  `__HOST_PKG__.write` permission. The test installs the fakes once
+ *  via `mockAtriumRegistry` and asserts the gating without standing up
+ *  the SPA.
+ */
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { cleanup, screen, waitFor } from '@testing-library/react';
+
+import {
+  mockAtriumRegistry,
+  renderWithAtrium,
+  type MockAtriumHandles,
+  type UserContext,
+} from '@brendanbank/atrium-test-utils';
+
+import { __BRAND_PASCAL__Widget } from '../__BRAND_PASCAL__Widget';
+import { queryClient } from '../queryClient';
+
+const EDITOR: UserContext = {
+  id: 1,
+  email: 'admin@example.com',
+  full_name: 'Admin',
+  is_active: true,
+  roles: ['admin'],
+  permissions: ['__HOST_PKG__.write'],
+  impersonating_from: null,
+};
+
+const VIEWER: UserContext = {
+  id: 2,
+  email: 'viewer@example.com',
+  full_name: 'Viewer',
+  is_active: true,
+  roles: [],
+  permissions: [],
+  impersonating_from: null,
+};
+
+let handles: MockAtriumHandles;
+let currentMe: UserContext | null = null;
+
+function stubFetch() {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async (url: string) => {
+      if (url.endsWith('/users/me/context')) {
+        if (!currentMe) return new Response(null, { status: 401 });
+        return new Response(JSON.stringify(currentMe), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      if (url.endsWith('/__HOST_PKG__/state')) {
+        return new Response(
+          JSON.stringify({ message: 'Hello from __BRAND_NAME__', counter: 7 }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      }
+      return new Response('{}', { status: 200 });
+    }),
+  );
+}
+
+beforeEach(() => {
+  stubFetch();
+});
+
+afterEach(() => {
+  cleanup();
+  handles?.cleanup();
+  // The widget self-wraps in a module-singleton QueryClient so clear
+  // it between tests, otherwise the previous test's `me` leaks via
+  // the cache.
+  queryClient.clear();
+  currentMe = null;
+  vi.unstubAllGlobals();
+});
+
+describe('__BRAND_PASCAL__Widget', () => {
+  test('users with __HOST_PKG__.write can press the bump button', async () => {
+    currentMe = EDITOR;
+    handles = mockAtriumRegistry({ me: EDITOR });
+    renderWithAtrium(<__BRAND_PASCAL__Widget />);
+    const button = (await screen.findByTestId('__HOST_NAME__-bump')) as HTMLButtonElement;
+    await waitFor(() => expect(button).not.toBeDisabled());
+    expect(screen.getByText('Bump counter')).toBeInTheDocument();
+  });
+
+  test('users without __HOST_PKG__.write see the disabled label', async () => {
+    currentMe = VIEWER;
+    handles = mockAtriumRegistry({ me: VIEWER });
+    renderWithAtrium(<__BRAND_PASCAL__Widget />);
+    const button = (await screen.findByTestId('__HOST_NAME__-bump')) as HTMLButtonElement;
+    await waitFor(() =>
+      expect(screen.getByText(/admin only/)).toBeInTheDocument(),
+    );
+    expect(button).toBeDisabled();
+  });
+});

package/template/frontend/src/test/setup.ts

@@ -0,0 +1,21 @@
+import '@testing-library/jest-dom/vitest';
+
+// jsdom doesn't ship window.matchMedia; Mantine's MantineProvider
+// reads it on mount to decide the initial colour scheme. Stub a
+// "no preference" response so component tests can render without a
+// runtime error.
+if (typeof window !== 'undefined' && !window.matchMedia) {
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    value: (query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    }),
+  });
+}

package/template/frontend/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/template/frontend/vite.config.ts

@@ -0,0 +1,7 @@
+import { hostBundleConfig } from '@brendanbank/atrium-host-bundle-utils/vite';
+
+// One function call: lib-mode build emitting `dist/main.js`, CSS
+// inlined via runtime <style> tags, defines for the externalised
+// React + TanStack Query references. See @brendanbank/atrium-host-bundle-utils
+// for the rationale on each default.
+export default hostBundleConfig({ entry: 'src/main.tsx' });

package/template/frontend/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+// Vite's built-in esbuild loader handles tsx via the project's
+// tsconfig (`jsx: react-jsx`). No `@vitejs/plugin-react` needed for
+// unit tests — the package isn't listed as a peer dep so we'd be
+// adding one for tests alone, which the host-bundle pattern keeps
+// out by design.
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: false,
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/**/*.test.{ts,tsx}'],
+  },
+});