html-attributes-utils 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a383443446570cb37c2c67e608c4bcde35ecf1b255eca392cbcc263d5a36ae76
+  data.tar.gz: 2b81b3e7929301ee349b330dae54131b79f93afe417db7e57b934cc4c8a96615
+SHA512:
+  metadata.gz: 9c2568b9c1a67be8cad3df9ccd4eb5f11a9e612c27da3438acddc2587eaaee2d12138adf9397aeb43bb0d05e57b3fa3735df9caf0437a8cb6d53b8eddc937e59
+  data.tar.gz: ce81b1c86dcbf9e464a9268d02e595a60ee6eb30ba5fd0e5fa829a5f8ed233bee252da1a06716ba9ff0a06a565a70010d71d372acc42796e7c104c6ab222d98f

data/README.md

@@ -0,0 +1,3 @@
+# HTML Attributes Utilities
+
+This is a small library intended to make it easier to deal with hashes of attributes.

data/lib/html_attributes_utils.rb

@@ -0,0 +1,132 @@
+require "active_support/core_ext/hash/keys"
+
+module HTMLAttributesUtils
+  refine Hash do
+    # Merge the incoming hash into the current one in a way that suits
+    # HTML attributes.
+    #
+    # @param custom [Hash] the incoming hash
+    # @param parents [Array] used to keep track of the keys that have already been
+    #   merged, *don't supply this unless the method is called during recursion*
+    # @mergeable_attributes [Array<Array<Symbol>>] Mergeable attributes are
+    #   HTML attributes can contain lists made from space-separated strings. We
+    #   convert them to arrays so they can be cleanly merged. Rails accepts them
+    #   as arrays so there's no need to convert back to strings.
+    #
+    # @example
+    #   original = { class: "red", data: { size: "medium", controller: "comment" } }
+    #   incoming = { class: "blue", data: { controller: "reply" } }
+    #
+    #   original.deep_merge_html_attributes(incoming)
+    #
+    #   => { class: "blue", data: { size: "medium", controller: "reply" } }
+    #
+    def deep_merge_html_attributes(custom, parents = [], mergeable_attributes: default_mergeable_attributes)
+      return custom unless custom.is_a?(Hash)
+
+      overrides = custom.deep_symbolize_keys
+
+      deep_symbolize_keys.each_with_object(deep_symbolize_keys) { |(key, value), merged|
+        next unless overrides.key?(key)
+
+        merged[key] = combine_values(
+          value,
+          overrides[key],
+          parents: parents << key,
+          mergeable_attributes: mergeable_attributes
+        )
+
+        overrides.delete(key)
+      }.merge(overrides)
+    end
+
+    # Remove unwanted attributes from a the hash and any values that are hashes
+    # recursively. In particular we don't care for empty hashes, arrays,
+    # strings that are empty or just contain spaces and nils.
+    #
+    # It preserves +true+ and +false+.
+    #
+    # @return [Hash] the tidied hash
+    # @example
+    #   { class: "blue", title: nil, lang: "", aria: { describedby: [] } }.deep_tidy_html_attributes
+    #
+    #   => { class: "blue" }
+    #
+    def deep_tidy_html_attributes
+      each_with_object({}) do |(key, value), tidy|
+        (tidy[key] = tidy_value(value)) unless skippable_value?(value)
+      end
+    end
+
+  private
+
+    def tidy_value(value)
+      case value
+      when Hash
+        value.deep_tidy_html_attributes.presence
+      when Array
+        value.reject(&:blank?).presence
+      when String
+        value.strip.presence
+      else
+        value
+      end
+    end
+
+    # Identiy attribute values we don't care about.
+    #
+    # We can't check for this using Rails' `#presence` because we want `false` to be
+    # included so some HTML attributes that default to on can be disabled, like
+    # `autocomplete: false`
+    #
+    # FIXME: there is probably a nicer way of doing this...
+    def skippable_value?(value)
+      return false if [true, false].include?(value)
+
+      value.blank?
+    end
+
+    def combine_values(value, override, **kwargs)
+      case split_attribute_list(value, **kwargs)
+      when Array
+        combine_array(value, override, **kwargs)
+      when Hash
+        combine_hash(value, override, **kwargs)
+      else
+        split_attribute_list(override, **kwargs)
+      end
+    end
+
+    def combine_array(originals, overrides, parents:, mergeable_attributes:)
+      return overrides if overrides.nil?
+      return overrides unless mergeable_attributes.include?(parents)
+
+      (try_split(originals) + try_split(overrides)).uniq
+    end
+
+    def try_split(value)
+      value.is_a?(String) ? value.split : value
+    end
+
+    def combine_hash(originals, overrides, parents:, mergeable_attributes:)
+      originals.deep_merge_html_attributes(overrides, parents, mergeable_attributes: mergeable_attributes)
+    end
+
+    def split_attribute_list(value, parents:, mergeable_attributes:)
+      return value.split if value.is_a?(String) && mergeable_attributes.include?(parents)
+
+      value
+    end
+
+    def default_mergeable_attributes
+      [
+        %i(class),
+        %i(aria controls),
+        %i(aria describedby),
+        %i(aria flowto),
+        %i(aria labelledby),
+        %i(aria owns),
+      ]
+    end
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: html-attributes-utils
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Peter Yates
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-03-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.4.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.4.4
+- !ruby/object:Gem::Dependency
+  name: debug
+  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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.11.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-govuk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.3.0
+description: A small collection of utilities to ease working with hashes of HTML attributes
+email:
+- peter.yates@graphia.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/html_attributes_utils.rb
+homepage: https://github.com/DFE-Digital/html-attributes-utils
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/DFE-Digital/html-attributes-utils/issues
+  changelog_uri: https://github.com/DFE-Digital/html-attributes-utils/releases
+  homepage_uri: https://govuk-form-builder.netlify.app
+  source_code_uri: https://github.com/DFE-Digital/html-attributes-utils
+  github_repo: https://github.com/DFE-Digital/html-attributes-utils
+  documentation_uri: https://www.rubydoc.info/gems/html-attributes-utils/
+  rubygems_mfa_required: 'true'
+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.3.7
+signing_key:
+specification_version: 4
+summary: HTML attribute hash utilities
+test_files: []