import { Canvas, Meta } from "@storybook/blocks";
import * as SwatchStories from "./swatch.stories";

<Meta title="Foundations/Utilities/Swatch/Docs" />

# Swatch

Swatches are elements that display a color, gradient or image. They can sometimes trigger an action.

## Background Property

A swatch component can receive several props. The `background` prop is the most important and must be an object. Depending on the value of the background property we will get different variants of the component.

## Variants

If the background prop has a property `value` with an hex color value it will display a full swatch with a solid color

<Canvas of={SwatchStories.Default} />

If the background prop has a property `value` with an hex color value and a a property `opacity` it will display a full swatch with a solid color on one side and the same color with the opacity applied on the other side. (default opacity: 1)

<Canvas of={SwatchStories.WithOpacity} />

If the background prop has a gradient property it will display a full swatch with the gradient (linear or radial)

<Canvas of={SwatchStories.LinearGradient} />
<Canvas of={SwatchStories.RadialGradient} />

The element can also be interactive, and execute an external function. Typically, it launches the color picker. To make it an interactive button, it accepts an onClick function.

<Canvas of={SwatchStories.Clickable} />

> Due to technical issues regarding how we display internal images in Penpot we cannot preview:

    - Swatches with images

## Technical Notes

### onClick

> Note: If the swatch is interactive, an `aria-label` is required. See the `Accessibility` section for more information.

The swatch button accepts an onClick prop that expects a function on the parent context.
It should be useful for launching other tools as a color picker.
It is executed when the user clicks on the swatch, or presses Enter or Spacebar while focused.

### Accessibility

If the swatch is interactive, an `aria-label` is required.

```clj
[:> swatch* {:on-click launch-colorpicker :aria-label "Lorem ipsum"}]
```