feat: Consolidate package exports, stamp versions, rework install docs - #175
Draft
abbybowman wants to merge 7 commits into
Draft
feat: Consolidate package exports, stamp versions, rework install docs#175abbybowman wants to merge 7 commits into
abbybowman wants to merge 7 commits into
Conversation
Drop src/assets/ from the published files list; dist/assets/ is a superset produced by the build, so shipping both double-packaged the same fonts and icons. Replace the deprecated trailing-slash "./assets/" export (Node DEP0155) with the "./assets/*" subpath pattern, and add the missing "./js/uswds" export. Update the React setup guide's vite-plugin-static-copy targets to copy from dist/assets instead of the now-unpublished src/assets. Also remove a duplicated loadPaths line in the same snippet.
A copied dist/ keeps no package.json, lockfile, or install log, so an adopter's server records nothing about what version is live. A PostCSS plugin, running last so its output survives comment-discarding and minification, now opens every bundle with a /*! banner naming the HDS and USWDS versions, and adds --hds-version / --hds-uswds-version on :root in hds.min.css only (the required bundle). Emitting the props from optional bundles too would let a stale copy win the cascade and misreport the version. Also substitutes USWDS's own banner: HDS compiles USWDS from source, where the string is the literal placeholder `uswds @version`, so our bundles were shipping the unsubstituted token. It now reads the real version. Versions are read at build time, so the stamp tracks the changesets bump with no generated file to keep in sync. Classified patch: diagnostics that report a deployment, not a capability to build with. The output filename is derived by splitting on both path separators so the banner and per-bundle property gate work when built on Windows.
Reorder Installation so it follows the real sequence: get the package (npm or zip, presented as two parallel options), see what's in it, then choose an approach. Add a shared Assets section before the pre-compiled / Sass fork, since the requirement (assets/ beside css/) is identical for both. Correct several install facts: the pre-compiled path needs only @nasa-hds/core (CSS is self-contained, USWDS scripts ship in dist/js/), with @uswds/uswds as an auto-installed peer that only the Sass path compiles against; name both JS files and show the uswds-init + uswds script pair with the real reason init loads early; scope "order does not matter" to compiled-CSS links and point to the Sass singleton rule for why @forward order does matter. In Getting Started, drop the claim that HDS keeps a site current "automatically"; especially pre-v1.0, users should pin and upgrade deliberately.
Retitle away from "Customizing USWDS settings": nothing there is Sass-configurable. Lead with the real surface (HDS tokens, USWDS functions, HDS mixins, the two config flags) and state the canonical entry point (@forward '@nasa-hds/core/scss') that the other guides reconcile to. Document the .hds-global-styles and .hds-global-styles-reset wrappers, which were shipping undocumented, and move typography/palette classes out to their foundations docs rather than re-cataloging them. Explain the sealed USWDS settings as one honest section (the singleton rule, the fork-drift trap, and the correct @forward ordering) and cut the 40-line reserved-settings catalog that nothing linked to and no consumer could act on.
Fix the false claim that grid classes require hds-uswds.min.css: grid ships in hds.min.css; the optional bundle adds spacing and color utilities, not grid. Point the fetch/verify step at Installation's Get the package section instead of repeating the checksum steps, and keep the runtime version check for the copied-dist audience.
Replace "settings not reserved by HDS Core continue to work" (no $theme-* setting can be changed from consumer Sass) with the real options (the site cascade layer, your own variables). Use the canonical @forward '@nasa-hds/core/scss' path and the precise singleton wording, and scope "order does not matter" to stylesheet links.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
src/assets/, tightens theexportsmap to subpath patterns, adds the./js/uswdsexport)The docs pass corrects several claims that were false or contradictory (asset paths, bundle contents, sealed USWDS settings) and restructures the Installation page around "get the package, then choose an approach."
Type of change
The version stamp adds two custom properties (
--hds-version,--hds-uswds-version). These are diagnostics that report a deployment, not a capability to build with, so the changeset is a patch. The asset consolidation and exports changes do not change compiled CSS output (verified byte-identical).Checklist
npm run format:fixandnpm run lint:scss:fixpassnpm run lint:jsandnpm run lint:mdpassnpm test)Public API and changesets
npm run update:api-snapshotand reviewed the diffnpx changeset) with appropriate bump levelVisual review
N/A
Notes for reviewers
This branch bundles four related changes that share one review:
Package consolidation (
package.json,ReactSetup.mdx): dropsrc/assets/fromfiles(it double-shipped whatdist/assets/already contains), replace the deprecated trailing-slash./assets/export with the./assets/*subpath pattern, add./js/uswds. The React guide's asset-copy targets move fromsrc/assetstodist/assetsaccordingly.Version stamp (
.config/postcss-hds-stamp.mjs,postcss.config.mjs, snapshot, changeset): a PostCSS plugin, running last so its output survives minification, opens every bundle with a/*! ... */banner naming the HDS and USWDS versions and adds--hds-version/--hds-uswds-versiontohds.min.css. It also substitutes USWDS's ownuswds @versionplaceholder, which shipped unsubstituted because HDS compiles USWDS from source. The filename is derived by splitting on both path separators so the banner and per-bundle property gate work when the build runs on Windows.Docs accuracy/readability pass (Installation, SassConfiguration, NoBuild, USWDS, GettingStarted): corrects false/contradictory claims (grid ships in
hds.min.css, not the optional bundle; USWDS$theme-*settings are sealed, not "adjustable"; pre-compiled consumers need only@nasa-hds/core), restructures Installation around get-then-choose with a shared Assets section, and reframes Sass Configuration around what a consumer can actually build with (tokens, functions, mixins) rather than settings they cannot change.All docs-only claims were verified against current source and a fresh build, but would appreciate a reviewer's testing as well to finalize these install/setup instructions ahead of v1.0.