active_storage-async_variants-ui 0.1.0

data/lib/active_storage/async_variants/helper.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    # View/controller helper methods. Included in the AssetTagHelperExtension
+    # (so image_tag/video_tag can use them) and added to StatesController via
+    # `helper ActiveStorage::AsyncVariants::Helper` (so the state partials can
+    # use them).
+    module Helper
+      # Invisible box reserving layout for the progress bar. The image src is a
+      # tiny gem GIF whose URL ends in the media filename (no original fetched);
+      # the video placeholder carries no <source>.
+      def async_variant_placeholder_tag(variant, html_options = {}, kind: :image)
+        opts = async_variant_box_dimensions(variant)
+          .merge(html_options.symbolize_keys.except(:src, :controls, :autoplay, :preload, :poster))
+        if kind == :video
+          content_tag(:video, "", opts)
+        else
+          src = Rails.application.routes.url_helpers.async_variant_placeholder_path(variant.blob.filename.to_s)
+          image_tag(src, opts)
+        end
+      end
+
+      def async_variant_box_dimensions(variant)
+        resize = variant.variation.transformations
+          .values_at(:resize_to_limit, :resize_to_fit, :resize_to_fill)
+          .compact.first
+        resize.is_a?(Array) ? { width: resize[0], height: resize[1] } : {}
+      end
+
+      # In test with non-bucket-backed services, the gem defers to vanilla
+      # ActiveStorage (synchronous vips transform) -- inline rendering keeps
+      # those environments simple. Otherwise, only inline a normal <img> when
+      # the variant has reached the processed terminal state.
+      def async_variant_processed_inline?(variant)
+        !variant.blob.bucket_backed? || variant.async_state == "processed"
+      end
+
+      def async_variant_resolved_src(variant, direct:)
+        if direct && variant.async_state == "processed"
+          async_variant_direct_url(variant)
+        else
+          variant.processed if variant.blob.bucket_backed?
+          async_variant_representation_path(variant)
+        end
+      end
+
+      def async_variant_frame_id(variant)
+        digest = variant.variation.digest.gsub(/[^a-zA-Z0-9_-]/, "")
+        "async-variant-#{variant.blob.id}-#{digest}"
+      end
+
+      def async_variant_frame_src(variant, kind:, direct:, html_options: {})
+        async_variant_state_path(
+          signed_blob_id: variant.blob.signed_id,
+          variation_key: variant.variation.key,
+          kind:,
+          direct:,
+          opts: html_options.slice(*PASS_THROUGH_HTML_OPTIONS),
+        )
+      end
+
+      def async_variant_direct_url(variant)
+        if cdn = ActiveStorage::AsyncVariants.cdn_host
+          "#{cdn}/#{variant.key}"
+        else
+          variant.image.url
+        end
+      end
+
+      def async_variant_representation_path(variant)
+        Rails.application.routes.url_helpers.rails_blob_representation_path(
+          variant.blob.signed_id,
+          variant.variation.key,
+          variant.blob.filename.to_s,
+        )
+      end
+    end
+  end
+end

data/lib/active_storage/async_variants/ui/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module AsyncVariants
+    module UI
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/active_storage/async_variants/ui.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_storage/async_variants"   # the plumbing gem
+require "turbo-rails"
+require "isolate_assets"
+require_relative "ui/version"
+require_relative "helper"
+require_relative "asset_tag_helper_extension"
+
+module ActiveStorage
+  module AsyncVariants
+    # HTML attributes round-tripped through the state-endpoint URL so the
+    # eventual processed-state render can apply them to the inner <img>/<video>.
+    PASS_THROUGH_HTML_OPTIONS = %i[alt width height controls autoplay preload].freeze
+
+    mattr_accessor :cdn_host
+    mattr_accessor :retry_visible_proc, default: ->(_view) { false }
+
+    # Lets the host app plug its auth chain (and thus `current_user`) into the
+    # gem's StatesController. Set to a string so resolution is deferred until
+    # the host's class is autoloadable. Defaults to ActionController::Base.
+    mattr_accessor :parent_controller, default: "ActionController::Base"
+
+    # Gates the failed-state retry affordance; the block runs in the view context.
+    def self.retry_visible_if(&block)
+      self.retry_visible_proc = block
+    end
+
+    def self.retry_visible?(view)
+      !!view.instance_exec(&retry_visible_proc)
+    rescue StandardError
+      false
+    end
+
+    class UIEngine < ::Rails::Engine
+      config.after_initialize do
+        ActionView::Helpers::AssetTagHelper.prepend(
+          ActiveStorage::AsyncVariants::AssetTagHelperExtension
+        )
+      end
+    end
+
+    Assets = IsolateAssets.register(namespace: self, engine: UIEngine, route_name: :async_variant_asset)
+  end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: active_storage-async_variants-ui
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Micah Geisel
+bindir: exe
+cert_chain: []
+date: 2026-06-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: active_storage-async_variants
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: isolate_assets
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+email:
+- micah@botandrose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".ruby-gemset"
+- ".ruby-version"
+- Appraisals
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/javascripts/progress-bar.js
+- app/assets/javascripts/retry.js
+- app/assets/stylesheets/progress.css
+- app/assets/stylesheets/retry.css
+- app/controllers/active_storage/async_variants/states_controller.rb
+- app/views/active_storage/async_variants/states/_failed.html.erb
+- app/views/active_storage/async_variants/states/_pending.html.erb
+- app/views/active_storage/async_variants/states/_processed.html.erb
+- app/views/active_storage/async_variants/states/_processing.html.erb
+- app/views/active_storage/async_variants/states/show.html.erb
+- config/routes.rb
+- features/retry_flow.feature
+- features/retry_visibility.feature
+- features/state_rendering.feature
+- features/step_definitions/dummy_steps.rb
+- features/support/env.rb
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
+- lib/active_storage/async_variants/asset_tag_helper_extension.rb
+- lib/active_storage/async_variants/helper.rb
+- lib/active_storage/async_variants/ui.rb
+- lib/active_storage/async_variants/ui/version.rb
+- log/.gitkeep
+homepage: https://github.com/botandrose/active_storage-async_variants-ui
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/botandrose/active_storage-async_variants-ui
+  source_code_uri: https://github.com/botandrose/active_storage-async_variants-ui
+  changelog_uri: https://github.com/botandrose/active_storage-async_variants-ui/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: 'Turbo-frame UI for active_storage-async_variants: image_tag/video_tag rendering,
+  progress bars, and retry.'
+test_files: []