nameplate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71033d48e71e5ea461b075ae0d1d6b5f359eb9dfcd39885ec2994ec4c1475641
+  data.tar.gz: bc180c2c1ebee448c4c19ee3ed16e20cf4f20cde96f131963f12451e0b9e0bde
+SHA512:
+  metadata.gz: 4647667e97c3ab81e10b2730048c8dd3098524eb2d67e635c3ee60652145b8c5d52ab10cb3b5a3cefa7d2ea3f0266eada2596dd459832d978972f15b76a7125b
+  data.tar.gz: 2b88c146ad0373b3069723d962b964e432ccd2f84d46abc49d9fb4034c477fe99be90c5c2dc58d00fec8508d2c46b9fff37f83b0a5e62e0f7f7df77f8369aa9b

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 t0nylombardi
+
+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,122 @@
+# NamePlate
+
+**NamePlate** is a Ruby gem for generating simple, Google-style avatar images from names or usernames. It’s a modernized successor to [letter_avatar](https://github.com/ksz2k/letter_avatar), built with maintainability, SOLID design, and Rails-friendly integration in mind.
+
+Think of it as a quick way to give everyone in your app a unique, consistent avatar — without storing profile photos.
+
+---
+
+## Features
+
+- 🔠 Generates avatars with initials (e.g., **Tony Lombardi → TL**)  
+- 🎨 Deterministic background colors from input strings  
+- 📐 Flexible sizing (from tiny icons to large images)  
+- 🖼 Transparent padding and proper centering with MiniMagick  
+- ⚡ Caching support for faster repeated lookups  
+- ✅ Rails helpers for easy view integration  
+- 🧪 Fully tested and type-annotated with RBS  
+
+---
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem "nameplate"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself with:
+
+```bash
+gem install nameplate
+```
+
+---
+
+## Usage
+
+### Quick Start
+
+```ruby
+require "nameplate"
+
+# Generate a 128x128 avatar for "Tony"
+path = NamePlate::Avatar::Generator.call("Tony", 128)
+
+# => "tmp/generated/128.png"
+```
+
+### With Rails View Helper
+
+```erb
+<%= nameplate_avatar("Tony", size: 64, class: "avatar") %>
+```
+
+Outputs an `<img>` tag pointing to the cached avatar file.
+
+---
+
+## Configuration
+
+You can configure fonts, colors, and weights globally:
+
+```ruby
+NamePlate.configure do |config|
+  config.font      = Rails.root.join("app/assets/fonts/YourFont.ttf")
+  config.weight    = 400
+  config.pointsize = 64
+end
+```
+
+---
+
+## Async Generation
+
+For heavy workloads (e.g., pre-warming caches):
+
+```ruby
+future = NamePlate::Avatar::Generator.async_call("Tony", 128)
+future.value! # blocks until done
+```
+
+---
+
+## Development
+
+Clone the repo and run:
+
+```bash
+bin/setup
+bundle exec rake spec
+```
+
+---
+
+## Roadmap
+
+- SVG support  
+- Rails engine integration (asset pipeline)  
+- Configurable color palettes  
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/t0nylombardi/nameplate](https://github.com/t0nylombardi/nameplate).  
+
+---
+
+## License
+
+MIT License. See `LICENSE.txt` for details.
+
+---
+
+⚡ **NamePlate** — because every name deserves a face.

data/Rakefile

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "standard/rake"
+require "pry"
+require "pry-byebug"
+require_relative "lib/nameplate"
+
+SIG_DIR = "sig"
+
+task default: %i[specstandard]
+task :standard do
+  Standard::RakeTask.new.execute
+end
+
+desc "Iterate over [A..Z] letters in every theme"
+task :iterate_letters do
+  output_dir = File.expand_path("demo_images", __dir__)
+  FileUtils.mkdir_p(output_dir)
+
+  size = 128
+
+  NamePlate::Colors.registry.each do |key, palette|
+    puts "== Theme: #{key} =="
+
+    NamePlate.colors_palette = key
+    theme_dir = File.join(output_dir, key.to_s)
+    FileUtils.mkdir_p(theme_dir)
+
+    ("A".."Z").each do |letter|
+      path = NamePlate::Avatar.generate(letter, size)
+      dest = File.join(theme_dir, "#{letter}.png")
+      FileUtils.cp(path, dest)
+      puts "  #{letter} → #{dest}"
+    end
+  end
+
+  puts "All images generated under #{output_dir}/"
+end

data/lib/nameplate/avatar/cache.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+require "fileutils"
+
+module NamePlate
+  class Avatar
+    # Thread-safe cache manager for avatar file paths.
+    class Cache
+      @cache = Concurrent::Map.new
+
+      class << self
+        # Returns the base path for cached avatars.
+        #
+        # @return [String] Base cache path.
+        def base_path
+          "#{NamePlate.cache_base_path || "public/system"}/nameplate/#{Avatar::VERSION}"
+        end
+
+        # Builds or fetches the file path for a cached avatar.
+        #
+        # Uses a Concurrent::Map to ensure thread-safe memoization.
+        #
+        # @param [Identity] identity The identity object representing the user.
+        # @param [Integer] size The size of the avatar.
+        # @return [String] The file path for the cached avatar.
+        def path(identity, size)
+          key = cache_key(identity, size)
+
+          @cache.compute_if_absent(key) do
+            dir = File.join(base_path, identity.letters, identity.color.join("_"))
+            FileUtils.mkdir_p(dir)
+            File.join(dir, "#{size}.png")
+          end
+        end
+
+        # Check if a cached avatar exists for the given identity and size.
+        #
+        # @param [Identity] identity The identity object representing the user.
+        # @param [Integer] size The size of the avatar.
+        # @return [Boolean] True if a cached avatar exists, false otherwise.
+        def cached?(identity, size)
+          File.exist?(path(identity, size))
+        end
+
+        private
+
+        # Builds a unique cache key from identity + size.
+        #
+        # @param [Identity] identity
+        # @param [Integer] size
+        # @return [String]
+        def cache_key(identity, size)
+          "#{identity.letters}-#{identity.color.join("_")}-#{size}"
+        end
+      end
+    end
+  end
+end

data/lib/nameplate/avatar/generator.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "mini_magick"
+require "concurrent-ruby"
+
+module NamePlate
+  class Avatar
+    # Generates PNG avatars from usernames using MiniMagick/ImageMagick.
+    #
+    # - Derives an {Identity} (initial letters + background color) from a username.
+    # - Produces a square PNG at the requested size (capped at {Avatar::FULLSIZE}).
+    # - Uses {Avatar::Cache} to reuse existing files and to build deterministic paths.
+    #
+    # The high-level API for consumers is {NamePlate::Avatar.generate}. This class
+    # exists as the lower-level, orchestration entry point that handles logging,
+    # validation, caching, and MiniMagick invocation.
+    #
+    # Requirements:
+    # - ImageMagick must be installed and accessible on the PATH (MiniMagick uses `convert`).
+    # - A valid font file must be configured at {Avatar::FONT_FILE}.
+    #
+    # Configuration sources used during generation:
+    # - `NamePlate.pointsize`, `NamePlate.weight`, `NamePlate.annotate_position`
+    # - {Avatar::FILL_COLOR} (foreground text/letters color)
+    # - {Avatar::FONT_FILE} (font used by ImageMagick)
+    # - `NamePlate.cache_base_path` (root for cached files; see {Avatar::Cache})
+    # - `ENV["NAMEPLATE_LOG_LEVEL"]` (set to `DEBUG` for verbose logging)
+    #
+    # @example Generate and return a cached 128px avatar path
+    #   path = NamePlate::Avatar::Generator.call("Tony Baloney", 128)
+    #   # => "public/system/nameplate/1/TB/163_163_163/128.png"
+    #
+    # @example Disable cache and provide a custom logger
+    #   logger = Logger.new($stderr)
+    #   path = NamePlate::Avatar::Generator.call("Ada Lovelace", 256, cache: false, logger: logger)
+    #   # Generates a fresh 256px PNG even if a cached one exists
+    #
+    # @see NamePlate::Avatar.generate User-facing convenience API
+    # @see NamePlate::Avatar::Cache Path building and cache helpers
+    class Generator
+      # Base class for avatar generation errors
+      class GenerationError < StandardError; end
+
+      # Raised when MiniMagick/ImageMagick fails to render an avatar.
+      class ImageMagickError < GenerationError; end
+
+      # Raised when filesystem operations (write/verify) fail.
+      class FileSystemError < GenerationError; end
+
+      # Raised when inputs or configuration are invalid.
+      class ConfigurationError < GenerationError; end
+
+      # Instantiate a new generator.
+      #
+      # Prefer {::call} unless you need a long-lived instance.
+      #
+      # @param username [String] The source name used to derive initials and color.
+      # @param size [Integer] Target size in pixels (> 0). Capped at {Avatar::FULLSIZE}.
+      # @param cache [Boolean] Reuse existing cached PNG when present. Defaults to `true`.
+      # @param logger [Logger, nil] Optional logger; defaults to a simple STDOUT logger.
+      # @raise [ConfigurationError] If parameters are invalid or required assets are missing.
+      def initialize(username, size, cache: true, logger: nil)
+        @username = username
+        @size = size
+        @cache = cache
+        @font = Avatar::FONT_FILE
+        @fill = Avatar::FILL_COLOR
+        @logger = logger || default_logger
+
+        validate_inputs!
+      end
+
+      def self.call(username, size, cache: true, logger: nil)
+        new(username, size, cache: cache, logger: logger).execute!
+      end
+
+      # Same API as {.call}, but returns a Future so callers can decide
+      # when to block.
+      #
+      # @return [Concurrent::Future<String>] Future that resolves to the avatar path.
+      # @see .call
+      def self.async_call(username, size, cache: true, logger: nil)
+        Concurrent::Future.execute do
+          new(username, size, cache: cache, logger: logger).execute!
+        end
+      end
+
+      # Run the avatar generation pipeline: build identity, resolve cache path,
+      # and generate if needed.
+      #
+      # @return [String] Filesystem path to the generated or cached avatar PNG.
+      # @raise [GenerationError] If anything goes wrong during generation.
+      def execute!
+        with_error_handling do
+          logger.info "Starting avatar generation for '#{username}' at size #{size}px"
+          path = generate
+          logger.info "Avatar generation completed successfully: #{path}"
+          path
+        end
+      end
+
+      private
+
+      attr_reader :username, :size, :cache, :font, :fill, :logger
+
+      # Generate or reuse an avatar at the requested size.
+      #
+      # Builds an identity from `username`, computes the cache path,
+      # renders the PNG if not already cached, and returns the file path.
+      #
+      # @return [String] Filesystem path to the generated or cached avatar PNG.
+      def generate
+        identity = build_identity
+        target_size = normalize_size
+        target_path = Avatar::Cache.path(identity, target_size)
+        return use_cached(target_path) if cached?(target_path)
+
+        Concurrent::Future.execute { generate_avatar(identity, target_size, target_path) }.value!
+
+        target_path
+      end
+
+      # Build an avatar identity from the configured username.
+      #
+      # @return [NamePlate::Avatar::Identity] Derived initials and background color.
+      def build_identity
+        Avatar::Identity.from_username(username).tap do |identity|
+          logger.debug "Generated identity: #{identity.inspect}"
+        end
+      end
+
+      # Clamp the requested size to the maximum full size.
+      #
+      # @return [Integer] Target size in pixels (<= {Avatar::FULLSIZE}).
+      def normalize_size
+        [size, Avatar::FULLSIZE].min.tap do |s|
+          logger.debug "Target size: #{s}"
+        end
+      end
+
+      # Check if a cached avatar exists at the given path.
+      #
+      # @param [String] path The expected avatar file path.
+      # @return [Boolean] True if a cached file exists, false otherwise.
+      def cached?(path)
+        cache && File.exist?(path)
+      end
+
+      # Use an existing cached avatar path.
+      #
+      # @param [String] path The cached avatar file path.
+      # @return [String] The same cached path that was provided.
+      def use_cached(path)
+        path
+      end
+
+      # Render the avatar image using MiniMagick/ImageMagick.
+      #
+      # @param identity [Identity] Letters and background color.
+      # @param size [Integer] Target size in pixels.
+      # @param filename [String, Pathname] Output file path.
+      # @raise [ImageMagickError] If MiniMagick raises during conversion.
+      def generate_avatar(identity, size, filename)
+        MiniMagick.convert do |c|
+          c.size "#{size}x#{size}"
+          c << "xc:#{to_rgb(identity.color)}"
+          c.pointsize NamePlate.pointsize.to_s
+          c.font font.to_s
+          c.weight NamePlate.weight.to_s
+          c.fill fill.to_s.gsub(/\s+/, "")
+          c.gravity "Center"
+          c.annotate NamePlate.annotate_position.to_s, identity.letters.to_s
+          c << filename.to_s
+        end
+      rescue => e
+        raise ImageMagickError, "MiniMagick failed to generate avatar: #{e.message}"
+      end
+
+      # Convert `[r, g, b]` array to `rgb(r,g,b)` string accepted by ImageMagick.
+      #
+      # @param color [Array<Integer>] RGB values in the 0..255 range.
+      # @return [String] `rgb(r,g,b)` formatted string.
+      # @raise [ConfigurationError] If the color is not a valid triplet.
+      def to_rgb(color)
+        "rgb(#{color.join(",")})"
+      rescue => e
+        raise ConfigurationError, "Invalid color format: #{color.inspect} - #{e.message}"
+      end
+
+      # Validate constructor inputs and required configuration.
+      #
+      # @return [void]
+      # @raise [ConfigurationError] When any validation fails.
+      def validate_inputs!
+        raise ConfigurationError, "Username cannot be empty" if username.to_s.strip.empty?
+        raise ConfigurationError, "Size must be positive integer" unless size.is_a?(Integer) && size.positive?
+        raise ConfigurationError, "Font file not found: #{font}" unless File.exist?(font.to_s)
+        raise ConfigurationError, "Fill color not configured" if fill.to_s.empty?
+      end
+
+      # Runs a block, wrapping/logging any errors in GenerationError subclasses.
+      #
+      # @yield The block to execute safely.
+      # @return [Object] The block's return value if successful.
+      # @raise [GenerationError] A normalized error if anything fails.
+      def with_error_handling
+        yield
+      rescue GenerationError => e
+        logger.error "#{e.class}: #{e.message}"
+        raise
+      rescue Errno::ENOENT, Errno::EACCES, Errno::EIO => e
+        logger.error "File system error: #{e.class} - #{e.message}"
+        raise FileSystemError, e.message
+      rescue => e
+        logger.error "Unexpected error: #{e.class} - #{e.message}"
+        logger.debug e.backtrace.join("\n")
+        raise GenerationError, "Unexpected error: #{e.message}"
+      end
+
+      # Build a default logger that writes to STDOUT.
+      #
+      # Log level defaults to `INFO`; set `ENV["NAMEPLATE_LOG_LEVEL"] = "DEBUG"`
+      # to enable verbose output during generation.
+      #
+      # @return [Logger]
+      def default_logger
+        require "logger"
+        Logger.new($stdout).tap do |log|
+          log.level = (ENV["NAMEPLATE_LOG_LEVEL"]&.upcase == "DEBUG") ? Logger::DEBUG : Logger::INFO
+          log.formatter = proc do |severity, datetime, _progname, msg|
+            "[#{datetime.strftime("%H:%M:%S")}] #{severity}: #{msg}\n"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/nameplate/avatar/identity.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module NamePlate
+  class Avatar
+    # Represents a derived avatar identity: letters and color.
+    class Identity
+      attr_reader :color, :letters
+
+      def initialize(color, letters)
+        @color = color
+        @letters = letters
+      end
+
+      # Build an identity from a username.
+      #
+      # @param [String] username The input name.
+      # @return [Identity] The derived avatar identity.
+      def self.from_username(username)
+        color = NamePlate::Colors.for(username)
+        letters = initials(username, count(username))
+        new(color, letters)
+      end
+
+      class << self
+        private
+
+        def initials(username, count)
+          username
+            .split(/\s+/)
+            .map { |word| word[0] }
+            .join
+            .upcase[0..count - 1]
+        end
+
+        def count(username)
+          (username.strip.split(/\s+/).size >= 2) ? 2 : 1
+        end
+      end
+    end
+  end
+end

data/lib/nameplate/avatar.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "avatar/generator"
+require_relative "avatar/cache"
+require_relative "avatar/identity"
+
+module NamePlate
+  # Avatar generation from usernames.
+  #
+  # Responsibilities are split into:
+  # - {Identity}: maps username → initials + color
+  # - {Cache}: builds consistent cache paths
+  # - {Generator}: orchestrates avatar creation and resizing
+  #
+  # Public API:
+  #   NamePlate::Avatar.generate("John Doe", 128)
+  #
+  class Avatar
+    VERSION = 1 # bump on any change to avatar generation
+    FULLSIZE = 600
+    FILL_COLOR = "rgba(0, 0, 0, 0.65)" # black at 65% opacity
+    # Use __dir__ and fall back to the current working directory for Steep
+    # which can type __dir__ as String | nil.
+    FONT_FILE = File.expand_path("fonts/Roboto-Medium", __dir__ || Dir.pwd)
+
+    # Public API entry point
+    #
+    # @param username [String]
+    # @param size [Integer]
+    # @param opts [Hash] options, e.g. { cache: true }
+    # @return [String] path to avatar file
+    def self.generate(username, size, opts = {})
+      Generator.call(username, size, **opts)
+    end
+  end
+end

data/lib/nameplate/colors/palette.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module NamePlate
+  module Colors
+    class Palette
+      attr_reader :colors
+
+      # Initialize a new color palette.
+      #
+      # @param [Array<Array<Integer>>] colors The array of RGB triplets.
+      # If nil, uses the default {COLORS} constant defined in subclasses.
+      # @raise [NotImplementedError] If the subclass does not define COLORS constant.
+      # @raise [ArgumentError] If COLORS is not a valid array of RGB triplets
+      def initialize(colors = nil)
+        colors ||= self.class.const_get(:COLORS)
+        @colors = colors.freeze
+      end
+
+      def self.key
+        raise NotImplementedError, "#{self}.key must return a Symbol"
+      end
+
+      # Select a color based on a username string.
+      #
+      # @param [String] username The username to base the color selection on.
+      # @return [Array<Integer>] RGB triplet
+      def pick(username)
+        index = hash_index(username)
+        colors[index % colors.length]
+      end
+
+      private
+
+      # Generate a hash index from a username.
+      #
+      # @param [String] username The username to hash.
+      # @return [Integer] The hash index.
+      def hash_index(username)
+        Digest::MD5.hexdigest(username)[0...15].to_i(16)
+      end
+    end
+  end
+end

data/lib/nameplate/colors/palettes/custom.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module NamePlate
+  module Colors
+    module Palettes
+      class Custom < Palette
+        def self.key = :custom
+
+        def initialize
+          super(NamePlate.custom_palette || [])
+        end
+
+        def pick(username)
+          raise "Custom palette not set" if colors.empty?
+          super
+        end
+      end
+    end
+  end
+end

data/lib/nameplate/colors/palettes/dracula.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module NamePlate
+  module Colors
+    module Palettes
+      # Inspired by Dracula theme
+      class Dracula < Palette
+        COLORS = [
+          [40, 42, 54],    # background
+          [68, 71, 90],    # current line
+          [98, 114, 164],  # comment
+          [139, 233, 253], # cyan
+          [80, 250, 123],  # green
+          [255, 184, 108], # orange
+          [255, 121, 198], # pink
+          [189, 147, 249], # purple
+          [241, 250, 140], # yellow
+          [255, 85, 85]    # red
+        ].freeze
+
+        def self.key = :dracula
+
+        def initialize
+          super(COLORS)
+        end
+      end
+    end
+  end
+end