# Z-Index

Utilities for controlling the stack order of an element.

## Table of Contents

- [Basic Usage](#basic-usage)
- [Quick Reference](#quick-reference)
- [Variants](#variants)
- [Responsive Design](#responsive-design)
- [Dark Mode](#dark-mode)
- [Arbitrary Values](#arbitrary-values)
- [Customizing Theme](#customizing-theme)
- [Related Documentation](#related-documentation)

```dart
// Standard values
WDiv(className: 'z-0')
WDiv(className: 'z-50')

// Arbitrary values
WDiv(className: 'z-[100]')
WDiv(className: 'z-[-1]')
```

## Basic Usage

`z-*` parses into `WindStyle.zIndex`, but no widget reads it yet: children paint in source order. Control stacking by child order.

```dart
// Painted in source order: the green box ends up on top
Stack(
  children: [
    WDiv(className: 'z-0 bg-blue-500 w-20 h-20'),
    WDiv(className: 'z-10 bg-red-500 w-20 h-20 ml-10 mt-10'),
    WDiv(className: 'z-20 bg-green-500 w-20 h-20 ml-20 mt-20'),
  ],
)
```

## Quick Reference

| Class | Value | Description |
|:------|:------|:------------|
| `z-0` | 0 | Stack level 0 |
| `z-10` | 10 | Stack level 10 |
| `z-20` | 20 | Stack level 20 |
| `z-30` | 30 | Stack level 30 |
| `z-40` | 40 | Stack level 40 |
| `z-50` | 50 | Stack level 50 |
| `z-auto` | `null` | Resets stack level (default) |

## Variants

### Hover & Focus

State prefixes such as `hover:z-50` parse like any other class, but because no widget reads `zIndex`, they do not change the paint order.

## Responsive Design

Apply different z-indices at specific breakpoints using the `sm:`, `md:`, `lg:`, `xl:`, and `2xl:` prefixes.

```dart
// z-0 on mobile, z-50 on medium screens and up
WDiv(className: 'z-0 md:z-50')
```

## Dark Mode

Use the `dark:` prefix to apply specific z-indices when the application is in dark mode.

```dart
WDiv(className: 'z-10 dark:z-20')
```

## Arbitrary Values

Use square brackets `[]` to apply custom z-index values that aren't part of the theme. This supports both positive and negative integers.

```dart
// Custom positive value
WDiv(className: 'z-[100]')

// Custom negative value
WDiv(className: 'z-[-5]')
```

## Customizing Theme

To extend or override the default z-index scale, modify the `zIndices` property in `WindThemeData`.

```dart
WindThemeData(
  zIndices: {
    // Override defaults
    '0': 0,
    '50': 50,
    
    // Add custom values
    '100': 100,
    'modal': 9999,
    'popover': 5000,
  },
)
```

Usage with custom theme:

```dart
WDiv(className: 'z-modal')   // Parses to zIndex 9999
WDiv(className: 'z-popover') // Parses to zIndex 5000
```

## Related Documentation

- [Position](https://anilcancakir.com/wind_kit/docs/layout/positioning.md)
- [Display](https://anilcancakir.com/wind_kit/docs/layout/display.md)
- [WindTheme](https://anilcancakir.com/wind_kit/docs/core-concepts/theming.md)