import { Canvas, Meta, Controls } from "@storybook/addon-docs/blocks";

import * as ButtonStories from "./Button.stories";

<Meta of={ButtonStories} />

# Button

The Button component is a key UI element that enables users to trigger actions or events, such as submitting forms, navigating pages, or interacting with system functionality. Its purpose is to provide a clear, intuitive way for users to interact with a system. Buttons are relevant in virtually all interfaces, ensuring user engagement by offering a simple, recognizable mechanism for executing commands. They are essential for usability, guiding user behavior and driving application workflows.

## Usage

<Canvas of={ButtonStories.Documentation}
        source={ { code:
                ` // Code for a Primary button
        \n import { Button } from '@webiny/admin-ui';
        \n <Button variant="primary" text={"Button"}></Button>

` } }
additionalActions={[
{
title: 'Open in GitHub',
onClick: () => {
window.open(
'https://github.com/webiny/webiny-js/blob/feat/new-admin-ui/packages/admin-ui/src/Button/Button.tsx',
'_blank'
);
},
}
]}
/>

<Controls of={ButtonStories.Documentation} exclude={"onClick"} />

```jsx
import { Button } from "@webiny/admin-ui";

<Button variant="primary" text={"Button"}></Button>;
```

## Examples

### Primary

<Canvas of={ButtonStories.Primary}
        source={ { code:
                `// Code for a Primary button
        \n import { Button } from '@webiny/admin-ui';
        \n <Button variant="primary" text={"Button"}></Button>

` } }
/>

### Secondary

<Canvas of={ButtonStories.Secondary}
        source={ { code:
                `// Code for a Secondary button
        \n import { Button } from '@webiny/admin-ui';
        \n <Button variant="secondary" text={"Button"}></Button>

` } }
/>

### Tertiary

<Canvas of={ButtonStories.Tertiary}
        source={ { code:
                `// Code for a Tertiary button
        \n import { Button } from '@webiny/admin-ui';
        \n <Button variant="tertiary" text={"Button"}></Button>

` } }
/>

### Ghost

<Canvas of={ButtonStories.Ghost}
        source={ { code:
                `// Code for a Ghost button
        \n import { Button } from '@webiny/admin-ui';
        \n <Button variant="ghost" text={"Button"}></Button>

` } }
/>

### Ghost Negative

<Canvas of={ButtonStories.GhostNegative}
        source={ { code:
                `// Code for a Ghost Negative button
        \n import { Button } from '@webiny/admin-ui';
        \n <Button variant="ghost-negative" text={"Button"}></Button>

` } }
/>

### With Icon

<Canvas of={ButtonStories.WithIcon} story={ {inline: false}}
        source={ { code:
                `// Code for a With Icon button

                import { Button } from '@webiny/admin-ui';
                import { ReactComponent as PencilIcon } from "@webiny/icons/edit.svg";
                \n<Button variant="primary"  text={"Button"} size="md" icon={<PencilIcon />} iconPosition="start"></Button>

` } }
/>

### As Child

The Button component can be used as a wrapper for other elements, allowing flexible composition. This is particularly useful when integrating custom text elements, or any other components inside a button.

<Canvas of={ButtonStories.WithAsChild} story={ {inline: false}}
        source={ { code:
                `// Code for a As Child button
\n import { Button } from '@webiny/admin-ui';

                <Button variant="primary" asChild={true}>
                    <span>Button</span>
                </Button>

` } }
/>

### Icon Only Button

import * as IconButtonStories from "./IconButton.stories";

**We have a dedicated `IconButton` component for the Icon-only button. Please check the code below for more details.**

#### Usage

```jsx
import { IconButton } from "@webiny/admin-ui";
```

```jsx
import { ReactComponent as AddIcon } from "@webiny/icons/add.svg";
<IconButton icon={<AddIcon />} size={"md"} />;
```

<Canvas of={IconButtonStories.Documentation}
        source={ { code:
                ` // Code for a Icon Only Primary button
        \n import { IconButton } from '@webiny/admin-ui';
        \n import { ReactComponent as AddIcon } from "@webiny/icons/add.svg"
        \n <IconButton icon={<AddIcon />} size={"md"}/>

` } }
additionalActions={[
{
title: 'Open in GitHub',
onClick: () => {
window.open(
'https://github.com/webiny/webiny-js/blob/feat/new-admin-ui/packages/admin-ui/src/Button/Button.tsx',
'_blank'
);
},
}
]}
/>

#### Props

<Controls of={IconButtonStories.Documentation} exclude={"onClick"} />

## Anatomy

### Construction

<img src="/images/storybook/button/contruction.png" alt="Construction" />

### Options

<img src="/images/storybook/button/options.png" alt="Options" />

### Variants

<img src="/images/storybook/button/type.png" alt="Variants" />

### Size

Regular buttons come in four different sizes: small, medium, large, and xl. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.

<img src="/images/storybook/button/size.png" alt="Size" />

**Icon-only button** come in six different sizes to accommodate for various component needs.

<img src="/images/storybook/button/size-icon-only.png" alt="Size - Icon Only" />

### States

<img src="/images/storybook/button/states.png" alt="States" />

## Usage

### Icon Usage

An icon should only be used in a button when it's benefitial and when it has a meaningful association with the label.

<img src="/images/storybook/button/icon-usage.png" alt="Icon Usage" />

### Use primary buttons sparingly

Use primary buttons as the desired action for users. Competing primary buttons may leave the user unsure of next steps in their user journey. As a rule of thumb limit primary buttons to 1 in contained UIs and 3 in full page UIs.

<img src="/images/storybook/button/primary-button-usage.png" alt="Primary Button Usage" />

### Button Group

When used in groups, buttons should support only maximum of two type variants, with an exception of third variant being ghost extension button (eg. ellipsis). Avoid using random type and icon options within the button groups. Avoid using different sizes within the same group.

<img src="/images/storybook/button/button-group.png" alt="Button Group" />