ruby-exclaim 0.0.0

data/lib/exclaim/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Exclaim
+  class Railtie < Rails::Railtie
+    initializer 'exclaim.config' do
+      Exclaim.configure do |config|
+        config.logger = Rails.logger
+      end
+    end
+  end
+end

data/lib/exclaim/renderer.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Exclaim
+  class Renderer
+    def initialize(parsed_ui)
+      @parsed_ui = parsed_ui
+    end
+
+    def call(env: {})
+      top_level_component = @parsed_ui
+      render_element(top_level_component, env)
+    end
+
+    private
+
+    def render_element(element, env)
+      case element
+      in Component => component
+        resolved_config = resolve_component_config(component, env)
+        render_child = method(:render_element)
+        component.implementation.call(resolved_config, env, &render_child)
+      else
+        resolve(element, env)
+      end
+    end
+
+    def resolve_component_config(component, env)
+      resolve(component.config, env).transform_values! { |value| escape_html!(value) }
+    end
+
+    def escape_html!(value)
+      case value
+      when String
+        CGI.escape_html(value)
+      when Hash
+        value.transform_values! { |v| escape_html!(v) }
+      when Array
+        value.map! { |v| escape_html!(v) }
+      when Numeric, TrueClass, FalseClass, NilClass
+        value
+      else
+        # assumed to be a custom wrapper class returned by a helper
+        value
+      end
+    end
+
+    def resolve(element, env)
+      case element
+      in Component => component
+        component # will be resolved by calling its implementation later
+      in Bind => bind
+        bind.evaluate(env)
+      in Helper => helper
+        resolved_helper_config = resolve(helper.config, env)
+        helper.implementation.call(resolved_helper_config, env)
+      in Hash => hash
+        hash.transform_values { |value| resolve(value, env) }
+      in Array => array
+        array.map { |item| resolve(item, env) }
+      else
+        element
+      end
+    end
+  end
+end

data/lib/exclaim/ui.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Exclaim
+  class Ui
+    attr_reader :implementation_map, :parsed_ui, :renderer
+
+    def initialize(implementation_map: Exclaim::Implementations.example_implementation_map)
+      @implementation_map = Exclaim::ImplementationMap.parse!(implementation_map)
+    rescue Exclaim::Error
+      raise
+    rescue StandardError => e
+      e.extend(Exclaim::InternalError)
+      raise
+    end
+
+    def parse_ui!(ui_config)
+      self.parsed_ui = Exclaim::UiConfiguration.parse!(@implementation_map, ui_config)
+    rescue Exclaim::Error
+      raise
+    rescue StandardError => e
+      e.extend(Exclaim::InternalError)
+      raise
+    end
+
+    def render(env: {})
+      if parsed_ui.nil?
+        error_message = 'Cannot render without UI configured, must call Exclaim::Ui#parse_ui(ui_config) first'
+        raise RenderingError.new(error_message)
+      end
+
+      renderer.call(env: env)
+    rescue Exclaim::Error
+      raise
+    rescue StandardError => e
+      e.extend(Exclaim::InternalError)
+      raise
+    end
+
+    def unique_bind_paths
+      if parsed_ui.nil?
+        error_message = 'Cannot compute unique_bind_paths without UI configured, ' \
+                        'must call Exclaim::Ui#parse_ui(ui_config) first'
+        raise UiConfigurationError.new(error_message)
+      end
+
+      parsed_ui.config.reduce([]) { |all_paths, config_value| bind_paths(config_value, all_paths) }.uniq!
+    end
+
+    def each_element(element_names = :ALL_ELEMENTS, &blk)
+      if parsed_ui.nil?
+        error_message = 'Cannot compute each_element without UI configured, ' \
+                        'must call Exclaim::Ui#parse_ui(ui_config) first'
+        raise UiConfigurationError.new(error_message)
+      end
+      normalized_element_names = parse_element_names(element_names)
+
+      if block_given?
+        top_level_component = parsed_ui
+        recurse_json_declarations(top_level_component, normalized_element_names, &blk)
+      else
+        to_enum(__callee__)
+      end
+    end
+
+    private
+
+    def parsed_ui=(value)
+      @parsed_ui = value
+      @renderer = Exclaim::Renderer.new(@parsed_ui)
+    end
+
+    def bind_paths(config_value, accumulator)
+      case config_value
+      in Hash => hash
+        hash.values.each { |val| bind_paths(val, accumulator) }
+      in Array => array
+        array.each { |val| bind_paths(val, accumulator) }
+      in Bind => bind
+        accumulator.push(bind.path)
+      in Helper | Component => element
+        bind_paths(element.config, accumulator)
+      else
+        nil
+      end
+
+      accumulator
+    end
+
+    def parse_element_names(element_names)
+      case element_names
+      when :ALL_ELEMENTS
+        :ALL_ELEMENTS
+      when String
+        [normalize_name(element_names)]
+      when Array
+        element_names.map { |en| normalize_name(en) }
+      else
+        raise UiConfigurationError.new('Exclaim::Ui#each_element: element_names argument ' \
+                                       "must be a String or Array, given #{element_names.class}")
+      end
+    end
+
+    def normalize_name(element_name)
+      element_name.start_with?('$') ? element_name[1..] : element_name
+    end
+
+    def recurse_json_declarations(config_value, element_names, &blk)
+      case config_value
+      in Bind => bind
+        yield bind.json_declaration if element_matches?(element_names, 'bind')
+      in Component | Helper => element
+        yield element.json_declaration if element_matches?(element_names, element.name)
+        element.config.each_value { |val| recurse_json_declarations(val, element_names, &blk) }
+      in Array => array
+        array.each { |val| recurse_json_declarations(val, element_names, &blk) }
+      in Hash => hash
+        hash.each_value { |val| recurse_json_declarations(val, element_names, &blk) }
+      else
+        nil
+      end
+    end
+
+    def element_matches?(requested_element_names, parsed_element_name)
+      requested_element_names == :ALL_ELEMENTS || requested_element_names.include?(parsed_element_name)
+    end
+  end
+end

data/lib/exclaim/ui_configuration.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module UiConfiguration
+    extend self
+
+    EXPLICIT_ELEMENT_NAMES = ['$component', '$helper', '$bind'].freeze
+
+    def parse!(implementation_map, ui_config)
+      raise UiConfigurationError.new("ui_config must be a Hash, given: #{ui_config.class}") unless ui_config.is_a?(Hash)
+
+      parsed_ui = parse_config_value(implementation_map, ui_config)
+
+      unless parsed_ui.is_a?(Exclaim::Component)
+        error_message = 'ui_config must declare a component at the top-level that is present in implementation_map'
+        raise UiConfigurationError.new(error_message)
+      end
+
+      parsed_ui
+    end
+
+    private
+
+    def parse_config_value(implementation_map, config_value)
+      case config_value
+      in Hash => hash
+        parse_config_hash(implementation_map, hash)
+      in Array => array
+        array.map { |value| parse_config_value(implementation_map, value) }
+      else
+        config_value
+      end
+    end
+
+    def parse_config_hash(implementation_map, config_hash)
+      # config_hash will be either an Exclaim element declaration or just plain configuration values
+      element_name = parse_element_name(implementation_map, config_hash)
+      if element_name.nil?
+        config_hash.transform_values { |val| parse_config_value(implementation_map, val) }
+      else
+        parse_element(implementation_map, element_name, config_hash)
+      end
+    end
+
+    def parse_element(implementation_map, element_name, element_declaration_hash)
+      implementation = implementation_map[element_name]
+
+      if helper?(implementation)
+        config = parse_element_config(implementation_map, element_declaration_hash)
+        Exclaim::Helper.new(json_declaration: element_declaration_hash,
+                            name: element_name,
+                            implementation: implementation,
+                            config: config)
+      elsif component?(implementation)
+        config = parse_element_config(implementation_map, element_declaration_hash)
+        Exclaim::Component.new(json_declaration: element_declaration_hash,
+                               name: element_name,
+                               implementation: implementation,
+                               config: config)
+      else
+        Exclaim::Bind.new(json_declaration: element_declaration_hash, path: element_declaration_hash['$bind'])
+      end
+    end
+
+    def parse_element_config(implementation_map, element_declaration_hash)
+      element_declaration_hash.each_with_object({}) do |(key, val), parsed_element_config|
+        parsed_element_config[key] = if ['$component', '$helper'].include?(key)
+                                       val
+                                     else
+                                       parse_config_value(implementation_map, val)
+                                     end
+      end
+    end
+
+    def parse_element_name(implementation_map, config_hash)
+      candidate_names = config_hash.keys.filter_map do |key|
+        key[1..] if key.start_with?('$') && !EXPLICIT_ELEMENT_NAMES.include?(key)
+      end
+      candidate_names.reject! do |name|
+        unrecognized = implementation_map[name].nil?
+        Exclaim.logger.warn("ui_config includes key \"$#{name}\" which has no matching implementation") if unrecognized
+        unrecognized
+      end
+
+      explicit_component_name = parse_explicit_declaration(implementation_map, config_hash, '$component')
+      explicit_helper_name = parse_explicit_declaration(implementation_map, config_hash, '$helper')
+
+      candidate_names.push(explicit_component_name, explicit_helper_name)
+      candidate_names.compact!
+
+      # binds do not have implementations, but they are still special Exclaim elements
+      candidate_names.push('bind') if config_hash.include?('$bind')
+
+      if candidate_names.count > 1
+        error_message = "Multiple Exclaim elements defined at one configuration level: #{candidate_names}. " \
+                        'Only one allowed.'
+        raise UiConfigurationError.new(error_message)
+      end
+
+      # returns nil when config_hash is not an Exclaim element declaration
+      candidate_names.first
+    end
+
+    def parse_explicit_declaration(implementation_map, config_hash, explicit_key)
+      explicit_name = config_hash[explicit_key]
+      return nil if explicit_name.nil?
+
+      if explicit_name.start_with?('$')
+        error_message = "Invalid: \"#{explicit_key}\": \"#{explicit_name}\", " \
+                        "when declaring explicit \"#{explicit_key}\" do not prefix the name with \"$\""
+        raise UiConfigurationError.new(error_message)
+      end
+
+      if implementation_map[explicit_name].nil?
+        error_message = "ui_config declares \"#{explicit_key}\": \"#{explicit_name}\" " \
+                        'which has no matching implementation'
+        raise UiConfigurationError.new(error_message)
+      end
+
+      explicit_name
+    end
+
+    def component?(element)
+      element_type(element) == 'component'
+    end
+
+    def helper?(element)
+      element_type(element) == 'helper'
+    end
+
+    def element_type(element)
+      if element.respond_to?(:component?)
+        element.component? ? 'component' : 'helper'
+      elsif element.respond_to?(:helper?)
+        element.helper? ? 'helper' : 'component'
+      end
+    end
+  end
+end

data/lib/exclaim/utilities.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Utilities
+    def element_name(config_hash)
+      unless config_hash.is_a?(Hash)
+        error_message = "Exclaim.element_name can only determine name from a Hash, given #{config_hash.class} value"
+        Exclaim.logger.warn(error_message)
+        return
+      end
+
+      return config_hash['$component'] if config_hash.include?('$component')
+      return config_hash['$helper'] if config_hash.include?('$helper')
+      return 'bind' if config_hash.include?('$bind')
+
+      shorthand_name = config_hash.keys.find { |key| key.start_with?('$') }
+      shorthand_name&.[](1..)
+    end
+  end
+end

data/lib/exclaim/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Exclaim
+  VERSION = '0.0.0'
+end

data/ruby-exclaim.gemspec

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'exclaim/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ruby-exclaim'
+  spec.version       = Exclaim::VERSION
+  spec.authors       = ['Salsify, Inc']
+  spec.email         = ['engineering@salsify.com']
+
+  spec.summary       = 'Ruby utilities for Exclaim UIs'
+  spec.description   = spec.summary
+  spec.homepage      = 'https://github.com/salsify/ruby-exclaim'
+
+  spec.license       = 'MIT'
+
+
+  # Set 'allowed_push_post' to control where this gem can be published.
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'bin'
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.7'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'overcommit'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.9'
+  spec.add_development_dependency 'rspec_junit_formatter', '~> 0.4.1'
+
+  spec.add_development_dependency 'salsify_rubocop', '~> 1.0'
+end

metadata

@@ -0,0 +1,166 @@
+--- !ruby/object:Gem::Specification
+name: ruby-exclaim
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Salsify, Inc
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: overcommit
+  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: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+- !ruby/object:Gem::Dependency
+  name: salsify_rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Ruby utilities for Exclaim UIs
+email:
+- engineering@salsify.com
+executables:
+- console
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- ".circleci/config.yml"
+- ".github/workflows/release.yml"
+- ".gitignore"
+- ".overcommit.yml"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/exclaim.rb
+- lib/exclaim/bind.rb
+- lib/exclaim/component.rb
+- lib/exclaim/errors.rb
+- lib/exclaim/helper.rb
+- lib/exclaim/implementable.rb
+- lib/exclaim/implementation_map.rb
+- lib/exclaim/implementations/each_component.rb
+- lib/exclaim/implementations/example_implementation_map.rb
+- lib/exclaim/implementations/if_helper.rb
+- lib/exclaim/implementations/image_component.rb
+- lib/exclaim/implementations/join_helper.rb
+- lib/exclaim/implementations/let_component.rb
+- lib/exclaim/implementations/paragraph_component.rb
+- lib/exclaim/implementations/text_component.rb
+- lib/exclaim/implementations/vbox_component.rb
+- lib/exclaim/railtie.rb
+- lib/exclaim/renderer.rb
+- lib/exclaim/ui.rb
+- lib/exclaim/ui_configuration.rb
+- lib/exclaim/utilities.rb
+- lib/exclaim/version.rb
+- ruby-exclaim.gemspec
+homepage: https://github.com/salsify/ruby-exclaim
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.11
+signing_key:
+specification_version: 4
+summary: Ruby utilities for Exclaim UIs
+test_files: []