import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import {
  Button,
  Card,
  CardSection,
  NextButton,
  Text,
  Link,
  Box,
  UnstyledButton,
  TertiaryButton,
} from '../../index';

<Meta title="Components/Actions/Accessibility Tips" />

# Accessible Calls to Action

Most designs contain "calls to action" (CTAs). These take the form of links, buttons, and other clickable elements. Here are a few things to keep in mind.

## 1) Never put an `onClick` on Arbitrary DOM Elements

### Problem

As soon as you give something an `onClick` callback, it becomes an "interactive component". There is a whole bunch of things that interactive components need to do right in order to be considered accessible:

- a screen reader has to be able to find some meaningful text to read out for the component
- the component has to be accessible via the keyboard, and render a UI cue when it has the keyboard focus
- it has to have a focus state, respond to `onFocus` and `onBlur` events,
- etc.

**Bad:** not accessible: the clickable icon below can't be accessed via the keyboard. It also doesn't have any text the screen reader can read.

<Canvas>
  <Box onClick={() => alert("You can't activate me with the keyboard")}>
    Click Me!
  </Box>
</Canvas>

### Solutions

### Use one of Patchwork's `Action` components

There should rarely be a need to roll your own custom links or buttons. One of the components in the `Actions` section of this storybook should fit your needs.

<Canvas>
  <Button
    size="sm"
    onClick={() => alert('You *can* activate me with the keyboard!')}
  >
    Click Me!
  </Button>
</Canvas>

### Check that the Component doesn't already have an onClick or href property

Failing that, there are other components that accept optional `onClick` or `href` properties, like `Card`, `CardSection`. If patchwork exposes an `onClick` on one of its components, we make sure it's done accessibly.

<Canvas>
  <Card
    spacing="p2"
    onClick={() => alert('You *can* activate me with the keyboard!')}
  >
    Click Me!
  </Card>
</Canvas>

<Canvas>
  <Card>
    <CardSection
      spacing="p2"
      onClick={() => alert('You *can* activate me with the keyboard!')}
    >
      Click Me 1!
    </CardSection>
    <CardSection
      spacing="p2"
      onClick={() => alert('You *can* activate me with the keyboard!')}
    >
      Click Me 2!
    </CardSection>
  </Card>
</Canvas>

### Wrap your component in an UnstyledButton

If all else fails and you need to add interactivity to a custom piece of UI, wrap the thing you want to make clickable in an `UnstyledButton`. `UnstyledButton` takes care of the stuff mentioned above for you.

<Canvas>
  <UnstyledButton
    spacing="p1"
    onClick={() => alert('You *can* activate me with the keyboard')}
  >
    Click Me!
  </UnstyledButton>
</Canvas>

## 2) Make Sure All CTAs Have Readable Text

### Problem

Screen readers need to be able to name the button something sensible. Normally if you use a `Link`, `Button`, `SecondaryButton`, or `TertiaryButton`, it will have child text that serves this purpose. For example, VoiceOver will read the following as "button: save".

<Canvas>
  <TertiaryButton>Save</TertiaryButton>
</Canvas>

However we're often tempted to make buttons that rely only on iconography to present meaning. This doesn't work for non-sighted users.

For example:

**Bad** Not accessible: no descriptive text.

<Canvas>
  <NextButton onClick={() => alert('Mystery button')} />
</Canvas>

### Solutions

**Good:** Assigning an `aria-label` tells the screen reader what to read.

<Canvas>
  <NextButton onClick={() => alert('Next')} aria-label="Go to the next step" />
</Canvas>

**Best:** Having visible button text is better for sighted users as well.

<Canvas>
  <NextButton onClick={() => alert('Next')} stacked="row" align="center">
    Next step
  </NextButton>
</Canvas>

## 3) The Button/Link Duality

We often use buttons and links interchangeably from a design perspective. However from a screen reader point of view they behave differently and have different implications for navigating around the document.

The rule of thumb is that if it uses an `href` prop, it should render an `<a>` tag. If it uses an `onClick` prop, it should render a `<button>` tag.

The good news is patchwork's `Link`, `Button`, `SecondaryButton`, `TertiaryButton`, and `TextButtonWithIcon` components handle this under the hood for you. Specify an `href`, and you get an `<a>` under the hood. Specify an `onClick` and you get a `<button>` under the hood. Specify both, and the `href` takes precedence. This is useful for cases where you want to record an analytics hit before following a link.