# XWUIButton

Buttons trigger actions. Use them for form submissions, navigation, confirmations, and interactive controls. XWUIButton wraps XWUIItem internally, giving it full icon support, loading states, and flexible sizing.

## Basic Usage

One line of TypeScript creates a fully styled, accessible button.

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: A primary button with a click handler.
```

## Variants

Eight visual variants cover every context - from primary calls to action to destructive confirmations.

```example
file: examples/Variants.ts
html: examples/Variants.html
title: Variants
description: primary, secondary, success, danger, warning, info, outline, ghost
```

## Sizes

Three size presets adapt padding, font-size, and min-height together.

```example
file: examples/Sizes.ts
html: examples/Sizes.html
title: Sizes
description: sm, md (default), lg
```

## States

`disabled` prevents interaction. `loading` shows a spinner and disables the button while an async operation runs.

```example
file: examples/States.ts
html: examples/States.html
title: Disabled & Loading
description: Non-interactive states for async and restricted scenarios.
```

## With Icons

Pass any icon name from the XWUI icon set. Icons can appear on the left, right, or replace the label entirely for compact icon-only buttons.

```example
file: examples/WithIcons.ts
html: examples/WithIcons.html
title: With Icons
description: Left icon, right icon, and icon-only buttons.
```

## Tonal, Shapes & Effects

Beyond the solid variants, three composable modifiers cover modern button styling:

- `tonal: true` - soft/tonal rendering of any semantic variant (tinted fill + coloured ink), the low-contrast alternative for secondary actions.
- `shape: 'sharp' | 'rounded' | 'pill'` - per-button corner radius, overriding the theme default.
- `effect: 'gradient' | 'raised' | 'glow'` - decorative treatments for marketing / premium CTAs.
- `variant: 'link'` - renders as inline text that underlines on hover (no fill or border).

### Physical press

Every button physically depresses (shrinks slightly) while held down - a tactile "pushed in" feel - **on by default**. The depth is a style-level setting, the `--button-press-scale` token defined per style in `styles/style/*/spacing.css` (e.g. `0.95`); set it to `1` to disable the press globally for a style or app. To opt a single button out, pass `press: false`.

## Button Gallery

A full catalogue exercising every variant, semantic colour, tonal fill, size, icon arrangement, state, shape, and effect in a single page - the xwui equivalent of a Tailwind button-library reference, built from config alone.

```example
file: examples/ButtonGallery.ts
html: examples/ButtonGallery.html
title: Button Gallery
description: The complete button spectrum - variants, tonal, sizes, icons, states, shapes, gradient/3D/glow, and a split button.
```

## Full Width

`fullWidth: true` stretches the button to fill its container - useful in forms, drawers, and mobile layouts.

```example
file: examples/FullWidth.ts
html: examples/FullWidth.html
title: Full Width
description: Button that stretches to its container.
```

## Real-World

A sign-in button as used in a login form - large, full-width, primary variant.

```example
file: examples/RealWorld.ts
html: examples/RealWorld.html
title: Sign-in Form Button
description: Realistic usage inside a login form.
```

## Async Submit

A submit button that shows a spinner while an async save runs. Call `setLoading(true)` to disable the button and show the ⟳ indicator, then switch to a success variant when the request resolves.

```example
file: examples/AsyncSubmit.ts
html: examples/AsyncSubmit.html
title: Async Submit
description: Loading spinner during an async save, then a success state.
```

## Button Group

Group related actions into a toolbar, or build a segmented single-select control from `toggleable` buttons that clear one another with `setPressed`.

```example
file: examples/ButtonGroup.ts
html: examples/ButtonGroup.html
title: Button Group
description: An action toolbar and a segmented single-select set.
```

## Icon-Only Buttons

Pass an empty label and an `icon` to render a compact icon-only button. The `title` becomes both the `aria-label` and a hover tooltip, so the action stays accessible without visible text.

```example
file: examples/IconOnly.ts
html: examples/IconOnly.html
title: Icon-Only Buttons
description: Compact icon buttons with aria-labels and tooltips.
```

## Confirm Delete

A destructive action guarded by a two-step confirm. The first click arms the button (warning variant); the second click commits the delete, with a timer that cancels the armed state if the user hesitates.

```example
file: examples/ConfirmDelete.ts
html: examples/ConfirmDelete.html
title: Confirm Delete
description: A destructive action with an inline confirm step.
```

```api
```