trevl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 18b85bde0894ec3023141a8e20862d0bc2641ece9cab486b0743d765fdae45e3
+  data.tar.gz: 57b043cd9f75abdd5a8a3b4f63276c9526c7893f059eaa7d9acd19d9c68de0df
+SHA512:
+  metadata.gz: c06f1cffb20b1ea8185d89425395702a44c443f1f4928011876f8eccc5f04218a413c25edd610613abc35da88c9694b91a60304158f0b48a72239cdb1963d090
+  data.tar.gz: 4224f7d0f8675a6de3ceca6c3665f9df884275b01d4efe835621b10e81bd4a0e0b7708651b7953908d6e1c39b875da0f4c4f27688d1d889c8c010ebf78c6c77b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trendence Institut GmbH
+
+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.

data/NOTICE

@@ -0,0 +1,9 @@
+Third-party notice
+
+This project renders charts with Highcharts, which is NOT covered by the MIT
+licence in LICENSE and is not distributed with this project. Highcharts is
+commercial software by Highsoft AS. Using it, whether from the CDN or from a
+local copy, requires a valid licence from Highsoft for anything beyond the
+uses their terms grant for free.
+
+See https://www.highcharts.com/license

data/README.md

@@ -0,0 +1,431 @@
+<p align="center">
+  <img src="assets/trevl-logo.svg" alt="TREVL" width="220" />
+  <br /><br />
+  <img src="assets/trendence-logo.svg" alt="Trendence" width="140" />
+</p>
+
+<h3 align="center">Write YAML, get Highcharts.</h3>
+
+<p align="center">
+  <a href="https://trevl.trendence.com">DSL Documentation</a> &middot;
+  <a href="notebooks/demo.ipynb">Demo Notebook</a> &middot;
+  <a href="https://github.com/trendence/trevl">GitHub</a>
+</p>
+
+---
+
+[Trendence](https://www.trendence.com) is a Berlin-based HR data and analytics company. We believe data visualization should be modern, AI-ready, and accessible. That's why we've been building TREVL -- the **TR**Endence **V**isualization **L**anguage -- a custom DSL designed to make chart creation as simple as writing a few lines of YAML. A language humans easily can use and robots love.
+
+## AI-First Design
+
+TREVL is built for humans and machines. Every feature is designed so that LLMs can generate, validate, and iterate on visualizations autonomously:
+
+- **`Trevl.schema_reference`** -- compact reference (~1500 tokens) optimized for system prompts
+- **`Trevl.validate(yaml)`** -- structured error feedback for self-correction loops
+- **`Trevl.examples`** -- 10 annotated examples for few-shot learning
+- **`Trevl::DataSource.for("name").field_names("endpoint")`** -- discover available data fields
+- **[`llms.txt`](llms.txt)** -- machine-readable reference in the repo root
+- **JSON Schema** -- formal validation for editors, CI, and AI agents
+
+```ruby
+# 1. Discover: what fields does this endpoint return?
+Trevl::DataSource.for("myapi").field_names("salary")
+# => ["q10", "q50", "q90"]
+
+# 2. Reference: get the compact TREVL spec for a system prompt
+Trevl.schema_reference
+# => "# TREVL — TREndence Visualization Language\n..."
+
+# 3. Examples: few-shot learning material
+Trevl.examples.first
+# => {name: "bar_chart", description: "Simple bar chart...", yaml: "..."}
+
+# 4. Validate: catch errors before rendering
+Trevl.validate(yaml).errors
+# => ["[my_chart] Missing required field(s): api, highchartsData (at )"]
+
+# 5. Render: YAML → Highcharts JSON
+Trevl.render(yaml)
+```
+
+## Features
+
+- **Declarative YAML** -- define charts, scores, tables, and filters without writing JavaScript
+- **Pluggable data sources** -- REST APIs, CubeJS, static/in-memory data, or build your own
+- **Computed fields** -- per-row JavaScript transformations via ExecJS
+- **Postprocess** -- full-dataset transforms (sort, filter, aggregate) in JavaScript
+- **Template inheritance** -- share chart styles with deep merge
+- **JSON Schema validation** -- catch errors before rendering
+- **iRuby notebooks** -- render interactive Highcharts directly in Jupyter
+- **Fully offline** -- bundled Highcharts JS, no CDN needed
+- **Standalone** -- no Rails, no framework dependencies
+
+## Installation
+
+```ruby
+gem "trevl", github: "trendence/trevl"
+```
+
+**Prerequisites:** Ruby >= 3.1, Node.js (`brew install node`) for computed fields.
+
+## Quick Start
+
+```ruby
+require "trevl"
+
+# 1. Register a data source
+Trevl::DataSource.register("demo", Trevl::DataSource::Static.new(
+  data: {
+    "pirates" => {
+      "data" => [
+        {"name" => "Guybrush",  "barrels" => 12},
+        {"name" => "LeChuck",   "barrels" => 47},
+        {"name" => "Elaine",    "barrels" => 3},
+        {"name" => "Stan",      "barrels" => 28},
+        {"name" => "Murray",    "barrels" => 0}
+      ]
+    }
+  }
+))
+
+# 2. Render
+results = Trevl.render(<<~YAML)
+  components:
+  - id: rum_consumption
+    type: chart
+    api: demo
+    highchartsData:
+      chart:
+        type: bar
+      title:
+        text: Annual Rum Consumption by Pirate (Barrels)
+      colors: ["#8B4513"]
+      series:
+      - name: Rum (barrels)
+        data:
+          x: "$pirates.data.name"
+          y: "$pirates.data.barrels"
+YAML
+
+# 3. Done -- results.first["highchartsData"] is ready for Highcharts
+```
+
+<p align="center">
+  <img src="docs/screenshots/01_bar_chart.png" alt="Bar Chart" width="600" />
+</p>
+
+## Examples Gallery
+
+<table>
+<tr>
+<td><img src="docs/screenshots/02_column_chart.png" alt="Column Chart" width="400" /></td>
+<td><img src="docs/screenshots/03_line_chart.png" alt="Line Chart" width="400" /></td>
+</tr>
+<tr>
+<td><img src="docs/screenshots/04_pie_chart.png" alt="Pie Chart" width="400" /></td>
+<td><img src="docs/screenshots/05_computed_fields.png" alt="Computed Fields" width="400" /></td>
+</tr>
+<tr>
+<td><img src="docs/screenshots/06_postprocess_top_n.png" alt="Postprocess Top-N" width="400" /></td>
+<td><img src="docs/screenshots/10_multi_series.png" alt="Multi Series" width="400" /></td>
+</tr>
+</table>
+
+See [`examples/`](examples/) for the YAML source of each chart.
+
+## HTML Export
+
+Render TREVL to an HTML file:
+
+```ruby
+html = Trevl.render_to_html(yaml, width: 1000, height: 500)
+File.write("chart.html", html)
+```
+
+The output is a complete HTML document that pulls Highcharts from the CDN. Point `highcharts_path` at a local copy (see [Highcharts](#highcharts)) and it is embedded inline instead, which makes the file self-contained and usable offline. Open it in any browser, or take a screenshot for AI agents:
+
+```ruby
+# Grover gem (Puppeteer wrapper)
+Grover.new(html).to_png
+
+# Ferrum (Chrome DevTools Protocol)
+browser = Ferrum::Browser.new
+browser.content = html
+browser.screenshot(path: "chart.png")
+
+# Playwright MCP (for AI agents)
+# browser_navigate → browser_take_screenshot
+```
+
+## iRuby Notebooks
+
+```ruby
+require "trevl"
+require "trevl/notebook"
+
+nb = Trevl::Notebook.new
+
+nb.chart(<<~YAML, data: {"salary" => {"data" => [...]}})
+  components:
+  - id: chart
+    type: chart
+    api: static
+    highchartsData:
+      chart:
+        type: column
+      series:
+      - data:
+          x: "$salary.data.level"
+          y: "$salary.data.value"
+YAML
+```
+
+Highcharts is bundled -- charts render offline. See [`notebooks/demo.ipynb`](notebooks/demo.ipynb) for 5 working examples.
+
+## Data Sources
+
+### Static (in-memory)
+
+```ruby
+Trevl::DataSource.register("mydata", Trevl::DataSource::Static.new(
+  data: {"endpoint" => {"data" => [...], "meta" => {...}}}
+))
+```
+
+### REST API
+
+```ruby
+Trevl::DataSource.register("myapi", Trevl::DataSource::Api.new(
+  base_url: "https://api.example.com/v1",
+  auth: Trevl::Auth::BearerToken.new(ENV["API_TOKEN"])
+))
+```
+
+### CubeJS
+
+```ruby
+Trevl::DataSource.register("cube", Trevl::DataSource::Cube.new(
+  url: "https://cube.example.com/cubejs-api/v1",
+  token: ENV["CUBE_TOKEN"]
+))
+```
+
+### Custom
+
+```ruby
+class MySource < Trevl::DataSource::Base
+  def fetch(endpoint, params = {}, resource: nil)
+    {"data" => MyDB.query(endpoint, params), "meta" => {}}
+  end
+end
+
+Trevl::DataSource.register("db", MySource.new)
+```
+
+### Per-render injection
+
+Instead of registering globally, pass data directly to a render call.
+Per-render data takes precedence over the registry and never touches shared
+state — the right choice when the data differs per request (e.g. web apps
+serving concurrent users).
+
+For inline rows, pass the raw hash as `data:` — it answers any `api:` name in
+the document, and components may omit `api:` entirely:
+
+```ruby
+Trevl.render(yaml, data: {"scores" => rows_for_this_request})
+Trevl.render_to_html(yaml, data: {"scores" => rows_for_this_request})
+```
+
+For full control (multiple sources, API/Cube instances), pass `data_sources:`
+— entries win over `data:` for their name:
+
+```ruby
+source = Trevl::DataSource::Api.new(base_url: "https://api.example.com/v1")
+
+Trevl.render(yaml, data_sources: {"mydata" => source})
+```
+
+## Validation
+
+Validate TREVL YAML before rendering — catch errors early, not at render time.
+
+```ruby
+result = Trevl.validate(<<~YAML)
+  components:
+  - id: my_chart
+    type: chart
+YAML
+
+result.valid?   # => false
+result.errors   # => ["[my_chart] Missing required field(s): api, highchartsData (at )"]
+```
+
+Powered by [JSON Schema (draft 2020-12)](lib/trevl/schema/component.json) -- covers all 5 component types with conditional validation. The schema files work standalone in VS Code, CI pipelines, or any JSON Schema-compatible tool.
+
+Ideal for AI agents: generate TREVL, validate, self-correct, render.
+
+Full docs: [trevl.trendence.com/validation](https://trevl.trendence.com/validation)
+
+## YAML Reference
+
+### Component Types
+
+| Type | Description |
+|------|-------------|
+| `chart` | Highcharts visualization (bar, column, line, pie, ...) |
+| `score` | Single KPI value with optional unit |
+| `table` | Data table with column definitions |
+| `text` | Static text / HTML content |
+| `filter` | Filter options bound to data |
+
+### Variable References
+
+```yaml
+"$endpoint.data.fieldName"             # data row field
+"$endpoint.meta.fieldName"             # metadata field
+"$resource.endpoint.data.fieldName"    # with resource qualifier
+"$computedFieldName"                   # computed field shorthand
+```
+
+### Computed Fields
+
+Per-row JavaScript expressions:
+
+```yaml
+computed:
+- name: color
+  arguments:
+    val: "$salary.data.value"
+  code: 'val > 60000 ? "#003F85" : "#ccc"'
+```
+
+### Postprocess
+
+Full-dataset JavaScript transforms:
+
+```yaml
+postprocess: |
+  $result = $result
+    .sort((a, b) => b.value - a.value)
+    .slice(0, 10);
+```
+
+### Templates
+
+```ruby
+Trevl.template_store.register("blue_bar", {
+  "highchartsData" => {
+    "chart" => {"type" => "bar"},
+    "colors" => ["#003F85"]
+  }
+})
+```
+
+```yaml
+- id: my_chart
+  template: blue_bar
+  highchartsData:
+    title:
+      text: My Chart
+```
+
+Deep merge: component overrides template at the same path.
+
+## Auth
+
+```ruby
+# Bearer token
+auth = Trevl::Auth::BearerToken.new("token")
+
+# Custom -- any object with #apply(headers, url:)
+class MyAuth
+  def apply(headers, url: nil)
+    headers["Authorization"] = "Bearer #{fetch_token}"
+  end
+end
+```
+
+## Configuration
+
+```ruby
+Trevl.configure do |c|
+  c.logger = Logger.new($stdout, level: :info)
+  c.template_store = my_custom_store
+end
+```
+
+## Highcharts
+
+TREVL produces Highcharts configuration; it does not ship Highcharts. Highcharts is
+commercial software by [Highsoft](https://www.highcharts.com/license) and is
+deliberately not bundled here, so using it requires your own licence.
+
+`Trevl.render` returns plain configuration hashes and never touches Highcharts at all.
+Only the HTML export and the notebook display load it, and by default they reference
+the CDN:
+
+```ruby
+Trevl.configure do |c|
+  c.highcharts_url = "https://code.highcharts.com/11.4.0/highcharts.js"  # default
+  c.highcharts_modules = ["https://code.highcharts.com/11.4.0/highcharts-more.js"]
+end
+```
+
+Set `highcharts_path` to a local file and it gets inlined instead of linked, which is
+what you want for offline use or air-gapped rendering:
+
+```ruby
+Trevl.configure do |c|
+  c.highcharts_path = "/opt/highcharts/highcharts.js"
+end
+```
+
+`highcharts_modules` accepts URLs and local paths under the same rule: a path is
+inlined, a URL is referenced.
+
+### In a Rails app
+
+If your app already renders charts, it almost certainly ships Highcharts through the
+asset pipeline. In that case, do nothing: pass the hash from `Trevl.render` to your
+existing frontend and let the bundle you already load draw it.
+
+```ruby
+components = Trevl.render(yaml, data: {"rows" => rows})
+# hand components.first["highchartsData"] to your Stimulus controller
+```
+
+Only the server-side HTML export needs its own copy. The leanest way to give it one is
+to reuse the file the asset pipeline already has:
+
+```ruby
+# config/initializers/trevl.rb
+Trevl.configure do |c|
+  local = Rails.root.join("vendor/javascript/highcharts.js")
+  c.highcharts_path = local if local.exist?
+end
+```
+
+Without that initializer the export falls back to the CDN, which is fine for anything
+that renders in a browser with network access.
+
+## Development
+
+```bash
+bin/setup              # install dependencies
+bundle exec rspec      # 140 specs
+bundle exec standardrb # lint
+bin/console            # interactive console
+```
+
+## Language Specification
+
+The full TREVL v3.0 specification lives at **[trevl.trendence.com](https://trevl.trendence.com)** -- covering component schemas, query definitions, filter operators, computed fields, postprocess patterns, template inheritance, and data source integration.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).
+
+Highcharts is not covered by that licence and is not distributed with this project.
+Using it requires a licence from Highsoft; see [NOTICE](NOTICE) and
+[highcharts.com/license](https://www.highcharts.com/license).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/assets/trendence-logo.svg

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg aria-hidden="true" enable-background="new 0 0 733.8 140.4" version="1.1" width="733" height="140" viewBox="0 0 733 140" xml:space="preserve" xmlns="http://www.w3.org/2000/svg">
+  <g fill="#006ADF">
+    <path d="m542.9 108.6v-63.3h9s3.3-0.1 5.7 2.9 2.3 4.7 2.3 4.7 4.7-7.6 17.2-7.6 22.1 9.3 22.1 21.8v41.4h-9.7s-7.6-0.8-7.7-9.6v-26.9s0.4-11.4-9.9-11.4-11.8 11.4-11.8 14.9v33.2h-17.2z" />
+    <path d="m332.9 108.6v-63.3h9s3.3-0.1 5.7 2.9 2.3 4.7 2.3 4.7 4.7-7.6 17.2-7.6 22.1 9.3 22.1 21.8v41.4h-9.7s-7.6-0.8-7.7-9.6v-26.9s0.4-11.4-9.9-11.4-11.8 11.4-11.8 14.9v33.2h-17.2z" />
+    <path d="m731.7 83.2s0.4-1.3 0.4-6-1.2-14.1-8.8-22.6-16.8-10.2-23.1-10.2-15.7 2.1-23.2 10.8-9.8 20.1-7.6 30.2 8.3 17.7 19.8 22.3 24.6 1.2 30.8-2.7 8.7-7.4 8.7-7.4l-11.7-9s-5.4 6.2-14 6.2c0 0-8.8 0.4-13.5-4.3-3.8-3.9-3.6-7.2-3.6-7.2h45.8zm-31.4-23.9c11.6 0 13.9 10.5 13.9 10.5h-27.6s2-10.5 13.7-10.5z" />
+    <path d="m532.7 83s0.4-1.3 0.4-6-1.2-14.1-8.8-22.6-16.8-10.2-23.1-10.2-15.7 2.1-23.2 10.8-9.8 20.1-7.6 30.3 8.3 17.7 19.8 22.3 24.6 1.2 30.8-2.7 8.7-7.4 8.7-7.4l-11.7-9.1s-5.4 6.2-14 6.2c0 0-8.8 0.4-13.5-4.3-3.8-3.9-3.6-7.2-3.6-7.2h45.8zm-31.4-24c11.6 0 13.9 10.5 13.9 10.5h-27.6s2-10.5 13.7-10.5z" />
+    <path d="m323.4 83.2s0.4-1.3 0.4-6-1.2-14.1-8.8-22.6-16.8-10.1-23-10.1-15.7 2.1-23.2 10.8-9.8 20.1-7.6 30.2 8.3 17.7 19.8 22.3 24.6 1.2 30.8-2.7 8.7-7.4 8.7-7.4l-11.6-9.2s-5.4 6.2-14 6.2c0 0-8.8 0.4-13.5-4.3-3.8-3.9-3.6-7.2-3.6-7.2h45.6zm-31.4-23.9c11.6 0 13.9 10.5 13.9 10.5h-27.6s2.1-10.5 13.7-10.5z" />
+    <path d="m428.8 45.5c5.8 0 11.2 1.6 15.9 4.3v-31.3h16.7l0.1 90.5h-8.2s-5.3 0-7.5-4.7c-4.9 3.1-10.7 4.9-17 4.9-17.6 0-31.9-14.3-31.9-31.8 0.1-17.6 14.4-31.9 31.9-31.9zm0 47.9c8.9 0 16.1-7.2 16.1-16.1s-7.2-16.1-16.1-16.1-16.1 7.2-16.1 16.1 7.3 16.1 16.1 16.1z" />
+    <path d="m173.4 45.6v-16.8h17.7v16.8h10.2v13.1h-10.3v28.3s-0.4 5.4 5.2 5.4h8v16.4h-12.9s-8.5 0.5-14.1-5.6c-4.3-4.7-3.9-12.4-3.9-12.4v-32h-10.3v-13.2h10.4z" />
+    <path d="m256.7 62.4l-2.4 0.1s-10.3 0.1-14.8 6.1c-4.3 5.7-3.5 12.4-3.5 12.4v27.4h-17.6v-63h9.6s2.7-0.2 5.2 3c2.5 3.1 2.1 5.6 2.1 5.6s1-3.6 5.8-6.5 10.2-2.7 10.2-2.7h5.6v17.4l-0.2 0.2z" />
+    <path d="m651.6 87.2c-2.9 3.9-7.6 6.4-12.9 6.4-8.9 0-16.1-7.2-16.1-16.1s7.2-16.1 16.1-16.1c5.4 0 10.2 2.7 13.2 6.8l12.9-9c-5.8-8.2-15.3-13.6-26.1-13.6-17.6 0-31.8 14.3-31.8 31.8 0 17.6 14.3 31.8 31.8 31.8 10.5 0 19.8-5.1 25.6-12.9l-12.7-9.1z" />
+    <circle cx="69.7" cy="69.5" r="13.4" />
+    <path d="m69.7 28.8c-22.5 0-40.7 18.2-40.7 40.7 0 8.1 2.4 15.7 6.5 22 0.1 0.1 0.1 0.2 0.2 0.3 0 0 0 0.1 0.1 0.1 1.5 2.2 4 3.6 6.9 3.6 4.6 0 8.3-3.7 8.3-8.3 0-1.7-0.5-3.2-1.4-4.6 0-0.1-0.1-0.1-0.1-0.2-2.4-3.7-3.8-8.2-3.8-13 0-13.3 10.8-24.1 24.1-24.1s24.1 10.8 24.1 24.1-10.8 24.1-24.1 24.1c-0.9 0-1.7 0-2.5-0.1h-0.1-0.1-0.8c-4.6 0-8.3 3.7-8.3 8.3 0 4.3 3.2 7.8 7.3 8.3h0.4c1.3 0.1 2.7 0.2 4.1 0.2 22.5 0 40.7-18.2 40.7-40.7s-18.3-40.7-40.8-40.7z" />
+    <path d="m69.7 0.6c-6.6 0-13 1-19.1 2.7-0.5 0.1-0.9 0.2-1.3 0.4-3.3 1.2-5.7 4.4-5.7 8.1 0 4.8 3.9 8.7 8.7 8.7 0.7 0 1.3-0.1 1.9-0.2 0.4-0.1 0.7-0.2 1-0.3 4.6-1.3 9.5-2.1 14.5-2.1 28.5 0 51.6 23.1 51.6 51.6s-23.1 51.6-51.6 51.6-51.6-23.1-51.6-51.6c0-14.7 6.2-28 16.1-37.4 0.2-0.1 0.3-0.3 0.5-0.4 1.5-1.6 2.4-3.7 2.4-6 0-4.8-3.9-8.7-8.7-8.7-2 0-3.9 0.7-5.4 1.9-0.4 0.3-0.8 0.7-1.1 1-12.9 12.5-21.1 30.1-21.1 49.6 0 38 30.8 68.9 68.9 68.9s68.9-30.8 68.9-68.9-30.8-68.9-68.9-68.9z" />
+  </g>
+</svg>

data/assets/trevl-logo.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 92 36" width="92" height="36">
+  <!-- TREVL logo: letters in Trendence blue, E = colorful bar chart -->
+
+  <!-- T - Trendence blue -->
+  <text x="0" y="27" font-family="Inter, -apple-system, sans-serif" font-size="28" font-weight="700" fill="#006ADF" letter-spacing="-1">T</text>
+
+  <!-- R - Trendence blue -->
+  <text x="17" y="27" font-family="Inter, -apple-system, sans-serif" font-size="28" font-weight="700" fill="#006ADF" letter-spacing="-1">R</text>
+
+  <!-- E as three horizontal bars in brand colors -->
+  <rect x="38" y="7" width="18" height="5" rx="1.5" fill="#8B3A9F"/>
+  <rect x="38" y="14" width="12" height="5" rx="1.5" fill="#E8922F"/>
+  <rect x="38" y="21" width="16" height="5" rx="1.5" fill="#E85D3A"/>
+
+  <!-- V - Trendence blue -->
+  <text x="58" y="27" font-family="Inter, -apple-system, sans-serif" font-size="28" font-weight="700" fill="#006ADF" letter-spacing="-1">V</text>
+
+  <!-- L - Trendence blue -->
+  <text x="76" y="27" font-family="Inter, -apple-system, sans-serif" font-size="28" font-weight="700" fill="#006ADF" letter-spacing="-1">L</text>
+</svg>

data/examples/01_bar_chart.yml

@@ -0,0 +1,16 @@
+# Simple bar chart. Use when you want horizontal bars comparing categories.
+components:
+- id: rum_consumption
+  type: chart
+  api: demo
+  highchartsData:
+    chart:
+      type: bar
+    title:
+      text: Annual Rum Consumption by Pirate (Barrels)
+    colors: ["#8B4513"]
+    series:
+    - name: Rum (barrels)
+      data:
+        x: "$pirates.data.name"
+        y: "$pirates.data.barrels"

data/examples/02_column_chart.yml

@@ -0,0 +1,19 @@
+# Vertical column chart. Use for comparing values across categories side by side.
+components:
+- id: treasure_haul
+  type: chart
+  api: demo
+  highchartsData:
+    chart:
+      type: column
+    title:
+      text: Treasure Haul by Quarter (Doubloons)
+    colors: ["#DAA520"]
+    plotOptions:
+      column:
+        borderRadius: 4
+    series:
+    - name: Doubloons
+      data:
+        x: "$loot.data.quarter"
+        y: "$loot.data.doubloons"

data/examples/03_line_chart.yml

@@ -0,0 +1,21 @@
+# Line chart for time series. Use when showing trends over time.
+components:
+- id: monkey_sightings
+  type: chart
+  api: demo
+  highchartsData:
+    chart:
+      type: line
+    title:
+      text: Three-Headed Monkey Sightings per Month
+    xAxis:
+      type: category
+    yAxis:
+      title:
+        text: Sightings
+    series:
+    - name: Sightings
+      color: "#2E7D32"
+      data:
+        x: "$monkeys.data.month"
+        y: "$monkeys.data.sightings"

data/examples/04_pie_chart.yml

@@ -0,0 +1,15 @@
+# Pie chart for proportions. Use when showing parts of a whole.
+components:
+- id: mutiny_vote
+  type: chart
+  api: demo
+  highchartsData:
+    chart:
+      type: pie
+    title:
+      text: Mutiny Board Election Results
+    series:
+    - name: Votes
+      data:
+        name: "$candidates.data.candidate"
+        y: "$candidates.data.votes"

data/examples/05_computed_fields.yml

@@ -0,0 +1,26 @@
+# Computed fields with conditional coloring. Use when you need per-row logic.
+# Arguments bind $references to JS variables. Code is a JS expression.
+# Computed field results are accessible as row fields via $endpoint.data.fieldName.
+components:
+- id: insult_mastery
+  type: chart
+  api: demo
+  computed:
+  - name: color
+    arguments:
+      val: "$pirates.data.skill"
+    code: 'val > 80 ? "#2E7D32" : val > 50 ? "#E65100" : "#C62828"'
+  highchartsData:
+    chart:
+      type: bar
+    title:
+      text: Insult Sword Fighting Skill Rating
+    plotOptions:
+      bar:
+        colorByPoint: true
+    series:
+    - name: Skill
+      data:
+        x: "$pirates.data.name"
+        y: "$pirates.data.skill"
+        color: "$pirates.data.color"

data/examples/06_postprocess_top_n.yml

@@ -0,0 +1,21 @@
+# Postprocess: sort and take top N. Use when you need to filter/sort the full dataset.
+# $result is the data array. Reassign it with the transformed result.
+components:
+- id: top_islands
+  type: chart
+  api: demo
+  postprocess: |
+    $result = $result
+      .sort(function(a, b) { return b.buried - a.buried; })
+      .slice(0, 5);
+  highchartsData:
+    chart:
+      type: bar
+    title:
+      text: Top 5 Islands by Buried Treasure
+    colors: ["#DAA520"]
+    series:
+    - name: Chests buried
+      data:
+        x: "$islands.data.name"
+        y: "$islands.data.buried"

data/examples/07_score_kpi.yml

@@ -0,0 +1,13 @@
+# Score component for a single KPI value. Use for dashboards with key numbers.
+components:
+- id: crew_morale
+  type: score
+  api: demo
+  display:
+    value: "$morale.data.score"
+    unit: "%"
+    header:
+      title: Crew Morale
+    format:
+      minimumFractionDigits: 0
+      maximumFractionDigits: 0