@abgov/nx-adsp 13.23.1 → 13.25.0

package/migrations.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "generators": {
+    "add-migrate-advisory-lock": {
+      "version": "13.24.0",
+      "description": "Wrap express-service's generated src/migrate.ts drizzle migrate() call in a Postgres advisory lock, so concurrent init containers serialize instead of racing.",
+      "implementation": "./src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock",
+      "prompt": "./src/migrations/add-migrate-advisory-lock/add-migrate-advisory-lock.md"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abgov/nx-adsp",
-  "version": "13.23.1",
+  "version": "13.25.0",
   "license": "Apache-2.0",
   "main": "src/index.js",
   "description": "Government of Alberta - Nx plugin for ADSP apps.",
@@ -41,6 +41,9 @@
     "socket.io-client": "^4.8.3"
   },
   "generators": "./generators.json",
+  "nx-migrations": {
+    "migrations": "./migrations.json"
+  },
   "scripts": {},
   "types": "./src/index.d.ts",
   "type": "commonjs"

package/src/build-assets.spec.ts

@@ -59,4 +59,78 @@ describe('build assets packaging', () => {
 
     expect(unmatched).toEqual([]);
   });
+
+  // The same boundary one level up. A migration is only reachable if
+  // package.json declares the registry and project.json ships it — and the
+  // migration's own unit tests resolve everything from the source tree, so they
+  // pass either way. Nothing else catches a migration that publishes inert.
+  it('ships the migrations registry declared in package.json', () => {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8'),
+    );
+    const registry: string | undefined = pkg['nx-migrations']?.migrations;
+    expect(registry).toBeDefined();
+
+    const registryPath = path.join(projectRoot, registry as string);
+    expect(fs.existsSync(registryPath)).toBe(true);
+
+    const project = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'project.json'), 'utf-8'),
+    );
+    const assets: unknown[] = project.targets.build.options.assets ?? [];
+    const rootGlobs = assets
+      .filter(
+        (a): a is { input: string; glob: string } =>
+          typeof a === 'object' &&
+          a !== null &&
+          'input' in a &&
+          path.resolve(repoRoot, (a as { input: string }).input) ===
+            path.resolve(projectRoot),
+      )
+      .map((a) => a.glob);
+
+    const rel = path.relative(projectRoot, registryPath);
+    expect(rootGlobs.some((glob) => minimatch(rel, glob, { dot: true }))).toBe(
+      true,
+    );
+  });
+
+  // Every file a migration names must resolve, or `nx migrate` fails at run
+  // time in the consumer's workspace rather than here. `prompt` is the markdown
+  // handed to the paired AI step; Nx resolves it relative to migrations.json
+  // (not through package exports), and requires at least one of implementation,
+  // factory, or prompt per entry.
+  it('points every migration at files that exist', () => {
+    const registry = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'migrations.json'), 'utf-8'),
+    );
+    const entries: [
+      string,
+      { implementation?: string; factory?: string; prompt?: string },
+    ][] = Object.entries(registry.generators ?? {});
+    expect(entries.length).toBeGreaterThan(0);
+
+    const problems: string[] = [];
+    for (const [name, entry] of entries) {
+      if (!entry.implementation && !entry.factory && !entry.prompt) {
+        problems.push(`${name}: needs implementation, factory, or prompt`);
+      }
+      if (
+        entry.implementation &&
+        !fs.existsSync(path.join(projectRoot, `${entry.implementation}.ts`))
+      ) {
+        problems.push(`${name}: implementation not found`);
+      }
+      // Referenced verbatim, extension included — unlike implementation, which
+      // Nx resolves without one.
+      if (
+        entry.prompt &&
+        !fs.existsSync(path.join(projectRoot, entry.prompt))
+      ) {
+        problems.push(`${name}: prompt not found`);
+      }
+    }
+
+    expect(problems).toEqual([]);
+  });
 });

package/src/generators/vue-admin-crud/files/src/views/__editViewFileName__.vue__tmpl__

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { reactive, ref, computed, onMounted } from 'vue';
+import { reactive, ref, computed, watch, onUnmounted } from 'vue';
 import { useRoute, useRouter } from 'vue-router';
 import { useKeycloak } from '@dsb-norge/vue-keycloak-js';
 import { GoabInput, GoabCheckbox } from '<%= goaImportPath %>';
@@ -8,7 +8,7 @@ import { useApi } from '../composables/useApi';
 const route = useRoute();
 const router = useRouter();
 const kc = useKeycloak();
-const { apiFetch } = useApi();
+const { get, save } = useApi();
 
 const idParam = computed(() => String(route.params.id ?? ''));
 const isNew = computed(() => idParam.value === 'new' || idParam.value === '');
@@ -28,15 +28,14 @@ const saving = ref(false);
 const loadError = ref<string | null>(null);
 const saveError = ref<string | null>(null);
 const successMessage = ref<string | null>(null);
+let redirectTimer: ReturnType<typeof setTimeout> | undefined;
 
 async function load() {
   if (isNew.value) return;
   loading.value = true;
   loadError.value = null;
   try {
-    const res = await apiFetch(`/api/<%= resource %>/${idParam.value}`);
-    if (!res.ok) throw new Error(`Failed to load (${res.status})`);
-    const data = await res.json();
+    const data = await get('<%= resource %>', idParam.value);
 <% fields.forEach(function (field) { -%>
     if (data['<%= field.key %>'] !== undefined) form.<%= field.key %> = data['<%= field.key %>'];
 <% }); -%>
@@ -47,7 +46,32 @@ async function load() {
   }
 }
 
-onMounted(load);
+// Field defaults come from the same EJS loop that seeds `form` above, so there
+// is one source of truth for them. `form` is reactive, so it is reset per key
+// rather than reassigned.
+function resetForm() {
+<% fields.forEach(function (field) { -%>
+  form.<%- field.key %> = <%- field.type === 'checkbox' ? 'false' : "''" %>;
+<% }); -%>
+  for (const key of Object.keys(errors)) errors[key] = undefined;
+}
+
+// Vue Router reuses this component when only the id param changes, so onMounted
+// would never fire again. The reset branch matters as much as the reload one: on
+// an edit/<id> -> edit/new change load() returns early on isNew, which would
+// leave the previous record's values sitting in a "create" form.
+watch(
+  idParam,
+  () => {
+    if (isNew.value) {
+      resetForm();
+      loadError.value = null;
+      return;
+    }
+    void load();
+  },
+  { immediate: true },
+);
 
 function validate(): boolean {
   let valid = true;
@@ -69,17 +93,10 @@ async function onSubmit() {
   saving.value = true;
   saveError.value = null;
   try {
-    const res = await apiFetch(
-      isNew.value ? '/api/<%= resource %>' : `/api/<%= resource %>/${idParam.value}`,
-      {
-        method: isNew.value ? 'POST' : 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(form),
-      },
-    );
-    if (!res.ok) throw new Error(`Failed to save (${res.status})`);
+    // Create vs. update — which verb and path that means is the adapter's call.
+    await save('<%= resource %>', isNew.value ? null : idParam.value, form);
     successMessage.value = isNew.value ? '<%= singularLabel %> created.' : '<%= singularLabel %> saved.';
-    setTimeout(() => router.push('<%= route %>'), 600);
+    redirectTimer = setTimeout(() => router.push('<%= route %>'), 600);
   } catch (e) {
     saveError.value = e instanceof Error ? e.message : 'Failed to save.';
   } finally {
@@ -90,6 +107,13 @@ async function onSubmit() {
 function goBack() {
   router.push('<%= route %>');
 }
+
+// The success message holds for 600ms before redirecting. If the user navigates
+// away inside that window the timer would fire anyway and yank them back to the
+// list from wherever they went.
+onUnmounted(() => {
+  if (redirectTimer) clearTimeout(redirectTimer);
+});
 </script>
 
 <template>

package/src/generators/vue-admin-crud/files/src/views/__listViewFileName__.vue__tmpl__

@@ -5,7 +5,7 @@ import { WorkspaceTable } from '<%= goaImportPath %>';
 import { useApi } from '../composables/useApi';
 
 const kc = useKeycloak();
-const { apiFetch } = useApi();
+const { list } = useApi();
 
 const columns = [
 <% fields.forEach(function (field) { -%>
@@ -23,11 +23,7 @@ async function load() {
   loading.value = true;
   error.value = null;
   try {
-    const res = await apiFetch('/api/<%= resource %>');
-    if (!res.ok) throw new Error(`Failed to load (${res.status})`);
-    const data = await res.json();
-    // Accept either a bare array or a { results } envelope.
-    rows.value = Array.isArray(data) ? data : (data.results ?? []);
+    rows.value = (await list('<%= resource %>')).rows;
   } catch (e) {
     error.value = e instanceof Error ? e.message : 'Failed to load.';
   } finally {

package/src/generators/vue-admin-crud/vue-admin-crud.spec.ts

@@ -61,7 +61,9 @@ describe('Vue Admin CRUD Generator', () => {
       .read('apps/test/src/views/RegionsListView.vue')
       .toString();
     expect(view).toContain('<h1>Regions</h1>');
-    expect(view).toContain("apiFetch('/api/regions')");
+    expect(view).toContain("await list('regions')");
+    // The envelope shape is the adapter's business, not the view's.
+    expect(view).not.toContain('data.results');
     expect(view).toContain("import { WorkspaceTable } from '@proj/vue-components';");
     expect(view).toContain('<WorkspaceTable');
     // No pagination props bound -- this is the "reused without its pagination/
@@ -90,9 +92,26 @@ describe('Vue Admin CRUD Generator', () => {
     expect(view).toContain("errors.name = 'Name is required.';");
     // Checkbox has no required-validation block.
     expect(view).not.toContain('errors.active');
-    expect(view).toContain("method: isNew.value ? 'POST' : 'PUT'");
-    expect(view).toContain("isNew.value ? '/api/regions'");
-    expect(view).toContain('apiFetch(`/api/regions/${idParam.value}`');
+    // Create vs. update is expressed as a null id; which verb and path that
+    // becomes is decided by useApi's adapter.
+    expect(view).toContain("await save('regions', isNew.value ? null : idParam.value, form)");
+    expect(view).toContain("await get('regions', idParam.value)");
+    expect(view).not.toContain('apiFetch');
+    expect(view).not.toContain("'PUT'");
+
+    // Vue Router reuses this component across an id-only change. The reset
+    // branch is the point: edit/<id> -> edit/new must not leave the previous
+    // record's values in a create form.
+    expect(view).toContain('watch(');
+    expect(view).toContain('{ immediate: true }');
+    expect(view).toContain('function resetForm()');
+    expect(view).toContain('resetForm();');
+    expect(view).not.toContain('onMounted(');
+
+    // The 600ms success redirect must not fire after the user navigates away.
+    expect(view).toContain('redirectTimer = setTimeout(');
+    expect(view).toContain('clearTimeout(redirectTimer)');
+    expect(view).toContain('onUnmounted(');
     expect(view).toContain("router.push('/regions')");
     expect(view).toContain('Create Regions');
     expect(view).toContain('Edit Regions');

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

@@ -290,6 +290,34 @@ const res = await apiFetch('/api/v1/my-resource', {
 const res = await fetch('http://localhost:3333/<%= pairedProject || 'my-service' %>/v1/my-resource')
 ```
 
+**For CRUD against a REST resource, prefer the domain-level helpers over `apiFetch`.**
+`useApi()` also returns `list`/`get`/`save`/`action`, which state what you want rather than how
+this API spells it:
+
+```typescript
+const { list, get, save, action } = useApi()
+
+const { rows, total } = await list('my-resource', {
+  page: 1, pageSize: 20, search: term, sortBy: 'name', sortDir: 'asc',
+  filters: { status: 'active' },
+})
+const record = await get('my-resource', id)
+await save('my-resource', null, payload)   // null id = create
+await save('my-resource', id, payload)     // an id = update
+await action('my-resource', id, 'submit')  // POST /:id/submit
+```
+
+Every wire-level detail these hide — the base path, whether paging is `page`/`limit` or
+`limit`/`offset`, whether rows arrive bare or under `results`/`entries`, whether an update is PUT
+or PATCH — lives in the **API convention adapter** at the top of
+`src/composables/useApi.ts`. That block is the glue layer between this app and its backend:
+**edit it when your API differs, and never encode an API convention in a view.** Every
+`vue-*-view` generator emits views that go through these helpers, so a view stays correct when the
+backend's conventions aren't the default ones, and your mapping survives regenerating the view.
+
+Use `apiFetch` directly for anything that isn't resource CRUD — a non-REST endpoint, a file
+download, a custom collection path.
+
 **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.

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

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+import { apiConvention } from './useApi'
+
+// The API convention adapter is this app's glue layer to its backend, so it is
+// the piece most likely to be edited by hand. These tests pin the default
+// mapping; if you change the adapter to match a different API, change them with
+// it -- a failure here means a generated view's assumptions moved.
+describe('apiConvention', () => {
+  it('builds collection, record, and action paths', () => {
+    expect(apiConvention.path('widgets')).toBe('/api/widgets')
+    expect(apiConvention.path('widgets', 7)).toBe('/api/widgets/7')
+    expect(apiConvention.path('widgets', 7, 'submit')).toBe('/api/widgets/7/submit')
+  })
+
+  it('maps a domain page/pageSize onto this API page/limit parameters', () => {
+    const params = apiConvention.query({ page: 3, pageSize: 20 })
+    expect(params.get('page')).toBe('3')
+    expect(params.get('limit')).toBe('20')
+  })
+
+  it('omits paging entirely when the view did not ask for a page', () => {
+    expect(apiConvention.query({}).toString()).toBe('')
+  })
+
+  it('passes search, sort, and extra filters through, dropping empty values', () => {
+    const params = apiConvention.query({
+      search: 'abc',
+      sortBy: 'name',
+      filters: { status: 'active', region: undefined, owner: '' },
+    })
+    expect(params.get('search')).toBe('abc')
+    expect(params.get('sortBy')).toBe('name')
+    expect(params.get('sortDir')).toBe('asc') // defaulted
+    expect(params.get('status')).toBe('active')
+    expect(params.has('region')).toBe(false)
+    expect(params.has('owner')).toBe(false)
+  })
+
+  it('reads a bare array response', () => {
+    expect(apiConvention.result([{ id: 1 }, { id: 2 }])).toEqual({
+      rows: [{ id: 1 }, { id: 2 }],
+      total: 2,
+    })
+  })
+
+  it('reads a { results, total } envelope, and falls back to row count', () => {
+    expect(apiConvention.result({ results: [{ id: 1 }], total: 57 })).toEqual({
+      rows: [{ id: 1 }],
+      total: 57,
+    })
+    expect(apiConvention.result({ results: [{ id: 1 }] })).toEqual({
+      rows: [{ id: 1 }],
+      total: 1,
+    })
+  })
+
+  it('yields no rows rather than throwing on an unrecognised envelope', () => {
+    // A silently empty table is the failure this adapter exists to make fixable
+    // in one place: if your API nests rows under another key, map it above.
+    expect(apiConvention.result({ entries: [{ id: 1 }], total: 9 })).toEqual({
+      rows: [],
+      total: 9,
+    })
+    expect(apiConvention.result(null)).toEqual({ rows: [], total: 0 })
+  })
+
+  it('creates with POST and updates with PUT', () => {
+    expect(apiConvention.writeMethod(true)).toBe('POST')
+    expect(apiConvention.writeMethod(false)).toBe('PUT')
+  })
+})

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

@@ -1,5 +1,83 @@
 import { useKeycloak } from '@dsb-norge/vue-keycloak-js'
 
+// ---------------------------------------------------------------------------
+// API convention adapter — THE GLUE LAYER. Edit this block, not the views.
+//
+// Generated views speak in domain terms only: page, pageSize, search, sort,
+// filters, rows, total. Every wire-level detail — the base path, what the paging
+// parameters are called, which key the rows arrive under, which verb updates a
+// record — lives here and nowhere else. A backend that pages by limit/offset,
+// wraps rows under `entries`, or updates with PATCH is a change to this block
+// alone, with no view touched and nothing to redo when a view is regenerated.
+//
+// This is deliberately a small amount of indirection: the alternative, which
+// this replaced, inlined `page`/`limit` and `data.results` into every generated
+// view, so a backend using different names silently produced an empty table
+// under a pagination control reporting the right total.
+// ---------------------------------------------------------------------------
+
+export interface ListQuery {
+  page?: number
+  pageSize?: number
+  search?: string
+  sortBy?: string
+  sortDir?: 'asc' | 'desc'
+  /** Extra key/value filters. Empty values are dropped. */
+  filters?: Record<string, string | undefined>
+}
+
+export interface ListResult<T = Record<string, unknown>> {
+  rows: T[]
+  total: number
+}
+
+export const apiConvention = {
+  /** Path to a collection, one record, or a named action on a record. */
+  path(resource: string, id?: string | number, action?: string): string {
+    const base = `/api/${resource}`
+    if (id === undefined || id === null) return base
+    return action ? `${base}/${id}/${action}` : `${base}/${id}`
+  },
+
+  /** Domain list query -> this API's query string. */
+  query(query: ListQuery): URLSearchParams {
+    const params = new URLSearchParams()
+    if (query.page !== undefined && query.pageSize !== undefined) {
+      params.set('page', String(query.page))
+      params.set('limit', String(query.pageSize))
+      // For a limit/offset API, replace the two lines above with:
+      //   params.set('limit', String(query.pageSize))
+      //   params.set('offset', String((query.page - 1) * query.pageSize))
+    }
+    if (query.search) params.set('search', query.search)
+    if (query.sortBy) {
+      params.set('sortBy', query.sortBy)
+      params.set('sortDir', query.sortDir ?? 'asc')
+    }
+    for (const [key, value] of Object.entries(query.filters ?? {})) {
+      if (value) params.set(key, value)
+    }
+    return params
+  },
+
+  /**
+   * This API's list response -> { rows, total }. Handles a bare array and a
+   * `{ results, total }` envelope; if yours nests rows under a different key
+   * (e.g. `entries`), read it here.
+   */
+  result(data: unknown): ListResult {
+    if (Array.isArray(data)) return { rows: data, total: data.length }
+    const envelope = (data ?? {}) as Record<string, unknown>
+    const rows = (envelope.results ?? []) as Record<string, unknown>[]
+    return { rows, total: (envelope.total as number) ?? rows.length }
+  },
+
+  /** Create vs. update verb. Updates with PATCH instead? Change it here. */
+  writeMethod(isNew: boolean): 'POST' | 'PUT' | 'PATCH' {
+    return isNew ? 'POST' : 'PUT'
+  },
+}
+
 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
@@ -17,5 +95,80 @@ export function useApi() {
     return fetch(url, init)
   }
 
-  return { apiFetch }
+  // `verb` only shapes the thrown message ("Failed to load (404)"), so a view's
+  // catch block can surface it unchanged.
+  async function request<T>(
+    url: string,
+    init: RequestInit,
+    verb: string,
+  ): Promise<T> {
+    const res = await apiFetch(url, init)
+    if (!res.ok) throw new Error(`Failed to ${verb} (${res.status})`)
+    // A write may legitimately answer 204, or 200 with an empty body — parsing
+    // that as JSON would throw on a request that actually succeeded.
+    if (res.status === 204) return undefined as T
+    const body = await res.text()
+    return (body ? JSON.parse(body) : undefined) as T
+  }
+
+  function list<T = Record<string, unknown>>(
+    resource: string,
+    query: ListQuery = {},
+  ): Promise<ListResult<T>> {
+    const params = apiConvention.query(query).toString()
+    const url = apiConvention.path(resource) + (params ? `?${params}` : '')
+    return request<unknown>(url, {}, 'load').then(
+      (data) => apiConvention.result(data) as ListResult<T>,
+    )
+  }
+
+  function get<T = Record<string, unknown>>(
+    resource: string,
+    id: string | number,
+  ): Promise<T> {
+    return request<T>(apiConvention.path(resource, id), {}, 'load')
+  }
+
+  function save<T = Record<string, unknown>>(
+    resource: string,
+    id: string | number | null,
+    body: unknown,
+  ): Promise<T> {
+    const isNew = id === null || id === undefined
+    return request<T>(
+      isNew
+        ? apiConvention.path(resource)
+        : apiConvention.path(resource, id),
+      {
+        method: apiConvention.writeMethod(isNew),
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      },
+      'save',
+    )
+  }
+
+  /** A named action on one record, e.g. action('applications', id, 'submit'). */
+  function action<T = Record<string, unknown>>(
+    resource: string,
+    id: string | number,
+    name: string,
+    body?: unknown,
+  ): Promise<T> {
+    return request<T>(
+      apiConvention.path(resource, id, name),
+      {
+        method: 'POST',
+        ...(body === undefined
+          ? {}
+          : {
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify(body),
+            }),
+      },
+      name,
+    )
+  }
+
+  return { apiFetch, list, get, save, action }
 }

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

@@ -295,6 +295,16 @@ describe('Vue App Generator', () => {
     expect(useApi).toContain('updateToken');
     expect(useApi).toContain('Authorization');
     expect(useApi).toContain('apiFetch');
+    // The glue layer: views state paging/sorting in domain terms and this block
+    // maps them to the wire. Its absence is what let query-param names and
+    // response-envelope keys get inlined into every generated view.
+    expect(useApi).toContain('apiConvention');
+    expect(useApi).toContain('THE GLUE LAYER');
+    for (const method of ['function list', 'function get', 'function save', 'function action']) {
+      expect(useApi).toContain(method);
+    }
+    // The documented escape hatch for a limit/offset backend.
+    expect(useApi).toContain("params.set('offset'");
 
     // HomeView delegates to the composable — raw token wiring must not leak into views.
     const homeView = host.read('apps/test/src/views/HomeView.vue').toString();

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

@@ -8,6 +8,7 @@ invoked automatically by `vue-app` and by every `vue-*-view` generator.
 |---|---|---|
 | `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** |
+| `src/lib/formatters.ts` | Shared value formatting for views (`formatDate`, `formatDateTime`, `formatNumber`, `formatPercent`) | **Permanent** |
 
 **Not every pattern component is present in every app.** `AppLayout`, `AppHeader`,
 `AppFooter`, `AppSideMenu`, and `SessionExpiredBanner` are base app-shell — `vue-app`
@@ -38,6 +39,50 @@ building on it.
 > package — a design system ships primitives, not your app's shell. Nothing in
 > `patterns/` is deleted when `primitives/` is.
 
+## Use the design system's own elements — most need no wrapper
+
+**Read this before writing any markup.** GoA's design system ships ~94 custom elements. Only a
+handful need a Vue wrapper (the form inputs — see the next section for why); the rest are
+presentational, have nothing to bind, and are used **bare** in any Vue SFC. `vite.config.mts`'s
+`isCustomElement` already recognises `goa-*`, so they work with no import and no registration.
+
+If you find yourself writing `style="…"` for layout, spacing, or typography, stop — the element you
+want almost certainly exists. Measured on a real ADSP app that shipped without this catalog: 254 of
+its 257 inline styles were on raw HTML (`div`, `th`, `td`, `span`, `h2`) standing in for the elements
+below, while only 3 were on `goa-*` elements. Every view its generators fully covered had zero
+inline styles.
+
+| Instead of hand-rolling | Use | Notes |
+|---|---|---|
+| `<div style="background:white;border:1px solid …;border-radius:…;padding:…">` | `<goa-container>` | The bordered, padded card box. `type`/`accent` variants |
+| `<div style="display:flex;gap:…;align-items:…">` | `<goa-block>` | Flex row or stack, `gap` and `direction` props |
+| `<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(…))">` | `<goa-grid>` | Responsive auto-fit grid, `min-child-width` prop |
+| `<h2 style="font-size:…;font-weight:…;color:…">`, styled `span`/`p` | `<goa-text>` | Typography scale: `size`, `weight`, `color`, `mt`/`mb` |
+| `<table>` with `<th style>`/`<td style>` | `<goa-table>` (+ `<goa-table-sort-header>`) | For any table that isn't a paginated list view — `WorkspaceTable` already wraps this for that case |
+| Tab `<button>`s toggling `v-if` blocks | `<goa-tabs>` + `<goa-tab heading="…">` | Slot-based and self-managing: `initialtab` sets the first open tab, no `v-model` and no `@_change` |
+| A margin-only `<div>` or `<br>` | `<goa-spacer vspacing="m">` | |
+| A styled status pill | `<goa-badge type="…">` | |
+| A hand-built alert/notice box | `<goa-callout type="…" heading="…">` | |
+| A loading `<div>` or spinner markup | `<goa-skeleton type="…">` or `<goa-spinner>` | Skeletons match the shape they replace (`card`, `text`, `table`) |
+| A `<label>` + error `<span>` around an input | `<goa-form-item label="…" error="…">` | Wrap the `Goab*` input in this, don't restyle it |
+| A row of buttons with flex styling | `<goa-button-group alignment="…">` | |
+
+Also available bare and worth knowing before hand-rolling: `goa-accordion`, `goa-details`,
+`goa-divider`, `goa-chip`, `goa-filter-chip`, `goa-icon`, `goa-icon-button`, `goa-link`,
+`goa-notification`, `goa-popover`, `goa-tooltip`, `goa-date-picker`, `goa-file-upload-input`,
+`goa-file-upload-card`, `goa-circular-progress`, `goa-linear-progress`, `goa-hero-banner`,
+`goa-page-block`. For the full set, list the registered element names from the installed package:
+
+```bash
+grep -rhoE 'customElements\.define\("goa-[a-z0-9-]+"' node_modules/@abgov/web-components \
+  | grep -oE 'goa-[a-z0-9-]+' | sort -u
+```
+
+For values rather than layout, use `formatters.ts` (`formatDate`, `formatDateTime`, `formatNumber`,
+`formatPercent`) rather than an inline `toLocaleString` — every view should render a date or a count
+the same way, and each formatter already returns an em dash for a null/unparseable value so a
+partially-populated record needs no per-field guard.
+
 ## What these wrappers do (and why they're needed)
 
 `goa-*` are framework-agnostic custom elements (built with Svelte). Three quirks
@@ -177,6 +222,13 @@ banners — not a single-element wrapper. Existing examples: `AppLayout`,
 
 ## Don't
 
+- **Don't write inline `style` for layout, spacing, or typography** in a component here or in a
+  view that consumes it. Use the elements in the catalog above. An inline style is a signal either
+  that the right element wasn't found, or that a pattern component is missing — both worth raising
+  rather than working around.
+- **Don't wrap a presentational element.** `primitives/` exists only to add `v-model` over elements
+  whose `_`-prefixed event Vue can't bind. `goa-container`, `goa-block`, `goa-grid`, `goa-text`,
+  `goa-table`, and `goa-tabs` have no model to bind — a wrapper would add a layer for nothing.
 - **Don't add new `goa-*` element wrappers to `patterns/`, or new composite
   components to `primitives/`.** Single-element wrappers belong in
   `primitives/` (interim, deleted on the `@abgov/vue-components` swap);

package/src/generators/vue-components/files/src/index.ts__tmpl__

@@ -9,6 +9,10 @@
 // PERMANENT: these have no equivalent in an official design-system package
 // (that's app-shell composition, not a design-system primitive) and are not
 // deleted when primitives/ is.
+//
+// formatters.ts — shared value formatting for views. PERMANENT, and not a
+// component: presentational goa-* elements need no wrapper, but every view
+// still has to render a date or a count the same way as every other view.
 export { default as GoabInput } from './lib/primitives/GoabInput.vue';
 export { default as GoabTextarea } from './lib/primitives/GoabTextarea.vue';
 export { default as GoabDropdown } from './lib/primitives/GoabDropdown.vue';
@@ -26,3 +30,11 @@ export { default as RecordDetailShell } from './lib/patterns/RecordDetailShell.v
 export { default as WorkspaceTable } from './lib/patterns/WorkspaceTable.vue';
 export { default as Stepper } from './lib/patterns/Stepper.vue';
 export { default as StepErrorSummary } from './lib/patterns/StepErrorSummary.vue';
+
+export {
+  formatCurrency,
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  formatPercent,
+} from './lib/formatters';