@spark-web/button 0.0.0-snapshot-release-20220907020533

package/README.md

@@ -0,0 +1,213 @@
+---
+title: Button
+storybookPath: forms-buttons-button--default
+isExperimentalPackage: true
+---
+
+Buttons are clickable elements that are used to trigger actions. They
+communicate calls to action to the user and allow users to interact with pages
+in a variety of ways. Button labels express what action will occur when the user
+interacts with it.
+
+## Tone
+
+Button tones can be broken up into two types; decorative and semantic.
+
+For destructive actions like “delete” you should use the semantic `tone` of
+`critical`.
+
+For buttons that have no semantic action type (more common on marketing pages)
+use one of our decorative `tones`.
+
+Defaults to `primary`.
+
+```jsx live
+<Stack gap="large">
+  <Text weight="strong">Decorative tones</Text>
+  <Inline gap="small">
+    <Button tone="primary">Primary</Button>
+    <Button tone="secondary">Secondary</Button>
+  </Inline>
+  <Divider />
+  <Text weight="strong">Semantic tones</Text>
+  <Inline gap="small">
+    <Button tone="neutral">Neutral</Button>
+    <Button tone="positive">Positive</Button>
+    <Button tone="critical">Critical</Button>
+  </Inline>
+</Stack>
+```
+
+## Prominence
+
+The appearance of the button can be customised with the prominence prop. Valid
+options are: `low` and `high`.
+
+Defaults to `high`.
+
+```jsx live
+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
+
+Button's are available in two size: `medium` and `large`.
+
+Defaults to `medium`.
+
+```jsx live
+<Inline gap="small">
+  <Button size="medium">Medium</Button>
+  <Button size="large">Large</Button>
+</Inline>
+```
+
+## Icons
+
+Icons can be placed next to labels to both clarify an action and call attention
+to a button.
+
+```jsx live
+<Inline gap="small">
+  <Button>
+    <DownloadIcon />
+    Download
+  </Button>
+  <Button tone="critical">
+    <TrashIcon />
+    Delete
+  </Button>
+</Inline>
+```
+
+### Icon only
+
+When using buttons that contain only an icon, you must provide a `label` for
+users of assistive technology.
+
+```jsx live
+<Inline gap="small">
+  <Button label="Download PDF">
+    <DownloadIcon />
+  </Button>
+  <Button tone="critical" label="Delete item">
+    <TrashIcon />
+  </Button>
+  <Button tone="neutral" label="Dismiss">
+    <XIcon size="xxsmall" />
+  </Button>
+</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,
+with the exception of `href` vs `onClick` props.
+
+```jsx live
+<Text>
+  <ButtonLink href="#">Visually a link, with button semantics</ButtonLink>
+</Text>
+```
+
+## BaseButton
+
+Unstyled button primitive that:
+
+- Forwards the button ref
+- Provides a default type of `button` (so it doesn't accidently submit forms if
+  left off)
+- Prevents `onClick` from firing when disabled without disabling the button
+- Forces focus of the underlying button when clicked (to address a bug in
+  Safari)
+
+## Button Props
+
+<PropsTable displayName="Button" />

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

@@ -0,0 +1,10 @@
+import type { BoxProps } from '@spark-web/box';
+import type { MouseEvent as ReactMouseEvent } from 'react';
+import type { NativeButtonProps } from './types';
+export declare type BaseButtonProps = NativeButtonProps & Partial<BoxProps>;
+export declare const BaseButton: import("react").ForwardRefExoticComponent<NativeButtonProps & Partial<BoxProps> & import("react").RefAttributes<HTMLButtonElement>>;
+/**
+ * handle "disabled" behaviour w/o disabling buttons
+ * @see https://axesslab.com/disabled-buttons-suck/
+ */
+export declare function getPreventableClickHandler(onClick: BaseButtonProps['onClick'], disabled: boolean): (event: ReactMouseEvent<HTMLButtonElement, MouseEvent>) => void;

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

@@ -0,0 +1,28 @@
+/// <reference types="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';
+};
+/**
+ * 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: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

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

@@ -0,0 +1,9 @@
+/// <reference types="react" />
+import type { LinkComponentProps } from '@spark-web/link';
+import type { CommonButtonProps } from './types';
+export declare type ButtonLinkProps = LinkComponentProps & CommonButtonProps;
+/** The appearance of a `Button`, with the semantics of a link. */
+export declare const ButtonLink: <Comp extends import("react").ElementType<any> = "a">(props: {
+    as?: Comp | undefined;
+    ref?: import("react").Ref<Comp extends "symbol" | "svg" | "animate" | "animateMotion" | "animateTransform" | "circle" | "clipPath" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "filter" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "marker" | "mask" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "stop" | "switch" | "text" | "textPath" | "tspan" | "use" | "view" | "set" | keyof HTMLElementTagNameMap ? (HTMLElementTagNameMap & Pick<SVGElementTagNameMap, "symbol" | "svg" | "animate" | "animateMotion" | "animateTransform" | "circle" | "clipPath" | "defs" | "desc" | "ellipse" | "feBlend" | "feColorMatrix" | "feComponentTransfer" | "feComposite" | "feConvolveMatrix" | "feDiffuseLighting" | "feDisplacementMap" | "feDistantLight" | "feDropShadow" | "feFlood" | "feFuncA" | "feFuncB" | "feFuncG" | "feFuncR" | "feGaussianBlur" | "feImage" | "feMerge" | "feMergeNode" | "feMorphology" | "feOffset" | "fePointLight" | "feSpecularLighting" | "feSpotLight" | "feTile" | "feTurbulence" | "filter" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "marker" | "mask" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "stop" | "switch" | "text" | "textPath" | "tspan" | "use" | "view" | "set">)[Comp] : Comp extends new (...args: any) => any ? InstanceType<Comp> : undefined> | undefined;
+} & Omit<import("react").PropsWithoutRef<import("react").ComponentProps<Comp>>, "as"> & ButtonLinkProps) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;

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

@@ -0,0 +1,8 @@
+export { BaseButton } from './BaseButton';
+export { Button } from './Button';
+export { ButtonLink } from './ButtonLink';
+export { useButtonStyles } from './useButtonStyles';
+export type { BaseButtonProps } from './BaseButton';
+export type { ButtonProps } from './Button';
+export type { ButtonLinkProps } from './ButtonLink';
+export type { UseButtonStylesProps } from './useButtonStyles';

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

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+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, isLoading, prominence, size, tone, }: ResolveButtonChildren) => JSX.Element[];
+export {};

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

@@ -0,0 +1,37 @@
+import type { BackgroundTone } from '@spark-web/a11y';
+import type { IconProps } from '@spark-web/icon';
+import type { DataAttributeMap } from '@spark-web/utils/internal';
+import type { ButtonHTMLAttributes, ReactElement } from 'react';
+import type { mapTokens } from './utils';
+export declare type ButtonSize = keyof typeof mapTokens[keyof typeof mapTokens];
+export declare type ButtonProminence = 'high' | 'low' | 'none';
+export declare type ButtonTone = Exclude<BackgroundTone, 'disabled'>;
+declare type ChildrenWithText = {
+    label?: never;
+    children: string | number | [ReactElement<IconProps>, string | number] | [string | number, 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 = {
+    /** Sets the visual prominence of the button. */
+    prominence?: ButtonProminence;
+    /** Sets the size of the button. */
+    size?: ButtonSize;
+    /** Sets the tone of the button. */
+    tone?: ButtonTone;
+};
+export {};

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

@@ -0,0 +1,88 @@
+import type { ButtonProminence, ButtonSize, ButtonTone } from './types';
+/**
+ * useButtonStyles
+ *
+ * Custom hook for styling buttons and certain links.
+ * Returns a tuple where the first item is an object of props to spread onto the
+ * underlying `Box` component, and the second item is a CSS object that can be
+ * passed to Emotion's `css` function.
+ */
+export declare function useButtonStyles({ iconOnly, prominence, size, tone, }: UseButtonStylesProps): readonly [{
+    readonly alignItems: "center";
+    readonly background: "body" | "input" | "infoLight" | "criticalLight" | "positiveLight" | "cautionLight" | "muted" | "disabled" | "backdrop" | "surface" | "surfaceMuted" | "surfacePressed" | "fieldAccent" | "inputPressed" | "inputDisabled" | "accent" | "accentMuted" | "neutral" | "neutralLow" | "primary" | "primaryLow" | "primaryMuted" | "secondary" | "secondaryLow" | "secondaryMuted" | "caution" | "cautionLow" | "cautionMuted" | "critical" | "criticalLow" | "criticalMuted" | "info" | "infoLow" | "infoMuted" | "positive" | "positiveLow" | "positiveMuted" | undefined;
+    readonly border: import("@spark-web/theme").ResponsiveProp<"standard" | "fieldAccent" | "accent" | "accentMuted" | "neutral" | "primary" | "secondary" | "caution" | "cautionMuted" | "critical" | "criticalMuted" | "info" | "infoMuted" | "positive" | "positiveMuted" | "standardInverted" | "field" | "fieldHover" | "fieldDisabled" | "primaryHover" | "primaryActive" | "secondaryHover" | "secondaryActive"> | undefined;
+    readonly borderWidth: import("@spark-web/theme").ResponsiveProp<"standard" | "large"> | undefined;
+    readonly borderRadius: "small" | "medium";
+    readonly cursor: "pointer";
+    readonly display: "inline-flex";
+    readonly gap: "small";
+    readonly height: "large" | "medium";
+    readonly justifyContent: "center";
+    readonly paddingX: "medium" | "xlarge" | undefined;
+    readonly position: "relative";
+    readonly width: "large" | "medium" | undefined;
+}, {
+    readonly '&:not([aria-disabled=true])': {
+        readonly ':hover': {
+            readonly borderColor: string | undefined;
+            readonly backgroundColor: string | undefined;
+            readonly '> *': {
+                readonly color: string | undefined;
+                readonly stroke: string | undefined;
+                readonly transitionProperty: string;
+                readonly transitionTimingFunction: string;
+                readonly transitionDuration: string;
+            };
+        };
+        readonly ':active': {
+            readonly borderColor: string | undefined;
+            readonly backgroundColor: string | undefined;
+            readonly transform: "scale(0.98)";
+            readonly '> *': {
+                readonly color: string | undefined;
+                readonly stroke: string | undefined;
+                readonly transitionProperty: string;
+                readonly transitionTimingFunction: string;
+                readonly transitionDuration: string;
+            };
+        };
+        readonly ':focus': {
+            boxShadow: string;
+            outline: string;
+            outlineOffset: string;
+        } | {
+            outline: string;
+            outlineOffset: string;
+        };
+    };
+    readonly '&[aria-disabled=true]': {
+        readonly backgroundColor: string | undefined;
+        readonly borderColor: string | undefined;
+        readonly cursor: "default";
+        readonly '*': {
+            readonly color: string | undefined;
+            readonly stroke: string | undefined;
+        };
+        readonly ':focus': {
+            boxShadow: string;
+            outline: string;
+            outlineOffset: string;
+        } | {
+            outline: string;
+            outlineOffset: string;
+        };
+    };
+    readonly transitionProperty: string;
+    readonly transitionTimingFunction: string;
+    readonly transitionDuration: string;
+}];
+export declare type UseButtonStylesProps = {
+    /** Whether the children of the button is a single icon or not. */
+    iconOnly: boolean;
+    /** Sets the visual prominence of the button. */
+    prominence: ButtonProminence;
+    /** Sets the size of the button. */
+    size: ButtonSize;
+    /** Sets the tone of the button. */
+    tone: ButtonTone;
+};

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

@@ -0,0 +1,43 @@
+import type { BoxProps } from '@spark-web/box';
+import type { ForegroundTone } from '@spark-web/text';
+import type { BrighteTheme } from '@spark-web/theme';
+import type { ButtonProminence, ButtonTone } from './types';
+declare type BaseButtonStyles = {
+    background: BoxProps['background'];
+    border?: BoxProps['border'];
+    borderWidth?: BoxProps['borderWidth'];
+    textTone?: ForegroundTone;
+};
+declare type HoverButtonStyles = {
+    backgroundHover: keyof BrighteTheme['backgroundInteractions'];
+    borderHover?: keyof BrighteTheme['border']['color'];
+    textToneHover?: keyof BrighteTheme['color']['foreground'];
+};
+declare type ActiveButtonStyles = {
+    backgroundActive: keyof BrighteTheme['backgroundInteractions'];
+    borderActive?: keyof BrighteTheme['border']['color'];
+    textToneActive?: keyof BrighteTheme['color']['foreground'];
+};
+declare type DisabledButtonStyles = {
+    backgroundDisabled: keyof BrighteTheme['color']['background'];
+    borderDisabled?: keyof BrighteTheme['border']['color'];
+    textToneDisabled: keyof BrighteTheme['color']['foreground'];
+};
+declare type ButtonStyles = BaseButtonStyles & HoverButtonStyles & ActiveButtonStyles & DisabledButtonStyles;
+declare type Variants = Record<ButtonProminence, Record<ButtonTone, ButtonStyles | undefined>>;
+export declare const variants: Variants;
+export declare const mapTokens: {
+    readonly fontSize: {
+        readonly medium: "small";
+        readonly large: "standard";
+    };
+    readonly size: {
+        readonly medium: "medium";
+        readonly large: "large";
+    };
+    readonly spacing: {
+        readonly medium: "medium";
+        readonly large: "xlarge";
+    };
+};
+export {};

package/dist/spark-web-button.cjs.d.ts

@@ -0,0 +1 @@
+export * from "./declarations/src/index";