Layout System

The layout system in Dashbrew allows you to organize your dashboard components in a flexible, responsive manner. Understanding how layouts work is key to creating well-structured dashboards that adapt to different terminal sizes.

Layout Structure

Dashbrew uses a nested layout structure consisting of containers and components:

Dashboard
└── Root Container
    ├── Container 1
    │   ├── Component A
    │   └── Component B
    └── Container 2
        ├── Container 2.1
        │   └── Component C
        └── Component D

Every dashboard has a root container defined in the layout field of your configuration file. Inside this container, you can place components directly or nest additional containers to create complex layouts.

Basic Layout Example

{
  "layout": {
    "type": "container",
    "direction": "row",
    "children": [
      {
        "type": "component",
        "component": {
          "type": "text",
          "title": "Left Panel"
        }
      },
      {
        "type": "component",
        "component": {
          "type": "text",
          "title": "Right Panel"
        }
      }
    ]
  }
}

This creates a simple two-panel layout with components side by side.

Container Types

Dashbrew supports two primary container types:

1. Root Contaienr

The top-level container that holds your entire dashboard. This must be specified in the layout field of your configuration:

{
  "layout": {
    "type": "container",
    "direction": "column",
    "children": [
      // Components or nested containers
    ]
  }
}

2. Nested Containers

Containers inside other containers that allow for complex layouts:

{
  "type": "container",
  "direction": "row", 
  "flex": 2,
  "children": [
    // Components or more nested containers
  ]
}

Container Properties

Each container has these key properties:

Property	Description	Values
type	Must be "container"	"container"
direction	How children are arranged	"row" or "column"
flex	Relative size	Integer (1, 2, 3, etc.)
children	Array of components or containers	Array

Direction

The direction property determines how children are arranged within a container:

• row: Children are placed horizontally, from left to right
• column: Children are placed vertically, from top to bottom

Row Container Example

{
  "type": "container",
  "direction": "row",
  "children": [
    // Components/containers arranged horizontally
  ]
}

Column Container Example

{
  "type": "container",
  "direction": "column",
  "children": [
    // Components/containers arranged vertically
  ]
}

Flex Sizing

The flex property determines how components and containers share available space relative to each other. The higher the flex value, the more space that element will take up compared to its siblings.

How Flex Works

• Each sibling (component or container) can specify a flex value (default is 1)
• Available space is distributed proportionally based on these values
• Elements with higher flex values get more space

For example, if three siblings have flex values of 1, 2, and 1 respectively:

• The first gets 1/4 (1/(1+2+1)) of the available space
• The second gets 2/4 (2/(1+2+1)) of the available space
• The third gets 1/4 (1/(1+2+1)) of the available space

Flex Example

{
  "layout": {
    "type": "container",
    "direction": "column",
    "children": [
      {
        "type": "component",
        "flex": 1,  // Takes 1/4 of vertical space
        "component": {
          "type": "text",
          "title": "Header"
        }
      },
      {
        "type": "container",
        "direction": "row",
        "flex": 3,  // Takes 3/4 of vertical space
        "children": [
          {
            "type": "component",
            "flex": 1,  // Takes 1/3 of horizontal space within its container
            "component": {
              "type": "list",
              "title": "Sidebar"
            }
          },
          {
            "type": "component",
            "flex": 2,  // Takes 2/3 of horizontal space within its container
            "component": {
              "type": "chart",
              "title": "Main Content"
            }
          }
        ]
      }
    ]
  }
}

Common Layout Patterns

Split Screen Layout

{
  "layout": {
    "type": "container",
    "direction": "row",
    "children": [
      {
        "type": "component",
        "flex": 1,
        "component": { "type": "text", "title": "Left Panel" }
      },
      {
        "type": "component",
        "flex": 1,
        "component": { "type": "text", "title": "Right Panel" }
      }
    ]
  }
}

Grid Layout

{
  "layout": {
    "type": "container",
    "direction": "column",
    "children": [
      {
        "type": "container",
        "direction": "row",
        "flex": 1,
        "children": [
          {
            "type": "component",
            "flex": 1,
            "component": { "type": "text", "title": "Top Left" }
          },
          {
            "type": "component",
            "flex": 1,
            "component": { "type": "text", "title": "Top Right" }
          }
        ]
      },
      {
        "type": "container",
        "direction": "row",
        "flex": 1,
        "children": [
          {
            "type": "component",
            "flex": 1,
            "component": { "type": "text", "title": "Bottom Left" }
          },
          {
            "type": "component",
            "flex": 1,
            "component": { "type": "text", "title": "Bottom Right" }
          }
        ]
      }
    ]
  }
}

Main + Sidebar Layout

{
  "layout": {
    "type": "container",
    "direction": "row",
    "children": [
      {
        "type": "component",
        "flex": 1,
        "component": { "type": "list", "title": "Sidebar" }
      },
      {
        "type": "component",
        "flex": 3,
        "component": { "type": "text", "title": "Main Content" }
      }
    ]
  }
}

Tips for effective Layouts

• Start simple: Begin with a basic layout and gradually add complexity
• Use nested containers: Create sophisticated layouts by nesting row and column containers
• Consider terminal size: Remember that your dashboard needs to work in different terminal dimensions
• Balance flex values: Use meaningful flex proportions (e.g., 1:3 ratio for sidebar:main)
• Group related components: Place related components in the same container