import { Meta, Canvas, Source } from '@storybook/addon-docs/blocks';
import { Bulb } from '@transferwise/icons';
import ListItem from '../../listItem';
import * as stories from './Button.test.story';

<Meta title="Actions/Button/Accessibility" />

# Accessibility

Given the `Button` is a widely used and highly sensitive component, there are some instances where care is required to ensure inclusive and accessible experience.

<ListItem
  title="Design guidance"
  subtitle="Before you start, familiarise yourself with the dedicated accessibility documentation."
  control={<ListItem.Navigation href="https://wise.design/components/button#accessibility" />}
  media={
    <ListItem.AvatarView>
      <Bulb />
    </ListItem.AvatarView>
  }
/>

<br />
<br />

## Anchors

While it's technically possible to make the `Button` component render as a link by using `as="a"` on its own, and there are use cases for it, this will not result in a semantic HTML anchor. For that to happen, you should set `href` instead – it will automatically render the component as a semantic anchor.

<Source dark code={`
// ⚠️ use with care
<Button v2 as="a">Inaccessible anchor</Button>

// ✅ semantic link

<Button v2 href="https://wise.com">
  Accessible anchor
</Button>
<Button v2 href="https://wise.com" as="a">
  Accessible anchor
</Button>
`}/>

It's also worth noting that HTML links without a valid `href` are not recognised by RTL via `getByRole('link')`.

**Additional resources:**

1. [Deque: Anchors must only be used as links with valid URLs or URL fragments](https://dequeuniversity.com/rules/axe-devtools/4.2/href-no-hash)
2. [whatwg HTML standard: 4.6.2 Links created by a and area elements](https://html.spec.whatwg.org/multipage/links.html#links-created-by-a-and-area-elements)

<br />

## Disabled anchors

Technically, there's no such thing as disabled HTML anchor and the `disabled` attribute is not recognised on the `<a />`. While the code shown below works in all major screen readers, should be overall considered a last resort and design teams should be encouraged to use it sporadically and consider alternative flows instead.

<Source
  dark
  code={`
// ⚠️ use with care
<Button v2 href="https://wise.com" disabled>Emulated disabled anchor</Button>
`}
/>

We're emulating this behaviour by applying a combination of the following:

1. removing `href` attribute to strip out the link's semantics.
2. adding `role="link"` to make it recognisable and discoverable by the assistive tech.
3. setting `aria-disabled="true"` to inform assistive tech of the component state.

**Additional resources:**

1. [Scott O'Hara: Disabling a link](https://www.scottohara.me/blog/2021/05/28/disabled-links.html)
2. [CSS-Tricks: How to Disable Links](https://css-tricks.com/how-to-disable-links/)

<br />

## Loading state

While it might be tempting to use the native, HTML `disabled` attribute for the `loading` state, it would result in a component that is completely invisible to the assistive tech – not focusable and not parsable – entirely inaccessible experience for users relying on such tools.

Instead, we're relying on ARIA attributes and roles to ensure the `Button` is focusable, correctly announced as "busy" and offering visual cue different to the disabled state.

<Source dark code={`
// ❌  do not use
<Button v2 loading disabled>Invisible</Button>

// ✅ semantic loading button

<Button v2 loading>
  Proper loading state
</Button>
`}/>

`Button` instances rendered as HTML anchors, follow the strategy described in the [Disabled anchors](#disabled-anchors) section above.

<br />

## Working with addons (accessories)

One of the core requirements of accessible experience is that all users have equal access to the same content, no matter how they interact with our products.

This becomes troublesome for more complex instances of the `Button` such as those with contentful icons or avatars, e.g. those referring to particular currencies, people or action types.

Exposing separate ARIA labels for such addons would likely become problematic due to syntactic differences between different languages and so instead we recommend using simple `aria-label` attribute to describe given components complete content. Please note, that screen readers will use that text over the visible label

<Canvas of={stories.AccessibilityAddons} />