# Layout

![npm](https://img.shields.io/npm/dt/@asphalt-react/layout?style=flat-square)
[![npm version](https://badge.fury.io/js/@asphalt-react%2Flayout.svg)](https://badge.fury.io/js/@asphalt-react%2Flayout)

The Layout component provides a flexible and composable way to structure your application's pages using semantic sections and responsive layouts. It includes helpers for common page areas (Header, Aside, Main, Footer) and a powerful layout system for arranging content.

## Usage

```jsx
import { Page, Layout } from '@asphalt-react/layout'
import { Appbar } from '@asphalt-react/appbar'
import { Logo } from '@asphalt-react/logo'

<Page>
  <Page.Header>
    <Appbar head={<Logo />} />
  </Page.Header>
  <Page.Main>
    <Layout>
      content
    </Layout>
  <Page.Main>
  <Page.Footer>
    <Layout>
      Footer content
    </Layout>
  </Page.Footer>
</Page>
```

## Components

### Page & Section

A wrapper for page content, providing consistent styling and structure. This component will arrange the UI based on the layout regions declared in Page Section.

A semantic wrapper for page areas. Use `Page.Header`, `Page.Aside`, `Page.Main`, and `Page.Footer` for common layout regions. Add sections inside the `Page` component to automatically arrange them. Set `semantic` to `true` to render components as <a href="https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/" target="_blank">HTML semantic elements</a>.

Below is an example usage with [Sidebar](./?path=/docs/packages-sidebar--documentation) or [Appbar](./?path=/docs/packages-appbar--documentation). If using both components, ensure that navigation is included in only one—either the sidebar or the appbar.

```jsx
<Page>
  <Page.Header>
    <Appbar head={<Logo />} />
  </Page.Header>
  <Page.Main>
    <Layout>
      content
    </Layout>
  <Page.Main>
  <Page.Footer>
    <Layout>
      footer
    </Layout>
  </Page.Footer>
</Page>
```

### Layout & Slot

Layout component supports both grid and flexbox, with options for gaps, alignment, templates, and breakpoints. This component provides the following layout types:

* **Fluid** — Follows the intrinsic width of its children.
* **Fill** — Distributes available space equally among children.
* **Spread** — Adds equal spacing between child elements.
* **Template** — Arranges children according to a template format.

You can nest a `Layout` component inside another `Layout`. For best results, place the `Layout` inside `Page.Main`, as it relies on container queries that depend on the Main component.

The `Slot` component is designed for use within `Layout`. It lets you specify a container area when used with `<Layout template>`. It also controls the order of items responsively using the `order` prop. The `order` prop can be a single number or an object specifying the order for small (`s`), medium (`m`), and large (`l`) breakpoints.

```jsx
<Page.Main>
  <Layout>
    <Layout.Slot order={{s: -1, m: 1}}></Layout.Slot>
    <Layout.Slot order={-1}></Layout.Slot>
  </Layout>
</Page.Main>
```

## Fluid

This is the default behavior of `Layout`. It arranges child elements horizontally or vertically, following the intrinsic width or height of their content. By default, items will wrap to a new line when there is not enough space.

```jsx
// vertical prop will arrange layout to stack vertically

<Page.Main>
  <Layout vertical>
    <div style={{width: "200px"}}>content...</div>
    <div>content...</div>
  </Layout>
</Page.Main>
```

## Spread

Spread distributes child elements with equal spacing between them. The gap between elements is adjusted automatically.

```jsx
<Layout spread>
  <Button>Login</Button>
  <Button>Forgot Password</Button>
</Layout>
```

## Fill

The fill layout ensures that all child elements expand to fill the available space equally. This is especially useful for repetitive items, such as cards or tiles, that should have uniform sizing regardless of their content. On smaller screens, items will stack vertically and take full width. You can override this behaviour by specifying the number of items per row for each breakpoint (e.g., s={2}, m={4}).

```jsx
// fill the space equally
<Layout fill>
  <div></div>
  <div></div>
  <div></div>
</Layout>

// 2 columns on small screen, 6 columns in medium screen
<Layout fill s={2} m={6}>
  <div></div>
  <div></div>
  <div></div>
  ...
</Layout>
```

## Template

The template layout enables developers to define complex, grid-based arrangements using named areas. Add a line break to indicate new rows. Add a space to indicate new columns. Each child can be assigned to a specific area by setting the `area` prop on the `Slot` component. If the `s` (small) breakpoint is not specified, items will automatically stack vertically and take up 100% width on mobile screens.

```jsx
const template = 
`analytis analytics summary
category consumer summary`;
const templateResponsive = {
  s: `summary summary
  category customers
  analytics analytics`,
  m: `analytics analytics summary
  customers category summary`,
}

<Layout template={template}>
  <Layout.Slot area="analytics"></Layout.Slot>
  <Layout.Slot area="category"></Layout.Slot>
  <Layout.Slot area="consumer"></Layout.Slot>
  <Layout.Slot area="summary"></Layout.Slot>
</Layout>
```

# Layout

[comment]: # "Layout Props"

## Props

### children

React node(s) to render inside the layout container.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | N/A     |

### gap

The gap size between layout items. Accepts 'xs', 's', 'm', 'l', 'xl', '2xl', or '3xl'. The default is 'm'.

| type | required | default |
| ---- | -------- | ------- |
| enum | false    | "m"     |

### responsiveGap

Applies responsive gap values on small screens. The default is false.
Set `responsive=true` in ThemeProvider to enable the responsive tokens.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### align

Align of items along cross-axis: 'start', 'end', 'center', or 'stretch'. Equivalent to CSS align-items.

| type | required | default |
| ---- | -------- | ------- |
| enum | false    | N/A     |

### placement

Placement of items along the main axis: 'start', 'end', or 'center'. Equivalent to CSS justify-content.

| type | required | default |
| ---- | -------- | ------- |
| enum | false    | N/A     |

### spread

Adds equal spacing between items.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### vertical

Applies vertical layout. Only works on default Layout and Spread.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### wrap

Enables wrapping of items. Default is true. Only works on default Layout and Spread.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

### reverseOrder

Reverses the order of children items. Only works on default Layout and Spread.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### fill

Fill available space equally.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### s

Number of columns for small screens (used with fill).

| type   | required | default |
| ------ | -------- | ------- |
| number | false    | N/A     |

### m

Number of columns for medium screens (used with fill).

| type   | required | default |
| ------ | -------- | ------- |
| number | false    | N/A     |

### l

Number of columns for large screens (used with fill).

| type   | required | default |
| ------ | -------- | ------- |
| number | false    | N/A     |

### template

Sets layout template areas, as a string or an object with s/m/l keys.
Use a line break to indicate new rows.
For example: `slot1 slot2 \n slot1 slot2` or
` { s:  `slot1 \n slot2` , m:  `slot1 slot2 \n slot1 slot2`  } `

| type   | required | default |
| ------ | -------- | ------- |
| custom | false    | ""      |

### responsiveLayout

Enables responsive Layout which auto adjusts layout based on screen size.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

# Page

[comment]: # "Page Props"

## Props

### children

Components or elements to be rendered inside the Page.

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

### asideEnd

Aligns Aside component to the end of the container.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |