active_storage-blurhash 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b2017d1770807244bbd6a7c5478f4ecb59a5f13ee5b7eb5a086c2f09856973f0
+  data.tar.gz: 9f086097d1d55813b5c0edae2e221a9470af3260e442622ca294c05646fcf48e
+SHA512:
+  metadata.gz: 0e47a24da41f183e833387d0d2d03eac0c22dfb032044a333e328be4f04d41c79d638966adc0af9672e30ec5bd464c08e44a595d4e9d45b322891d2f20723578
+  data.tar.gz: 4700ccb58f8bc1e8e0b93e8f7207a09e3ebac00e0773fe8675fa2f88489fe2c4c2ff852c22a68b41670cb7db30559d1b056b3b19ef864cd11d7cfd33102e79d0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Julian Rubisch
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,65 @@
+# ActiveStorage::Blurhash
+
+A [blurhash](https://blurha.sh/) integration for images stored in ActiveStorage. 
+
+## Motivation
+Elimination of layout shift and speeding up First/Largest Contentful Paint are among the primary goals for improving Core Web Vitals. For both scenarios, lazy loading images while displaying a temporary Blurhash before swapping it out for the actual image is a great way to enhance the loading experience and perceived performance.
+
+## Usage
+
+Suppose we have a simple `Person` model containing an `avatar` attachment:
+
+```rb
+class Person < ApplicationRecord
+  has_one_attached :avatar
+end
+```
+
+Simply swap out `image_tag` for `blurhash_image_tag` when displaying it:
+
+```erb
+<%= blurhash_image_tag person.avatar %>
+```
+
+This will create a wrapper `<div>` containing a `<canvas>` that is going to be painted with the respective blurhash.
+
+Make sure to run the install generator and backfill any existing attachments (see below). New attachments should be automatically analyzed to include the blurhash metadata.
+
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "active_storage-blurhash"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+
+Install the JavaScript packages and blurhash snippet:
+
+```bash
+$ bin/rails g active_storage:blurhash:install
+```
+
+## Backfilling
+
+Chances are you already have a large assortment of ActiveStorage attachments. In this case, we can help you out with a backfill rake task that re-analyzes all existing image blobs:
+
+```bash
+$ bin/rails active_storage_blurhash:backfill
+```
+
+If you want to throttle it, you can change the batch size using the `BATCH_SIZE` environment variable (default is 1000):
+
+```bash
+$ BATCH_SIZE=50 bin/rails active_storage_blurhash:backfill
+```
+
+Note that for each blob an `AnalyzeJob` will be appended to your job processor queue.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/helpers/blurhash_image_helper.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BlurhashImageHelper
+  def blurhash_image_tag(source, options = {})
+    case source
+    when String
+      # if a URL is passed, we have to manually re-hydrate the blob from it
+      path_parameters = Rails.application.routes.recognize_path(source)
+      blob = ActiveStorage::Blob.find_signed!(path_parameters[:signed_blob_id] || path_parameters[:signed_id])
+    when ActiveStorage::Blob
+      blob = source
+    when ActiveStorage::Attached::One
+      blob = source.blob
+    when ActiveStorage::VariantWithRecord
+      blob = source.blob
+      # dimensions of the transformation need not represent the actual aspect ratio, like in `resize_to_fit`
+      # size = source.variation.transformations[:resize]
+    end
+
+    blurhash = blob.metadata["blurhash"]
+    size ||= "#{blob.metadata["width"]}x#{blob.metadata["height"]}"
+
+    if !!blurhash
+      options[:loading] = "lazy"
+      options[:size] = size
+
+      wrapper_class = options.delete(:wrapper_class)
+      canvas_class = options.delete(:canvas_class)
+      tag.div class: wrapper_class, data: {blurhash: blurhash}, style: "position: relative" do
+        image_tag(source, options) + tag.canvas(style: "position: absolute; inset: 0; transition-property: opacity; transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1); transition-duration: 150ms;", class: canvas_class)
+      end
+    else
+      image_tag(source, options)
+    end
+  rescue ActionController::RoutingError
+    image_tag(source, options)
+  end
+end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/active_storage/blurhash/analyzer/image_magick.rb

@@ -0,0 +1,16 @@
+require "active_storage/blurhash/analyzing"
+require "active_storage/blurhash/thumbnail/image_magick"
+
+module ActiveStorage
+  module Blurhash
+    module Analyzer
+      class ImageMagick < ActiveStorage::Analyzer::ImageAnalyzer::ImageMagick
+        include ActiveStorage::Blurhash::Analyzing
+
+        protected 
+
+        def processor = "ImageMagick"
+      end
+    end
+  end
+end

data/lib/active_storage/blurhash/analyzer/vips.rb

@@ -0,0 +1,16 @@
+require "active_storage/blurhash/analyzing"
+require "active_storage/blurhash/thumbnail/vips"
+
+module ActiveStorage
+  module Blurhash
+    module Analyzer
+      class Vips < ActiveStorage::Analyzer::ImageAnalyzer::Vips
+        include ActiveStorage::Blurhash::Analyzing
+
+        protected
+        
+        def processor = "Vips"
+      end
+    end
+  end
+end

data/lib/active_storage/blurhash/analyzing.rb

@@ -0,0 +1,32 @@
+require "blurhash"
+
+module ActiveStorage
+  module Blurhash
+    module Analyzing
+      attr_accessor :thumbnail
+
+      def metadata
+        # we could also re-implement #metadata, so that the image is only read once, but it's much less DRY
+        read_image do |image|
+          build_thumbnail(image)
+          super.merge blurhash
+        end
+      end
+
+      def blurhash
+        {
+          blurhash: ::Blurhash.encode(
+            thumbnail.width,
+            thumbnail.height,
+            thumbnail.pixels
+          )
+        }
+      end
+
+      def build_thumbnail(image)
+        # we scale down the image for faster blurhash processing
+        @thumbnail ||= "ActiveStorage::Blurhash::Thumbnail::#{processor}".constantize.new(image)
+      end
+    end
+  end
+end

data/lib/active_storage/blurhash/engine.rb

@@ -0,0 +1,13 @@
+require "active_storage/blurhash/analyzer/image_magick"
+require "active_storage/blurhash/analyzer/vips"
+
+module ActiveStorage
+  module Blurhash
+    class Engine < ::Rails::Engine
+      initializer "active_storage-blurhash.analyze" do
+        Rails.application.config.active_storage.analyzers.prepend ActiveStorage::Blurhash::Analyzer::ImageMagick
+        Rails.application.config.active_storage.analyzers.prepend ActiveStorage::Blurhash::Analyzer::Vips
+      end
+    end
+  end
+end

data/lib/active_storage/blurhash/thumbnail/image_magick.rb

@@ -0,0 +1,19 @@
+module ActiveStorage
+  module Blurhash
+    module Thumbnail
+      class ImageMagick
+        delegate_missing_to :@thumbnail
+
+        def initialize(image)
+          @thumbnail = MiniMagick::Image.open(
+            ::ImageProcessing::MiniMagick.source(image.path).resize_to_limit(200, 200).call.path
+          )
+        end
+
+        def pixels
+          @thumbnail.get_pixels.flatten
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/blurhash/thumbnail/vips.rb

@@ -0,0 +1,19 @@
+module ActiveStorage
+  module Blurhash
+    module Thumbnail
+      class Vips
+        delegate_missing_to :@thumbnail
+
+        def initialize(image)
+          @thumbnail = ::Vips::Image.new_from_file(
+            ::ImageProcessing::Vips.source(image.filename).resize_to_limit(200, 200).call.path
+          )
+        end
+
+        def pixels
+          @thumbnail.write_to_memory.unpack("C*")
+        end
+      end
+    end
+  end
+end

data/lib/active_storage/blurhash/version.rb

@@ -0,0 +1,5 @@
+module ActiveStorage
+  module Blurhash
+    VERSION = "0.1.0"
+  end
+end

data/lib/active_storage/blurhash.rb

@@ -0,0 +1,7 @@
+require "active_storage/blurhash/version"
+require "active_storage/blurhash/engine"
+
+module ActiveStorage
+  module Blurhash
+  end
+end

data/lib/generators/active_storage/blurhash/install/USAGE

@@ -0,0 +1,8 @@
+Description:
+    This generator installs/pins the `blurhash` NPM package and copies over the necessary JavaScript boilerplate.
+
+Example:
+    bin/rails generate active_storage:blurhash:install
+
+    This will create:
+        app/javascript/blurhash/index.js

data/lib/generators/active_storage/blurhash/install/install_generator.rb

@@ -0,0 +1,21 @@
+class ActiveStorage::Blurhash::InstallGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  def install_javascript_deps
+    if File.exist? Rails.root.join("config", "importmap.rb")
+      say "Pinning blurhash"
+      run "bin/importmap pin blurhash"
+    else
+      say "Installing blurhash"
+      run "yarn add blurhash"
+    end
+  end
+
+  def copy_application_javascript
+    directory "javascript", "app/javascript/blurhash"
+  end
+
+  def append_to_main_javascript_entrypoint
+    append_to_file "app/javascript/application.js", "import \"./blurhash\";\n"
+  end
+end

data/lib/generators/active_storage/blurhash/install/templates/javascript/index.js

@@ -0,0 +1,107 @@
+import { decode } from "blurhash";
+
+window.ActiveStorageBlurhash = {
+  observer: new MutationObserver((mutationList, observer) => {
+    mutationList.forEach(({ type, target, addedNodes, attributeName }) => {
+      switch (type) {
+        case "childList":
+          if (addedNodes.length === 0) return;
+
+          Array.from(addedNodes)
+            .filter((node) => {
+              try {
+                return "blurhash" in node.dataset;
+              } catch (e) {
+                return false;
+              }
+            })
+            .forEach((node) => {
+              window.ActiveStorageBlurhash.renderAndLoad(node);
+            });
+          break;
+        case "attributes":
+          window.ActiveStorageBlurhash.renderAndLoad(target);
+          break;
+      }
+    });
+  }),
+  renderAndLoad(wrapper) {
+    const image = wrapper.querySelector("img");
+
+    // the image might already be completely loaded. In this case we need to do nothing
+    if (image.complete) return;
+
+    // if the image comes in with empty dimensions, we can't assign canvas data
+    if (image.width === 0 || image.height === 0) return;
+
+    const width = image.width;
+    const height = image.height;
+
+    const canvas = wrapper.querySelector("canvas");
+
+    canvas.width = width;
+    canvas.height = height;
+
+    const pixels = decode(wrapper.dataset.blurhash, width, height);
+    const ctx = canvas.getContext("2d");
+    const imageData = ctx.createImageData(width, height);
+    imageData.data.set(pixels);
+    ctx.putImageData(imageData, 0, 0);
+
+    sessionStorage.setItem(
+      `active-storage-blurhash-${wrapper.dataset.blurhash}`,
+      canvas.toDataURL(),
+    );
+
+    const swap = () => {
+      canvas.style.opacity = "0";
+    };
+
+    if (image.complete) {
+      // the image might already have been loaded
+      swap();
+    } else {
+      // else we need to wait for it to load
+      image.onload = swap;
+    }
+  },
+  restoreCanvases() {
+    const inNamespace = ([key, _payload]) =>
+      key.startsWith("active-storage-blurhash-");
+    Object.entries(sessionStorage)
+      .filter(inNamespace)
+      .forEach(([key, _payload]) => {
+        const match = /^active-storage-blurhash-(.*)/.exec(key);
+        const targetElement = document.querySelector(
+          `[data-blurhash="${match[1]}"]`,
+        );
+
+        if (targetElement) {
+          const canvas = targetElement.querySelector("canvas");
+          canvas.style.opacity = "100%";
+
+          // right now we don't do anything with the payload, since setting the opacity to 100% apparently correctly prepares the elements for caching
+          sessionStorage.removeItem(key);
+        }
+      });
+  },
+};
+
+document.addEventListener("turbo:load", () => {
+  document.querySelectorAll("div[data-blurhash]").forEach((wrapper) => {
+    window.ActiveStorageBlurhash.renderAndLoad(wrapper);
+  });
+
+  window.ActiveStorageBlurhash.observer.disconnect();
+  window.ActiveStorageBlurhash.observer.observe(document.body, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: ["data-blurhash"],
+  });
+});
+
+document.addEventListener(
+  "turbo:before-cache",
+  window.ActiveStorageBlurhash.restoreCanvases,
+);

data/lib/tasks/active_storage/blurhash_tasks.rake

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+namespace :active_storage_blurhash do
+  desc "Backfill blurhash metadata for existing ActiveStorage image attachments"
+  task backfill: :environment do
+    batch_size = ENV["BATCH_SIZE"]&.to_i || 1000
+
+    ActiveStorage::Attachment
+      .joins(:blob)
+      .where("content_type LIKE ?", "image/%")
+      .find_each(batch_size: batch_size) do |attachment|
+      attachment.analyze_later
+    end
+  end
+end

metadata

@@ -0,0 +1,189 @@
+--- !ruby/object:Gem::Specification
+name: active_storage-blurhash
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Julian Rubisch
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.3.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.3.4
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.3.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.3.4
+- !ruby/object:Gem::Dependency
+  name: blurhash
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: image_processing
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.3.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.3.4
+- !ruby/object:Gem::Dependency
+  name: mini_magick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby-vips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Use blurhashes to lazy load ActiveStorage images
+email:
+- julian@julianrubisch.at
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/config/active_storage_blurhash_manifest.js
+- app/helpers/blurhash_image_helper.rb
+- config/routes.rb
+- lib/active_storage/blurhash.rb
+- lib/active_storage/blurhash/analyzer/image_magick.rb
+- lib/active_storage/blurhash/analyzer/vips.rb
+- lib/active_storage/blurhash/analyzing.rb
+- lib/active_storage/blurhash/engine.rb
+- lib/active_storage/blurhash/thumbnail/image_magick.rb
+- lib/active_storage/blurhash/thumbnail/vips.rb
+- lib/active_storage/blurhash/version.rb
+- lib/generators/active_storage/blurhash/install/USAGE
+- lib/generators/active_storage/blurhash/install/install_generator.rb
+- lib/generators/active_storage/blurhash/install/templates/javascript/index.js
+- lib/tasks/active_storage/blurhash_tasks.rake
+homepage: https://github.com/avo-hq/active_storage-blurhash
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/avo-hq/active_storage-blurhash
+  source_code_uri: https://github.com/avo-hq/active_storage-blurhash
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Use blurhashes to lazy load ActiveStorage images
+test_files: []