Button: deprecate isPrimary, isSecondary, isTertiary and isLink props in favour of variant prop

[ciampo]

Description

This PR takes inspiration from previous PRs #29990 and #31297

• Expose a new variant prop (i.e. variant="primary|secondary|tertiary|link")
• Do not mark the isPrimary, isSecondary, isTertiary and isLink props as deprecated yet, but add logic to the <Button /> component to translate their values into the variant prop
• Update docs, changelog, unit tests and Storybook Button stories
• Add unit tests to verify that the above-mentioned props are effectively marked as deprecated, while the expected classes are still being applied
• Update all of the usages in the repo to utilise the new variant prop instead of the deprecated props (necessary to have all tests passing)

Part of the next steps highlighted in #30503

Testing instructions

• Run Gutenberg and make sure that Buttons still work as expected
• All tests are passing
• Run Button unit tests: npm run test-unit packages/components/src/button
• Run local storybook npm run storybook:dev and compare the Button component against what's currently in production
• Search in the repo's codebase for the isPrimary, isSecondary, isTertiary and isLink props and make sure they have all been replaced with the new variant prop

Screenshots

N/A

Types of changes

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• I've tested my changes with keyboard and screen readers.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• N/A I've updated all React Native files affected by any refactorings/renamings in this PR (please manually search all *.native.js files for terms that need renaming or removal).

[kevin940726]

I like this a lot!

[ciampo]

Rebased on top of latest trunk, and removed the official deprecation notices in 8344c80.

The docs don't mention the isPrimary, isSecondary, isTertiary and isLink props anymore, in favor of the new variant prop

[sarayourfriend]

Once this is rebased it LGTM, nice work.

@youknowriad any ideas when we would be able to actually add deprecation warnings for the old props?

[youknowriad]

Right after 5.8 beta freeze would work for me. I guess that means next week :)

[ciampo]

Hey @jorgefilipecosta , we are currently in the process of replacing isTertiary and isLink with a new variant prop — which also means that a button can be assigned to only one variant at the time.

Does this fit your needs? Or did you need this button to be at the same tertiary AND marked as a link?
We're also considering keeping isLink (see #31713 (comment))

[jorgefilipecosta]

The design is changed a little bit. I think it is ok (provided we correct a small pixel alignment between the button and the input as a follow up):
new:

old:

But I'm going to cc: @jameskoster to double-check if we can do this UI change.

[ciampo]

I could also change it to variant="link" if that works better

[jameskoster]

Should be fine, I actually have a PR open to adjust that popover a bit. There it's only using isSecondary and isDestructive which I assume will work fine with the new system?

[ciampo]

There it's only using isSecondary and isDestructive which I assume will work fine with the new system?

That's not going to be an issue. isSecondary will become variant="secondary" and isDestructive can stay as-is

[mtias]

Wonder if it's slightly odd to see link as a variant. Would it ever make sense to have a "primary link" or a "secondary link"? Should externalLink be considered a variant as well (it exists as a separate thin now)?

[sarayourfriend]

variant="link" doesn't determine whether the component renders an anchor tag, that's determined by the href prop's presence.

Furthermore, the link variant cannot be mixed with the other three variants for a good looking experience. These are the three variants together with link:

They all say "tertiary" button but they're the mixes of link with tertiary, secondary and primary respectively.

[mtias]

If it's determined by href why do we need it as a variant?

[sarayourfriend]

link is a variant of the style of the button, not the functionality. Passing href changes the functionality. You could, for example, have a button that looks like a link by passing <Button onClick={() => alert('hello!')} variant="link">Hello!</Button>

[kevin940726]

We should probably rename it to text or flat though. material-ui is a good source of inspiration for this. (not necessary related to this PR though)

[sarayourfriend]

I'd expect text to look most like the variantless button though, i.e., without the underline. 🤷‍♀️ I'm fine renaming it to whatever makes the most sense to people but I don't think we'll find something perfect. Our variants aren't as "varied" as material's. We really just have the five: no variant, primary, secondary, tertiary, and link. And they all or remove the outline/background arbitrarily (link, incidentally, is probably the easiest to guess what it does currently aside from the confusion around functionality).

[griffbrad]

I agree. I think it would be best to merge this change (i.e. introducing variant as a preferred alternative to the overlapping is props) and then we could potentially reconsider renaming or changing variants separately. Don't want to keep this PR open any longer because it touches so many usages of Button that it needs constant rebasing, etc.

[mtias]

It's weird to use "link" to refer to an appearance characteristic but we can revisit this separately as we should also clarify the design expectations.

[mtias]

I like this.

Do not mark the isPrimary, isSecondary, isTertiary and isLink props as deprecated yet, but add logic to the component to translate their values into the variant prop

This sounds like a good approach to me. I think we might consider soft deprecating — just converting internally but not warning — given how widespread the use of this component is.

[Lovor01]

This change is introduced in the docs too early. WordPress 5.8.1 still uses button with is**** attributes, and these deprecations (will still work in future versions - I inspected code) are not mentioned at all in the docs for Button component

[ciampo]

Hey @Lovor01!

This change is introduced in the docs too early [...] these deprecations are not mentioned at all in the docs for Button component

This deprecation was mentioned in the changelog.

Regarding the mention on the Button docs, we are on purpose not mentioning it. We just removed the props from the docs (while still supporting them in code), in order to encourage the usage of the new variant prop without introducing a breaking change. You can read more about this approach in the contributing guidelines

WordPress 5.8.1 still uses button with is**** attributes

Could you be more precise about which Buttons in the codebase you are referring to?