Layout overview

Layout — higher-level layout combinators built on top of Box.

Provides container-aware composition primitives inspired by CSS Flexbox:

Flex.row / Flex.col distribute space among children proportionally
Container.make passes available dimensions to child builders
Grid.make / Grid.auto arrange items in fixed-column grids

All helpers are pure functions that return standard Box values, composable with existing Box primitives (border, annotate, pad, etc).

combinators

Container

Provides container dimensions to a child builder function. Automatically computes inner dimensions after padding, enforces width on the output, and applies padding.

Signature

export declare const Container: {
  readonly make: <A>(options: Container.Options, builder: (ctx: Container.Context) => Box.Box<A>) => Box.Box<A>
}

Flex

Distributes space among children using a flexbox-style algorithm.

Fixed children keep their intrinsic size. Grow and Fill children share remaining space proportionally based on their factor. Remainder columns are distributed one each to the first N grow children to avoid rounding gaps.

If fixed children exceed the container size, grow children receive 0 space and the result may be wider/taller than the container. Compose with Box.maxWidth to enforce hard limits.

Signature

export declare const Flex: {
  readonly fixed: <A>(box: Box.Box<A>) => Flex.Child<A>
  readonly grow: <A>(box: Box.Box<A>, factor?: number) => Flex.Child<A>
  readonly fill: <A>(builder: (size: number) => Box.Box<A>, factor?: number) => Flex.Child<A>
  readonly spacer: (factor?: number) => Flex.Child<never>
  readonly row: ((
    containerWidth: number,
    options?: Flex.Options
  ) => <A>(self: ReadonlyArray<Flex.Child<A>>) => Box.Box<A>) &
    (<A>(self: ReadonlyArray<Flex.Child<A>>, containerWidth: number, options?: Flex.Options) => Box.Box<A>)
  readonly col: ((
    containerHeight: number,
    options?: Flex.Options
  ) => <A>(self: ReadonlyArray<Flex.Child<A>>) => Box.Box<A>) &
    (<A>(self: ReadonlyArray<Flex.Child<A>>, containerHeight: number, options?: Flex.Options) => Box.Box<A>)
}

Example

import { pipe } from "effect"
import * as Box from "effect-boxes/Box"
import { Flex } from "effect-boxes/Layout"
 
// Data-first
const row = Flex.row([Flex.fixed(Box.text("Name:")), Flex.spacer(), Flex.fixed(Box.text("[ok]"))], 80)
 
// Data-last (pipe)
const row2 = pipe(
  [Flex.fixed(Box.text("Name:")), Flex.grow(Box.text("value"), 2), Flex.fixed(Box.text("[ok]"))],
  Flex.row(80, { gap: 1 })
)

Grid

Arranges items in rows and columns with uniform column width.

Signature

export declare const Grid: {
  readonly make: ((options: Grid.Options) => <A>(self: ReadonlyArray<Box.Box<A>>) => Box.Box<A>) &
    (<A>(self: ReadonlyArray<Box.Box<A>>, options: Grid.Options) => Box.Box<A>)
  readonly auto: ((
    containerWidth: number,
    options: Grid.AutoOptions
  ) => <A>(self: ReadonlyArray<Box.Box<A>>) => Box.Box<A>) &
    (<A>(self: ReadonlyArray<Box.Box<A>>, containerWidth: number, options: Grid.AutoOptions) => Box.Box<A>)
}

models

Container (namespace)

Context (interface)

Context passed to a container builder function with computed inner dimensions after padding.

Signature

export interface Context {
  readonly width: number
  readonly height: number
  readonly innerWidth: number
  readonly innerHeight: number
}

Options (interface)

Options for creating a container.

Signature

export interface Options {
  readonly width: number
  readonly height?: number
  readonly padding?: number | readonly [number, number]
}

Flex (namespace)

Fill (interface)

A flex child that fills remaining space via a builder function.

Signature

export interface Fill<A = never> {
  readonly _tag: "Fill"
  readonly builder: (size: number) => Box.Box<A>
  readonly factor: number
}

Fixed (interface)

A flex child that occupies its intrinsic width/height.

Signature

export interface Fixed<A = never> {
  readonly _tag: "Fixed"
  readonly box: Box.Box<A>
}

Grow (interface)

A flex child that grows to fill remaining space proportionally.

Signature

export interface Grow<A = never> {
  readonly _tag: "Grow"
  readonly box: Box.Box<A>
  readonly factor: number
}

Options (interface)

Options for flex row/col layout.

Signature

export interface Options {
  readonly align?: Box.Alignment
  readonly gap?: number
}

Child (type alias)

A child element in a flex layout.

Signature

export type Child<A = never> = Fixed<A> | Grow<A> | Fill<A>

Grid (namespace)

AutoOptions (interface)

Options for auto-column grid layout.

Signature

export interface AutoOptions {
  readonly minColWidth: number
  readonly maxColWidth?: number
  readonly gap?: number
  readonly align?: Box.Alignment
  readonly stretch?: boolean
}

Options (interface)

Options for fixed-column grid layout.

Signature

export interface Options {
  readonly cols: number
  readonly colWidth: number
  readonly gap?: readonly [number, number]
  readonly align?: Box.Alignment
  readonly stretch?: boolean
}