RubyGems - social_construct - Versions diffs - 0.1.0 → 0.2.0 - Mend

social_construct 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

checksums.yaml +4 -4
data/README.md +97 -132
data/app/models/social_construct/base_card.rb +209 -32
data/lib/generators/social_construct/install/templates/social_cards_layout.html.erb +2 -1
data/lib/social_construct/engine.rb +1 -0
data/lib/social_construct/version.rb +1 -1
metadata +5 -5

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10cb6057e914282f135714277ab5459c5794e1892a4a2a0825c24cc64ec6259c
-  data.tar.gz: 239310809089b66d572365265074e18a32d1ddc7c693374d60090276a38d793f
+  metadata.gz: 1a6da2405e4a0117c652f0273ba675242053926527418d9fdcb3acf01df55342
+  data.tar.gz: bb626f6d95fac62a0b0696b8c6ceb083f3109d03b74ad670f5496640f44eacb8
 SHA512:
-  metadata.gz: f269fe451a28fae49d20e8c78953b810fe39c7db26559c80d8f555a8cc03ec9f0d80ce811ff6aa94466ba815fd6b4dfe4c19542477878729201b52f70dfbf4aa
-  data.tar.gz: 868aa2dd22efbae1a7e105c8d10f0cfb2bbeee80f71386acdc44c1205b8672a279eefbca334255255230808863d5bde084de1b3ab5c936da39359d5da5dd4f32
+  metadata.gz: 29c1411422336bffdfb0fda48294395b8043dddab4ba44dd20b7bc8f3a367311a33dc1a484e79fb30403a5cfdf7c5b17d90512ac594151b7324d189a5be1a013
+  data.tar.gz: ca8995422185f360f50feeb4f0d0860f592e7d821b389305e8199936f388ff7b0d53672fcccc50772f34ba686b49eaa9efade2e864ab3057c2af6836eb8a24e3

data/README.md CHANGED Viewed

@@ -1,188 +1,153 @@
-# SocialConstruct
+<img src="https://s3.brnbw.com/Stack-C9apVxz8Pg.webp" width="600">
-A Rails engine for generating social media preview cards (Open Graph images) with built-in preview functionality.
+- Design using HTML/CSS
+- Supports images, fonts, caching, ...
+- Built-in previews in development (like mailers)
+- Only requirement is Chrome(ium)
-## Installation
+## Example
-Add to your Gemfile:
+Create a card class:
 ```ruby
-gem "social_construct"
-```
-Run the installation generator:
-```bash
-bundle install
-bin/rails generate social_construct:install
-```
-This will:
-- Create a configuration initializer
-- Set up ApplicationSocialCard base class
-- Create an example social card with template
-- Add a shared layout for social cards
-- Mount the preview interface in development
-- Create example preview classes
-## Usage
-### 1. Create your base social card class
-```ruby
-# app/social_cards/application_social_card.rb
-class ApplicationSocialCard < SocialConstruct::BaseCard
-  include SocialConstruct::CardConcerns
-  # Set the logo path for your application
-  self.logo_path = Rails.root.join("app/assets/images/logo.png")
-end
-```
-### 2. Create specific social card classes
-```ruby
-# app/social_cards/item_social_card.rb
-class ItemSocialCard < ApplicationSocialCard
-  def initialize(item)
-    super()
-    @item = item
+class PostSocialCard < ApplicationSocialCard
+  def initialize(post)
+    @post = post
   end
-  private
   def template_assigns
     {
-      item: @item,
-      cover_image_data_url: image_to_data_url(@item.cover_image, resize_to_limit: [480, 630], saver: {quality: 75}),
-      logo_data_url: logo_data_url
+      title: @post.title,
+      author: @post.author_name,
+      avatar: image_to_data_url(@post.author.avatar)
     }
   end
 end
 ```
-### 3. Create templates
-Templates go in `app/views/social_cards/` and should match your class names:
+Create a template:
 ```erb
-<!-- app/views/social_cards/item_social_card.html.erb -->
+<!-- app/views/social_cards/post_social_card.html.erb -->
 <div class="card">
-  <h1><%= item.title %></h1>
-  <!-- Your card HTML -->
+  <img src="<%= avatar %>" class="logo">
+  <h1><%= title %></h1>
+  <p>by <%= author %></p>
 </div>
 ```
-### 4. Optional: Use a shared layout
-Create `app/views/layouts/social_cards.html.erb` for shared HTML structure:
+Add a controller action:
-```erb
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8">
-    <style>
-      /* Shared styles */
-    </style>
-    <%= yield :head %>
-  </head>
-  <body>
-    <%= yield %>
-  </body>
-</html>
-```
+```ruby
+class PostsController < ApplicationController
+  include SocialConstruct::Controller
-### 5. Create preview classes for development
+  # ...
-```ruby
-# app/social_cards/previews/item_social_card_preview.rb
-class ItemSocialCardPreview
-  def default
-    item = Item.first || Item.new(title: "Example Item")
-    ItemSocialCard.new(item)
-  end
+  def social_image
+    @post = Post.find(params[:id])
-  def with_long_title
-    item = Item.new(title: "This is a very long title that will test text wrapping")
-    ItemSocialCard.new(item)
+    send_social_card(
+      PostSocialCard.new(@post),
+      cache_key: [@post.id, @post.updated_at]
+    )
   end
 end
 ```
-Visit `/rails/social_cards` in development to see all your previews.
+## Setup
-### 6. Use in your controllers
+```sh
+$ bundle add social_construct && bundle install
+$ bin/rails generate social_construct:install
+```
-Include the controller concern:
+## Images
-```ruby
-class ItemsController < ApplicationController
-  include SocialConstruct::Controller
+Convert ActiveStorage attachments to Base64 `data://` URLs:
-  def og
-    @item = Item.find(params[:id])
-    render ItemSocialCard.new(@item)
-  end
+```ruby
+def template_assigns
+  {
+    cover_image: image_to_data_url(@post.cover_image),
+    avatar: image_to_data_url(@post.author.avatar, resize_to_limit: [200, 200])
+  }
 end
 ```
-The `render` method automatically handles both formats:
+## Fonts
-- `.png` - Generates the actual PNG image
-- `.html` - Shows the HTML preview (useful for debugging)
+### Remote fonts
-Or with caching:
+Just import them normally and they should work.
-```ruby
-def og
-  @item = Item.find(params[:id])
+```erb
+<style>
+  @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap');
+  body { font-family: 'Inter', sans-serif; }
+</style>
+```
-  cache_key = [
-    "social-cards",
-    "item",
-    @item.id,
-    @item.updated_at.to_i
-  ]
+### Local fonts
-  render ItemSocialCard.new(@item), cache_key: cache_key
+Store fonts in `app/assets/fonts/` and embed as `data://` URLs:
+```ruby
+class LocalFontsCard < ApplicationSocialCard
+  def template_assigns
+    {
+      custom_font_css: generate_font_face(
+        "custom-font-name",
+        "Recursive_VF_1.085--subset-GF_latin_basic.woff2",
+        weight: "300 1000"
+      )
+    }
+  end
 end
 ```
-Alternative API:
+And include in template:
-```ruby
-def og
-  @item = Item.find(params[:id])
-  card = ItemSocialCard.new(@item)
-  send_social_card(card,
-    cache_key: ["social-cards", @item.id, @item.updated_at.to_i],
-    expires_in: 7.days
-  )
-end
+```erb
+<style>
+  <%= custom_font_css %>
+  body {
+    font-family: 'custom-font-name', sans-serif;
+  }
+</style>
 ```
-## Configuration
+## Previews
-Configure in your initializer:
+Mount the preview engine:
 ```ruby
-# config/initializers/social_construct.rb
+Rails.application.routes.draw do
+  if Rails.env.development?
+    mount(SocialConstruct::Engine => "/rails/social_cards")
+  end
+end
+```
-# Template path (default: "social_cards")
-Rails.application.config.social_construct.template_path = "custom_path"
+Create preview classes:
-# Enable debug logging (default: false)
-SocialConstruct::BaseCard.debug = true
-```
+```ruby
+# app/social_cards/previews/post_social_card_preview.rb
+class PostSocialCardPreview
+  def default
+    PostSocialCard.new(Post.first)
+  end
-## Requirements
+  def long_title
+    post = Post.new(title: "A very long title that demonstrates text wrapping behavior")
+    PostSocialCard.new(post)
+  end
+end
+```
-- Rails 7.0+
-- Ferrum (headless Chrome driver)
-- Marcel (MIME type detection)
+Visit `http://localhost:3000/rails/social_cards` to preview all cards.
 ## License

data/app/models/social_construct/base_card.rb CHANGED Viewed

@@ -6,14 +6,14 @@ module SocialConstruct
     include ActionView::Helpers
     include Rails.application.routes.url_helpers
-    attr_reader :width, :height
-    # Class-level debug setting
     cattr_accessor :debug, default: false
-    def initialize
-      @width = 1200
-      @height = 630
+    def width
+      @width || 1200
+    end
+    def height
+      @height || 630
     end
     def render
@@ -33,7 +33,7 @@ module SocialConstruct
       browser_options = {
         headless: true,
         timeout: 30,
-        window_size: [@width, @height]
+        window_size: [width, height]
       }
       # Add Docker-specific options in production
@@ -81,13 +81,38 @@ module SocialConstruct
         browser.goto("data:text/html;charset=utf-8,#{encoded_html}")
       end
-      browser.set_viewport(width: @width, height: @height)
+      browser.set_viewport(width: width, height: height)
       # Wait for the page to fully load
       browser.network.wait_for_idle
-      # Add extra wait for complex pages with large images
-      sleep(0.5)
+      # Wait for all images and fonts to load
+      browser.execute(
+        <<~JS
+          return new Promise((resolve) => {
+            // Check if all images are loaded
+            const images = Array.from(document.querySelectorAll('img'));
+            const imagePromises = images.map(img => {
+              if (img.complete) return Promise.resolve();
+              return new Promise(res => {
+                img.addEventListener('load', res);
+                img.addEventListener('error', res);
+              });
+            });
+            // Check document fonts
+            const fontPromise = document.fonts?.ready || Promise.resolve();
+            // Wait for everything
+            Promise.all([...imagePromises, fontPromise]).then(() => {
+              // Small delay to ensure rendering is complete
+              requestAnimationFrame(() => {
+                setTimeout(resolve, 50);
+              });
+            });
+          });
+        JS
+      )
       # Log page readiness
       if debug
@@ -108,6 +133,21 @@ module SocialConstruct
         log_debug("Body HTML length: #{body_html_length}")
       end
+      # Ensure content is painted before screenshot
+      browser.execute(
+        <<~JS
+          // Force layout and paint
+          document.body.offsetHeight;
+          // Check if we have visible content
+          const hasContent = document.body.textContent.trim().length > 0 ||
+                            document.querySelectorAll('img').length > 0;
+          if (!hasContent) {
+            console.warn('Page appears to have no visible content');
+          }
+          return hasContent;
+        JS
+      )
       screenshot = browser.screenshot(
         encoding: :binary,
         quality: 100,
@@ -116,27 +156,6 @@ module SocialConstruct
       log_debug("Screenshot generated, size: #{screenshot.bytesize} bytes")
-      # Check if screenshot might be blank (very small file size indicates mostly white/single color)
-      # Less than 10KB usually means it's mostly one color
-      if screenshot.bytesize < 10_000
-        log_debug("Screenshot seems too small, might be blank. Retrying with delay...", :warn)
-        # Wait a bit more and try again
-        sleep(1)
-        # Force a paint
-        browser.execute(
-          "document.body.style.display = 'none'; document.body.offsetHeight; document.body.style.display = 'flex';"
-        )
-        screenshot = browser.screenshot(
-          encoding: :binary,
-          quality: 100,
-          full: false
-        )
-        log_debug("Retry screenshot size: #{screenshot.bytesize} bytes")
-      end
       screenshot
     rescue => e
       log_debug("Ferrum screenshot failed: #{e.message}", :error)
@@ -191,14 +210,93 @@ module SocialConstruct
         content_type = blob.content_type || "image/jpeg"
         image_data = blob.download
+        file_size = image_data.bytesize
+        # Check image size limitations
+        # 2MB hard limit
+        if file_size > 2_000_000
+          log_debug("Image is #{file_size} bytes (#{file_size / 1024 / 1024}MB), exceeds 2MB data URL limit", :error)
+          return nil
+          # 500KB warning threshold
+        elsif file_size > 500_000
+          log_debug(
+            "Image is #{file_size} bytes (#{file_size / 1024}KB), consider optimizing for better performance",
+            :warn
+          )
+        end
-        "data:#{content_type};base64,#{Base64.strict_encode64(image_data)}"
+        encoded_data = Base64.strict_encode64(image_data)
+        log_debug("Image loaded: #{file_size} bytes (#{encoded_data.bytesize} bytes encoded)")
+        "data:#{content_type};base64,#{encoded_data}"
       rescue => e
         log_debug("Failed to convert image to data URL: #{e.message}", :error)
         nil
       end
     end
+    # Local font helper - converts font file to data URL
+    def font_to_data_url(font_path)
+      full_path = if font_path.start_with?("/")
+        font_path
+      else
+        Rails.root.join("app", "assets", "fonts", font_path)
+      end
+      return nil unless File.exist?(full_path)
+      begin
+        font_data = File.read(full_path)
+        file_size = font_data.bytesize
+        # Check file size limitations
+        # Most browsers have data URL limits around 2MB, but performance degrades after ~500KB
+        # 2MB hard limit
+        if file_size > 2_000_000
+          log_debug(
+            "Font file #{font_path} is #{file_size} bytes (#{file_size / 1024 / 1024}MB), exceeds 2MB data URL limit",
+            :error
+          )
+          return nil
+          # 500KB warning threshold
+        elsif file_size > 500_000
+          log_debug(
+            "Font file #{font_path} is #{file_size} bytes (#{file_size / 1024}KB), consider optimizing for better performance",
+            :warn
+          )
+        end
+        content_type = font_content_type(full_path)
+        encoded_data = Base64.strict_encode64(font_data)
+        # Base64 encoding increases size by ~33%
+        encoded_size = encoded_data.bytesize
+        log_debug("Font #{font_path} loaded: #{file_size} bytes (#{encoded_size} bytes encoded)")
+        "data:#{content_type};base64,#{encoded_data}"
+      rescue => e
+        log_debug("Failed to convert font to data URL: #{e.message}", :error)
+        nil
+      end
+    end
+    # Generate @font-face declaration for local fonts
+    def generate_font_face(family_name, font_path, weight: "normal", style: "normal", display: "swap")
+      data_url = font_to_data_url(font_path)
+      return "" unless data_url
+      <<~CSS
+        @font-face {
+          font-family: '#{family_name}';
+          src: url('#{data_url}');
+          font-weight: #{weight};
+          font-style: #{style};
+          font-display: #{display};
+        }
+      CSS
+        .html_safe
+    end
     def template_path
       Rails.application.config.social_construct.template_path
     end
@@ -207,5 +305,84 @@ module SocialConstruct
       return unless debug
       Rails.logger.send(level, "[SocialCard] #{message}")
     end
+    # Local image helper - converts image file to data URL
+    def image_data_url(image_path)
+      full_path = if image_path.start_with?("/")
+        image_path
+      else
+        Rails.root.join("app", "assets", "images", image_path)
+      end
+      return nil unless File.exist?(full_path)
+      begin
+        image_data = File.read(full_path)
+        file_size = image_data.bytesize
+        # Check file size limitations
+        if file_size > 2_000_000
+          log_debug(
+            "Image file #{image_path} is #{file_size} bytes (#{file_size / 1024 / 1024}MB), exceeds 2MB data URL limit",
+            :error
+          )
+          return nil
+        elsif file_size > 500_000
+          log_debug(
+            "Image file #{image_path} is #{file_size} bytes (#{file_size / 1024}KB), consider optimizing for better performance",
+            :warn
+          )
+        end
+        content_type = image_content_type(full_path)
+        encoded_data = Base64.strict_encode64(image_data)
+        log_debug("Image #{image_path} loaded: #{file_size} bytes (#{encoded_data.bytesize} bytes encoded)")
+        "data:#{content_type};base64,#{encoded_data}"
+      rescue => e
+        log_debug("Failed to convert image to data URL: #{e.message}", :error)
+        nil
+      end
+    end
+    # Determine MIME type for image files
+    def image_content_type(image_path)
+      extension = File.extname(image_path).downcase
+      case extension
+      when ".png"
+        "image/png"
+      when ".jpg", ".jpeg"
+        "image/jpeg"
+      when ".gif"
+        "image/gif"
+      when ".svg"
+        "image/svg+xml"
+      when ".webp"
+        "image/webp"
+      else
+        # fallback
+        "image/png"
+      end
+    end
+    # Determine MIME type for font files
+    def font_content_type(font_path)
+      extension = File.extname(font_path).downcase
+      case extension
+      when ".woff2"
+        "font/woff2"
+      when ".woff"
+        "font/woff"
+      when ".ttf"
+        "font/truetype"
+      when ".otf"
+        "font/opentype"
+      when ".eot"
+        "application/vnd.ms-fontobject"
+      else
+        # fallback
+        "font/truetype"
+      end
+    end
   end
 end

data/lib/generators/social_construct/install/templates/social_cards_layout.html.erb CHANGED Viewed

@@ -46,4 +46,5 @@
   <body>
     <%= yield %>
   </body>
-</html>
+</html>

data/lib/social_construct/engine.rb CHANGED Viewed

@@ -9,6 +9,7 @@ module SocialConstruct
     config.before_initialize do
       require "ferrum"
       require "marcel"
     end
   end
 end

data/lib/social_construct/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module SocialConstruct
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: social_construct
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mikkel Malmberg
@@ -78,12 +78,12 @@ files:
 - lib/social_construct.rb
 - lib/social_construct/engine.rb
 - lib/social_construct/version.rb
-homepage: https://github.com/brnbw/social_construct
+homepage: https://github.com/mikker/social_construct
 licenses: []
 metadata:
-  homepage_uri: https://github.com/brnbw/social_construct
-  source_code_uri: https://github.com/brnbw/social_construct
-  changelog_uri: https://github.com/brnbw/social_construct/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/mikker/social_construct
+  source_code_uri: https://github.com/mikker/social_construct
+  changelog_uri: https://github.com/mikker/social_construct/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib