# Layout

Page layout is the consuming site's job. The package ships only the parts whose
behavior is worth writing once: the scroll and snap of a rail, the full-bleed
arithmetic of a band, the pager on a table. None of them needs to know what it
is carrying.

## Showcase carousel

Use it for a larger peer set where showing every item at once would dominate
the page. Controls stay minimal and native horizontal scrolling stays
available.

The rail never sees its cards' data. `tabs` is one label per card in slot
order, and the script matches a tab to a card by position among the track's
children. Slot whatever card you like; the rail sizes it.

Compile the model

The feature variant leads with a large media block and sets the text below
it, so use it where the carousel is the main event on the page.

Measure what it costs

Cards are about three quarters of the track width, so the next one is
always visible at its edge.

Put it on the device

The previous and next controls disable at the ends of the track, and the
active tab follows the first card at or past the visible left edge.

## The compact variant

`variant="compact"` is text-forward. The whole card is one bordered surface,
the media becomes a short band at the top, and cards drop to about a third of
the width so three read at once on a desktop viewport. Use it for update feeds
and other secondary sections.

A shorter card

One paragraph is the right length here.

Three at a time

The rail still scrolls past the third.

Same part, other shape

Only the variant changed, not the cards.

Fourth card

Enough to make the track overflow on a desktop.

## Sizing is the rail's

The track sets `--carousel-card-basis` and applies the flex basis and the
scroll-snap alignment to its own children, so a slotted card needs no carousel
knowledge at all. A card that wants a different width can still set its own
`flex` and win on specificity.

## Section header

Use it for the heading of a page section: the label, the title, the line under
it, and the link to the fuller view, all on one baseline. Everything is a prop
because the trailing link is aligned against the title block, which only works
if the header knows both.

- [Reference designs](https://ambiqai.github.io/helia-ui/layout/#section-header): Boards, sensors, and the models that have been measured on them.

## Editorial band

Use it for a change of ground partway down a long page. The band escapes the
content column so the paint reaches the viewport edges, while the text inside it
stays on the readable measure. Consecutive bands butt together rather than
stacking a gap.

The band is the one part that deliberately breaks out of its container. Give
it an `id` where a nav or a deep link has to reach the section.

## Data table

Use it for a set of values that has to be read across rows. Cells are strings:
the pager hides rows by index and the frame sizes columns from their text, and
neither survives arbitrary markup. `pageSize` is the only behavior, and it is
progressive, so every row is in the document without scripting.