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
• Constructor
• Props
• Runtime-Dynamic Colors
• Layout Modes
• Event Handling
• State Variants
• Styling Examples
• All Supported Classes
• Customizing Theme
• Related Documentation

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.

// 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

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

Props

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].

// 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 children in rows.
• 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.

For direct gesture support (taps, long presses) or to create semantic buttons, use WAnchor or WButton.

State Variants

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

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.

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

Shadows & Rings

Apply depth with shadows or focus indicators with rings.

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.

// 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

Customizing Theme

WDiv respects the configuration defined in WindThemeData.

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 & Grid
• Sizing Utilities
• Spacing & Margins
• Interaction State Prefixes
• WAnchor Widget
• WSpacer Widget