SamLayouts

✨ Your new, shiny Nx workspace is ready ✨.

Learn more about this workspace setup and its capabilities or run npx nx graph to visually explore what was created. Now, let's get you up to speed!

Run tasks

This workspace uses Angular's native Vitest runner. Run both suites with coverage and enforce the checked-in per-project floors with:

npm run test:coverage

Coverage floors are recorded in coverage-thresholds.json for statements, branches, functions, and lines. They are explicit initial Vitest baselines measured from the current source include scope (src/**/*.ts, excluding tests and declarations): the library baseline is 64.13/59.37/52.73/60.11% and the application baseline is 100% for each metric. These are proposed migration baselines pending human review; they are not Jest carryovers. The current Angular 21 run has 34 library tests and 3 app tests, including direct-standalone feedback and custom landing-icon rendering regressions; module-loading smoke suites remain scope/evaluation evidence rather than behavioral coverage. npm run coverage:bump may only raise a floor to a newer measured percentage; lowering a floor requires a deliberate configuration change and rationale. Missing, malformed, empty, or stale reports fail closed. Coverage demonstrates instrumented source behavior; module loading is only scope/evaluation evidence, not a claim of behavioral coverage.

Angular 21 consumer migration

@gsa-sam/layouts@21.0.0 targets Angular 21. Its components and directives are standalone, so new consumers may import them directly. Existing NgModule consumers remain supported through the exported compatibility modules (SdsHeaderModule, SdsFooterModule, and the other feature modules); no selector or module import needs to change solely for this upgrade.

The package now declares every runtime external emitted by its FESM as a peer dependency. Consumers must install peers that satisfy the package manifest rather than relying on workspace hoisting or transitive copies. In particular, the corrected partial-Ivy SDS packages require @gsa-sam/components, @gsa-sam/sam-formly, and @gsa-sam/sam-material-extensions at 21.0.2 or newer within major 21. Use a strict install without legacy-peer-deps and resolve any peer conflict instead of suppressing it.

After building the library, npm run package:contract verifies that every emitted runtime external is declared and that Angular/SDS ranges remain on the supported Angular 21 line. npm run package:consumer then packs the artifact, installs it outside the workspace from public npm without legacy-peer-deps, verifies the complete dependency tree and peer identities, and strictly compiles both direct-standalone and compatibility-NgModule Angular 21 consumers. Storybook registration alone is not render proof; npm run test:storybook-render renders every registered story in Chromium, asserts component-specific DOM, and fails on browser errors.

To run the dev server for your app, use:

npx nx serve sam-layouts

To create a production bundle:

npx nx build sam-layouts

To see all available targets to run for a project, run:

npx nx show project sam-layouts

These targets are either inferred automatically or defined in the project.json or package.json files.

More about running tasks in the docs »

Add new projects

While you could add new projects to your workspace manually, you might want to leverage Nx plugins and their code generation feature.

Use the plugin's generator to create new projects.

To generate a new application, use:

npx nx g @nx/angular:app demo

To generate a new library, use:

npx nx g @nx/angular:lib mylib

You can use npx nx list to get a list of installed plugins. Then, run npx nx list <plugin-name> to learn about more specific capabilities of a particular plugin. Alternatively, install Nx Console to browse plugins and generators in your IDE.

Learn more about Nx plugins » | Browse the plugin registry »

Set up CI!

Step 1

To connect to Nx Cloud, run the following command:

npx nx connect

Connecting to Nx Cloud ensures a fast and scalable CI pipeline. It includes features such as:

• Remote caching
• Task distribution across multiple machines
• Automated e2e test splitting
• Task flakiness detection and rerunning

Step 2

Use the following command to configure a CI workflow for your workspace:

npx nx g ci-workflow

Learn more about Nx on CI

Branch of record

main is the branch of record and the default branch (gh repo view GSA/sam-layouts --json defaultBranchRef → main). All new work branches from and merges into main.

Three disjoint git histories

This repo has three git histories that share no common ancestor with each other:

Branch(es)	Commits	Status
main	7	Branch of record
master, old-main	145 (byte-identical, both a0739b5, last touched 2023-05-03)	Retained, read-only — see below
angular-11 … angular-18 chain	92	Retired (deleted)

One more branch is retained: thread, which branches off master's history (merge base 67d8d0b, 7 commits ahead) and is pending a disposition decision — see Retired branches below.

main has no merge base with master or with the angular-18 head. angular-18 is deleted, but GitHub keeps its head at refs/pull/49/head, so any clone can still fetch it:

git merge-base origin/main origin/master  # exit 1, no output

git fetch origin refs/pull/49/head        # angular-18 head, a79508e
git merge-base origin/main FETCH_HEAD     # exit 1, no output

angular-19 and feature/IAEMOD-57632 are ancestors of main, so their commits are in every clone even though the branches are gone — check them by SHA, not by ref:

git merge-base --is-ancestor ffc454ec4939207010d70932c2f3b2913639ec54 origin/main # true, angular-19
git merge-base --is-ancestor caf221fba36a9bfe3c801667ef2bdff23bbcc79a origin/main # true, feature/IAEMOD-57632

No feature work was lost

When main was scaffolded fresh via Nx, it looked like 30+ Jira fixes from the angular-18 line had been dropped. They were not — this was re-verified:

git fetch origin refs/pull/49/head # angular-18 head, a79508e
git diff -w --stat FETCH_HEAD:layouts/src/lib origin/main:sam-layouts/src/lib
# 28 files changed, 47 insertions(+)

• Zero deletions across the entire library diff — nothing on angular-18 was dropped.
• All 47 added lines are standalone: false, stamped onto existing components. (Before #58 removed the leftover Nx scaffold component layouts.component.{ts,html,css} — <p>Layouts works!</p> — this diff read 31 files changed, 58 insertions(+), the extra 11 lines being that scaffold.)
• Spot-check: stepper.component.html, stepper.component.scss, and stepper.module.ts are byte-identical between the angular-18 head and main — IAEMOD-39957 (stepper list icon) and IAEMOD-39122 (screen-reader message) are both present on main.

This is a git-hygiene problem, not a content-recovery problem. No cherry-pick or port of any angular-*/IAEMOD-* commit is required.

GitHub Pages and historical branches

Pushes to main build Storybook from source and publish dist/storybook/sam-layouts to the gh-pages branch through .github/workflows/deploy-storybook-pages.yml. The workflow blocks deployment unless its index.json has at least 34 entries and includes both Subheader and Subheader/Modes; it also writes .nojekyll into the published output. This uses the fleet-standard branch-push deployment action rather than the GitHub Actions Pages/OIDC route. gh-pages is a generated deployment-only branch (typically orphan), never the branch of record or a development branch; main remains the branch of record.

The current legacy Pages source remains master /docs until an administrator changes it after gh-pages has been successfully populated. The safe order is: let the workflow populate gh-pages, verify its branch root and .nojekyll, have an administrator switch Pages to gh-pages /, then load https://gsa.github.io/sam-layouts/ and confirm the public Storybook. The workflow creates and updates only gh-pages; changing the Pages setting and checking the live site are deliberately manual and are not performed by this repository.

master / old-main — retained, read-only

master and old-main are preserved as the pre-Nx historical tree and must not be modified or deleted. Their historical /docs content remains read-only history. The legacy Pages configuration currently serves master /docs; deleting master while that setting remains would take the public site down.

Retired branches

40 stale branches (the angular-*/IAEMOD-* chain and assorted misc branches) have been deleted from origin, taking it from 46 branches down to four long-lived refs — main, master, old-main, thread — plus whatever short-lived gh-* branches are in flight. Every one was verified to contain no content absent from main, or to have had its content explicitly dispositioned, before deletion. The full branch → SHA list is in the closing comments on #53.

Recoverability is not uniform. Of the 40:

• 34 are durably recoverable from origin itself. 32 heads are reachable from a refs/pull/N/head ref, which GitHub retains indefinitely and does not prune; angular-19 (ffc454e) and feature/IAEMOD-57632 (caf221f) are ancestors of main.
• 6 are reachable by SHA only, and only until GitHub garbage-collects them — ang13 (5ceb702), angular-14 (d13c943), angular-14-2 (c939d2c), footer (8df95f7), IAEMOD-29493 (4d3833e), IAEMOD-29493-1 (e04d266). git fetch origin <sha> works today, but no ref on origin points at them, so that is not a guarantee. All six were verified content-complete on main before deletion (see #53); no durable archive ref has been pushed for them.
• The only complete archive is a local git bundle of all 46 pre-deletion origin branches, held on one workstation at .branch-backup/. It is not team-accessible and should not be relied on.

Restore a branch:

# from a PR ref (durable)
git fetch origin refs/pull/49/head && git push origin FETCH_HEAD:refs/heads/angular-18

# by SHA (works only while the object survives on origin)
git fetch origin 5ceb702886aa7f9a789f9ea78b93740839e48585 && git push origin FETCH_HEAD:refs/heads/ang13

Three of those 40 carried content that was not on main, and were deleted only after a deliberate decision:

Branch	Unique content	Disposition
help-slide-search	helpSearchEvent output on the header, wiring help-dialog search	PR #14 closed with the gap recorded; reapply against main if still wanted
footerfix / angular-14-2	A one-line footer fix (margin-left-neg-10) on neither main nor angular-18	Discarded — trivial to reapply

thread is retained pending a disposition decision. It holds a complete, never-merged comment-thread component (859 lines, 11 files, last touched 2022-05-20) that exists on no other branch in this repo; its head commit b2b34ab is additionally preserved at refs/pull/6/head from closed PR #6. Tracked on #61.

Install Nx Console

Nx Console is an editor extension that enriches your developer experience. It lets you run tasks, generate code, and improves code autocompletion in your IDE. It is available for VSCode and IntelliJ.

Install Nx Console »

Useful links

Learn more:

• Learn more about this workspace setup
• Learn about Nx on CI
• Releasing Packages with Nx release
• What are Nx plugins?

And join the Nx community:

• Discord
• Follow us on X or LinkedIn
• Our Youtube channel
• Our blog