# Luminous

Luminous is a framework for creating dashboards within [Phoenix Live
View]( It is somewhat inspired by
grafana both conceptually and functionally in that:

- it focuses on time series data (albeit not exclusively)
- it is organized around panels
- it is parameterized by a time range
- it can be parameterized by user-defined variables

Dashboards are defined at compile time using elixir code (see
`Luminous.Dashboard.define/5`). At runtime, Luminous uses the
following javascript libraries (as [live view
for supporting client-side visualizations and interactions with the
live view process:

- [chartjs]( for plots
- [flatpickr]( for time range selection

Luminous is currently used in production systems and has demonstrated
solid performance and stability characteristics. At the same time, it
is currently under development and some things may change.

## Installation

The package is not yet published to `` but can be installed
directly from this repo by adding `luminous` to your list of
dependencies in `mix.exs` like so:

def deps do
    {:luminous, git: "", branch: "main"}

`luminous` assumes that it will be embedded in a standard Phoenix LiveView application with [tailwindcss](

In order to be able to use the provided components, the library's `javascript` and
`CSS` files must be imported to your project:

In `assets/package.json`:
"dependencies": {
  "luminous": "file:../deps/luminous"

In `assets/js/app.js`:

import { ChartJSHook, TimeRangeHook } from "luminous"

let Hooks = {
  TimeRangeHook: new TimeRangeHook(),
  ChartJSHook: new ChartJSHook()


let liveSocket = new LiveSocket("/live", Socket, {
  hooks: Hooks

Finally, in `assets/css/app.css`:
@import "luminous/dist/luminous";

## Usage

A [demo dashboard](dev/demo_dashboard_live.ex) has been provided that
showcases some of Luminous' capabilities.

The demo can be inspected live using the project's dev server (run
`mix dev` in the project and then visit [this

Luminous is a framework in the sense that the luminous client is
responsible for specifying queries, variables etc. and `Luminous.Live`
will call the client's code by setting up all the required plumbing.

In general, a custom dashboard needs to:

- implement the `Luminous.Variable` behaviour for the
  dashboard-specific variables
- implement the `Luminous.Query` behaviour for loading the necessary
  data that will be visualized in the client
- implement the `Luminous.TimeRangeSelector` behaviour for determining
  the default time range for the dashboard
- `use` the `Luminous.Live` module for leveraging the live dashboard
  functionality and capabilities
- render the dashboard in the view template (only
  `Luminous.Components.dashboard` is necessary but the layout can be
  customized by using directly the various components in

## Features

- Time range selection and refresh of all dashboard panel queries
- Asynchronous queries and page updates
- User-facing variable dropdowns that are available to panel queries
- Client-side zoom in charts
- Multiple supported chart types (currently `:line` and `:bar`)
- Download panel data (CSV, PNG)
- Stat panels (show single or multiple stats)
- Summary statistics in panels

## Development

Documentation can be generated with
[ExDoc]( and published on
[HexDocs]( Once published, the docs can be found
at <>.