initial import

.editorconfig

@@ -0,0 +1,13 @@
+# http://editorconfig.org
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+max_line_length = 120
+
+[*.yaml]
+indent_size = 2

.gitignore

@@ -0,0 +1,3 @@
+build
+__pycache__
+*.egg-info

LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2022 Andreas Gerstmayr <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,55 @@
+# Fava Dashboards
+fava-dashboards allows creating custom dashboards in [Fava](https://github.com/beancount/fava).
+
+[![Overview](example/overview.png)](example/overview.png)
+[![Expenses](example/expenses.png)](example/expenses.png)
+
+## Installation
+```
+pip install git+https://github.com/andreasgerstmayr/fava-dashboards.git
+```
+
+Enable this plugin in Fava by adding the following lines to your ledger:
+```
+2010-01-01 custom "fava-extension" "fava_dashboards"
+```
+
+## Configuration
+Please take a look at the example dashboard configuration [dashboards.yaml](example/dashboards.yaml), which uses most of the functionality described below.
+
+The configuration file can contain multiple dashboards, and a dashboard contains one or more panels.
+A panel has a relative width (e.g. `50%` for 2 columns, or `33.3%` for 3 column layouts) and a absolute height.
+Currently there are two kinds of panels: Charts and HTML.
+
+### Charts
+Chart panels can contain a `queries` field and must contain a `chart` field.
+
+The `queries` field contains one or multiple queries. The beancount query must be stored in the `bql` field of the respectiv query.
+The query results can be accessed via `panel.queries[i].result`, where `i` is the index of the query in the `queries` field.
+
+The `chart` field must contain valid JavaScript code and must return a valid [Apache ECharts](https://echarts.apache.org) configuration.
+Please take a look at the [ECharts examples](https://echarts.apache.org/examples) to get familiar with the available chart types and options.
+
+For convenience a `utils.months` and `utils.years` variable is accessible in the JavaScript code, containing a list of years/months of the current selected time frame.
+
+Note: Additionally to the beancount query, Fava's filter bar further filters the available entries of the ledger.
+
+### HTML
+HTML panels must contain a `html` field with HTML code.
+This code will be rendered in the panel.
+
+## View Example Ledger
+`cd example; fava example.beancount`
+
+## Why no React/Svelte/X?
+The main reason is simplicity.
+This project is small enough to use plain HTML/CSS/JS and Jinja2 templates only, and doesn't warrant using a modern and ever-changing web development toolchain.
+Currently it requires only two external dependencies: pyyaml and echarts.
+
+## Related Projects
+* [Fava Portfolio Returns](https://github.com/andreasgerstmayr/fava-portfolio-returns)
+
+## Acknowledgements
+Thanks to Martin Blais and all contributors of [beancount](https://github.com/beancount/beancount),
+Jakob Schnitzer, Dominik Aumayr and all contributors of [Fava](https://github.com/beancount/fava),
+and to all contributors of [Apache ECharts](https://echarts.apache.org).

example/Pipfile

@@ -0,0 +1,12 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+fava-dashboards = {editable = true, path = "./.."}
+
+[dev-packages]
+
+[requires]
+python_version = "3.10"

example/dashboards.yaml

@@ -0,0 +1,239 @@
+dashboards:
+- name: Overview
+  panels:
+  - title: Income/Expenses 💰
+    height: 400px
+    queries:
+    - name: Income
+      stack: income
+      bql: |
+        SELECT year, month, CONVERT(SUM(position), 'EUR') AS value
+        WHERE account ~ '^Income:'
+        GROUP BY year, month
+    - name: Home
+      stack: expenses
+      bql: |
+        SELECT year, month, CONVERT(SUM(position), 'EUR') AS value
+        WHERE account ~ '^Expenses:Home:'
+        GROUP BY year, month
+    - name: Food
+      stack: expenses
+      bql: |
+        SELECT year, month, CONVERT(SUM(position), 'EUR') AS value
+        WHERE account ~ '^Expenses:Food:'
+        GROUP BY year, month
+    - name: Travel
+      stack: expenses
+      bql: |
+        SELECT year, month, CONVERT(SUM(position), 'EUR') AS value
+        WHERE account ~ '^Expenses:' AND 'travel' IN tags
+        GROUP BY year, month
+    - name: Other
+      stack: expenses
+      bql: |
+        SELECT year, month, CONVERT(SUM(position), 'EUR') AS value
+        WHERE account ~ '^Expenses:' AND NOT account ~ '^Expenses:(Home|Food):' AND NOT 'travel' IN tags
+        GROUP BY year, month
+    chart: |
+      const currencyFormat = new Intl.NumberFormat(undefined, {style: "currency", currency: "EUR", maximumFractionDigits: 0});
+      const months = utils.months.map(m => `${m.month}/${m.year}`);
+
+      // the beancount query only returns months where there was at least one matching transaction, therefore we group by month
+      const valuesPerMonth = {};
+      for (let query of panel.queries) {
+        valuesPerMonth[query.name] = {};
+        for (let row of query.result) {
+          valuesPerMonth[query.name][`${row.month}/${row.year}`] = query.stack == "income" ? -row.value.EUR : row.value.EUR;
+        }
+      }
+
+      const series = panel.queries.map(query => ({
+        type: "bar",
+        name: query.name,
+        stack: query.stack,
+        data: months.map(month => valuesPerMonth[query.name][month] || 0)
+      }));
+
+      return {
+        tooltip: {
+          valueFormatter: currencyFormat.format
+        },
+        legend: {
+          top: "bottom"
+        },
+        xAxis: {
+          data: months
+        },
+        yAxis: {
+          axisLabel: {
+            formatter: currencyFormat.format
+          }
+        },
+        series: series
+      };
+
+- name: Expenses
+  panels:
+  - title: Categories 💸
+    width: 50%
+    height: 400px
+    queries:
+    - bql: |
+        SELECT account, CONVERT(SUM(position), 'EUR') AS value
+        WHERE account ~ '^Expenses:'
+        GROUP BY account
+        ORDER BY account
+    chart: |
+      const currencyFormat = new Intl.NumberFormat(undefined, {style: "currency", currency: "EUR", maximumFractionDigits: 0});
+      const mainCategories = {};
+      const subCategories = {};
+
+      for (let row of panel.queries[0].result) {
+        const [, mainCategory, subCategory] = row.account.split(":");
+
+        if (!(mainCategory in mainCategories))
+          mainCategories[mainCategory] = 0;
+        mainCategories[mainCategory] += row.value.EUR;
+
+        if (!(subCategory in subCategories))
+          subCategories[subCategory] = 0;
+        subCategories[subCategory] += row.value.EUR;
+      }
+
+      return {
+        tooltip: {
+          valueFormatter: currencyFormat.format
+        },
+        series: [
+          {
+            type: "pie",
+            radius: [0, "55%"],
+            label: {show: false},
+            data: Object.entries(mainCategories).map(([k, v]) => ({name: k, value: v}))
+          },
+          {
+            type: "pie",
+            radius: ["60%", "100%"],
+            label: {show: false},
+            data: Object.entries(subCategories).map(([k, v]) => ({name: k, value: v}))
+          }
+        ]
+      };
+
+  - title: Food Expenses 🥐
+    width: 50%
+    height: 400px
+    queries:
+    - bql: |
+        SELECT year, month, CONVERT(SUM(position), 'EUR') AS value
+        WHERE account ~ '^Expenses:Food:'
+        GROUP BY year, month
+    chart: |
+      const currencyFormat = new Intl.NumberFormat(undefined, {style: "currency", currency: "EUR", maximumFractionDigits: 0});
+      const months = panel.queries[0].result.map((row) => `${row.month}/${row.year}`);
+      const values = panel.queries[0].result.map((row) => row.value.EUR);
+
+      return {
+        tooltip: {
+          valueFormatter: currencyFormat.format
+        },
+        xAxis: {
+          data: months
+        },
+        yAxis: {
+          axisLabel: {
+            formatter: currencyFormat.format
+          }
+        },
+        series: [
+          {
+            type: "line",
+            smooth: true,
+            data: values
+          }
+        ]
+      };
+
+  - title: Travel Costs per Year 📅
+    # Note: Holidays over New Year's Eve are counted in both years aliquot.
+    height: 400px
+    queries:
+    - bql: |
+        SELECT year, CONVERT(SUM(position), 'EUR') AS value
+        WHERE account ~ '^Expenses:' AND 'travel' IN tags
+        GROUP BY year
+    chart: |
+      const currencyFormat = new Intl.NumberFormat(undefined, {style: "currency", currency: "EUR", maximumFractionDigits: 0});
+      const years = utils.years;
+      const amount = {};
+
+      for (let row of panel.queries[0].result) {
+        amount[row.year] = row.value.EUR;
+      }
+
+      return {
+        tooltip: {
+          valueFormatter: currencyFormat.format
+        },
+        xAxis: {
+          data: years
+        },
+        yAxis: {
+          axisLabel: {
+            formatter: currencyFormat.format
+          }
+        },
+        series: [
+          {
+            type: "line",
+            smooth: true,
+            data: years.map(year => amount[year] || 0)
+          }
+        ]
+      };
+
+  - title: Destinations ✈️
+    height: 300px
+    queries:
+    - bql: |
+        SELECT tags, CONVERT(position, 'EUR') AS value
+        WHERE account ~ '^Expenses:' AND 'travel' IN tags
+        ORDER BY date
+    chart: |
+      const currencyFormat = new Intl.NumberFormat(undefined, {style: "currency", currency: "EUR", maximumFractionDigits: 0});
+      const travels = [];
+      const amounts = {};
+
+      for (let row of panel.queries[0].result) {
+        const tag = row.tags.find(tag => tag.match(/\-\d{4}/));
+        if (!(tag in amounts)) {
+          travels.unshift(tag);
+          amounts[tag] = 0;
+        }
+        amounts[tag] += row.value.number;
+      }
+
+      return {
+        tooltip: {
+          valueFormatter: currencyFormat.format
+        },
+        grid: {
+          left: "150px"
+        },
+        xAxis: {
+          type: "value",
+          axisLabel: {
+            formatter: currencyFormat.format
+          }
+        },
+        yAxis: {
+          type: "category",
+          data: travels
+        },
+        series: [
+          {
+            type: "bar",
+            data: travels.map(travel => amounts[travel])
+          }
+        ]
+      }