trevl 0.1.0

data/examples/08_table.yml

@@ -0,0 +1,14 @@
+# Data table with columns. Use when you need tabular output instead of charts.
+components:
+- id: crew_manifest
+  type: table
+  api: demo
+  tableData:
+    headers: ["Pirate", "Role", "Grog Ration"]
+    columns:
+    - identifier: pirate
+      value: "$crew.data.name"
+    - identifier: role
+      value: "$crew.data.role"
+    - identifier: grog
+      value: "$crew.data.grog_ration"

data/examples/09_template_inheritance.yml

@@ -0,0 +1,25 @@
+# Template inheritance. Register a template first, then reference it.
+# Component values override template values at the same path (deep merge).
+#
+# Ruby setup:
+#   Trevl.template_store.register("pirate_bar", {
+#     "highchartsData" => {
+#       "chart" => {"type" => "bar"},
+#       "colors" => ["#8B4513", "#DAA520"],
+#       "plotOptions" => {"bar" => {"borderRadius" => 6}},
+#       "credits" => {"enabled" => false}
+#     }
+#   })
+components:
+- id: plunder_template
+  type: chart
+  api: demo
+  template: pirate_bar
+  highchartsData:
+    title:
+      text: Plunder by Ship (uses pirate_bar template)
+    series:
+    - name: Plunder
+      data:
+        x: "$ships.data.ship"
+        y: "$ships.data.plunder"

data/examples/10_multi_series.yml

@@ -0,0 +1,23 @@
+# Multiple series from the same data source. Use for comparison charts.
+# Each series maps different fields from the same rows.
+components:
+- id: grog_vs_rum
+  type: chart
+  api: demo
+  highchartsData:
+    chart:
+      type: column
+    title:
+      text: Grog vs Rum Sales at the SCUMM Bar
+    colors: ["#8B4513", "#DAA520"]
+    legend:
+      enabled: true
+    series:
+    - name: Grog (pints)
+      data:
+        x: "$sales.data.month"
+        y: "$sales.data.grog"
+    - name: Rum (shots)
+      data:
+        x: "$sales.data.month"
+        y: "$sales.data.rum"

data/lib/trevl/auth/bearer_token.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Trevl
+  module Auth
+    # Simple bearer token authentication.
+    #
+    #   auth = Trevl::Auth::BearerToken.new("my-secret-token")
+    #   Trevl::DataSource::Api.new(base_url: "...", auth: auth)
+    #
+    # Custom auth objects can be used instead — any object responding to
+    # #apply(headers, url:) will work.
+    #
+    class BearerToken
+      def initialize(token)
+        @token = token
+      end
+
+      def apply(headers, url: nil)
+        headers["Authorization"] = "Bearer #{@token}"
+      end
+    end
+  end
+end

data/lib/trevl/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Trevl
+  class Configuration
+    # Highcharts is commercially licensed and not bundled with this gem, so it
+    # is loaded from the CDN unless a local copy is configured.
+    HIGHCHARTS_CDN_URL = "https://code.highcharts.com/11.4.0/highcharts.js"
+
+    attr_accessor :logger, :highcharts_url, :highcharts_path, :highcharts_modules
+    attr_writer :template_store
+
+    def initialize
+      @logger = Logger.new($stderr, level: Logger::WARN)
+      @template_store = nil
+      @highcharts_url = HIGHCHARTS_CDN_URL
+      @highcharts_path = nil
+      @highcharts_modules = []
+    end
+
+    def template_store
+      @template_store ||= TemplateStore.new
+    end
+  end
+end

data/lib/trevl/core_ext/hash.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Trevl
+  module CoreExt
+    module Hash
+      def self.deep_dup(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key] = case value
+          when ::Hash then deep_dup(value)
+          when ::Array then value.map { |v| v.is_a?(::Hash) ? deep_dup(v) : v }
+          else value
+          end
+        end
+      end
+
+      def self.deep_stringify_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = case value
+          when ::Hash then deep_stringify_keys(value)
+          when ::Array then value.map { |v| v.is_a?(::Hash) ? deep_stringify_keys(v) : v }
+          else value
+          end
+        end
+      end
+
+      def self.deep_merge(base, override)
+        base.merge(override) do |_key, base_val, override_val|
+          if base_val.is_a?(::Hash) && override_val.is_a?(::Hash)
+            deep_merge(base_val, override_val)
+          else
+            override_val
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trevl/data_source/api.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module Trevl
+  module DataSource
+    # Generic REST API data source.
+    #
+    #   Trevl::DataSource.register("my_api", Trevl::DataSource::Api.new(
+    #     base_url: "https://api.example.com/v1",
+    #     auth: Trevl::Auth::BearerToken.new("my-token")
+    #   ))
+    #
+    class Api < Base
+      include HTTParty
+
+      EMPTY_RESULT = {"data" => [], "meta" => {}}.freeze
+
+      attr_reader :base_url
+
+      def initialize(base_url:, auth: nil, default_resource: nil, **)
+        super()
+        @base_url = base_url.to_s.chomp("/")
+        @auth = auth
+        @default_resource = default_resource
+      end
+
+      def fetch(endpoint, params = {}, resource: nil)
+        resource = (resource || @default_resource).to_s
+        url = build_url(resource, endpoint)
+        headers = build_headers(url)
+        body = params.is_a?(Hash) ? params : {}
+
+        Trevl.logger.info("[Trevl::DataSource::Api] POST #{url}")
+
+        response = self.class.post(url, body: body.to_json, headers: headers, timeout: 15)
+
+        unless response.success?
+          Trevl.logger.error("[Trevl::DataSource::Api] HTTP #{response.code} from #{url}")
+          return EMPTY_RESULT.dup
+        end
+
+        parse_response(response.body)
+      rescue JSON::ParserError, Timeout::Error, Errno::ECONNREFUSED => e
+        Trevl.logger.error("[Trevl::DataSource::Api] Error: #{e.message}")
+        EMPTY_RESULT.dup
+      end
+
+      private
+
+      def build_url(resource, endpoint)
+        parts = [@base_url]
+        parts << resource unless resource.empty?
+        parts << endpoint unless endpoint.nil? || endpoint.empty?
+        parts.join("/")
+      end
+
+      def build_headers(url)
+        headers = {"Content-Type" => "application/json", "Accept" => "application/json"}
+        @auth&.apply(headers, url: url)
+        headers
+      end
+
+      def parse_response(body)
+        data = JSON.parse(body)
+        meta = extract_meta(data)
+        rows = extract_rows(data)
+        {"data" => rows, "meta" => meta}
+      end
+
+      def extract_meta(data)
+        return {} unless data.is_a?(Hash)
+        m = data["metadata"] || data["meta"]
+        m.is_a?(Hash) ? m : {}
+      end
+
+      def extract_rows(data)
+        case data
+        when Array then data
+        when Hash then data["results"] || data["data"] || (data.key?("meta") ? [] : [data])
+        else []
+        end
+      end
+    end
+  end
+end

data/lib/trevl/data_source/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Trevl
+  module DataSource
+    class Base
+      def fetch(endpoint, params = {}, resource: nil)
+        raise NotImplementedError, "#{self.class}#fetch must be implemented"
+      end
+
+      # Returns the field names available for an endpoint by fetching a sample row.
+      # Override in subclasses for more efficient discovery (e.g. schema endpoints).
+      def field_names(endpoint, params = {}, resource: nil)
+        result = fetch(endpoint, params, resource: resource)
+        row = Array(result["data"]).first
+        row.is_a?(Hash) ? row.keys : []
+      end
+    end
+  end
+end

data/lib/trevl/data_source/cube.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module Trevl
+  module DataSource
+    # Generic CubeJS data source.
+    #
+    #   Trevl::DataSource.register("cube", Trevl::DataSource::Cube.new(
+    #     url: "https://cube.example.com/cubejs-api/v1",
+    #     token: ENV["CUBE_TOKEN"]
+    #   ))
+    #
+    class Cube < Base
+      include HTTParty
+
+      EMPTY_RESULT = {"data" => [], "meta" => {}}.freeze
+      QUERY_KEYS = %w[dimensions measures filters timeDimensions order limit].freeze
+
+      def initialize(url:, token: nil, **)
+        super()
+        @url = url.to_s.chomp("/")
+        @token = token
+      end
+
+      def fetch(endpoint, params = {}, resource: nil)
+        query = build_query(params)
+        headers = {"Content-Type" => "application/json", "Accept" => "application/json"}
+        headers["Authorization"] = @token if @token
+
+        Trevl.logger.info("[Trevl::DataSource::Cube] Querying #{@url}/load")
+
+        response = self.class.post(
+          "#{@url}/load",
+          body: {query: query}.to_json,
+          headers: headers,
+          timeout: 30
+        )
+
+        unless response.success?
+          Trevl.logger.error("[Trevl::DataSource::Cube] HTTP #{response.code}: #{response.body}")
+          return EMPTY_RESULT.dup
+        end
+
+        data = JSON.parse(response.body)
+        rows = Array(data["data"]).map { |row| flatten_keys(row) }
+        {"data" => rows, "meta" => {}}
+      rescue JSON::ParserError, Timeout::Error, Errno::ECONNREFUSED => e
+        Trevl.logger.error("[Trevl::DataSource::Cube] Error: #{e.message}")
+        EMPTY_RESULT.dup
+      end
+
+      private
+
+      def build_query(params)
+        QUERY_KEYS.each_with_object({}) do |key, query|
+          val = params[key] || params[key.to_sym]
+          query[key] = val if val
+        end
+      end
+
+      def flatten_keys(row)
+        row.each_with_object({}) do |(key, value), flat|
+          flat_key = key.to_s.include?(".") ? key.to_s.split(".").last : key.to_s
+          flat[flat_key] = value
+        end
+      end
+    end
+  end
+end

data/lib/trevl/data_source/static.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Trevl
+  module DataSource
+    class Static < Base
+      attr_reader :data
+
+      def initialize(data: {}, **)
+        super()
+        @data = data
+      end
+
+      def fetch(endpoint, params = {}, resource: nil)
+        key = resource ? "#{resource}/#{endpoint}" : endpoint
+        result = @data[key] || @data[endpoint]
+
+        case result
+        when Array
+          {"data" => result, "meta" => {}}
+        when Hash
+          data = result["data"] || result[:data] || []
+          meta = result["meta"] || result[:meta] || {}
+          {"data" => Array(data), "meta" => meta.is_a?(Hash) ? meta : {}}
+        else
+          {"data" => [], "meta" => {}}
+        end
+      end
+    end
+  end
+end

data/lib/trevl/data_source.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Trevl
+  module DataSource
+    class << self
+      def register(name, source)
+        registry[name.to_s.strip.downcase] = source
+      end
+
+      def for(name, **)
+        key = name.to_s.strip.downcase
+        source = registry[key]
+        raise DataSourceError, "No data source registered for '#{name}'. Available: #{registry.keys.join(", ")}." unless source
+
+        source.is_a?(Class) ? source.new(**) : source
+      end
+
+      def all
+        registry.map do |name, source|
+          obj = source.is_a?(Class) ? source : source.class
+          {name: name, type: obj.name&.split("::")&.last || obj.to_s, source: source}
+        end
+      end
+
+      def names
+        registry.keys
+      end
+
+      def registry
+        @registry ||= {}
+      end
+
+      def reset!
+        @registry = {}
+      end
+    end
+  end
+end

data/lib/trevl/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Trevl
+  class Error < StandardError; end
+  class ParseError < Error; end
+  class ValidationError < Error; end
+  class DataSourceError < Error; end
+  class RenderError < Error; end
+end

data/lib/trevl/highcharts_asset.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Trevl
+  # Builds the <script> tags that load Highcharts into generated HTML.
+  #
+  # Highcharts is commercially licensed and is therefore not shipped with this
+  # gem. By default it is loaded from the official CDN. Point the configuration
+  # at local copies to keep the output self-contained and usable offline:
+  #
+  #   Trevl.configure do |config|
+  #     config.highcharts_path = Rails.root.join("vendor/highcharts/highcharts.js")
+  #   end
+  #
+  # Using Highcharts requires a licence from Highsoft. See highcharts.com/license.
+  module HighchartsAsset
+    class << self
+      # Core library plus any configured modules, as ready-to-embed script tags.
+      def script_tags
+        config = Trevl.configuration
+        sources = [[config.highcharts_path, config.highcharts_url]] +
+          config.highcharts_modules.map { |m| [local?(m) ? m : nil, m] }
+
+        sources.map { |path, url| script_tag(path, url) }.join("\n")
+      end
+
+      private
+
+      # A local file is inlined so the page works without network access;
+      # anything else becomes a src reference.
+      def script_tag(path, url)
+        if path && File.exist?(path.to_s)
+          "<script>#{File.read(path.to_s)}</script>"
+        elsif path
+          raise Trevl::Error, "Highcharts JS not found at #{path}"
+        else
+          %(<script src="#{url}"></script>)
+        end
+      end
+
+      def local?(source)
+        !source.to_s.match?(%r{\Ahttps?://})
+      end
+    end
+  end
+end

data/lib/trevl/html_renderer.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Trevl
+  # Renders TREVL YAML to an HTML page that draws its charts with Highcharts.
+  # Highcharts itself is loaded from the CDN by default; configure
+  # `highcharts_path` to inline a local copy and get a self-contained file
+  # that works offline.
+  #
+  #   html = Trevl.render_to_html(yaml_string)
+  #   File.write("chart.html", html)
+  #
+  # For screenshots, open the HTML file with any headless browser:
+  #   - Grover gem: Grover.new(html).to_png
+  #   - Ferrum: browser.goto("file:///tmp/chart.html"); browser.screenshot
+  #   - Playwright MCP: browser_navigate + browser_take_screenshot
+  #   - CLI: npx puppeteer screenshot chart.html
+  #
+  class HtmlRenderer
+    def initialize(width: 800, height: 400, background: "#ffffff")
+      @width = width
+      @height = height
+      @background = background
+    end
+
+    # Renders TREVL YAML to a standalone HTML string.
+    # Returns a complete HTML document with all charts embedded.
+    def render(yaml_string, params: {}, data: nil, data_sources: {})
+      results = Trevl.render(yaml_string, params: params, data: data, data_sources: data_sources)
+      charts = results.select { |r| r["type"] == "chart" && r["highchartsData"] }
+      scores = results.select { |r| r["type"] == "score" && r["display"] }
+
+      build_html(charts, scores)
+    end
+
+    # Renders a single pre-rendered component hash to HTML.
+    def render_component(result)
+      case result["type"]
+      when "chart" then build_html([result], [])
+      when "score" then build_html([], [result])
+      else ""
+      end
+    end
+
+    private
+
+    def build_html(charts, scores)
+      <<~HTML
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <meta charset="utf-8">
+          <style>
+            body { margin: 0; padding: 20px; background: #{@background}; font-family: -apple-system, BlinkMacSystemFont, sans-serif; }
+            .trevl-chart { width: #{@width}px; height: #{@height}px; margin: 0 auto 20px; }
+            .trevl-score { text-align: center; padding: 20px; margin: 0 auto 20px; }
+            .trevl-score-title { font-size: 14px; color: #6b7280; margin-bottom: 8px; }
+            .trevl-score-value { font-size: 48px; font-weight: 700; color: #1f2937; }
+          </style>
+          #{HighchartsAsset.script_tags}
+        </head>
+        <body>
+          #{scores.map { |s| score_html(s) }.join("\n")}
+          #{charts.each_with_index.map { |c, i| chart_html(c, i) }.join("\n")}
+        </body>
+        </html>
+      HTML
+    end
+
+    def chart_html(result, index)
+      container_id = "trevl_chart_#{index}"
+      <<~HTML
+        <div id="#{container_id}" class="trevl-chart"></div>
+        <script>Highcharts.chart('#{container_id}', #{result["highchartsData"].to_json});</script>
+      HTML
+    end
+
+    def score_html(result)
+      display = result["display"] || {}
+      value = display["value"]
+      unit = display["unit"] || ""
+      title = display.dig("header", "title") || ""
+
+      <<~HTML
+        <div class="trevl-score">
+          <div class="trevl-score-title">#{title}</div>
+          <div class="trevl-score-value">#{value}#{unit}</div>
+        </div>
+      HTML
+    end
+  end
+end

data/lib/trevl/notebook/display.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Trevl
+  class Notebook
+    class Display
+      def render_chart(highcharts_data, height: 400)
+        container_id = "trevl_#{SecureRandom.hex(6)}"
+
+        html = +""
+        html << highcharts_script_tag unless @highcharts_loaded
+        html << <<~HTML
+          <div id="#{container_id}" style="width:100%;height:#{height}px;"></div>
+          <script>
+            Highcharts.chart('#{container_id}', #{highcharts_data.to_json});
+          </script>
+        HTML
+
+        @highcharts_loaded = true
+        display_html(html)
+      end
+
+      def render_score(display_data)
+        value = display_data["value"]
+        unit = display_data["unit"] || ""
+        header = display_data["header"] || {}
+        title = header["title"] || ""
+
+        html = <<~HTML
+          <div style="text-align:center;padding:20px;font-family:sans-serif;">
+            <div style="font-size:14px;color:#6b7280;margin-bottom:8px;">#{title}</div>
+            <div style="font-size:48px;font-weight:700;color:#1f2937;">#{value}#{unit}</div>
+          </div>
+        HTML
+
+        display_html(html)
+      end
+
+      private
+
+      def highcharts_script_tag
+        "#{HighchartsAsset.script_tags}\n"
+      end
+
+      def display_html(html)
+        if defined?(IRuby)
+          IRuby.display(html, mime: "text/html")
+        else
+          puts html
+        end
+      end
+    end
+  end
+end

data/lib/trevl/notebook.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "notebook/display"
+
+module Trevl
+  class Notebook
+    attr_reader :display
+
+    def initialize
+      @display = Display.new
+    end
+
+    # Render a TREVL YAML string as an interactive Highcharts chart in iRuby.
+    # Optionally pass static data to avoid API calls — inline data answers any
+    # api name and components without one (Trevl.render data: semantics).
+    def chart(yaml_string, params: {}, data: nil, height: 400)
+      results = Trevl.render(yaml_string, params: params, data: data)
+      results.each do |result|
+        next unless result["type"] == "chart" && result["highchartsData"]
+        @display.render_chart(result["highchartsData"], height: height)
+      end
+      nil
+    end
+
+    # Render a score component inline
+    def score(yaml_string, params: {}, data: nil)
+      results = Trevl.render(yaml_string, params: params, data: data)
+      results.each do |result|
+        next unless result["type"] == "score"
+        @display.render_score(result["display"] || result)
+      end
+      nil
+    end
+
+    # Fetch raw data from a registered data source
+    def fetch(source_name, endpoint, params = {}, resource: nil)
+      source = DataSource.for(source_name)
+      source.fetch(endpoint, params, resource: resource)
+    end
+  end
+end