trevl 0.1.0

data/llms.txt

@@ -0,0 +1,171 @@
+# TREVL — TREndence Visualization Language
+
+> Write YAML, get Highcharts. AI-first Ruby gem for declarative data visualization.
+
+## What is TREVL?
+
+TREVL is a YAML-based DSL that turns declarative component definitions into Highcharts JSON.
+You describe what data to fetch, how to transform it, and how to display it.
+The engine does the rest.
+
+## Install
+
+```ruby
+gem "trevl", github: "trendence/trevl"
+```
+
+## Component Types
+
+| Type   | Required fields                    |
+|--------|------------------------------------|
+| chart  | id, type, api, highchartsData      |
+| score  | id, type, api, display             |
+| table  | id, type, api, tableData           |
+| text   | id, type                           |
+| filter | id, type, api, filters             |
+
+## Variable Reference Syntax
+
+```
+$endpoint.data.fieldName             → row field value
+$endpoint.meta.fieldName             → metadata value
+$resource.endpoint.data.fieldName    → with resource qualifier
+$computedFieldName                   → computed field shorthand
+```
+
+## Minimal Chart Example
+
+```yaml
+components:
+- id: my_chart
+  type: chart
+  api: my_data_source
+  highchartsData:
+    chart:
+      type: bar
+    title:
+      text: My Chart
+    series:
+    - name: Values
+      data:
+        x: "$endpoint.data.label"
+        y: "$endpoint.data.value"
+```
+
+## Computed Fields (per-row JavaScript)
+
+```yaml
+computed:
+- name: color
+  arguments:
+    val: "$endpoint.data.value"
+  code: 'val > 50 ? "#003F85" : "#ccc"'
+```
+
+## Postprocess (full-dataset JavaScript)
+
+```yaml
+postprocess: |
+  $result = $result
+    .sort(function(a, b) { return b.value - a.value; })
+    .slice(0, 10);
+```
+
+## Templates (inherit + override)
+
+```yaml
+- id: my_chart
+  type: chart
+  api: myapi
+  template: blue_bar
+  highchartsData:
+    title:
+      text: Override Title Only
+    series:
+    - data:
+        y: "$endpoint.data.value"
+```
+
+## Score Example
+
+```yaml
+- id: kpi
+  type: score
+  api: myapi
+  display:
+    value: "$endpoint.data.avg_salary"
+    unit: " EUR"
+    header:
+      title: Average Salary
+```
+
+## Table Example
+
+```yaml
+- id: data_table
+  type: table
+  api: myapi
+  tableData:
+    headers: ["Name", "Value"]
+    columns:
+    - identifier: name
+      value: "$endpoint.data.name"
+    - identifier: val
+      value: "$endpoint.data.value"
+```
+
+## Ruby API
+
+```ruby
+require "trevl"
+
+# Register data source
+Trevl::DataSource.register("demo", Trevl::DataSource::Static.new(
+  data: {"salary" => {"data" => [...], "meta" => {}}}
+))
+
+# Validate
+result = Trevl.validate(yaml)
+result.valid?    # => true/false
+result.errors    # => ["[component_id] Missing required field: api"]
+
+# Render to Highcharts JSON
+results = Trevl.render(yaml)
+results.first["highchartsData"]  # => Highcharts JSON
+
+# Render with inline data (no global registration; answers any api name,
+# components may omit api: — use for request-specific data)
+results = Trevl.render(yaml, data: {"salary" => [{"level" => "q50", "value" => 45000}]})
+
+# Render with per-call data source instances (win over data: and registry)
+results = Trevl.render(yaml, data_sources: {"demo" => Trevl::DataSource::Static.new(
+  data: {"salary" => {"data" => [...], "meta" => {}}}
+)})
+
+# Render to standalone HTML (self-contained, offline)
+html = Trevl.render_to_html(yaml, width: 800, height: 400)
+File.write("chart.html", html)
+
+# Discover data source fields
+Trevl::DataSource.for("demo").field_names("salary")
+# => ["label", "value"]
+
+# Get this reference
+Trevl.schema_reference  # => this text
+
+# List examples
+Trevl.examples  # => [{name: "bar_chart", yaml: "...", description: "..."}, ...]
+```
+
+## Highcharts Chart Types
+
+bar, column, line, area, pie, scatter, spline, areaspline, heatmap, bubble, waterfall, funnel, gauge, solidgauge, bullet
+
+## Filter Operators
+
+equals, notEquals, gt, gte, lt, lte, afterDate, beforeDate, set, notSet, contains, notContains
+
+## Docs
+
+https://trevl.trendence.com
+https://github.com/trendence/trevl

data/notebooks/demo.ipynb

@@ -0,0 +1,312 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "34e8ac3b",
+   "metadata": {},
+   "source": [
+    "# TREVL Demo Notebook\n",
+    "\n",
+    "Interactive data visualization with TREVL YAML and Highcharts."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fd72b046",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))\n",
+    "require 'trevl'\n",
+    "require 'trevl/notebook'\n",
+    "\n",
+    "puts \"TREVL v#{Trevl::VERSION} loaded\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2c27ff7f",
+   "metadata": {},
+   "source": [
+    "## 1. Simple Bar Chart"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5971e608",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "nb = Trevl::Notebook.new\n",
+    "\n",
+    "salary_data = {\n",
+    "  \"salary\" => {\n",
+    "    \"data\" => [\n",
+    "      {\"label\" => \"Junior\",    \"value\" => 42000},\n",
+    "      {\"label\" => \"Mid-Level\", \"value\" => 58000},\n",
+    "      {\"label\" => \"Senior\",    \"value\" => 78000},\n",
+    "      {\"label\" => \"Lead\",      \"value\" => 92000},\n",
+    "      {\"label\" => \"Principal\", \"value\" => 110000}\n",
+    "    ]\n",
+    "  }\n",
+    "}\n",
+    "\n",
+    "nb.chart(<<~YAML, data: salary_data)\n",
+    "  components:\n",
+    "  - id: salary_bar\n",
+    "    type: chart\n",
+    "    api: static\n",
+    "    highchartsData:\n",
+    "      chart:\n",
+    "        type: bar\n",
+    "      title:\n",
+    "        text: Salary by Seniority (EUR)\n",
+    "      colors: [\"#003F85\"]\n",
+    "      yAxis:\n",
+    "        title:\n",
+    "          text: Annual Salary (EUR)\n",
+    "      series:\n",
+    "      - name: Salary\n",
+    "        data:\n",
+    "          x: \"$salary.data.label\"\n",
+    "          y: \"$salary.data.value\"\n",
+    "YAML"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "21bf9b3f",
+   "metadata": {},
+   "source": [
+    "## 2. Column Chart with Computed Fields"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7ccb1bb6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "skills_data = {\n",
+    "  \"skills\" => {\n",
+    "    \"data\" => [\n",
+    "      {\"name\" => \"Python\",     \"demand\" => 85},\n",
+    "      {\"name\" => \"JavaScript\", \"demand\" => 78},\n",
+    "      {\"name\" => \"SQL\",        \"demand\" => 72},\n",
+    "      {\"name\" => \"Java\",       \"demand\" => 65},\n",
+    "      {\"name\" => \"Ruby\",       \"demand\" => 45},\n",
+    "      {\"name\" => \"Go\",         \"demand\" => 38},\n",
+    "      {\"name\" => \"Rust\",       \"demand\" => 22}\n",
+    "    ]\n",
+    "  }\n",
+    "}\n",
+    "\n",
+    "yaml = <<~YAML\n",
+    "  components:\n",
+    "  - id: skills_chart\n",
+    "    type: chart\n",
+    "    api: static\n",
+    "    computed:\n",
+    "    - name: color\n",
+    "      arguments:\n",
+    "        d: \"$skills.data.demand\"\n",
+    "      code: 'd > 70 ? \"#003F85\" : d > 50 ? \"#4A90D9\" : \"#B0C4DE\"'\n",
+    "    highchartsData:\n",
+    "      chart:\n",
+    "        type: column\n",
+    "      title:\n",
+    "        text: Programming Language Demand\n",
+    "      yAxis:\n",
+    "        title:\n",
+    "          text: Demand Score\n",
+    "        max: 100\n",
+    "      plotOptions:\n",
+    "        column:\n",
+    "          borderRadius: 4\n",
+    "          colorByPoint: true\n",
+    "      series:\n",
+    "      - name: Demand\n",
+    "        data:\n",
+    "          x: \"$skills.data.name\"\n",
+    "          y: \"$skills.data.demand\"\n",
+    "          color: \"$color\"\n",
+    "YAML\n",
+    "\n",
+    "nb.chart(yaml, data: skills_data)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "62267b86",
+   "metadata": {},
+   "source": [
+    "## 3. Postprocess: Top-N with Sorting"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "59018534",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cities_data = {\n",
+    "  \"cities\" => {\n",
+    "    \"data\" => [\n",
+    "      {\"city\" => \"Berlin\",     \"vacancies\" => 12500},\n",
+    "      {\"city\" => \"Munich\",     \"vacancies\" => 9800},\n",
+    "      {\"city\" => \"Hamburg\",    \"vacancies\" => 7200},\n",
+    "      {\"city\" => \"Frankfurt\",  \"vacancies\" => 6500},\n",
+    "      {\"city\" => \"Cologne\",    \"vacancies\" => 4800},\n",
+    "      {\"city\" => \"Stuttgart\",  \"vacancies\" => 4200},\n",
+    "      {\"city\" => \"Dusseldorf\", \"vacancies\" => 3900},\n",
+    "      {\"city\" => \"Leipzig\",    \"vacancies\" => 2100}\n",
+    "    ]\n",
+    "  }\n",
+    "}\n",
+    "\n",
+    "nb.chart(<<~YAML, data: cities_data)\n",
+    "  components:\n",
+    "  - id: top_cities\n",
+    "    type: chart\n",
+    "    api: static\n",
+    "    postprocess: |\n",
+    "      $result = $result\n",
+    "        .sort(function(a, b) { return b.vacancies - a.vacancies; })\n",
+    "        .slice(0, 5);\n",
+    "    highchartsData:\n",
+    "      chart:\n",
+    "        type: bar\n",
+    "      title:\n",
+    "        text: Top 5 Cities by Job Vacancies\n",
+    "      colors: [\"#E87722\"]\n",
+    "      series:\n",
+    "      - name: Vacancies\n",
+    "        data:\n",
+    "          x: \"$cities.data.city\"\n",
+    "          y: \"$cities.data.vacancies\"\n",
+    "YAML"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "86f96998",
+   "metadata": {},
+   "source": [
+    "## 4. Score Component"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d6c07d23",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "kpi_data = {\n",
+    "  \"kpi\" => {\n",
+    "    \"data\" => [{\"avg_salary\" => 62100}],\n",
+    "    \"meta\" => {\"median\" => 58000}\n",
+    "  }\n",
+    "}\n",
+    "\n",
+    "nb.score(<<~YAML, data: kpi_data)\n",
+    "  components:\n",
+    "  - id: median_score\n",
+    "    type: score\n",
+    "    api: static\n",
+    "    display:\n",
+    "      value: \"$kpi.data.avg_salary\"\n",
+    "      unit: \" EUR\"\n",
+    "      header:\n",
+    "        title: Average Salary\n",
+    "YAML"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a40d7e17",
+   "metadata": {},
+   "source": [
+    "## 5. Templates: Reusable Chart Styles"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2492aa3e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Trevl.template_store.register(\"branded_bar\", {\n",
+    "  \"highchartsData\" => {\n",
+    "    \"chart\" => {\"type\" => \"bar\"},\n",
+    "    \"colors\" => [\"#003F85\", \"#E87722\"],\n",
+    "    \"plotOptions\" => {\n",
+    "      \"bar\" => {\"borderRadius\" => 6, \"groupPadding\" => 0.1}\n",
+    "    },\n",
+    "    \"legend\" => {\"enabled\" => true},\n",
+    "    \"credits\" => {\"enabled\" => false}\n",
+    "  }\n",
+    "})\n",
+    "\n",
+    "compare_data = {\n",
+    "  \"compare\" => {\n",
+    "    \"data\" => [\n",
+    "      {\"region\" => \"North\", \"current\" => 55000, \"previous\" => 52000},\n",
+    "      {\"region\" => \"South\", \"current\" => 48000, \"previous\" => 47500},\n",
+    "      {\"region\" => \"East\",  \"current\" => 43000, \"previous\" => 41000},\n",
+    "      {\"region\" => \"West\",  \"current\" => 51000, \"previous\" => 50000}\n",
+    "    ]\n",
+    "  }\n",
+    "}\n",
+    "\n",
+    "nb.chart(<<~YAML, data: compare_data)\n",
+    "  components:\n",
+    "  - id: region_compare\n",
+    "    type: chart\n",
+    "    api: static\n",
+    "    template: branded_bar\n",
+    "    highchartsData:\n",
+    "      title:\n",
+    "        text: Salary Comparison by Region\n",
+    "      series:\n",
+    "      - name: Current Year\n",
+    "        data:\n",
+    "          x: \"$compare.data.region\"\n",
+    "          y: \"$compare.data.current\"\n",
+    "      - name: Previous Year\n",
+    "        data:\n",
+    "          x: \"$compare.data.region\"\n",
+    "          y: \"$compare.data.previous\"\n",
+    "YAML"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dcbf126f-1d4a-490f-8e96-72f7b7be7a07",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Ruby 3 (iruby kernel)",
+   "language": "ruby",
+   "name": "ruby3"
+  },
+  "language_info": {
+   "file_extension": ".rb",
+   "mimetype": "application/x-ruby",
+   "name": "ruby",
+   "version": "3.4.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

data/notebooks/exploration.ipynb

@@ -0,0 +1,164 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "34e8ac3b",
+   "metadata": {},
+   "source": [
+    "# TREVL - Viz DSL for humans and robots 🤖 \n",
+    "\n",
+    "TREVL is a DSL for visualization. Let's dive in what that means! First, let's ensure we have it on board:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fd72b046",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))\n",
+    "require 'trevl'\n",
+    "require 'trevl/notebook'\n",
+    "\n",
+    "puts \"TREVL v#{Trevl::VERSION} loaded\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3d909b50-2824-4a9c-a8d5-6780d3aa1279",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Trevl::DataSource.all"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "63844182-5dbe-4bc9-b208-cf545769fb0d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Trevl::DataSource.register(\"elections\", Trevl::DataSource::Static.new(\n",
+    "  data: {\n",
+    "    \"parties\" => {\n",
+    "      \"data\" => [\n",
+    "        {\"name\" => \"Grüne\",  \"share\" => 6},\n",
+    "        {\"name\" => \"AFD\",  \"share\" => 16},\n",
+    "        {\"name\" => \"SPD\",  \"share\" => 11},\n",
+    "        {\"name\" => \"CDU\",    \"share\" => 22},\n",
+    "        {\"name\" => \"Linke\",  \"share\" => 5},\n",
+    "      ]\n",
+    "    }\n",
+    "  }\n",
+    "))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0a740b54-1b4f-42aa-bb99-64f95353a5b2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Trevl::DataSource.all"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "984cad5c-7fed-47ba-ab49-c689a70fa5cf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Trevl::DataSource.register(\"elections\", Trevl::DataSource::Static.new(\n",
+    "  data: {\n",
+    "    \"parties\" => {\n",
+    "      \"data\" => [\n",
+    "        {\"name\" => \"Grüne\",  \"share\" => 6},\n",
+    "        {\"name\" => \"AFD\",  \"share\" => 16},\n",
+    "        {\"name\" => \"SPD\",  \"share\" => 11},\n",
+    "        {\"name\" => \"CDU\",    \"share\" => 22},\n",
+    "        {\"name\" => \"Linke\",  \"share\" => 5},\n",
+    "      ]\n",
+    "    }\n",
+    "  }\n",
+    "))\n",
+    "\n",
+    "nb = Trevl::Notebook.new\n",
+    "\n",
+    "chart = nb.chart(<<~YAML)\n",
+    "  components:\n",
+    "  - id: election_results\n",
+    "    type: chart\n",
+    "    api: elections\n",
+    "    highchartsData:\n",
+    "      chart:\n",
+    "        type: column\n",
+    "      title:\n",
+    "        text: Wahlergebnis - Kommunalwahl in Klein Datenhausen\n",
+    "      series:\n",
+    "      - name: Anteil in %\n",
+    "        data:\n",
+    "          x: \"$parties.data.name\"\n",
+    "          y: \"$parties.data.share\"\n",
+    "YAML"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c48f917a-a068-491c-bad2-b06fa069c77d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "Trevl::DataSource.for(\"elections\").field_names(\"parties\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f3f44b55-36eb-4891-a13d-85373ef7c967",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    " chart.errors"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "83412406-5f44-40c8-a3b6-ad12b4705601",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "chart.class"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2bf45618-4306-4822-8f6a-da38fd34107a",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Ruby 3 (iruby kernel)",
+   "language": "ruby",
+   "name": "ruby3"
+  },
+  "language_info": {
+   "file_extension": ".rb",
+   "mimetype": "application/x-ruby",
+   "name": "ruby",
+   "version": "3.4.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}