# Layout & Structure Components

> Components: DCard, DBox, DLayout, DLayoutPane, DContainer, DRow, DCol

---

## DCard

```tsx
<DCard>
  <DCard.Header><h5>Title</h5></DCard.Header>
  <DCard.Body>Content</DCard.Body>
  <DCard.Footer><DButton text="Action" /></DCard.Footer>
</DCard>
```

---

## DBox

> Flex box utility component — **Coming Soon**

Props: `direction` (`'row'|'column'`), `align` (`'start'|'center'|'end'`), `justify` (`'start'|'center'|'end'|'between'|'around'`), `gap`, `className`.

```tsx
<DBox direction="row" justify="between" align="center">
  <div>Left</div><div>Right</div>
</DBox>
```

---

## DLayout / DLayoutPane

> ✨ NEW in v2.0 - Bootstrap Grid CSS layout system

**Purpose:** Create 12-column grid layouts with responsive panes for multi-column arrangements.

### When to Use DLayout

- Dashboard layouts with sidebars
- Multi-column content arrangements
- Responsive 12-column grid layouts
- Complex page structures with varying column widths

### Props

**DLayout:** `gap` (0-5), `children`, `className`, `style`

**DLayout.Pane:** `cols` (1-12), `colsXs`/`colsSm`/`colsMd`/`colsLg`/`colsXl`/`colsXxl` (responsive), `children`, `className`, `style`

### Usage

```tsx
import { DLayout } from '@dynamic-framework/ui-react';

// Basic two-column layout (8/4 split of 12 columns)
<DLayout gap={3}>
  <DLayout.Pane cols={8}>
    <DCard>
      <DCard.Body>Main content area</DCard.Body>
    </DCard>
  </DLayout.Pane>
  <DLayout.Pane cols={4}>
    <DCard>
      <DCard.Body>Sidebar</DCard.Body>
    </DCard>
  </DLayout.Pane>
</DLayout>

// Responsive: stacks on mobile, side-by-side on desktop
<DLayout gap={3}>
  <DLayout.Pane cols={12} colsLg={8}><DCard>Main content</DCard></DLayout.Pane>
  <DLayout.Pane cols={12} colsLg={4}><DCard>Sidebar</DCard></DLayout.Pane>
</DLayout>
```

### Common Patterns

- **Dashboard**: 8/4 split — main chart + sidebar stats
- **Master-Detail**: 4/8 split — list on left, detail on right
- **Three-Column**: 3/6/3 split

### Notes

- Uses CSS Grid (`g-col-*`), 12-column system. Cols must add up to 12 or less.
- Access pane via `DLayout.Pane` (subcomponent pattern, not separate import).

---

## DContainer, DRow, DCol

> **Planned but not yet available in Dynamic UI.** Use DLayout/DLayout.Pane or Bootstrap grid classes (`row`/`col-*`) instead.

---

## Best Practices

### Breakpoints
```
xs: 0-575px | sm: 576-767px | md: 768-991px | lg: 992-1199px | xl: 1200px+
```

### Key Rules
- Column spans must add up to 12 (or less)
- Use `gap` on parent, not margins on columns
- Mobile-first: `cols={12} colsLg={8}` for responsive

### Common Layout Patterns

- **Dashboard**: DLayout 8/4 split (main + sidebar), stack on mobile with `cols={12} colsLg={8}`
- **Card grid**: Use DLayout.Pane with responsive cols per card
- **Key on wrapper**: Put `key={item.id}` on the outer wrapper, not on DCard

---

## DCollapse

Collapsible content container. **Controlled component** — you MUST manage state.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `collapsed` | `boolean` | Yes | Controlled collapsed state |
| `onChange` | `(collapsed: boolean) => void` | Yes | State change handler |
| `children` | `ReactNode` | Yes | Content to show/hide |
| `className` | `string` | No | Additional CSS classes |

### Usage

```tsx
const [collapsed, setCollapsed] = useState(false);

<DCollapse collapsed={collapsed} onChange={setCollapsed}>
  <div className="p-3 border mt-2">Collapsible content</div>
</DCollapse>
```

### Patterns

- **Accordion:** Track `openIndex` in state, toggle: `setOpenIndex(openIndex === i ? null : i)`
- **Multiple sections:** Object state `{ filters: false, recent: false }`, toggle per key
- **Zustand:** Store `collapsedSections: Record<string, boolean>` with `toggleSection(key)` action

### Common Mistakes

```tsx
// ❌ No state — won't work
<DCollapse>Content</DCollapse>
// ❌ Single state for multiple sections — all toggle together
// ❌ collapsed={open} — inverted logic, should be collapsed={!open}

// ✅ Each section needs its own state entry
<DCollapse collapsed={collapsed.section1}
  onChange={(c) => setCollapsed(p => ({ ...p, section1: c }))} />
```

---

**End of Layout Components Reference**