@abgov/nx-adsp 13.25.0 → 13.27.0

package/package.json

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

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

@@ -7,7 +7,7 @@ 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** |
+| `src/lib/patterns/` | Composite, app-shell components (`AppLayout`, `AppHeader`, `AppFooter`, `AppSideMenu`, `SessionExpiredBanner`, `RecordDetailShell`, `WorkspaceTable`, `Stepper`, `StepErrorSummary`, `FilterBar`) | **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`,
@@ -66,10 +66,11 @@ inline styles.
 | 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="…">` | |
+| A hand-built filter row above a table | `<FilterBar>` (this library) | Controls, collapse, active-filter chips and clear-all. It emits a query-ready values object; the *view* owns resetting the page, debouncing, and URL sync |
 
 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-notification`, `goa-popover`, `goa-tooltip`, `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:
 
@@ -111,6 +112,7 @@ the design system supports keeps working without being re-declared.
 | `GoabCheckbox` | `goa-checkbox` | `boolean` | `$event.detail.checked` |
 | `GoabButton` | `goa-button` | — (re-exposes `_click` as `@click`) | — |
 | `GoabModal` | `goa-modal` | `open: boolean` (`v-model:open`) | `_close` clears it |
+| `GoabDatePicker` | `goa-date-picker` | `Date \| undefined` | `$event.detail.value` is a **`Date`**, not a string (`valueStr` carries the string form) |
 
 Most value elements put the value on `detail.value`; some carry extra keys
 (dropdown adds `label`, radio-group adds `labels`) you can ignore unless you need

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

@@ -20,6 +20,7 @@ export { default as GoabCheckbox } from './lib/primitives/GoabCheckbox.vue';
 export { default as GoabRadioGroup } from './lib/primitives/GoabRadioGroup.vue';
 export { default as GoabButton } from './lib/primitives/GoabButton.vue';
 export { default as GoabModal } from './lib/primitives/GoabModal.vue';
+export { default as GoabDatePicker } from './lib/primitives/GoabDatePicker.vue';
 
 export { default as AppLayout } from './lib/patterns/AppLayout.vue';
 export { default as AppHeader } from './lib/patterns/AppHeader.vue';
@@ -30,6 +31,7 @@ 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 { default as FilterBar } from './lib/patterns/FilterBar.vue';
 
 export {
   formatCurrency,

package/src/generators/vue-components/files/src/lib/patterns/FilterBar.spec.ts__tmpl__

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { mount } from '@vue/test-utils';
+import FilterBar from './FilterBar.vue';
+
+// FilterBar is presentational: values in via v-model, values out via
+// update:modelValue, and nothing else. These tests pin that contract -- notably
+// that it never reaches for the page, the router, or the network.
+//
+// These mount goa-* elements, so Vue logs "Failed to resolve component" unless
+// this project's vite config sets isCustomElement (see AGENTS.md > Testing).
+// The assertions pass either way -- the option only silences the warnings.
+const filters = [
+  {
+    key: 'status',
+    label: 'Status',
+    type: 'dropdown' as const,
+    options: [
+      { value: 'active', label: 'Active' },
+      { value: 'closed', label: 'Closed' },
+    ],
+  },
+  { key: 'from', label: 'From', type: 'date' as const },
+];
+
+function mountBar(modelValue: Record<string, string> = {}) {
+  return mount(FilterBar, {
+    props: { filters, modelValue },
+    global: { stubs: { GoabDropdown: true, GoabDatePicker: true, GoabButton: true } },
+  });
+}
+
+describe('FilterBar', () => {
+  it('renders one form item per filter', () => {
+    const wrapper = mountBar();
+    expect(wrapper.findAll('goa-form-item')).toHaveLength(2);
+  });
+
+  it('shows no chips and no clear-all when nothing is filtered', () => {
+    const wrapper = mountBar();
+    expect(wrapper.find('goa-filter-chip').exists()).toBe(false);
+  });
+
+  it('renders a chip per active filter, labelled with the option label not its value', () => {
+    const wrapper = mountBar({ status: 'active' });
+    const chips = wrapper.findAll('goa-filter-chip');
+    expect(chips).toHaveLength(1);
+    expect(chips[0].attributes('content')).toBe('Status: Active');
+  });
+
+  it('falls back to the raw value when no option matches (e.g. a date)', () => {
+    const wrapper = mountBar({ from: '2026-08-28' });
+    expect(wrapper.find('goa-filter-chip').attributes('content')).toBe(
+      'From: 2026-08-28',
+    );
+  });
+
+  it('emits the whole values object, not a partial patch', async () => {
+    const wrapper = mountBar({ status: 'active' });
+    // Dismissing a chip clears that one key and keeps the rest of the object.
+    await wrapper.find('goa-filter-chip').trigger('_click');
+    const emitted = wrapper.emitted('update:modelValue');
+    expect(emitted?.[0][0]).toEqual({ status: '' });
+  });
+
+  it('collapses behind goa-details only when asked', () => {
+    expect(mountBar().find('goa-details').exists()).toBe(false);
+    const collapsible = mount(FilterBar, {
+      props: { filters, modelValue: {}, collapsible: true, heading: 'Filters' },
+      global: { stubs: { GoabDropdown: true, GoabDatePicker: true, GoabButton: true } },
+    });
+    expect(collapsible.find('goa-details').exists()).toBe(true);
+  });
+});
+
+describe('FilterBar date handling', () => {
+  it('serialises a picked Date to YYYY-MM-DD for the query string', async () => {
+    const wrapper = mount(FilterBar, {
+      props: { filters, modelValue: {} },
+      global: { stubs: { GoabDropdown: true, GoabButton: true } },
+    });
+    const picker = wrapper.findComponent({ name: 'GoabDatePicker' });
+    // Local midnight is what a date picker yields for a picked calendar date.
+    // A UTC instant here would make the assertion timezone-dependent.
+    await picker.vm.$emit('update:modelValue', new Date(2026, 7, 28));
+    expect(wrapper.emitted('update:modelValue')?.[0][0]).toEqual({
+      from: '2026-08-28',
+    });
+  });
+
+  it('clears the key when the date is cleared', async () => {
+    const wrapper = mount(FilterBar, {
+      props: { filters, modelValue: { from: '2026-08-28' } },
+      global: { stubs: { GoabDropdown: true, GoabButton: true } },
+    });
+    const picker = wrapper.findComponent({ name: 'GoabDatePicker' });
+    await picker.vm.$emit('update:modelValue', undefined);
+    expect(wrapper.emitted('update:modelValue')?.[0][0]).toEqual({ from: '' });
+  });
+});
+
+const dateOnlyFilters = [{ key: 'from', label: 'From', type: 'date' as const }];
+const stubs = { GoabDropdown: true, GoabButton: true };
+
+describe('date round-trip preserves the calendar date the user picked', () => {
+  it('serialises the picked calendar date, not its UTC date', async () => {
+    const wrapper = mount(FilterBar, { props: { filters: dateOnlyFilters, modelValue: {} }, global: { stubs } });
+    // What a picker yields for "28 Aug 2026": local midnight.
+    const localMidnight = new Date(2026, 7, 28, 0, 0, 0);
+    await wrapper.findComponent({ name: 'GoabDatePicker' }).vm.$emit('update:modelValue', localMidnight);
+    expect(wrapper.emitted('update:modelValue')?.[0][0]).toEqual({ from: '2026-08-28' });
+  });
+
+  it('parses a stored YYYY-MM-DD back to the same local calendar date', () => {
+    const wrapper = mount(FilterBar, {
+      props: { filters: dateOnlyFilters, modelValue: { from: '2026-08-28' } },
+      global: { stubs },
+    });
+    const back = wrapper.findComponent({ name: 'GoabDatePicker' }).props('modelValue') as Date;
+    expect([back.getFullYear(), back.getMonth() + 1, back.getDate()]).toEqual([2026, 8, 28]);
+  });
+});

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

@@ -0,0 +1,158 @@
+<script setup lang="ts">
+// The presentation half of a filtered list: control layout, collapse, the
+// active-filter chips, and clear-all. Deliberately NOT the query half — it
+// emits a values object and nothing else, so it stays presentational per this
+// library's rules (accept data via props, report via emit, no side effects).
+//
+// What that means for the consumer: resetting the page to 1, debouncing, and
+// syncing to the URL all belong to the view, which owns `page` and the router.
+// A component can't reach either without becoming stateful.
+//
+// Values are strings, query-ready, so a view can hand the object straight to
+// useApi's `filters`. A `date` filter converts its Date to YYYY-MM-DD here,
+// which is a format decision this component can make because it chose the
+// control; anything richer belongs in the view.
+//
+// Both date conversions use local calendar parts, never toISOString() or
+// `new Date(string)`. Those route through UTC, which shifts the date by a day on
+// one side of midnight or the other: in Alberta (UTC-6/-7) `new Date('2026-08-28')`
+// is 27 Aug 18:00 local, so a stored date would render as the day before.
+import { computed } from 'vue';
+import GoabDropdown from '../primitives/GoabDropdown.vue';
+import GoabDatePicker from '../primitives/GoabDatePicker.vue';
+import GoabButton from '../primitives/GoabButton.vue';
+
+export interface FilterOption {
+  value: string;
+  label: string;
+}
+
+export interface FilterDescriptor {
+  key: string;
+  label: string;
+  type: 'dropdown' | 'date';
+  /** Dropdown only. May arrive after mount when fetched — it's a prop. */
+  options?: FilterOption[];
+  /** Dropdown only. Label for the "no filter" choice. */
+  anyLabel?: string;
+}
+
+const props = withDefaults(
+  defineProps<{
+    filters: FilterDescriptor[];
+    /** Collapse the controls behind a disclosure. Chips stay visible. */
+    collapsible?: boolean;
+    heading?: string;
+  }>(),
+  { collapsible: false, heading: 'Filters' },
+);
+
+// Record<key, value>; an empty string means "not filtering on this".
+const model = defineModel<Record<string, string>>({ default: () => ({}) });
+
+const active = computed(() =>
+  props.filters
+    .filter((filter) => !!model.value[filter.key])
+    .map((filter) => ({
+      ...filter,
+      value: model.value[filter.key],
+      display:
+        filter.options?.find((o) => o.value === model.value[filter.key])
+          ?.label ?? model.value[filter.key],
+    })),
+);
+
+// Parsed once per model change, not per render: handing goa-date-picker a fresh
+// Date object every render would re-set its value on each tick.
+const dateValues = computed(() =>
+  Object.fromEntries(
+    props.filters
+      .filter((filter) => filter.type === 'date')
+      .map((filter) => [
+        filter.key,
+        model.value[filter.key]
+          ? fromIsoDate(model.value[filter.key])
+          : undefined,
+      ]),
+  ),
+);
+
+// Local-calendar YYYY-MM-DD -- see the header note on why not toISOString().
+function toIsoDate(date: Date): string {
+  const pad = (part: number) => String(part).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
+function fromIsoDate(value: string): Date | undefined {
+  const [year, month, day] = value.split('-').map(Number);
+  return year && month && day ? new Date(year, month - 1, day) : undefined;
+}
+
+function set(key: string, value: string) {
+  model.value = { ...model.value, [key]: value };
+}
+
+function setDate(key: string, date: Date | undefined) {
+  set(key, date ? toIsoDate(date) : '');
+}
+
+function clearAll() {
+  model.value = Object.fromEntries(
+    props.filters.map((filter) => [filter.key, '']),
+  );
+}
+</script>
+
+<template>
+  <div>
+    <component
+      :is="collapsible ? 'goa-details' : 'div'"
+      v-bind="collapsible ? { heading } : {}"
+    >
+      <goa-block gap="m" direction="row" alignment="end">
+        <goa-form-item
+          v-for="filter in filters"
+          :key="filter.key"
+          :label="filter.label"
+        >
+          <GoabDropdown
+            v-if="filter.type === 'dropdown'"
+            :model-value="model[filter.key] ?? ''"
+            :name="filter.key"
+            @update:model-value="(value: string) => set(filter.key, value)"
+          >
+            <goa-dropdown-item value="" :label="filter.anyLabel ?? 'Any'" />
+            <goa-dropdown-item
+              v-for="option in filter.options ?? []"
+              :key="option.value"
+              :value="option.value"
+              :label="option.label"
+            />
+          </GoabDropdown>
+          <GoabDatePicker
+            v-else
+            :model-value="dateValues[filter.key]"
+            :name="filter.key"
+            @update:model-value="(date: Date | undefined) => setDate(filter.key, date)"
+          />
+        </goa-form-item>
+      </goa-block>
+    </component>
+
+    <template v-if="active.length">
+      <goa-spacer vspacing="s" />
+      <goa-block gap="xs" direction="row" alignment="center">
+        <goa-filter-chip
+          v-for="filter in active"
+          :key="filter.key"
+          :content="`${filter.label}: ${filter.display}`"
+          :aria-label="`Remove ${filter.label} filter`"
+          @_click="set(filter.key, '')"
+        />
+        <GoabButton type="tertiary" size="compact" @click="clearAll">
+          Clear all
+        </GoabButton>
+      </goa-block>
+    </template>
+  </div>
+</template>

package/src/generators/vue-components/files/src/lib/primitives/GoabDatePicker.spec.ts__tmpl__

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { mount } from '@vue/test-utils';
+import GoabDatePicker from './GoabDatePicker.vue';
+
+// Pins the event contract read out of the installed @abgov/web-components:
+// goa-date-picker dispatches _change with { name, value: Date, valueStr: string }.
+// Every other value wrapper here reads a string off detail.value; this one does
+// not, so the contract is worth a test rather than a comment alone.
+describe('GoabDatePicker', () => {
+  it('takes the Date off detail.value, not detail.valueStr', async () => {
+    const wrapper = mount(GoabDatePicker, { props: { modelValue: undefined } });
+    const date = new Date('2026-08-28T00:00:00.000Z');
+    await wrapper
+      .find('goa-date-picker')
+      .element.dispatchEvent(
+        new CustomEvent('_change', {
+          detail: { name: 'from', value: date, valueStr: '2026-08-28' },
+        }),
+      );
+    expect(wrapper.emitted('update:modelValue')?.[0][0]).toBeInstanceOf(Date);
+    expect(wrapper.emitted('update:modelValue')?.[0][0]).toEqual(date);
+  });
+
+  it('passes the model down as the element value', () => {
+    const date = new Date('2026-01-02T00:00:00.000Z');
+    const wrapper = mount(GoabDatePicker, { props: { modelValue: date } });
+    expect(wrapper.find('goa-date-picker').exists()).toBe(true);
+  });
+});

package/src/generators/vue-components/files/src/lib/primitives/GoabDatePicker.vue__tmpl__

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+// INTERIM WRAPPER — remove once GoA DS publishes @abgov/vue-components (see
+// GoabInput.vue for the full rationale). Adds v-model to <goa-date-picker>.
+//
+// The model is a Date, not a string: goa-date-picker's _change detail is
+// { name, value: Date, valueStr: string } — verified against the installed
+// package, where the dispatch reads `value: j.date, valueStr: r`. That makes it
+// the one element here whose detail.value isn't the string the other value
+// wrappers read, so it does not use skeleton A verbatim.
+//
+// Consumers that need a wire format (a query parameter, a JSON body) convert at
+// that boundary — `date?.toISOString().slice(0, 10)` for YYYY-MM-DD — rather
+// than this wrapper guessing which format is wanted.
+//
+// Usage: <GoabDatePicker v-model="startDate" name="startDate" :max="new Date()" />
+const model = defineModel<Date | undefined>();
+
+function onChange(e: Event) {
+  model.value = (e as CustomEvent<{ value: Date }>).detail.value;
+}
+</script>
+
+<template>
+  <goa-date-picker :value="model" @_change="onChange">
+    <slot />
+  </goa-date-picker>
+</template>

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

@@ -14,6 +14,7 @@ describe('vue-components', () => {
       'GoabRadioGroup',
       'GoabButton',
       'GoabModal',
+      'GoabDatePicker',
     ]) {
       expect(lib[name as keyof typeof lib]).toBeTruthy();
     }
@@ -41,6 +42,7 @@ describe('vue-components', () => {
       'WorkspaceTable',
       'Stepper',
       'StepErrorSummary',
+      'FilterBar',
     ]) {
       expect(lib[name as keyof typeof lib]).toBeTruthy();
     }

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

@@ -58,6 +58,50 @@ describe('Vue Components Generator', () => {
     expect(index).toContain('export { default as AppLayout }');
     expect(index).toContain('@abgov/vue-components'); // interim marker
     expect(index).toContain("from './lib/formatters'");
+    expect(index).toContain('export { default as GoabDatePicker }');
+    expect(index).toContain('export { default as FilterBar }');
+
+    // GoabDatePicker is the one wrapper whose _change detail.value is a Date
+    // rather than a string -- verified against the installed web-components,
+    // where the dispatch reads `value: j.date, valueStr: r`.
+    const datePicker = host
+      .read('libs/vue-components/src/lib/primitives/GoabDatePicker.vue')
+      .toString();
+    expect(datePicker).toContain('defineModel<Date | undefined>()');
+    expect(datePicker).toContain('CustomEvent<{ value: Date }>');
+
+    // FilterBar stays presentational: it emits a query-ready values object and
+    // never touches the page, the router, or the network.
+    const filterBar = host
+      .read('libs/vue-components/src/lib/patterns/FilterBar.vue')
+      .toString();
+    expect(filterBar).toContain('goa-filter-chip');
+    expect(filterBar).toContain('goa-details');
+    // Precise API forms, not bare words -- 'page' appears in the component's own
+    // comment explaining that the *view* owns it.
+    for (const forbidden of [
+      'useRouter',
+      'useRoute',
+      'apiFetch',
+      'fetch(',
+      'page.value',
+    ]) {
+      expect(filterBar).not.toContain(forbidden);
+    }
+    // Local calendar parts, not UTC: in Alberta new Date('2026-08-28') is
+    // 27 Aug 18:00 local, so a stored date would render as the day before.
+    expect(filterBar).toContain('function toIsoDate');
+    expect(filterBar).toContain('function fromIsoDate');
+    // The call form, not the bare name: the component's own comments explain why
+    // toISOString() is wrong, so the name legitimately appears in them.
+    expect(filterBar).not.toContain('date.toISOString()');
+
+    for (const spec of [
+      'libs/vue-components/src/lib/patterns/FilterBar.spec.ts',
+      'libs/vue-components/src/lib/primitives/GoabDatePicker.spec.ts',
+    ]) {
+      expect(host.exists(spec)).toBeTruthy();
+    }
 
     // Shared value formatters: every view renders a date/count the same way
     // instead of inlining its own toLocaleString (which is what a real app did