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

<Meta title="FP.REACT Components/Buttons/Readme" />

# Button

## Summary

The `Button` component is a versatile and customizable button element that
supports various types and styles. It is designed to be reusable and accessible.

## Features

- Supports `button`, `submit`, and `reset` types
- Customizable styles and classes
- Handles various pointer events
- Accessible with `aria-disabled` attribute

## Props

| Name             | Type                                                              | Default    | Description                                                                        |
| ---------------- | ----------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| `type`           | `'button' \| 'submit' \| 'reset'`                                 | `'button'` | The button type                                                                    |
| `size`           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                  | -          | Size variant — merged into `data-btn`                                              |
| `variant`        | `'text' \| 'pill' \| 'icon' \| 'outline'`                         | -          | Style variant — maps to `data-style`                                               |
| `color`          | `'primary' \| 'secondary' \| 'danger' \| 'success' \| 'warning'`  | -          | Color variant using semantic tokens — maps to `data-color`                         |
| `block`          | `boolean`                                                         | -          | Stretches button to 100% container width — merged into `data-btn` as `"block"`     |
| `"data-btn"`     | `string`                                                          | -          | Raw `data-btn` tokens. Merged with `size` and `block` into the final attribute. `data-btn` tokens take precedence over `size` tokens — if both conflict, `data-btn` wins. |
| `styles`         | `React.CSSProperties`                                             | -          | Inline styles — use to override CSS custom properties e.g. `--btn-bg`             |
| `disabled`       | `boolean`                                                         | `false`    | Disables the button using the `aria-disabled` pattern (stays keyboard-focusable)   |
| `classes`        | `string`                                                          | -          | Additional CSS classes (merged automatically with `.is-disabled` when disabled)    |
| `onPointerDown`  | `(e: React.PointerEvent<HTMLButtonElement>) => void`              | -          | Callback for pointer down event                                                    |
| `onPointerOver`  | `(e: React.PointerEvent<HTMLButtonElement>) => void`              | -          | Callback for pointer over event                                                    |
| `onPointerLeave` | `(e: React.PointerEvent<HTMLButtonElement>) => void`              | -          | Callback for pointer leave event                                                   |
| `onClick`        | `(e: React.MouseEvent<HTMLButtonElement>) => void`                | -          | Callback for click event                                                           |

## Technical Details

The `Button` component uses the `UI` component from the `#components/ui`
library. It handles various pointer events and ensures accessibility by using
the `aria-disabled` attribute.

## Usage Example

### Basic Usage

```tsx
import React from "react";
import Button from "#components/buttons/button";

const handleClick = () => {
  console.log("Button clicked");
};

const BasicButton = () => (
  <Button type="button" onClick={handleClick}>
    Click Me
  </Button>
);

export default BasicButton;
```

### Size, Variant & Color Props

The `size`, `variant`, and `color` props provide a typed React API over the
underlying `data-*` attributes. This gives consumers autocomplete and type
safety without needing to know the attribute names.

```tsx
import Button from "#components/buttons/button";

// Size variants
<Button type="button" size="xs">Extra Small</Button>
<Button type="button" size="sm">Small</Button>
<Button type="button" size="lg">Large</Button>
<Button type="button" size="xl">Extra Large</Button>
<Button type="button" size="2xl">2X Large</Button>

// Style variants
<Button type="button" variant="outline">Outline</Button>
<Button type="button" variant="pill">Pill</Button>
<Button type="button" variant="text">Text Button</Button>
<Button type="button" variant="icon" aria-label="Close">✕</Button>

// Color variants (use semantic design tokens)
<Button type="button" color="primary">Primary</Button>
<Button type="button" color="secondary">Secondary</Button>
<Button type="button" color="danger">Delete</Button>
<Button type="button" color="success">Confirm</Button>
<Button type="button" color="warning">Warning</Button>

// Combine props freely
<Button type="button" color="primary" variant="outline" size="lg">
  Large Primary Outline
</Button>
<Button type="button" color="danger" variant="pill">Danger Pill</Button>
```

**Note:** `size`, `block`, and `data-btn` are all merged into a single
whitespace-separated `data-btn` attribute. `<Button size="lg" block data-btn="pill">`
resolves to `data-btn="lg block pill"`.

### Block Layout

The `block` prop stretches the button to 100% of its container width. It
composes freely with `size` and other `data-btn` tokens.

```tsx
<Button type="button" block>Full Width</Button>
<Button type="button" size="lg" block color="primary">Large Full Width Primary</Button>
```

### IconButton

`IconButton` wraps `Button` with enforced accessibility and icon-specific defaults.
It requires exactly one of `aria-label` or `aria-labelledby` (XOR — passing
both or neither is a TypeScript compile-time error).

```tsx
import { IconButton } from "@fpkit/acss";

// Icon only
<IconButton type="button" aria-label="Close menu" icon={<CloseIcon />} />

// Icon + visible label (label hides on mobile, stays in a11y tree)
<IconButton
  type="button"
  aria-label="Settings"
  icon={<SettingsIcon />}
  label="Settings"
  variant="outline"
/>

// Labelled by external element
<span id="btn-lbl">Delete item</span>
<IconButton type="button" aria-labelledby="btn-lbl" icon={<TrashIcon />} />
```

**Defaults:** `variant="icon"` (transparent bg, `currentColor` icon color, square touch target).
Override `variant` to restore padding when using a `label`.

### Advanced Usage

```tsx
import React from "react";
import Button from "#components/buttons/button";

const handlePointerDown = (e: React.PointerEvent<HTMLButtonElement>) => {
  console.log("Pointer down", e);
};

const handlePointerOver = (e: React.PointerEvent<HTMLButtonElement>) => {
  console.log("Pointer over", e);
};

const handlePointerLeave = (e: React.PointerEvent<HTMLButtonElement>) => {
  console.log("Pointer leave", e);
};

const AdvancedButton = () => (
  <Button
    type="submit"
    color="primary"
    size="lg"
    onPointerDown={handlePointerDown}
    onPointerOver={handlePointerOver}
    onPointerLeave={handlePointerLeave}
  >
    Submit
  </Button>
);

export default AdvancedButton;
```

## Accessible Disabled State (Updated)

### Overview

The Button component now uses an **optimized disabled state implementation**
that follows WCAG 2.1 Level AA accessibility guidelines. This update brings
significant performance improvements and better accessibility compliance.

### Key Improvements

#### 1. **ARIA-Disabled Pattern**

Instead of using the native `disabled` attribute, the button uses
`aria-disabled`:

- **Stays in tab order** - Screen reader users can discover and navigate to
  disabled buttons
- **Allows focus** - Users can still focus disabled buttons to read tooltips or
  help text
- **Prevents interactions** - All click/keyboard events are blocked when
  disabled
- **Better styling control** - Meets WCAG AA contrast requirements more easily

#### 2. **Performance Optimizations**

The new `useDisabledState` hook provides:

- **~90% reduction in unnecessary re-renders** compared to previous
  implementation
- **Stable handler references** - Event handlers don't recreate on every render
- **Optimized memoization** - Single memoization pass for all props and handlers

#### 3. **Automatic className Merging**

The disabled state now automatically merges your custom classes with the
`.is-disabled` class:

```tsx
// Before: You had to manage className manually
<Button classes="my-btn is-disabled" disabled={true}>
  Click me
</Button>

// After: Automatic merging - just pass your classes
<Button classes="my-btn" disabled={true}>
  Click me
</Button>
// Result: className="is-disabled my-btn"
```

### Browser Behavior

When `disabled={true}`:

- ✅ Button appears in tab order (keyboard accessible)
- ✅ Screen readers announce "disabled" state
- ❌ Click events are prevented
- ❌ Keyboard activation (Enter/Space) is blocked
- ✅ Hover effects still work (visual feedback)
- ✅ Can receive focus for tooltips/help text

### Handler Precedence When Disabled

When `disabled` or `isDisabled` is set, built-in pointer handlers (`onPointerDown`, `onPointerOver`, `onPointerLeave`, `onClick`) take precedence over any handlers passed via props. This prevents interaction callbacks from firing on a disabled button.

### Migration Guide

No breaking changes! The API remains the same:

```tsx
// Still works exactly as before
<Button disabled={true} onClick={handleClick}>
  Click me
</Button>

// Legacy isDisabled prop also supported
<Button isDisabled={true} onClick={handleClick}>
  Click me
</Button>

// Custom classes automatically merge
<Button disabled={true} classes="btn-primary btn-large">
  Auto-merges with .is-disabled class
</Button>
```

### Styling Disabled Buttons

Target the `.is-disabled` class in your CSS:

```css
button.is-disabled {
  opacity: 0.6;
  cursor: not-allowed;
  /* Ensure WCAG AA contrast ratio of 4.5:1 */
  color: #666;
  background-color: #e0e0e0;
}
```

### WCAG Compliance

This implementation follows:

- **WCAG 2.1.1 (Keyboard)** - Maintains keyboard accessibility
- **WCAG 4.1.2 (Name, Role, Value)** - Proper ARIA state announcement
- **WCAG 1.4.3 (Contrast Minimum)** - Better styling control for contrast

### Related

- See [useDisabledState Hook](/docs/hooks/use-disabled-state) for advanced usage
- See [Accessibility Guide](/docs/guides/accessibility) for WCAG compliance
  details

## Additional Notes

- Ensure the `type` prop is set to one of `'button'`, `'submit'`, or `'reset'`.
- The `styles` prop can be used to apply inline styles to the button.
- The `disabled` prop uses the accessible `aria-disabled` pattern instead of
  native `disabled` attribute.
- **Breaking (height):** The `--btn-height` multiplier changed from `2.25` to
  `2.75`. All buttons are ~22% taller. Override `--btn-height` via the `styles`
  prop or a stylesheet rule to restore previous sizing.
- **Breaking (`.btn-pill`):** The `.btn-pill` CSS class is now scoped to
  `button.btn-pill` only. Non-button elements carrying the class no longer
  receive pill border-radius. Prefer `variant="pill"` (React) or
  `data-style="pill"` / `data-btn="pill"` (HTML) instead.