docs(button): update clear-button details

Author: castastrophe

.changeset/hot-cups-report.md

@@ -1,6 +1,17 @@
 ---
-'@spectrum-web-components/clear-button': patch
+'@spectrum-web-components/button': minor
+'@spectrum-web-components/clear-button': minor
 '@spectrum-web-components/styles': patch
 ---
 
-More details forthcoming
+Clear button styles have been updated to the latest Spectrum CSS version of the clear button.
+
+As the updated styles now offer additional styling options, we have added the following API to the clear button:
+
+- `quiet` - when set to true, the button will be rendered as a quiet button. This is useful for cases where you want to use the clear button in a more subtle way.
+- `disabled` - when set to true, the button will be rendered as a disabled button.
+- `static-color` - currently this only supports the `white` context color. This is useful for cases where the button appears on a dark background texture. This is a replacement for the previously used `variant="overBackground"` attribute which is deprecated.
+
+### Deprecation
+
+The `variant="overBackground"` attribute is deprecated; please use the new `static-color="white"` attribute instead. When this property is used in the component, a deprecation warning will be shown in the console when in debug mode. The `variant` attribute will be removed in a future release.

packages/button/clear-button.md

@@ -93,6 +93,22 @@ The label for an `<sp-clear-button>` element can be set via it's default slot or
 </sp-tab-panel>
 </sp-tabs>
 
+#### Quiet
+
+The `quiet` attribute will render the `<sp-clear-button>` as a quiet button. This is useful for cases where you want to use the clear button in a more subtle way.
+
+```html
+<sp-clear-button quiet label="Clear content"></sp-clear-button>
+```
+
+#### Static color
+
+The `static-color` attribute will render the `<sp-clear-button>` with a static color. This is useful for cases where the button appears on a dark background texture. This is a replacement for the previously used `variant="overBackground"` attribute which is deprecated.
+
+```html
+<sp-clear-button static-color="white" label="Clear content"></sp-clear-button>
+```
+
 ### States
 
 In addition to the variant, the `<sp-clear-button>` elements supports a disabled state, which can be applied by adding the attribute `disabled`.

packages/button/src/ClearButton.ts

@@ -64,16 +64,21 @@ export class ClearButton extends SizedMixin(StyledButton, {
         return [...super.styles, buttonStyles, crossMediumStyles];
     }
 
+    @property({ type: Boolean, reflect: true })
+    public quiet = false;
+
     /**
      * The visual variant to apply to this button.
      * @deprecated Use `static-color='white'` instead.
      */
     @property({ reflect: true })
     public set variant(variant: 'overBackground' | undefined) {
-        const oldValue = this.variant;
+        const oldValue = this._variant;
+        const oldStaticColor = this.staticColor;
         if (variant !== 'overBackground') {
             this.removeAttribute('variant');
             this._variant = undefined;
+            this.staticColor = undefined;
             return;
         }
 
@@ -92,6 +97,7 @@ export class ClearButton extends SizedMixin(StyledButton, {
         }
 
         this.requestUpdate('variant', oldValue);
+        this.requestUpdate('staticColor', oldStaticColor);
     }
 
     public get variant(): 'overBackground' | undefined {
@@ -103,7 +109,7 @@ export class ClearButton extends SizedMixin(StyledButton, {
     /**
      * The visual variant to apply to this button.
      */
-    @property({ reflect: true })
+    @property({ reflect: true, attribute: 'static-color' })
     public staticColor: 'white' | undefined;
 
     protected override get buttonContent(): TemplateResult[] {

packages/button/test/clear-button.test.ts

@@ -13,15 +13,15 @@
 import '@spectrum-web-components/button/sp-clear-button.js';
 import { ClearButton } from '@spectrum-web-components/button';
 import { ElementSize } from '@spectrum-web-components/base';
-import { expect, fixture, html } from '@open-wc/testing';
+import { elementUpdated, expect, fixture, html } from '@open-wc/testing';
 import { testForLitDevWarnings } from '../../../test/testing-helpers';
+import { SinonStub, stub } from 'sinon';
 
 describe('Clear Button', () => {
-    testForLitDevWarnings(
-        async () =>
-            await fixture<ClearButton>(html`
-                <sp-clear-button size="m" label="Clear"></sp-clear-button>
-            `)
+    testForLitDevWarnings(async () =>
+        fixture<ClearButton>(html`
+            <sp-clear-button size="m" label="Clear"></sp-clear-button>
+        `)
     );
     (['s', 'm', 'l', 'xl'] as ElementSize[]).map((size) => {
         it(`loads - ${size}`, async () => {
@@ -32,6 +32,21 @@ describe('Clear Button', () => {
             await expect(el).to.be.accessible();
         });
     });
+    it(`loads static-color="white" when variant="overBackground"`, async () => {
+        const el = await fixture<ClearButton>(html`
+            <sp-clear-button
+                label="Clear"
+                variant="overBackground"
+            ></sp-clear-button>
+        `);
+
+        await elementUpdated(el);
+
+        // Check that the staticColor is set to white
+        expect(el.staticColor).to.equal('white');
+        expect(el.hasAttribute('static-color')).to.be.true;
+        expect(el.getAttribute('static-color')).to.equal('white');
+    });
 
     describe('dev mode', () => {
         let consoleStub: SinonStub;
@@ -61,11 +76,6 @@ describe('Clear Button', () => {
 
             expect(consoleStub).to.be.calledOnce;
             expect(warning.includes(expectedContent)).to.be.true;
-
-            // Check that the staticColor is set to white
-            expect(el.staticColor).to.equal('white');
-            expect(el.hasAttribute('static-color')).to.be.true;
-            expect(el.getAttribute('static-color')).to.equal('white');
         });
     });
 });

packages/clear-button/src/clear-button-overrides.css

@@ -10,15 +10,3 @@
  * governing permissions and limitations under the License.
  */
 
-:host {
-    --spectrum-clear-button-background-color: var(--system-clear-button-background-color);
-    --spectrum-clear-button-background-color-hover: var(--system-clear-button-background-color-hover);
-    --spectrum-clear-button-background-color-down: var(--system-clear-button-background-color-down);
-    --spectrum-clear-button-background-color-key-focus: var(--system-clear-button-background-color-key-focus);
-}
-
-:host([static-color="white"]) {
-    --spectrum-clear-button-background-color-hover: var(--system-clear-button-static-white-background-color-hover);
-    --spectrum-clear-button-background-color-down: var(--system-clear-button-static-white-background-color-down);
-    --spectrum-clear-button-background-color-key-focus: var(--system-clear-button-static-white-background-color-key-focus);
-}

packages/clear-button/src/clear-button.css

@@ -10,9 +10,146 @@
  * governing permissions and limitations under the License.
  */
 
-@import url("./spectrum-clear-button.css");
-@import url("./clear-button-overrides.css");
+:host {
+    --spectrum-clear-button-background-color: var(--system-clear-button-background-color);
+    --spectrum-clear-button-background-color-hover: var(--system-clear-button-background-color-hover);
+    --spectrum-clear-button-background-color-down: var(--system-clear-button-background-color-down);
+    --spectrum-clear-button-background-color-key-focus: var(--system-clear-button-background-color-key-focus);
+}
+
+:host([static-color="white"]) {
+    --spectrum-clear-button-background-color-hover: var(--system-clear-button-static-white-background-color-hover);
+    --spectrum-clear-button-background-color-down: var(--system-clear-button-static-white-background-color-down);
+    --spectrum-clear-button-background-color-key-focus: var(--system-clear-button-static-white-background-color-key-focus);
+}
 
 :host {
+    --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-icon-color: var(--spectrum-neutral-content-color-default);
+    --spectrum-clear-button-icon-color-hover: var(--spectrum-neutral-content-color-hover);
+    --spectrum-clear-button-icon-color-down: var(--spectrum-neutral-content-color-down);
+    --spectrum-clear-button-icon-color-key-focus: var(--spectrum-neutral-content-color-key-focus);
+
     box-sizing: border-box;
+    block-size: var(--mod-clear-button-height, var(--spectrum-clear-button-height));
+    inline-size: var(--mod-clear-button-width, var(--spectrum-clear-button-width));
+    background-color: var(--mod-clear-button-background-color, transparent);
+    padding: var(--mod-clear-button-padding, var(--spectrum-clear-button-padding));
+    color: var(--mod-clear-button-icon-color, var(--spectrum-clear-button-icon-color));
+    border: none;
+    border-radius: 100%;
+    margin: 0;
+}
+
+:host([size="s"]) {
+    --spectrum-clear-button-height: var(--spectrum-component-height-75);
+    --spectrum-clear-button-width: var(--spectrum-component-height-75);
+}
+
+:host([size="l"]) {
+    --spectrum-clear-button-height: var(--spectrum-component-height-200);
+    --spectrum-clear-button-width: var(--spectrum-component-height-200);
+}
+
+:host([size="xl"]) {
+    --spectrum-clear-button-height: var(--spectrum-component-height-300);
+    --spectrum-clear-button-width: var(--spectrum-component-height-300);
+}
+
+:host([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;
+}
+
+:host([static-color="white"]) {
+    --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;
+}
+
+:host(:disabled),
+:host([disabled]) {
+    --mod-clear-button-icon-color: var(--mod-clear-button-icon-color-disabled, var(--spectrum-disabled-content-color));
+    --mod-clear-button-icon-color-hover: var(--spectrum-disabled-content-color);
+    --mod-clear-button-icon-color-down: var(--spectrum-disabled-content-color);
+    --mod-clear-button-background-color: var(--mod-clear-button-background-color-disabled, transparent);
+}
+
+:host(:not(:disabled)),
+:host(:not([disabled])) {
+    cursor: pointer;
+}
+
+.icon {
+    margin-block: 0;
+    margin-inline: auto;
+}
+
+@media (hover: hover) {
+    :host(:hover:not(:disabled)),
+    :host(:hover:not([disabled])) {
+        color: var(--highcontrast-clear-button-icon-color-hover, var(--mod-clear-button-icon-color-hover, var(--spectrum-clear-button-icon-color-hover)));
+    }
+
+    :host(:hover:not(:disabled)) .fill,
+    :host(:hover:not([disabled])) .fill {
+        background-color: var(--mod-clear-button-background-color-hover, var(--spectrum-clear-button-background-color-hover));
+    }
+}
+
+:host(:is(:active, [active]):not(:disabled)),
+:host(:is(:active, [active]):not([disabled])) {
+    color: var(--mod-clear-button-icon-color-down, var(--spectrum-clear-button-icon-color-down));
+}
+
+:host(:is(:active, [active]):not(:disabled)),
+:host(:is(:active, [active]):not([disabled])) .fill {
+    background-color: var(--mod-clear-button-background-color-down, var(--spectrum-clear-button-background-color-down));
+}
+
+:host(:not(:disabled):focus-visible),
+:host(:not([disabled]):focus-visible),
+:host(:not(:disabled):focus-within),
+:host(:not([disabled]):focus-within) {
+    color: var(--mod-clear-button-icon-color-key-focus, var(--spectrum-clear-button-icon-color-key-focus));
+}
+
+:host(:not(:disabled):focus-visible) .fill,
+:host(:not([disabled]):focus-visible) .fill,
+:host(:not(:disabled):focus-within) .fill,
+:host(:not([disabled]):focus-within) .fill {
+    background-color: var(--mod-clear-button-background-color-key-focus, var(--spectrum-clear-button-background-color-key-focus));
+}
+
+.icon {
+    color: inherit;
+}
+
+.fill {
+    background-color: var(--mod-clear-button-background-color, var(--spectrum-clear-button-background-color));
+    inline-size: 100%;
+    block-size: 100%;
+    border-radius: 100%;
+    justify-content: center;
+    align-items: center;
+    display: flex;
+}
+
+:host([variant="overBackground"]:focus-visible),
+:host([static-color="white"]:focus-visible) {
+    outline: none;
+}
+
+@media (forced-colors: active) {
+    :host(:not(:disabled)),
+    :host(:not([disabled])) {
+        --highcontrast-clear-button-icon-color-hover: Highlight;
+    }
 }