@graphenedata/cli 0.0.15 → 0.0.16

package/dist/skills/graphene/SKILL.md

@@ -1,28 +1,28 @@
-
 ---
 name: graphene
 description: How to use Graphene, our framework for data modeling, analysis, and visualization.
 ---
 
-Graphene is a framework for doing data analysis and BI as code. Schema definitions and semantic models are in `.gsql` files, dashboards in `.md`.
+Graphene is a framework for doing data analysis and BI as code. Schema definitions and semantic models are in `.gsql` files, dashboards/notebooks (called pages) in `.md`.
 
 # GSQL
 GSQL extends ANSI SQL with dimensions, measures, and join relationships. Declare them in `table` statements:
 
 ```sql
 table orders (
-  id BIGINT
-  user_id BIGINT
-  amount FLOAT
-  status STRING
+  id bigint
+  created_at datetime
+  user_id bigint
+  amount float                          #units=usd
+  status string
   join one users on user_id = users.id  -- many orders per user
   is_complete: status = 'Complete'      -- dimension (scalar expression)
-  revenue: sum(amount)                  -- measure (agg expression)
-  avg_order: revenue / count(*)         -- measures can compose
+  revenue: sum(amount)                  -- measure (agg expression) #units=usd
+  avg_order: revenue / count(*)         -- measures can compose #units=usd
 )
 table users (
-  id BIGINT
-  name VARCHAR
+  id bigint
+  name varchar
   join many orders on id = orders.user_id
 )
 ```
@@ -43,139 +43,193 @@ Dimensions and measures are like macros that expand inline when GSQL compiles to
 - OK: `floor(revenue)`, `revenue / cost` 
 - OK: `sum(case when is_complete then 1 else 0 end)` or `group by is_complete` (because `is_complete` is a dimension, not a measure)
 
+### Arrays
+- Array columns and casts use `array<T>` syntax in GSQL, for example `tags array<string>` or `cast(tags as array<string>)`
+- Arrays can be expanded in queries with `cross join unnest(tags) as tag`
+
 ### Special features
 - `group by all` is implied when aggregates exist, and does not need to be put in GSQL
 - Agg function `pXX(column)` computes the XXth percentile (e.g., p50, p975, p9999)
+- `select`, `from`, `order by`, etc. in any order
 
-### Unsupported
-- Set operations (`union`, etc.)
-- Semi-structured data types (`VARIANT`, `OBJECT`, `ARRAY`)
+### Supported
+- All scalar, agg, and window functions of the connected database
+- ANSI joins, CTEs, subqueries, set operations
 
-# Dashboards
-Graphene dashboards extend Markdown with the following:
+### Not supported
+- Table functions
+- UDFs
+- `pivot`, `lateral`
+- `variant`, `object`, `record` types
+
+# Pages
+Graphene pages extend Markdown with the following:
 - GSQL queries in code fences
-- Visualization components reference query names
+- Visualization and input components
 
 ````md
-```sql sales_by_category
-select category, revenue from orders
+---
+title: My First Dashboard
+layout: dashboard
+---
+
+```sql sales_by_status
+select extract(year from created_at) AS year, status, revenue
+from orders
+where status <> 'cancelled'
 ```
-<BarChart data="sales_by_category" x="category" y="revenue" />
-<BigValue data="sales_by_category" value="revenue" />
+
+<BigValue data="orders" value="revenue" />
+<BarChart data="sales_by_status" x="year" y="revenue" splitBy="status"/>
 ````
 
-Queries can be referenced by other queries in the `from` or `join` to form DAGs of data transformations within the dashboard.
-`data` can be a query name or a table name. Attributes that accept columns also accept GSQL expressions.
-
-## Components
-### Visualizations
-- BarChart: data, x, y, y2, series, title, subtitle, xFmt, yFmt, y2Fmt, colorPalette, type, swapXY, labels, labelFmt, sort, legend, yMin, yMax
-- LineChart: data, x, y, y2, series, title, subtitle, xFmt, yFmt, colorPalette, labels, sort, legend, handleMissing, markers, markerShape, lineType, lineWidth
-- AreaChart: data, x, y, series, title, subtitle, xFmt, yFmt, colorPalette, type, labels, sort, legend, handleMissing, fillOpacity, line
-- PieChart: data, category, value, title, subtitle
-- BigValue: data, value, title, fmt, comparison, comparisonFmt, comparisonTitle, downIsGood, sparkline, sparklineType, sparklineColor
-- Table: data, rows, title, subtitle, groupBy, groupType, subtotals, totalRow, search, sort, link, rowShading, rowNumbers, compact, headerColor
-  - Column (sub-component of Table): id, title, fmt, align, wrap, contentType, totalAgg, redNegatives
-
-### Inputs
-- Dropdown: name, data, value, label, defaultValue, multiple, title
-- TextInput: name, title, placeholder
-
-### Other components
-- Row: no attributes (layout container, distributes children horizontally)
-
-## Component attributes
-- series: column whose values become separate lines/bars (series=country plots one line per country)
-- type: stacked (default), grouped (BarChart only), stacked100
-- y2: secondary y-axis, y2SeriesType sets its chart type (line/bar/scatter)
-- swapXY: horizontal bars
-- handleMissing: gap (default), connect, zero
-- colorPalette: comma-separated "#hex1, #hex2", applied to series in order
-- seriesOrder: control series order "Val1, Val2", pairs with colorPalette
-- labels: show value labels on chart
-- markers: show dots on line points; markerShape: circle, emptyCircle, rect, triangle, diamond
-- lineType: solid, dashed, dotted
-- downIsGood: green for negative (for comparison/delta)
-- sparkline: date column for mini trend; sparklineType: line, area, bar
-- groupBy: group table rows; groupType: accordion (collapsible) or section (merged)
-- totalRow: sum row at bottom; subtotals: sum row per group
-- link: make table rows clickable, value is URL column
-- contentType:
-  - delta: arrows+colors. deltaSymbol, downIsGood, chip, neutralMin/Max
-  - colorscale: background gradient. colorScale, colorMin/Mid/Max
-  - bar: in-cell bar. barColor, negativeBarColor
-  - link: clickable. linkLabel, openInNewTab
-  - image: show image. height, width
-  - sparkline/sparkarea/sparkbar: mini chart from array. sparkX, sparkY, sparkColor
-- totalAgg: sum (default), mean, weightedMean, median, min, max, count, countDistinct
-
-## Tying input components to SQL
-Inject input values into queries by referring to their `name` attribute as $name. 
+Queries can be referenced by other queries in the `from` or `join` to form DAGs of data logic within the page.
+
+## Page frontmatter
+You can add YAML frontmatter at the top of a page. The following attributes are supported:
+- `title`: title displayed at the top of the page
+- `layout`: `notebook` is the default, good for prose interspersed with charts. `dashboard` has a wider max-width, for chart-heavy pages with lots of `<Row>`s.
+
+## Viz and display components
+- LineChart: title, data, x, y, y2, splitBy, sort, height, width
+- AreaChart: title, data, x, y, y2, splitBy, arrange (`stack` (default) or `stack100`), sort, height, width
+- BarChart: title, data, x, y, y2, splitBy, arrange (`stack` (default), `group`, or `stack100`), label (true or false (default); shows labels above bars), sort, height, width
+- ScatterPlot: title, data, x, y, splitBy, height, width
+- PieChart: title, data, category, value, height, width
+- ECharts: data, height, width, renderer
+- BigValue: title, data, value
+- Table: title, data, rows, sortable, sort, groupBy, groupType, subtotals, totalRow, link, showLinkCol, rowShading, rowLines, rowNumbers, compact, headerColor, headerFontColor, totalRowColor, totalFontColor, backgroundColor, emptyMessage
+  - Column (sub-component of Table): id (column name), title, description, align, wrap, wrapTitle, colGroup, contentType, totalAgg, redNegatives
+- Value: data, column, row
+- Row (layout container, distributes children horizontally): No attributes
+
+Notes on common attributes:
+- `data` can also point at a modeled GSQL table.
+- Any attribute that accepts a column can also accept an arbitrary GSQL expression. These attributes are x, y, y2, splitBy, category, value, link, groupBy, scaleColumn
+- `splitBy` creates a series for each distinct value in the column (long format data).
+- `y` can take a comma-separated list of columns/expressions, to map multiple fields to the same y-axis as separate series (wide format data).
+- `sort` takes a column name followed by `asc` or `desc`, eg. `my_col desc`. Useful when you want something sorted differently than its inherent alphanumeric ordering.
+- `height` and `width` accept any CSS size units eg. `240px` or `50%`.
+
+### `<ECharts>`
+To create visualizations or customizations beyond Graphene's out-of-the-box components, specify an ECharts config via `<ECharts>`.
+
+This example creates a stacked bar chart with a purple x-axis.
+
+```md
+<ECharts data="sales_by_status">
+  title: {text: "Annual Revenue by Status"},
+  xAxis: {axisLine: {lineStyle: {color: 'purple'}}},
+  series: [{type: "bar", stack: "bar-stack", encode: {x: "year", y: "revenue", splitBy: "status"}],
+</ECharts>
+```
+
+Use `encode` to map objects to the columns of the data source. In Graphene, `encode` also accepts `splitBy` which automatically expands one template into multiple series. For bar charts, `splitBy` can be a two-item list (`[groupBy, stackBy]`) for grouped+stacked bars.
+
+Graphene will handle axes, layout, and styles for you, so you can omit those configurations unless you explicitly want to override them.
+
+Unsupported:
+- `{@colName}` formatter templates (but `{a}`, `{b}`, `{c}` work)
+- Javascript of any kind
+
+### `<Value>`
+`<Value>` is used for inlining SQL-derived values within markdown text. You can place them anywhere in markdown, including headers, and they can be styled with `**` or `_`.
+
+```md
+### Top 3 Most Active Airplane Models
+1. **<Value data=top_airplane_models column=manufacturer_model row=0 />** ...
+```
+
+## Input components
+- Dropdown: title, name, data, value (column to populate list with), label, defaultValue, multiple
+- TextInput: title, name, placeholder
+- DateRange: title, name, data, dates, start, end, defaultValue, presetRanges, description
+
+Inject input values into queries by referring to their `name` attribute as `$name` in GSQL. 
 
 ````md
 <Dropdown name=status .../>
+
 ```sql my_query
 select ...
 where status = $status
 ```
 ````
 
-## Formatting
-`fmt` attributes accept Excel custom format codes or built-in Graphene formats:
-- Numbers: num, num0-num4, num0k, num0m, num0b (etc.), id, fract, mult, mult0-mult2, sci
-- Currency: usd, usd0-usd2, usd0k, usd0m, usd0b (etc.), (also eur, gbp, etc.)
-- Percent: pct, pct0, pct1, pct2, pct3
-- Dates: shortdate, longdate, fulldate, mdy, dmy, hms, ddd, dddd, mmm, mmmm, yyyy
-- Excel: "$#,##0.00", "0.0%", "m/d/yy" (etc.)
+DateRange components emit two referenceable values via `${name}_start` and `${name}_end`.
+
+Input values also sync into the page URL query string (eg. `localhost:4000/my_dashboard?status=cancelled`), so reloads and shared links preserve the same dashboard state.
 
 # CLI
 
-`graphene check` is a diagnostics command.
+Invoke the CLI via your project's package manager (e.g. `pnpm graphene check`, `npm exec graphene run`).
 
 ```bash
 graphene check # Check diagnostics across all .gsql files in the project
 graphene check path/to/file.gsql # Check diagnostics for one specific gsql file
 graphene check path/to/page.md # Check diagnostics for one specific markdown file
-```
-
-`graphene run` supports both query execution and markdown page runs.
 
-```bash
 graphene run "from flights select count() as total" # Run inline GSQL and print results
 graphene run - # Read GSQL from stdin and print results
 
 graphene run path/to/page.md # Run the page and save a full-page screenshot
+
+# `-c/--chart` can target either a chart title or the chart's `queryId`. For charts without titles use `graphene list` to see the exact IDs for charts on a page.
 graphene run path/to/page.md -c "Chart Title" # Run the page and screenshot one chart by title
-graphene run path/to/page.md -q query_name # Run a named query/table from the markdown context and print results
-```
+graphene run path/to/page.md -c 'Query (data="query_name" x="category" y="total")' # Run the page and screenshot one chart by queryId
 
-`-q/--query` can target anything usable in a chart `data` prop (for example, a gsql table or a named code-fenced query in the markdown file).
+# `-q/--query` can target anything usable in a chart `data` prop (for example, a gsql table or a named code-fenced query in the markdown file).
+graphene run path/to/page.md -q query_name # Run a named query/table from the markdown context and print results
 
-Invoke via your project's package manager (e.g. `pnpm graphene check`, `npm exec graphene run`).
+graphene compile "[GSQL]" # Show the compiled, dialect-specific SQL
 
-Other commands:
+# `schema` is for implementation/migration purposes and is NOT for exploring GSQL models
+graphene schema # List datasets/schemas in the connected database
+graphene schema my_dataset # List schemas (or tables) in a dataset
+graphene schema my_dataset.table # Print the GSQL table statement for a database table
 
-```bash
-graphene compile "[GSQL]" # Show the compiled, dialect-specific SQL
+graphene serve # Start the local dev server (foreground)
+graphene serve --bg # Start the local dev server in the background
+graphene stop # Stop the background dev server
 ```
 
 # Best practices
-- Start simple - Get basic query working, then add complexity
-- Use check often - Catches syntax and analysis errors early
-- Iterate dashboard queries in-file - When tuning a code-fenced query in a markdown dashboard, edit the `.md` file and run `graphene run [mdFile] -q [queryName]` instead of inline CLI GSQL to avoid drift between experimentation and what gets committed
-- Leverage models - Use modeled joins, dimensions, and measures rather than raw SQL
-- Don't format in SQL - Rely on `fmt` instead. Do not multiply percentages by 100.
+- **Leverage models** - Use modeled joins, dimensions, and measures whenever possible
+- Use `check` after editing .gsql files to catch syntax errors
+- Use `run path/to/page.md` after editing a page to catch runtime errors and to review the screenshot
+- Use `run path/to/page.md -c "[Chart Title | Query ID]"` after editing an ECharts component to view the screenshot
+- When iterating on code-fenced GSQL queries, use `run path/to/page.md -q query_name` instead of `run "[GSQL]"`
+- Rely on Graphene's defaults for value formatting and chart styles before trying to override in SQL or ECharts
+- Keep numbers grounded - Use the `<Value/>` component in prose instead of hard-coding numbers 
+- When adding viz, think like Edward Tufte. What is _the_ most effective way to illustrate the data? 
+
+If the user asks:
+- An open-ended question => notebook
+- To create a page for monitoring purposes => dashboard
+- A more straightforward, tactical question => no page, answer in chat
+
+## Notebook guide
+- Use `layout: notebook` in frontmatter
+- Queries should be point-in-time via absolute time filters
+- Page should read like a narrative with prose interspersed with tables or visuals
+- Try to use the most scientifically rigorous means possible to derive insights: think like a statistician or data scientist
+
+## Dashboard guide
+- Use `layout: dashboard` in frontmatter
+- Queries generally use relative time filters eg. last 3 months. If user doesn't specify, ask.
+- Avoid narratives - Don't use headers, prose, other markdown content much if at all
+- Use `<Row>` to create grids to fit the maximum amount of information in the viewport
+- Ask the user if they would like any inputs to dynamically filter things
 
 # Reference documentation
 Consult the reference documentation for more detailed information on using Graphene.
+For semantic modeling with GSQL references, read `references/model-gsql.md`.
 
-- references/area-chart.md
-- references/bar-chart.md
 - references/big-value.md
+- references/date-range.md
 - references/dropdown.md
+- references/echarts.md
 - references/gsql.md
-- references/line-chart.md
-- references/pie-chart.md
+- references/model-gsql.md
 - references/table.md
 - references/text-input.md
-- references/value-formats.md

package/dist/skills/graphene/references/big-value.md

@@ -1,55 +1,20 @@
-Use big values to display a large value standalone, and optionally include a comparison and a sparkline.
+Use a BigValue to display a single large value standalone.
 
 Here's an example:
 
 ```markdown
 <BigValue
-  data=orders_with_comparisons
+  data=orders
   value=num_orders
-  sparkline=month
-  comparison=order_growth
-  comparisonFmt=pct1
-  comparisonTitle="vs. Last Month"
+  title="Total Orders"
 />
 ```
 
 # Attributes
 
-## Data
-
 | Attribute | Description | Required | Options | Default |
 |------|-------------|----------|---------|---------|
 | data | GSQL query or table name | true | query name | - |
-| value | Column or expression to pull the main value from. | true | column name, stored expression name, GSQL expression | - |
-| title | Title of the card. | false | string | Title of the value column. |
-| minWidth | Overrides min-width of component | false | % or px value | `"18%"` |
-| maxWidth | Adds a max-width to the component | false | % or px value | - |
-| fmt | Sets format for the value ([see available formats](#value-formatting)) | false | Excel-style format, built-in format | - |
-| emptySet | Sets behaviour for empty datasets. Can throw an error, a warning, or allow empty. When set to 'error', empty datasets will block builds in `build:strict`. Note this only applies to initial page load - empty datasets caused by input component changes (dropdowns, etc.) are allowed. | false | `error`, `warn`, `pass` | `error` |
-| emptyMessage | Text to display when an empty dataset is received - only applies when `emptySet` is 'warn' or 'pass', or when the empty dataset is a result of an input component change (dropdowns, etc.). | false | string | `"No records"` |
-| link | Used to navigate to other pages. Can be a full external link like `"https://google.com"` or an internal link like `"/sales/performance"` | false | - | - |
-
-## Comparison
-
-| Attribute | Description | Required | Options | Default |
-|------|-------------|----------|---------|---------|
-| comparison | Column or expression to pull the comparison value from. | false | column name, stored expression name, GSQL expression | - |
-| comparisonTitle | Text to the right of the comparison. | false | string | Title of the comparison column. |
-| comparisonDelta | Whether to display delta symbol and color | false | `true`, `false` | `true` |
-| downIsGood | If present, negative comparison values appear in green, and positive values appear in red. | false | `true`, `false` | `false` |
-| neutralMin | Sets the bottom of the range for 'neutral' values - neutral values appear in grey rather than red or green | false | number | `0` |
-| neutralMax | Sets the top of the range for 'neutral' values - neutral values appear in grey rather than red or green | false | number | `0` |
-| comparisonFmt | Sets format for the comparison ([see available formats](#value-formatting)) | false | Excel-style format, built-in format | - |
-
-## Sparkline
-
-| Attribute | Description | Required | Options | Default |
-|------|-------------|----------|---------|---------|
-| sparkline | Column or expression to pull the date from to create the sparkline. | false | column name, stored expression name, GSQL expression | - |
-| sparklineType | Chart type for sparkline | false | `line`, `area`, `bar` | `line` |
-| sparklineValueFmt | Formatting for tooltip values | false | format code | same as fmt if supplied |
-| sparklineDateFmt | Formatting for tooltip dates | false | format code | `YYYY-MM-DD` |
-| sparklineColor | Color of visualization | false | CSS name, hexademical, RGB, HSL | - |
-| sparklineYScale | Whether to truncate the y-axis of the chart to enhance visibility | false | `true`, `false` | `false` |
-| connectGroup | Group name to connect this sparkline to other charts for synchronized tooltip hovering. Charts with the same `connectGroup` name will become connected | false | string | - |
-| description | Adds an info icon with description tooltip on hover | false | string | - |
+| value | Column or expression to pull the main value from | true | column name, stored expression name, GSQL expression | - |
+| title | Title displayed above the value | false | string | - |
+| subtitle | Subtitle displayed below the title | false | string | - |

package/dist/skills/graphene/references/date-range.md

@@ -0,0 +1,64 @@
+Creates a date range picker with start/end date inputs and optional preset ranges. The selected range can be used to filter queries or in markdown.
+
+Here's an example:
+
+````markdown
+```sql sales
+select date, revenue from orders
+```
+
+<DateRange
+  title="Date Range"
+  name=date_filter
+  data=sales
+  dates=date
+/>
+````
+
+The selected start and end dates are then referenced in GSQL as `$date_filter_start` and `$date_filter_end`. For example:
+
+```sql
+select date, revenue
+from orders
+where date >= $date_filter_start and date < $date_filter_end
+```
+
+Date range selections sync into the page URL query string as `{name}_start` and `{name}_end`, eg. `localhost:4000/my_dashboard?date_filter_start=2024-01-01&date_filter_end=2024-02-01`.
+
+# Attributes
+
+| Attribute | Description | Required | Options | Default |
+|------|-------------|----------|---------|---------|
+| name | Name of the date range, used to reference the selected value elsewhere as `"$name.start"` and `"$name.end"` | true | - | - |
+| data | GSQL query or table name to infer the date domain from | false | query name | - |
+| dates | Column name from the query containing date values, used to determine the min/max of the domain | false | column name | - |
+| start | Initial start date | false | date string or Date | - |
+| end | Initial end date | false | date string or Date | - |
+| defaultValue | Preset label to apply on first load (e.g., `"Last 30 Days"`) | false | preset label | - |
+| presetRanges | List of preset range labels to show in the dropdown. Accepts a comma-separated string or an array. | false | preset labels | See defaults below |
+| title | Title to display above the input | false | string | - |
+| description | Subtitle text displayed below the title | false | string | - |
+
+# Preset ranges
+
+By default, the following presets are available in the dropdown:
+
+- Last 7 Days
+- Last 30 Days
+- Last 90 Days
+- Last 365 Days
+- Last Month
+- Last Year
+- Month to Date
+- Month to Today
+- Year to Date
+- Year to Today
+- All Time
+
+The `Last N Days` and `Last N Months` patterns are also supported for any number N (e.g., `"Last 14 Days"`, `"Last 6 Months"`).
+
+You can override the list with the `presetRanges` prop:
+
+```markdown
+<DateRange name="date_filter" presetRanges="Last 7 Days, Last 30 Days, Last Year" />
+```

package/dist/skills/graphene/references/dropdown.md

@@ -24,6 +24,8 @@ from orders
 where status = $status_dropdown
 ```
 
+Dropdown selections also sync into the page URL query string. Single-select dropdowns use one key, and multi-select dropdowns repeat the key for each selected value.
+
 # Attributes
 
 | Attribute | Description | Required | Options | Default |
@@ -31,16 +33,13 @@ where status = $status_dropdown
 | name | Name of the dropdown, used to reference the selected value elsewhere as `"$name"` | true | - | - |
 | data | GSQL query or table name | false | query name | - |
 | value | Column name from the query containing values to pick from | false | column name | - |
-| multiple | Enables multi-select which returns a list | false | `true`, `false` | `false` |
+| multiple | Enables multi-select which returns a list and syncs repeated values into the URL query string | false | `true`, `false` | `false` |
 | defaultValue | Value to use when the dropdown is first loaded. Must be one of the options in the dropdown. Lists supported for multi-select. | false | value from dropdown, list of values e.g. `"Value 1, Value 2"` | - |
 | selectAllByDefault | Selects and returns all values, multiple attribute required | false | `true`, `false` | `false` |
 | noDefault | Stops any default from being selected. Overrides any set `defaultValue`. | false | boolean | `false` |
 | disableSelectAll | Removes the `"Select all"` button. Recommended for large datasets. | false | boolean | `false` |
 | label | Column name from the query containing labels to display instead of the values (e.g., you may want to have the drop-down use `customer_id` as the value, but show `customer_name` to your users) | false | column name | Uses the column in value |
 | title | Title to display above the dropdown | false | string | - |
-| order | Column to sort options by, with optional ordering keyword | false | column name [ `asc`, `desc` ] | Ascending based on dropdown value (or label, if specified) |
-| where | SQL where fragment to filter options by (e.g., where sales > 40000) | false | SQL where clause | - |
-| hideDuringPrint | Hide the component when the report is printed | false | `true`, `false` | `true` |
 | description | Adds an info icon with description tooltip on hover | false | string | - |
 
 # DropdownOption sub-component

package/dist/skills/graphene/references/echarts.md

@@ -0,0 +1,162 @@
+Use `ECharts` when you need chart behavior that goes beyond the built-in chart components.
+
+Graphene charts are powered by Apache ECharts (v6). In markdown, you define the ECharts option object **inside the `<ECharts>` tag body**.
+
+Example:
+
+```markdown
+<ECharts data="sales_by_month">
+  title: {text: "Revenue"},
+  tooltip: {trigger: "axis"},
+  series: [{type: "line", encode: {x: "month", y: "revenue"}}],
+</ECharts>
+```
+
+# Attributes
+
+| Attribute | Description | Required | Options | Default |
+|----------|-------------|----------|---------|---------|
+| data | GSQL query or table name | true | query/table name | - |
+| height | Chart height in px or CSS size string | false | number, string | `240px` |
+| width | Chart width in px or CSS size string | false | number, string | `100%` |
+| renderer | ECharts renderer | false | `svg`, `canvas` | `svg` |
+
+## Config body syntax
+
+Inside `<ECharts>...</ECharts>`, Graphene parses the config as JSON5:
+- Unquoted keys are allowed (`xAxis: {}`)
+- Trailing commas are allowed
+- You can wrap the whole thing in `{ ... }` or omit the outer braces
+- Inline Javascript is not allowed
+
+## What Graphene handles automatically
+
+You don't need to configure these — Graphene applies them by default:
+
+- Axes: created if missing, types inferred from field metadata (time, category, value), tick formatting applied
+- Layout: grid padding computed to prevent title/legend overlap
+- Style: color palette, fonts, axis borders, split lines, and series marker defaults (via the Graphene theme)
+
+Your config typically only needs to specify the series `type`, `encode` mappings, and any explicit overrides to the above.
+
+## Encode fields by series type
+
+Each series type maps columns via `encode`. Graphene accepts:
+
+| Series type | Encode fields |
+|-------------|---------------|
+| `bar`, `line`, `scatter`, `candlestick`, `heatmap`, `effectScatter` | `x`, `y`, `splitBy` |
+| `pie`, `funnel` | `itemName`, `value` |
+| `treemap` | `itemName`, `value` |
+| `sankey`, `chord` | `source`, `target`, `value` |
+| `themeRiver` | `single`, `value`, `seriesName` |
+
+For a beeswarm, use a `scatter` series and set `jitter` (plus optional `jitterOverlap`/`jitterMargin`) on the categorical axis.
+
+## Customizing with split hints
+
+To keep configs concise, Graphene supports a split hint:
+
+- `encode.splitBy: "field"`: split one series template into one series per distinct field value
+- `encode.splitBy: ["groupField", "stackField"]` (bar only): expands to grouped+stacked bars, where the first field groups and the second stacks
+- with a single split field, `series.stack` decides stacked vs grouped behavior
+- `stackPercentage: true`: convert stacked values to percentages (100% stacked)
+
+Examples:
+
+```markdown
+<ECharts data="sales_by_month_and_region">
+  title: {text: "Revenue by Region"},
+  series: [{
+    type: 'bar',
+    encode: {x: 'month', y: 'revenue', splitBy: 'region'},
+    stack: 'revenue-stack',
+    stackPercentage: true
+  }]
+</ECharts>
+
+<!-- Char that is both grouped by region and stacked by channel -->
+<ECharts data="sales_by_month_region_channel">
+  title: {text: "Revenue by Region and Channel"},
+  series: [{
+    type: 'bar',
+    encode: {x: 'month', y: 'revenue', splitBy: ['region', 'channel']},
+    stack: 'revenue-stack',
+    stackPercentage: true
+  }]
+/>
+```
+
+## More examples
+
+### Heatmap
+
+```markdown
+<ECharts data="delay_by_hour_and_day" height=520px>
+  title: {text: "Avg Delay by Hour & Day of Week (min)"},
+  tooltip: {trigger: 'item'},
+  visualMap: {
+    min: -5, max: 30,
+    calculable: true,
+    orient: 'horizontal',
+    left: 'center',
+    bottom: 4,
+    inRange: {color: ['#5B8F9E', '#e4eff3', '#D4A94C']},
+  },
+  xAxis: {type: 'category', position: 'top', data: ['Sun','Mon','Tue','Wed','Thu','Fri','Sat']},
+  yAxis: {type: 'category', inverse: true, data: ['6am','7am','8am','9am','10am','11am','12pm']},
+  series: [{type: 'heatmap', encode: {x: 'day_label', y: 'hour_label', value: 'avg_delay'}}],
+</ECharts>
+```
+
+### Scatter/bubble
+
+```markdown
+<ECharts data="airport_stats" height=480px>
+  title: {text: "Departure vs Arrival Delay by Airport"},
+  tooltip: {trigger: 'item'},
+  visualMap: {
+    dimension: 'flight_count',
+    type: 'continuous',
+    min: 0, max: 3000,
+    inRange: {symbolSize: [4, 32]},
+    show: false,
+  },
+  xAxis: {type: 'value', name: 'Avg Departure Delay (min)', nameLocation: 'middle', nameGap: 22},
+  yAxis: {type: 'value', name: 'Avg Arrival Delay (min)', nameLocation: 'middle', nameGap: 20},
+  series: [{
+    type: 'scatter',
+    encode: {x: 'avg_dep_delay', y: 'avg_arr_delay', itemName: 'code'},
+    tooltip: {formatter: '{b}'},
+  }],
+</ECharts>
+```
+
+### Lollipop
+
+Combine a `pictorialBar` series (the stem) with a `scatter` series (the dot) on a category y-axis.
+
+```markdown
+<ECharts data="avg_delay_by_carrier">
+  title: {text: "Avg Delay by Carrier (min)"},
+  xAxis: {type: 'value'},
+  yAxis: {type: 'category', inverse: true, encode: {y: 'carrier'}},
+  series: [
+    {
+      type: 'pictorialBar',
+      symbol: 'rect',
+      symbolSize: ['100%', 2],
+      symbolPosition: 'end',
+      encode: {x: 'avg_delay', y: 'carrier'},
+    },
+    {
+      type: 'scatter',
+      symbolSize: 12,
+      encode: {x: 'avg_delay', y: 'carrier', itemName: 'carrier'},
+      label: {show: true, position: 'right', formatter: '{b}', fontSize: 11},
+    },
+  ],
+</ECharts>
+```
+
+For common chart types, prefer `BarChart`, `LineChart`, `AreaChart`, `ScatterPlot`, and `PieChart`. Use `ECharts` when you need deeper customization.