@spark-web/button 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @spark-web/button
+
+## 1.0.0
+
+### Major Changes
+
+- [#27](https://github.com/brighte-labs/spark-web/pull/27)
+  [`4c8e398`](https://github.com/brighte-labs/spark-web/commit/4c8e3988f8a59d3dab60a6b67b1128b6ff2a5f2c)
+  Thanks [@JedWatson](https://github.com/JedWatson)! - Initial Version
+
+### Patch Changes
+
+- Updated dependencies
+  [[`4c8e398`](https://github.com/brighte-labs/spark-web/commit/4c8e3988f8a59d3dab60a6b67b1128b6ff2a5f2c)]:
+  - @spark-web/a11y@1.0.0
+  - @spark-web/box@1.0.0
+  - @spark-web/icon@1.0.0
+  - @spark-web/link@1.0.0
+  - @spark-web/text@1.0.0
+  - @spark-web/theme@1.0.0
+  - @spark-web/utils@1.0.0

package/README.md

@@ -0,0 +1,217 @@
+---
+title: Button
+storybookPath: forms-buttons-button--default
+---
+
+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
+<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>
+```
+
+## 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>
+```
+
+## 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>
+```
+
+## Props
+
+| Prop              | Type                                                                                     | Default   | Description                                                                                                                               |
+| ----------------- | ---------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| aria-controls?    | string                                                                                   |           | Identifies the element (or elements) whose contents or presence are controlled by the current element. Only applicable for `Button`.      |
+| 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.                                                                                          |
+| 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.                                                 |
+| 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`.                                                                                       |

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

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import type { CommonButtonProps, NativeButtonProps } from './types';
+export declare type ButtonProps = CommonButtonProps & {
+    'aria-controls'?: NativeButtonProps['aria-controls'];
+    'aria-describedby'?: NativeButtonProps['aria-describedby'];
+    'aria-expanded'?: NativeButtonProps['aria-expanded'];
+    onClick?: NativeButtonProps['onClick'];
+    size?: CommonButtonProps['size'];
+    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>>;
+/**
+ * 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;

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" | "clipPath" | "filter" | "mask" | "marker" | "text" | "circle" | "svg" | "animate" | "animateMotion" | "animateTransform" | "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" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "stop" | "switch" | "textPath" | "tspan" | "use" | "view" | keyof HTMLElementTagNameMap | "set" ? (HTMLElementTagNameMap & Pick<SVGElementTagNameMap, "symbol" | "clipPath" | "filter" | "mask" | "marker" | "text" | "circle" | "svg" | "animate" | "animateMotion" | "animateTransform" | "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" | "foreignObject" | "g" | "image" | "line" | "linearGradient" | "metadata" | "mpath" | "path" | "pattern" | "polygon" | "polyline" | "radialGradient" | "rect" | "stop" | "switch" | "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,4 @@
+export { Button } from './Button';
+export { ButtonLink } from './ButtonLink';
+export type { ButtonProps } from './Button';
+export type { ButtonLinkProps } from './ButtonLink';

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

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

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

@@ -0,0 +1,31 @@
+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 = BackgroundTone;
+declare type ChildrenWithText = {
+    label?: never;
+    children: string | [ReactElement<IconProps>, string] | [string, ReactElement<IconProps>];
+};
+declare type IconOnly = {
+    label: string;
+    children: ReactElement<IconProps>;
+};
+export declare type ButtonChildrenProps = ChildrenWithText | IconOnly;
+export declare type NativeButtonProps = ButtonHTMLAttributes<HTMLButtonElement>;
+export declare type CommonButtonProps = {
+    data?: DataAttributeMap;
+    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,10 @@
+import type { BoxProps } from '@spark-web/box';
+import type { ButtonProminence, ButtonSize, ButtonTone } from './types';
+declare type UseButtonStylesProps = {
+    iconOnly: boolean;
+    prominence: ButtonProminence;
+    size: ButtonSize;
+    tone: ButtonTone;
+};
+export declare function useButtonStyles({ iconOnly, prominence, size, tone, }: UseButtonStylesProps): Partial<BoxProps>;
+export {};

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

@@ -0,0 +1,32 @@
+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 ButtonStyles = {
+    background: BoxProps['background'];
+    border?: BoxProps['border'];
+    borderWidth?: BoxProps['borderWidth'];
+    textTone?: ForegroundTone;
+    backgroundHover: keyof BrighteTheme['backgroundInteractions'];
+    borderHover?: keyof BrighteTheme['border']['color'];
+    textToneHover?: keyof BrighteTheme['color']['foreground'];
+    backgroundActive: keyof BrighteTheme['backgroundInteractions'];
+    borderActive?: keyof BrighteTheme['border']['color'];
+    textToneActive?: keyof BrighteTheme['color']['foreground'];
+};
+export declare const variants: Record<ButtonProminence, Record<ButtonTone, ButtonStyles | undefined>>;
+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";