@abgov/nx-adsp 13.18.0-beta.7 → 13.18.0-beta.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abgov/nx-adsp",
-  "version": "13.18.0-beta.7",
+  "version": "13.18.0-beta.9",
   "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__

@@ -172,8 +172,8 @@ 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 |
-| `AppLayout` | The content gutter every view renders inside (see the key files table). Also renders the skip-to-main-content link |
+| `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. 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 |
 
 There's no `AppHeader`/`AppFooter`/hero banner in this layout — `AppSideMenu` is the
@@ -186,7 +186,7 @@ marketing chrome around a staff tool).
 | Component | Purpose |
 |---|---|
 | `AppHeader` | `goa-microsite-header` + `goa-app-header`. Takes a `heading` prop; put account/sign-in actions in its `utilities` slot (a bare child with no slot is silently dropped by `goa-app-header`) |
-| `AppLayout` | The content gutter every view renders inside (see the key files table). Also renders the skip-to-main-content link |
+| `AppLayout` | The content gutter every view renders inside (see the key files table). `App.vue` itself owns the skip-to-main-content landmark for this layout — `AppLayout` deliberately doesn't duplicate it |
 | `AppFooter` | `goa-app-footer` with the standard GoA nav/meta links (Services/Contact/Terms of Use, Privacy/Disclaimer/Accessibility) |
 | `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 |
 <% } %>
@@ -201,6 +201,23 @@ composite generator.
 
 ## Adding a view
 
+**Check whether a generator already covers this view before hand-authoring one.** Each
+retrofits into this project directly — file(s), route(s), and the shared component it's
+built on, all in one step:
+
+| If the view is... | Use | Built on |
+|---|---|---|
+| A single record's detail page (loading/error, optional status badge, back button) | `nx g @abgov/nx-adsp:vue-detail-view` | `RecordDetailShell` |
+| A staff-facing, paginated/sortable/filterable list | `nx g @abgov/nx-adsp:vue-workspace-view` | `WorkspaceTable` |
+| A simple admin list + create/update edit screen (no pagination) | `nx g @abgov/nx-adsp:vue-admin-crud` | `WorkspaceTable` |
+| A multi-step submission flow (route-per-step, review, confirmation) | `nx g @abgov/nx-adsp:vue-intake-view` | `Stepper`, `StepErrorSummary` |
+
+Run `nx g @abgov/nx-adsp:<generator> --help` for its full option list (each takes a
+`--fields`/`--columns`/`--steps` JSON-string spec, not a CLI array flag — see the
+generator's own schema description for why). Only hand-author a view when none of these
+match, or once a generator's output needs customization it doesn't cover — its own comments
+mark what's meant to be edited.
+
 1. Create `src/views/MyFeatureView.vue` as a `<script setup>` SFC. **Don't add your
    own page margins/centering** — every view renders inside `AppLayout`'s gutter, so
    any top-level tag (`<div>`, `<section>`, …) is already centered and padded.

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

@@ -64,6 +64,7 @@ function onAccountItemClick() {
     </AppLayout>
   </AppSideMenu>
 <% } else { %>
+  <a class="skip-link" href="#main-content">Skip to main content</a>
   <AppHeader heading="<%= projectName %>">
     <template #utilities>
       <goa-button-group alignment="end">
@@ -86,13 +87,34 @@ function onAccountItemClick() {
     @dismiss="session.dismiss"
   />
   <goa-hero-banner heading="<%= projectName %>" backgroundurl="/assets/banner.jpg" />
-  <AppLayout :variant="contentWidth">
-    <RouterView />
-  </AppLayout>
+  <main id="main-content">
+    <AppLayout :variant="contentWidth">
+      <RouterView />
+    </AppLayout>
+  </main>
   <AppFooter />
 <% } %>
 </template>
 
 <style>
 body { margin: 0; }
+<% if (layout !== 'internal') { %>
+/* Visually hidden until focused (e.g. via Tab from the top of the page) — lets
+   keyboard/screen-reader users jump past the header straight to the content.
+   The internal/side-menu shell has its own scoped copy of this; this layout
+   has no equivalent shell component, so App.vue owns it directly here. */
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  top: 0;
+  z-index: 100;
+  padding: var(--goa-space-s, 0.5rem) var(--goa-space-m, 1rem);
+  background: var(--goa-color-interactive-default, #0070c4);
+  color: #fff;
+}
+
+.skip-link:focus {
+  left: var(--goa-space-m, 1rem);
+}
+<% } %>
 </style>

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

@@ -124,14 +124,21 @@ describe('Vue App Generator', () => {
     expect(layout).toContain('form-content');
     expect(layout).toContain('wide-content');
     expect(layout).toContain('--goa-space');
-    // Skip-to-main-content link for keyboard/screen-reader users.
-    expect(layout).toContain('href="#main-content"');
+    // AppLayout must NOT own the skip-to-main-content landmark itself: it nests
+    // inside AppSideMenu for --layout=internal, which already provides one, and
+    // a second <main id="main-content"> would duplicate the landmark/id.
+    expect(layout).not.toContain('id="main-content"');
+    expect(layout).not.toContain('skip-link');
 
     // App.vue uses AppLayout and no longer relies on the `main > section` gutter
     // (which silently failed when a view's top-level tag wasn't <section>).
+    // For --layout=header (the default), App.vue itself owns the skip-link
+    // landmark instead, since there's no shell component to hold it.
     const app = host.read('apps/test/src/App.vue').toString();
     expect(app).toContain('AppLayout');
     expect(app).not.toContain('main > section');
+    expect(app).toContain('href="#main-content"');
+    expect(app).toContain('id="main-content"');
   });
 
   it('provisions the shared GoA wrapper library and points the app at it', async () => {
@@ -202,6 +209,11 @@ describe('Vue App Generator', () => {
     expect(app).toContain('@item-click="onAccountItemClick"');
     // The content gutter is shared regardless of shell choice.
     expect(app).toContain('<AppLayout');
+    // App.vue itself must not add a second skip-to-main-content landmark —
+    // AppSideMenu (imported, not inlined) already owns the one and only
+    // #main-content for this layout.
+    expect(app).not.toContain('id="main-content"');
+    expect(app).not.toContain('skip-link');
 
     const agents = host.read('apps/test/AGENTS.md').toString();
     expect(agents).toContain('--layout=internal');

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

@@ -1,14 +1,31 @@
 # AGENTS.md — vue-components (GoA Design System Vue wrappers + app shell)
 
-A shared, workspace-local library with two distinct kinds of content — every Vue
-app in this workspace imports both instead of carrying its own copy. Generated by
-`@abgov/nx-adsp:vue-components`.
+A shared, workspace-local library — every Vue app in this workspace imports from
+it instead of carrying its own copy. Generated by `@abgov/nx-adsp:vue-components`,
+invoked automatically by `vue-app` and by every `vue-*-view` generator.
 
 | Folder | Contains | Lifespan |
 |---|---|---|
 | `src/lib/primitives/` | Thin `v-model`/idiomatic-event wrappers over individual `goa-*` elements (`GoabInput`, `GoabButton`, …) | **Interim** — see below |
 | `src/lib/patterns/` | Composite, app-shell components (`AppLayout`, `AppHeader`, `AppFooter`, `AppSideMenu`, `SessionExpiredBanner`, `RecordDetailShell`, `WorkspaceTable`, `Stepper`, `StepErrorSummary`) | **Permanent** |
 
+**Not every pattern component is present in every app.** `AppLayout`, `AppHeader`,
+`AppFooter`, `AppSideMenu`, and `SessionExpiredBanner` are base app-shell — `vue-app`
+provisions and wires all five into `App.vue` for every generated app, unconditionally.
+The rest are on-demand: they only exist in a given app's `src/lib/patterns/` if that
+app has run the matching view generator at least once.
+
+| Component | Provisioned by |
+|---|---|
+| `RecordDetailShell` | `vue-detail-view` |
+| `WorkspaceTable` | `vue-workspace-view`, `vue-admin-crud` |
+| `Stepper`, `StepErrorSummary` | `vue-intake-view` |
+
+Don't assume one of these on-demand components exists in a given app — check whether
+its generator has actually been run (e.g. `nx list @abgov/nx-adsp` won't tell you;
+look for the component file itself, or the view file that would import it) before
+building on it.
+
 > **⚠️ `primitives/` is interim — do not invest in it as permanent.** It exists
 > only because GoA DS has not yet published an official Vue wrapper package. When
 > `@abgov/vue-components` ships, delete `primitives/` and repoint imports at it —

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

@@ -8,37 +8,24 @@
 //   meta: { layout: 'form' }   // single-column forms      → 640px
 //   (default)                  // general content          → 1000px
 //   meta: { layout: 'wide' }   // data-heavy pages / tables → 1200px
+//
+// Deliberately not a landmark/skip-target itself: this component nests inside
+// AppSideMenu for --layout=internal, which already provides one, and a second
+// copy would duplicate the anchor screen readers/keyboard nav jump to. The
+// top-level shell (App.vue for --layout=header, AppSideMenu for --layout=internal)
+// owns that landmark instead.
 withDefaults(defineProps<{ variant?: 'page' | 'wide' | 'form' }>(), {
   variant: 'page',
 });
 </script>
 
 <template>
-  <a class="skip-link" href="#main-content">Skip to main content</a>
-  <main id="main-content">
-    <div :class="`${variant}-content`">
-      <slot />
-    </div>
-  </main>
+  <div :class="`${variant}-content`">
+    <slot />
+  </div>
 </template>
 
 <style scoped>
-/* Visually hidden until focused (e.g. via Tab from the top of the page) — lets
-   keyboard/screen-reader users jump past the header straight to the content. */
-.skip-link {
-  position: absolute;
-  left: -9999px;
-  top: 0;
-  z-index: 100;
-  padding: var(--goa-space-s, 0.5rem) var(--goa-space-m, 1rem);
-  background: var(--goa-color-interactive-default, #0070c4);
-  color: #fff;
-}
-
-.skip-link:focus {
-  left: var(--goa-space-m, 1rem);
-}
-
 .page-content,
 .wide-content,
 .form-content {

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 —