adobe / spectrum-web-components / 31502502140

96%

push

github

feat(dev-validation): add reusable dev-mode validation helpers and docs (#6508)

* feat(dev-validation): add reusable dev-mode validation helpers and docs

Lays the foundation for consistent dev-mode validation warnings across
2nd-gen components: shared helpers (validateEnum, warnIf,
validateRequiredSlot, validateAllowedChildren) in
@spectrum-web-components/core/utils replace the hand-rolled
includes()+warn() checks each component previously wrote independently.

Also fixes window.__swc.warn's dedup key (adds the message to
localName:type:level) so two distinct warnings on the same component no
longer silently suppress each other.

Documents the full set of validation categories (enum, required,
conditionally required, mutually exclusive/no-effect, required slots,
allowed children, component-specific quirks via warnIf) in the style
guide and the washing-machine migration workflow, and adds a consumer-
facing Storybook guide explaining how the warnings work.

* docs(dev-validation): say Gen2 instead of 2nd-gen in the consumer guide

The rest of the repo's docs use "2nd-gen" as an established convention
(120+ files), so pre-existing prose in touched files is left as-is;
this only fixes the one line of net-new prose this PR introduced.

* docs(dev-validation): add per-bundler production-stripping recipes

Turns the "no guaranteed production stripping" known limitation into
actionable guidance: concrete recipes for webpack/Next.js, Vite,
esbuild, and Rollup to confirm process.env.NODE_ENV is actually
replaced and the resulting dead branch removed, plus the no-bundler
ReferenceError case. Addresses the concern that components could ship
dev-only validation code and message strings to production bundles by
default.

* feat(dev-validation): gate helpers on the literal NODE_ENV, not just DEBUG

Each helper in dev-validation.ts now returns immediately when
process.env.NODE_ENV === 'production', ahead of the existing
window.__swc?.DEBUG check. This makes the in... (continued)

6021 of 6465 branches covered (93.13%)

Branch coverage included in aggregate %.

37993 of 39268 relevant lines covered (96.75%)

460.43 hits per line