glyphs 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e0ed91cb2af5c3414aa3db654c772ec9c3ad506f4f7d9998223b76144897d33
-  data.tar.gz: 37a81b162e603e83060c7adfd395cef55f1d20c4896d9bb4d4b0ec96e3e83908
+  metadata.gz: 798fe439ca9ea93ff3bfb84f23de90f87abd6ffee953cd85de5543066b52a4f0
+  data.tar.gz: 58829c2ec4bf5ed6aaa24da8b40a376b7aae48525277be499eae957754a99c11
 SHA512:
-  metadata.gz: 82eb60a70f7fd553e38130cf57025834ca8daf9c02c54c315df9900c07346138eb1230d48783204509ab897791203434db38cf62ed1035337bf3ded8aee7b2ed
-  data.tar.gz: 188c29bbe5a8a8f6dbae785e39af4a6b49ee4c660a302bf8fd032525012c47ce7b6559e45c342f5b6544f06994162ab443b4e4fc8e51eb81b2c0bbc6ceb38152
+  metadata.gz: 49acc1efae75b8d2eb0fac2079ef20c2d5fb211a519c598d61f306453c3dbc000f4ee2fd4bb75090b10a63f009e8bbbddde0e4a3277bc340b58e5eead644eec2
+  data.tar.gz: 7b3adbeb6816fbeb13eea1584a33ef1cbcb241339c7caedab14b92b44a185050ebd8240ae0ed99ab5715cc8ccaeb471968f491354e009112eee76ccbd23831a3

data/CHANGELOG.md

@@ -4,6 +4,15 @@
 
 ### Added
 
+- **`config.merge_default_data` keeps a library's default data next to a
+  call's own.** Off by default. The icons gem replaces a library's configured
+  `default.data` with a call's `data:` hash, so a default marker such as
+  `data-icon` disappears from exactly the icons that carry data of their own.
+  With the setting on, the call's `data:` hash is merged over the defaults (the
+  call's keys win, its hash is not mutated; `data: nil` keeps the defaults, uncached).
+  Cached and uncached renders are byte-identical, the cache key is unchanged,
+  and a library with no default data renders as before. With it off, output is
+  unchanged. Refs #40
 - **A non-main Ractor renders icons it has not cached.** A miss there used to
   raise `Ractor::IsolationError` (`@configuration from Icons`), because the
   icons gem reads an unshareable module ivar and parses with Nokogiri, which

data/README.md

@@ -105,6 +105,16 @@ Glyphs.configure do |config|
   # on every render that goes uncached.
   config.cache_svgs = true
 
+  # Merge a call's data: hash over the library's configured default data
+  # (`default.data` in the icons configuration) instead of replacing it, as the
+  # icons gem does. The call's keys win on a conflict; its hash is not mutated.
+  # data: nil keeps the defaults, as no data: does; any other non-hash data:
+  # renders as the icons gem renders it. Both render uncached. Cached and
+  # uncached renders are identical either way. Default: false (the icons gem's behavior).
+  # The cache holds the merged markup: call Glyphs.reset_cache! after changing
+  # this or the icons gem's default data at runtime (tests).
+  config.merge_default_data = false
+
   # How many icons the cache holds (least recently used evicted first). One
   # cache per Ractor, so a plain threaded server has one. Default: 1024.
   config.svg_cache_size = 1024
@@ -137,6 +147,8 @@ Active Support; elsewhere, add `gem "ractor-dispatch"`. The markup is the main R
 the calling Ractor's cache keeps it, so each icon crosses once per cache entry; cache hits never leave the
 Ractor. The missing-icon policy runs on the main Ractor too, `on_missing_icon` included. A call with an
 attribute that renders uncached, or any call with `cache_svgs = false`, goes to the main Ractor every time.
+`merge_default_data` reads the default data where the icons gem renders, on the main Ractor, so it adds no
+crossing: a hit merges the call's `data:` in the calling Ractor. With it on, a non-hash `data:` (`nil` included) renders uncached.
 
 Without ractor-dispatch, a miss in a non-main Ractor raises `Glyphs::MainRactor::Unavailable`, naming the
 icon. You can still render on the main Ractor and hand the markup over with `Glyphs.preload_svg`; cache hits

data/lib/glyphs/configuration.rb

@@ -18,6 +18,9 @@ module Glyphs
     # cache_svgs: memoize rendered SVGs per [library, variant, name]; the
     #   caller's attributes are applied to the cached markup on every call.
     # svg_cache_size: how many icons each Ractor's LRU cache holds (1024).
+    # merge_default_data: boolean; when true, a caller's data: hash is merged
+    #   over the library/variant's configured default data (the caller's keys
+    #   win) instead of replacing it, as the icons gem does. Default: false.
     # keep_icons: icons the pruner must keep despite no static reference
     #   (dynamic / data-driven names). A flat list of names/globs, or a
     #   { library => [names/globs] } hash. fallback_icons are always kept.
@@ -28,7 +31,7 @@ module Glyphs
     #   would delete raises Glyphs::PrunableIconError. For the test environment:
     #   the first uncached render scans the source, once per process.
     attr_accessor :raise_on_missing, :on_missing_icon, :fallback_icons, :cache_svgs,
-      :keep_icons, :prune_source_globs, :raise_on_prunable
+      :keep_icons, :prune_source_globs, :raise_on_prunable, :merge_default_data
     attr_reader :svg_cache_size
 
     def initialize
@@ -40,6 +43,7 @@ module Glyphs
       @keep_icons = []
       @prune_source_globs = nil
       @raise_on_prunable = false
+      @merge_default_data = false
     end
 
     def svg_cache_size=(size)

data/lib/glyphs/default_data.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Glyphs
+  # config.merge_default_data: merges a library's configured default data under
+  # a caller's data: hash, which the icons gem would otherwise replace it with.
+  # Reads the icons gem's configuration, so it runs on the main Ractor only
+  # (Glyphs.build_svg, which a non-main Ractor reaches through MainRactor).
+  # A default data key named like SvgTemplate's slot marker (glyphs-data-slot)
+  # would be dropped by the cached data: template, so such defaults are not
+  # merged: both paths render as the icons gem does.
+  module DefaultData
+    SLOT_NAME = SvgTemplate::SLOT_ATTRIBUTE.delete_prefix("data-").freeze
+
+    class << self
+      # The attributes with the default data merged under a data: hash, or
+      # without a data: nil (the defaults alone, as with no data:), when the
+      # library has default data; else the attributes as given. A new Hash: the
+      # caller's is never mutated.
+      def merge(attributes, library:, variant:)
+        return attributes unless attributes.key?(:data)
+
+        data = attributes[:data]
+        return attributes unless data.nil? || data.is_a?(Hash)
+
+        defaults = lookup(library:, variant:)
+        return attributes unless mergeable?(defaults)
+
+        data.nil? ? attributes.except(:data) : attributes.merge(data: by_name(defaults, data))
+      end
+
+      private
+
+      def mergeable?(defaults)
+        defaults.is_a?(Hash) && !defaults.empty? && defaults.each_key.none? { |key| key.to_s.tr("_", "-") == SLOT_NAME }
+      end
+
+      # One entry per attribute name, however its key is spelled (:toggle_target,
+      # "toggle-target"): at the position its name first appears, with the value
+      # it was given last, the caller's after the defaults. That is how a cache
+      # hit splices the caller's data over the template's defaults.
+      def by_name(defaults, data)
+        merged = {}
+        defaults.each { |key, value| merged[key.to_s.tr("_", "-")] = value }
+        data.each { |key, value| merged[key.to_s.tr("_", "-")] = value }
+        merged
+      end
+
+      # The icons gem's own lookup (Icons::Icon::Configurable): the variant, else
+      # the library's default_variant, else the global default_variant.
+      def lookup(library:, variant:)
+        icons = Icons.configuration
+        library = library.to_sym
+        variant ||= icons.libraries.dig(library, :default_variant) || icons.default_variant
+        variant = variant.to_s.empty? ? nil : variant.to_sym
+        (icons.libraries.dig(*[library, variant].compact) || {}).dig(:default, :data)
+      end
+    end
+  end
+end

data/lib/glyphs/svg_template.rb

@@ -18,6 +18,9 @@ module Glyphs
   # A caller's data: replaces the library's default data (the icons gem merges
   # them that way) and lands where the defaults would have, so data: calls use
   # a template rendered with DATA_SLOT, whose marker attribute holds that place.
+  # With merge_default_data on, that template is rendered with the default data
+  # before the marker (Glyphs::DefaultData), and a caller's key that names a
+  # default replaces it in place, as rendering the merged hash would.
   class SvgTemplate
     DATA_SLOT = { data: { "glyphs-data-slot" => "" }.freeze }.freeze
     SLOT_ATTRIBUTE = "data-glyphs-data-slot"

data/lib/glyphs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Glyphs
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/lib/glyphs.rb

@@ -92,8 +92,15 @@ module Glyphs
     # policy (raise / instrument / fallback) and the per-Ractor cache: one
     # entry per [library, variant, name], the caller's attributes applied to
     # the cached markup on every call.
+    #
+    # With merge_default_data on, the library's default data is merged under a
+    # caller's data: hash when the icons gem renders (build_svg, main Ractor
+    # only, where its configuration is readable). The data: template is then
+    # rendered with the defaults beside the slot marker, so a cache hit splices
+    # the caller's keys over them exactly as the merged hash would render. A
+    # non-hash data: renders uncached (data: nil keeps the defaults, if any).
     def svg_for(name:, library:, variant:, attributes:)
-      return render_svg(name:, library:, variant:, attributes:) unless configuration.cache_svgs
+      return render_svg(name:, library:, variant:, attributes:) if uncached?(attributes)
 
       data = attributes.key?(:data)
       template = svg_cache.compute_if_absent([library, variant, name, data], configuration.svg_cache_size) do
@@ -123,6 +130,13 @@ module Glyphs
 
     private
 
+    def uncached?(attributes)
+      config = configuration
+      return true unless config.cache_svgs
+
+      config.merge_default_data && attributes.key?(:data) && !attributes[:data].is_a?(Hash)
+    end
+
     # A non-main Ractor cannot run the icons gem, so it renders on the main
     # Ractor (see MainRactor); the missing-icon policy runs there too.
     def render_svg(name:, library:, variant:, attributes:)
@@ -154,6 +168,7 @@ module Glyphs
     end
 
     def build_svg(name:, library:, variant:, attributes:)
+      attributes = DefaultData.merge(attributes, library:, variant:) if configuration.merge_default_data
       Icons::Icon.new(name:, library:, variant:, arguments: attributes).svg
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: glyphs
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -68,6 +68,7 @@ files:
 - lib/glyphs/animated_icon.rb
 - lib/glyphs/box_icon.rb
 - lib/glyphs/configuration.rb
+- lib/glyphs/default_data.rb
 - lib/glyphs/feather_icon.rb
 - lib/glyphs/flag_icon.rb
 - lib/glyphs/hero_icon.rb