@abgov/nx-adsp 13.18.0-beta.8 → 13.18.0

package/README.md

@@ -2,7 +2,7 @@
 
 Nx plugin for bootstrapping [ADSP](https://govalta.github.io/adsp-monorepo/) applications for the Government of Alberta.
 
-The plugin provides generators for Node/Express services, React and Angular frontends, .NET services, and fullstack solutions. When `@abgov/nx-oc` is also installed in the workspace, OpenShift deployment YAML is automatically included in the generated output.
+The plugin provides generators for Node/Express services, React, Angular, and Vue 3 frontends, .NET services, and fullstack solutions. When `@abgov/nx-oc` is also installed in the workspace, OpenShift deployment YAML is automatically included in the generated output.
 
 ## Prerequisites
 
@@ -10,17 +10,18 @@ Install only the framework peers for the generators you use — they are declare
 as **optional** peer dependencies, so a workspace that only builds Vue apps
 doesn't need `@nx/react`, `@nx/angular`, etc.
 
-| Generator                       | Required peer dependency                 |
-| ------------------------------- | ---------------------------------------- |
-| `react-app`                     | `@nx/react`                              |
-| `angular-app`                   | `@nx/angular`                            |
-| `vue-app`                       | `@nx/vue`                                |
-| `dotnet-service`                | `@nx-dotnet/core`                        |
-| `react-dotnet`                  | `@nx/react`, `@nx-dotnet/core`           |
-| `express-service`               | `@nx/express`                            |
-| `pevn`, `mevn` (full-stack)     | `@nx/express`, `@nx/vue`                 |
-| `pern`, `pean` (full-stack)     | `@nx/express`, `@nx/react`/`@nx/angular` |
-| `react-form`, `react-task-list` | existing React project in the workspace  |
+| Generator                                                                    | Required peer dependency                    |
+| ---------------------------------------------------------------------------- | ------------------------------------------- |
+| `react-app`                                                                  | `@nx/react`                                 |
+| `angular-app`                                                                | `@nx/angular`                               |
+| `vue-app`                                                                    | `@nx/vue`                                   |
+| `dotnet-service`                                                             | `@nx-dotnet/core`                           |
+| `react-dotnet`                                                               | `@nx/react`, `@nx-dotnet/core`              |
+| `express-service`                                                            | `@nx/express`                               |
+| `pevn`, `mevn` (full-stack)                                                  | `@nx/express`, `@nx/vue`                    |
+| `pern`, `pean` (full-stack)                                                  | `@nx/express`, `@nx/react`/`@nx/angular`    |
+| `react-form`, `react-task-list`                                              | existing React project in the workspace     |
+| `vue-detail-view`, `vue-workspace-view`, `vue-admin-crud`, `vue-intake-view` | existing `vue-app` project in the workspace |
 
 ## Installation
 
@@ -185,6 +186,30 @@ Accepts the same options as `react-app`.
 
 ---
 
+### `vue-app`
+
+Creates a Vue 3 frontend application configured for ADSP, using GoA web components
+(`@abgov/web-components`) and `@dsb-norge/vue-keycloak-js` for authentication. Requires
+`@nx/vue`.
+
+```bash
+npx nx g @abgov/nx-adsp:vue-app my-app --env dev --tenant my-tenant
+```
+
+Accepts the same options as `react-app`, plus:
+
+| Option   | Required | Description                                                                                                                                                                                                                                                                                            |
+| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `layout` | No       | Top-level app shell: `header` (default) is a `goa-app-header` + hero banner + footer (public-facing); `internal` is a `goa-work-side-menu` shell with no header/banner/footer (staff-facing). Pair two runs against the same `--pairedProject` for a public+internal frontend pairing over one backend |
+
+Every generated app provisions a shared `vue-components` library — `Goab*` `v-model` wrappers
+over the design system plus reusable app-shell pattern components (`AppLayout`, `AppHeader`,
+`AppFooter`, `AppSideMenu`, `SessionExpiredBanner`) — see the generated app's own `AGENTS.md`
+for the full contract. Four more generators retrofit common view shapes into an existing
+`vue-app` project; see below.
+
+---
+
 ### `dotnet-service`
 
 Creates an ASP.NET Core backend service configured for ADSP. Requires `@nx-dotnet/core`.
@@ -241,6 +266,103 @@ Accepts the same options as `react-form`.
 
 ---
 
+### `vue-detail-view`
+
+Adds a record-detail view (loading/error/loaded states, optional status badge, back button) to
+an existing `vue-app` project, built on the shared `RecordDetailShell` pattern component.
+
+```bash
+npx nx g @abgov/nx-adsp:vue-detail-view my-app --name=application-detail --resource=applications --route=/applications/:id --fields='[{"key":"status","label":"Status","type":"badge"}]'
+```
+
+| Option         | Required | Description                                                                                                                                                                                               |
+| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project`      | Yes      | The `vue-app` project to add the view to                                                                                                                                                                  |
+| `name`         | Yes      | View name, e.g. `application-detail` generates `src/views/ApplicationDetailView.vue`                                                                                                                      |
+| `resource`     | Yes      | API resource path segment — the view fetches `/api/<resource>/:id`                                                                                                                                        |
+| `route`        | Yes      | Route path added to `router/index.ts`, e.g. `/applications/:id`. Must contain a `:id` param                                                                                                               |
+| `fields`       | Yes      | JSON array of fields rendered in the record's info list, in display order: `{ key, label, type?: "text"\|"date"\|"currency"\|"badge" }` — a JSON string, not a comma-separated CLI array (see note below) |
+| `heading`      | No       | Page heading. Defaults to the view name, title-cased                                                                                                                                                      |
+| `requiresAuth` | No       | Whether the generated route requires authentication. Defaults to `true`                                                                                                                                   |
+
+---
+
+### `vue-workspace-view`
+
+Adds a staff-facing, paginated list view (a debounced search filter bar + sortable columns) to
+an existing `vue-app` project, built on the shared `WorkspaceTable` pattern component.
+
+```bash
+npx nx g @abgov/nx-adsp:vue-workspace-view my-app --name=applications --resource=applications --route=/applications --detailRoute=/applications --columns='[{"key":"status","label":"Status","type":"badge","sortable":true}]'
+```
+
+| Option         | Required | Description                                                                                                                                              |
+| -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project`      | Yes      | The `vue-app` project to add the view to                                                                                                                 |
+| `name`         | Yes      | View name, e.g. `applications` generates `src/views/ApplicationsListView.vue`                                                                            |
+| `resource`     | Yes      | API resource path segment — fetches `/api/<resource>?page=&limit=&search=&sortBy=&sortDir=`                                                              |
+| `route`        | Yes      | Route path added to `router/index.ts`, e.g. `/applications`                                                                                              |
+| `columns`      | Yes      | JSON array of table columns, in display order: `{ key, label, type?: "text"\|"date"\|"currency"\|"badge", sortable? }` — a JSON string (see note below)  |
+| `detailRoute`  | No       | If set, each row gets a "View" action linking to `` `${detailRoute}/${row.id}` `` — typically a `vue-detail-view`'s route with the `:id` segment dropped |
+| `filterable`   | No       | Whether to generate a debounced search input above the table. Defaults to `true`                                                                         |
+| `heading`      | No       | Page heading. Defaults to the view name, title-cased                                                                                                     |
+| `pageSize`     | No       | Rows per page. Defaults to `20`                                                                                                                          |
+| `requiresAuth` | No       | Whether the generated route requires authentication. Defaults to `true`                                                                                  |
+
+---
+
+### `vue-admin-crud`
+
+Adds a simple admin CRUD screen pair (a `WorkspaceTable` list view with a Create action and
+per-row Edit, plus a create/update Edit view) to an existing `vue-app` project — suited to small
+lookup-table style admin screens, not large paginated workspaces (see `vue-workspace-view` for
+that).
+
+```bash
+npx nx g @abgov/nx-adsp:vue-admin-crud my-app --name=regions --resource=regions --route=/regions --fields='[{"key":"name","label":"Name"},{"key":"active","label":"Active","type":"checkbox"}]'
+```
+
+| Option          | Required | Description                                                                                                                                                         |
+| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project`       | Yes      | The `vue-app` project to add the views to                                                                                                                           |
+| `name`          | Yes      | View name, e.g. `regions` generates `src/views/RegionsListView.vue` and `src/views/RegionsEditView.vue`                                                             |
+| `resource`      | Yes      | API resource path segment — fetches `/api/<resource>` (list), `/api/<resource>/:id` (load one), `POST /api/<resource>` (create), `PUT /api/<resource>/:id` (update) |
+| `route`         | Yes      | List route path added to `router/index.ts`, e.g. `/regions`. The edit/create route is added as `` `${route}/:id` `` (visiting `${route}/new` creates)               |
+| `fields`        | Yes      | JSON array of fields, in display/form order: `{ key, label, type?: "text"\|"checkbox", required? }` — a JSON string (see note below)                                |
+| `heading`       | No       | List page heading. Defaults to the view name, title-cased                                                                                                           |
+| `singularLabel` | No       | Singular label used in "Create <label>"/"Edit <label>" headings and buttons. Defaults to `--heading` (override for irregular plurals)                               |
+| `requiresAuth`  | No       | Whether the generated routes require authentication. Defaults to `true`                                                                                             |
+
+---
+
+### `vue-intake-view`
+
+Adds a route-per-step intake wizard (`Stepper` + `StepErrorSummary`, a required read-only
+review step, and a confirmation page) to an existing `vue-app` project. Cross-step state is
+server-persisted — each step PUTs/POSTs to `/api/<resource>/:id` and refetches on mount, so
+there's no client-side draft caching. Every field is currently a plain text input.
+
+```bash
+npx nx g @abgov/nx-adsp:vue-intake-view my-app --name=application --resource=applications --route=/applications --steps='[{"key":"personal-info","label":"Personal information","fields":[{"key":"fullName","label":"Full name"}]}]'
+```
+
+| Option         | Required | Description                                                                                                                                                                   |
+| -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project`      | Yes      | The `vue-app` project to add the views to                                                                                                                                     |
+| `name`         | Yes      | Base name for the generated views, e.g. `application` generates `<Step>StepView.vue` per step plus `ApplicationReviewView.vue`/`ApplicationConfirmationView.vue`              |
+| `resource`     | Yes      | API resource path segment. Each step fetches/saves `/api/<resource>/:id`; the review step's Submit posts `/api/<resource>/:id/submit`                                         |
+| `route`        | Yes      | Base route, e.g. `/applications`. Steps become `/applications/:id/<step-key>`, plus `/review` and `/confirmation`. Start a new intake at `/applications/new/<first-step-key>` |
+| `steps`        | Yes      | JSON array of steps, in order: `{ key, label, fields: [{ key, label, required? }] }` — a JSON string (see note below)                                                         |
+| `requiresAuth` | No       | Whether the generated routes require authentication. Defaults to `true`                                                                                                       |
+
+---
+
+> **Note on JSON-string options (`fields`/`columns`/`steps`):** Nx's own CLI arg coercion only
+> supports comma-separated primitive lists for `array`-typed schema options, not JSON — a JSON
+> string is the only CLI syntax that survives it, so these options are declared as `string` and
+> parsed internally. A plain array also works when the generator is invoked programmatically
+> (e.g. from a script), bypassing CLI parsing entirely.
+
 ## Authentication
 
 Most generators call ADSP APIs during generation, which needs an ADSP access

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abgov/nx-adsp",
-  "version": "13.18.0-beta.8",
+  "version": "13.18.0",
   "license": "Apache-2.0",
   "main": "src/index.js",
   "description": "Government of Alberta - Nx plugin for ADSP apps.",

package/src/generators/vue-app/files/AGENTS.md__tmpl__

@@ -34,11 +34,15 @@ executors read options from `project.json` and do not prompt.
 <% if (layout === 'internal') { %>
 | `src/App.vue` | Shell — `AppSideMenu` (side-menu shell, Sign in/out as an account item), `SessionExpiredBanner`, `<RouterView>` wrapped in `AppLayout` |
 <% } else { %>
-| `src/App.vue` | Shell — `AppHeader` with sign-in/out in its `utilities` slot, `SessionExpiredBanner`, hero banner, `<RouterView>` wrapped in `AppLayout`, `AppFooter` |
+| `src/App.vue` | Shell — `AppHeader` with sign-in/out in its `utilities` slot, `SessionExpiredBanner`, `<RouterView>` wrapped in `AppLayout`, `AppFooter` |
 <% } %>
 | `src/stores/session.ts` | Pinia store — `expired` flag behind `SessionExpiredBanner`, set from `main.ts`'s `onAuthRefreshError` hook |
 | `src/router/index.ts` | Routes — `/protected` guarded with `requiresAuth` meta |
+<% if (layout === 'internal') { %>
 | `src/views/HomeView.vue` | Public page — calls public and private APIs |
+<% } else { %>
+| `src/views/HomeView.vue` | Public page — hero banner (page content, not app-shell — real GoA services show it once on the landing page, not on every route) + calls public and private APIs |
+<% } %>
 | `src/views/ProtectedView.vue` | Authenticated page — shows user info from token |
 | `src/environments/environment.ts` | Access URL, realm, client ID — pre-set from ADSP tenant |
 | `vite.config.ts` | Vite config — `isCustomElement` marks `goa-*` as web components |
@@ -172,7 +176,7 @@ from **`<%= goaImportPath %>`**, not hand-rolled markup:
 
 | Component | Purpose |
 |---|---|
-| `AppSideMenu` | `goa-work-side-menu`. Takes `heading`/`primaryItems`/`secondaryItems`/`accountItems` props (each item: `{ label, to?, icon?, badge?, current? }`) and emits `itemClick` — it doesn't know about routing or auth, so `App.vue` computes `current`/handles the click itself. `App.vue` currently only populates `accountItems` (a single Sign in/out item); add real nav items to `primaryItems`/`secondaryItems` as routes are added. Also owns the skip-to-main-content landmark for this layout — `AppLayout` deliberately doesn't duplicate it |
+| `AppSideMenu` | `goa-work-side-menu`. Takes `heading`/`primaryItems`/`secondaryItems`/`accountItems` props (each item: `{ label, to?, icon?, badge?, current? }`) and emits `itemClick` — it doesn't know about routing or auth, so `App.vue` computes `current`/handles the click itself. `App.vue` currently only populates `accountItems` (a single Sign in/out item); add real nav items to `primaryItems`/`secondaryItems` as routes are added. **`icon` is effectively required** — `goa-work-side-menu-item` renders a blank item without it; use a GoA icon name (see [design.alberta.ca/components/icons](https://design.alberta.ca/components/icons)). Also owns the skip-to-main-content landmark for this layout — `AppLayout` deliberately doesn't duplicate it. Also takes an optional `#topbar` slot — a slim row above the routed content, for something like a notification bell; only renders when given content, unused by default |
 | `AppLayout` | The content gutter every view renders inside (see the key files table) |
 | `SessionExpiredBanner` | A `v-model:show` banner with `signIn`/`dismiss` emits. Bound to the `useSessionStore()` Pinia store (`src/stores/session.ts`), which `main.ts`'s `onAuthRefreshError` hook flips when the refresh token itself has expired |
 
@@ -230,20 +234,105 @@ mark what's meant to be edited.
    { path: '/queue', component: () => import('../views/QueueView.vue'), meta: { layout: 'wide' } }
    { path: '/apply', component: () => import('../views/ApplyView.vue'), meta: { layout: 'form' } }
    ```
-3. Add a nav link to `src/App.vue` if needed
+3. **For the `internal` layout: add a nav link to `src/App.vue`.** The generated shell only
+   populates `accountItems`; primary navigation lives in `primaryItems` (or `secondaryItems`).
+   `AppSideMenu` is purely presentational — it doesn't know about routing, so `App.vue` owns
+   `current` detection and the `itemClick` handler:
+
+   ```typescript
+   // In <script setup>:
+   import { computed } from 'vue';
+   import { RouterView, useRoute, useRouter } from 'vue-router';
+   // ...existing imports...
+
+   const route = useRoute();    // already in the generated App.vue
+   const router = useRouter();
+
+   // Icon names come from the GoA icon set: design.alberta.ca/components/icons
+   const primaryItems = computed(() => [
+     { label: 'Home',       to: '/',           icon: 'home',  current: route.path === '/' },
+     { label: 'My Feature', to: '/my-feature', icon: 'list',  current: route.path.startsWith('/my-feature') },
+   ]);
+
+   function onItemClick(item: { to?: string }) {
+     if (item.to) router.push(item.to);
+   }
+   ```
+
+   ```html
+   <!-- In <template>, add :primary-items and @item-click to <AppSideMenu>: -->
+   <AppSideMenu
+     heading="..."
+     :primary-items="primaryItems"
+     :account-items="accountItems"
+     @item-click="onItemClick"
+   >
+   ```
+
+   The `header` layout has no side menu — add route-level breadcrumbs or a secondary nav
+   directly inside the view component instead.
 
 ## Backend API calls (proxy setup)
 
-Use relative `/api/` paths — they route through Vite's dev proxy and nginx in production:
+Use relative `/api/` paths — they route through Vite's dev proxy and nginx in production.
+
+**Use `useApi()` for all API calls.** `apiFetch` automatically refreshes the token and adds
+`Authorization: Bearer` when the user is authenticated — you never need to do it at each
+call site.
 
 ```typescript
-// ✓ correct
-const res = await fetch('/api/v1/my-resource');
+import { useApi } from '../composables/useApi' // adjust depth for nested components (../../…)
 
-// ✗ wrong — bypasses proxy, won't work in production
-const res = await fetch('http://localhost:3333/my-service/v1/my-resource');
+const { apiFetch } = useApi()
+
+// ✓ Any route — adds the token when authenticated, skips it when not
+const res = await apiFetch('/api/v1/my-resource')
+
+// ✓ With a request body
+const res = await apiFetch('/api/v1/my-resource', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify(payload),
+})
+
+// ✗ Wrong path — bypasses proxy, won't work in production
+const res = await fetch('http://localhost:3333/<%= pairedProject || 'my-service' %>/v1/my-resource')
+```
+
+**Most routes require authentication.** The service mounts `/v1` with the anonymous passport
+strategy, so a bare request without a token reaches the router — but business routes also
+gate on `tenant` auth and will 401. `apiFetch` handles this automatically when signed in.
+
+**React to auth state for calls that require the user to be signed in.** Keycloak settles
+asynchronously; watch `kc.authenticated` rather than reading it once on mount:
+
+```typescript
+import { watch } from 'vue'
+import { useKeycloak } from '@dsb-norge/vue-keycloak-js'
+import { useApi } from '../composables/useApi'
+
+const kc = useKeycloak()
+const { apiFetch } = useApi()
+
+watch(
+  () => kc.authenticated,
+  async (authenticated) => {
+    if (!authenticated) return
+    try {
+      const res = await apiFetch('/api/v1/my-resource')
+      // ...
+    } catch {
+      // apiFetch rejects on network error or if the refresh token expired;
+      // the SessionExpiredBanner handles the latter via onAuthRefreshError.
+    }
+  },
+  { immediate: true },
+)
 ```
 
+`apiFetch` adds the token only when `kc.authenticated` is true — the watch ensures
+you call it only after auth has settled, not speculatively on mount.
+
 ## Testing
 
 Tests live alongside source files (`*.spec.ts` / `*.spec.vue`) and run with Vitest:

package/src/generators/vue-app/files/src/App.vue__tmpl__

@@ -86,7 +86,6 @@ function onAccountItemClick() {
     @sign-in="signInAgain"
     @dismiss="session.dismiss"
   />
-  <goa-hero-banner heading="<%= projectName %>" backgroundurl="/assets/banner.jpg" />
   <main id="main-content">
     <AppLayout :variant="contentWidth">
       <RouterView />

package/src/generators/vue-app/files/src/composables/useApi.ts__tmpl__

@@ -0,0 +1,21 @@
+import { useKeycloak } from '@dsb-norge/vue-keycloak-js'
+
+export function useApi() {
+  // Keep the reactive instance — do NOT destructure: `authenticated` and `keycloak`
+  // are plain values inside a reactive object and only populate asynchronously once
+  // Keycloak settles. Reading `kc.authenticated` at call time (inside apiFetch)
+  // always gets the current value; a destructured snapshot would freeze at setup time.
+  const kc = useKeycloak()
+
+  async function apiFetch(url: string, init: RequestInit = {}): Promise<Response> {
+    if (kc.authenticated) {
+      await kc.keycloak?.updateToken(30)
+      const headers = new Headers(init.headers)
+      headers.set('Authorization', `Bearer ${kc.keycloak?.token}`)
+      return fetch(url, { ...init, headers })
+    }
+    return fetch(url, init)
+  }
+
+  return { apiFetch }
+}

package/src/generators/vue-app/files/src/views/HomeView.vue__tmpl__

@@ -1,47 +1,50 @@
 <script setup lang="ts">
-import { ref, onMounted, watch } from 'vue';
-import { useKeycloak } from '@dsb-norge/vue-keycloak-js';
+import { ref, onMounted, watch } from 'vue'
+import { useKeycloak } from '@dsb-norge/vue-keycloak-js'
+import { useApi } from '../composables/useApi'
 
 // Keep the reactive instance — do NOT destructure (see App.vue): a destructured
-// `authenticated`/`keycloak` freezes at its setup-time value, so the private
-// fetch below would never see the user sign in and the bearer token stays undefined.
-const kc = useKeycloak();
-const publicResource = ref('Not retrieved — is the backend service running?');
-const privateResource = ref('Not retrieved — sign in first.');
+// `authenticated` freezes at its setup-time value, so the watch below would never
+// see the user sign in and apiFetch would always skip the token.
+const kc = useKeycloak()
+const { apiFetch } = useApi()
+const publicResource = ref('Not retrieved — is the backend service running?')
+const privateResource = ref('Not retrieved — sign in first.')
 
 onMounted(async () => {
   try {
-    const res = await fetch('/api/v1/public');
-    const data = await res.json();
-    publicResource.value = data.message;
+    const res = await apiFetch('/api/v1/public')
+    const data = await res.json()
+    publicResource.value = data.message
   } catch {
-    publicResource.value = 'Error loading public resource.';
+    publicResource.value = 'Error loading public resource.'
   }
-});
+})
 
 // React to authentication (which settles asynchronously and may flip after mount,
 // e.g. on return from the login redirect) rather than reading it once on mount.
 watch(
   () => kc.authenticated,
   async (authenticated) => {
-    if (!authenticated) return;
+    if (!authenticated) return
     try {
-      await kc.keycloak?.updateToken(30);
-      const res = await fetch('/api/v1/private', {
-        headers: { Authorization: `Bearer ${kc.keycloak?.token}` },
-      });
-      const data = await res.json();
-      privateResource.value = data.message;
+      const res = await apiFetch('/api/v1/private')
+      const data = await res.json()
+      privateResource.value = data.message
     } catch {
-      privateResource.value = 'Error loading private resource.';
+      privateResource.value = 'Error loading private resource.'
     }
   },
-  { immediate: true }
-);
+  { immediate: true },
+)
 </script>
 
 <template>
   <section>
+    <% if (layout !== 'internal') { %>
+    <goa-hero-banner heading="<%= projectName %>" backgroundurl="/assets/banner.jpg" />
+    <goa-spacer vspacing="l" />
+    <% } %>
     <h2>Welcome to <%= projectName %>!</h2>
     <p>Don't panic. Start editing the project to build your digital service.</p>
     <h3>A few things you might want to do next:</h3>

package/src/generators/vue-app/vue-app.spec.ts

@@ -297,6 +297,23 @@ describe('Vue App Generator', () => {
     expect(app).toContain('kc.keycloak?.login()');
   }, 30000);
 
+  it('generates a useApi composable that handles token refresh and auth headers', async () => {
+    await generator(host, options);
+    expect(host.exists('apps/test/src/composables/useApi.ts')).toBeTruthy();
+    const useApi = host.read('apps/test/src/composables/useApi.ts').toString();
+    // Token refresh and auth header injection are encapsulated here, not at each call site.
+    expect(useApi).toContain('updateToken');
+    expect(useApi).toContain('Authorization');
+    expect(useApi).toContain('apiFetch');
+
+    // HomeView delegates to the composable — raw token wiring must not leak into views.
+    const homeView = host.read('apps/test/src/views/HomeView.vue').toString();
+    expect(homeView).toContain('useApi');
+    expect(homeView).toContain('apiFetch');
+    expect(homeView).not.toContain('updateToken');
+    expect(homeView).not.toContain('Authorization');
+  }, 30000);
+
   it('index.html is at the Vite entry root and its mount target matches main.ts', async () => {
     await generator(host, options);
     // Vite's entry is <projectRoot>/index.html, not src/index.html — a template
@@ -313,17 +330,35 @@ describe('Vue App Generator', () => {
 
   it('static assets live in public/ so Vite serves them at the referenced URLs', async () => {
     await generator(host, options);
-    // App.vue's <goa-hero-banner backgroundurl="/assets/banner.jpg"> and
+    // HomeView's <goa-hero-banner backgroundurl="/assets/banner.jpg"> and
     // index.html's favicon.ico are absolute-URL string refs, so they must be in
     // the Vite publicDir (public/) — a src/assets file is not served at /assets.
-    const appVue = host.read('apps/test/src/App.vue').toString();
-    const bannerUrl = appVue.match(/backgroundurl="([^"]+)"/)?.[1];
+    const homeView = host.read('apps/test/src/views/HomeView.vue').toString();
+    const bannerUrl = homeView.match(/backgroundurl="([^"]+)"/)?.[1];
     expect(bannerUrl).toBe('/assets/banner.jpg');
     expect(host.exists('apps/test/public/assets/banner.jpg')).toBeTruthy();
     expect(host.exists('apps/test/src/assets/banner.jpg')).toBeFalsy();
     expect(host.exists('apps/test/public/favicon.ico')).toBeTruthy();
   }, 30000);
 
+  it('the hero banner is home-page content, not part of the persistent app shell', async () => {
+    // Real GovAlta-Pronghorn source (both the canonical template and an
+    // independently-evolved production app) puts goa-hero-banner only inside
+    // HomeView -- never in App.vue/AppLayout -- so it shows once on the
+    // landing page, not repeated on every interior route.
+    await generator(host, options);
+    const app = host.read('apps/test/src/App.vue').toString();
+    expect(app).not.toContain('goa-hero-banner');
+    const homeView = host.read('apps/test/src/views/HomeView.vue').toString();
+    expect(homeView).toContain('goa-hero-banner');
+  }, 30000);
+
+  it('--layout=internal has no hero banner anywhere, including on HomeView', async () => {
+    await generator(host, { ...options, layout: 'internal' });
+    const homeView = host.read('apps/test/src/views/HomeView.vue').toString();
+    expect(homeView).not.toContain('goa-hero-banner');
+  }, 30000);
+
   it('vite.config.ts marks goa-* elements as custom elements', async () => {
     await generator(host, options);
     const viteConfig = host.read('apps/test/vite.config.ts').toString();

package/src/generators/vue-components/files/src/lib/patterns/AppSideMenu.vue__tmpl__

@@ -1,9 +1,20 @@
 <script setup lang="ts">
+import { useSlots } from 'vue';
+
 // The alternate top-level shell for staff-facing/internal apps (goa-work-side-menu),
 // used instead of AppHeader/AppFooter -- not together with them. Presentational only:
 // unlike the real GovAlta-Pronghorn source this is adapted from, active-route
 // highlighting and navigation are the caller's job (pass `current` on each item,
 // listen for `item-click`) so this component doesn't need vue-router as a dependency.
+//
+// The real reference source also has a slim in-content "topbar" row for
+// module-registered header actions (e.g. a notification bell) -- there's no
+// AppHeader/utilities slot in this layout to hold that kind of thing. Exposed
+// here as a plain named slot (`#topbar`), not a module-registration system --
+// that's app-specific plumbing, not something a shared, presentational
+// component should own.
+const slots = useSlots();
+
 interface AppSideMenuItem {
   label: string;
   to?: string;
@@ -63,6 +74,9 @@ const emit = defineEmits<{ itemClick: [item: AppSideMenuItem] }>();
       />
     </goa-work-side-menu>
     <main id="main-content" class="app-side-menu-content">
+      <div v-if="slots.topbar" class="app-side-menu-topbar">
+        <slot name="topbar" />
+      </div>
       <slot />
     </main>
   </div>
@@ -80,6 +94,15 @@ const emit = defineEmits<{ itemClick: [item: AppSideMenuItem] }>();
   overflow-y: auto;
 }
 
+.app-side-menu-topbar {
+  display: flex;
+  justify-content: flex-end;
+  align-items: center;
+  gap: var(--goa-space-s, 0.75rem);
+  padding: var(--goa-space-xs, 0.5rem) var(--goa-space-m, 1rem);
+  border-bottom: 1px solid var(--goa-color-greyscale-100, #f1f1f1);
+}
+
 .skip-link {
   position: absolute;
   left: -9999px;

package/src/generators/vue-components/vue-components.spec.ts

@@ -76,6 +76,19 @@ describe('Vue Components Generator', () => {
     expect(agents).toContain('defineModel<boolean>');
   }, 30000);
 
+  it('AppSideMenu exposes an optional #topbar slot for header-action-style content', async () => {
+    await generator(host);
+
+    const sideMenu = host
+      .read('libs/vue-components/src/lib/patterns/AppSideMenu.vue')
+      .toString();
+    // Named slot, only rendered when actually given content -- no empty bar
+    // shows by default, matching the "unused by default" doc claim.
+    expect(sideMenu).toContain('<slot name="topbar" />');
+    expect(sideMenu).toContain('v-if="slots.topbar"');
+    expect(sideMenu).toContain('useSlots');
+  }, 30000);
+
   it('disables vue/no-deprecated-slot-attribute in flat config too, not just .eslintrc.json', async () => {
     // useFlatConfig() (from @nx/eslint) treats a root flat-config file's
     // presence as authoritative, regardless of the installed ESLint version —