npm package: @psp-asia/layout
Description: Layout and debug tools for PSP development with TailwindCSS
Latest version: 1.1.2

# @psp-asia/layout - PSP Layout & Debug Tools

Complete layout and debugging system for PSP development with TailwindCSS integration.

## Package Contents

### Layout System (`grid.css`)
- **Rack**: CSS Grid container with responsive track system
- **Rail**: Horizontal scroll container with fixed-width columns

### Debug Tools (`debug.css`, `debug.js`)
- Visual debugging overlay for grid layouts
- Territory lines and viewport controls
- Development-only utilities

## Installation

```bash
npm install @psp-asia/layout
```

## Usage

### Basic Layout Import
```css
@import "@psp-asia/layout/grid.css";
```

### Development with Debug Tools
```html
<!-- CSS -->
<link rel="stylesheet" href="/npm/@psp-asia/layout/grid.css">
<link rel="stylesheet" href="/npm/@psp-asia/layout/debug.css">

<!-- JS -->
<script src="/npm/@psp-asia/layout/debug.js"></script>
```

## Rack System (CSS Grid)

### Responsive Track System
- **sm (default)**: 4 tracks
- **md (48rem+)**: 14 tracks  
- **lg (64rem+)**: 24 tracks

### Column Classes
```css
.col-1 through .col-12  /* Responsive column spans */
.col-start-N            /* Grid positioning */
```

### Examples
```html
<div class="rack">
  <div class="col-6">Half width</div>
  <div class="col-6">Half width</div>
</div>

<div class="rack">
  <div class="col-start-2 col-10">Centered content</div>
</div>
```

## Rail System (Horizontal Scroll)

### Fixed Width Columns
```css
.col-1  → 16rem (256px)
.col-2  → 20rem (320px)
.col-3  → 24rem (384px)
/* ... up to .col-12 → 100% */
```

### Examples
```html
<div class="rail">
  <div class="col-3">Card 1</div>
  <div class="col-3">Card 2</div>
  <div class="col-3">Card 3</div>
</div>
```

## Debug Tools

### Features
- Visual grid overlay
- Territory line indicators
- Viewport size display
- Development-only activation

### Activation
The debug tools activate automatically in development environments and provide visual feedback for layout debugging.

## File Structure

```
@psp-asia/layout/
├── grid.css    # Main layout system
├── debug.css   # Debug visual styles
└── debug.js    # Debug functionality
```

## Browser Support
- Modern browsers with CSS Grid support
- Flexbox fallback for older browsers
- Progressive enhancement approach

# @psp-asia/layout System Guide

## Core Understanding

The @psp-asia/layout system uses **semantic grid classes** that automatically adapt to screen sizes. **Never use responsive prefixes** like `lg:`, `md:`, `sm:` - the system handles breakpoints internally.

## Container Types

### 1. Rack Container
- **Purpose**: Responsive grid that wraps columns to new lines
- **Behavior**: Automatically adjusts column spans based on screen size
- **Usage**: Use for main content layouts, sections, cards

```html
<div class="rack">
  <div class="col-6">Half width content</div>
  <div class="col-6">Other half content</div>
</div>
```

### 2. Rail Container
- **Purpose**: Horizontal scrolling container
- **Behavior**: Columns scroll horizontally, never wrap
- **Usage**: Use for image galleries, carousels, timeline views

```html
<div class="rail">
  <div class="col-3">Card 1</div>
  <div class="col-3">Card 2</div>
  <div class="col-3">Card 3</div>
</div>
```

## Column System

### Basic Columns (col-1 to col-12)
- **col-1**: Smallest column (1/12 semantic width)
- **col-6**: Half width (6/12 semantic width)
- **col-12**: Full width (12/12 semantic width)

**How it actually works:**
- **Mobile (sm)**: 4 physical grid tracks
    - `col-1`, `col-2` = 2 tracks each
    - `col-3` to `col-12` = 4 tracks (full width)
- **Tablet (md)**: 14 physical grid tracks
    - `col-1` to `col-4` = 6 tracks each
    - `col-5`, `col-6` = 10 tracks each
    - `col-7` to `col-12` = 14 tracks (full width)
- **Desktop (lg)**: 24 physical grid tracks
    - `col-1` = 2 tracks, `col-2` = 4 tracks, etc.
    - `col-12` = 24 tracks (full width)

### Positioning with Offsets
Use `offset-N` + `col-M` together for positioning:

```html
<div class="rack">
  <div class="offset-2 col-8">Centered content (2 + 8 + 2 = 12)</div>
  <div class="offset-3 col-6">Smaller centered (3 + 6 + 3 = 12)</div>
</div>
```

## Common Patterns

### Full Width Section
```html
<div class="rack">
  <div class="col-12">
    <!-- Full width content -->
  </div>
</div>
```

### Two Column Layout
```html
<div class="rack">
  <div class="col-8">Main content</div>
  <div class="col-4">Sidebar</div>
</div>
```

### Three Column Layout
```html
<div class="rack">
  <div class="col-4">Column 1</div>
  <div class="col-4">Column 2</div>
  <div class="col-4">Column 3</div>
</div>
```

### Centered Content
```html
<div class="rack">
  <div class="offset-3 col-6">Centered content</div>
</div>
```

### Card Grid
```html
<div class="rack">
  <div class="col-3">Card 1</div>
  <div class="col-3">Card 2</div>
  <div class="col-3">Card 3</div>
  <div class="col-3">Card 4</div>
</div>
```

### Horizontal Scrolling Gallery
```html
<div class="rail">
  <div class="col-3">Image 1</div>
  <div class="col-3">Image 2</div>
  <div class="col-3">Image 3</div>
  <div class="col-3">Image 4</div>
  <div class="col-3">Image 5</div>
</div>
```

## Critical Rules

1. **NO responsive prefixes**: Never use `lg:col-6`, `md:col-4`, etc.
2. **Container required**: Always wrap `col-*` inside `rack` or `rail`
3. **Semantic sizing**: Think in terms of 12-column layout, system handles physical tracks
4. **Offset for positioning**: Use `offset-N` for gaps and centering
5. **Rail for horizontal**: Use `rail` only when you want horizontal scrolling

## Ruby Helpers (Optional)

If using Ruby/ERB, you can create helpers:

```ruby
def rack_container(&block)
  content = capture(&block) if block_given?
  "<div class=\"rack\">#{content}</div>".html_safe
end

def col(size, offset = nil, &block)
  content = capture(&block) if block_given?
  css_classes = ["col-#{size}"]
  css_classes << "offset-#{offset}" if offset
  "<div class=\"#{css_classes.join(' ')}\">#{content}</div>".html_safe
end
```

Usage:
```erb
<%= rack_container do %>
  <%= col(6) do %>Content 1<% end %>
  <%= col(6) do %>Content 2<% end %>
<% end %>
```

## Anti-Patterns (Don't Do This)

❌ **Using responsive prefixes**
```html
<!-- WRONG -->
<div class="col-12 md:col-6 lg:col-4">Content</div>
```

❌ **Missing container**
```html
<!-- WRONG -->
<div class="col-6">Content</div>
```

❌ **Wrong container for purpose**
```html
<!-- WRONG: Using rail for normal layout -->
<div class="rail">
  <div class="col-12">Full width content</div>
</div>
```

✅ **Correct Usage**
```html
<!-- CORRECT -->
<div class="rack">
  <div class="col-6">Content</div>
</div>
```

The system is designed to be simple: think semantically about your 12-column layout, use `rack` for normal layouts and `rail` for horizontal scrolling, and let the system handle all responsive behavior automatically.