JSONForms address field: country-filtered states, defaults, BC geocoder search (#42)

* feat(forms): add JSONForms address field with country-filtered states

- New Address control (@repo/react) dispatched on options.format:'address':
  searchable country combobox filters the states/provinces dropdown;
  per-country state/postal labels (curated ISO2 map); postal field hidden
  when the country has no postal system; changing country clears province.
  Degrades to plain text inputs without a GeoDataProvider. Editable +
  read-only display renderers + shared model/normalize helpers.
- GeoDataProvider hooks-port keeps the library API-agnostic; each web app
  supplies its own geo fetchers and mounts the provider once at the root.
- Public geo API (/v1/geo/countries, /v1/geo/countries/:id/states) added
  to both BFFs, reading geo reference data; integer :id validated -> 400.
- Form builder: 'address' palette entry + object-schema serialization.
- Postal codes validated against the country's regex on submit (422);
  drafts remain unvalidated. Address stored inline in submission JSONB.

* feat(forms): address field default country / state in the builder inspector

- Inspector: an address field gains a geo-powered defaults editor (default
  country + default state/province, reusing the same country-filtered
  dropdowns and per-country labels as the field). Changing the default
  country clears the default province.
- Model/codec: ControlNode carries defaultCountry/defaultProvince, serialized
  into the address property's JSON-Schema `default` and parsed back.
- Renderer: the address control seeds itself from schema.default when the
  field is still empty, so citizens see the pre-filled values (they can
  change them). The write is deferred a macrotask (a handleChange during the
  mount commit is dropped before JsonForms finishes init) and the seed flag
  flips inside the timer so the seed survives StrictMode's double-invoke.

* feat(forms): BC address geocoder autocomplete for the address field

- New "Search for your address" typeahead under the Country selector, shown
  only when the selected country/province is a server-supported geocoder region
  (v1: Canada / British Columbia, matched by ISO codes). As-you-type it queries
  the region's geocoder and fills Address line 1 + City on select (the geocoder
  returns no postal code, so postal stays manual).
- ISO-scoped, extensible geocoder proxy on both BFFs: GET /v1/geo/address-search
  and /address-search/regions (@public). A provider registry keyed by
  "<COUNTRY>:<PROVINCE>" (CA:BC -> BC OLS geocoder) registers a region only when
  its credentials are set; the API key stays server-side and never reaches the
  browser. Upstream errors degrade to [] (typing never 5xxs). The states read
  now exposes iso2 so the client can match regions.
- Env: optional BC_GEOCODER_API_KEY + BC_GEOCODER_URL (both apis); the field is
  hidden entirely when the geocoder is unconfigured.
- GeoData port gains optional searchAddresses + useAddressSearchRegions; both web
  apps wire them, with react-select(-async-paginate) added to optimizeDeps for
  the lazy form route.

* style(platform-web): console sidebar nav active-state accent border

Remove the link underline and add a left accent border to the console
sidebar nav items — a transparent border by default, bcgov-blue when active.

* fix(forms): enforce required validation on the address field

A required address only forced the object to EXIST, not its sub-fields — and
the control writes empty strings, so blank addresses passed. Now a required
address serializes the object's own required set (country, address line 1,
city, state/province, postal code — address line 2 stays optional) with
minLength:1, so empties are rejected by Ajv on both the client (JSONForms
submit gating) and the server (submit validation).

JSONForms attributes the sub-field (child-path) errors below the object
control, not on it, so the address field showed no message — the citizen saw
a disabled Submit with no reason. The control now derives requiredness from
the schema and renders its own per-field asterisk + "This field is required"
message (shown in validation-visible modes).

* fix(forms): show the selected address label, not raw JSON, in the search field

The address-search option value encodes the whole suggestion as JSON so a
pick can both fill the form and be mapped back. AsyncSelect's controlled-value
effect, with no resolver, was displaying that JSON value as the selected
label. Add a resolveValue that decodes the value back to the suggestion's
human `label` for display (via a shared parseSuggestion helper).

* feat(forms): default a new address field to Canada / British Columbia

createField('address') now seeds defaultCountry='Canada' and
defaultProvince='British Columbia', so a freshly-added address field
pre-fills those in the inspector's defaults editor and in the builder
preview. Authors can still change or clear them.

* feat(forms): show field defaults in the builder canvas card

The canvas field-card preview renders the control readonly, so the address
control's default-seeding effect (which skips readonly) never populated it —
the card showed an empty country/province. Seed the preview data from each
property's JSON-Schema `default`, so the address card reflects its Canada /
British Columbia default (and any future defaulted field shows its default).

* chore(charts): wire BC_GEOCODER_URL / BC_GEOCODER_API_KEY for the address search

Add BC_GEOCODER_URL (public BC OLS endpoint, non-sensitive) to the env
ConfigMap of both API charts, and document BC_GEOCODER_API_KEY as an optional
key in each app's existingSecret (values comments + charts README secret table
and create-secret example). Absent key → the address-search field is hidden.
The CI deploy's `helm dependency build` picks these up into the umbrella chart.

Author: sidmclaughlin

apps/citizen-portal-api/.env.example

@@ -65,3 +65,10 @@ OUTBOX_RELAY_MAX_ATTEMPTS=5
 # Public web origins the notification emails deep-link into (composed server-side from config).
 CITIZEN_WEB_URL=http://localhost:3000
 PLATFORM_WEB_URL=http://localhost:3001
+
+# --- Address geocoder (feature 154) -------------------------------------------------------------
+# BC OLS Physical Address Geocoder. Leave the key unset to disable the "Search for your address"
+# field (the CA/BC region is only registered when a key is present). Obtain a key from the BC API
+# portal (https://api.gov.bc.ca/devportal/api-directory). Secret — server-side only.
+BC_GEOCODER_URL=https://geocoder.api.gov.bc.ca
+# BC_GEOCODER_API_KEY=

apps/citizen-portal-api/src/app.module.ts

@@ -22,6 +22,7 @@ import { OutboxRelayModule } from './notifications/outbox-relay.module';
 import { NotificationsModule } from './modules/notifications/notifications.module';
 import { ApplicationsModule } from './modules/applications/applications.module';
 import { CatalogModule } from './modules/catalog/catalog.module';
+import { GeoModule } from './modules/geo/geo.module';
 import { ServiceAgreementsModule } from './modules/service-agreements/service-agreements.module';
 
 @Module({
@@ -107,6 +108,7 @@ import { ServiceAgreementsModule } from './modules/service-agreements/service-ag
     HealthModule.forRoot({ readiness: [DatabaseHealthIndicator] }),
     // Feature modules live under src/modules/<feature>/.
     CatalogModule,
+    GeoModule,
     ApplicationsModule,
     NotificationsModule,
     ServiceAgreementsModule,

apps/citizen-portal-api/src/config/env.schema.ts

@@ -72,6 +72,13 @@ export const envSchema = z.object({
   OUTBOX_RELAY_INTERVAL_MS: z.coerce.number().int().min(250).default(5000),
   OUTBOX_RELAY_BATCH_SIZE: z.coerce.number().int().min(1).max(100).default(10),
   OUTBOX_RELAY_MAX_ATTEMPTS: z.coerce.number().int().min(1).max(20).default(5),
+
+  // --- Address geocoder (feature 154) ------------------------------------------------------------
+  // BC OLS Physical Address Geocoder. OPTIONAL: when the API key is unset the CA/BC address-search
+  // region is not registered, so the web control hides the "Search for your address" field. The key
+  // is a secret — server-side only, attached to the upstream request, never sent to the browser.
+  BC_GEOCODER_URL: z.url().default('https://geocoder.api.gov.bc.ca'),
+  BC_GEOCODER_API_KEY: z.string().optional(),
 });
 
 export type Env = z.infer<typeof envSchema>;

apps/citizen-portal-api/src/modules/applications/services/applications.service.ts

@@ -3,6 +3,7 @@ import { ConfigService } from '@nestjs/config';
 import { UnprocessableEntityException } from '@nestjs/common';
 import {
   type Database,
+  countries,
   documentReferences,
   documentVersions,
   documents,
@@ -14,7 +15,7 @@ import {
   workspaces,
 } from '@repo/database';
 import { InjectDatabase } from '@repo/nestjs/database';
-import { and, desc, eq } from 'drizzle-orm';
+import { and, desc, eq, inArray } from 'drizzle-orm';
 import {
   type ApplicationDetail,
   type MyApplication,
@@ -29,7 +30,11 @@ import {
 import type { Env } from '../../../config/env.schema';
 import { enqueueNotification } from '../../../notifications/enqueue';
 import { staffSubmissionContent, submissionReceivedContent } from '../util/notification-content';
-import { validateSubmission } from '../util/validate';
+import {
+  collectAddressPostals,
+  validateAddressPostals,
+  validateSubmission,
+} from '../util/validate';
 import { ConsentService } from './consent.service';
 
 const FORM_KINDS = new Set(['basic-form', 'multi-stage-form']);
@@ -255,6 +260,29 @@ export class ApplicationsService {
     return this.toDto(sub, this.expectRow(updated[0]));
   }
 
+  /**
+   * Resolve each address field's postal code against the entered country's regex (from geo reference
+   * data). Returns error strings (empty = all valid). Countries with no known regex impose no
+   * constraint; no address fields → no DB read.
+   */
+  private async validateAddressPostals(
+    kind: string,
+    structure: Record<string, unknown>,
+    data: Record<string, unknown>,
+  ): Promise<string[]> {
+    const entries = collectAddressPostals(kind, structure, data);
+    if (entries.length === 0) {
+      return [];
+    }
+    const names = [...new Set(entries.map((entry) => entry.country))];
+    const rows = await this.db
+      .select({ name: countries.name, regex: countries.postalCodeRegex })
+      .from(countries)
+      .where(inArray(countries.name, names));
+    const regexByCountry = new Map(rows.map((row) => [row.name, row.regex]));
+    return validateAddressPostals(entries, (country) => regexByCountry.get(country) ?? null);
+  }
+
   /**
    * Submit the application: validate the answers against the form schema (422 on failure), then
    * persist the final answers and advance draft → pending. Validation runs only here — drafts are
@@ -275,6 +303,15 @@ export class ApplicationsService {
         errors: result.errors,
       });
     }
+    // Address fields (feature 153): postal codes are validated against the entered country's regex
+    // (resolved from geo reference data — country-dependent, so it can't live in the static schema).
+    const postalErrors = await this.validateAddressPostals(form.kind, form.structure, data);
+    if (postalErrors.length > 0) {
+      throw new UnprocessableEntityException({
+        message: 'The application has validation errors',
+        errors: postalErrors,
+      });
+    }
     // Consent gate: every required service agreement must be approved (against its current version).
     await this.consent.assertSubmittableForForm(userId, sub.documentVersionId);
     // Pre-resolve the citizen's contact email (read BEFORE the tx) for the notification seed.

apps/citizen-portal-api/src/modules/applications/util/validate.ts

@@ -22,6 +22,7 @@ function validateAgainst(schema: Record<string, unknown>, data: unknown): string
 
 interface MultiStagePage {
   schema?: Record<string, unknown>;
+  uischema?: Record<string, unknown>;
 }
 interface MultiStageStage {
   pages?: MultiStagePage[];
@@ -46,3 +47,103 @@ export function validateSubmission(
   const errors = schemas.flatMap((schema) => validateAgainst(schema, data));
   return { valid: errors.length === 0, errors };
 }
+
+// ── Address postal-code validation (feature 153) ─────────────────────────────────────────────────
+//
+// The address control (`options.format: 'address'`) stores an object under its property key. The
+// postal-code format is country-dependent and only known at submit time, so it can't live in the
+// static JSON Schema — we resolve the entered country's regex (from geo reference data) at submit.
+
+/** A postal code to validate: the field key, the entered country name, and the entered postal. */
+export interface AddressPostalEntry {
+  key: string;
+  country: string;
+  postal: string;
+}
+
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  value && typeof value === 'object' ? (value as Record<string, unknown>) : undefined;
+
+const asText = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+const ADDRESS_SCOPE = /^#\/properties\/(.+)$/;
+
+/** Recursively collect the property keys of every address control in a uischema tree. */
+function addressKeysFromUischema(uischema: Record<string, unknown> | undefined): string[] {
+  if (!uischema) {
+    return [];
+  }
+  const keys: string[] = [];
+  const options = asRecord(uischema.options);
+  if (uischema.type === 'Control' && options?.format === 'address') {
+    const key = ADDRESS_SCOPE.exec(asText(uischema.scope))?.[1];
+    if (key !== undefined) {
+      keys.push(key);
+    }
+  }
+  const elements = Array.isArray(uischema.elements) ? uischema.elements : [];
+  for (const child of elements) {
+    keys.push(...addressKeysFromUischema(asRecord(child)));
+  }
+  return keys;
+}
+
+/**
+ * Find every address field in the form + the citizen's entered country/postal for it. Only entries
+ * with BOTH a country and a non-empty postal are returned (empty postal is allowed — postal
+ * requiredness is not enforced here). Basic forms carry one uischema; multi-stage forms carry one per
+ * page.
+ */
+export function collectAddressPostals(
+  kind: string,
+  structure: Record<string, unknown>,
+  data: unknown,
+): AddressPostalEntry[] {
+  const uischemas: Array<Record<string, unknown> | undefined> =
+    kind === 'multi-stage-form'
+      ? ((structure['stages'] as MultiStageStage[] | undefined) ?? []).flatMap((stage) =>
+          (stage.pages ?? []).map((page) => page.uischema),
+        )
+      : [structure['uischema'] as Record<string, unknown> | undefined];
+  const record = asRecord(data) ?? {};
+  const keys = [...new Set(uischemas.flatMap(addressKeysFromUischema))];
+  return keys.flatMap((key): AddressPostalEntry[] => {
+    const address = asRecord(record[key]);
+    if (!address) {
+      return [];
+    }
+    const country = asText(address.country);
+    const postal = asText(address.postal_code);
+    return country && postal ? [{ key, country, postal }] : [];
+  });
+}
+
+/**
+ * Validate each collected postal against a per-country regex resolver (backed by geo reference data
+ * in the service). A country with no known regex (or an unknown country) imposes no constraint. A
+ * malformed regex is treated as "no constraint" (never throws). Returns human-readable error strings.
+ */
+export function validateAddressPostals(
+  entries: AddressPostalEntry[],
+  regexFor: (country: string) => string | null | undefined,
+): string[] {
+  const errors: string[] = [];
+  for (const entry of entries) {
+    const pattern = regexFor(entry.country);
+    if (!pattern) {
+      continue;
+    }
+    let re: RegExp;
+    try {
+      re = new RegExp(pattern);
+    } catch {
+      continue;
+    }
+    if (!re.test(entry.postal)) {
+      errors.push(
+        `${entry.key}: "${entry.postal}" is not a valid postal code for ${entry.country}`,
+      );
+    }
+  }
+  return errors;
+}

apps/citizen-portal-api/src/modules/geo/controllers/geo-v1.controller.ts

@@ -0,0 +1,57 @@
+import { Controller, Get, Param, Query } from '@nestjs/common';
+import { ApiTags } from '@nestjs/swagger';
+import { Public } from '@repo/nestjs/auth';
+import { ZodSerializerDto } from 'nestjs-zod';
+
+import {
+  AddressSearchQueryDto,
+  AddressSearchRegionListDto,
+  AddressSuggestionListDto,
+  GeoCountryListDto,
+  GeoStateListDto,
+} from '../dtos/geo.dtos';
+import { GeoService } from '../services/geo.service';
+import { GeocoderService } from '../services/geocoder.service';
+
+/**
+ * `/v1/geo` — PUBLIC reference data for the address form field (feature 153). Countries and their
+ * states/provinces. Every route is `@Public` (no user data, no writes).
+ */
+@ApiTags('Geo')
+@Controller({ path: 'geo', version: '1' })
+export class GeoV1Controller {
+  constructor(
+    private readonly geo: GeoService,
+    private readonly geocoder: GeocoderService,
+  ) {}
+
+  @Public()
+  @Get('countries')
+  @ZodSerializerDto(GeoCountryListDto)
+  async listCountries() {
+    return { items: await this.geo.listCountries() };
+  }
+
+  @Public()
+  @Get('countries/:id/states')
+  @ZodSerializerDto(GeoStateListDto)
+  async listStates(@Param('id') id: string) {
+    return { items: await this.geo.listStates(id) };
+  }
+
+  // The (country, province) ISO2 pairs the server can run address search for (feature 154). Empty
+  // when no geocoder is configured → the web control hides the "Search for your address" field.
+  @Public()
+  @Get('address-search/regions')
+  @ZodSerializerDto(AddressSearchRegionListDto)
+  addressSearchRegions() {
+    return { items: this.geocoder.regions() };
+  }
+
+  @Public()
+  @Get('address-search')
+  @ZodSerializerDto(AddressSuggestionListDto)
+  async addressSearch(@Query() query: AddressSearchQueryDto) {
+    return { items: await this.geocoder.search(query.country, query.province, query.q) };
+  }
+}

apps/citizen-portal-api/src/modules/geo/dtos/geo.dtos.ts

@@ -0,0 +1,69 @@
+import { createZodDto } from 'nestjs-zod';
+import { z } from 'zod';
+
+/**
+ * DTOs for the public geo reference-data endpoints (feature 153). Read-only projections of
+ * `geo.countries` / `geo.states` (feature 152) — just the fields the address form field needs.
+ * Response DTOs serialize handler output via @ZodSerializerDto.
+ */
+
+/**
+ * A country option for the address field's country combobox. `iso2` drives the per-country label
+ * lookup; `hasStates` tells the client to show a states dropdown vs a free-text province input;
+ * `hasPostal` hides the postal field for countries with no postal system.
+ */
+export const geoCountrySchema = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  iso2: z.string().nullable(),
+  hasStates: z.boolean(),
+  hasPostal: z.boolean(),
+});
+export type GeoCountry = z.infer<typeof geoCountrySchema>;
+export class GeoCountryListDto extends createZodDto(
+  z.object({ items: z.array(geoCountrySchema) }),
+) {}
+
+/** A state / province / region under a country. `type` is the upstream subdivision type, if known.
+ * `iso2` is the ISO 3166-2 subdivision code (e.g. `BC`), used to match address-search regions. */
+export const geoStateSchema = z.object({
+  id: z.number().int(),
+  name: z.string(),
+  type: z.string().nullable(),
+  iso2: z.string().nullable(),
+});
+export type GeoState = z.infer<typeof geoStateSchema>;
+export class GeoStateListDto extends createZodDto(z.object({ items: z.array(geoStateSchema) })) {}
+
+// ── Address search (feature 154) ─────────────────────────────────────────────────────────────────
+
+/** A (country, province) ISO2 pair the server can run address search for. */
+export const addressSearchRegionSchema = z.object({
+  country: z.string(),
+  province: z.string(),
+});
+export type AddressSearchRegion = z.infer<typeof addressSearchRegionSchema>;
+export class AddressSearchRegionListDto extends createZodDto(
+  z.object({ items: z.array(addressSearchRegionSchema) }),
+) {}
+
+/** A normalized address suggestion (no postal code — the BC geocoder returns none). */
+export const addressSuggestionSchema = z.object({
+  label: z.string(),
+  streetAddress: z.string(),
+  city: z.string(),
+  provinceCode: z.string(),
+});
+export type AddressSuggestion = z.infer<typeof addressSuggestionSchema>;
+export class AddressSuggestionListDto extends createZodDto(
+  z.object({ items: z.array(addressSuggestionSchema) }),
+) {}
+
+/** `GET /v1/geo/address-search` query — ISO2 country + province + the typed text. */
+export const addressSearchQuerySchema = z.object({
+  country: z.string().trim().min(2).max(3),
+  province: z.string().trim().min(1).max(3),
+  q: z.string().trim().min(1).max(100),
+});
+export type AddressSearchQuery = z.infer<typeof addressSearchQuerySchema>;
+export class AddressSearchQueryDto extends createZodDto(addressSearchQuerySchema) {}

apps/citizen-portal-api/src/modules/geo/geo.module.ts

@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+
+import { GeoV1Controller } from './controllers/geo-v1.controller';
+import { GeoService } from './services/geo.service';
+import { GeocoderService } from './services/geocoder.service';
+
+/**
+ * Public geo reference data (feature 153): countries + states/provinces for the address form field.
+ * Read-only, workspace-free. Imported by AppModule.
+ */
+@Module({
+  controllers: [GeoV1Controller],
+  providers: [GeoService, GeocoderService],
+})
+export class GeoModule {}