Components

Components are the building blocks of your Dashbrew dashboard. Each component represents a specific visualization or interaction type, allowing you to display and interact with different kinds of data.

Component Overview

Dashbrew currently supports the following component types:

Component Type	Description	Interactive	Add Support
text	Displays text content with scrolling	Yes	No
list	Shows items in a scrollable list	Yes	No
todo	Interactive todo list with completion tracking	Yes	Yes
chart	Line charts for numerical data	Yes	No
table	Tabular data with columns	Yes	No
histogram	Bar chart for distribution data	Yes	No

Common Properties

All components share these base properties:

{
  "type": "component",
  "component": {
    "type": "TYPE_NAME",  // Required: text, list, todo, chart, table, or histogram
    "title": "Component Title",  // Optional: header text
    "id": "unique-id",  // Optional: custom identifier
    "data": {
      // Data source configuration (varies by component)
    }
  }
}

Data Sources

Most components can fetch data from different sources:

• Script: Run a shell command to get data
• API: Fetch data from a web endpoint
• File: Read data from a local file (primarily for todo component)

"data": {
  "source": "script",  // "script", "api", or file path for todos
  "command": "echo 'hello world'",  // For script source

  "url": "https://api.example.com/data",  // For API source
  "json_path": "$.data.items",  // Optional: extract specific JSON data

  "refresh_interval": 10,  // Optional: seconds between refresh
  "caption": "Footer Caption" // Optional: for text and histogram components
}

Text Component

Displays text content with scrolling support.

Data Format

The Text component accepts any plain text. Line breaks in the text create new lines in the display.

Interaction

• Arrow keys or j/k/: Scroll up/down
• Page Up/Down: Scroll by page
• Mouse wheel: Scroll

Examples

API Example:

{
  "type": "component",
  "component": {
    "type": "text",
    "title": "Current Weather",
    "data": {
      "source": "api",
      "url": "https://wttr.in/Yerevan?format=3",
      "refresh_interval": 300
    }
  }
}

File Content Example:

{
  "type": "component",
  "component": {
    "type": "text",
    "title": "Long Text File",
    "data": {
      "source": "script",
      "command": "cat ./dashboard.json",
      "refresh_interval": 5,
      "caption": "dashboard.json content"
    }
  }
}

List Component

The List component displays items in a scrollable, filterable list. It's useful for displaying collections of items, command outputs that generate multiple lines, or API responses.

Data Format

The List component can parse data in these formats from script and api sources:

• Plain text: Each non-empty line becomes a list item
• JSON array: Each array element becomes a list item

Interaction

• Arrow keys or j/k/: Scroll up/down
• g/G: Scroll to Top/Bottom
• /: Filter list items
• Escape: Exit filter mode

Examples

API Example

{
  "type": "component",
  "component": {
    "type": "list",
    "title": "User Names",
    "data": {
      "source": "api",
      "url": "https://jsonplaceholder.typicode.com/users",
      "json_path": "$[*].name"
    }
  }
}

Command Output Example

{
  "type": "component",
  "component": {
    "type": "list",
    "title": "Directory Listing",
    "data": {
      "source": "script",
      "command": "ls -la | tail -n +2"
    }
  }
}

ToDo Component

The Todo component provides an interactive task list with support for adding new items and toggling completion status. Tasks are stored in a text file.

Data Format

Todo data is stored in a simple text file:

• Lines starting with - are incomplete tasks
• Lines starting with + are completed tasks
• Example:

  - Buy groceries (incomplete)
  + Clean room (completed)
  

Interaction

• Arrow keys or j/k/: Scroll up/down
• g/G: Scroll to Top/Bottom
• Space Toggle completion status
• /: Filter list items
• Escape: Exit filter mode
• a Add new ToDo Item
• d Delete selected item

Examples*

Basic ToDo List

{
  "type": "component",
  "component": {
    "type": "todo",
    "title": "Work Tasks",
    "data": {
      "source": "./work.txt"
    }
  }
}

Chart Component

The Chart component displays numerical data as line charts. It's perfect for visualizing trends, metrics, and time-series data.

Data Format The Chart component accepts:

• JSON array of numbers: [1, 5, 3, 8, 2]
• Plain text with one number per line:

  1
  5
  3
  8
  2
  

Special Properties

• refresh_mode:
  • replace: Replaces data on refresh (default)
  • append: Adds new data points to existing ones
• caption: Optional text shown below the chart

Examples

Memory Usage Chart

{
  "type": "component",
  "component": {
    "type": "chart",
    "title": "Memory Usage",
    "data": {
      "source": "script",
      "command": "memory_pressure | grep \"System-wide memory free percentage\" | awk '{print 100-$5}'",
      "refresh_interval": 1,
      "refresh_mode": "append",
      "caption": "Memory % Used"
    }
  }
}

API Data Chart

{
  "type": "component",
  "component": {
    "type": "chart",
    "title": "API Response Times",
    "data": {
      "source": "api",
      "url": "https://example.com/metrics/response_times",
      "json_path": "$.data.values",
      "refresh_interval": 30
    }
  }
}

Table Component

The Table component displays structured data in a tabular format with defined columns. It's ideal for displaying datasets with multiple attributes per item.

Data Formats

The Table component accepts:

• JSON array of objects: Each object is a row, properties map to columns
• JSON Array of arrays: Each inner array is a row with values for each column

Column Configuration

Each column accepts:

• label: (Required) Column header text
• field: (Optional) Property name (for JSON objects)
• flex: (Optional) Relative width (higher numbers get more space)

Interaction

• Arrow keys or j/k/: Scroll up/down
• g/G: Scroll to Top/Bottom

Examples

API Users Table

{
  "type": "component",
  "component": {
    "type": "table",
    "title": "User Information",
    "data": {
      "source": "api",
      "url": "https://jsonplaceholder.typicode.com/users",
      "columns": [
        {
          "label": "ID",
          "field": "id",
          "flex": 1
        },
        {
          "label": "Name",
          "field": "name",
          "flex": 3
        },
        {
          "label": "Email",
          "field": "email",
          "flex": 4
        }
      ]
    }
  }
}

Histogram Component

The Histogram component displays distribution data as horizontal bar charts. It's excellent for frequency distributions, categorized metrics, or any key-value data where values represent quantities.

Data Format

The Histogram accepts data in these formats:

1. JSON object with key-value pairs (keys are labels, values are counts):

{
  "18-24": 45,
  "25-34": 78,
  "35-44": 52,
  "45-54": 34,
  "55+": 21
}

2. Plain text with key-value pairs (one per line):

18-24: 45
25-34: 78
35-44: 52
45-54: 34
55+: 21

3. List of items (the component will count occurrences):

apple
banana
apple
orange
apple
banana

Special Properties

• caption: Optional text shown below the histogram

Examples

API Data Example

{
  "type": "component",
  "component": {
    "type": "histogram",
    "title": "API Response Status",
    "data": {
      "source": "api",
      "url": "https://jsonplaceholder.typicode.com/posts",
      "json_path": "$.[:15].userId",
      "refresh_interval": 60,
      "caption": "User Post Count"
    }
  }
}

{
  "type": "component",
  "component": {
    "type": "histogram",
    "title": "Histogram Data",
    "data": {
      "source": "script",
      "command": "cat ./histogram_data.sh",
      "refresh_interval": 5
    }
  }
}

Component Interaction

All components support basic navigation using:

• Shift+Arrow Keys or Shift + H/J/K/L: Navigate between components
• Mouse: Click to focus a component

Interactive components may support additional actions:

R: Refresh data Space: Toggle item (todo lists) A: Add new item (todo lists) /: Filter items (lists) Arrow keys, Mouse Scroll, h/j/k/l: Navigate within component content