Button - Loading

.changeset/eight-dolls-sniff.md

@@ -0,0 +1,5 @@
+---
+"@salt-ds/core": minor
+---
+
+Added `loading` prop/functionality to the Button component. This prop will display a spinner to indicate that the action is in progress. This is useful for actions that take some time to process, such as submitting a form or loading data.

packages/core/src/__tests__/__e2e__/button/Button.cy.tsx

@@ -3,7 +3,7 @@ import { composeStories } from "@storybook/react";
 import { checkAccessibility } from "../../../../../../cypress/tests/checkAccessibility";
 
 const composedStories = composeStories(buttonStories);
-const { Default, FocusableWhenDisabled } = composedStories;
+const { Default, FocusableWhenDisabled, LoadingSingle } = composedStories;
 
 describe("Given a Button", () => {
   checkAccessibility(composedStories);
@@ -51,6 +51,20 @@ describe("Given a Button", () => {
     cy.get("@clickSpy").should("not.be.called");
   });
 
+  it("should be focusable when loading", () => {
+    const clickSpy = cy.stub().as("clickSpy");
+    cy.mount(<LoadingSingle onClick={clickSpy} />);
+    cy.findByRole("button").should("have.attr", "data-loading", "true");
+    cy.realPress("Tab");
+    cy.findByRole("button").should("be.focused");
+    cy.realPress("Enter");
+    cy.get("@clickSpy").should("not.be.called");
+    cy.realPress("Space");
+    cy.get("@clickSpy").should("not.be.called");
+    cy.findByRole("button").realClick();
+    cy.get("@clickSpy").should("not.be.called");
+  });
+
   it("should apply type prop to button element", () => {
     cy.mount(<Default type="submit" />);
     cy.findByRole("button").should("have.attr", "type", "submit");

packages/core/src/button/Button.css

@@ -131,6 +131,22 @@
   --button-borderColor-disabled: var(--salt-actionable-accented-subtle-borderColor-disabled);
 }
 
+.saltButton-accented.saltButton-loading {
+  --button-text-color: var(--salt-actionable-accented-background);
+  --button-text-color-hover: var(--salt-actionable-accented-background);
+  --button-text-color-active: var(--salt-actionable-accented-background);
+  --button-text-color-disabled: var(--salt-actionable-accented-background);
+  --button-background: var(--salt-actionable-accented-background);
+  --button-background-hover: var(--salt-actionable-accented-background);
+  --button-background-active: var(--salt-actionable-accented-background);
+  --button-background-disabled: var(--salt-actionable-accented-background);
+  --button-borderColor: var(--salt-actionable-accented-borderColor);
+  --button-borderColor-hover: var(--salt-actionable-accented-borderColor);
+  --button-borderColor-active: var(--salt-actionable-accented-borderColor);
+  --button-borderColor-disabled: var(--salt-actionable-accented-borderColor);
+  cursor: progress;
+}
+
 .saltButton-neutral.saltButton-solid {
   --button-text-color: var(--salt-actionable-bold-foreground);
   --button-text-color-hover: var(--salt-actionable-bold-foreground-hover);
@@ -176,6 +192,22 @@
   --button-borderColor-disabled: var(--salt-actionable-subtle-borderColor-disabled);
 }
 
+.saltButton-neutral.saltButton-loading {
+  --button-text-color: var(--salt-actionable-background);
+  --button-text-color-hover: var(--salt-actionable-background);
+  --button-text-color-active: var(--salt-actionable-background);
+  --button-text-color-disabled: var(--salt-actionable-background);
+  --button-background: var(--salt-actionable-background);
+  --button-background-hover: var(--salt-actionable-background);
+  --button-background-active: var(--salt-actionable-background);
+  --button-background-disabled: var(--salt-actionable-background);
+  --button-borderColor: var(--salt-actionable-borderColor);
+  --button-borderColor-hover: var(--salt-actionable-borderColor);
+  --button-borderColor-active: var(--salt-actionable-borderColor);
+  --button-borderColor-disabled: var(--salt-actionable-borderColor);
+  cursor: progress;
+}
+
 .saltButton-negative.saltButton-solid {
   --button-text-color: var(--salt-actionable-negative-bold-foreground);
   --button-text-color-hover: var(--salt-actionable-negative-bold-foreground-hover);
@@ -221,6 +253,22 @@
   --button-borderColor-disabled: var(--salt-actionable-negative-subtle-borderColor-disabled);
 }
 
+.saltButton-negative.saltButton-loading {
+  --button-text-color: var(--salt-actionable-negative-background);
+  --button-text-color-hover: var(--salt-actionable-negative-background);
+  --button-text-color-active: var(--salt-actionable-negative-background);
+  --button-text-color-disabled: var(--salt-actionable-negative-background);
+  --button-background: var(--salt-actionable-negative-background);
+  --button-background-hover: var(--salt-actionable-negative-background);
+  --button-background-active: var(--salt-actionable-negative-background);
+  --button-background-disabled: var(--salt-actionable-negative-background);
+  --button-borderColor: var(--salt-actionable-negative-borderColor);
+  --button-borderColor-hover: var(--salt-actionable-negative-borderColor);
+  --button-borderColor-active: var(--salt-actionable-negative-borderColor);
+  --button-borderColor-disabled: var(--salt-actionable-negative-borderColor);
+  cursor: progress;
+}
+
 .saltButton-positive.saltButton-solid {
   --button-text-color: var(--salt-actionable-positive-bold-foreground);
   --button-text-color-hover: var(--salt-actionable-positive-bold-foreground-hover);
@@ -266,6 +314,22 @@
   --button-borderColor-disabled: var(--salt-actionable-positive-subtle-borderColor-disabled);
 }
 
+.saltButton-positive.saltButton-loading {
+  --button-text-color: var(--salt-actionable-positive-background);
+  --button-text-color-hover: var(--salt-actionable-positive-background);
+  --button-text-color-active: var(--salt-actionable-positive-background);
+  --button-text-color-disabled: var(--salt-actionable-positive-background);
+  --button-background: var(--salt-actionable-positive-background);
+  --button-background-hover: var(--salt-actionable-positive-background);
+  --button-background-active: var(--salt-actionable-positive-background);
+  --button-background-disabled: var(--salt-actionable-positive-background);
+  --button-borderColor: var(--salt-actionable-positive-borderColor);
+  --button-borderColor-hover: var(--salt-actionable-positive-borderColor);
+  --button-borderColor-active: var(--salt-actionable-positive-borderColor);
+  --button-borderColor-disabled: var(--salt-actionable-positive-borderColor);
+  cursor: progress;
+}
+
 .saltButton-caution.saltButton-solid {
   --button-text-color: var(--salt-actionable-caution-bold-foreground);
   --button-text-color-hover: var(--salt-actionable-caution-bold-foreground-hover);
@@ -310,3 +374,34 @@
   --button-borderColor-active: var(--salt-actionable-caution-subtle-borderColor-active);
   --button-borderColor-disabled: var(--salt-actionable-caution-subtle-borderColor-disabled);
 }
+
+.saltButton-caution.saltButton-loading {
+  --button-text-color: var(--salt-actionable-caution-background);
+  --button-text-color-hover: var(--salt-actionable-caution-background);
+  --button-text-color-active: var(--salt-actionable-caution-background);
+  --button-text-color-disabled: var(--salt-actionable-caution-background);
+  --button-background: var(--salt-actionable-caution-background);
+  --button-background-hover: var(--salt-actionable-caution-background);
+  --button-background-active: var(--salt-actionable-caution-background);
+  --button-background-disabled: var(--salt-actionable-caution-background);
+  --button-borderColor: var(--salt-actionable-caution-borderColor);
+  --button-borderColor-hover: var(--salt-actionable-caution-borderColor);
+  --button-borderColor-active: var(--salt-actionable-caution-borderColor);
+  --button-borderColor-disabled: var(--salt-actionable-caution-borderColor);
+  cursor: progress;
+}
+
+.saltButton-spinner {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.saltButton-sr-only {
+  position: fixed;
+  top: 0;
+  left: 0;
+  transform: translate(-100%, -100%);
+}

packages/core/src/button/Button.tsx

@@ -1,3 +1,4 @@
+import { Spinner } from "@salt-ds/core";
 import { useComponentCssInjection } from "@salt-ds/styles";
 import { useWindow } from "@salt-ds/window";
 import { clsx } from "clsx";
@@ -66,6 +67,13 @@ export interface ButtonProps extends ComponentPropsWithoutRef<"button"> {
    * @since 1.36.0.
    */
   sentiment?: ButtonSentiment;
+
+  /**
+   * If `true`, the button will be in a loading state. This allows a spinner to be nested inside the button.
+   *
+   * @since 1.38.0.
+   */
+  loading?: boolean;
 }
 
 function variantToAppearanceAndColor(
@@ -87,6 +95,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
       children,
       className,
       disabled,
+      loading,
       focusableWhenDisabled,
       onKeyUp,
       onKeyDown,
@@ -101,6 +110,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     ref?,
   ): ReactElement<ButtonProps> {
     const { active, buttonProps } = useButton({
+      loading,
       disabled,
       focusableWhenDisabled,
       onKeyUp,
@@ -119,6 +129,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
     const mapped = variantToAppearanceAndColor(variant);
     const appearance: ButtonAppearance =
       appearanceProp ?? mapped.appearance ?? "solid";
+
     const sentiment: ButtonSentiment =
       sentimentProp ?? mapped.sentiment ?? "neutral";
 
@@ -132,6 +143,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
           withBaseName(),
           withBaseName(variant),
           {
+            [withBaseName("loading")]: loading,
             [withBaseName("disabled")]: disabled,
             [withBaseName("active")]: active,
             [withBaseName(appearance)]: appearance,
@@ -143,6 +155,11 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
         ref={ref}
         type={type}
       >
+        {loading && (
+          <div className={withBaseName("spinner")} aria-hidden>
+            <Spinner size="small" aria-hidden disableAnnouncer />
+          </div>
+        )}
         {children}
       </button>
     );

packages/core/src/button/useButton.ts

@@ -7,6 +7,7 @@ import {
 } from "react";
 
 export interface ButtonHookProps<T extends Element> {
+  loading?: boolean;
   disabled?: boolean;
   focusableWhenDisabled?: boolean;
   onKeyUp?: (event: KeyboardEvent<T>) => void;
@@ -19,6 +20,7 @@ export interface ButtonHookResult<T extends Element> {
   active: boolean;
   buttonProps: {
     "aria-disabled"?: boolean;
+    "data-loading"?: boolean;
     disabled?: boolean;
     tabIndex: number;
     onBlur: (event: FocusEvent<T>) => void;
@@ -29,6 +31,7 @@ export interface ButtonHookResult<T extends Element> {
 }
 
 export const useButton = <T extends Element>({
+  loading,
   disabled,
   focusableWhenDisabled,
   onKeyUp,
@@ -83,10 +86,11 @@ export const useButton = <T extends Element>({
 
   const buttonProps = {
     "aria-disabled": disabled && focusableWhenDisabled ? true : undefined,
+    "data-loading": loading,
     disabled: disabled && !focusableWhenDisabled,
     tabIndex: disabled && !focusableWhenDisabled ? -1 : 0,
     onBlur: handleBlur,
-    onClick: !disabled ? handleClick : undefined,
+    onClick: !loading && !disabled ? handleClick : undefined,
     onKeyDown: handleKeyDown,
     onKeyUp: handleKeyUp,
   };

packages/core/stories/button/button.qa.stories.css

@@ -0,0 +1,3 @@
+.saltButton.noSpin .saltSpinner-spinner {
+  animation: none;
+}