# Box (w-box)

## Description

Box is a layout component used for separating content areas on a page.

[Warp component reference](https://warp-ds.github.io/docs/components/box/frameworks/elements)

## Usage

Box is a layout component for visually separating a section of content from the surrounding page.

Use `w-box` for grouped content that needs padding, a background, or a border. The component does not add heading structure, spacing between children, or interactive behavior. Those you must provide yourself.

### Basic Box

```html
<w-box aria-labelledby="delivery-heading">
  <h2 id="deliver-heading">Delivery</h2>
  <p>Choose how you want the item delivered.</p>
</w-box>
```

### Visual Treatments

Use one visual treatment at a time:

- `neutral`: a quiet sunken surface for grouped content
- `info`: a subtle information background
- `bordered`: a bordered surface with the default background

```html
<w-box neutral role="none">
  <p>Neutral content area</p>
</w-box>

<w-box info role="none">
  <p>Informational content area</p>
</w-box>

<w-box bordered role="none">
  <p>Bordered content area</p>
</w-box>
```

### Bleed

Use `bleed` when a box sits inside a page gutter but should extend to the container edge on narrow screens. `bleed` is commonly combined with a visual treatment such as `neutral` or `info`.

```html
<w-box neutral bleed aria-labelledby="summary-heading">
  <h2 id="summary-heading">Summary</h2>
  <p>This box extends into the horizontal gutter on narrow screens.</p>
</w-box>
```

## Accessibility

Box wraps its slotted content in a section tag by default which is equivalant to role="region" for the purposes of screen readers.

### Do Not Rely On Visual Treatment Alone

The `info`, `neutral`, `bordered`, and `bleed` properties are visual only. They do not change the meaning of the content for assistive technologies.

Always use headings, text, and semantic HTML inside the box to communicate structure and purpose.

### Landmark Behaviour For Meaningful Sections

By default, w-box behaves as a landmark for screen readers. This means it represents a section of the page that users may want to navigate to directly.

We strongly suggest you provide a heading and an accessible landmark name to ensure that screen readers properly treat it as a landmark.

```html
  <w-box aria-labelledby="delivery-heading">
    <h2 id="delivery-heading">Delivery</h2>
    <p>Choose how you want the item delivered.</p>
  </w-box>
```

If you must use box for a purely visual grouping, set role none:

```html
<w-box role="none">
  <p>This box is only a visual container.</p>
</w-box>
```

## Examples

### Basic

<elements-example>
  
```html
<w-box aria-labelledby="delivery-heading">
  <h2 id="delivery-heading">Delivery</h2>
  <p>Choose how you want the item delivered.</p>
</w-box>
```

</elements-example>

### Neutral

<elements-example>

```html
<w-box neutral aria-labelledby="order-summary-heading">
  <h2 id="order-summary-heading">Order summary</h2>
  <p>Review the item price, delivery, and total before continuing.</p>
</w-box>
```

</elements-example>

### Info

<elements-example>

```html
<w-box info aria-labelledby="good-to-know-heading">
  <h2 id="good-to-know-heading">Good to know</h2>
  <p>You can change the delivery method before payment.</p>
</w-box>
```

</elements-example>

### Bordered

<elements-example>

```html
<w-box bordered aria-labelledby="contact-seller-heading">
  <h2 id="contact-seller-heading">Contact seller</h2>
  <p>Send a message to ask about pickup times.</p>
</w-box>
```

</elements-example>

### Bleed

<elements-example>

```html
<div style="padding: 0 16px;">
  <w-box neutral bleed aria-labelledby="summary-heading">
    <h2 id="summary-heading">Summary</h2>
    <p>This box extends into the horizontal gutter on narrow screens.</p>
  </w-box>
</div>
```

</elements-example>


### Visual Grouping Without Accessibility Landmarking

<elements-example>

```html
<w-box role="none">
  <p>This box is only a visual container.</p>
</w-box>
```

</elements-example>

## Styling API

## `<w-box>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| bleed | `boolean` | `false` | Makes the box bleed to the container edge. |
| bordered | `boolean` | `false` | Shows the box as a bordered surface. |
| info | `boolean` | `false` | Shows the box with information styling. |
| neutral | `boolean` | `false` | Shows the box with neutral styling. |
| role | `string` | `"region"` | ARIA role for the box wrapper. |

### Property Details

#### bleed

Makes the box bleed to the container edge.
Extends the box into the horizontal gutter on narrow screens. Adds negative horizontal margins and square side corners below the small breakpoint, then restores the normal margins and rounded corners from the small breakpoint and up.

- Type: `boolean`
- Default: `false`

#### bordered

Shows the box as a bordered surface.
Use this when the content needs a clear visual boundary from the surrounding page.

- Type: `boolean`
- Default: `false`

#### info

Shows the box with information styling.
Use this for supporting informational content that should be visually separated from the surrounding page.

- Type: `boolean`
- Default: `false`

#### neutral

Shows the box with neutral styling.
Use this for quiet grouped content that needs a background without strong emphasis.

- Type: `boolean`
- Default: `false`

#### role

ARIA role for the box wrapper.
Defaults to a role of `region`. Set `role="none"` to override this behaviour for purely visual grouping, or set a specific role when the box has a clearer semantic purpose.

- Type: `string`
- Default: `"region"`

