Pipeline modernization and Angular version migration for @gsa-sam/sam-ui-elements — the fourth tracer bullet of the SAM design-library Angular upgrade epic (IAEMOD-57412), following sam-styles (#732 on GSA/sam-styles), ngx-uswds-icons (#26 on GSA/ngx-uswds-icons), and ngx-uswds (#184 on GSA/ngx-uswds). Coordination/tracking lives on the internal research repo (mcaas-iae/iae-angular-upgrade).
sam-ui-elements sits at Angular 19 (published @gsa-sam/sam-ui-elements@19.0.0) and consumes only sam-styles (effectively done), so it is unblocked. It is the only design library that is not a compiled Angular library: it publishes raw TypeScript source (no main/module/exports; ~560 .ts), and the consumer compiles it in-place. Its formly is bundled and load-bearing in prod. See binding decision ADR-0009 on the coordination repo.
What makes this repo different
- Raw-source publish, not ng-packagr. No library
ng build; the consumer's own Angular compiler builds our source. Deep import paths (/src/formly/**, /src/ui-kit/**) are a frozen contract — no file moves this epic.
- Branch of record is
ng-19, not master. master lags at Angular 18.0.2; ng-19 is a strict content superset (the lone "master-only" commit is an empty merge bubble, 0 unique files). Reconcile by merging ng-19→master (no force).
- No GitHub Actions — only a commented-out CircleCI stub on Node 10.
- Test harness is rotten. Tests live in a separate
test-app/ that hard-links ../src in, but the harness is Angular 9 / TS 2.3 / ngx-formly 5 against a library at Angular 19 — the 107 specs have not been compiling against a matching Angular. Green-at-19 is the gate before any migration.
- formly kept + migrated, not deprecated.
AbstractSamFormly is imported in 15 files across 3 consumers, incl. prod — unlike uswds-formly (separate package, 0 consumers, cleanly removed). So ngx-formly 6→7 is in scope, gating Angular 20.
- rxjs already on 7 (peer
>=7.5.0) — no rxjs migration; ~6 rxjs-6-only imports survive in specs only, fixed during the green baseline.
Goal
Two bundled tracks, sequenced pipeline-first so the Angular migration lands on green CI:
- Pipeline/tooling — inherit the pattern proven on sam-styles, icons, and ngx-uswds: registry-pinned
.npmrc, normalized Node, ESLint (off tslint) with the a11y gate, Prettier, test + coverage, Dependabot, a PR template, dead-code pruning, Playwright smoke (replacing Protractor), and a tag-gated live npm publish.
- Angular migration — stepped per-major chain 19 → 20 → 21 (LTS), one major at a time, with the ngx-formly 6→7 migration as its own sub-issue gating the 20 step.
Parallelism model
Serialize anything that mutates package.json / angular.json / tsconfig; parallelize disjoint file sets. Prettier and dead-code prune are "stop the world" (run solo). The Angular chain is a serial train — one major at a time, nothing else editing manifests/source in flight.
Deferred (own follow-up issues, NOT this epic)
- Convert to a compiled ng-packagr library. Prereq: break the
src/ui-kit/filters → src/formly (FormlySAMUIModule) dependency cycle.
- Replace the
test-app copy-src-in harness with a standard in-repo Karma/Jest setup; retire test-app.
Notes / scope boundaries
- Migration is unblocked — sam-ui-elements consumes only sam-styles. Only the live publish sub-issue carries the DevOps dependency (OIDC Trusted Publisher registration, ADR-0007).
- Pin, don't break, the Angular-17 legacy consumer (
iae-sam-front-end3, IBM/legacy SAM). Major-locked peers make the version pin the natural outcome.
- Consumer validation is mandatory before publish:
npm pack --dry-run + audit every frozen deep path against the three consumers.
- Jira epic (this repo): IAEMOD-61187
- Program epic (SAM design-library Angular upgrade): IAEMOD-57412
Pipeline modernization and Angular version migration for
@gsa-sam/sam-ui-elements— the fourth tracer bullet of the SAM design-library Angular upgrade epic (IAEMOD-57412), following sam-styles (#732 on GSA/sam-styles), ngx-uswds-icons (#26 on GSA/ngx-uswds-icons), and ngx-uswds (#184 on GSA/ngx-uswds). Coordination/tracking lives on the internal research repo (mcaas-iae/iae-angular-upgrade).sam-ui-elements sits at Angular 19 (published
@gsa-sam/sam-ui-elements@19.0.0) and consumes only sam-styles (effectively done), so it is unblocked. It is the only design library that is not a compiled Angular library: it publishes raw TypeScript source (nomain/module/exports; ~560.ts), and the consumer compiles it in-place. Its formly is bundled and load-bearing in prod. See binding decision ADR-0009 on the coordination repo.What makes this repo different
ng build; the consumer's own Angular compiler builds our source. Deep import paths (/src/formly/**,/src/ui-kit/**) are a frozen contract — no file moves this epic.ng-19, notmaster.masterlags at Angular 18.0.2;ng-19is a strict content superset (the lone "master-only" commit is an empty merge bubble, 0 unique files). Reconcile by mergingng-19→master(no force).test-app/that hard-links../srcin, but the harness is Angular 9 / TS 2.3 / ngx-formly 5 against a library at Angular 19 — the 107 specs have not been compiling against a matching Angular. Green-at-19 is the gate before any migration.AbstractSamFormlyis imported in 15 files across 3 consumers, incl. prod — unlikeuswds-formly(separate package, 0 consumers, cleanly removed). So ngx-formly 6→7 is in scope, gating Angular 20.>=7.5.0) — no rxjs migration; ~6 rxjs-6-only imports survive in specs only, fixed during the green baseline.Goal
Two bundled tracks, sequenced pipeline-first so the Angular migration lands on green CI:
.npmrc, normalized Node, ESLint (off tslint) with the a11y gate, Prettier, test + coverage, Dependabot, a PR template, dead-code pruning, Playwright smoke (replacing Protractor), and a tag-gated livenpm publish.Parallelism model
Serialize anything that mutates
package.json/angular.json/tsconfig; parallelize disjoint file sets. Prettier and dead-code prune are "stop the world" (run solo). The Angular chain is a serial train — one major at a time, nothing else editing manifests/source in flight.Deferred (own follow-up issues, NOT this epic)
src/ui-kit/filters → src/formly(FormlySAMUIModule) dependency cycle.test-appcopy-src-in harness with a standard in-repo Karma/Jest setup; retiretest-app.Notes / scope boundaries
iae-sam-front-end3, IBM/legacy SAM). Major-locked peers make the version pin the natural outcome.npm pack --dry-run+ audit every frozen deep path against the three consumers.