@chamie/container (working title)

A React container component that lets you define complex grid layouts using ASCII-art-style strings. Stop mentally executing walls of JSX to figure out what your UI looks like — just draw it.

<Container
  order={`
    Title_________|ActionButtons
    ==
    HitsTitle_____|HitsMeter
    TotalLoadTitle|TotalLoadMeter
  `}
  layout={`
    _|
    ==
    _|__
    _|__
  `}
>
  <Header layoutSlot="Title" />
  <ActionButtons layoutSlot="ActionButtons" />
  <div layoutSlot="HitsTitle">Hits:</div>
  <Meter layoutSlot="HitsMeter" />
  <div layoutSlot="TotalLoadTitle">Total Load:</div>
  <Meter layoutSlot="TotalLoadMeter" />
</Container>

---

Install

npm install @chamie/container
# or
yarn add @chamie/container

---

How it works

The Container component renders a flex-based grid. You describe it with two string props:

order (required)

Defines which components go where. Each line is a row, cells are separated by |. Underscores are visual padding and are ignored during parsing.

Title_________|ActionButtons
==
HitsTitle_____|HitsMeter

• | separates cells in a row
• == lines (or any line starting with ==) are ignored — use them as visual separators. Or adding comments, if you feel like those are needed for some reason
• Underscores in component names are stripped, so HitsTitle_____ and HitsTitle resolve to the same slot
• An empty cell (only underscores, no name) renders as a spacer with no matching child required

layout (optional)

Defines the size of each cell, row by row, matching the structure of order. If omitted, cells share space equally.

_|
==
_|__
_|__

Each cell value can be:

Format	Meaning	Example
Underscores	Flex ratio by character count	___ → flex: 3
Plain number	Explicit flex value	5 → flex: 5
CSS size unit	Fixed width	20px, 10%, 4vw

Mixed formats are supported per row:

___|10%|20px

== lines are ignored here too, so you can keep order and layout visually aligned.

layoutSlot prop

Every child that should be placed by the container needs a layoutSlot prop matching the name used in order. Works on any element — custom components, plain <div>s, anything React can render.

<div layoutSlot="HitsTitle">Hits:</div>
<Meter layoutSlot="HitsMeter" value={hits} />

Children without a layoutSlot are ignored.

---

Props

Prop	Type	Required	Description
order	string	✓	ASCII-art slot layout
layout	string		Cell sizing configuration
children	ReactElement[]	✓	Components with layoutSlot props
strict	boolean		Throw on mismatches instead of warning
classNamePrefix	string		Prefix for generated class names (container, row, col)

---

Examples

Equal columns, no layout prop needed

<Container order="Left|Center|Right">
  <Nav layoutSlot="Left" />
  <Main layoutSlot="Center" />
  <Aside layoutSlot="Right" />
</Container>

Fixed sidebar + fluid content

<Container
  order="Sidebar|Content"
  layout="240px|_"
>
  <Sidebar layoutSlot="Sidebar" />
  <Content layoutSlot="Content" />
</Container>

Spacer cells

Empty cells (pure underscores) render as unstyled divs with no child required:

<Container
  order={`
    Logo___|_|NavLinks
  `}
  layout={`
    __|_|__
  `}
>
  <Logo layoutSlot="Logo" />
  <NavLinks layoutSlot="NavLinks" />
  {/* middle cell is a spacer, no child needed */}
</Container>

Nesting

And of course you can nest them if you want a more complex layout:

<Container order="Sidebar|Main">
    <Sidebar layoutSlot="Sidebar" />

    <Container layoutSlot="Main"
        order={`
            Header
            Content
        `}
    >
        <Header layoutSlot="Header" />
        <Content layoutSlot="Content" />
    </Container>
</Container>

Compile-time slot name safety

If you want typos caught by TypeScript:

const slots = {
  Title: "Title",
  Actions: "Actions",
  Chart: "Chart",
} as const;

<Container
  order={`
    ${slots.Title}__|${slots.Actions}
    ==
    ${slots.Chart}
  `}
>
  <Header layoutSlot={slots.Title} />
  <Toolbar layoutSlot={slots.Actions} />
  <Chart layoutSlot={slots.Chart} />
</Container>

---

Error handling

By default, mismatches warn to the console and render a red Missing: SlotName placeholder in place of the absent child.

Pass strict to throw instead — useful for catching layout/child mismatches at development time:

<Container order="A|B" strict>
  <A layoutSlot="A" />
  {/* B missing → throws */}
</Container>

---

CSS classes

The container generates three class names, optionally prefixed via classNamePrefix:

Element	Default class	With classNamePrefix="my"
Root div	container	my-container
Row div	row	my-row
Cell div	col	my-col

---

License

MIT