import {
  Meta,
  Story,
  Canvas,
  Primary,
  Controls,
  Unstyled,
  Source,
  Title,
} from '@storybook/addon-docs/blocks';
import { Button } from '../../src/lib/components/buttonv2/Buttonv2.component';

import * as ButtonStories from './button.stories';

<Meta of={ButtonStories} name="Guideline" />

# Button

Buttons trigger an action or state change.

## Hierarchy & grouping

**One primary button per view or modal.** A single `variant="primary"` defines the intended action at any given moment.

- Primary button: far right of the group.
- Dismissive actions (Cancel, Go back): `variant="outline"`, placed on the left.

Align button groups with the container's right side by default; adjust only when visual balance requires it.

### Wizard / multi-step flows

In multi-step flows, group all navigation buttons on the right. "Continue" (or the equivalent forward action) is always `primary`. "Back" sits to its left as `outline`.

Never use "Next". It is not an action verb.

<Canvas layout="fullscreen" of={ButtonStories.SimpleForm} sourceState="none" />

## Usage

Button labels must be short, clear, and describe the action performed.

**✅ Do**
- Use an action verb + noun: "Save", "Create project", "Delete"
- Prefer 1–2 words; 3 words maximum. A single verb ("Save", "Add", "Delete") is acceptable. Pairing it with a resource name ("Save settings", "Add node", "Delete volume") is preferred for clarity.
- Sentence case but capitalize resource names: "Create Folder", "Edit Node"
- Use a `Link` component instead when the action is purely navigational (no mutation, no side effect).

**❌ Don't**
- Use a noun alone: "Confirmation", "Settings"
- Add punctuation or exclamation marks
- Write "Click here" or generic labels like "Yes", "OK"

## Variations

### Variant

Use this table to choose the right variant:

| Situation | Variant |
|---|---|
| Main / intended action on the page or in a modal | `primary` |
| Irreversible or destructive action (delete, reset) | `danger` |
| Action that must be accessible but must not attract attention (dismissal, low-priority utility) | `outline` |
| Secondary action alongside a primary | `secondary` |
| Low-emphasis utility in a constrained space (table, key-value list) | ghost (no variant, icon only) |

<Canvas layout="fullscreen" of={ButtonStories.DefaultButtons} />
<br />

#### Primary

Used for the main action. It must appear only once within a group of buttons or a screen.
For example, "Continue" in a form.

<Canvas of={ButtonStories.Primary} layout="fullscreen" />

#### Secondary

Used when two constructive actions coexist and both advance the flow, but one is more important.

**Example:** "Save draft" (secondary) + "Publish" (primary). Both move the user forward, but publishing is the intended outcome.

<Canvas layout="fullscreen" of={ButtonStories.Secondary} />

#### Outline

Used when an action must be accessible without attracting attention. It signals "available, but not the priority."

Two typical cases:
- **Dismissal / exit:** Cancel, Go back, Close. Any action that steps back from the current flow.
- **Low-priority utility:** Export, Download, Preview, Copy link. Actions that are useful but must not compete visually with the primary action.

Prefer Outline over Secondary when the action doesn't advance the main flow.

<Canvas layout="fullscreen" of={ButtonStories.Outline} />

#### Danger

Used for critical, irreversible actions (typically delete). When the main action is destructive, use `danger` instead of `primary`. Never use them alongside each other. In a destructive confirmation context, `danger` takes the primary position (right side of the group).

Destructive confirmation is always handled through a modal or an explicit checkbox. Never use a double-click pattern on the button itself.

<Canvas layout="fullscreen" of={ButtonStories.Danger} />

### Button vs Link

Use a `Link` component for any navigation, internal or external. `Button` is reserved for actions that trigger a mutation or a state change.

| Use case | Component |
|---|---|
| Navigate to another page or URL | `Link` |
| Open an external site | `Link` with an external indicator |
| Trigger a mutation, form submission, or state change | `Button` |
| Open a modal, panel, or dialog | `Button` |

### Size

Only 2 sizes are available: default and inline.

Inline is used for constrained spaces like tables or key/value sections.
In all other cases, use default.

<Canvas layout="fullscreen" of={ButtonStories.ButtonSizes} />

### States

#### Disabled state

The button triggers no action and shows a not-allowed cursor.
A tooltip **must** appear on hover explaining why the button is disabled. Exception: when the reason is self-evident, such as a form with required fields not yet filled.

<Canvas layout="fullscreen" of={ButtonStories.ButtonDisabled} />

#### Loading state

Displays a spinner within the button and disables all interactions.
Use for async operations (API calls, form submissions) where the result is not immediate.
The button label changes to the gerund form with ellipsis: "Save" becomes "Saving…", "Delete" becomes "Deleting…".

<Canvas
  layout="fullscreen"
  of={ButtonStories.ButtonLoading}
/>

## Icon on buttons

### Usage

- Icons are optional. Use them to aid recognition and differentiation between actions.
- An icon-only button (no label) is acceptable for universally understood actions such as edit, copy, delete, or refresh. For less obvious actions, prefer pairing the icon with a label.
- Prefer universally understood icons (print, close, play/pause, save).
- Use standard icons only when their meaning matches the action.
- Avoid creating new icons for infrequently used actions.
- If no label is provided, a tooltip is required.

### Placement

Seeing the icon first helps users scan the page more easily, except for a few cases such as navigation (right arrow).

<Canvas
  layout="fullscreen"
  of={ButtonStories.ButtonsWithIcon}
  sourceState="none"
/>

### Ghost buttons (icon-only)

Ghost buttons are low-emphasis, icon-only buttons without a `variant`. They are effective in space-limited areas like tables or key-value lists.

**✅ Do**
- Always include a tooltip with a verb phrase: "Refresh metrics", "Export data"
- Limit ghost buttons to common, universally understood actions

**❌ Don't**
- Use a standalone noun as tooltip text ("Refresh", "Export"). It must describe the action.
- Use them instead of Outline buttons when the action needs to be clearly recognized as a button
- Create too many different ghost button instances in the same context

<Canvas
  layout="fullscreen"
  of={ButtonStories.GhostButtons}
  sourceState="none"
/>

### Accessibility

- Use icons that are easily recognizable. If the icon is ambiguous, omit it. An unclear icon is worse than no icon.
- For icon-only buttons, the `tooltip.overlay` text is automatically used as `aria-label`. It must describe the action with a verb.

<Canvas
  layout="fullscreen"
  of={ButtonStories.IconButtonWithTooltip}
  sourceState="none"
/>

## Empty states

When a view has no content yet, use a single `primary` button as the main call to action. It should be centered, standalone, and paired with an `Icon` component to reinforce the action.

Do not place secondary or outline buttons in empty states. The goal is a single, clear entry point.

## Playground

<Canvas of={ButtonStories.Playground} layout="fullscreen" />

<Controls of={ButtonStories.Playground} />