@spark-web/button 1.0.3 → 1.1.0

package/README.md

@@ -45,95 +45,56 @@ options are: `low` and `high`.
 Defaults to `high`.
 
 ```jsx live
-<Stack gap="large">
-  <Text weight="strong">High prominence</Text>
-  <Inline gap="small">
-    <Button prominence="high" tone="primary">
-      <LightBulbIcon />
-      Primary
-    </Button>
-    <Button prominence="high" tone="secondary">
-      <LightBulbIcon />
-      Secondary
-    </Button>
-    <Button prominence="high" tone="neutral">
-      <LightBulbIcon />
-      Neutral
-    </Button>
-    <Button prominence="high" tone="positive">
-      <LightBulbIcon />
-      Positive
-    </Button>
-    <Button prominence="high" tone="critical">
-      <LightBulbIcon />
-      Critical
-    </Button>
-  </Inline>
-  <Divider />
-  <Text weight="strong">Low prominence</Text>
-  <Inline gap="small">
-    <Button prominence="low" tone="primary">
-      <LightBulbIcon />
-      Primary
-    </Button>
-    <Button prominence="low" tone="secondary">
-      <LightBulbIcon />
-      Secondary
-    </Button>
-    <Button prominence="low" tone="neutral">
-      <LightBulbIcon />
-      Neutral
-    </Button>
-    <Button prominence="low" tone="positive">
-      <LightBulbIcon />
-      Positive
-    </Button>
-    <Button prominence="low" tone="critical">
-      <LightBulbIcon />
-      Critical
-    </Button>
-    <Button prominence="low" tone="caution">
-      <LightBulbIcon />
-      Critical
-    </Button>
-    <Button prominence="low" tone="info">
-      <LightBulbIcon />
-      Informative
-    </Button>
-  </Inline>
-  <Divider />
-  <Text weight="strong">None prominence</Text>
-  <Inline gap="small">
-    <Button prominence="none" tone="primary">
-      <LightBulbIcon />
-      Primary
-    </Button>
-    <Button prominence="none" tone="secondary">
-      <LightBulbIcon />
-      Secondary
-    </Button>
-    <Button prominence="none" tone="neutral">
-      <LightBulbIcon />
-      Neutral
-    </Button>
-    <Button prominence="none" tone="positive">
-      <LightBulbIcon />
-      Positive
-    </Button>
-    <Button prominence="none" tone="critical">
-      <LightBulbIcon />
-      Critical
-    </Button>
-    <Button prominence="none" tone="caution">
-      <LightBulbIcon />
-      Critical
-    </Button>
-    <Button prominence="none" tone="info">
-      <LightBulbIcon />
-      Informative
-    </Button>
-  </Inline>
-</Stack>
+const baseButtonTones = [
+  { label: 'Primary', tone: 'primary' },
+  { label: 'Secondary', tone: 'secondary' },
+  { label: 'Neutral', tone: 'neutral' },
+  { label: 'Positive', tone: 'positive' },
+  { label: 'Critical', tone: 'critical' },
+];
+
+const extraButtonTones = [
+  { label: 'Caution', tone: 'caution' },
+  { label: 'Informative', tone: 'info' },
+];
+
+return (
+  <Stack gap="large" dividers>
+    <Stack gap="large">
+      <Text weight="strong">High prominence</Text>
+      <Inline gap="small">
+        {baseButtonTones.map(({ label, tone }) => (
+          <Button key={label} tone={tone} prominence="high">
+            <LightBulbIcon />
+            {label}
+          </Button>
+        ))}
+      </Inline>
+    </Stack>
+    <Stack gap="large">
+      <Text weight="strong">Low prominence</Text>
+      <Inline gap="small">
+        {baseButtonTones.concat(extraButtonTones).map(({ label, tone }) => (
+          <Button key={label} tone={tone} prominence="low">
+            <LightBulbIcon />
+            {label}
+          </Button>
+        ))}
+      </Inline>
+    </Stack>
+    <Stack gap="large">
+      <Text weight="strong">None prominence</Text>
+      <Inline gap="small">
+        {baseButtonTones.concat(extraButtonTones).map(({ label, tone }) => (
+          <Button key={label} tone={tone} prominence="none">
+            <LightBulbIcon />
+            {label}
+          </Button>
+        ))}
+      </Inline>
+    </Stack>
+  </Stack>
+);
 ```
 
 ## Size
@@ -186,6 +147,44 @@ users of assistive technology.
 </Inline>
 ```
 
+## Loading
+
+Buttons have an optional `loading` prop to indicate that an action is in
+progress. When this is true a spinner will be displayed.
+
+Note: buttons will not be interative when `loading` is true.
+
+```jsx live
+const [loading, setLoading] = React.useState(false);
+const toggle = event => setLoading(event.target.checked);
+
+return (
+  <Stack gap="large">
+    <Checkbox size="medium" checked={loading} onChange={toggle}>
+      <Text>Toggle loading state</Text>
+    </Checkbox>
+    <Inline gap="large">
+      <Button label="Download" loading={loading}>
+        <DownloadIcon />
+      </Button>
+      <Button loading={loading}>
+        <DownloadIcon />
+        Download
+      </Button>
+    </Inline>
+    <Inline gap="large">
+      <Button label="Download" size="large" loading={loading}>
+        <DownloadIcon />
+      </Button>
+      <Button size="large" loading={loading}>
+        <DownloadIcon />
+        Download
+      </Button>
+    </Inline>
+  </Stack>
+);
+```
+
 ## ButtonLink
 
 The appearance of a button, with the semantics of a link — shares `Button` API,
@@ -205,13 +204,17 @@ with the exception of `href` vs `onClick` props.
 | aria-describedby? | string                                                                                   |           | Identifies the element (or elements) that describes the object. Only applicable for `Button`.                                             |
 | aria-expanded?    | string                                                                                   |           | Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. Only applicable for `Button`. |
 | children          | string \| React.ReactElement\<IconProps>                                                 |           | Children element to be rendered inside the button.                                                                                        |
-| data?             | Object                                                                                   |           | Allows setting of data attributes on the button.                                                                                          |
+| data?             | [DataAttributeMap][data-attribute-map]                                                   |           | Allows setting of data attributes on the button.                                                                                          |
 | disabled?         | boolean                                                                                  |           | When true, prevents `onClick` from firing. Only applicable for `Button`.                                                                  |
 | href              | string                                                                                   |           | Specifies the url the button should redirect to upon being clicked. Only applicable for `ButtonLink`.                                     |
 | id?               | string                                                                                   |           | Unique identifier for the button.                                                                                                         |
 | label?            | string                                                                                   |           | Implicit label for buttons only required for icon-only buttons for accessibility reasons.                                                 |
+| loading?          | boolean                                                                                  |           | When true, the button will display a loading spinner.                                                                                     |
 | onClick?          | Function                                                                                 |           | Function to be fired following a click event of the button. Only applicable for `Button`.                                                 |
 | prominence?       | 'high' \| 'low'                                                                          | 'high'    | Sets the visual prominence of the button.                                                                                                 |
 | size?             | 'medium' \| 'large'                                                                      | 'medium'  | Sets the size of the button.                                                                                                              |
 | tone?             | 'primary' \| 'secondary' \| 'neutral' \| 'positive' \| 'caution' \| 'critical' \| 'info' | 'primary' | Sets the tone of the button.                                                                                                              |
 | type?             | 'button' \| 'submit' \| 'reset'                                                          | 'button'  | Sets the button type. Only applicable for `Button`.                                                                                       |
+
+[data-attribute-map]:
+  https://github.com/brighte-labs/spark-web/blob/e7f6f4285b4cfd876312cc89fbdd094039aa239a/packages/utils/src/internal/buildDataAttributes.ts#L1

package/dist/declarations/src/Button.d.ts

@@ -1,22 +1,34 @@
-import * as React from 'react';
+import type { MouseEvent as ReactMouseEvent } from 'react';
 import type { CommonButtonProps, NativeButtonProps } from './types';
 export declare type ButtonProps = CommonButtonProps & {
+    /**
+     * Identifies the element (or elements) whose contents or presence
+     * are controlled by the current element.
+     */
     'aria-controls'?: NativeButtonProps['aria-controls'];
+    /**  Identifies the element (or elements) that describes the object. */
     'aria-describedby'?: NativeButtonProps['aria-describedby'];
+    /**  Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed. */
     'aria-expanded'?: NativeButtonProps['aria-expanded'];
+    /** When true, prevents onClick from firing. */
+    disabled?: boolean;
+    /** When true, the button will display a loading spinner. */
+    loading?: boolean;
+    /** Function to be fired following a click event of the button. Only applicable for Button. */
     onClick?: NativeButtonProps['onClick'];
+    /** The size of the button. */
     size?: CommonButtonProps['size'];
+    /** Provide an alternate type if the button is within a form. */
     type?: 'button' | 'submit' | 'reset';
-    disabled?: boolean;
 };
 /**
  * Buttons are used to initialize an action, their label should express what
  * action will occur when the user interacts with it.
  */
-export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
 /**
  * Prevent click events when the component is "disabled".
  * Note: we don't want to actually disable a button element for several reasons.
  * One being because that would prohibit the use of tooltips.
  */
-export declare function getPreventableClickHandler(onClick: NativeButtonProps['onClick'], disabled: boolean): (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
+export declare function getPreventableClickHandler(onClick: NativeButtonProps['onClick'], disabled: boolean): (event: ReactMouseEvent<HTMLButtonElement, MouseEvent>) => void;

package/dist/declarations/src/resolveButtonChildren.d.ts

@@ -1,8 +1,9 @@
 import type { ButtonChildrenProps, ButtonProminence, ButtonSize, ButtonTone } from './types';
 declare type ResolveButtonChildren = ButtonChildrenProps & {
+    isLoading: boolean;
     prominence: ButtonProminence;
     size: ButtonSize;
     tone: ButtonTone;
 };
-export declare const resolveButtonChildren: ({ children, prominence, size, tone, }: ResolveButtonChildren) => JSX.Element[];
+export declare const resolveButtonChildren: ({ children, isLoading, prominence, size, tone, }: ResolveButtonChildren) => JSX.Element[];
 export {};

package/dist/declarations/src/types.d.ts

@@ -11,13 +11,19 @@ declare type ChildrenWithText = {
     children: string | [ReactElement<IconProps>, string] | [string, ReactElement<IconProps>];
 };
 declare type IconOnly = {
+    /**
+     * Implicit label for buttons only required for icon-only buttons
+     * for accessibility reasons.
+     */
     label: string;
     children: ReactElement<IconProps>;
 };
 export declare type ButtonChildrenProps = ChildrenWithText | IconOnly;
 export declare type NativeButtonProps = ButtonHTMLAttributes<HTMLButtonElement>;
 export declare type CommonButtonProps = {
+    /** Allows setting of data attributes on the underlying element. */
     data?: DataAttributeMap;
+    /** Unique identifier for the underlying element. */
     id?: string;
 } & ButtonChildrenProps & ButtonStyleProps;
 export declare type ButtonStyleProps = {

package/dist/spark-web-button.cjs.dev.js

@@ -4,37 +4,18 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var _objectSpread = require('@babel/runtime/helpers/objectSpread2');
 var _objectWithoutProperties = require('@babel/runtime/helpers/objectWithoutProperties');
+var a11y = require('@spark-web/a11y');
 var box = require('@spark-web/box');
+var spinner = require('@spark-web/spinner');
 var internal = require('@spark-web/utils/internal');
-var React = require('react');
+var react = require('react');
+var css = require('@emotion/css');
 var text = require('@spark-web/text');
 var jsxRuntime = require('react/jsx-runtime');
-var css = require('@emotion/css');
-var a11y = require('@spark-web/a11y');
 var theme = require('@spark-web/theme');
 var link = require('@spark-web/link');
 var ts = require('@spark-web/utils/ts');
 
-function _interopNamespace(e) {
-  if (e && e.__esModule) return e;
-  var n = Object.create(null);
-  if (e) {
-    Object.keys(e).forEach(function (k) {
-      if (k !== 'default') {
-        var d = Object.getOwnPropertyDescriptor(e, k);
-        Object.defineProperty(n, k, d.get ? d : {
-          enumerable: true,
-          get: function () { return e[k]; }
-        });
-      }
-    });
-  }
-  n["default"] = e;
-  return Object.freeze(n);
-}
-
-var React__namespace = /*#__PURE__*/_interopNamespace(React);
-
 var variants = {
   high: {
     primary: {
@@ -179,32 +160,39 @@ var mapTokens = {
 
 var resolveButtonChildren = function resolveButtonChildren(_ref) {
   var children = _ref.children,
+      isLoading = _ref.isLoading,
       prominence = _ref.prominence,
       size = _ref.size,
       tone = _ref.tone;
   var variant = variants[prominence][tone];
-  return React.Children.map(children, function (child) {
+  return react.Children.map(children, function (child) {
     if (typeof child === 'string') {
-      return /*#__PURE__*/jsxRuntime.jsx(text.Text, {
-        as: "span",
-        baseline: false,
-        overflowStrategy: "nowrap",
-        weight: "strong",
-        size: mapTokens.fontSize[size],
-        tone: variant === null || variant === void 0 ? void 0 : variant.textTone,
-        children: child
+      return /*#__PURE__*/jsxRuntime.jsx(HiddenWhenLoading, {
+        isLoading: isLoading,
+        children: /*#__PURE__*/jsxRuntime.jsx(text.Text, {
+          as: "span",
+          baseline: false,
+          overflowStrategy: "nowrap",
+          weight: "semibold",
+          size: mapTokens.fontSize[size],
+          tone: variant === null || variant === void 0 ? void 0 : variant.textTone,
+          children: child
+        })
       });
     }
 
-    if ( /*#__PURE__*/React.isValidElement(child)) {
-      return /*#__PURE__*/React.cloneElement(child, {
-        // Dismiss buttons need to be `xxsmall`
-        // For everything else, we force them to be `xsmall`
-        size: child.props.size === 'xxsmall' ? child.props.size : 'xsmall',
-        // If the button is low prominence with a decorative tone we want to force
-        // the tone to be the same as the button
-        // We also don't want users to override the tone of the icon inside of the button
-        tone: variant === null || variant === void 0 ? void 0 : variant.textTone
+    if ( /*#__PURE__*/react.isValidElement(child)) {
+      return /*#__PURE__*/jsxRuntime.jsx(HiddenWhenLoading, {
+        isLoading: isLoading,
+        children: /*#__PURE__*/react.cloneElement(child, {
+          // Dismiss buttons need to be `xxsmall`
+          // For everything else, we force them to be `xsmall`
+          size: child.props.size === 'xxsmall' ? child.props.size : 'xsmall',
+          // If the button is low prominence with a decorative tone we want to force
+          // the tone to be the same as the button
+          // We also don't want users to override the tone of the icon inside of the button
+          tone: variant === null || variant === void 0 ? void 0 : variant.textTone
+        })
       });
     }
 
@@ -212,6 +200,17 @@ var resolveButtonChildren = function resolveButtonChildren(_ref) {
   });
 };
 
+function HiddenWhenLoading(_ref2) {
+  var children = _ref2.children,
+      isLoading = _ref2.isLoading;
+  return /*#__PURE__*/jsxRuntime.jsx("span", {
+    className: isLoading ? css.css({
+      opacity: 0
+    }) : undefined,
+    children: children
+  });
+}
+
 function useButtonStyles(_ref) {
   var iconOnly = _ref.iconOnly,
       prominence = _ref.prominence,
@@ -269,13 +268,13 @@ function useButtonStyles(_ref) {
   return buttonStyleProps;
 }
 
-var _excluded$1 = ["aria-controls", "aria-describedby", "aria-expanded", "data", "disabled", "id", "onClick", "prominence", "size", "tone", "type"];
+var _excluded$1 = ["aria-controls", "aria-describedby", "aria-expanded", "data", "disabled", "id", "loading", "onClick", "prominence", "size", "tone", "type"];
 
 /**
  * Buttons are used to initialize an action, their label should express what
  * action will occur when the user interacts with it.
  */
-var Button = /*#__PURE__*/React__namespace.forwardRef(function (_ref, ref) {
+var Button = /*#__PURE__*/react.forwardRef(function (_ref, ref) {
   var ariaControls = _ref['aria-controls'],
       ariaDescribedBy = _ref['aria-describedby'],
       ariaExpanded = _ref['aria-expanded'],
@@ -283,6 +282,8 @@ var Button = /*#__PURE__*/React__namespace.forwardRef(function (_ref, ref) {
       _ref$disabled = _ref.disabled,
       disabled = _ref$disabled === void 0 ? false : _ref$disabled,
       id = _ref.id,
+      _ref$loading = _ref.loading,
+      loading = _ref$loading === void 0 ? false : _ref$loading,
       onClick = _ref.onClick,
       _ref$prominence = _ref.prominence,
       prominence = _ref$prominence === void 0 ? 'high' : _ref$prominence,
@@ -300,18 +301,17 @@ var Button = /*#__PURE__*/React__namespace.forwardRef(function (_ref, ref) {
     size: size,
     tone: tone,
     prominence: prominence
-  }); // TODO: add loading state for button
-
-  var isDisabled = disabled;
-  /* || loading */
-
+  });
+  var isDisabled = disabled || loading;
+  var isLoading = loading && !disabled;
+  var variant = variants[prominence][tone];
   /**
    * handle "disabled" behaviour w/o disabling buttons
    * @see https://axesslab.com/disabled-buttons-suck/
    */
 
   var handleClick = getPreventableClickHandler(onClick, isDisabled);
-  return /*#__PURE__*/jsxRuntime.jsx(box.Box, _objectSpread(_objectSpread(_objectSpread({
+  return /*#__PURE__*/jsxRuntime.jsxs(box.Box, _objectSpread(_objectSpread(_objectSpread({
     "aria-controls": ariaControls,
     "aria-describedby": ariaDescribedBy,
     "aria-disabled": isDisabled,
@@ -323,14 +323,17 @@ var Button = /*#__PURE__*/React__namespace.forwardRef(function (_ref, ref) {
     ref: ref,
     type: type
   }, buttonStyleProps), data ? internal.buildDataAttributes(data) : undefined), {}, {
-    children: resolveButtonChildren(_objectSpread(_objectSpread({}, props), {}, {
+    children: [resolveButtonChildren(_objectSpread(_objectSpread({}, props), {}, {
+      isLoading: isLoading,
       prominence: prominence,
       size: size,
       tone: tone
-    }))
+    })), isLoading && /*#__PURE__*/jsxRuntime.jsx(Loading, {
+      tone: variant === null || variant === void 0 ? void 0 : variant.textTone
+    })]
   }));
 });
-Button.displayName = 'Buttton';
+Button.displayName = 'Button';
 /**
  * Prevent click events when the component is "disabled".
  * Note: we don't want to actually disable a button element for several reasons.
@@ -347,6 +350,27 @@ function getPreventableClickHandler(onClick, disabled) {
   };
 }
 
+function Loading(_ref2) {
+  var tone = _ref2.tone;
+  return /*#__PURE__*/jsxRuntime.jsxs(box.Box, {
+    as: "span",
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    left: 0,
+    right: 0,
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "center",
+    children: [/*#__PURE__*/jsxRuntime.jsx(a11y.VisuallyHidden, {
+      children: "button loading indicator"
+    }), /*#__PURE__*/jsxRuntime.jsx(spinner.Spinner, {
+      size: "xsmall",
+      tone: tone
+    })]
+  });
+}
+
 var _excluded = ["data", "href", "id", "prominence", "size", "tone"];
 
 /** The appearance of a `Button`, with the semantics of a link. */
@@ -366,9 +390,9 @@ var ButtonLink = ts.forwardRefWithAs(function (_ref, ref) {
   var iconOnly = Boolean(props.label);
   var buttonStyleProps = useButtonStyles({
     iconOnly: iconOnly,
+    prominence: prominence,
     size: size,
-    tone: tone,
-    prominence: prominence
+    tone: tone
   });
   return /*#__PURE__*/jsxRuntime.jsx(box.Box, _objectSpread(_objectSpread(_objectSpread({
     "aria-label": props.label,
@@ -379,6 +403,7 @@ var ButtonLink = ts.forwardRefWithAs(function (_ref, ref) {
     ref: ref
   }, buttonStyleProps), data ? internal.buildDataAttributes(data) : undefined), {}, {
     children: resolveButtonChildren(_objectSpread(_objectSpread({}, props), {}, {
+      isLoading: false,
       prominence: prominence,
       size: size,
       tone: tone