Box

Import

import { Box } from '@envsemble/envui';

Usage

Box renders a div, or the element in render, such as render={<section />}, which takes its attributes.

padding sets its inset on every side, a step of the spacing scale, none by default.
name names the region for dev mode and agents, as data-env-name.

InsetRegion.tsx

import { Box, Button, Column, Text } from '@envsemble/envui';

export default function InsetRegion() {
  return (
    // A named region with an inset and nothing else: no fill, no border, no gaps of its own.
    <Box name="invitation" padding={5} render={<section aria-labelledby="invitation-heading" />}>
      <Column gap={3} align="start">
        <Text render={<h3 />} variant="title" id="invitation-heading">
          Invite your team
        </Text>
        <Text>Projects are easier with the people who work on them.</Text>
        <Button variant="secondary">Invite people</Button>
      </Column>
    </Box>
  );
}

Size container

container="summary" makes the box a size container that the application's style sheet can query, such as @container summary (width >= 37.5rem).

A container is as wide as its context gives it, never as its content, so give one in a flex row a width of its own.
The env-* container names are envUI's own. Use container="env-window" only for a preview frame whose content should lay out at the box's width, as a window of its own.

<Box container="summary">
  <Grid columns="repeat(auto-fit, minmax(min(100%, 9rem), 1fr))" gap={4}>
    {figures.map(([label, value]) => (
      <Column key={label} gap={1}>
        <Text variant="body-sm" emphasis="muted">
          {label}
        </Text>
        <Text variant="headline">{value}</Text>
      </Column>
    ))}
  </Grid>
</Box>

@container summary (width >= 37.5rem) {
  /* The application's own rules for a wide summary. */
}

Composition

Put one inset on the region and a Column, Row or Grid inside it for the gaps, rather than a padded box around each child. Box has no fill, border or corners: a Surface has them.

Accessibility

You provide

A heading and a name for a box that is a region, such as aria-labelledby on a section.

envUI provides

A div with no role of its own, or the element in render, such as render={<section />}.
No keys, focus or announcements of its own.

Props

A plain block for what needs no row or column of its own: an inset (`padding`), a size container (`container`) or a named node. It sizes to its content and never paints.

Prop	Type	Description
`render`	`ReactElement`	The element to render, for its meaning, such as render={<section />} or render={<ul />}, or another component to lay out without a wrapper, such as a Surface: the primitive's attributes merge into its props. It must forward native props and refs. A div by default.
`ref`	`Ref<RenderedElement>`	The rendered element, a div by default. Its type is the element type parameter, which a ref passed in sets: a ref to the element that render makes, such as useRef<HTMLElement>(null) with render={<section />}, type-checks.
`name`	`string`	A name for this node, such as "filters" or "summary", which dev mode and the docs show; it renders as `data-env-name`. A component's part class names its node instead.
`container`	`string`	Makes the element a size container of this name, for container queries on its inline size, such as container="filters" for `@container filters (width >= 37.5rem)`. A container is as wide as its context gives it, never as its content. container="env-window" makes the element a window of its own on purpose, such as a preview frame, whose content lays out at its window class; other `env-*` names are envUI's own.
`padding`	`0123456789`	The inset on every side, a step of the spacing scale. None by default.

Also accepts the native props of <div>, such as ref, className and aria-* attributes.

Changelog

1.0.0: Box, with Row, Column and Grid, the layout primitives.