Skip to content

ADR-027: Adopt m3e-angular for Material 3 Expressive components

Status

In-Review, 2026-10-27. Foundation PR #4598. It adds the dependency and smoke specs only; no screen changes. It supersedes the vendored-tarball experiment in #4485.

Context

Angular Material 22 has no Material 3 Expressive dialog, stepper or navigation rail. The search import wizard needs a multi-step dialog, and the wider web app is migrating towards Material 3. @camaradesuk/m3e-angular (MIT, public npm) provides MatExp* components that compose Material and CDK primitives and keep the application owning form state, validation and actions.

Decision

  1. Depend on @camaradesuk/m3e-angular at the exact version 0.1.0-alpha.7 from public npm, with its peer gsap at exact 3.15.0. No vendored tarball.
  2. Adopt components surface by surface. Native MatDialog stays in place until each dialog migrates.
  3. No global setup is added by the foundation. Component styles are opt-in Sass mixins (@use '@camaradesuk/m3e-angular' as mat-exp; @include mat-exp.mat-exp-dialog-styles();), added in the PR that first renders a component.
  4. Feature flag: none. Nothing user-visible changes; the first consumer (the search import wizard) is behind searchImportWizard.

Consequences

  • MatExpDialogRef is not type-identical to MatDialogRef. Each dialog migrates explicitly (injects MatExpDialogRef, opens through MatExpDialog); there is no drop-in swap. MAT_DIALOG_DATA is unchanged.
  • Dialog migration (#4599): every dialog moves to m3e through the SyRF layer in src/services/web/src/app/shared/dialog/ (SyrfDialogService, <syrf-dialog-layout>, [syrfDialogClose], injectSyrfDialogRef()), which opens MatExpDialog when the default-off expressiveDialogs flag is on and MatDialog when it is off. A guard spec stops new native dialog usage. Plan: dialog migration.
  • MatExpDialog.open requires mode ('adaptive' or 'alert') and a non-empty title.
  • The package is pre-release. Upgrades are deliberate PRs, never range-driven.
  • Licences: @camaradesuk/m3e-angular is MIT. Its required peer gsap (3.13 and later) ships under GreenSock's Standard "no charge" licence, which is free of charge (including commercial use) under its own terms but is not an OSI licence. It is accepted because m3e-angular's spring motion is built on it; a licence audit should record it as such.
  • Smoke specs in src/services/web/src/app/shared/m3e/ fail fast if an upgrade breaks the dialog or stepper contract.