From 732577fae591a04462044fc89f9497e822b6268c Mon Sep 17 00:00:00 2001
From: Kacper Kula <kulak@kulak.at>
Date: Sat, 22 Feb 2025 10:37:38 +0100
Subject: [PATCH] docs: adding few extra pages

---
 docs/.vitepress/config.mts    | 10 +++++++++-
 docs/chart-type/bar-chart.md  |  2 ++
 docs/chart-type/line-chart.md |  2 ++
 docs/syntax.md                | 30 ++++++++++++++++++++++++++++++
 4 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 docs/syntax.md

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 405fa3e..749dfdb 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -25,7 +25,15 @@ export default defineConfig({
       {
         text: 'Documentation',
         items: [
-          { text: 'Quick Start', link: '/quick-start' }
+          { text: 'Quick Start', link: '/quick-start' },
+          { text: 'Syntax', link: '/syntax' }
+        ]
+      },
+      {
+        text: 'Chart Types',
+        items: [
+          { text: 'Line Chart', link: '/chart-type/line-chart' },
+          { text: 'Bar Chart', link: '/chart-type/bar-chart' }
         ]
       }
     ],
diff --git a/docs/chart-type/bar-chart.md b/docs/chart-type/bar-chart.md
index da41a21..1261283 100644
--- a/docs/chart-type/bar-chart.md
+++ b/docs/chart-type/bar-chart.md
@@ -1 +1,3 @@
 # Bar Chart
+
+Under construction.
diff --git a/docs/chart-type/line-chart.md b/docs/chart-type/line-chart.md
index 323ca87..e29adb8 100644
--- a/docs/chart-type/line-chart.md
+++ b/docs/chart-type/line-chart.md
@@ -1 +1,3 @@
 # Line Chart
+
+Under construction.
diff --git a/docs/syntax.md b/docs/syntax.md
new file mode 100644
index 0000000..25e2d51
--- /dev/null
+++ b/docs/syntax.md
@@ -0,0 +1,30 @@
+# Syntax
+SQLSeal Charts uses [ECharts](https://echarts.apache.org/en/index.html) under the hood. It automatically exposes data returned by your SQL query as a `data` dataset in ECharts. This means you can generate plenty of charts without worrying too much about how the data is being passed down. For more complex use-cases, you can always refer to the data by column name, it's index or even filter it down to create separate data-sets for different series.
+To read more about datasets, [check out ECharts documentation](https://apache.github.io/echarts-handbook/en/concepts/dataset/).
+
+## Variables
+In addition SQLSeal exposes data returned by SQLSeal Query in the following variables:
+| Variable Name          | Description                                                                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `data`                 | Array of objects containing raw data                                                                                                             |
+| `columns`              | array of column names                                                                                                                            |
+| Object for each column | You can refer to each of the column data by their name, i.e. for `SELECT category, amount FROM data` you can use `category` and `amount` columns |
+
+## Functions
+Extra functions are exposed in SQLSeal Charts configuration object so you can use them:
+
+| Function                                                            | Description                                                                                                                                          |
+| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `column(name: string)`                                              | Returns array of the values for a specified column                                                                                                   |
+| `mean, max, min, uniq, uniqBy`                                      | [Lodash](https://lodash.com/docs/4.17.15) functions to help with data processing                                                                     |
+| `array(...arrays)`                                                  | creates subarrays from arrays, i.e. `array([1,2], [3,4 ]) == [[1,3], [2,4]]`. Useful when grouping multiple columns together when reshaping the data |
+| `assembleObjects(...definitions: { key: string, values: array }[])` | Assembles multiple arrays into array of objects using provided key values                                                                            |
+| `assemble(definition: Record<string, array>)`                       | Assembles multiple arrays into array of objects using a key=>value map                                                                               |
+
+## JavaScript functionality
+Configuration has some basic JavaScript capabilities. For security reasons not all JavaScript syntax is available. This will change and more functions will be exposed.
+For now the following JavaScript syntax is enabled:
+- Arrow functions, i.e: `() => column('data')`
+- Template literals, i.e.: \`${column('data')[0]}\`
+
+More functionality will get exposed soon.
\ No newline at end of file