npm package: @simpledotstudio/simple-layout
Description: SimpleLayout - A versatile layout component supporting both flexbox and grid layouts with easy spacing and alignment controls
Author: SimpleStudio
Latest version: 1.0.0-alpha.2

# SimpleLayout

A versatile layout component supporting both flexbox and grid layouts with easy spacing, alignment, and responsive controls.

## Installation

```bash
npm install @simpledotstudio/simple-layout
```

## Usage

```tsx
import { SimpleLayout } from '@simpledotstudio/simple-layout';

function App() {
  return (
    // Flexbox layout with gap and padding
    <SimpleLayout gap="md" padding="lg" align="center">
      <div>Item 1</div>
      <div>Item 2</div>
      <div>Item 3</div>
    </SimpleLayout>
  );
}
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | - | Child elements to layout |
| `type` | `'flex' \| 'grid'` | `'flex'` | Layout type |
| `gap` | `SpacingSize \| number` | - | Gap between items (works for both flex and grid) |
| `padding` | `SpacingSize \| number` | - | Padding inside the container |
| `margin` | `SpacingSize \| number` | - | Margin outside the container |
| **Flexbox Props** |
| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | `'row'` | Flex direction |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'stretch'` | Align items on cross axis |
| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | `'start'` | Justify content on main axis |
| `wrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | Flex wrap behavior |
| `grow` | `boolean` | `false` | Whether flex items should grow to fill space |
| **Grid Props** |
| `columns` | `number \| string` | `'auto'` | Number of columns or custom grid template |
| `rows` | `number \| string` | `'auto'` | Number of rows or custom grid template |
| `minColumnWidth` | `string` | - | Minimum column width for auto-fit grids |
| `columnGap` | `SpacingSize \| number` | - | Column gap (overrides gap for grid) |
| `rowGap` | `SpacingSize \| number` | - | Row gap (overrides gap for grid) |
| **Common Props** |
| `fullWidth` | `boolean` | `false` | Take full width |
| `fullHeight` | `boolean` | `false` | Take full height |
| `center` | `boolean` | `false` | Center the container horizontally |
| `as` | `string` | `'div'` | HTML element to render as |
| `className` | `string` | - | Additional CSS class |
| `style` | `CSSProperties` | - | Inline styles |

### SpacingSize

Spacing sizes can be: `'none'`, `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'2xl'`, `'3xl'`, or a number (in pixels).

## Examples

### Basic Flexbox Layout

```tsx
// Horizontal layout with gap
<SimpleLayout gap="md" padding="lg">
  <Card>Card 1</Card>
  <Card>Card 2</Card>
  <Card>Card 3</Card>
</SimpleLayout>

// Vertical layout
<SimpleLayout direction="column" gap="sm">
  <Header />
  <Content />
  <Footer />
</SimpleLayout>

// Centered content
<SimpleLayout align="center" justify="center" fullHeight>
  <LoginForm />
</SimpleLayout>

// Space between items
<SimpleLayout justify="between" padding="md">
  <Logo />
  <Navigation />
  <UserMenu />
</SimpleLayout>
```

### Grid Layouts

```tsx
// 3-column grid
<SimpleLayout type="grid" columns={3} gap="lg">
  {items.map(item => <Card key={item.id} {...item} />)}
</SimpleLayout>

// Responsive auto-fit grid
<SimpleLayout 
  type="grid" 
  columns="auto" 
  minColumnWidth="250px" 
  gap="md"
>
  {products.map(product => <ProductCard key={product.id} {...product} />)}
</SimpleLayout>

// Custom grid template
<SimpleLayout 
  type="grid" 
  columns="200px 1fr 200px" 
  gap="lg"
>
  <Sidebar />
  <MainContent />
  <Aside />
</SimpleLayout>

// Grid with different row and column gaps
<SimpleLayout 
  type="grid" 
  columns={4} 
  columnGap="xl" 
  rowGap="sm"
>
  {items.map(item => <Item key={item.id} {...item} />)}
</SimpleLayout>
```

### Spacing Examples

```tsx
// Using predefined spacing sizes
<SimpleLayout gap="lg" padding="xl" margin="md">
  <Content />
</SimpleLayout>

// Using numeric values (pixels)
<SimpleLayout gap={24} padding={32} margin={16}>
  <Content />
</SimpleLayout>

// Mixed spacing
<SimpleLayout gap="lg" padding={20}>
  <Content />
</SimpleLayout>
```

### Nested Layouts

```tsx
<SimpleLayout direction="column" fullHeight>
  <SimpleLayout as="header" padding="md" justify="between">
    <Logo />
    <Navigation />
  </SimpleLayout>
  
  <SimpleLayout as="main" style={{ flex: 1 }}>
    <SimpleLayout as="aside" direction="column" style={{ width: '200px' }}>
      <Menu />
    </SimpleLayout>
    
    <SimpleLayout direction="column" gap="lg" padding="lg" style={{ flex: 1 }}>
      <SimpleLayout type="grid" columns={3} gap="md">
        <StatCard />
        <StatCard />
        <StatCard />
      </SimpleLayout>
      
      <Content />
    </SimpleLayout>
  </SimpleLayout>
  
  <SimpleLayout as="footer" padding="md">
    <FooterContent />
  </SimpleLayout>
</SimpleLayout>
```

### Semantic HTML Elements

```tsx
<SimpleLayout as="section" direction="column" gap="lg">
  <SimpleLayout as="header">
    <h1>Page Title</h1>
  </SimpleLayout>
  
  <SimpleLayout as="article" padding="md">
    <p>Article content...</p>
  </SimpleLayout>
  
  <SimpleLayout as="footer">
    <p>Footer information</p>
  </SimpleLayout>
</SimpleLayout>
```

### Responsive Behavior

The component includes built-in responsive behavior:
- On mobile (< 640px): Flex rows become columns, grids become single column
- On tablet (641px - 1024px): Grid columns are reduced proportionally

## Styling

The component uses CSS modules with CSS custom properties for theming. You can override the default spacing values:

```css
:root {
  --ui-spacing-xs: 0.25rem;
  --ui-spacing-sm: 0.5rem;
  --ui-spacing-md: 1rem;
  --ui-spacing-lg: 1.5rem;
  --ui-spacing-xl: 2rem;
  --ui-spacing-2xl: 3rem;
  --ui-spacing-3xl: 4rem;
}
```

## Development

To run the component in development mode:

```bash
npm run storybook
```

To run tests:

```bash
npm test
```

To lint the component:

```bash
npm run lint
```