trmnl_preview 0.7.1 → 0.8.0

data/lib/trmnlp/lint/checks/no_async_functions.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class NoAsyncFunctions < Check
+        MESSAGE = 'Async JavaScript functions are not allowed due to browser ' \
+                  'timeout settings for generating screenshots.'
+
+        private
+
+        def pass? = !source.all_markup.downcase.include?('async function')
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/no_opacity.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class NoOpacity < Check
+        MESSAGE = 'Opacity should not be used, use the "--gray--##" Framework classes instead.'
+        LEARN_MORE = 'https://trmnl.com/framework/docs/text_color'
+        PATTERN = /opacity:\s*[\d.]+/
+
+        private
+
+        def pass? = !source.all_markup.match?(PATTERN)
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/no_size_classes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class NoSizeClasses < Check
+        PATTERN = /\b(view(--|__)(full|half_horizontal|half_vertical|quadrant))\b("|')>/
+        MESSAGE = "We already apply the 'full', 'half_horizontal', 'half_vertical', and " \
+                  "'quadrant' classes to each view, please remove them."
+
+        private
+
+        def pass? = !source.all_markup.match?(PATTERN)
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/title_casing.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class TitleCasing < Check
+        MESSAGE = 'Title should begin with a capital letter.'
+
+        private
+
+        def pass?
+          name = source.plugin_name
+          name.empty? || name[0] == name[0].upcase
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/title_length.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class TitleLength < Check
+        MAX_LENGTH = 50
+        MESSAGE = "Title should be <= #{MAX_LENGTH} characters long.".freeze
+
+        private
+
+        def pass? = source.plugin_name.length <= MAX_LENGTH
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/checks/waits_for_dom_load.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class WaitsForDomLoad < Check
+        MESSAGE = 'JavaScript should listen for the DOMContentLoaded event, not window.onLoad()'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/9510536-private-plugins#h_db7030f8b8'
+        FORBIDDEN = ['window.onload', 'window.addeventlistener("load")',
+                     "window.addeventlistener('load')"].freeze
+
+        private
+
+        def pass?
+          markup = source.all_markup.downcase
+          FORBIDDEN.none? { |token| markup.include?(token) }
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/source.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  module Lint
+    # The plugin data every lint check examines: markup per view, shared
+    # markup, the combined markup string, and the raw settings.yml. Built
+    # once and shared across all checks. Settings come straight from
+    # Config::Plugin (a single parse); checks read the raw `{{ }}` templates,
+    # which Config::Plugin's semantic readers render away.
+    class Source
+      VIEWS = %w[full half_horizontal half_vertical quadrant].freeze
+
+      def initialize(config:, paths:)
+        @config = config
+        @paths = paths
+      end
+
+      def plugin_name = settings['name'].to_s
+      def settings = config.plugin.settings
+      def custom_field_values = config.project.custom_fields
+      def custom_field_definitions = config.plugin.custom_field_definitions
+
+      def view_markup
+        @view_markup ||= VIEWS.to_h { |view| [view, read(paths.template(view))] }
+      end
+
+      def shared_markup
+        @shared_markup ||= read(paths.shared_template)
+      end
+
+      def all_markup
+        @all_markup ||= view_markup.values.join + shared_markup
+      end
+
+      private
+
+      attr_reader :config, :paths
+
+      def read(path) = path.exist? ? path.read.strip : ''
+    end
+  end
+end

data/lib/trmnlp/lint.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'lint/check'
+require_relative 'lint/source'
+require_relative 'lint/checks/title_casing'
+require_relative 'lint/checks/title_length'
+require_relative 'lint/checks/layouts_have_content'
+require_relative 'lint/checks/no_async_functions'
+require_relative 'lint/checks/waits_for_dom_load'
+require_relative 'lint/checks/limited_inline_styles'
+require_relative 'lint/checks/no_size_classes'
+require_relative 'lint/checks/no_opacity'
+require_relative 'lint/checks/highcharts_animations_disabled'
+require_relative 'lint/checks/highcharts_elements_unique'
+require_relative 'lint/checks/image_links_reachable'
+require_relative 'lint/checks/custom_fields_used'
+require_relative 'lint/checks/form_fields_valid'
+
+module TRMNLP
+  # Markup best-practice checks behind `trmnlp lint`.
+  module Lint
+    # Every check the lint command runs, in report order.
+    CHECKS = [
+      Checks::TitleCasing,
+      Checks::TitleLength,
+      Checks::LayoutsHaveContent,
+      Checks::NoAsyncFunctions,
+      Checks::WaitsForDomLoad,
+      Checks::LimitedInlineStyles,
+      Checks::NoSizeClasses,
+      Checks::NoOpacity,
+      Checks::HighchartsAnimationsDisabled,
+      Checks::HighchartsElementsUnique,
+      Checks::ImageLinksReachable,
+      Checks::CustomFieldsUsed,
+      Checks::FormFieldsValid
+    ].freeze
+  end
+end

data/lib/trmnlp/paths.rb

@@ -1,22 +1,24 @@
+# frozen_string_literal: true
+
 require 'xdg'
 
 module TRMNLP
   class Paths
     attr_reader :root_dir
-    
+
     def initialize(root_dir)
       @root_dir = Pathname.new(root_dir)
       @xdg = XDG.new
     end
-    
+
     # --- trmnlp library ---
-    
+
     def gem_dir = Pathname.new(__dir__).join('..', '..').expand_path
 
     def templates_dir = gem_dir.join('templates')
 
     # --- directories ---
-    
+
     def src_dir = root_dir.join('src')
 
     def build_dir = root_dir.join('_build')
@@ -34,19 +36,37 @@ module TRMNLP
     def trmnlp_config = root_dir.join('.trmnlp.yml')
 
     def plugin_config = src_dir.join('settings.yml')
-      
+
     def template(view) = src_dir.join("#{view}.liquid")
 
     def shared_template = template('shared')
-      
+
     def app_config = app_config_dir.join('config.yml')
 
     def user_data = cache_dir.join('data.json')
 
     def render_template = Pathname.new(__dir__).join('..', '..', 'web', 'views', 'render_html.erb')
-    
+
     def src_files = src_dir.glob('*').select(&:file?)
 
+    # File extension → transform language identifier.
+    TRANSFORM_EXTENSIONS = {
+      '.py' => 'python',
+      '.rb' => 'ruby',
+      '.php' => 'php',
+      '.js' => 'node'
+    }.freeze
+
+    # Locate src/transform.{py,rb,php,js}. Returns [Pathname, language]
+    # or [nil, nil] if no transform file exists.
+    def transform_file
+      TRANSFORM_EXTENSIONS.each do |ext, language|
+        candidate = src_dir.join("transform#{ext}")
+        return [candidate, language] if candidate.exist?
+      end
+      [nil, nil]
+    end
+
     # --- utilities ---
 
     def expand(path) = Pathname.new(path).expand_path(root_dir)
@@ -55,4 +75,4 @@ module TRMNLP
 
     attr_reader :xdg
   end
-end
+end

data/lib/trmnlp/poller.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/conversions'
+require 'faraday'
+require 'json'
+
+require_relative 'reporter'
+
+module TRMNLP
+  class Poller
+    def initialize(config:, paths:, reporter: Reporter.new)
+      @config = config
+      @paths = paths
+      @reporter = reporter
+    end
+
+    def poll_data
+      return unless config.plugin.polling?
+      raise InvalidConfig, 'config must specify polling_url or polling_urls' if config.plugin.polling_urls.empty?
+
+      data = aggregate_responses
+      write_user_data(data)
+      data
+    # NOTE: trmnlp is a dev tool — a flaky upstream API should surface a warning
+    # and keep the preview server alive, not crash the user's session. We
+    # deliberately swallow here and return {} so the renderer keeps rendering.
+    rescue StandardError => e
+      reporter.info("warning: #{e.message}")
+      {}
+    end
+
+    def put_webhook(payload)
+      write_user_data(wrap_array(JSON.parse(payload)))
+    # NOTE: Same rationale as #poll_data — a bad webhook payload shouldn't take
+    # down the dev server. Report a warning and keep serving.
+    rescue StandardError => e
+      reporter.info("webhook warning: #{e.message}")
+    end
+
+    private
+
+    attr_reader :config, :paths, :reporter
+
+    def aggregate_responses
+      responses = config.plugin.polling_urls.map { |url| fetch_one(url) }
+      return responses.first if responses.size == 1
+
+      responses.each_with_index.with_object({}) { |(r, i), h| h["IDX_#{i}"] = r }
+    end
+
+    def fetch_one(url)
+      verb = config.plugin.polling_verb.upcase
+      response = perform_request(url, verb)
+      reporter.info("#{verb} #{url} — received #{response.body.length} bytes (#{response.status} status)")
+      parse_response(response)
+    end
+
+    def perform_request(url, verb)
+      conn = Faraday.new(url:, headers: config.plugin.polling_headers)
+      verb == 'POST' ? conn.post { |req| req.body = config.plugin.polling_body } : conn.get
+    end
+
+    def parse_response(response)
+      return parse_failure(response.body) unless response.status == 200
+
+      parse_body(response.body, response.headers['content-type'])
+    end
+
+    def parse_failure(body)
+      reporter.info(body)
+      {}
+    end
+
+    def parse_body(body, content_type_header)
+      content_type = content_type_header&.split(';')&.first&.strip
+      case content_type
+      when 'application/json', %r{^application/.+\+json} then wrap_array(JSON.parse(body))
+      when 'text/xml', 'application/xml', %r{^application/.+\+xml} then wrap_array(Hash.from_xml(body))
+      when 'text/html', 'text/plain' then sniff_json(body) || { 'text' => body }
+      else log_unknown_type(content_type_header)
+      end
+    end
+
+    def log_unknown_type(header)
+      reporter.info("unknown content type received: #{header}")
+      {}
+    end
+
+    def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
+
+    def sniff_json(body)
+      trimmed = body.to_s.strip
+      return nil unless trimmed.start_with?('{', '[')
+
+      wrap_array(JSON.parse(trimmed))
+    rescue JSON::ParserError
+      nil
+    end
+
+    def write_user_data(data)
+      paths.create_cache_dir
+      paths.user_data.write(JSON.generate(data))
+    end
+  end
+end

data/lib/trmnlp/renderer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'trmnl/liquid'
+
+require_relative 'screen'
+
+module TRMNLP
+  class Renderer
+    def initialize(config:, paths:, user_data_assembler:)
+      @config = config
+      @paths = paths
+      @user_data_assembler = user_data_assembler
+    end
+
+    def render_full_page(view, params = {})
+      device = user_data_assembler.device_from_params(params)
+      binding_obj = TemplateBinding.new(self, view, params)
+      ERB.new(paths.render_template.read).result(
+        binding_obj.get_binding { render_or_error(view, device:) }
+      )
+    end
+
+    def framework = config.plugin.framework_version
+
+    def screen_classes(classes = 'screen')
+      classes ||= 'screen' # an explicit nil (omitted screen_classes param) still needs a base
+      classes += ' screen--no-bleed' if config.plugin.no_screen_padding == 'yes'
+      classes
+    end
+
+    private
+
+    attr_reader :config, :paths, :user_data_assembler
+
+    # NOTE: a missing template or Liquid syntax error is a user-facing
+    # signal — the plugin author needs to *see* what broke. We surface
+    # those as RenderError, then #render_or_error embeds the message
+    # inside the preview frame so the dev server keeps serving instead
+    # of 500-ing. Anything that's not a RenderError bubbles up as a bug.
+    def render_liquid_template(view, device: {})
+      template_path = paths.template(view)
+      raise RenderError, "Missing template: #{template_path}" unless template_path.exist?
+
+      parse_and_render(template_path, device:)
+    end
+
+    def parse_and_render(template_path, device:)
+      Liquid::Template.parse(full_markup(template_path), environment: liquid_environment)
+                      .render(user_data_assembler.call(device:))
+    rescue StandardError => e
+      raise RenderError, e.message
+    end
+
+    def render_or_error(view, device:)
+      render_liquid_template(view, device:)
+    rescue RenderError => e
+      e.message
+    end
+
+    def full_markup(template_path)
+      shared = paths.shared_template
+      shared.exist? ? shared.read + template_path.read : template_path.read
+    end
+
+    def liquid_environment
+      @liquid_environment ||= TRMNL::Liquid.new do |env|
+        config.project.user_filters.each do |module_name, relative_path|
+          require paths.root_dir.join(relative_path)
+          env.register_filter(Object.const_get(module_name))
+        end
+      end
+    end
+
+    # bindings must match the `GET /render/{view}.html` route in app.rb
+    class TemplateBinding
+      def initialize(renderer, view, params)
+        @view = view
+        @screen_classes = renderer.screen_classes(params[:screen_classes])
+        @framework = renderer.framework
+        @mashup_classes = Screen.find(view)&.mashup_classes
+      end
+
+      def get_binding = binding
+    end
+  end
+end

data/lib/trmnlp/reporter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  # Single sink for user-facing command output. Records every message so
+  # specs can assert on what a command would have said, and writes to the
+  # underlying stream unless quiet:.
+  class Reporter
+    attr_reader :messages
+
+    def initialize(quiet: false, stream: $stdout)
+      @quiet = quiet
+      @stream = stream
+      @messages = []
+    end
+
+    def info(message)
+      @messages << message
+      @stream.puts(message) unless @quiet
+    end
+
+    def green(text) = colorize(text, 32)
+    def yellow(text) = colorize(text, 33)
+
+    private
+
+    def colorize(text, code) = "\e[#{code}m#{text}\e[0m"
+  end
+end

data/lib/trmnlp/screen.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  class Screen < Data.define(:name, :mashup_classes)
+    FULL             = new(name: 'full',             mashup_classes: nil)
+    HALF_HORIZONTAL  = new(name: 'half_horizontal',  mashup_classes: 'mashup mashup--1Tx1B')
+    HALF_VERTICAL    = new(name: 'half_vertical',    mashup_classes: 'mashup mashup--1Lx1R')
+    QUADRANT         = new(name: 'quadrant',         mashup_classes: 'mashup mashup--2x2')
+
+    ALL = [FULL, HALF_HORIZONTAL, HALF_VERTICAL, QUADRANT].freeze
+
+    def self.all = ALL
+    def self.find(name) = ALL.find { it.name == name }
+    def self.names = ALL.map(&:name)
+  end
+end