# Display

Utilities for controlling the layout mode of an element.

- [Basic Usage](#basic-usage)
  - [Block](#block)
  - [Flex](#flex)
  - [Grid](#grid)
  - [Wrap](#wrap)
  - [Hidden](#hidden)
- [Quick Reference](#quick-reference)
- [Responsive Design](#responsive-design)
- [Dark Mode](#dark-mode)
- [State Variants](#state-variants)
- [Arbitrary Values](#arbitrary-values)
- [Customizing Theme](#customizing-theme)
- [Related Documentation](#related-documentation)

```dart
// Flex container
WDiv(className: 'flex gap-4', children: [...])

// Grid container
WDiv(className: 'grid grid-cols-3', children: [...])

// Hidden element
WDiv(className: 'hidden', child: ...)
```

## Basic Usage

### Block

Use `block` to create a standard block-level element. In Wind, this is the default behaviour of `WDiv` (rendering a `Container` or `SizedBox`).

```dart
WDiv(
  className: 'block p-4 bg-white',
  child: WText('This is a block element'),
)
```

### Flex

Use `flex` to create a flex container. This enables Flexbox layout properties (like `flex-row`, `items-center`, `justify-between`).

> [!NOTE]
> `flex` creates a `Row` or `Column` depending on `flex-row` (default) or `flex-col`.

```dart
WDiv(
  className: 'flex items-center space-x-4',
  children: [
    WDiv(className: 'w-10 h-10 bg-blue-500'),
    WText('Flex item'),
  ],
)
```

### Grid

Use `grid` to create a grid container. This enables Grid layout properties (like `grid-cols-3`, `gap-4`).

```dart
WDiv(
  className: 'grid grid-cols-3 gap-4',
  children: [
    WDiv(className: 'h-20 bg-blue-100'),
    WDiv(className: 'h-20 bg-blue-200'),
    WDiv(className: 'h-20 bg-blue-300'),
  ],
)
```

### Wrap

Use `wrap` to create a wrapping container. This renders a Flutter `Wrap` widget.

> [!NOTE]
> In Flutter, `Row`/`Column` cannot wrap, so `wrap` renders a dedicated `Wrap` widget rather than composing with `flex`. Prefer `wrap` directly; `flex-wrap` is aliased to it for callers coming from CSS (emits a one-time debug hint suggesting `wrap`).

```dart
WDiv(
  className: 'wrap gap-2',
  children: [
    WBadge('React'),
    WBadge('Flutter'),
    WBadge('Vue'),
  ],
)
```

### Hidden

Use `hidden` to remove an element from the visual tree. This renders a `SizedBox.shrink()` (effectively 0x0 size).

```dart
WDiv(
  className: 'hidden',
  child: WText('This will not appear'),
)
```

## Quick Reference

| Class | Description |
| :--- | :--- |
| `block` | Standard box model layout (Default). |
| `flex` | Creates a Flex container (Row/Column). |
| `grid` | Creates a Grid container. |
| `wrap` | Creates a Wrap container. |
| `hidden` | Removes the element from the layout. |

## Responsive Design

Prefix any display utility with a breakpoint variant like `md:` to apply it only at specific screen sizes.

```dart
// Hidden on mobile, Flex on medium screens and up
WDiv(
  className: 'hidden md:flex gap-4',
  children: [...],
)

// Block on mobile, Hidden on large screens
WDiv(
  className: 'block lg:hidden',
  child: ...,
)
```

## Dark Mode

Prefix any display utility with `dark:` to apply it only when dark mode is active.

```dart
// Visible only in dark mode
WDiv(
  className: 'hidden dark:block',
  child: WText('Dark Mode Active'),
)
```

## State Variants

Prefix utilities with state variants like `hover:` or `focus:` to conditionally apply display modes. `active:` is not wired to the pointer; it applies only when the widget is given `states: {'active'}`. `group-hover:` is not supported.

```dart
// Show element on hover
WAnchor(
  onTap: () {},
  child: WDiv(
    className: 'p-4',
    children: [
      WText('Hover the card'),
      WText('Revealed on hover', className: 'hidden hover:block'),
    ],
  ),
)
```

A `WDiv` with `hover:` tracks its own hover; reveal through a `WText`.

## Arbitrary Values

The display utility does not support arbitrary values. You must use one of the predefined keywords (`block`, `flex`, `grid`, `wrap`, `hidden`).

## Customizing Theme

Display utilities are structural and cannot be customised via `WindThemeData`. They map directly to Flutter widgets (`Row`, `Column`, `Wrap`, `GridView`).

## Related Documentation

- [Flexbox](https://anilcancakir.com/wind_kit/docs/layout/flexbox.md) - Layout direction, alignment, and sizing for flex containers.
- [Grid](https://anilcancakir.com/wind_kit/docs/layout/grid.md) - Column definitions and gaps for grid containers.