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

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

# Using Inputs Accessibly

Inputs are a common source of accessibility problems if not done correctly. Here are some tips to avoid creating issues.

## Avoid Making Your Own Inputs

A lot of thought and testing has gone into making sure Patchwork's inputs are accessible, and we're constantly improving them over time.

Considerations that have gone into the input designs include things like:

- do they work with assistive technology like screen readers, or non-mouse input devices?
- is meaning conveyed in ways that are perceptible to users with different levels of colour vision?
- are things labelled in ways that make life easier for users with cognitive or other impairments?

We are at a point where most form controls have a corresponding patchwork implementation; please use them.

**In general, branding is _not_ a good enough justification to reinvent the wheel on the considerations above**.

If you get a design that calls for a new take on a `TextBox` for example, reach out to the design team and the #front-end-platform team in Slack to make sure it's

- not a mistake,
- absolutely necessary,
- gets implemented correctly.

## Prefer UX Flows Composed from Basic, Familiar Input Types

If you get a design with some wildly novel input control, you will need to research and implement the correct [ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.1/) for the UX interaction it's trying to emulate. This can be tricky to get right and is likely not worth the effort in many cases. Ask the designer if the same functionality can be achieved with standard controls instead. Remember that accessibility is UX too, and that optimizing UX for some users often makes things worse for others.

Basic form control paradigms are battle-tested and familiar, and in many cases have undergone decades of use and tweaking. They should be preferred in designs.

## Always Supply a Descriptive Label

Screen readers need a descriptive label so that their users can understand what information any input is looking for. Most patchwork inputs expose a required `label` property for this purpose.

**Tips:**

> Never omit or specify an empty string for a required `label` property. Doing so creates an accessibility bug.

> If your project supports i18n, use translated strings for the label. Most label props have the `TranslatedContent` type, which can accept either `String`, or `FormattedMessage` instances.

### Label Render Modes

The "inline" inputs (e.g. `TextInput`, `SearchInput`, etc) support different label render modes thought the `labelStyle` prop.

#### Floating

By default, labels are either rendered above the input or as an inline floating label. This is the preferred approach going forward.

<Canvas>
  <TextInput label="Label" placeholder="Placeholder" />
</Canvas>

<Canvas>
  <TextArea label="Label" placeholder="Placeholder" />
</Canvas>

In both of these cases, the label is visible in all control states, which is important for users with cognitive impairments and a WCAG requirement.

#### External

Certain older designs look funny with the floating label. In these cases, `labelStyle="external"` may be used. This renders a label just above the control.

#### Hidden

There may be cases where the design calls for an input but does not have a visible text label present.

In this case, you must still specify the label property as above, but with the `labelStyle="hidden"` prop which makes the text available to screen readers even though it is not shown visually.

In this case you will most likely want to specify a `placeholder` for sighted users.

**Be aware that the hidden label pattern is a WCAG violation and should be considered a bug in the design.**

As such, the `hidden` label style is deprecated and will be removed from patchwork once we sort out the legacy designs that require it.

<Canvas>
  <TextInput label="Label" hideLabel placeholder="Placeholder" />
</Canvas>

## Use Placeholders Judiciously

Placeholders are a source of controversy in accessibility circles.

**Placeholders are ignored by most screen readers**. Inputs that use placeholders as their only descriptive text (i.e. no label) provide visually impaired users with no information as to what the input is asking for.

**Placeholders that provide an example value are confusing to some users**. Users are often confused with labels that look like correct values and think the input is filled in when it's not.

<Canvas>
  <TextInput
    error="Bad: this placeholder looks like a real value, which is confusing."
    label="Phone number"
    placeholder="555 555 5555"
  />
</Canvas>

The main use case for a placeholder is to provide instructions to **sighted** users for format-masked inputs like `Datepicker` where the placeholder describes the requirements of the data (e.. `YYYY-MM-DD`).