feat(stepper): s2 number field/stepper migration #3681

marissahuysentruyt · 2025-04-21T18:20:23Z

Description

Welcome to the new & improved number field (previously known as stepper)! 🥳🔢 This migration was quite complex, and added a LOT of new features to our humble number field.

New features include:

an error state with alert icon
optional help text
embedded field label & optional positions

Following React's lead, the markup of the number field has changed. You'll see that the .spectrum-Textfield div is where the S2 design language lives (instead of on the input element), while the actual input is unstyled and incorporated more subtly. Based on design's, React's and SWC's naming conventions, the display name for this component has also changed from stepper to numberField. This introduced breaking changes in all previous custom properties, where any --spectrum-stepper-* or --mod-stepper-* properties moved to --spectrum-numberfield-*or --mod-numberfield-*. This also applied to class names, where .spectrum-Stepper changed to .spectrum-NumberField. The hide-stepper class has also been updated to match our class naming conventions (.spectrum-NumberField--hiddenStepper).

Because of all the new features and to align more with design, SWC and React, below is a quick recap of the following tokens & classes that have been renamed in the CSS:

All .spectrum-Stepper* class names have been converted to .spectrum-NumberField*
The .hide-stepper class has been converted to .spectrum-NumberField--hiddenStepper
Custom properties have been renamed from --spectrum-stepper* to --spectrum-numberfield*
Modifiable custom properties have been renamed from --mod-stepper* to --mod-numberfield

Removed custom properties include:
--mod-stepper-animation-duration
--mod-stepper-button-border-width
--mod-stepper-button-width
--mod-stepper-button-width-quiet
--mod-stepper-buttons-background-color
--mod-stepper-buttons-border-color
--mod-stepper-buttons-border-color-focus
--mod-stepper-buttons-border-color-focus-hover
--mod-stepper-buttons-border-color-hover
--mod-stepper-buttons-border-color-keyboard-focus
--mod-stepper-buttons-border-style
--mod-stepper-buttons-border-width
--mod-stepper-focus-indicator-visibility
--mod-stepper-height (renamed to --mod-numberfield-block-size)
--mod-stepper-width (renamed to --mod-numberfield-inline-size)

New custom properties include:
--mod-numberfield-background-color
--mod-numberfield-background-color-disabled
--mod-numberfield-block-size (renamed from --mod-stepper-height)
--mod-numberfield-border-color-disabled
--mod-numberfield-border-color-invalid-default
--mod-numberfield-border-color-invalid-focus
--mod-numberfield-border-color-invalid-focus-hover
--mod-numberfield-border-color-invalid-hover
--mod-numberfield-border-color-invalid-keyboard-focus
--mod-numberfield-button-inline-offset
--mod-numberfield-font-family
--mod-numberfield-font-size
--mod-numberfield-font-style
--mod-numberfield-font-weight
--mod-numberfield-hidden-stepper-min-inline-size
--mod-numberfield-inline-size (renamed from --mod-stepper-width)
--mod-numberfield-label-to-field
--mod-numberfield-line-height
--mod-numberfield-min-inline-size
--mod-numberfield-spacing-block-end-edge-to-text
--mod-numberfield-spacing-block-start-edge-to-text
--mod-numberfield-spacing-field-to-helptext

This PR also incorporates the refactoring and test coverage that was introduced and tested in both #3558 and #3670 (both of which could be closed after this PR is merged 👍)

Jira/Specs

CSS-1120
Figma token specs (under Number field)
Figma desktop designs (under Number field)

How and where has this been tested?

Please tag yourself on the tests you've marked complete to confirm the tests have been run by someone other than the author.

Validation steps

Additional Validation

Navigate to the forms docs page.
If you haven't already, pull down the branch to search the repo.
Search for Stepper in your IDE. No function calls, and no imports in references to Stepper should exist. As a caveat, there will still be references to stepper. The NPM package is still named "stepper," and all of the previous changelogs still use "stepper" as the component name, so not everything has been converted to "number field." We also have arguments in stories file that use the word "stepper," but all of the function calls to this component and any imports should be changed to NumberField.
Search for hide-stepper in your IDE. Nothing should be returned (except maybe some older JSON).
Search for --spectrum-Stepper and --mod-stepper in your IDE. Nothing should be returned except for changelogs.
Feel free to view the Chromatic test preview in WHCM to verify the component aligns with textfield (maybe it's not identical, but it should align closely).

Regression testing

Validate:

The documentation pages for at least two other components are still loading, including:

The pages render correctly, are accessible, and are responsive.

If components have been modified, VRTs have been run on this branch:

VRTs have been run and looked at.
Any VRT changes have been accepted (by reviewer and/or PR author), or there are no changes.

Screenshots

S1

S2

To-do list

I have read the contribution guidelines.
I have updated relevant storybook stories and templates.
I have tested these changes in Windows High Contrast mode.
If my change impacts other components, I have tested to make sure they don't break.
If my change impacts documentation, I have updated the documentation accordingly.
✨ This pull request is ready to merge. ✨

changeset-bot · 2025-04-21T18:20:27Z

🦋 Changeset detected

Latest commit: bd77043

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@spectrum-css/stepper	Major

Not sure what this means? Click here to learn what changesets are.

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

github-actions · 2025-04-21T18:27:01Z

File metrics

Summary

Total size: 1.39 MB^*

Package	Size	Minified	Gzipped
stepper	28.53 KB	27.46 KB	3.02 KB

stepper

Filename	Head	Minified	Gzipped	Compared to base
index.css	28.53 KB	27.46 KB	3.02 KB	🔴 ⬆ 10.24 KB
metadata.json	14.06 KB	-	-	🔴 ⬆ 6.23 KB

* Size is the sum of all main files for packages in the library.
* An ASCII character in UTF-8 is 8 bits or 1 byte.

github-actions

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

stylelint

⚠️ [stylelint] <spectrum-tools/no-unknown-custom-properties> _{reported by reviewdog 🐶}
Custom property --spectrum-number-field-edge-to-validation-icon-extra-large not defined

spectrum-css/components/stepper/index.css

Line 132 in 58fcc4f

    
           --spectrum-numberfield-spacing-validation-icon-to-stepper-hidden: var(--spectrum-number-field-edge-to-validation-icon-extra-large);

⚠️ [stylelint] <rule-empty-line-before> _{reported by reviewdog 🐶}
Expected empty line before rule

spectrum-css/components/stepper/index.css

Lines 246 to 250 in 58fcc4f

    
           .spectrum-NumberField-textfield:not(:has(.spectrum-Textfield-validationIcon)) { 
        
           	.spectrum-NumberField-input { 
        
           		padding-inline-end: 0; 
        
           	} 
        
           }

⚠️ [stylelint] <selector-class-pattern> _{reported by reviewdog 🐶}
Expected ".hide-stepper" to match pattern "^(spectrum-|is-|u-)[A-Za-z0-9-]+"

spectrum-css/components/stepper/index.css

Line 166 in 58fcc4f

    
           --mod-textfield-min-width: var(--mod-numberfield-hidden-stepper-min-inline-size, var(--spectrum-numberfield-hidden-stepper-min-inline-size));

⚠️ [stylelint] <selector-class-pattern> _{reported by reviewdog 🐶}
Expected ".hide-stepper" to match pattern "^(spectrum-|is-|u-)[A-Za-z0-9-]+"

spectrum-css/components/stepper/index.css

Line 231 in 58fcc4f

    
           min-inline-size: var(--mod-numberfield-hidden-stepper-min-inline-size, var(--spectrum-numberfield-hidden-stepper-min-inline-size));

⚠️ [stylelint] <selector-class-pattern> _{reported by reviewdog 🐶}
Expected ".hide-stepper" to match pattern "^(spectrum-|is-|u-)[A-Za-z0-9-]+"

spectrum-css/components/stepper/index.css

Line 240 in 58fcc4f

&.spectrum-Textfield.is-invalid .spectrum-Textfield-validationIcon {

github-actions · 2025-04-21T18:27:45Z

🚀 Deployed on https://pr-3681--spectrum-css.netlify.app

components/stepper/stories/stepper.test.js

components/stepper/stories/stepper.stories.js

marissahuysentruyt · 2025-04-22T13:46:02Z

components/stepper/stories/template.js

+					isInvalid,
+					isFocused,
+					isDisabled,
+					displayLabel: false,


I hardcoded this displayLabel: false (as opposed to displayLabel getting passed into Textfield) so that we wouldn't get duplicate field labels.

Does that make sense, or should I refactor? I'm pretty sure I could just use the embedded field label (and maybe even the help text) that's already within the textfield component, with some additional CSS edits.

Ohhh, this is a little weird... my initial instinct is that we shouldn't be dealing with field labels in each. But using textfield's field label also feels weird because it's a bit different (I think) from what SWC does, and it'd be better to be more aligned rather than less aligned.

It kind of feels like it's Textfield's fault that you have to do this. What would be pros/cons of separating the Textfield input from the Textfield with the field label and help text in the template? Like, that Textfield input could be a separate export that we could use in number field? I feel like Picker is also composed in this way? What do you think? If we did something like that, it doesn't have to be done here, I think this works fine for now, because if we change textfield's template, we'll start potentially affecting other components that use textfield too.

Also, why is field label a boolean situation with label text and help text is just a string (in textfield)? That feels inconsistent.

A few things to update here:

I can now remove the displayLabel: false since this PR to address this was merged.

I don't mind the idea of separating the textfield input from the rest of textfield. That may encourage the "unstyled" input thing I tried in this PR. I'm happy to explore that some more.

Right now, the displayLabel is a boolean for the field label because I'm pulling it from textfield's args.

Do you think I should refactor number field's field label arg to match label text and help text (getting rid of the boolean and just using a string?)

I don't mind the idea of separating the textfield input from the rest of textfield. That may encourage the "unstyled" input thing I tried in this PR. I'm happy to explore that some more.

I wonder if that's worth exploring in more of an RFC, textfield ends up being a headache for SWC's number field too, would it potentially solve problems for them too if we had an unstyled input that we used?

Do you think I should refactor number field's field label arg to match label text and help text (getting rid of the boolean and just using a string?)

I'd be slightly in favor, but don't feel strongly!

I'll create a ticket to create an RFC I guess! I do think that would solve some of our problems, but I'd have to experiment more from the SWC side to verify that.

@rise-erpelding Does this ticket (CSS-867) actually cover what we're talking about? It has some browser support steps to it, but sounds like some research into styling the inputs is involved.

components/stepper/stories/template.js

components/form/index.css

components/stepper/index.css

components/stepper/stories/template.js

components/stepper/stories/stepper.stories.js

aramos-adobe · 2025-04-23T21:47:31Z

Awesome work on this @marissahuysentruyt ! Only thing I can think of right now is adding the Storybook downstate interaction on the infield button and click functions in the isInline clicks to add and subtract.

components/stepper/stories/stepper.test.js

- updates documentation to use number field language instead of stepper - imports new numberfield templates - adds support for displaying the field label, label position, help text and label text - adds side label, invalid states stories - updates some sentence-case display names for stories - removes quiet variant stories - updates display title to Number field

- updates any stepper language to number field - adds test coverage for hidden stepper, side label, help text, invalid, minimum width, and truncation - adds test case for focus + hover, keyboardFocus + hover, disabled+ keyboardFocus

- new tokens used - cleans up/standardizes mod usage for textfield - cleans up/standardizes selectors so they are consistent across states/ variants - updates all custom properties to use numberfield prefix instead of stepper - adds style definitions for new features including hidden stepper, side label, help text, invalid, minimum width

- updates form to use number field import

- removes i18n test comments - removes duplicate disabled+keyboard-focused test

- uses textfield mods where possible to reduce the number of custom styles number field has - removes any textfield mods that are overwritten by number field styles - updates metadata - general clean up (stylelint warnings are addressed, some corrected mod definitions)

- adds styles for read-only state - adds test cases - adds story for read-only state on docs page and expands on some documentation - updates metadata

- updates the calc for the input to stepper spacing to subtract the infield buttons' inline padding from the text-to-stepper padding - updates metadata

- add calc for validation icon to stepper spacing to subtract the infield button's inline padding

- correctly calculates the input padding to account for the spacing between the input and alert icon, alert icon size and the new spacing between the icon and the stepper buttons - updates metadata

- corrects the padding-inline-end for the textfield by adding the offset to the calc - removes the mod for textfield's min-width since it is being overridden by the numberfield's min-width anyway

rise-erpelding

marissahuysentruyt self-assigned this Apr 21, 2025

github-actions bot reviewed Apr 21, 2025

View reviewed changes

marissahuysentruyt added size-3 M ~18-30hrs; moderate effort or complexity, several work days needed. S2 Spectrum 2 skip_vrt Add to a PR to skip running VRT (but still pass the action) labels Apr 22, 2025

marissahuysentruyt changed the base branch from spectrum-two to aramos-adobe/css770-infield-button-s2-migration April 22, 2025 12:22

marissahuysentruyt added the do not merge A flag for a branch indicating it should not be merged. label Apr 22, 2025

marissahuysentruyt force-pushed the marissahuysentruyt/css-1022-s2-migration-number-field-stepper branch from 55e94b1 to 840fffe Compare April 22, 2025 12:59

marissahuysentruyt commented Apr 22, 2025

View reviewed changes

components/stepper/stories/stepper.test.js Show resolved Hide resolved

marissahuysentruyt commented Apr 22, 2025

View reviewed changes

components/stepper/stories/stepper.test.js Show resolved Hide resolved

marissahuysentruyt commented Apr 22, 2025

View reviewed changes

components/stepper/stories/stepper.stories.js Show resolved Hide resolved

marissahuysentruyt commented Apr 22, 2025

View reviewed changes

components/stepper/stories/template.js Show resolved Hide resolved

marissahuysentruyt force-pushed the marissahuysentruyt/css-1022-s2-migration-number-field-stepper branch from e2354a0 to b1f40f5 Compare April 23, 2025 18:31

marissahuysentruyt marked this pull request as ready for review April 23, 2025 18:34

marissahuysentruyt added the ready-for-review label Apr 23, 2025

marissahuysentruyt commented Apr 23, 2025

View reviewed changes

components/form/index.css Outdated Show resolved Hide resolved

marissahuysentruyt commented Apr 23, 2025

View reviewed changes

components/stepper/index.css Outdated Show resolved Hide resolved

aramos-adobe reviewed Apr 23, 2025

View reviewed changes

components/stepper/stories/template.js Outdated Show resolved Hide resolved

aramos-adobe reviewed Apr 23, 2025

View reviewed changes

components/stepper/stories/stepper.stories.js Outdated Show resolved Hide resolved

aramos-adobe reviewed Apr 23, 2025

View reviewed changes

components/stepper/stories/stepper.stories.js Show resolved Hide resolved

aramos-adobe reviewed Apr 23, 2025

View reviewed changes

components/stepper/stories/stepper.stories.js Show resolved Hide resolved

Base automatically changed from aramos-adobe/css770-infield-button-s2-migration to spectrum-two April 24, 2025 15:58

marissahuysentruyt force-pushed the marissahuysentruyt/css-1022-s2-migration-number-field-stepper branch from 32555b2 to 785d2f9 Compare April 24, 2025 16:07

marissahuysentruyt removed the do not merge A flag for a branch indicating it should not be merged. label Apr 24, 2025

marissahuysentruyt commented Apr 24, 2025

View reviewed changes

components/stepper/stories/stepper.test.js Outdated Show resolved Hide resolved

marissahuysentruyt added 22 commits May 8, 2025 10:18

docs(numberfield): adds more test coverage

24bd4a2

- updates any stepper language to number field - adds test coverage for hidden stepper, side label, help text, invalid, minimum width, and truncation - adds test case for focus + hover, keyboardFocus + hover, disabled+ keyboardFocus

fix(form): updates number field language in comments

1f1785a

- updates form to use number field import

chore(numberfield): updates metadata.json

e26d1d1

chore(form): add changeset

c77a857

chore(numberfield): add changeset

4c5925d

fix(numberfield): linter fixes and update metadata

d57d6de

chore(numberfield): clean up testing file

bf3cc74

- removes i18n test comments - removes duplicate disabled+keyboard-focused test

docs(numberfield): corrects grammar, adds migrated tag/status

0d87c3e

chore(numberfield): linting, remove displayLabel

3a81f7b

chore(numberfield): adds min width size test cases

4ae151b

fix(numberfield): add readOnly state

1c9e832

- adds styles for read-only state - adds test cases - adds story for read-only state on docs page and expands on some documentation - updates metadata

docs(numberfield): adds functionality to number field

d84c403

docs(numberfield): add more documentation

0281733

chore(form): revert comment change and changeset

f258a77

fix(numberfield): adjust calc for input to stepper spacing

1a2db66

- updates the calc for the input to stepper spacing to subtract the infield buttons' inline padding from the text-to-stepper padding - updates metadata

fix(numberfield): accommodate border width in inline padding

b67c1d4

fix(numberfield): adjust calc for input to stepper spacing

a3d06b5

- add calc for validation icon to stepper spacing to subtract the infield button's inline padding

fix(numberfield): adjust calc for input to stepper spacing

86e55f1

- correctly calculates the input padding to account for the spacing between the input and alert icon, alert icon size and the new spacing between the icon and the stepper buttons - updates metadata

fix(numberfield): add offset to inline-end padding

bd77043

- corrects the padding-inline-end for the textfield by adding the offset to the calc - removes the mod for textfield's min-width since it is being overridden by the numberfield's min-width anyway

rise-erpelding approved these changes May 8, 2025

View reviewed changes

marissahuysentruyt force-pushed the marissahuysentruyt/css-1022-s2-migration-number-field-stepper branch from f46d2d6 to bd77043 Compare May 8, 2025 19:21

marissahuysentruyt merged commit 0a23664 into spectrum-two May 8, 2025
12 checks passed

marissahuysentruyt deleted the marissahuysentruyt/css-1022-s2-migration-number-field-stepper branch May 8, 2025 21:12

marissahuysentruyt mentioned this pull request May 9, 2025

refactor(stepper): standardize selectors and passthroughs usage #3558

Closed

18 tasks

This was referenced May 16, 2025

chore(swatch,menu,swatchgroup): fix reverted metadata assets #3752

Merged

chore: merge latest updates from main #3777

Merged

rise-erpelding mentioned this pull request May 19, 2025

feat(combobox): adding new s2 migration #3683

Open

14 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(stepper): s2 number field/stepper migration #3681

feat(stepper): s2 number field/stepper migration #3681

marissahuysentruyt commented Apr 21, 2025 •

edited by aramos-adobe

Loading

changeset-bot bot commented Apr 21, 2025 •

edited

Loading

github-actions bot commented Apr 21, 2025 •

edited

Loading

github-actions bot left a comment

github-actions bot commented Apr 21, 2025 •

edited

Loading

marissahuysentruyt Apr 22, 2025 •

edited

Loading

rise-erpelding Apr 25, 2025

rise-erpelding Apr 25, 2025

marissahuysentruyt Apr 29, 2025

rise-erpelding Apr 29, 2025 •

edited

Loading

marissahuysentruyt Apr 30, 2025

marissahuysentruyt Apr 30, 2025

aramos-adobe commented Apr 23, 2025

rise-erpelding left a comment

	.spectrum-NumberField-textfield:not(:has(.spectrum-Textfield-validationIcon)) {
	.spectrum-NumberField-input {
	padding-inline-end: 0;
	}
	}

feat(stepper): s2 number field/stepper migration #3681

feat(stepper): s2 number field/stepper migration #3681

Conversation

marissahuysentruyt commented Apr 21, 2025 • edited by aramos-adobe Loading

Description

Jira/Specs

How and where has this been tested?

Validation steps

Additional Validation

Regression testing

Screenshots

To-do list

changeset-bot bot commented Apr 21, 2025 • edited Loading

🦋 Changeset detected

github-actions bot commented Apr 21, 2025 • edited Loading

File metrics

Summary

stepper

github-actions bot left a comment

Choose a reason for hiding this comment

github-actions bot commented Apr 21, 2025 • edited Loading

marissahuysentruyt Apr 22, 2025 • edited Loading

Choose a reason for hiding this comment

rise-erpelding Apr 25, 2025

Choose a reason for hiding this comment

rise-erpelding Apr 25, 2025

Choose a reason for hiding this comment

marissahuysentruyt Apr 29, 2025

Choose a reason for hiding this comment

rise-erpelding Apr 29, 2025 • edited Loading

Choose a reason for hiding this comment

marissahuysentruyt Apr 30, 2025

Choose a reason for hiding this comment

marissahuysentruyt Apr 30, 2025

Choose a reason for hiding this comment

aramos-adobe commented Apr 23, 2025

rise-erpelding left a comment

Choose a reason for hiding this comment

marissahuysentruyt commented Apr 21, 2025 •

edited by aramos-adobe

Loading

changeset-bot bot commented Apr 21, 2025 •

edited

Loading

github-actions bot commented Apr 21, 2025 •

edited

Loading

github-actions bot commented Apr 21, 2025 •

edited

Loading

marissahuysentruyt Apr 22, 2025 •

edited

Loading

rise-erpelding Apr 29, 2025 •

edited

Loading