trmnl_preview 0.26.0 → 0.28.0

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Small gray text dithers into dots on a 1-bit screen, so it needs a 1bit: class
+      # (1bit:text--black, or 1bit:text--white on a black panel) on the same element.
+      class GrayTextHasOneBitClass < Check
+        SMALL = /\A(?:label|text|description)--x?small\z/
+        GRAY = /\A(?:text--gray(?:-\d+)?|label--gray)\z/
+        LEARN_MORE = 'https://trmnl.com/framework/docs/3.4/text_color'
+
+        def issues
+          offending_elements.map { |_, element| self.class.class_list(element) }.uniq.map do |classes|
+            { message: "'#{classes}' is small gray text with no 1bit: class, so it breaks up " \
+                       'into dots on 1-bit screens. Add 1bit:text--black (1bit:text--white on a black background).',
+              learn_more: LEARN_MORE }
+          end
+        end
+
+        def offending_elements
+          @offending_elements ||= source.html_fragments.flat_map do |path, fragment|
+            fragment.css('[class]').select { small_gray_without_one_bit?(it['class'].split) }.map { [path, it] }
+          end
+        end
+
+        def self.class_list(element) = element['class'].split.join(' ')
+
+        private
+
+        def small_gray_without_one_bit?(classes)
+          classes.any?(SMALL) && classes.any?(GRAY) && classes.none? { it.start_with?('1bit:') }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports a custom field that sets how often the content changes. The refresh rate and the
+      # playlist already decide that, so the field repeats them. A field must both be named for
+      # it (rotation, refresh, new …) and offer intervals, so data such as "collected every 2 weeks" passes.
+      class NoRefreshRateField < Check
+        NAME = /rotat|refresh|frequen|interval|how often|\bnew\b|\bnext\b/i
+        INTERVAL_OPTION = /\A(?:daily|hourly|(?:once|twice|\d+\stimes)\s(?:a|per)\s(?:day|hour)|
+                           every\s(?:\d+\s)?(?:minute|hour|day)s?|\d+\s*(?:minutes?|mins?|hours?|hrs?)\b)/ix
+        TIME_UNIT = /\b(?:minutes?|hours?)\b/i
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/11395668-recipe-best-practices'
+
+        def issues
+          offending_fields.map do |field|
+            { message: "Form field '#{field['keyname']}' sets how often the content changes. Remove it and let " \
+                       'the refresh rate and the playlist decide.', learn_more: LEARN_MORE }
+          end
+        end
+
+        def offending_fields = source.custom_field_definitions.select { refresh_rate_field?(it) }
+
+        private
+
+        def refresh_rate_field?(field)
+          return false unless "#{field['keyname'].to_s.tr('_', ' ')} #{field['name']}".match?(NAME)
+
+          case field['field_type']
+          when 'select' then interval_options?(field['options'])
+          when 'number', 'string' then [field['keyname'], field['name'],
+                                        field['description']].join(' ').match?(TIME_UNIT)
+          else false
+          end
+        end
+
+        def interval_options?(options)
+          labels = Array(options).map { it.is_a?(Hash) ? it.keys.first.to_s : it.to_s }
+          labels.count { it.match?(INTERVAL_OPTION) } >= 2
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports <style> rules that redo what the framework does across screens: fixed font
+      # sizes (no lg: scaling), hand-written line clamping and orientation reflows. CSS for
+      # art, charts and SVG text is left alone.
+      class NoStyleRestylingFramework < Check
+        STYLE_BLOCK = %r{<style\b[^>]*>(.*?)</style>}mi
+        RULE = /([^{}]*)\{([^{}]*)\}/
+        FIXED_FONT_SIZE = /font-size\s*:\s*[\d.]+\s*(?:px|pt)\b/i
+        SVG_OR_CHART = /(?:\A|[\s>+~,])(?:svg|text|tspan)\b|highcharts|chart/i
+        KINDS = {
+          font_size: ['A <style> block sets font-size in px or pt, so the text keeps one size on every screen. ' \
+                      'Use the element sizes (label, value, description, title) with lg: steps.',
+                      'https://trmnl.com/framework/docs/3.4/element_sizes'],
+          line_clamp: ['A <style> block clamps lines with -webkit-line-clamp. Use data-clamp="N" on the element.',
+                       'https://trmnl.com/framework/docs/3.4/clamp'],
+          orientation: ['A <style> block reflows with @media (orientation …). ' \
+                        'Use the portrait: and lg:portrait: prefixes.',
+                        'https://trmnl.com/framework/docs/3.4/responsive']
+        }.freeze
+
+        def issues
+          occurrences.keys.map { |kind| { message: KINDS[kind][0], learn_more: KINDS[kind][1] } }
+        end
+
+        # kind => [[path, offset], ...] for each place in a <style> block.
+        def occurrences
+          @occurrences ||= places.group_by(&:first).transform_values { it.map { |_, path, offset| [path, offset] } }
+        end
+
+        private
+
+        def places
+          source.markup_files.flat_map do |path, markup|
+            markup.to_enum(:scan, STYLE_BLOCK).flat_map do
+              start = Regexp.last_match.begin(1)
+              style_block_offsets(Regexp.last_match(1)).map { |kind, offset| [kind, path, start + offset] }
+            end
+          end
+        end
+
+        def style_block_offsets(css)
+          offsets = css.to_enum(:scan, RULE).filter_map do
+            selector, declarations = Regexp.last_match.captures
+            next if selector.match?(SVG_OR_CHART) || !declarations.match?(FIXED_FONT_SIZE)
+
+            [:font_size, Regexp.last_match.begin(2) + declarations.index(FIXED_FONT_SIZE)]
+          end
+          offsets + pattern_offsets(css, /-webkit-line-clamp/i, :line_clamp) +
+            pattern_offsets(css, /@media[^{]*orientation/i, :orientation)
+        end
+
+        def pattern_offsets(css, pattern, kind) = css.to_enum(:scan, pattern).map { [kind, Regexp.last_match.begin(0)] }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports a select option written as one quoted string, 'Voyager 1: voyager1'. TRMNL reads
+      # a string option as a label and saves it lowercased with spaces as underscores, so the
+      # value the markup sees is 'voyager_1:_voyager1'. Unquoted, YAML makes it a label and a value.
+      class SelectOptionsSplitLabelAndValue < Check
+        LABEL_AND_VALUE = /\A[^:]+:\s+\S/
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10513740-custom-plugin-form-builder'
+
+        def issues
+          split_options.map do |field_index, option_index|
+            field = source.custom_field_definitions[field_index]
+            option = field['options'][option_index]
+            { message: "Form field '#{field['keyname']}' has the option '#{option}' as one string, so TRMNL saves " \
+                       "'#{option.downcase.tr(' ', '_')}'. Write it as 'Label': value to save the value.",
+              learn_more: LEARN_MORE }
+          end
+        end
+
+        # [field index, option index] of the first such option in each select field.
+        def split_options
+          source.custom_field_definitions.each_with_index.filter_map do |field, field_index|
+            options = field['options']
+            next unless field['field_type'] == 'select' && options.is_a?(Array)
+
+            option_index = options.index { |option| option.is_a?(String) && option.match?(LABEL_AND_VALUE) }
+            [field_index, option_index] if option_index
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Recipe review asks a webhook recipe to show each install its own
+      # webhook URL, so the user can copy it into the service that pushes data.
+      class WebhookUrlShown < Check
+        MESSAGE = 'Add a custom field with field_type copyable_webhook_url, so people who install this webhook ' \
+                  'recipe can copy their webhook URL. TRMNL fills it in with the URL of each install.'
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10513740-custom-plugin-form-builder#h_431c22552a'
+
+        private
+
+        def pass?
+          source.settings['strategy'] != 'webhook' ||
+            source.custom_field_definitions.any? { it['field_type'] == 'copyable_webhook_url' }
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/diagnostic.rb

@@ -7,7 +7,8 @@ module TRMNLP
     class Diagnostic
       SETTINGS_KEYS = {
         'title_casing' => 'name', 'title_length' => 'name',
-        'description_length' => 'description', 'recipe_overview_length' => 'recipe_overview'
+        'description_length' => 'description', 'recipe_overview_length' => 'recipe_overview',
+        'webhook_url_shown' => 'strategy'
       }.freeze
       MARKUP_PATTERNS = {
         'no_async_functions' => /async function/i,
@@ -36,6 +37,7 @@ module TRMNLP
 
       def rule_id = Lint.rule_id(check.class)
 
+      # rubocop:disable-next Metrics/CyclomaticComplexity -- one branch per rule that locates its own findings
       def locations
         return source.yaml_location('src/settings.yml', SETTINGS_KEYS[rule_id]) if SETTINGS_KEYS.key?(rule_id)
         return source.locations(MARKUP_PATTERNS[rule_id]) if MARKUP_PATTERNS.key?(rule_id)
@@ -46,17 +48,22 @@ module TRMNLP
         when 'form_fields_valid' then form_field_locations
         when 'custom_field_links_embedded' then custom_field_description_locations
         when 'custom_fields_used' then project_field_locations
+        when 'no_refresh_rate_field' then settings_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 'gray_text_has_one_bit_class' then gray_text_locations
         when 'image_links_reachable' then source.locations(Regexp.union(check.unreachable_urls))
+        when 'select_options_split_label_and_value' then split_option_locations
+        when 'no_style_restyling_framework' then style_block_locations
         else []
         end
       end
 
       def class_locations
         css_class = finding[:message][/\A'([^']+)'/, 1]
-        css_class ? source.locations(Regexp.new(Regexp.escape(css_class))) : []
+        # Up to the end of the class, so `lg:title` does not also find `lg:title--small`.
+        css_class ? source.locations(Regexp.new("#{Regexp.escape(css_class)}(?![\\w-])")) : []
       end
 
       def filter_locations
@@ -73,6 +80,29 @@ module TRMNLP
         end
       end
 
+      def split_option_locations
+        check.split_options.flat_map do |field, option|
+          source.yaml_location('src/settings.yml', 'custom_fields', field, 'options', option)
+        end
+      end
+
+      def gray_text_locations
+        classes = finding[:message][/\A'([^']+)'/, 1]
+        check.offending_elements.select { |_, element| Checks::GrayTextHasOneBitClass.class_list(element) == classes }
+             .map { |path, element| source.element_location(path, element) }
+      end
+
+      def style_block_locations
+        kind = Checks::NoStyleRestylingFramework::KINDS.find { |_, (message, _)| message == finding[:message] }&.first
+        check.occurrences.fetch(kind, []).map { |path, offset| source.offset_location(path, offset) }
+      end
+
+      def settings_field_locations
+        keyname = finding[:message][/Form field '([^']+)'/, 1]
+        index = source.custom_field_definitions.index { it['keyname'].to_s == keyname }
+        index ? source.yaml_location('src/settings.yml', 'custom_fields', index) : []
+      end
+
       def form_field_locations
         warning = finding[:message].split(' — ', 2).last
         source.custom_field_definitions.each_with_index.flat_map do |field, index|

data/lib/trmnlp/lint/source.rb

@@ -87,16 +87,17 @@ module TRMNLP
 
       def locations(pattern, files: markup_files)
         files.flat_map do |path, contents|
-          contents.to_enum(:scan, pattern).map do
-            offset = Regexp.last_match.begin(0)
-            prefix = contents[0...offset]
-            line = prefix.count("\n") + 1
-            { path:, line:, column: offset - (prefix.rindex("\n") || -1),
-              snippet: contents.lines[line - 1].to_s.chomp[0, 240] }
-          end
+          contents.to_enum(:scan, pattern).map { offset_location(path, Regexp.last_match.begin(0), contents:) }
         end.uniq
       end
 
+      def offset_location(path, offset, contents: markup_files.fetch(path))
+        prefix = contents[0...offset]
+        line = prefix.count("\n") + 1
+        { path:, line:, column: offset - (prefix.rindex("\n") || -1),
+          snippet: contents.lines[line - 1].to_s.chomp[0, 240] }
+      end
+
       def yaml_location(file, *keys)
         path = file == '.trmnlp.yml' ? paths.trmnlp_config : paths.plugin_config
         contents = raw_read(path)

data/lib/trmnlp/lint.rb

@@ -10,15 +10,19 @@ 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_style_restyling_framework'
 require_relative 'lint/checks/no_size_classes'
 require_relative 'lint/checks/arbitrary_values_in_range'
 require_relative 'lint/checks/no_opacity'
+require_relative 'lint/checks/gray_text_has_one_bit_class'
 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'
 require_relative 'lint/checks/yes_no_selects_are_boolean'
+require_relative 'lint/checks/select_options_split_label_and_value'
+require_relative 'lint/checks/no_refresh_rate_field'
 require_relative 'lint/checks/coordinates_use_lat_lon'
 require_relative 'lint/checks/no_custom_filters'
 require_relative 'lint/checks/no_unknown_filters'
@@ -30,6 +34,7 @@ require_relative 'lint/checks/framework_prefixes_exist'
 require_relative 'lint/checks/no_external_qr_codes'
 require_relative 'lint/checks/custom_field_links_embedded'
 require_relative 'lint/checks/files_under_upload_limit'
+require_relative 'lint/checks/webhook_url_shown'
 
 module TRMNLP
   # Markup best-practice checks behind `trmnlp lint`.
@@ -44,15 +49,19 @@ module TRMNLP
       Checks::NoAsyncFunctions,
       Checks::WaitsForDomLoad,
       Checks::LimitedInlineStyles,
+      Checks::NoStyleRestylingFramework,
       Checks::NoSizeClasses,
       Checks::ArbitraryValuesInRange,
       Checks::NoOpacity,
+      Checks::GrayTextHasOneBitClass,
       Checks::HighchartsAnimationsDisabled,
       Checks::HighchartsElementsUnique,
       Checks::ImageLinksReachable,
       Checks::CustomFieldsUsed,
       Checks::FormFieldsValid,
       Checks::YesNoSelectsAreBoolean,
+      Checks::SelectOptionsSplitLabelAndValue,
+      Checks::NoRefreshRateField,
       Checks::CoordinatesUseLatLon,
       Checks::NoCustomFilters,
       Checks::NoUnknownFilters,
@@ -63,7 +72,8 @@ module TRMNLP
       Checks::FrameworkPrefixesExist,
       Checks::NoExternalQrCodes,
       Checks::CustomFieldLinksEmbedded,
-      Checks::FilesUnderUploadLimit
+      Checks::FilesUnderUploadLimit,
+      Checks::WebhookUrlShown
     ].freeze
 
     def self.rule_id(check_type) = check_type.name.split('::').last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase

data/lib/trmnlp/version.rb

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

data/templates/init/bin/trmnlp

@@ -7,9 +7,10 @@
 # Add a tag to stay on one release, v0.22.0 or later: trmnl/trmnlp:v0.22.0
 IMAGE=trmnl/trmnlp
 
-# Saved on the PATH as `trmnlp`, this script is what `command -v trmnlp` finds: not a gem.
+# Saved on the PATH as `trmnlp`, this script is what `command -v trmnlp` finds: not a gem. Nor is
+# another copy of it there (it names run_in_docker): that one would run its own image, not the one above.
 GEM="$(command -v trmnlp)"
-if [ -n "$GEM" ] && ! [ "$GEM" -ef "$0" ]
+if [ -n "$GEM" ] && ! [ "$GEM" -ef "$0" ] && ! grep -qs run_in_docker "$GEM"
 then
     exec "$GEM" "$@"
 fi

data/templates/run_in_docker

@@ -60,6 +60,7 @@ exec docker run \
     "${ARGS[@]}" \
     --env CI \
     --env TRMNL_API_KEY \
+    --env TRMNLP_IMAGE="$IMAGE" \
     --volume "$CONFIG_DIR:$CONTAINER_HOME/.config/trmnlp" \
     --volume "$CACHE_DIR:$CONTAINER_HOME/.cache/trmnl" \
     --volume "$(pwd):/plugin" \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.28.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -432,6 +432,7 @@ files:
 - lib/trmnlp/lint/checks/form_fields_valid.rb
 - lib/trmnlp/lint/checks/framework_classes_exist.rb
 - lib/trmnlp/lint/checks/framework_prefixes_exist.rb
+- lib/trmnlp/lint/checks/gray_text_has_one_bit_class.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
@@ -442,13 +443,17 @@ files:
 - 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_refresh_rate_field.rb
 - lib/trmnlp/lint/checks/no_size_classes.rb
+- lib/trmnlp/lint/checks/no_style_restyling_framework.rb
 - lib/trmnlp/lint/checks/no_unknown_filters.rb
 - lib/trmnlp/lint/checks/recipe_overview_length.rb
+- lib/trmnlp/lint/checks/select_options_split_label_and_value.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/webhook_url_shown.rb
 - lib/trmnlp/lint/checks/yes_no_selects_are_boolean.rb
 - lib/trmnlp/lint/diagnostic.rb
 - lib/trmnlp/lint/source.rb