npm package: @pagedotapp/page-layout
Description: PageLayout - A versatile layout component supporting both flexbox and grid layouts with easy spacing and alignment controls
Author: PageStudio
Latest version: 0.0.0-alpha.13

# PageLayout

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

## Installation

```bash
npm install @pagedotapp/page-layout
```

## Usage

```tsx
import { PageLayout } from "@pagedotapp/page-layout"

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

## 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
<PageLayout gap="md" padding="lg">
  <Card>Card 1</Card>
  <Card>Card 2</Card>
  <Card>Card 3</Card>
</PageLayout>

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

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

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

### Grid Layouts

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

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

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

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

### Spacing Examples

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

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

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

### Nested Layouts

```tsx
<PageLayout direction="column" fullHeight>
	<PageLayout as="header" padding="md" justify="between">
		<Logo />
		<Navigation />
	</PageLayout>

	<PageLayout as="main" style={{ flex: 1 }}>
		<PageLayout as="aside" direction="column" style={{ width: "200px" }}>
			<Menu />
		</PageLayout>

		<PageLayout direction="column" gap="lg" padding="lg" style={{ flex: 1 }}>
			<PageLayout type="grid" columns={3} gap="md">
				<StatCard />
				<StatCard />
				<StatCard />
			</PageLayout>

			<Content />
		</PageLayout>
	</PageLayout>

	<PageLayout as="footer" padding="md">
		<FooterContent />
	</PageLayout>
</PageLayout>
```

### Semantic HTML Elements

```tsx
<PageLayout as="section" direction="column" gap="lg">
	<PageLayout as="header">
		<h1>Page Title</h1>
	</PageLayout>

	<PageLayout as="article" padding="md">
		<p>Article content...</p>
	</PageLayout>

	<PageLayout as="footer">
		<p>Footer information</p>
	</PageLayout>
</PageLayout>
```

### 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
```