feat(validation): warn on invalid enum values instead of overriding

[miwha-adobe]

Description

This is a proof-of-concept, not intended to merge. It demonstrates removing the "coerce an invalid value to a default" behavior for constrained enums, so that an invalid value is left in place and a dev-mode warning is emitted instead of being silently swapped for the default. The purpose is to make the trade-offs concrete for a team discussion on what our fallback policy should be.

Changes shown here (for illustration only):

• Tabs (keyboardActivation, density, direction): coercing getter/setter pairs replaced with plain @property + validateEnum in willUpdate (warn-only).
• AlertBanner (variant): the setter no longer blanks or removes the attribute on invalid input.
• Meter (variant): drops the willUpdate this.variant = 'informative' fallback.
• Tests updated to assert the warn-only behavior.

The open question

When a consumer sets an invalid property value, should the component fall back to a default (and warn), or leave the value as-is (and warn)? Our components are currently inconsistent about this, and we want one deliberate, documented policy.

The tension comes down to production behavior, since dev warnings are stripped from production builds:

• Warn, don't coerce (what this POC does): respect the consumer's value; the warning is the response. Silently swapping a value hides the mistake, because the consumer's code still reads the invalid value while the component renders something else.
• Fallback is the guided behavior (counter-position): the fallback is intended graceful degradation and the warning is just a dev note. Because warnings do not exist in production, warn-only is the one path that fails both silently and ugly in prod (e.g. variant="banana" matches no CSS rule, so the component renders unstyled, with no warning). Fallback-to-default means it always looks like something, and developers still get told in dev.

Proposed policy to discuss (not decided)

A consistent matrix, applied the same way everywhere, rather than per-component choices:

Value category	Proposed behavior
Constrained enum (variant, size, density, direction)	Fall back to default, and warn
Numeric out of range (progress, level)	Clamp, and warn (already the documented behavior)
Accessibility (e.g. an accessible name)	Do NOT fabricate a default; warn-only
Developer-typed / free-form values	Preserve exactly as typed; warn-only

Two things to note about how the current code sits against this proposal:

• This POC removes the fallback for constrained enums, which is the opposite of the first row. That is deliberate: it shows what warn-only looks like so we can decide whether we actually want it, or whether fallback-and-warn is the better default.
• The accessibility row cuts the other way: ProgressCircle currently fabricates an aria-label default ("Loading") when no accessible name is provided. Under the a11y exception that would become warn-only. This is the sharpest trade-off in the whole policy, because in production (no warning) it would ship an unnamed element to end users. It needs the most discussion and is not changed here.

Relationship to the placement PR

The philosophy-neutral part of this effort (moving dev-warnings to the pre-render phase) is separated into its own PR and does not depend on this decision. That PR carries no behavior change. This branch carries only the contested coercion change.

Do not merge

Blocked on the fallback-policy decision. Attached to [Jira ticket number] for team discussion.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9f49451

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview Links

• Storybook (Gen2, dev mode)
• Storybook (Gen2, prod mode)
• Documentation Site (Gen1)
• Storybook (Gen1)

🔍 Gen1 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6564

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.