# WDiv

The fundamental building block of Wind. `WDiv` acts as a multi-purpose container that replaces standard Flutter widgets like `Container`, `Row`, `Column`, `Flex`, `Grid`, `Wrap`, and `SingleChildScrollView`.

It embodies the "Intelligent Composition" philosophy, dynamically constructing the most efficient widget tree based on the provided utility classes. Instead of blindly wrapping content, `WDiv` inspects the `className` and selectively applies specialized widgets like `Padding`, `Align`, `Row`, or `GridView` only when necessary.

- [Basic Usage](#basic-usage)
- [Constructor](#constructor)
- [Props](#props)
- [Runtime-Dynamic Colors](#runtime-dynamic-colors)
- [Layout Modes](#layout-modes)
- [Event Handling](#event-handling)
- [State Variants](#state-variants)
- [Styling Examples](#styling-examples)
- [All Supported Classes](#all-supported-classes)
- [Customizing Theme](#customizing-theme)
- [Related Documentation](#related-documentation)

<!-- Description: Basic demonstration of WDiv as a styled container with flex layout -->

```dart
WDiv(
  className: 'flex flex-col gap-4 p-6 bg-white rounded-xl shadow-lg',
  children: [
    WText('Hello Wind', className: 'text-2xl font-bold'),
    WText('This is a styled container.', className: 'text-gray-600'),
  ],
)
```

## Basic Usage

Use `WDiv` with a single `child` for simple wrapping or with `children` when using layout modes like `flex` or `grid`.

```dart
// Simple container
WDiv(
  className: 'p-4 bg-blue-500 rounded',
  child: WText('Single Child', className: 'text-white'),
)

// Flex row
WDiv(
  className: 'flex flex-row gap-2',
  children: [
    WDiv(className: 'w-10 h-10 bg-red-500'),
    WDiv(className: 'w-10 h-10 bg-green-500'),
  ],
)
```

## Constructor

```dart
const WDiv({
  Key? key,
  String? className,
  Widget? child,
  List<Widget>? children,
  WindStyle? style,
  Set<String>? states,
  bool scrollPrimary = false,
  Color? backgroundColor,
})
```

## Props

| Prop | Type | Default | Description |
|:-----|:-----|:--------|:------------|
| `className` | `String?` | `null` | Utility class string defining layout and styles. |
| `child` | `Widget?` | `null` | Single child widget. Mutually exclusive with `children`. |
| `children` | `List<Widget>?` | `null` | List of children widgets. Mutually exclusive with `child`. |
| `style` | `WindStyle?` | `null` | Explicit style object that serves as a base for `className`. |
| `states` | `Set<String>?` | `null` | Custom states to activate prefix classes (e.g., `loading:bg-blue-500`). |
| `scrollPrimary` | `bool` | `false` | Whether this is the primary scroll view for iOS tap-to-top and desktop scrollbar integration. |
| `backgroundColor` | `Color?` | `null` | Inline background color for runtime-dynamic values. Overrides any `bg-*` / `dark:bg-*` from `className`. See [Runtime-Dynamic Colors](#runtime-dynamic-colors). |

## Runtime-Dynamic Colors

Utility classes are for **design tokens** (`bg-primary-500`, `bg-red-500`). When the color is a **runtime value**, a hex from a color picker or a brand color loaded per tenant, use the `backgroundColor` prop instead of interpolating into `bg-[#$hex]`.

```dart
// Good: runtime-dynamic color via inline prop
WDiv(
  backgroundColor: userBrandColor, // Color from a picker or API
  className: 'w-16 h-16 rounded-xl',
)

// Avoid: string interpolation bloats the parser cache, one entry per unique hex
WDiv(className: 'w-16 h-16 rounded-xl bg-[#${userBrandColor.hex}]')
```

Precedence: inline `backgroundColor` wins over any `bg-*` / `dark:bg-*` resolved from `className`. When `backgroundColor` is `null`, className behavior, including the `dark:` fallback, is unchanged. The inline color does not participate in the parser cache key.

## Layout Modes

`WDiv` dynamically switches its internal structure based on the `display` utility classes provided in `className`.

- **Block (Default)**: Standard vertical stack or single child wrapper. If `children` is used without `flex` or `grid`, it defaults to a `Column`.
- **Flex**: Enabled via `flex`. Supports `flex-row`, `flex-col`, `gap-*`, `items-*`, `justify-*`. It mimics CSS Flexbox behavior, including automatic `Flexible` wrapping for row children so they can shrink. That wrap is skipped when a child claims a grow share (`flex-1`, `grow`, `flex-auto`, a bare `w-full`, or a raw `Expanded`/`Flexible`), so the growing child keeps the free space and its siblings stay at their content width. See [Flexbox](https://anilcancakir.com/wind_kit/docs/v1.7/layout/flexbox.md#flex-grow--shrink).
- **Grid**: Enabled via `grid`. Uses a combination of `Wrap` and `LayoutBuilder` to achieve Tailwind-like grid behavior (`grid-cols-*`) with intrinsic item heights.
- **Wrap**: Enabled via `wrap`. Elements wrap to the next line when space is insufficient, similar to `flex-wrap` in CSS.
- **Hidden**: Enabled via `hidden`. The widget short-circuits to `SizedBox.shrink()` to save resources.

## Event Handling

`WDiv` automatically becomes interactive when state-based prefixes like `hover:`, `focus:`, or `active:` are used in the `className`. Under the hood, it wraps the content in a `WAnchor` to detect gestures and focus.

That wrap is styling only: the auto-wrapped `WAnchor` carries no gesture, so it publishes no `button` node to assistive technology. A `WDiv` with `hover:bg-slate-100` styles on hover and still announces as whatever its content is, rather than as a control that does nothing when activated.

It is not a keyboard or remote stop either. Inside a tappable `WAnchor` the wrapper inherits that anchor's `focus` and `disabled` rather than claiming a stop of its own, so the control is reached once and the ring is drawn on the element the user activates. Standing alone, with no anchor above it, the `WDiv` keeps its own focus node and stays reachable. `hover` is never inherited, so sibling divs inside one anchor still highlight independently. See [WAnchor](https://anilcancakir.com/wind_kit/docs/v1.7/widgets/w-anchor.md#keyboard-and-remote-control).

For direct gesture support (taps, long presses) or to create semantic buttons, use [WAnchor](https://anilcancakir.com/wind_kit/docs/v1.7/widgets/w-anchor.md) or [WButton](https://anilcancakir.com/wind_kit/docs/v1.7/widgets/w-button.md).

## State Variants

`WDiv` supports all Wind state prefixes, allowing you to change styles based on interaction or environment.

```dart
WDiv(
  className: 'bg-blue-500 hover:bg-blue-600 active:scale-95 duration-200',
  child: WText('Interactive', className: 'text-white'),
)
```

Common prefixes:
- `hover:` - Applies when the mouse pointer is over the element.
- `focus:` - Applies when the element has keyboard focus.
- `disabled:` - Applies when the element or parent is disabled.
- `dark:` - Applies when the application is in dark mode.
- `active:` - Applies while the element is being pressed.

## Styling Examples

### Backgrounds & Borders
Combine background colors, gradients, and border properties.

```dart
WDiv(className: 'bg-red-500 border-2 border-red-700 rounded-lg')
```

### Shadows & Rings
Apply depth with shadows or focus indicators with rings.

```dart
WDiv(className: 'shadow-xl ring-2 ring-blue-500 ring-offset-2')
```

### Responsive Design
`WDiv` uses mobile-first breakpoints to adapt layouts to different screen sizes.

```dart
// Stacked on mobile, side-by-side on tablet/desktop
WDiv(className: 'flex flex-col md:flex-row gap-4')

// Variable widths
WDiv(className: 'w-full md:w-1/2 lg:w-1/3')
```

## All Supported Classes

| Category | Classes |
|:---------|:--------|
| **Display** | `block`, `flex`, `grid`, `wrap`, `hidden` |
| **Flexbox** | `flex-row`, `flex-col`, `justify-*`, `items-*`, `gap-*`, `flex-1`, `flex-2`, etc. |
| **Grid** | `grid-cols-*`, `gap-x-*`, `gap-y-*` |
| **Sizing** | `w-*`, `h-*`, `min-w-*`, `max-w-*`, `aspect-*` |
| **Spacing** | `p-*`, `px-*`, `py-*`, `m-*`, `mx-*`, `my-*`, `space-x-*`, `space-y-*` |
| **Background** | `bg-*`, `bg-gradient-*`, `bg-opacity-*` |
| **Borders** | `border-*`, `rounded-*`, `border-opacity-*` |
| **Effects** | `shadow-*`, `opacity-*`, `ring-*`, `ring-offset-*` |
| **Overflow** | `overflow-hidden`, `overflow-scroll`, `overflow-auto`, `overflow-x-*`, `overflow-y-*` |
| **Animation** | `animate-spin`, `animate-pulse`, `animate-bounce`, `animate-ping` |
| **Transitions** | `transition-*`, `duration-*`, `ease-*` |

## Customizing Theme

`WDiv` respects the configuration defined in `WindThemeData`.

```dart
WindTheme(
  data: WindThemeData(
    baseSpacingUnit: 4.0, // Multiplier for p-1, m-4, etc.
    colors: { ... },      // Custom color palette for bg-*, border-*
    breakpoints: { ... }, // Custom screen sizes for md:, lg:, etc.
  ),
  child: ...,
)
```

## Related Documentation

- [Flexbox](https://anilcancakir.com/wind_kit/docs/v1.7/layout/flexbox.md) & [Grid](https://anilcancakir.com/wind_kit/docs/v1.7/layout/grid.md)
- [Sizing Utilities](https://anilcancakir.com/wind_kit/docs/v1.7/layout/sizing.md)
- [Spacing & Margins](https://anilcancakir.com/wind_kit/docs/v1.7/layout/spacing.md)
- [Interaction State Prefixes](https://anilcancakir.com/wind_kit/docs/v1.7/core-concepts/state-management.md)
- [WAnchor Widget](https://anilcancakir.com/wind_kit/docs/v1.7/widgets/w-anchor.md)
- [WSpacer Widget](https://anilcancakir.com/wind_kit/docs/v1.7/widgets/w-spacer.md)