trmnl_preview 0.15.0 → 0.17.0

data/templates/init/.github/workflows/trmnl.yml

@@ -3,6 +3,16 @@ on:
   pull_request:
   push:
     branches: [main]
+  workflow_dispatch:
+    inputs:
+      update_snapshots:
+        description: Rewrite the snapshots in tests/snapshots and upload them
+        type: boolean
+        default: false
+
+env:
+  # The trmnlp image the tests run in. Pin a release (trmnl/trmnlp:v0.17.0) to keep runs repeatable.
+  TRMNLP_IMAGE: trmnl/trmnlp:latest
 
 jobs:
   lint:
@@ -15,9 +25,30 @@ jobs:
       - run: gem install trmnl_preview
       - run: trmnlp lint
 
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: trmnlp test
+        run: >
+          docker run --rm -e CI=true -e GITHUB_STEP_SUMMARY=/summary.md
+          -v "$PWD":/plugin -v "$GITHUB_STEP_SUMMARY":/summary.md "$TRMNLP_IMAGE"
+          test --report report ${{ inputs.update_snapshots && '--update' || '' }}
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: trmnlp-report
+          path: report
+      - if: ${{ inputs.update_snapshots }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: snapshots
+          path: tests/snapshots
+
   push:
-    needs: lint
-    if: github.ref == 'refs/heads/main'
+    # Take test out of needs to push to TRMNL even when the tests fail.
+    needs: [lint, test]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

data/templates/init/.gitignore

@@ -1,2 +1,5 @@
 # trmnlp build output
 _build/
+
+# trmnlp test --report output
+report/

data/templates/init/tests/plugin_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# This plugin's tests, run with `trmnlp test` (add `--report report` for a page of every screen it drew).
+# Docs: https://github.com/usetrmnl/trmnlp#testing-plugins
+RSpec.describe 'My Plugin' do
+  # Canned answers for the requests the plugin makes, its polling urls and its transform's own, e.g.
+  #   { 'https://api.example.com/*' => { json: { temperature: 21 } } }
+  let(:mocks) { {} }
+
+  # The values of the custom fields in src/settings.yml to test with.
+  let(:custom_fields) { {} }
+
+  %w[full half_horizontal half_vertical quadrant].each do |view|
+    it "draws the #{view} view without overflow or page errors" do
+      screen = trmnl.render(view:, mocks:, custom_fields:)
+
+      expect(screen).to have_no_overflow
+      expect(screen).to have_no_problems
+    end
+  end
+
+  it "stays within TRMNL's serverless limits" do
+    expect(trmnl.transform(mocks:, custom_fields:)).to stay_within_serverless_limits
+  end
+
+  # A picture of the full view, compared pixel for pixel on every run. Record it once with
+  # `trmnlp test --update` (or the workflow's update_snapshots run) and commit tests/snapshots.
+  #
+  # it 'looks as it did' do
+  #   expect(trmnl.render(mocks:, custom_fields:)).to match_snapshot
+  # end
+end

data/trmnl_preview.gemspec

@@ -48,6 +48,7 @@ Gem::Specification.new do |spec|
   # HTML rendering
   spec.add_dependency 'activesupport', '~> 8.0'
   spec.add_dependency 'crass', '~> 1.0'
+  spec.add_dependency 'csv', '~> 3.3'
   spec.add_dependency 'nokogiri', '~> 1.18'
   spec.add_dependency 'trmnl-liquid', '~> 0.8.2'
 
@@ -56,6 +57,11 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'mini_magick', '~> 5.3'
   spec.add_dependency 'selenium-webdriver', '~> 4.44'
 
+  # Plugin tests (`trmnlp test`)
+  spec.add_dependency 'capybara', '~> 3.40'
+  spec.add_dependency 'rspec-core', '~> 3.13'
+  spec.add_dependency 'rspec-expectations', '~> 3.13'
+
   # OAuth2 (local plugin preview auth flow)
   spec.add_dependency 'oauth2', '~> 2.0'
 

data/web/public/index.js

@@ -23,7 +23,8 @@ trmnlp.connectLiveRender = function () {
 // trmnl.device values the picked model and palette decide.
 trmnlp.deviceParams = function (state) {
   const bitDepth = Math.ceil(Math.log2(state.palette?.grays || 2));
-  return new URLSearchParams({ width: state.width, height: state.height, model: state.model.name, bit_depth: bitDepth });
+  const orientation = state.isPortrait ? 'portrait' : 'landscape';
+  return new URLSearchParams({ width: state.width, height: state.height, model: state.model.name, bit_depth: bitDepth, orientation });
 };
 
 trmnlp.fetchPreview = function (pickerState) {
@@ -31,6 +32,7 @@ trmnlp.fetchPreview = function (pickerState) {
   const screenClasses = (state?.screenClasses || []).join(" ");
   const encodedScreenClasses = encodeURIComponent(screenClasses);
   let src = `/render/${trmnlp.view}.${trmnlp.formatSelect.value}?screen_classes=${encodedScreenClasses}`;
+  if (trmnlp.themeSelect.value) src += `&theme=${encodeURIComponent(trmnlp.themeSelect.value)}`;
 
   // Pass the device for both HTML and PNG renders so trmnl.device.{width,height,model,bit_depth}
   // in the Liquid context tracks the picker model selection.
@@ -38,9 +40,8 @@ trmnlp.fetchPreview = function (pickerState) {
     src += `&${trmnlp.deviceParams(state)}`;
   }
 
-  // PNG-only: dark mode + color depth from palette
+  // PNG-only: color depth from palette
   if (trmnlp.formatSelect.value === 'png' && state) {
-    const isDarkMode = state.isDarkMode ? 1 : 0;
     const grays = state.palette.grays || 2;
     const colorDepth = Math.ceil(Math.log2(grays));
     src += `&color_depth=${colorDepth}`;
@@ -214,9 +215,13 @@ trmnlp.addSelectFieldRow = function (container, key, selectedValue, options) {
   const row = document.createElement('div');
   row.className = 'custom-field-row';
 
-  const optionsHtml = options.map(opt => {
-    const selected = String(opt) === String(selectedValue) ? 'selected' : '';
-    return `<option value="${trmnlp.escapeHtml(String(opt))}" ${selected}>${trmnlp.escapeHtml(String(opt))}</option>`;
+  // Saved as TRMNL saves them: "New York" as new_york, { Label: value } as its value.
+  const choices = options.map(opt => (opt && typeof opt === 'object')
+    ? [String(Object.keys(opt)[0]), String(Object.values(opt)[0])]
+    : [String(opt), String(opt).toLowerCase().replaceAll(' ', '_')]);
+  const optionsHtml = choices.map(([label, value]) => {
+    const selected = [label, value].includes(String(selectedValue)) ? 'selected' : '';
+    return `<option value="${trmnlp.escapeHtml(value)}" ${selected}>${trmnlp.escapeHtml(label)}</option>`;
   }).join('');
 
   row.innerHTML = `
@@ -261,6 +266,7 @@ document.addEventListener("DOMContentLoaded", async function () {
   trmnlp.view = document.querySelector("meta[name='trmnl-view']").content;
   trmnlp.iframe = document.querySelector("iframe");
   trmnlp.formatSelect = document.querySelector(".select-format");
+  trmnlp.themeSelect = document.querySelector("[data-theme-select]");
   trmnlp.userData = document.getElementById("user-data");
   trmnlp.spinner = document.querySelector(".spinner");
   trmnlp.isLiveReloadEnabled =
@@ -278,6 +284,12 @@ document.addEventListener("DOMContentLoaded", async function () {
     trmnlp.fetchPreview();
   });
 
+  trmnlp.themeSelect.value = localStorage.getItem("trmnlp-theme") || "";
+  trmnlp.themeSelect.addEventListener("change", () => {
+    localStorage.setItem("trmnlp-theme", trmnlp.themeSelect.value);
+    trmnlp.fetchPreview();
+  });
+
   trmnlp.iframe.addEventListener("load", () => {
     trmnlp.spinner.style.display = "none";
   });

data/web/views/index.erb

@@ -46,6 +46,13 @@
                     <span data-dark-mode-text>Light Mode</span>
                 </button>
 
+                <select data-theme-select>
+                    <option value="">Default theme</option>
+                    <% TRMNLP::FrameworkVersion::THEMES.each do |id, name| %>
+                    <option value="<%= id %>"><%= name %></option>
+                    <% end %>
+                </select>
+
                 <!-- Optional: Reset button -->
                 <button class="btn" type="button" data-reset-button>Reset</button>
             </form>

data/web/views/render_html.erb

@@ -1,8 +1,44 @@
 <!DOCTYPE html>
 <html>
   <head>
+    <script>
+      const [andXMorePrefix, andXMoreSuffix] = <%= @and_x_more.to_json %>;
+      window.I18n = { andXMore: (count) => `${andXMorePrefix} ${count} ${andXMoreSuffix}` };
+
+      // Copied from TRMNL's plugin_rendering.js: the PNG capture waits for TRMNL_HIGHCHARTS_DONE.
+      document.addEventListener("DOMContentLoaded", () => {
+        if (!window.Highcharts) {
+          window.TRMNL_HIGHCHARTS_DONE = true;
+          return;
+        }
+
+        let counter = 0;
+        const settle = () => {
+          const allReady = Highcharts.charts.every(c => c && c.renderer && c.renderer.boxWrapper);
+          if (!allReady && counter <= 50) return false; // 5 second timeout
+
+          // A chart drawn before the title bar clamped its slot falls back to a 400px height.
+          Highcharts.charts.forEach(c => {
+            if (!c || !c.renderTo) return;
+            const w = c.renderTo.offsetWidth;
+            const h = c.renderTo.offsetHeight;
+            if (h && Math.round(c.chartHeight) !== Math.round(h)) c.setSize(w, h, false);
+          });
+          window.TRMNL_HIGHCHARTS_DONE = true;
+          return true;
+        };
+
+        if (settle()) return;
+
+        const interval = setInterval(() => {
+          counter++;
+          if (settle()) clearInterval(interval);
+        }, 100);
+      });
+    </script>
     <link rel="stylesheet" href="<%= @framework.css_url %>" />
-    <script src="<%= @framework.js_url %>"></script>
+    <% if @theme_css_url %><link rel="stylesheet" href="<%= @theme_css_url %>" /><% end %>
+    <script type="module" src="<%= @framework.js_url %>"></script>
     <meta name="trmnl-framework-version" content="<%= @framework.number %>" />
     <meta name="trmnl-framework-pinned" content="<%= @framework.pinned? %>" />
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -79,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -135,6 +149,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.44'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.40'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.40'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
 - !ruby/object:Gem::Dependency
   name: oauth2
   requirement: !ruby/object:Gem::Requirement
@@ -302,11 +358,42 @@ files:
 - README.md
 - bin/rake
 - bin/trmnlp
+- db/data/and_x_more.yml
 - db/data/form_fields.yml
 - db/data/framework_versions.yml
+- db/data/locales/cs.yml
+- db/data/locales/da.yml
+- db/data/locales/de-AT.yml
+- db/data/locales/de.yml
+- db/data/locales/en-AU.yml
+- db/data/locales/en-GB.yml
+- db/data/locales/en.yml
+- db/data/locales/es-ES.yml
+- db/data/locales/fr.yml
+- db/data/locales/he.yml
+- db/data/locales/hu.yml
+- db/data/locales/id.yml
+- db/data/locales/is.yml
+- db/data/locales/it.yml
+- db/data/locales/ja.yml
+- db/data/locales/ko.yml
+- db/data/locales/lt.yml
+- db/data/locales/nl.yml
+- db/data/locales/no.yml
+- db/data/locales/pl.yml
+- db/data/locales/pt-BR.yml
+- db/data/locales/raw.yml
+- db/data/locales/ro.yml
+- db/data/locales/ru.yml
+- db/data/locales/sk.yml
+- db/data/locales/sv.yml
+- db/data/locales/uk.yml
+- db/data/locales/zh-CN.yml
+- db/data/locales/zh-HK.yml
 - lib/trmnlp.rb
 - lib/trmnlp/api_client.rb
 - lib/trmnlp/app.rb
+- lib/trmnlp/async_callback.rb
 - lib/trmnlp/browser_pool.rb
 - lib/trmnlp/cli.rb
 - lib/trmnlp/commands.rb
@@ -320,6 +407,7 @@ files:
 - lib/trmnlp/commands/pull.rb
 - lib/trmnlp/commands/push.rb
 - lib/trmnlp/commands/serve.rb
+- lib/trmnlp/commands/test.rb
 - lib/trmnlp/config.rb
 - lib/trmnlp/config/app.rb
 - lib/trmnlp/config/plugin.rb
@@ -342,6 +430,7 @@ files:
 - lib/trmnlp/lint/checks/layouts_have_content.rb
 - 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_opacity.rb
 - lib/trmnlp/lint/checks/no_size_classes.rb
 - lib/trmnlp/lint/checks/recipe_overview_length.rb
@@ -350,6 +439,7 @@ files:
 - lib/trmnlp/lint/checks/waits_for_dom_load.rb
 - lib/trmnlp/lint/diagnostic.rb
 - lib/trmnlp/lint/source.rb
+- lib/trmnlp/merged_plugin_locals.rb
 - lib/trmnlp/oauth.rb
 - lib/trmnlp/oauth/client.rb
 - lib/trmnlp/oauth/pkce.rb
@@ -357,22 +447,45 @@ files:
 - lib/trmnlp/oauth/session.rb
 - lib/trmnlp/oauth/token_bundle.rb
 - lib/trmnlp/oauth/token_store.rb
+- lib/trmnlp/outbound_request.rb
 - lib/trmnlp/paths.rb
 - lib/trmnlp/poller.rb
+- lib/trmnlp/qr_code_intrinsic_size.rb
+- lib/trmnlp/rails_helpers.rb
 - lib/trmnlp/renderer.rb
 - lib/trmnlp/reporter.rb
 - lib/trmnlp/screen.rb
 - lib/trmnlp/screen_generator.rb
 - lib/trmnlp/screenshot.rb
+- lib/trmnlp/select_field_choices.rb
+- lib/trmnlp/testing/browser.rb
+- lib/trmnlp/testing/certificate_authority.rb
+- lib/trmnlp/testing/device_models.rb
+- lib/trmnlp/testing/frozen_clock.rb
+- lib/trmnlp/testing/inline_stylesheets.rb
+- lib/trmnlp/testing/memory_sampler.rb
+- lib/trmnlp/testing/mock_proxy.rb
+- lib/trmnlp/testing/mock_table.rb
+- lib/trmnlp/testing/node_version.rb
+- lib/trmnlp/testing/plugin.rb
+- lib/trmnlp/testing/report.html.erb
+- lib/trmnlp/testing/report.rb
+- lib/trmnlp/testing/rspec.rb
+- lib/trmnlp/testing/run.rb
+- lib/trmnlp/testing/screen.rb
+- lib/trmnlp/testing/snapshot.rb
 - lib/trmnlp/transform_backend/http.rb
 - lib/trmnlp/transform_backend/subprocess.rb
 - lib/trmnlp/transform_backend/which.rb
 - lib/trmnlp/transform_backend/wrapper.rb
 - lib/trmnlp/transform_client.rb
 - lib/trmnlp/transform_pipeline.rb
+- lib/trmnlp/transform_state.rb
 - lib/trmnlp/user_data_assembler.rb
 - lib/trmnlp/version.rb
 - lib/trmnlp/watcher.rb
+- lib/trmnlp/webhook_payload.rb
+- lib/trmnlp/webhook_receiver.rb
 - templates/init/.github/workflows/trmnl.yml
 - templates/init/.gitignore
 - templates/init/.trmnlp.yml
@@ -384,6 +497,7 @@ files:
 - templates/init/src/settings.yml
 - templates/init/src/shared.liquid
 - templates/init/src/transform.py.example
+- templates/init/tests/plugin_spec.rb
 - trmnl_preview.gemspec
 - web/public/highlight/highlight.min.js
 - web/public/highlight/styles/atom-one-dark.min.css