# Sizing

Utilities for setting the width and height of elements.

- [Basic Usage](#basic-usage)
- [Quick Reference](#quick-reference)
- [Width](#width)
- [Height](#height)
- [Size (Both Axes)](#size-both-axes)
- [Min & Max Dimensions](#min--max-dimensions)
- [Intrinsic Sizing Limitation](#intrinsic-sizing-limitation)
- [Responsive Design](#responsive-design)
- [Dark Mode](#dark-mode)
- [Arbitrary Values](#arbitrary-values)
- [Customizing Theme](#customizing-theme)
- [Related Documentation](#related-documentation)

```dart
// Fixed width and height
WDiv(className: 'w-64 h-32 bg-blue-500')

// Percentage based
WDiv(className: 'w-1/2 h-full bg-green-500')

// Viewport relative
WDiv(className: 'w-screen h-screen bg-gray-900')
```

## Basic Usage

Use `w-{size}` and `h-{size}` to set fixed dimensions based on the global spacing scale, or use fraction/percentage utilities like `w-1/2` or `w-full`.

```dart
WDiv(
  className: 'w-full max-w-md mx-auto p-6 bg-white rounded-lg shadow-lg',
  child: WText('Centered Content'),
)
```

## Quick Reference

### Fixed Sizes

Values follow the global spacing scale (1 unit = 4px).

| Class | Value | Description |
|:------|:------|:------------|
| `w-0` / `h-0` | 0px | Zero width/height |
| `w-px` / `h-px` | 1px | 1px width/height |
| `w-1` / `h-1` | 4px | Tiny |
| `w-4` / `h-4` | 16px | Small |
| `w-16` / `h-16` | 64px | Medium |
| `w-96` / `h-96` | 384px | Large |

### Percentages & Viewport

| Class | Value | Description |
|:------|:------|:------------|
| `w-full` / `h-full` | 100% | Full parent width/height |
| `w-screen` / `h-screen` | 100vw / 100vh | Full viewport width/height |
| `w-1/2` / `h-1/2` | 50% | Half parent size |
| `w-1/3` / `h-1/3` | 33.33% | Third parent size |
| `w-2/3` / `h-2/3` | 66.66% | Two-thirds parent size |
| `w-1/4` / `h-1/4` | 25% | Quarter parent size |
| `w-3/4` / `h-3/4` | 75% | Three-quarters parent size |

## Width

Set the width of an element using `w-{number}` or `w-{fraction}`.

```dart
// Fixed width (128px)
WDiv(className: 'w-32 bg-blue-200')

// Fractional width (50%)
WDiv(className: 'w-1/2 bg-blue-300')

// Full width (100%)
WDiv(className: 'w-full bg-blue-400')
```

## Height

Set the height of an element using `h-{number}`, `h-{fraction}`, or `h-screen`.

```dart
// Fixed height (64px)
WDiv(className: 'h-16 bg-red-200')

// Full screen height
WDiv(className: 'h-screen bg-red-300')
```

## Size (Both Axes)

`size-{value}` sets width AND height in a single token (the Tailwind v3.4+ shorthand). It accepts the same values as `w-` / `h-`: spacing numbers, `full`, fractions, and arbitrary `[px]` / `[%]`. It works on a childless `WDiv`, so a fixed-size square such as a status dot needs no wrapper.

```dart
// 8x8 status dot, no child required
WDiv(className: 'size-2 rounded-full bg-green-500 dark:bg-green-400')

// Square avatar
WDiv(className: 'size-12 rounded-full bg-gray-200 dark:bg-gray-700')

// Fill the parent on both axes
WDiv(className: 'size-full bg-blue-500 dark:bg-blue-600')
```

A later `w-*` or `h-*` overrides the matching axis: `size-4 w-8` is 32px wide, 16px tall.

## Min & Max Dimensions

Constrain the size of elements using `min-w`, `max-w`, `min-h`, and `max-h` utilities.

### Max-Width Scale

Wind includes a comprehensive max-width scale, perfect for keeping text readable ("measure") or constraining layout width.

| Class | Value |
|:------|:------|
| `max-w-0` | 0px |
| `max-w-none` | No limit (Infinity) |
| `max-w-xs` | 320px |
| `max-w-sm` | 384px |
| `max-w-md` | 448px |
| `max-w-lg` | 512px |
| `max-w-xl` | 576px |
| `max-w-2xl` | 672px |
| `max-w-3xl` | 768px |
| `max-w-4xl` | 896px |
| `max-w-5xl` | 1024px |
| `max-w-6xl` | 1152px |
| `max-w-7xl` | 1280px |
| `max-w-full` | 100% |
| `max-w-screen` | 100vw |
| `max-w-prose` | 512px |

```dart
// Constrain content width and center it
WDiv(
  className: 'max-w-2xl mx-auto p-4',
  child: WText('Readable content...'),
)
```

### Other Constraints

| Class | Value |
|:------|:------|
| `min-w-0` | 0px |
| `min-w-full` | 100% |
| `min-w-screen` | 100vw |
| `min-h-0` | 0px |
| `min-h-full` | 100% |
| `min-h-screen` | 100vh |
| `max-h-full` | 100% |
| `max-h-screen` | 100vh |

## Intrinsic Sizing Limitation

Wrapping Wind content in `IntrinsicHeight` or `IntrinsicWidth` (or placing it in a `Row` / `Column` that needs child intrinsic heights, e.g. for equal-height columns) can throw:

```
LayoutBuilder does not support returning intrinsic dimensions.
```

**Why.** To resolve a size against the parent's real constraints, Wind used to introduce a `LayoutBuilder`, and a `LayoutBuilder` runs during the layout phase rather than the intrinsic-sizing phase, so any intrinsic query passing through one asserts. That is a Flutter constraint, not a Wind bug.

**What still triggers it: `grid` only.** `grid-cols-*` composes a `Wrap` inside a `LayoutBuilder` (it needs the available width to compute a column width), so a `grid` anywhere inside the subtree you wrap in `IntrinsicHeight` / `IntrinsicWidth` still asserts.

**What no longer does.** `h-full` and flex `basis-*` are both intrinsic-safe now. `h-full` resolves through the `WindFullHeightBox` render object, `basis-*` through `WindMainExtentProvider`, and the column cross-axis stretch through `WindCrossStretch`; a render object answers intrinsic queries, so all three render under an `IntrinsicHeight`, in a `Table` cell, or in an `items-stretch` grid cell without throwing. If you carry an escape hatch for `h-full` from an earlier version, you can drop it.

**Escape hatches, for the `grid` case that remains.**

- Prefer explicit sizing: give the cells a fixed `h-*` (or `size-*`) instead of a `grid` + `IntrinsicHeight`.
- For an equal-height row, use a `Stack` with a `Positioned(top: 0, bottom: 0)` element for the part that must fill, or reserve equal content so natural heights already match.
- Wind's own `items-stretch` grid equalizes row heights with real layout rather than `IntrinsicHeight`, so reach for it INSTEAD of wrapping.

```dart
// Throws: the wrapped subtree contains a grid.
IntrinsicHeight(
  child: WDiv(className: 'grid grid-cols-2 gap-4', children: cards),
)

// Safe: items-stretch equalizes the row heights with real layout.
WDiv(
  className: 'grid grid-cols-2 gap-4 items-stretch',
  children: cards,
)
```

## Responsive Design

Apply different sizing utilities at different breakpoints using standard prefixes.

```dart
// Full width on mobile, 50% on tablet, 33% on desktop
WDiv(className: 'w-full md:w-1/2 lg:w-1/3')
```

## Dark Mode

While sizing rarely changes based on theme, you can use `dark:` modifiers if needed.

```dart
WDiv(className: 'w-64 dark:w-full')
```

## Arbitrary Values

Use square brackets to apply specific values that aren't in the theme scale.

```dart
// Specific pixels
WDiv(className: 'w-[350px] h-[50px]')

// Specific percentage
WDiv(className: 'w-[33%] h-[45%]')
```

## Customizing Theme

To extend the sizing scale, modify the `spacing` section of your `WindThemeData`. This affects width, height, padding, margin, and positioning.

```dart
WindThemeData(
  spacing: {
    '128': 512.0, // Adds w-128, h-128, p-128...
  },
)
```

## Related Documentation

- [Padding & Margin](https://anilcancakir.com/wind_kit/docs/v1.9/layout/spacing.md)
- [Flexbox & Grid](https://anilcancakir.com/wind_kit/docs/v1.9/layout/flexbox.md)
- [Aspect Ratio](https://anilcancakir.com/wind_kit/docs/v1.9/layout/aspect-ratio.md)