import {
  ExampleCodeBlock,
  Specifications,
  SymbolDoc,
  SymbolDescription,
} from '@workday/canvas-kit-docs';

import Primary from './examples/Primary';
import PrimaryInverse from './examples/PrimaryInverse';
import Secondary from './examples/Secondary';
import SecondaryInverse from './examples/SecondaryInverse';
import Tertiary from './examples/Tertiary';
import TertiaryInverse from './examples/TertiaryInverse';
import Delete from './examples/Delete';
import Grow from './examples/Grow';
import CustomStyles from './examples/CustomStyles';
import ThemeOverrides from './examples/ThemeOverrides';


# Canvas Kit Button

Clickable button elements that extend the native `<button>` element with Canvas styling.

[> Workday Design Reference](https://design.workday.com/components/buttons/buttons)

## Installation

```sh
yarn add @workday/canvas-kit-react
```

## Usage

### PrimaryButton

<SymbolDescription name="PrimaryButton" fileName="/react/" />

The example below shows multiple instances of a `PrimaryButton` with various icon configurations.

<ExampleCodeBlock code={Primary} />

Primary Buttons also have an `inverse` variant. While it looks similar to the default Secondary
Button, the default outline as well as the hover and focus states are different. Use this variant
when you need to place a Primary Button on a dark or colorful background such as `blueberry400`.

<ExampleCodeBlock code={PrimaryInverse} />

### SecondaryButton

<SymbolDescription name="SecondaryButton" fileName="/react/" />

The example below shows multiple instances of a `SecondaryButton` with various icon configurations.

<ExampleCodeBlock code={Secondary} />

Secondary Buttons also have an `inverse` variant. Use this when you need to place a Secondary Button
on a dark or colorful background such as `blueberry400`.

<ExampleCodeBlock code={SecondaryInverse} />

### TertiaryButton

<SymbolDescription name="TertiaryButton" fileName="/react/" />

The example below shows multiple instances of a `TertiaryButton` with various icon configurations.

<ExampleCodeBlock code={Tertiary} />

Tertiary Buttons also have an `inverse` variant. Use this when you need to place a Tertiary Button
on a dark or colorful background such as `blueberry400`.

<ExampleCodeBlock code={TertiaryInverse} />

### DeleteButton

<SymbolDescription name="DeleteButton" fileName="/react/" />

<ExampleCodeBlock code={Delete} />

### Grow Prop

The example below shows the use of the `grow` prop on different variants of buttons. This will set
the width of the button to the width of its container.

<ExampleCodeBlock code={Grow} />

### Custom Styles

All of our buttons support custom styling via the `cs` prop. For more information, check our
["How To Customize Styles"](https://workday.github.io/canvas-kit/?path=/docs/styling-guides-customizing-styles--docs)
or view the example below.

<ExampleCodeBlock code={CustomStyles} />

### Theme Overrides

The most common way to theme our buttons is to pass a `theme` object at the root level of the
application via the `CanvasProvider`. In the example below, our buttons use our `brand.action.**`
tokens with the fallback being `brand.primary.**`.

> **Caution:** Setting `--cnvs-brand-action**` tokens at the `:root` CSS will override all
> `PrimaryButton` theme colors set at the `CanvasProvider` level.

> **Note:** You should **not** individually theme components wrapping them with the
> `CanvasProvider`, but rather theme at the root level of the application.

<ExampleCodeBlock code={ThemeOverrides} />

## Accessibility

Our button components render semantic HTML `<button>` elements to the browser DOM. This means that
ARIA roles won't be necessary in most cases, and `onClick` listeners will automatically support the
Enter and Space keys for keyboard interactions.

[Button Pattern | APG | WAI | W3C](https://www.w3.org/WAI/ARIA/apg/patterns/button/)

- An `aria-label` is only necessary for icon-only buttons in most cases. Using
  [Canvas Kit's tooltip component](/components/popups/tooltip/) will handle this for you, and all
  users will be able to see the label for the button.
- When button designs have 2 toggle states, an `aria-pressed={true | false}` property is required
  for screen reader support. For example, see Canvas Kit's
  [Segmented Control component](/components/buttons/segmented-control/).
- When buttons have an attached menu, an `aria-haspopup="true"` property is required. Using
  [Canvas Kit's Menu component](/components/popups/menu/) will handle this for you.
- The icons used in text buttons are decorative in most cases and include ARIA `role="presentation"`
  and `focusable="false"`. In some special cases where an icon does add meaning, you may be required
  to change the `role` and add an `aria-label` to the icon for equivalent screen reader support.

### Disabled Buttons

- Disabled buttons use the `disabled` attribute, removing them from the tab order.
- Disabled styling is exempt from WCAG contrast requirements.

### Screen Reader Experience

- Button text content is announced along with the button role (e.g., "Primary, button").
- Icon-only buttons announce the `aria-label` value along with the button role.
- Toggle buttons announce their pressed/unpressed state (e.g., "Activity Stream, toggle button,
  pressed" and check out the [Segmented Control component](/components/buttons/segmented-control/)).

### Touch Target Size

- All buttons meet the minimum 24px by 24px touch target size requirement for mobile accessibility.
- Button padding ensures adequate spacing between interactive elements to prevent accidental
  activation.

### Button Groups

- Related buttons can be grouped together with HTML unordered list elements or with `<fieldset>` and
  `<legend>` elements. This can help give additional context to screen readers about the purpose of
  the group.

## Component API

<SymbolDoc name="PrimaryButton" fileName="/react/" />
<SymbolDoc name="SecondaryButton" fileName="/react/" />
<SymbolDoc name="TertiaryButton" fileName="/react/" />
<SymbolDoc name="DeleteButton" fileName="/react/" />

## Specifications

<Specifications file="Button.spec.tsx" name="Button" />