Layout System

@saastro/forms provides two layout modes for organizing fields in a grid:

Manual Mode

Use manual mode when you need precise control over field widths at different breakpoints.

How It Works

1. Set a fixed number of columns (e.g., 12)
2. Each field specifies how many columns it occupies
3. Use responsive breakpoints (md, lg, etc.) for different screen sizes

Example

import { FormBuilder } from '@saastro/forms';

const config = FormBuilder.create('contact')
  .layout('manual') // Explicit manual mode
  .columns(12) // 12-column grid
  .gap(4) // gap-4 (1rem)
  .addField(
    'firstName',
    (f) => f.type('text').label('First Name').columns({ default: 12, md: 6 }), // Full width on mobile, half on md+
  )
  .addField('lastName', (f) => f.type('text').label('Last Name').columns({ default: 12, md: 6 }))
  .addField(
    'email',
    (f) => f.type('email').label('Email').columns({ default: 12 }), // Always full width
  )
  .addStep('main', ['firstName', 'lastName', 'email'])
  .build();

Generated CSS

<div class="grid grid-cols-12 gap-4">
  <div class="col-span-12 md:col-span-6"><!-- firstName --></div>
  <div class="col-span-12 md:col-span-6"><!-- lastName --></div>
  <div class="col-span-12"><!-- email --></div>
</div>

Breakpoints

Common Patterns

// Two columns on desktop
.columns({ default: 12, md: 6 })

// Three columns on large screens
.columns({ default: 12, md: 6, lg: 4 })

// Sidebar layout (4 + 8)
.columns({ default: 12, lg: 4 })  // sidebar
.columns({ default: 12, lg: 8 })  // main

// Equal thirds
.columns({ default: 12, md: 4 })

Auto Mode

Use auto mode when you want fields to automatically adjust to available space.

How It Works

1. Set a minimum field width (default: 240px)
2. Grid creates as many columns as fit
3. Optionally set a maximum number of columns
4. Fields stretch equally to fill available space

Example

const config = FormBuilder.create('settings')
  .layout('auto') // Auto mode (default)
  .minFieldWidth(280) // Minimum 280px per field
  .columns(4) // Maximum 4 columns
  .gap(6) // gap-6 (1.5rem)
  .addField('setting1', (f) => f.type('text').label('Setting 1'))
  .addField('setting2', (f) => f.type('text').label('Setting 2'))
  .addField('setting3', (f) => f.type('text').label('Setting 3'))
  .addField('setting4', (f) => f.type('text').label('Setting 4'))
  .addField('setting5', (f) => f.type('text').label('Setting 5'))
  .addStep('main', ['setting1', 'setting2', 'setting3', 'setting4', 'setting5'])
  .build();

Generated CSS

<div
  class="grid gap-6"
  style="grid-template-columns: repeat(auto-fit, minmax(max(17.5rem, calc((100% - 4.5rem) / 4)), 1fr))"
>
  <div><!-- setting1 --></div>
  <div><!-- setting2 --></div>
  <!-- ... -->
</div>

Auto Mode Options

Important Notes

• col-span-* classes are ignored in auto mode
• All fields have equal width
• Use minFieldWidth and columns to control sizing
• Great for forms where all fields should be similar size

Gap Configuration

The gap method sets spacing between fields:

.gap(0)   // gap-0 (no gap)
.gap(2)   // gap-2 (0.5rem / 8px)
.gap(4)   // gap-4 (1rem / 16px) - default
.gap(6)   // gap-6 (1.5rem / 24px)
.gap(8)   // gap-8 (2rem / 32px)

When to Use Each Mode

Use Manual Mode When:

• You need different field widths (name: 6 cols, address: 12 cols)
• You want responsive breakpoints per field
• Precise layout control is important
• Building complex multi-column layouts

Use Auto Mode When:

• All fields should be similar width
• You want automatic responsive behavior
• Building settings forms, preferences panels
• Content adapts to container width

API Reference

FormBuilder Layout Methods

FormBuilder.create('form')
  .layout(mode) // 'manual' | 'auto'
  .columns(n) // 1-12 (grid columns or max columns)
  .gap(n) // 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 14, 16, 20, 24
  .minFieldWidth(px) // Auto mode only: minimum field width in pixels
  .layoutClassName(cls); // Additional CSS classes for grid container

FieldBuilder Column Methods

.columns(n)                           // Simple: all breakpoints
.columns({ default: 12, md: 6 })      // Responsive: by breakpoint
.columns({ default: 12, sm: 6, md: 4, lg: 3 })  // Multiple breakpoints