active_storage-async_variants-ui 0.1.0

data/app/assets/stylesheets/retry.css

@@ -0,0 +1,98 @@
+/* Scoped to the retry dialog's shadow root (linked inside its <template>). */
+:host { display: contents; }
+
+button { font: inherit; cursor: pointer; }
+
+.opener {
+  position: absolute;
+  top: 6px; right: 6px;
+  width: 22px; height: 22px;
+  background: #2b7cd6;
+  color: #fff;
+  border: 2px solid #fff;
+  border-radius: 50%;
+  font-size: 13px;
+  font-weight: bold;
+  line-height: 1;
+  padding: 0;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.35);
+  display: var(--retry-opener-display, none);
+  align-items: center;
+  justify-content: center;
+}
+.opener:hover { background: #1a5fb0; }
+
+dialog {
+  width: 720px;
+  max-width: 90vw;
+  max-height: 80vh;
+  padding: 0;
+  border: 1px solid #999;
+  border-radius: 6px;
+  background: #fff;
+  color: #222;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
+  font: 13px/1.4 system-ui, -apple-system, sans-serif;
+}
+dialog[open] { display: flex; flex-direction: column; }
+dialog::backdrop { background: rgba(0, 0, 0, 0.5); }
+
+dialog > button {
+  position: absolute;
+  top: 10px;
+  right: 12px;
+  width: 32px; height: 32px;
+  background: transparent;
+  border: none;
+  color: #888;
+  font-size: 24px;
+  line-height: 1;
+  padding: 0;
+  border-radius: 4px;
+  z-index: 1;
+}
+dialog > button:hover { color: #000; background: rgba(0, 0, 0, 0.08); }
+
+header { padding: 20px 24px 0 24px; }
+header h3 {
+  margin: 0;
+  font-size: 16px;
+  font-weight: bold;
+  color: #111;
+  padding-right: 32px;
+}
+
+section {
+  flex: 1 1 auto;
+  overflow: auto;
+  padding: 12px 24px 20px 24px;
+  min-height: 0;
+}
+section pre {
+  background: #f5f5f5;
+  color: #222;
+  border: 1px solid #ddd;
+  padding: 8px;
+  font: 11px/1.4 ui-monospace, Menlo, monospace;
+  white-space: pre-wrap;
+  word-break: break-all;
+  margin: 0;
+}
+
+footer {
+  flex: 0 0 auto;
+  border-top: 1px solid #ddd;
+  padding: 12px 20px;
+  display: flex;
+  justify-content: flex-end;
+  background: #fafafa;
+}
+footer button {
+  padding: 8px 16px;
+  background: #2a7;
+  color: #fff;
+  border: none;
+  border-radius: 4px;
+  font-weight: bold;
+}
+footer button:disabled { opacity: 0.5; cursor: wait; }

data/app/controllers/active_storage/async_variants/states_controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    class StatesController < ActiveStorage::AsyncVariants.parent_controller.constantize
+      # signed_blob_id + variation_key in URL act as CSRF: both require app's secret.
+      skip_forgery_protection
+
+      helper "turbo/frames"
+      helper ActiveStorage::AsyncVariants::Helper
+
+      layout false
+
+      # 1x1 transparent GIF served at a filename-bearing URL, so the
+      # processing/failed <img> identifies its media without fetching anything.
+      TRANSPARENT_GIF = "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7".unpack1("m").freeze
+
+      before_action :set_variant, only: %i[show retry]
+
+      def show
+      end
+
+      def placeholder
+        expires_in 1.year, public: true
+        send_data TRANSPARENT_GIF, type: "image/gif", disposition: "inline"
+      end
+
+      def retry
+        @variant.blob.variant_records.where(
+          variation_digest: @variant.variation.digest,
+          state: "failed",
+        ).destroy_all
+        @variant.enqueue!
+
+        redirect_to Rails.application.routes.url_helpers.async_variant_state_path(
+          signed_blob_id: params[:signed_blob_id],
+          variation_key: params[:variation_key],
+          kind: params[:kind],
+          direct: params[:direct],
+          opts: async_variant_html_options.presence,
+        ), status: :see_other
+      end
+
+      helper_method :async_variant_kind, :async_variant_direct?, :async_variant_html_options
+
+      private
+
+      def set_variant
+        blob = ActiveStorage::Blob.find_signed!(params[:signed_blob_id])
+        variation = ActiveStorage::Variation.decode(params[:variation_key])
+        @variant = blob.variant(variation)
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        head :not_found
+      end
+
+      def async_variant_kind
+        params[:kind].to_s == "video" ? :video : :image
+      end
+
+      def async_variant_direct?
+        ActiveModel::Type::Boolean.new.cast(params[:direct])
+      end
+
+      def async_variant_html_options
+        params[:opts]
+          &.permit(*ActiveStorage::AsyncVariants::PASS_THROUGH_HTML_OPTIONS)
+          .to_h
+      end
+    end
+  end
+end

data/app/views/active_storage/async_variants/states/_failed.html.erb

@@ -0,0 +1,44 @@
+<div class="async-variant-state async-variant-failed">
+  <%= async_variant_placeholder_tag(variant, html_options, kind: kind) %>
+
+  <%= content_tag "progress-bar", "", mode: "circular", error: "", class: "async-variant-progress" %>
+
+  <%= ActiveStorage::AsyncVariants.stylesheet_link_tag "progress" %>
+  <%= ActiveStorage::AsyncVariants.javascript_include_tag "progress-bar", type: "module" %>
+
+  <% if ActiveStorage::AsyncVariants.retry_visible?(self) %>
+    <% dialog_id = "#{async_variant_frame_id(variant)}-error" %>
+    <% form_id = "#{dialog_id}-form" %>
+    <%# Light DOM, so the custom property inherits into the shadow root. %>
+    <style>
+      .async-variant-failed { --retry-opener-display: none; }
+      .async-variant-failed:hover { --retry-opener-display: inline-flex; }
+    </style>
+    <%# In the light DOM so its submit reaches Turbo, and so preventDefault on the
+        buttons doesn't also cancel the submit. %>
+    <form action="<%= Rails.application.routes.url_helpers.async_variant_state_retry_path(signed_blob_id:, variation_key:, kind:, direct:, opts: html_options) %>"
+          method="post"
+          id="<%= form_id %>"
+          data-turbo-frame="<%= async_variant_frame_id(variant) %>"
+          hidden></form>
+    <async-variant-retry>
+      <template shadowrootmode="open">
+        <%= ActiveStorage::AsyncVariants.stylesheet_link_tag "retry" %>
+        <button class="opener" type="button"
+                onclick="event.preventDefault(); event.stopPropagation(); this.getRootNode().getElementById('<%= dialog_id %>').showModal()"
+                title="Variant processing failed — click for details">?</button>
+        <dialog id="<%= dialog_id %>">
+          <button type="button"
+                  onclick="event.preventDefault(); event.stopPropagation(); this.closest('dialog').close()">&times;</button>
+          <header><h3>Variant processing failed</h3></header>
+          <section><pre><%= variant.error %></pre></section>
+          <footer>
+            <button type="button"
+                    onclick="event.preventDefault(); event.stopPropagation(); this.disabled = true; this.textContent = 'Retrying…'; document.getElementById('<%= form_id %>').requestSubmit()">Retry processing</button>
+          </footer>
+        </dialog>
+      </template>
+    </async-variant-retry>
+    <%= ActiveStorage::AsyncVariants.javascript_include_tag "retry", type: "module" %>
+  <% end %>
+</div>

data/app/views/active_storage/async_variants/states/_pending.html.erb

@@ -0,0 +1 @@
+<%= render "active_storage/async_variants/states/processing", local_assigns %>

data/app/views/active_storage/async_variants/states/_processed.html.erb

@@ -0,0 +1,5 @@
+<%
+  method = kind == :video ? :video_tag : :image_tag
+  src = direct ? async_variant_direct_url(variant) : async_variant_representation_path(variant)
+%>
+<%= send method, src, **html_options.symbolize_keys %>

data/app/views/active_storage/async_variants/states/_processing.html.erb

@@ -0,0 +1,15 @@
+<div class="async-variant-state async-variant-processing">
+  <%= async_variant_placeholder_tag(variant, html_options, kind: kind) %>
+
+  <%= content_tag "progress-bar", "", mode: "circular", class: "async-variant-progress", percent: variant.progress, rate: variant.progress_rate %>
+</div>
+
+<%= ActiveStorage::AsyncVariants.stylesheet_link_tag "progress" %>
+<%= ActiveStorage::AsyncVariants.javascript_include_tag "progress-bar", type: "module" %>
+<% interval_ms = ActiveStorage::AsyncVariants.heartbeat_interval.in_seconds * 1000 %>
+<script>
+  (() => {
+    const frame = document.currentScript?.closest("turbo-frame")
+    setTimeout(() => frame?.reload(), <%= interval_ms %>)
+  })()
+</script>

data/app/views/active_storage/async_variants/states/show.html.erb

@@ -0,0 +1,10 @@
+<%= turbo_frame_tag async_variant_frame_id(@variant) do %>
+  <%= render "active_storage/async_variants/states/#{@variant.async_state}", {
+    variant: @variant,
+    html_options: async_variant_html_options,
+    kind: async_variant_kind,
+    direct: async_variant_direct?,
+    signed_blob_id: params[:signed_blob_id],
+    variation_key: params[:variation_key],
+  } %>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  get  "/active_storage/async_variants/states/:signed_blob_id/:variation_key",
+    to: "active_storage/async_variants/states#show",
+    as: :async_variant_state
+  post "/active_storage/async_variants/states/:signed_blob_id/:variation_key/retry",
+    to: "active_storage/async_variants/states#retry",
+    as: :async_variant_state_retry
+
+  # Tiny 1x1 GIF whose URL carries the media's filename, so the processing/failed
+  # box reserves layout without fetching the original through a representation.
+  get "/active_storage/async_variants/placeholder/:filename",
+    to: "active_storage/async_variants/states#placeholder",
+    as: :async_variant_placeholder,
+    constraints: { filename: %r{[^/]+} },
+    format: false
+
+  ActiveStorage::AsyncVariants::Assets.draw(self, "/active_storage/async_variants/assets")
+end

data/features/retry_flow.feature

@@ -0,0 +1,20 @@
+Feature: Clicking the retry affordance opens a dialog and resubmits the variant
+
+  Background:
+    Given a user with an attached avatar
+    And the retry affordance is visible to everyone
+
+  Scenario: Clicking the opener reveals the error inside the shadow-DOM dialog
+    Given the avatar's :thumb_proc variant is in failed state with error "boom from upstream"
+    When I visit the avatar page for the :thumb_proc variant
+    And I click the retry opener
+    Then the failure dialog should be open
+    And the failure dialog should contain "boom from upstream"
+
+  Scenario: Submitting Retry destroys the failed record and re-enqueues
+    Given the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    And I click the retry opener
+    And I click "Retry processing"
+    Then the frame should render the processing state
+    And the page should not have navigated away

data/features/retry_visibility.feature

@@ -0,0 +1,23 @@
+Feature: The retry affordance is gated by ActiveStorage::AsyncVariants.retry_visible_if
+
+  Scenario: When retry_visible_if returns true, the retry chrome renders
+    Given a user with an attached avatar
+    And the retry affordance is visible to everyone
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    Then the retry affordance should be visible
+
+  Scenario: When retry_visible_if returns false, the retry chrome is omitted
+    Given a user with an attached avatar
+    And the retry affordance is hidden
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    Then the retry affordance should NOT be visible
+
+  Scenario: A proc that consults current_user gates the affordance per-viewer
+    Given a user with an attached avatar
+    And the retry affordance requires a signed-in user
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I sign in as the user
+    And I visit the avatar page for the :thumb_proc variant
+    Then the retry affordance should be visible

data/features/state_rendering.feature

@@ -0,0 +1,40 @@
+Feature: image_tag with async: true emits the right markup per variant state
+
+  Scenario: A processed variant emits a plain <img> -- no turbo-frame, no chrome
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processed state
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should NOT contain a turbo-frame
+
+  Scenario: An unprocessed variant emits a turbo-frame in processing state
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processing state
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the frame should render the processing state
+
+  Scenario: A processing variant renders an indeterminate progress bar before any heartbeat
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processing state
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the frame should render a progress bar
+    And the progress bar should be indeterminate
+    And the placeholder image should reserve layout
+
+  Scenario: A processing variant with reported progress renders a determinate progress bar
+    Given a user with an attached avatar
+    And the avatar's :thumb_proc variant is in processing state
+    And the avatar's :thumb_proc variant has reported 42% progress
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the progress bar should show 42%
+
+  Scenario: A failed variant renders the failed partial inside the frame
+    Given a user with an attached avatar
+    And the retry affordance is visible to everyone
+    And the avatar's :thumb_proc variant is in failed state with error "boom"
+    When I visit the avatar page for the :thumb_proc variant
+    Then the page should contain a turbo-frame
+    And the frame should render the failed state
+    And the frame should render an error progress bar

data/features/step_definitions/dummy_steps.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+Given /^a user with an attached avatar$/ do
+  @user = User.create!
+  attach_avatar_to(@user)
+end
+
+Given /^the avatar's :(\w+) variant is in (pending|processing|processed|failed) state(?: with error "([^"]+)")?$/ do |variant_name, state, error|
+  variant = @user.avatar.variant(variant_name.to_sym)
+  if state == "processed"
+    simulate_processed_variant(variant)
+  else
+    create_variant_record(variant, state: state, error: error)
+  end
+end
+
+Given /^the avatar's :(\w+) variant has reported (\d+)% progress$/ do |variant_name, percent|
+  variant = @user.avatar.variant(variant_name.to_sym)
+  record = variant.blob.variant_records.find_by(variation_digest: variant.variation.digest)
+  record.update!(progress: percent.to_i)
+end
+
+Then /^the frame should render a progress bar$/ do
+  expect(page).to have_css("turbo-frame progress-bar", visible: :all)
+end
+
+Then /^the frame should render an error progress bar$/ do
+  expect(page).to have_css("turbo-frame progress-bar[error]", visible: :all)
+end
+
+Then /^the progress bar should be indeterminate$/ do
+  expect(page).to have_css("turbo-frame progress-bar:not([percent])", visible: :all)
+end
+
+Then /^the progress bar should show (\d+)%$/ do |percent|
+  expect(page).to have_css(%(turbo-frame progress-bar[percent="#{percent}"]), visible: :all)
+end
+
+# Default (visible-only) matcher: passes only because the placeholder is hidden
+# via opacity (not visibility/display), so Capybara still sees it.
+Then /^the placeholder image should reserve layout$/ do
+  expect(page).to have_css("turbo-frame .async-variant-processing img")
+end
+
+Given /^the retry affordance is visible to everyone$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { true }
+end
+
+Given /^the retry affordance is hidden$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { false }
+end
+
+Given /^the retry affordance requires a signed-in user$/ do
+  ActiveStorage::AsyncVariants.retry_visible_if { current_user.present? }
+end
+
+When /^I sign in as the (admin|user)$/ do |_kind|
+  visit "/session/#{@user.id}"
+end
+
+When /^I visit the avatar page for the :(\w+) variant$/ do |variant_name|
+  visit "/avatars/#{@user.id}/#{variant_name}"
+end
+
+Then /^the page should contain a turbo-frame$/ do
+  expect(page).to have_css("turbo-frame")
+end
+
+Then /^the page should NOT contain a turbo-frame$/ do
+  expect(page).to have_no_css("turbo-frame")
+  expect(page).to have_css("img")
+end
+
+Then /^the frame should render the (failed|processing|processed) state$/ do |state|
+  expect(page).to have_css("turbo-frame .async-variant-#{state}")
+end
+
+Then /^the retry affordance should be visible$/ do
+  expect(page).to have_css("async-variant-retry", visible: :all)
+end
+
+Then /^the retry affordance should NOT be visible$/ do
+  expect(page).to have_no_css("async-variant-retry", visible: :all)
+end
+
+Then /^the page should not have navigated away$/ do
+  expect(page).to have_css("h1#page-marker")
+end
+
+Then /^the failure dialog should be open$/ do
+  expect(page).to have_css("async-variant-retry", visible: :all)
+  open = page.evaluate_script(<<~JS)
+    (() => {
+      const host = document.querySelector("async-variant-retry")
+      if (!host || !host.shadowRoot) return false
+      const dialog = host.shadowRoot.querySelector("dialog")
+      return dialog ? dialog.open : false
+    })()
+  JS
+  expect(open).to eq(true)
+end
+
+Then /^the failure dialog should contain "([^"]+)"$/ do |text|
+  contains = page.evaluate_script(<<~JS)
+    (() => {
+      const host = document.querySelector("async-variant-retry")
+      if (!host || !host.shadowRoot) return false
+      return host.shadowRoot.textContent.includes(#{text.inspect})
+    })()
+  JS
+  expect(contains).to eq(true)
+end
+
+# Wait for Turbo to swap the frame and our shim to attach the shadow root.
+def wait_for_shadow!
+  Timeout.timeout(5) do
+    loop do
+      attached = page.evaluate_script("!!document.querySelector('async-variant-retry')?.shadowRoot")
+      break if attached
+      sleep 0.05
+    end
+  end
+end
+
+When /^I click the retry opener$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector(".opener").click()
+  JS
+end
+
+When /^I click "Retry processing"$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector("footer button").click()
+  JS
+end
+
+When /^I close the failure dialog$/ do
+  wait_for_shadow!
+  page.evaluate_script(<<~JS)
+    document.querySelector("async-variant-retry").shadowRoot.querySelector("dialog > button[type=button]").click()
+  JS
+end

data/features/support/env.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+ENV["RAILS_ENV"] ||= "test"
+require File.expand_path("../../spec/dummy/config/environment", __dir__)
+
+require "capybara"
+require "capybara/cucumber"
+require "capybara/cuprite"
+require_relative "../../spec/support/schema"
+
+DummySchema.load!
+
+Capybara.register_driver(:cuprite) do |app|
+  Capybara::Cuprite::Driver.new(app, window_size: [1200, 900], timeout: 10, process_timeout: 20, js_errors: true)
+end
+Capybara.app                = Rails.application
+Capybara.javascript_driver  = :cuprite
+Capybara.default_driver     = :cuprite
+Capybara.server             = :puma, { Silent: true }
+
+ActionController::Base.allow_forgery_protection = false
+
+# Test adapter just records enqueued jobs -- we don't want them to actually run
+# during browser tests (they'd call real transformers and modify variant_records
+# behind the test's back). The retry step seeds the new state explicitly.
+ActiveJob::Base.queue_adapter = :test
+
+Before { DummySchema.cleanup! }

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "irb"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "simplecov", require: false
+gem "rspec-rails"
+gem "rails", "~> 7.2.0"
+gem "sqlite3"
+gem "cucumber"
+gem "capybara"
+gem "cuprite"
+gem "puma"
+
+gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "irb"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "simplecov", require: false
+gem "rspec-rails"
+gem "rails", "~> 8.0.0"
+gem "sqlite3"
+gem "cucumber"
+gem "capybara"
+gem "cuprite"
+gem "puma"
+
+gemspec path: "../"

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,18 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "irb"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "simplecov", require: false
+gem "rspec-rails"
+gem "rails", "~> 8.1.0"
+gem "sqlite3"
+gem "cucumber"
+gem "capybara"
+gem "cuprite"
+gem "puma"
+
+gemspec path: "../"

data/lib/active_storage/async_variants/asset_tag_helper_extension.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    # Prepended onto ActionView::Helpers::AssetTagHelper. Adds `async:` and
+    # `direct:` options to image_tag/video_tag; routes unprocessed variants
+    # through a <turbo-frame> whose body lives in StatesController#show.
+    module AssetTagHelperExtension
+      include ActiveStorage::AsyncVariants::Helper
+
+      def image_tag(source, options = {})
+        async_variant_tag(:image, [source], options) do |urls, opts|
+          super(urls.first, opts)
+        end
+      end
+
+      def video_tag(*sources)
+        options = sources.extract_options!
+        async_variant_tag(:video, sources, options) do |urls, opts|
+          super(*urls, opts)
+        end
+      end
+
+      private
+
+      def async_variant_tag(kind, sources, options)
+        options = options.symbolize_keys
+        async = options.delete(:async)
+        direct = options.delete(:direct)
+        return yield(sources, options) if !async && !direct
+
+        variant, *rest = sources
+        assert_async_variant!(variant)
+
+        if async && !async_variant_processed_inline?(variant)
+          async_variant_turbo_frame(variant, kind:, direct:, html_options: options)
+        else
+          yield [async_variant_resolved_src(variant, direct:), *rest], options
+        end
+      end
+
+      def assert_async_variant!(source)
+        unless source.is_a?(ActiveStorage::VariantWithRecord) || source.is_a?(ActiveStorage::Preview)
+          raise ArgumentError, "image_tag/video_tag with async:/direct: requires an ActiveStorage::VariantWithRecord or Preview, got #{source.class}"
+        end
+      end
+
+      def async_variant_turbo_frame(variant, kind:, direct:, html_options:)
+        content_tag(
+          :"turbo-frame",
+          "",
+          id: async_variant_frame_id(variant),
+          src: async_variant_frame_src(variant, kind: kind, direct: direct, html_options: html_options),
+          refresh: "morph",
+        )
+      end
+    end
+  end
+end