{ /* This Source Code Form is subject to the terms of the Mozilla Public
  License, v. 2.0. If a copy of the MPL was not distributed with this
  file, You can obtain one at http://mozilla.org/MPL/2.0/.

  Copyright (c) KALEIDOS INC Sucursal en España SL */ }

import { Canvas, Meta } from '@storybook/addon-docs/blocks';
import * as ButtonStories from "./button.stories";
import * as IconButtonStories from "./icon_button.stories";

<Meta title="Buttons/Docs" />

# Buttons

Buttons trigger an action such as submitting a form or showing/hiding an interface component.

## Variants

**Primary** (`"primary"`), used to initiate the main / primary action of a view or flow. Avoid to have more than one primary buttons in the same view or flow.

<Canvas of={ButtonStories.Primary} />

**Secondary** (`"secondary"`), the default and most common buttons in the interface. Use them for non primary actions.

<Canvas of={ButtonStories.Secondary} />

**Ghosts** (`"ghost"`), used for less prominent, and sometimes independent, actions (examples: add pages, add properties, etc.)

<Canvas of={ButtonStories.Ghost} />

**Destructive** (`"destructive"`), used for any action that destroys any object or data. Don't use them for actions like dettach, unlink, etc.

<Canvas of={ButtonStories.Destructive} />

## Technical notes

### Icons

Both `button*` and `icon-button*` accept an `icon` prop, which must contain an [icon ID](../foundations/assets/icon.mdx).
These are available in the `app.main.ds.foundations.assets.icon` namespace.

```clj
(ns app.main.ui.foo
  (:require
   [app.main.ui.ds.foundations.assets.icon :as i]))
```

```clj
[:> button* {:icon i/effects} "Lorem ipsum"]
```

<Canvas of={ButtonStories.WithIcon} />

```clj
[:> icon-button* {:variant "primary"
                  :icon i/effects}]
```

<Canvas of={IconButtonStories.Primary} />

### Action Buttons

Action buttons are a variant of `icon-button*` (`"action"`) but smaller.

```clj
[:> icon-button* {:variant "action"
                  :icon i/effects}]
```

<Canvas of={IconButtonStories.Action} />

### Semantics

In some cases, a button needs to be semantically an 'a' tag, but visually maintain the button style.
In that case, the button accepts a 'to' property with the expected 'href'. It will then be rendered as an anchor element.

### Accessibility

Icon buttons require an `aria-label`. This is also shown in a tooltip on hovering the button.

```clj
[:> icon-button* {:icon i/effects :aria-label "Lorem ipsum"}]
```

<Canvas of={IconButtonStories.Default} />

## Usage guidelines (design)

### Where to use

Penpot app has a high-density interface, so use buttons thoughtfully to establish
a clear and logical visual hierarchy, and avoid overwhelming the user.

### When to use

Buttons can be used in forms, navigation links or anywhere that needs simple,
standard button functionality. Used also to grab users' attention (i.e. navigate
to main user flows like register, etc.)