feat(clearbutton): s2 migration (#4043)

* feat(clearbutton): s2 migration

* chore(clearbutton): add search + tags links to docs

* chore(clearbutton): add hover + down state tests

* chore(clearbutton): add hover + down state controls, add migrated tags

* chore(clearbutton): add down state to changelog

* chore(clearbutton): move size table out of usage notes to size story

* fix(clearbutton): correct test key names

* chore(clearbutton): remove keyboard focus outline

Author: cdransf

.changeset/neat-schools-take.md

@@ -0,0 +1,12 @@
+---
+"@spectrum-css/clearbutton": major
+---
+
+#### S2 migration for clear button
+
+This migrates the clear button component to the latest Spectrum 2 designs. Custom properties have been remapped and added per the design specification.
+
+- The quiet variant has been remove as all clear buttons have a transparent background.
+- The over-background and static color variants have been removed.
+- Test and stories for deprecated variants have been removed.
+- The down state has been added, corresponding controls and tests have been added.

components/clearbutton/dist/metadata.json

@@ -3,17 +3,14 @@
   "selectors": [
     ".spectrum-ClearButton",
     ".spectrum-ClearButton > .spectrum-Icon",
-    ".spectrum-ClearButton--overBackground:focus-visible",
-    ".spectrum-ClearButton--staticWhite:focus-visible",
     ".spectrum-ClearButton-fill",
     ".spectrum-ClearButton-icon",
     ".spectrum-ClearButton.is-disabled",
-    ".spectrum-ClearButton.spectrum-ClearButton--quiet",
     ".spectrum-ClearButton.spectrum-ClearButton--sizeL",
     ".spectrum-ClearButton.spectrum-ClearButton--sizeS",
     ".spectrum-ClearButton.spectrum-ClearButton--sizeXL",
-    ".spectrum-ClearButton.spectrum-ClearButton--staticWhite",
     ".spectrum-ClearButton:disabled",
+    ".spectrum-ClearButton:focus-visible",
     ".spectrum-ClearButton:not(:disabled)",
     ".spectrum-ClearButton:not(:disabled):active",
     ".spectrum-ClearButton:not(:disabled):active .spectrum-ClearButton-fill",
@@ -57,16 +54,17 @@
     "--spectrum-component-height-200",
     "--spectrum-component-height-300",
     "--spectrum-component-height-75",
+    "--spectrum-component-size-difference-down",
+    "--spectrum-component-size-minimum-perspective-down",
     "--spectrum-disabled-content-color",
-    "--spectrum-disabled-static-white-content-color",
-    "--spectrum-in-field-button-edge-to-fill",
+    "--spectrum-in-field-button-edge-to-fill-extra-large",
+    "--spectrum-in-field-button-edge-to-fill-large",
+    "--spectrum-in-field-button-edge-to-fill-medium",
+    "--spectrum-in-field-button-edge-to-fill-small",
     "--spectrum-neutral-content-color-default",
     "--spectrum-neutral-content-color-down",
     "--spectrum-neutral-content-color-hover",
-    "--spectrum-neutral-content-color-key-focus",
-    "--spectrum-transparent-white-400",
-    "--spectrum-transparent-white-500",
-    "--spectrum-white"
+    "--spectrum-neutral-content-color-key-focus"
   ],
   "passthroughs": [],
   "high-contrast": ["--highcontrast-clear-button-icon-color-hover"]

components/clearbutton/index.css

@@ -1,5 +1,5 @@
 /*!
-* Copyright 2024 Adobe. All rights reserved.
+* Copyright 2025 Adobe. All rights reserved.
 *
 * This file is licensed to you under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may obtain a copy
@@ -14,7 +14,7 @@
 .spectrum-ClearButton {
 	--spectrum-clear-button-height: var(--spectrum-component-height-100);
 	--spectrum-clear-button-width: var(--spectrum-component-height-100);
-	--spectrum-clear-button-padding: var(--spectrum-in-field-button-edge-to-fill);
+	--spectrum-clear-button-padding: var(--spectrum-in-field-button-edge-to-fill-medium);
 
 	--spectrum-clear-button-icon-color: var(--spectrum-neutral-content-color-default);
 	--spectrum-clear-button-icon-color-hover: var(--spectrum-neutral-content-color-hover);
@@ -26,46 +26,25 @@
 	--spectrum-clear-button-background-color-down: transparent;
 	--spectrum-clear-button-background-color-key-focus: transparent;
 
-	&.spectrum-ClearButton--staticWhite {
-		--spectrum-clear-button-background-color-hover: var(--spectrum-transparent-white-400);
-		--spectrum-clear-button-background-color-down: var(--spectrum-transparent-white-500);
-		--spectrum-clear-button-background-color-key-focus: var(--spectrum-transparent-white-400);
-	}
-
 	&.spectrum-ClearButton--sizeS {
 		--spectrum-clear-button-height: var(--spectrum-component-height-75);
 		--spectrum-clear-button-width: var(--spectrum-component-height-75);
+
+		--spectrum-clear-button-padding: var(--spectrum-in-field-button-edge-to-fill-small);
 	}
 
 	&.spectrum-ClearButton--sizeL {
 		--spectrum-clear-button-height: var(--spectrum-component-height-200);
 		--spectrum-clear-button-width: var(--spectrum-component-height-200);
+
+		--spectrum-clear-button-padding: var(--spectrum-in-field-button-edge-to-fill-large);
 	}
 
 	&.spectrum-ClearButton--sizeXL {
 		--spectrum-clear-button-height: var(--spectrum-component-height-300);
 		--spectrum-clear-button-width: var(--spectrum-component-height-300);
-	}
-
-	&.spectrum-ClearButton--quiet {
-		--mod-clear-button-background-color: transparent;
-		--mod-clear-button-background-color-hover: transparent;
-		--mod-clear-button-background-color-down: transparent;
-		--mod-clear-button-background-color-key-focus: transparent;
-	}
-
-	&.spectrum-ClearButton--staticWhite {
-		--spectrum-clear-button-background-color-hover: var(--spectrum-transparent-white-400);
-		--spectrum-clear-button-background-color-down: var(--spectrum-transparent-white-500);
-		--spectrum-clear-button-background-color-key-focus: var(--spectrum-transparent-white-400);
-
-		--mod-clear-button-icon-color: var(--spectrum-white);
-		--mod-clear-button-icon-color-hover: var(--spectrum-white);
-		--mod-clear-button-icon-color-down: var(--spectrum-white);
-		--mod-clear-button-icon-color-key-focus: var(--spectrum-white);
-		--mod-clear-button-icon-color-disabled: var(--spectrum-disabled-static-white-content-color);
 
-		--mod-clear-button-background-color: transparent;
+		--spectrum-clear-button-padding: var(--spectrum-in-field-button-edge-to-fill-extra-large);
 	}
 
 	&:disabled,
@@ -80,9 +59,8 @@
 .spectrum-ClearButton {
 	block-size: var(--mod-clear-button-height, var(--spectrum-clear-button-height));
 	inline-size: var(--mod-clear-button-width, var(--spectrum-clear-button-width));
-	border-radius: 100%;
 
-	background-color: var(--mod-clear-button-background-color, transparent);
+	background-color: transparent;
 	margin: 0;
 	padding: var(--mod-clear-button-padding, var(--spectrum-clear-button-padding));
 
@@ -93,6 +71,10 @@
 		cursor: pointer;
 	}
 
+	&:focus-visible {
+		outline: none;
+	}
+
 	> .spectrum-Icon {
 		/* @safari10 Workaround for https://bugs.webkit.org/show_bug.cgi?id=169700 */
 		margin-block: 0;
@@ -109,6 +91,7 @@
 
 	&:not(:disabled):active {
 		color: var(--mod-clear-button-icon-color-down, var(--spectrum-clear-button-icon-color-down));
+		transform: perspective(var(--spectrum-component-size-minimum-perspective-down)) translateZ(var(--spectrum-component-size-difference-down));
 
 		.spectrum-ClearButton-fill {
 			background-color: var(--mod-clear-button-background-color-down, var(--spectrum-clear-button-background-color-down));
@@ -134,21 +117,12 @@
 
 	inline-size: 100%;
 	block-size: 100%;
-	border-radius: 100%;
 
 	display: flex;
 	align-items: center;
 	justify-content: center;
 }
 
-/* @deprecated .spectrum-ClearButton--overBackground */
-.spectrum-ClearButton--staticWhite,
-.spectrum-ClearButton--overBackground {
-	&:focus-visible {
-		outline: none;
-	}
-}
-
 @media (forced-colors: active) {
 	.spectrum-ClearButton {
 		&:not(:disabled) {

components/clearbutton/stories/clearbutton.stories.js

@@ -1,56 +1,22 @@
 import { Sizes } from "@spectrum-css/preview/decorators";
 import { disableDefaultModes } from "@spectrum-css/preview/modes";
-import { isDisabled, isQuiet, size, staticColor } from "@spectrum-css/preview/types";
+import { isActive, isDisabled, isHovered, size } from "@spectrum-css/preview/types";
 import metadata from "../dist/metadata.json";
 import packageJson from "../package.json";
 import { ClearButtonGroup } from "./clearbutton.test.js";
 import { Template } from "./template.js";
 
 /**
- * The clear button component is an in-field button used in search and tags.
- *
- * ## Usage Notes
-
-	Use the correct cross icon size that corresponds to the t-shirt size you require for the clear button.
-
-	<table>
-		<thead>
-			<tr>
-				<th>**T-Shirt Size**</th>
-				<th>**Icon Size**</th>
-			</tr>
-		</thead>
-		<tbody>
-			<tr>
-				<td>spectrum-ClearButton--sizeS</td>
-				<td>spectrum-css-icon-Cross75</td>
-			</tr>
-			<tr>
-				<td>spectrum-ClearButton--sizeM</td>
-				<td>spectrum-css-icon-Cross100</td>
-			</tr>
-			<tr>
-				<td>spectrum-ClearButton--sizeL</td>
-				<td>spectrum-css-icon-Cross200</td>
-			</tr>
-			<tr>
-				<td>spectrum-ClearButton--sizeXL</td>
-				<td>spectrum-css-icon-Cross300</td>
-			</tr>
-		</tbody>
-	</table>
+ * The clear button component is an in-field button used in [search](/docs/components-search-field--docs) and [tags](/docs/components-tag--docs).
  */
 export default {
 	title: "Clear button",
 	component: "ClearButton",
 	argTypes: {
 		size: size(["s", "m", "l", "xl"]),
 		isDisabled,
-		isQuiet,
-		staticColor: {
-			...staticColor,
-			options: ["white"],
-		},
+		isHovered,
+		isActive,
 		isFocusable: {
 			table: { disable: true },
 			type: { name: "boolean" },
@@ -60,21 +26,25 @@ export default {
 		rootClass: "spectrum-ClearButton",
 		size: "m",
 		isDisabled: false,
-		isQuiet: false,
+		isHovered: false,
+		isActive: false,
 	},
 	parameters: {
 		packageJson,
 		metadata,
+		status: {
+			type: "migrated",
+		},
+		tags: ["migrated"],
 	},
 };
 
-/**
- * The default size for clear button is medium.
- */
-
 export const Default = ClearButtonGroup.bind({});
 Default.args = {};
 
+/**
+ * When disabled, the clear button color changes to `--spectrum-disabled-content-color` and is not interactive.
+ */
 export const Disabled = Template.bind({});
 Disabled.args = {
 	isDisabled: true,
@@ -85,17 +55,36 @@ Disabled.parameters = {
 };
 
 /**
- * The `.spectrum-ClearButton--quiet` class will use a transparent background (including when the Express theme is active).
- */
-export const Quiet = Template.bind({});
-Quiet.args = {
-	isQuiet: true,
-};
-Quiet.tags = ["!dev"];
-Quiet.parameters = {
-	chromatic: { disableSnapshot: true },
-};
+ * Use the correct cross icon size that corresponds to the t-shirt size you require for the clear button. The default size is medium.
 
+	<table>
+		<thead>
+			<tr>
+				<th>**T-Shirt Size**</th>
+				<th>**Icon Size**</th>
+			</tr>
+		</thead>
+		<tbody>
+			<tr>
+				<td>spectrum-ClearButton--sizeS</td>
+				<td>spectrum-css-icon-Cross75</td>
+			</tr>
+			<tr>
+				<td>spectrum-ClearButton--sizeM</td>
+				<td>spectrum-css-icon-Cross100</td>
+			</tr>
+			<tr>
+				<td>spectrum-ClearButton--sizeL</td>
+				<td>spectrum-css-icon-Cross200</td>
+			</tr>
+			<tr>
+				<td>spectrum-ClearButton--sizeXL</td>
+				<td>spectrum-css-icon-Cross300</td>
+			</tr>
+		</tbody>
+	</table>
+ *
+ */
 export const Sizing = (args, context) => Sizes({
 	Template,
 	withHeading: false,
@@ -109,15 +98,6 @@ Sizing.parameters = {
 
 };
 
-export const OverBackground = ClearButtonGroup.bind({});
-OverBackground.tags = ["!dev"];
-OverBackground.args = {
-	staticColor: "white",
-};
-OverBackground.parameters = {
-	chromatic: { disableSnapshot: true },
-};
-
 // ********* VRT ONLY ********* //
 export const WithForcedColors = ClearButtonGroup.bind({});
 WithForcedColors.tags = ["!autodocs", "!dev"];

components/clearbutton/stories/clearbutton.test.js

@@ -9,24 +9,19 @@ export const ClearButtonGroup = Variants({
 		{
 			testHeading: "Default",
 		},
-		{
-			testHeading: "Quiet",
-			isQuiet: true,
-		},
-		{
-			testHeading: "Static white",
-			staticColor: "white",
-		},
-		{
-			testHeading: "Static white - quiet",
-			staticColor: "white",
-			isQuiet: true,
-		},
 	],
 	stateData: [
 		{
 			testHeading: "Disabled",
 			isDisabled: true,
 		},
+		{
+			testHeading: "Hover",
+			isHovered: true,
+		},
+		{
+			testHeading: "Down",
+			isActive: true,
+		},
 	]
 });

components/clearbutton/stories/template.js

@@ -10,10 +10,10 @@ import "../index.css";
 export const Template = ({
 	rootClass = "spectrum-ClearButton",
 	isDisabled = false,
+	isHovered = false,
+	isActive = false,
 	size = "m",
-	isQuiet = false,
 	isFocusable = true,
-	staticColor,
 	id = getRandomId("clearbutton"),
 	onclick = () => {},
 	customClasses = [],
@@ -24,14 +24,9 @@ export const Template = ({
 		class=${classMap({
 			[rootClass]: true,
 			[`${rootClass}--size${size?.toUpperCase()}`]: typeof size !== "undefined",
-			[`${rootClass}--quiet`]: isQuiet,
-			[`${rootClass}--overBackground`]: staticColor === "white",
-			/**
-			 * There aren't styles for `--staticWhite` in clear button (yet)
-			 * but this makes it easier to support in the testing grid
-			 */
-			[`${rootClass}--staticWhite`]: staticColor === "white",
 			"is-disabled": isDisabled,
+			"is-hover": isHovered,
+			"is-active": isActive,
 			...customClasses.reduce((a, c) => ({ ...a, [c]: true }), {}),
 		})}
 		id=${ifDefined(id)}