{% wip %}

# Copy to clipboard

The copy to clipboard component lets users copy content to reuse elsewhere.

## Demo

{% demo 'Copy to clipboard', 'edsCopyToClipboardDemo', demos.edsCopyToClipboardDemo, component.brand %}

## When to use this component

Use the copy to clipboard component at times when it is helpful and safe for users to copy a piece of content they need to paste somewhere else.

For example, to let users copy:
- a discount code
- an article shareable link
- a summary generated by a tool

## When not to use this component

Do not overuse copy to clipboard. This can cause confusion and take the focus away from actions where copying is helpful.

Consider the level of risk of copying sensitive information.

## How it works

### Installation

To install the components, [go to the get started guide for developers](https://github.com/springernature/elements).

To use the Copy to clipboard component, enter the following command in your Terminal:

```bash
npm install @springernature/elements
```

### Styles

Import the styles of the Copy to clipboard component into your `scss` file:

```scss
@import '../path/to/@springernature/elements/components/eds-c-copy-to-clipboard';
```

### Options

| Name                 | Description                                                                                                           | Required |
|----------------------|-----------------------------------------------------------------------------------------------------------------------|:--------:|
| componentUID             | Provides a unique identifier to differentiate between multiple instances of the copy to clipboard component.                                                                      |    ✅     |
| inputField              | Defines the input field of the copy to clipboard component. The `inputField` value is the text content to be copied. If `inputField` is not provided, the text content to be copied can exist outside of the component but some conventions need to be followed (see [Copy from external text source](#copy-from-external-text-source)).                                                                                |         |
| inputField.inputId              | Defines the `id` attribute of the text input field.                                                                                |    ✅     |
| inputField.value                | Defines the text content to be copied to clipboard.                                                                          |    ✅     |
| inputField.label                | Defines the label configuration for the `eds-c-label` component.                                                                    |    ✅     |
| inputField.label.text           | Defines the text content for the label.                                                                                      |    ✅     |
| inputField.label.cssClass       | Provides additional CSS classes for the label.                                                                                |          |
| inputField.maxWidth        | Sets the maximum width of the input field. This should be a valid `flex-basis` CSS property value, for example `25ch`, `200px`, `50%`, `auto`.                                                                            |          |
| button | Defines the button of the copy to clipboard component.                                           |     ✅     |
| button.template       | Defines the button configuration using the `eds-c-button` component schema.                                                       |    ✅     |
| button.ariaLabelledBy | Provides an accessible name for the button using text element(s) on the page (preferred over `button.ariaLabel`) .                                           |          |
| button.ariaLabel      | Provides an accessible label for the button. Prefer `button.ariaLabelledBy` if possible.                                                                          |          |
| feedback             | Defines the feedback configuration of the copy to clipboard component.                                                                 |   ✅        |
| feedback.liveRegionTextOnSuccess | Defines the text announced to assistive technology users when the copy action is successful.                                                         |      ✅   |
| feedback.liveRegionTextOnError | Defines the text announced to assistive technology users when the copy action fails.                                                                  |     ✅     |
| feedback.buttonTextOnSuccess | Defines the text displayed on the button when the copy action is successful. It is required for the [Hidden label with feedback on button](#hidden-label-with-feedback-on-button) variant.                                                                  |          |
| feedback.buttonTextOnError | Defines the text displayed on the button when the copy action fails. It is required for the [Hidden label with feedback on button](#hidden-label-with-feedback-on-button) variant.                                                                        |          |
| feedback.uiFeedbackDuration | Specifies the duration (in milliseconds) for which the feedback text is visible and announced to the user. The default value is 5000ms. After this period, the live region content is cleared. If button text updates are enabled for success or error states, the button text will also revert to its default after this duration. |          |

### Variants

The copy to clipboard variants are:
- Visible label with feedback on label
- Hidden label with feedback on button
- Copy from external text source (paragraph)
- Copy from external text source (text area)

#### Visible label with feedback on label

This is the recommended variant to use when allowing users to copy from a text field (not an external text source).

{% demo 'Copy to clipboard', 'edsCopyToClipboardDemoVisibleLabel', demos.edsCopyToClipboardDemo, component.brand %}

#### Hidden label with feedback on button

{% demo 'Copy to clipboard', 'edsCopyToClipboardDemoHiddenLabel', demos.edsCopyToClipboardDemo, component.brand %}

#### Copy from external text source

If you do not want to use a text input field for the text content to be copied, you can provide an external text source to the copy to clipboard component. 

Create the source element. This needs to be a valid HTML element (for example `<p>`, `<textarea>`) with the data attribute `{% raw %}data-component-copytoclipboard-text-to-copy="{{componentUID}}"{% endraw %}`

Create a text element to be used as the live region. This is needed in order to announce a message to assistive technology users upon success or failure of the copy action. 

The live region element needs to have the following attributes:

```hbs
{% raw %}
<div
	role="status"
	aria-live="polite"
	class="u-visually-hidden"
	data-live-region-text-on-success="{{liveRegionTextOnSuccess}}"
	data-live-region-text-on-error="{{liveRegionTextOnError}}"
	data-component-copytoclipboard-live-region="{{componentUID}}">
</div>
{% endraw %}
```

To better understand these requirements, check:
- [Copy from external text source (paragraph)](#copy-from-external-text-source-paragraph)
- [Copy from external text source (text area)](#copy-from-external-text-source-text-area)

##### Copy from external text source (paragraph)

{% demo 'Copy to clipboard', 'edsCopyToClipboardDemoExternalParagraphSource', demos.edsCopyToClipboardDemo, component.brand %}

##### Copy from external text source (text area)

{% demo 'Copy to clipboard', 'edsCopyToClipboardDemoExternalTextareaSource', demos.edsCopyToClipboardDemo, component.brand %}

### Configuration

To view the configurations for this component, [go to the schema](https://github.com/springernature/elements/blob/main/components/eds-c-copy-to-clipboard/data/eds-c-copy-to-clipboard.schema.json).
