trmnl_preview 0.23.1 → 0.24.0

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Recipe review asks for a contact that is not Discord, because not every
+      # user has access to Discord.
+      class AuthorContactMethod < Check
+        MESSAGE = 'Add an email address, web link or GitHub link to the author_bio custom field, ' \
+                  'so users can reach you with questions or issues. A Discord link alone is not enough.'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10513740-custom-plugin-form-builder#h_02dd8f84a9'
+        CONTACT_KEYS = %w[email_address github_url learn_more_url description].freeze
+        CONTACT_PATTERN = %r{[^\s@]+@[^\s@]+\.\w+|https?://\S+}
+
+        private
+
+        def pass?
+          author_bio = source.custom_field_definitions.find { it['field_type'] == 'author_bio' }
+          return false unless author_bio
+
+          author_bio.values_at(*CONTACT_KEYS).join(' ').scan(CONTACT_PATTERN).any? { !it.match?(/discord/i) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports separate latitude and longitude fields in settings.yml. One
+      # lat_lon field asks for both, and lets the user pick a place on a map.
+      class CoordinatesUseLatLon < Check
+        LATITUDE_WORDS = %w[lat latitude].freeze
+        LONGITUDE_WORDS = %w[lon lng long longitude].freeze
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10513740-custom-plugin-form-builder#h_07a70ff721'
+
+        def issues
+          # A keyname with both words (lat_lng) is one field, so it never pairs with itself.
+          latitude = keynames_with(LATITUDE_WORDS) - keynames_with(LONGITUDE_WORDS)
+          longitude = keynames_with(LONGITUDE_WORDS) - keynames_with(LATITUDE_WORDS)
+          return [] if latitude.empty? || longitude.empty?
+
+          fields = (latitude + longitude).map { "'#{it}'" }.join(' and ')
+          [{ message: "Form fields #{fields} ask for one location. Use one field with field_type 'lat_lon'.",
+             learn_more: LEARN_MORE }]
+        end
+
+        private
+
+        def keynames_with(words) = keynames.select { |keyname| words.intersect?(words_in(keyname)) }
+
+        def keynames
+          source.custom_field_definitions.reject { |field| field['field_type'] == 'lat_lon' }
+                .map { |field| field['keyname'].to_s }
+        end
+
+        # home_lat, homeLat and home-lat all give %w[home lat].
+        def words_in(keyname) = keyname.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.split(/[^a-z\d]+/)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports classes in the Framework's own families that the plugin's release does
+      # not define, such as `value--medium`. They match no rule, so they do nothing.
+      class FrameworkClassesExist < Check
+        FAMILY_PATTERN = /\A(?:value|label|title|description|text)--/
+        DATA_PATH = File.expand_path('../../../../db/data/framework_classes.yml', __dir__)
+
+        # Release number => the family classes its plugins.css defines, from that release until the next one listed.
+        CLASSES_BY_RELEASE = YAML.load_file(DATA_PATH).transform_keys { Gem::Version.new(it) }.sort.freeze
+
+        def issues
+          (used_classes - release_classes).map do |name|
+            { message: "'#{name}' is not a class in Framework v#{source.framework_version}, so it has no effect. " \
+                       'Check the name in the Framework docs.' }
+          end
+        end
+
+        private
+
+        def used_classes
+          source.html_fragments.values.flat_map { it.css('[class]').flat_map { it['class'].split } }
+                .map { it.split(':').last.to_s }
+                .select { it.match?(FAMILY_PATTERN) && !it.include?('{{') }
+                .uniq
+        end
+
+        def release_classes
+          version = Gem::Version.new(source.framework_version.number)
+          CLASSES_BY_RELEASE.select { |release, _| release <= version }.last.last
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../check'
+require_relative '../source'
 require 'crass'
 require 'nokogiri'
 
@@ -25,7 +26,7 @@ module TRMNLP
         end
 
         def markup_without_liquid_comments
-          source.all_markup.gsub(/\{%-?\s*comment\s*-?%\}.*?\{%-?\s*endcomment\s*-?%\}/m, '')
+          source.all_markup.gsub(Source::LIQUID_COMMENT, '')
         end
       end
     end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class NoExternalQrCodes < Check
+        MESSAGE = 'Instead of an external service, please use our built-in Liquid filter for QR codes "qr_code".'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10347358-custom-plugin-filters#h_1c2c240f9e'
+        QR_GENERATORS = %r{
+          (?:qrserver\.com|goqr\.me|qrcode\.tec-it\.com|qrcode-monkey\.com
+          |quickchart\.io/qr\b|chart\.googleapis\.com/chart\?[^"')]*\bcht=qr\b)
+        }xi
+        PATTERN = %r{(?:\bsrc\s*=\s*|\burl\(\s*)["']?(?:https?:)?//(?:[\w-]+\.)*#{QR_GENERATORS}}i
+
+        private
+
+        def pass? = !source.all_markup.match?(PATTERN)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class NoNestedLayouts < Check
+        MESSAGE = "A 'layout' is inside another 'layout', which breaks the render. " \
+                  "Use one 'layout' per view, with 'columns' or 'flex' inside it."
+        LEARN_MORE = 'https://trmnl.com/framework/docs/layout'
+
+        def misplaced_elements
+          @misplaced_elements ||= source.html_fragments.flat_map do |path, fragment|
+            fragment.css('.layout .layout').map { [path, it] }
+          end
+        end
+
+        private
+
+        def pass? = misplaced_elements.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      class TitleBarOutsideLayout < Check
+        MESSAGE = "A 'title_bar' is inside a 'layout', so it does not render in its place. " \
+                  "Move it out of the 'layout', after it."
+        LEARN_MORE = 'https://trmnl.com/framework/docs/title_bar'
+
+        def misplaced_elements
+          @misplaced_elements ||= source.html_fragments.flat_map do |path, fragment|
+            fragment.css('.layout .title_bar').map { [path, it] }
+          end
+        end
+
+        private
+
+        def pass? = misplaced_elements.empty?
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports a settings.yml select whose only options are yes and no — one
+      # finding per field. A boolean field shows the same choice as a switch.
+      class YesNoSelectsAreBoolean < Check
+        YES_NO_VALUE_SETS = [%w[no yes], %w[false true]].freeze
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10513740-custom-plugin-form-builder'
+
+        def issues
+          source.custom_field_definitions.select { |field| yes_no_select?(field) }.map do |field|
+            { message: "Form field '#{field['keyname']}' is a select with only Yes and No options. " \
+                       "Use field_type 'boolean' to show a switch.", learn_more: LEARN_MORE }
+          end
+        end
+
+        private
+
+        def yes_no_select?(field)
+          options = field['options']
+          field['field_type'] == 'select' && options.is_a?(Array) && YES_NO_VALUE_SETS.include?(option_values(options))
+        end
+
+        # Same value TRMNL submits: a Label: value pair's value, otherwise the option itself.
+        def option_values(options)
+          options.map { |option| (option.is_a?(Hash) ? option.values.first : option).to_s.downcase }.uniq.sort
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/diagnostic.rb

@@ -13,6 +13,7 @@ module TRMNLP
         'no_async_functions' => /async function/i,
         'no_opacity' => Checks::NoOpacity::PATTERN,
         'no_size_classes' => Checks::NoSizeClasses::PATTERN,
+        'no_external_qr_codes' => Checks::NoExternalQrCodes::PATTERN,
         'waits_for_dom_load' => Regexp.new(Regexp.union(Checks::WaitsForDomLoad::FORBIDDEN).source, Regexp::IGNORECASE),
         'limited_inline_styles' => /\sstyle\s*=/i,
         'highcharts_animations_disabled' => /highcharts/i,
@@ -40,11 +41,13 @@ module TRMNLP
         return source.locations(MARKUP_PATTERNS[rule_id]) if MARKUP_PATTERNS.key?(rule_id)
 
         case rule_id
-        when 'arbitrary_values_in_range' then class_locations
+        when 'arbitrary_values_in_range', 'framework_classes_exist' then class_locations
         when 'layouts_have_content' then empty_view_locations
         when 'form_fields_valid' then form_field_locations
         when 'custom_fields_used' then project_field_locations
         when 'no_custom_filters', 'no_unknown_filters' then filter_locations
+        when 'title_bar_outside_layout', 'no_nested_layouts'
+          check.misplaced_elements.map { |path, element| source.element_location(path, element) }
         when 'image_links_reachable' then source.locations(Regexp.union(check.unreachable_urls))
         else []
         end

data/lib/trmnlp/lint/source.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'nokogiri'
 require 'trmnl/liquid'
 require 'yaml'
 
@@ -12,6 +13,7 @@ module TRMNLP
     # which Config::Plugin's semantic readers render away.
     class Source
       VIEWS = %w[full half_horizontal half_vertical quadrant].freeze
+      LIQUID_COMMENT = /\{%-?\s*comment\s*-?%\}.*?\{%-?\s*endcomment\s*-?%\}/m
 
       def initialize(config:, paths:)
         @config = config
@@ -60,6 +62,23 @@ module TRMNLP
         end
       end
 
+      # Parsed without render data: Liquid output becomes `{{}}` and tags become spaces,
+      # so the classes of every branch count and a quote inside Liquid cannot end an attribute.
+      # Each replacement keeps the newlines it replaced, so element lines stay true.
+      def html_fragments
+        @html_fragments ||= markup_files.transform_values do |markup|
+          html = markup.gsub(LIQUID_COMMENT) { "\n" * it.count("\n") }
+                       .gsub(/\{\{.*?\}\}/m) { "{{}}#{"\n" * it.count("\n")}" }
+                       .gsub(/\{%.*?%\}/m) { " #{"\n" * it.count("\n")}" }
+          Nokogiri::HTML.fragment(html)
+        end
+      end
+
+      def element_location(path, element)
+        snippet = markup_files.fetch(path).lines[element.line - 1].to_s.chomp
+        { path:, line: element.line, column: (snippet.index(/<#{element.name}\b/i) || 0) + 1, snippet: snippet[0, 240] }
+      end
+
       def locations(pattern, files: markup_files)
         files.flat_map do |path, contents|
           contents.to_enum(:scan, pattern).map do

data/lib/trmnlp/lint.rb

@@ -18,8 +18,15 @@ 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'
+require_relative 'lint/checks/yes_no_selects_are_boolean'
+require_relative 'lint/checks/coordinates_use_lat_lon'
 require_relative 'lint/checks/no_custom_filters'
 require_relative 'lint/checks/no_unknown_filters'
+require_relative 'lint/checks/author_contact_method'
+require_relative 'lint/checks/title_bar_outside_layout'
+require_relative 'lint/checks/no_nested_layouts'
+require_relative 'lint/checks/framework_classes_exist'
+require_relative 'lint/checks/no_external_qr_codes'
 
 module TRMNLP
   # Markup best-practice checks behind `trmnlp lint`.
@@ -42,8 +49,15 @@ module TRMNLP
       Checks::ImageLinksReachable,
       Checks::CustomFieldsUsed,
       Checks::FormFieldsValid,
+      Checks::YesNoSelectsAreBoolean,
+      Checks::CoordinatesUseLatLon,
       Checks::NoCustomFilters,
-      Checks::NoUnknownFilters
+      Checks::NoUnknownFilters,
+      Checks::AuthorContactMethod,
+      Checks::TitleBarOutsideLayout,
+      Checks::NoNestedLayouts,
+      Checks::FrameworkClassesExist,
+      Checks::NoExternalQrCodes
     ].freeze
 
     def self.rule_id(check_type) = check_type.name.split('::').last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase

data/lib/trmnlp/testing/publishable_recipe.rb

@@ -43,7 +43,8 @@ RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLI
 
   TRMNLP::Testing::PUBLISHABLE_RECIPE_VIEWS.product(screens).each do |view, screen|
     device = screen[:device].is_a?(Hash) ? screen[:device][:model] : screen[:device]
-    screen_name = [device, screen[:orientation]].compact.join(' ')
+    dark_mode = 'dark mode' if screen[:dark_mode]
+    screen_name = [device, screen[:orientation], screen[:palette], dark_mode].compact.join(' ')
 
     it "draws the #{view} view on #{screen_name} without page errors" do
       expect(trmnl.render(view:, **screen, **recipe_inputs)).to draw_cleanly

data/lib/trmnlp/testing/report.html.erb

@@ -20,6 +20,7 @@
   pre { background: #f6f8fa; padding: 8px; overflow-x: auto; white-space: pre-wrap; }
   .screens { display: flex; flex-wrap: wrap; gap: 16px; margin-top: 8px; }
   figure { margin: 0; max-width: 100%; }
+  .og-vs-x { display: block; max-width: 100%; height: auto; border: 1px solid var(--line); }
   .frame { position: relative; border: 1px solid var(--line); max-width: min(100%, 640px); }
   .frame img, .frame svg { display: block; width: 100%; height: auto; }
   .frame svg { position: absolute; inset: 0; display: none; }
@@ -47,6 +48,12 @@
   <label for="failures">failures only</label>
 </header>
 <main>
+<% if og_vs_x %>
+  <section>
+    <h2>Full view on TRMNL OG and TRMNL X, at the same height</h2>
+    <figure><img src="<%= og_vs_x %>" alt="TRMNL OG and TRMNL X side by side" class="og-vs-x"></figure>
+  </section>
+<% end %>
 <% examples.each do |example| %>
   <section class="<%= 'failed-example' if example[:status] == 'failed' %>">
     <h2 class="<%= example[:status] %>"><%= h(example[:description]) %></h2>

data/lib/trmnlp/testing/report.rb

@@ -3,6 +3,7 @@
 require 'erb'
 require 'fileutils'
 require 'json'
+require 'mini_magick'
 require 'rspec/core'
 
 module TRMNLP
@@ -12,6 +13,7 @@ module TRMNLP
     # DIR/report.json. Under GitHub Actions the counts and failures go to the step summary too.
     class Report
       TEMPLATE = File.expand_path('report.html.erb', __dir__)
+      OG_VS_X = 'og-vs-x.png'
       OUTLINES_SCRIPT = <<~JS
         (() => [...document.querySelectorAll('.view *')].slice(0, 3000).map((el) => {
           const box = el.getBoundingClientRect();
@@ -28,12 +30,17 @@ module TRMNLP
         @dir = "#{dir}#{ENV.fetch('TEST_ENV_NUMBER', '')}" # parallel_tests: report, report2, report3...
         @examples = {}
         @images = 0
+        @full_landscape_images = {}
       end
 
       def record_screen(screen)
-        entry&.fetch(:screens)&.push(
+        return unless entry
+
+        image = copy_image(screen.png_path)
+        remember_full_landscape(screen, image)
+        entry[:screens].push(
           label: "#{screen.device.name} · #{screen.view}", width: screen.device.width, height: screen.device.height,
-          image: copy_image(screen.png_path), outlines: screen.evaluate(OUTLINES_SCRIPT), problems: screen.problems
+          image:, outlines: screen.evaluate(OUTLINES_SCRIPT), problems: screen.problems
         )
       end
 
@@ -50,7 +57,8 @@ module TRMNLP
 
       def close(_notification)
         FileUtils.mkdir_p(@dir)
-        File.write(File.join(@dir, 'report.json'), JSON.pretty_generate(examples: examples))
+        write_og_vs_x
+        File.write(File.join(@dir, 'report.json'), JSON.pretty_generate(og_vs_x:, examples:))
         File.write(File.join(@dir, 'index.html'), ERB.new(File.read(TEMPLATE)).result(binding))
         write_step_summary if ENV['GITHUB_STEP_SUMMARY']
       end
@@ -75,6 +83,24 @@ module TRMNLP
         name
       end
 
+      def remember_full_landscape(screen, image)
+        return unless screen.view == 'full' && screen.device.width > screen.device.height
+
+        @full_landscape_images[screen.device.name] ||= image
+      end
+
+      def og_vs_x = (OG_VS_X if @full_landscape_images.values_at('og_plus', 'v2').all?)
+
+      # Both at the OG's height, so content that fills the OG but is small on the X shows at a glance.
+      def write_og_vs_x
+        return unless og_vs_x
+
+        MiniMagick.convert do |convert|
+          @full_landscape_images.values_at('og_plus', 'v2').each { convert << File.join(@dir, it) }
+          convert << '-resize' << 'x480' << '+append' << '+repage' << File.join(@dir, OG_VS_X)
+        end
+      end
+
       def count(status) = examples.count { it[:status] == status }
 
       def write_step_summary

data/lib/trmnlp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLP
-  VERSION = '0.23.1'
+  VERSION = '0.24.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.23.1
+  version: 0.24.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -360,6 +360,7 @@ files:
 - bin/trmnlp
 - db/data/and_x_more.yml
 - db/data/form_fields.yml
+- db/data/framework_classes.yml
 - db/data/framework_versions.yml
 - db/data/locales/cs.yml
 - db/data/locales/da.yml
@@ -421,9 +422,12 @@ files:
 - lib/trmnlp/lint.rb
 - lib/trmnlp/lint/check.rb
 - lib/trmnlp/lint/checks/arbitrary_values_in_range.rb
+- lib/trmnlp/lint/checks/author_contact_method.rb
+- lib/trmnlp/lint/checks/coordinates_use_lat_lon.rb
 - lib/trmnlp/lint/checks/custom_fields_used.rb
 - lib/trmnlp/lint/checks/description_length.rb
 - lib/trmnlp/lint/checks/form_fields_valid.rb
+- lib/trmnlp/lint/checks/framework_classes_exist.rb
 - lib/trmnlp/lint/checks/highcharts_animations_disabled.rb
 - lib/trmnlp/lint/checks/highcharts_elements_unique.rb
 - lib/trmnlp/lint/checks/image_links_reachable.rb
@@ -431,13 +435,17 @@ files:
 - lib/trmnlp/lint/checks/limited_inline_styles.rb
 - lib/trmnlp/lint/checks/no_async_functions.rb
 - lib/trmnlp/lint/checks/no_custom_filters.rb
+- lib/trmnlp/lint/checks/no_external_qr_codes.rb
+- lib/trmnlp/lint/checks/no_nested_layouts.rb
 - lib/trmnlp/lint/checks/no_opacity.rb
 - lib/trmnlp/lint/checks/no_size_classes.rb
 - lib/trmnlp/lint/checks/no_unknown_filters.rb
 - lib/trmnlp/lint/checks/recipe_overview_length.rb
+- lib/trmnlp/lint/checks/title_bar_outside_layout.rb
 - lib/trmnlp/lint/checks/title_casing.rb
 - lib/trmnlp/lint/checks/title_length.rb
 - lib/trmnlp/lint/checks/waits_for_dom_load.rb
+- lib/trmnlp/lint/checks/yes_no_selects_are_boolean.rb
 - lib/trmnlp/lint/diagnostic.rb
 - lib/trmnlp/lint/source.rb
 - lib/trmnlp/merged_plugin_locals.rb