vident 0.1.0

data/lib/vident/root_component/base.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Vident
+  module RootComponent
+    module Base
+      def initialize(
+        controllers: nil,
+        actions: nil,
+        targets: nil,
+        named_classes: nil, # https://stimulus.hotwired.dev/reference/css-classes
+        data_maps: nil,
+        element_tag: nil,
+        id: nil,
+        html_options: nil
+      )
+        @element_tag = element_tag
+        @html_options = html_options
+        @id = id
+        @controllers = Array.wrap(controllers)
+        @actions = actions
+        @targets = targets
+        @named_classes = named_classes
+        @data_map_kvs = {}
+        @data_maps = data_maps
+      end
+
+      # The view component's helpers for setting stimulus data-* attributes on this component.
+
+      # TODO: rename
+      # Create a Stimulus action string, and returns it
+      #   examples:
+      #   action(:my_thing) => "current_controller#myThing"
+      #   action(:click, :my_thing) => "click->current_controller#myThing"
+      #   action("click->current_controller#myThing") => "click->current_controller#myThing"
+      #   action("path/to/current", :my_thing) => "path--to--current_controller#myThing"
+      #   action(:click, "path/to/current", :my_thing) => "click->path--to--current_controller#myThing"
+      def action(*args)
+        part1, part2, part3 = args
+        (args.size == 1) ? parse_action_arg(part1) : parse_multiple_action_args(part1, part2, part3)
+      end
+
+      def action_data_attribute(*actions)
+        {action: parse_actions(actions).join(" ")}
+      end
+
+      # TODO: rename & make stimulus Target class instance and returns it, which can convert to String
+      # Create a Stimulus Target and returns it
+      #   examples:
+      #   target(:my_target) => {controller: 'current_controller' name: 'myTarget'}
+      #   target("path/to/current", :my_target) => {controller: 'path--to--current_controller', name: 'myTarget'}
+      def target(name, part2 = nil)
+        if part2.nil?
+          {controller: implied_controller_name, name: js_name(name)}
+        else
+          {controller: stimulize_path(name), name: js_name(part2)}
+        end
+      end
+
+      def target_data_attribute(name)
+        build_target_data_attributes([target(name)])
+      end
+
+      # Getter for a named classes list so can be used in view to set initial state on SSR
+      # Returns a String of classes that can be used in a `class` attribute.
+      def named_classes(*names)
+        names.map { |name| convert_classes_list_to_string(@named_classes[name]) }.join(" ")
+      end
+
+      # Helpers for generating the Stimulus data-* attributes directly
+
+      # Return the HTML `data-controller` attribute
+      def with_controllers
+        "data-controller='#{controller_list}'".html_safe
+      end
+
+      # Return the HTML `data-target` attribute
+      def as_targets(*targets)
+        build_target_data_attributes(parse_targets(targets))
+          .map { |dt, n| "data-#{dt}=\"#{n}\"" }
+          .join(" ")
+          .html_safe
+      end
+      alias_method :as_target, :as_targets
+
+      # Return the HTML `data-action` attribute to add these actions
+      def with_actions(*actions)
+        "data-action='#{parse_actions(actions).join(" ")}'".html_safe
+      end
+      alias_method :with_action, :with_actions
+
+      private
+
+      # An implicit Stimulus controller name is built from the implicit controller path
+      def implied_controller_name
+        stimulize_path(implied_controller_path)
+      end
+
+      # When using the DSL if you dont specify, the first controller is implied
+      def implied_controller_path
+        @controllers&.first || raise(StandardError, "No controllers have been specified")
+      end
+
+      # A complete list of Stimulus controllers for this component
+      def controller_list
+        @controllers&.map { |c| stimulize_path(c) }&.join(" ")
+      end
+
+      # Complete list of actions ready to be use in the data-action attribute
+      def action_list
+        return nil unless @actions&.size&.positive?
+        parse_actions(@actions).join(" ")
+      end
+
+      # Complete list of targets ready to be use in the data attributes
+      def target_list
+        return {} unless @targets&.size&.positive?
+        build_target_data_attributes(parse_targets(@targets))
+      end
+
+      def named_classes_list
+        return {} unless @named_classes&.size&.positive?
+        build_named_classes_data_attributes(@named_classes)
+      end
+
+      # stimulus "data-*" attributes map for this component
+      def tag_data_attributes
+        {controller: controller_list, action: action_list}
+          .merge!(target_list)
+          .merge!(named_classes_list)
+          .merge!(data_map_attributes)
+          .compact_blank!
+      end
+
+      # Actions can be specified as a symbol, in which case they imply an action on the primary
+      # controller, or as a string in which case it implies an action that is already fully qualified
+      # stimulus action.
+      # 1 Symbol: :my_action => "my_controller#myAction"
+      # 1 String: "my_controller#myAction"
+      # 2 Symbols: [:click, :my_action] => "click->my_controller#myAction"
+      # 1 String, 1 Symbol: ["path/to/controller", :my_action] => "path--to--controller#myAction"
+      # 1 Symbol, 1 String, 1 Symbol: [:hover, "path/to/controller", :my_action] => "hover->path--to--controller#myAction"
+
+      def parse_action_arg(part1)
+        if part1.is_a?(Symbol)
+          # 1 symbol arg, name of method on this controller
+          "#{implied_controller_name}##{js_name(part1)}"
+        elsif part1.is_a?(String)
+          # 1 string arg, fully qualified action
+          part1
+        end
+      end
+
+      def parse_multiple_action_args(part1, part2, part3)
+        if part3.nil? && part1.is_a?(Symbol)
+          # 2 symbol args = event + action
+          "#{part1}->#{implied_controller_name}##{js_name(part2)}"
+        elsif part3.nil?
+          # 1 string arg, 1 symbol = controller + action
+          "#{stimulize_path(part1)}##{js_name(part2)}"
+        else
+          # 1 symbol, 1 string, 1 symbol = as above but with event
+          "#{part1}->#{stimulize_path(part2)}##{js_name(part3)}"
+        end
+      end
+
+      # Parse actions, targets and attributes that are passed in as symbols or strings
+
+      def parse_targets(targets)
+        targets.map { |n| parse_target(n) }
+      end
+
+      def parse_target(raw_target)
+        return raw_target if raw_target.is_a?(String)
+        return raw_target if raw_target.is_a?(Hash)
+        target(raw_target)
+      end
+
+      def build_target_data_attributes(targets)
+        targets.map { |t| ["#{t[:controller]}-target".to_sym, t[:name]] }.to_h
+      end
+
+      def parse_actions(actions)
+        actions.map! { |a| a.is_a?(String) ? a : action(*a) }
+      end
+
+      def parse_attributes(attrs, controller = nil)
+        attrs.transform_keys { |k| "#{controller || implied_controller_name}-#{k}" }
+      end
+
+      def data_map_attributes
+        return {} unless @data_maps
+        @data_maps.each_with_object({}) do |m, obj|
+          if m.is_a?(Hash)
+            obj.merge!(parse_attributes(m))
+          elsif m.is_a?(Array)
+            controller_path = m.first
+            data = m.last
+            obj.merge!(parse_attributes(data, stimulize_path(controller_path)))
+          end
+        end
+      end
+
+      def parse_named_classes_hash(named_classes)
+        named_classes.map do |name, classes|
+          logical_name = name.to_s.dasherize
+          classes_str = convert_classes_list_to_string(classes)
+          if classes.is_a?(Hash)
+            {controller: stimulize_path(classes[:controller_path]), name: logical_name, classes: classes_str}
+          else
+            {controller: implied_controller_name, name: logical_name, classes: classes_str}
+          end
+        end
+      end
+
+      def build_named_classes_data_attributes(named_classes)
+        parse_named_classes_hash(named_classes)
+          .map { |c| ["#{c[:controller]}-#{c[:name]}-class", c[:classes]] }
+          .to_h
+      end
+
+      def convert_classes_list_to_string(classes)
+        return "" if classes.nil?
+        return classes if classes.is_a?(String)
+        return classes.join(" ") if classes.is_a?(Array)
+        classes[:classes].is_a?(Array) ? classes[:classes].join(" ") : classes[:classes]
+      end
+
+      # Convert a file path to a stimulus controller name
+      def stimulize_path(path)
+        path.split("/").map { |p| p.to_s.dasherize }.join("--")
+      end
+
+      # Convert a Ruby 'snake case' string to a JavaScript camel case strings
+      def js_name(name)
+        name.to_s.camelize(:lower)
+      end
+    end
+  end
+end

data/lib/vident/root_component/using_phlex_html.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+if Gem.loaded_specs.has_key? "phlex"
+  require "phlex"
+
+  module Vident
+    module RootComponent
+      class UsingPhlexHTML < Phlex::HTML
+        include Base
+
+        VALID_TAGS = Set[*(Phlex::HTML::VOID_ELEMENTS.keys + Phlex::HTML::STANDARD_ELEMENTS.keys)].freeze
+
+        # Create a tag for a target with a block containing content
+        def target_tag(tag_name, targets, **options, &block)
+          parsed = parse_targets(Array.wrap(targets))
+          options[:data] ||= {}
+          options[:data].merge!(build_target_data_attributes(parsed))
+          generate_tag(tag_name, **options, &block)
+        end
+
+        # Build a tag with the attributes determined by this components properties and stimulus
+        # data attributes.
+        def template(&block)
+          # Generate tag options and render
+          tag_type = @element_tag.presence&.to_sym || :div
+          raise ArgumentError, "Unsupported HTML tag name #{tag_type}" unless VALID_TAGS.include?(tag_type)
+          options = @html_options&.dup || {}
+          data_attrs = tag_data_attributes
+          data_attrs = options[:data].present? ? data_attrs.merge(options[:data]) : data_attrs
+          options = options.merge(id: @id) if @id
+          options.except!(:data)
+          options.merge!(data_attrs.transform_keys { |k| "data-#{k}" })
+          generate_tag(tag_type, **options, &block)
+        end
+
+        private
+
+        def generate_tag(tag_type, **options, &block)
+          send((tag_type == :template) ? :template_tag : tag_type, **options, &block)
+        end
+      end
+    end
+  end
+end

data/lib/vident/root_component/using_view_component.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+if Gem.loaded_specs.has_key? "view_component"
+  require "view_component"
+
+  module Vident
+    module RootComponent
+      class UsingViewComponent < ::ViewComponent::Base
+        include Base
+
+        SELF_CLOSING_TAGS = Set[:area, :base, :br, :col, :embed, :hr, :img, :input, :link, :meta, :param, :source, :track, :wbr].freeze
+
+        def target_tag(tag_name, targets, **options, &block)
+          parsed = parse_targets(Array.wrap(targets))
+          options[:data] ||= {}
+          options[:data].merge!(build_target_data_attributes(parsed))
+          content = view_context.capture(&block) if block
+          view_context.content_tag(tag_name, content, options)
+        end
+
+        def call
+          # Capture inner block content
+          # It's important that we capture the block content before generating the tag options.
+          # This is because the content could contain calls to `s.data_map`.
+          # These calls add key-value pairs to the internal data_map, which can then be translated into
+          # the correct `data-*` attrs by the tag options.
+          generated = content
+
+          # Generate outer tag options and render
+          tag_type = @element_tag.presence || :div
+          options = @html_options&.dup || {}
+          data_attrs = tag_data_attributes
+          options[:data] = options[:data].present? ? data_attrs.merge(options[:data]) : data_attrs
+          options = options.merge(id: @id) if @id
+          if SELF_CLOSING_TAGS.include?(tag_type)
+            view_context.tag(tag_type, options)
+          else
+            view_context.content_tag(tag_type, generated, options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vident/stable_id.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Vident
+  class StableId
+    class << self
+      def set_current_sequence_generator
+        ::Thread.current[:vident_number_sequence_generator] = id_sequence_generator
+      end
+
+      def next_id_in_sequence
+        generator = ::Thread.current[:vident_number_sequence_generator]
+        return "?" unless generator
+        generator.next.join("-")
+      end
+
+      private
+
+      def id_sequence_generator
+        number_generator = Random.new(296_865_628_524)
+        Enumerator.produce { number_generator.rand(10_000_000) }.with_index
+      end
+    end
+  end
+end

data/lib/vident/typed_component.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+if Gem.loaded_specs.has_key? "dry-struct"
+  require_relative "./attributes/typed"
+
+  module Vident
+    module TypedComponent
+      extend ActiveSupport::Concern
+
+      included do
+        include Vident::Base
+        include Vident::Attributes::Typed
+
+        attribute :id, String, delegates: false
+        attribute :html_options, Hash, delegates: false
+        attribute :element_tag, Symbol, delegates: false
+
+        # StimulusJS support
+        attribute :controllers, Array, default: [], delegates: false
+        attribute :actions, Array, default: [], delegates: false
+        attribute :targets, Array, default: [], delegates: false
+        attribute :data_maps, Array, default: [], delegates: false
+
+        # TODO normalise the syntax of defining actions, controllers, etc
+        attribute :named_classes, Hash, delegates: false
+      end
+
+      def initialize(attrs = {})
+        before_initialise(attrs)
+        prepare_attributes(attrs)
+        # The attributes need to also be set as ivars
+        attributes.each do |attr_name, attr_value|
+          instance_variable_set(self.class.attribute_ivar_names[attr_name], attr_value)
+        end
+        after_initialise
+        super()
+      end
+    end
+  end
+else
+  module Vident
+    module TypedComponent
+      def self.included(base)
+        raise "Vident::TypedComponent requires dry-struct to be installed"
+      end
+    end
+  end
+end

data/lib/vident/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Vident
+  VERSION = "0.1.0"
+end

data/lib/vident.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "vident/version"
+require_relative "vident/railtie"
+
+module Vident
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+  end
+
+  class Configuration
+    attr_accessor :include_i18n_helpers
+
+    def initialize
+      @include_i18n_helpers = true
+    end
+  end
+end
+
+require_relative "vident/stable_id"
+require_relative "vident/root_component/base"
+require_relative "vident/root_component/using_phlex_html"
+require_relative "vident/root_component/using_view_component"
+require_relative "vident/base"
+require_relative "vident/component"
+require_relative "vident/typed_component"

data/sig/vident.rbs

@@ -0,0 +1,4 @@
+module Vident
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: vident
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stephen Ierodiaconou
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-12-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description: Vident makes using Stimulus with your `ViewComponent` or `Phlex` view
+  components as easy as writing Ruby. It also provides a base class for your components
+  to inherit from.
+email:
+- stevegeek@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/ex1.gif
+- lib/tasks/vident.rake
+- lib/vident.rb
+- lib/vident/attributes/not_typed.rb
+- lib/vident/attributes/typed.rb
+- lib/vident/attributes/typed_niling_struct.rb
+- lib/vident/attributes/types.rb
+- lib/vident/base.rb
+- lib/vident/component.rb
+- lib/vident/railtie.rb
+- lib/vident/root_component/base.rb
+- lib/vident/root_component/using_phlex_html.rb
+- lib/vident/root_component/using_view_component.rb
+- lib/vident/stable_id.rb
+- lib/vident/typed_component.rb
+- lib/vident/version.rb
+- sig/vident.rbs
+homepage: https://github.com/stevegeek/vident
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stevegeek/vident
+  source_code_uri: https://github.com/stevegeek/vident
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.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: Vident is a view component base class for your design system implementation,
+  which provides helpers for working with Stimulus. For ViewComponent and Phlex.
+test_files: []