# Overflow

Utilities for controlling how an element handles content that is too large for the container.

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

```dart
// Basic examples
WDiv(className: 'overflow-hidden')
WDiv(className: 'overflow-scroll')
WDiv(className: 'overflow-x-auto')
```

## Basic Usage

Use `overflow-{mode}` to control how content behaves when it exceeds the container's bounds.

### Hidden

Use `overflow-hidden` to clip any content that extends beyond the container's edges.

The clip follows the container's own corner radius, and the anti-aliasing follows
the shape: a square clip uses `Clip.hardEdge`, which is the cheapest option and
exactly right on an axis-aligned rectangle, while a ROUNDED one uses
`Clip.antiAlias`. Hard-edging a curve can only cut on whole pixels, and because
a border's stroke sits inside the clip path (`BorderSide.strokeAlign` defaults to
`strokeAlignInside`), the staircase eats the border rather than the surface
behind it: the line thins and vanishes through each corner while the straight
runs stay crisp.

```dart
WDiv(
  className: 'overflow-hidden w-20 h-20 bg-white rounded-lg',
  child: WDiv(className: 'w-40 h-40 bg-red-500'),
)
```

### Scroll

Use `overflow-scroll` to enable scrolling regardless of whether content overflows. This generally wraps the content in a `SingleChildScrollView`.

```dart
WDiv(
  className: 'overflow-scroll w-64 h-64 bg-white',
  child: LongContentWidget(),
)
```

### Auto

Use `overflow-auto` to enable scrolling only when content actually overflows the container bounds.

```dart
WDiv(
  className: 'overflow-auto max-h-48 bg-gray-100',
  child: LongContentWidget(),
)
```

### Visible

Use `overflow-visible` to allow content to spill out of the container. This applies `Clip.none` and prevents the container from introducing a scroll context.

```dart
WDiv(
  className: 'overflow-visible',
  child: LargeContentWidget(),
)
```

## Quick Reference

| Class | Flutter Equivalent | Description |
|:------|:-------------------|:------------|
| `overflow-auto` | `SingleChildScrollView` (conditional) | Scroll only if content overflows |
| `overflow-hidden` | `Clip.antiAlias` when rounded, `Clip.hardEdge` when square | Clip overflowing content; with a border, the clip sits inside it (the padding box), as in CSS |
| `overflow-visible` | `Clip.none` | Content flows outside container |
| `overflow-scroll` | `SingleChildScrollView` | Always enable scrolling |

## Variants

### Directional Overflow

Use `overflow-x-{mode}` and `overflow-y-{mode}` to control overflow on a specific axis independently.

```dart
WDiv(className: 'overflow-x-scroll overflow-y-hidden')
```

| Class | Description |
|:------|:------------|
| `overflow-x-auto` | Scroll horizontally if needed |
| `overflow-y-scroll` | Always scroll vertically |
| `overflow-x-hidden` | Clip horizontal overflow |
| `overflow-y-visible` | Allow vertical overflow |

## Fill on Desktop, Scroll on Narrow (Responsive Table)

Compose `overflow-x-auto` on a wrapper with `w-full` (optionally `min-w-[Npx]`) on the inner content, the same pattern shadcn's `<Table>` uses. The inner content fills the viewport when it is wide and honors its minimum width (so the wrapper scrolls) when it is narrow:

```dart
WDiv(
  className: 'overflow-x-auto',
  child: WDiv(
    className: 'w-full min-w-[600px] flex flex-row',
    children: [
      WDiv(className: 'flex-1', child: WText('Name')),
      WDiv(className: 'flex-1', child: WText('Status')),
      WDiv(className: 'flex-1', child: WText('Updated')),
    ],
  ),
)
```

On a viewport wider than `600px` the row fills the container (no horizontal scroll). On a narrower viewport it stays `600px` wide and the wrapper scrolls horizontally. This works with no new token: `w-full` inside a horizontal scroll is threaded the viewport width instead of asserting on the scroll's unbounded width, and `min-w-[Npx]` sets the scroll floor. Without a `min-w-*` floor, `w-full` simply fills the viewport.

> **`h-full` inside a vertical scroll is a layout error.** A child that resolves `h-full` inside an `overflow-y-auto` / `overflow-y-scroll` parent has an unbounded height and produces a cryptic Flutter failure. Wind raises an actionable assert in debug pointing at the fix: use `flex-1` inside a `flex flex-col` (with the scroll on the column) instead of `h-full` inside a vertical scroll. The scroll container itself may still carry `h-full` (it is bounded by its own parent).

## Responsive Design

Apply different overflow behaviors at different breakpoints using standard modifiers like `sm:`, `md:`, `lg:`, `xl:`, and `2xl:`.

```dart
// Scroll on mobile, but show full content on desktop
WDiv(className: 'overflow-scroll md:overflow-visible')
```

## Dark Mode

Change overflow behavior in dark mode using the `dark:` prefix.

```dart
WDiv(className: 'overflow-visible dark:overflow-hidden')
```

## Arbitrary Values

The overflow utility does not support arbitrary values. You must use one of the defined keywords (`hidden`, `visible`, `scroll`, `auto`).

## Customizing Theme

Overflow utilities are hardcoded behavior toggles and cannot be customized via `WindThemeData`.

## Related Documentation

- [Sizing](https://anilcancakir.com/wind_kit/docs/v1.9/layout/sizing.md)
- [Display](https://anilcancakir.com/wind_kit/docs/v1.9/layout/display.md)