phlexi-display 0.0.1 → 0.0.3

data/lib/phlexi/display/option_mapper.rb

@@ -1,154 +0,0 @@
-# frozen_string_literal: true
-
-module Phlexi
-  module Display
-    # OptionMapper is responsible for converting a collection of objects into a hash of options
-    # suitable for form controls, such as `select > options`.
-    # Both values and labels are converted to strings.
-    #
-    # @example Basic usage
-    #   collection = [["First", 1], ["Second", 2]]
-    #   mapper = OptionMapper.new(collection)
-    #   mapper.each { |value, label| puts "#{value}: #{label}" }
-    #
-    # @example Using with ActiveRecord objects
-    #   users = User.all
-    #   mapper = OptionMapper.new(users)
-    #   mapper.each { |id, name| puts "#{id}: #{name}" }
-    #
-    # @example Array access with different value types
-    #   mapper = OptionMapper.new([["Integer", 1], ["String", "2"], ["Symbol", :three]])
-    #   puts mapper["1"]      # Output: "Integer"
-    #   puts mapper["2"]      # Output: "String"
-    #   puts mapper["three"]  # Output: "Symbol"
-    #
-    # @note This class is thread-safe as it doesn't maintain mutable state.
-    class OptionMapper
-      include Enumerable
-
-      # Initializes a new OptionMapper instance.
-      #
-      # @param collection [#call, #to_a] The collection to be mapped.
-      # @param label_method [Symbol, nil] The method to call on each object to get the label.
-      # @param value_method [Symbol, nil] The method to call on each object to get the value.
-      def initialize(collection, label_method: nil, value_method: nil)
-        @raw_collection = collection
-        @label_method = label_method
-        @value_method = value_method
-      end
-
-      # Iterates over the collection, yielding value-label pairs.
-      #
-      # @yieldparam value [String] The string value for the current item.
-      # @yieldparam label [String] The string label for the current item.
-      # @return [Enumerator] If no block is given.
-      def each(&)
-        collection.each(&)
-      end
-
-      # @return [Array<String>] An array of all labels in the collection.
-      def labels
-        collection.values
-      end
-
-      # @return [Array<String>] An array of all values in the collection.
-      def values
-        collection.keys
-      end
-
-      # Retrieves the label for a given value.
-      #
-      # @param value [#to_s] The value to look up.
-      # @return [String, nil] The label corresponding to the value, or nil if not found.
-      def [](value)
-        collection[value.to_s]
-      end
-
-      private
-
-      # @return [Hash<String, String>] The materialized collection as a hash of string value => string label.
-      def collection
-        @collection ||= materialize_collection(@raw_collection)
-      end
-
-      # Converts the raw collection into a materialized hash.
-      #
-      # @param collection [#call, #to_a] The collection to be materialized.
-      # @return [Hash<String, String>] The materialized collection as a hash of string value => string label.
-      # @raise [ArgumentError] If the collection cannot be materialized into an enumerable.
-      def materialize_collection(collection)
-        case collection
-        in Hash => hash
-          hash.transform_keys(&:to_s).transform_values(&:to_s)
-        in Array => arr
-          array_to_hash(arr)
-        in Range => range
-          range_to_hash(range)
-        in Proc => proc
-          materialize_collection(proc.call)
-        in Symbol
-          raise ArgumentError, "Symbol collections are not supported in this context"
-        in Set => set
-          array_to_hash(set.to_a)
-        else
-          array_to_hash(Array(collection))
-        end
-      rescue ArgumentError
-        # Rails.logger.warn("Unhandled inclusion collection type: #{e}")
-        {}
-      end
-
-      # Converts an array to a hash using detected or specified methods.
-      #
-      # @param array [Array] The array to convert.
-      # @return [Hash<String, String>] The resulting hash of string value => string label.
-      def array_to_hash(array)
-        sample = array.first || array.last
-        methods = detect_methods_for_sample(sample)
-
-        array.each_with_object({}) do |item, hash|
-          value = item.public_send(methods[:value]).to_s
-          label = item.public_send(methods[:label]).to_s
-          hash[value] = label
-        end
-      end
-
-      # Converts a range to a hash.
-      #
-      # @param range [Range] The range to convert.
-      # @return [Hash<String, String>] The range converted to a hash of string value => string label.
-      # @raise [ArgumentError] If the range is unbounded.
-      def range_to_hash(range)
-        raise ArgumentError, "Cannot safely materialize an unbounded range" if range.begin.nil? || range.end.nil?
-
-        range.each_with_object({}) { |value, hash| hash[value.to_s] = value.to_s }
-      end
-
-      # Detects suitable methods for label and value from a sample object.
-      #
-      # @param sample [Object] A sample object from the collection.
-      # @return [Hash{Symbol => Symbol}] A hash containing :label and :value keys with corresponding method names.
-      def detect_methods_for_sample(sample)
-        case sample
-        when Array
-          {value: :last, label: :first}
-        else
-          {
-            value: @value_method || collection_value_methods.find { |m| sample.respond_to?(m) },
-            label: @label_method || collection_label_methods.find { |m| sample.respond_to?(m) }
-          }
-        end
-      end
-
-      # @return [Array<Symbol>] An array of method names to try for collection values.
-      def collection_value_methods
-        @collection_value_methods ||= %i[id to_s].freeze
-      end
-
-      # @return [Array<Symbol>] An array of method names to try for collection labels.
-      def collection_label_methods
-        @collection_label_methods ||= %i[to_label name title to_s].freeze
-      end
-    end
-  end
-end

data/lib/phlexi/display/structure/dom.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module Phlexi
-  module Display
-    module Structure
-      # Generates DOM IDs, names, etc. for a Field, Namespace, or Node based on
-      # norms that were established by Rails. These can be used outsidef or Rails in
-      # other Ruby web frameworks since it has now dependencies on Rails.
-      class DOM
-        def initialize(field:)
-          @field = field
-        end
-
-        # Converts the value of the field to a String, which is required to work
-        # with Phlex. Assumes that `Object#to_s` emits a format suitable for the web form.
-        def value
-          @field.value.to_s
-        end
-
-        # Walks from the current node to the parent node, grabs the names, and seperates
-        # them with a `_` for a DOM ID.
-        def id
-          @id ||= begin
-            root, *rest = lineage
-            root_key = root.respond_to?(:dom_id) ? root.dom_id : root.key
-            rest.map(&:key).unshift(root_key).join("_")
-          end
-        end
-
-        # The `name` attribute of a node, which is influenced by Rails.
-        # All node names, except the parent node, are wrapped in a `[]` and collections
-        # are left empty. For example, `user[addresses][][street]` would be created for a form with
-        # data shaped like `{user: {addresses: [{street: "Sesame Street"}]}}`.
-        def name
-          @name ||= begin
-            root, *names = keys
-            names.map { |name| "[#{name}]" }.unshift(root).join
-          end
-        end
-
-        # One-liner way of walking from the current node all the way up to the parent.
-        def lineage
-          @lineage ||= Enumerator.produce(@field, &:parent).take_while(&:itself).reverse
-        end
-
-        # Emit the id, name, and value in an HTML tag-ish that doesnt have an element.
-        def inspect
-          "<#{self.class.name} id=#{id.inspect} name=#{name.inspect} value=#{value.inspect}/>"
-        end
-
-        private
-
-        def keys
-          @keys ||= lineage.map do |node|
-            # If the parent of a field is a field, the name should be nil.
-            node.key unless node.parent.is_a? FieldBuilder
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phlexi/display/structure/field_builder.rb

@@ -1,236 +0,0 @@
-# frozen_string_literal: true
-
-require "phlex"
-
-module Phlexi
-  module Display
-    module Structure
-      # FieldBuilder class is responsible for building display fields with various options and components.
-      #
-      # @attr_reader [Structure::DOM] dom The DOM structure for the field.
-      # @attr_reader [Hash] options Options for the field.
-      # @attr_reader [Object] object The object associated with the field.
-      # @attr_reader [Hash] attributes Attributes for the field.
-      # @attr_accessor [Object] value The value of the field.
-      class FieldBuilder < Node
-        include Phlex::Helpers
-        include FieldOptions::Associations
-        include FieldOptions::Themes
-        include FieldOptions::Validators
-        include FieldOptions::Labels
-        include FieldOptions::Hints
-        include FieldOptions::Errors
-        include FieldOptions::InferredTypes
-        include FieldOptions::Collection
-        include FieldOptions::Placeholder
-        include FieldOptions::Required
-        include FieldOptions::Autofocus
-        include FieldOptions::Disabled
-        include FieldOptions::Readonly
-        include FieldOptions::Length
-        include FieldOptions::MinMax
-        include FieldOptions::Pattern
-        include FieldOptions::Multiple
-        include FieldOptions::Limit
-
-        attr_reader :dom, :options, :object, :input_attributes, :value
-
-        # Initializes a new FieldBuilder instance.
-        #
-        # @param key [Symbol, String] The key for the field.
-        # @param parent [Structure::Namespace] The parent object.
-        # @param object [Object, nil] The associated object.
-        # @param value [Object] The initial value for the field.
-        # @param input_attributes [Hash] Default attributes to apply to input fields.
-        # @param options [Hash] Additional options for the field.
-        def initialize(key, parent:, object: nil, value: NIL_VALUE, input_attributes: {}, **options)
-          super(key, parent: parent)
-
-          @object = object
-          @value = determine_initial_value(value)
-          @input_attributes = input_attributes
-          @options = options
-          @dom = Structure::DOM.new(field: self)
-        end
-
-        # Creates a label tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the label.
-        # @return [Components::Label] The label component.
-        def label_tag(**attributes, &)
-          create_component(Components::Label, :label, **attributes, &)
-        end
-
-        # Creates an input tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the input.
-        # @return [Components::Input] The input component.
-        def input_tag(**attributes, &)
-          create_component(Components::Input, :input, **attributes, &)
-        end
-
-        def file_input_tag(**attributes, &)
-          create_component(Components::FileInput, :file, **attributes, &)
-        end
-
-        # Creates a checkbox tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the checkbox.
-        # @return [Components::Checkbox] The checkbox component.
-        def checkbox_tag(**attributes, &)
-          create_component(Components::Checkbox, :checkbox, **attributes, &)
-        end
-
-        # Creates collection checkboxes for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the collection checkboxes.
-        # @yield [block] The block to be executed for each checkbox.
-        # @return [Components::CollectionCheckboxes] The collection checkboxes component.
-        def collection_checkboxes_tag(**attributes, &)
-          create_component(Components::CollectionCheckboxes, :collection_checkboxes, **attributes, &)
-        end
-
-        # Creates a radio button tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the radio button.
-        # @return [Components::RadioButton] The radio button component.
-        def radio_button_tag(**attributes, &)
-          create_component(Components::RadioButton, :radio, **attributes, &)
-        end
-
-        # Creates collection radio buttons for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the collection radio buttons.
-        # @yield [block] The block to be executed for each radio button.
-        # @return [Components::CollectionRadioButtons] The collection radio buttons component.
-        def collection_radio_buttons_tag(**attributes, &)
-          create_component(Components::CollectionRadioButtons, :collection_radio_buttons, **attributes, &)
-        end
-
-        # Creates a textarea tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the textarea.
-        # @return [Components::Textarea] The textarea component.
-        def textarea_tag(**attributes, &)
-          create_component(Components::Textarea, :textarea, **attributes, &)
-        end
-
-        # Creates a select tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the select.
-        # @return [Components::Select] The select component.
-        def select_tag(**attributes, &)
-          create_component(Phlex::UI::Select, :select, **attributes, &)
-        end
-
-        def input_array_tag(**attributes, &)
-          create_component(Components::InputArray, :array, **attributes, &)
-        end
-
-        # Creates a hint tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the hint.
-        # @return [Components::Hint] The hint component.
-        def hint_tag(**attributes, &)
-          create_component(Components::Hint, :hint, **attributes, &)
-        end
-
-        # Creates an error tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the error.
-        # @return [Components::Error] The error component.
-        def error_tag(**attributes, &)
-          create_component(Components::Error, :error, **attributes, &)
-        end
-
-        # Creates a full error tag for the field.
-        #
-        # @param attributes [Hash] Additional attributes for the full error.
-        # @return [Components::FullError] The full error component.
-        def full_error_tag(**attributes, &)
-          create_component(Components::FullError, :full_error, **attributes, &)
-        end
-
-        # Wraps the field with additional markup.
-        #
-        # @param inner [Hash] Attributes for the inner wrapper.
-        # @param attributes [Hash] Additional attributes for the wrapper.
-        # @yield [block] The block to be executed within the wrapper.
-        # @return [Components::Wrapper] The wrapper component.
-        def wrapped(inner: {}, **attributes, &)
-          wrapper_class = attributes.delete(:class) || themed(attributes.delete(:theme) || :wrapper)
-          inner[:class] = inner.delete(:class) || themed(inner.delete(:theme) || :inner_wrapper)
-          Components::Wrapper.new(self, class: wrapper_class, inner: inner, **attributes, &)
-        end
-
-        # Creates a multi-value field collection.
-        #
-        # @param range [Integer, #to_a] The range of keys for each field. If an integer is passed, keys will begin from 1.
-        # @yield [block] The block to be executed for each item in the collection.
-        # @return [FieldCollection] The field collection.
-        def multi(range = nil, &)
-          FieldCollection.new(field: self, range: range, &)
-        end
-
-        # Creates a submit button
-        #
-        # @param attributes [Hash] Additional attributes for the submit.
-        # @return [Components::SubmitButton] The submit button component.
-        def submit_button_tag(**attributes, &)
-          create_component(Components::SubmitButton, :submit_button, **attributes, &)
-        end
-
-        def extract_input(params)
-          raise "field##{dom.name} did not define an input component" unless @field_input_component
-
-          @field_input_component.extract_input(params)
-        end
-
-        protected
-
-        def create_component(component_class, theme_key, **attributes, &)
-          if component_class.include?(Phlexi::Display::Components::Concerns::HandlesInput)
-            raise "input component already defined: #{@field_input_component.inspect}" if @field_input_component
-
-            attributes = input_attributes.deep_merge(attributes)
-            @field_input_component = component_class.new(self, class: component_class_for(theme_key, attributes), **attributes, &)
-          else
-            component_class.new(self, class: component_class_for(theme_key, attributes), **attributes, &)
-          end
-        end
-
-        def component_class_for(theme_key, attributes)
-          attributes.delete(:class) || themed(attributes.key?(:theme) ? attributes.delete(:theme) : theme_key)
-        end
-
-        def has_value?
-          value.present?
-        end
-
-        def determine_initial_value(value)
-          return value unless value == NIL_VALUE
-
-          determine_from_association || determine_value_from_object
-        end
-
-        def determine_value_from_object
-          object.respond_to?(key) ? object.public_send(key) : nil
-        end
-
-        def determine_from_association
-          return nil unless reflection.present?
-
-          value = object.public_send(key)
-          case reflection.macro
-          when :has_many, :has_and_belongs_to_many
-            value&.map { |v| v.public_send(reflection.klass.primary_key) }
-          when :belongs_to, :has_one
-            value&.public_send(reflection.klass.primary_key)
-          else
-            raise ArgumentError, "Unsupported association type: #{reflection.macro}"
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phlexi/display/structure/field_collection.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Phlexi
-  module Display
-    module Structure
-      class FieldCollection
-        include Enumerable
-
-        class Builder
-          attr_reader :key, :index
-
-          def initialize(key, field, index)
-            @key = key.to_s
-            @field = field
-            @index = index
-          end
-
-          def field(**)
-            @field.class.new(key, input_attributes: @field.input_attributes, **, parent: @field).tap do |field|
-              yield field if block_given?
-            end
-          end
-
-          def hidden_field_tag(value: "", force: false)
-            raise "Attempting to build hidden field on non-first field in a collection" unless index == 0 || force
-
-            @field.class
-              .new("hidden", parent: @field)
-              .input_tag(type: :hidden, value:)
-          end
-        end
-
-        def initialize(field:, range:, &)
-          @field = field
-          @range = case range
-          when Range, Array
-            range
-          when Integer
-            1..range
-          else
-            range.to_a
-          end
-          each(&) if block_given?
-        end
-
-        def each(&)
-          @range.each.with_index do |key, index|
-            yield Builder.new(key, @field, index)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phlexi/display/structure/namespace.rb

@@ -1,135 +0,0 @@
-# frozen_string_literal: true
-
-module Phlexi
-  module Display
-    module Structure
-      # A Namespace maps and object to values, but doesn't actually have a value itself. For
-      # example, a `User` object or ActiveRecord model could be passed into the `:user` namespace.
-      # To access the values on a Namespace, the `field` can be called for single values.
-      #
-      # Additionally, to access namespaces within a namespace, such as if a `User has_many :addresses` in
-      # ActiveRecord, the `namespace` method can be called which will return another Namespace object and
-      # set the current Namespace as the parent.
-      class Namespace < Structure::Node
-        include Enumerable
-
-        attr_reader :builder_klass, :object
-
-        def initialize(key, parent:, builder_klass:, object: nil)
-          super(key, parent: parent)
-          @builder_klass = builder_klass
-          @object = object
-          @children = {}
-          yield self if block_given?
-        end
-
-        def field(key, **attributes)
-          create_child(key, attributes.delete(:builder_klass) || builder_klass, object: object, **attributes).tap do |field|
-            yield field if block_given?
-          end
-        end
-
-        def submit_button(key = nil, **attributes, &)
-          field(key || SecureRandom.hex).submit_button_tag(**attributes, &)
-        end
-
-        # Creates a `Namespace` child instance with the parent set to the current instance, adds to
-        # the `@children` Hash to ensure duplicate child namespaces aren't created, then calls the
-        # method on the `@object` to get the child object to pass into that namespace.
-        #
-        # For example, if a `User#permission` returns a `Permission` object, we could map that to a
-        # form like this:
-        #
-        # ```ruby
-        # Superform :user, object: User.new do |form|
-        #   form.nest_one :permission do |permission|
-        #     form.field :role
-        #   end
-        # end
-        # ```
-        def nest_one(key, object: nil, &)
-          object ||= object_value_for(key: key)
-          create_child(key, self.class, object:, builder_klass:, &)
-        end
-
-        # Wraps an array of objects in Namespace classes. For example, if `User#addresses` returns
-        # an enumerable or array of `Address` classes:
-        #
-        # ```ruby
-        # Phlexi::Display.new User.new do |form|
-        #   render form.field(:email).input_tag
-        #   render form.field(:name).input_tag
-        #   form.nest_many :addresses do |address|
-        #     render address.field(:street).input_tag
-        #     render address.field(:state).input_tag
-        #     render address.field(:zip).input_tag
-        #   end
-        # end
-        # ```
-        # The object within the block is a `Namespace` object that maps each object within the enumerable
-        # to another `Namespace` or `Field`.
-        def nest_many(key, collection: nil, &)
-          collection ||= Array(object_value_for(key: key))
-          create_child(key, NamespaceCollection, collection:, &)
-        end
-
-        def extract_input(params)
-          if params.is_a?(Array)
-            each_with_object({}) do |child, hash|
-              hash.merge! child.extract_input(params[0])
-            end
-          else
-            input = each_with_object({}) do |child, hash|
-              hash.merge! child.extract_input(params[key])
-            end
-            {key => input}
-          end
-        end
-
-        # Iterates through the children of the current namespace, which could be `Namespace` or `Field`
-        # objects.
-        def each(&)
-          @children.values.each(&)
-        end
-
-        def dom_id
-          @dom_id ||= begin
-            id = if object.nil?
-              nil
-            elsif object.class.respond_to?(:primary_key)
-              object.public_send(object.class.primary_key) || :new
-            elsif object.respond_to?(:id)
-              object.id || :new
-            end
-            [key, id].compact.join("_").underscore
-          end
-        end
-
-        # Creates a root Namespace, which is essentially a form.
-        def self.root(*, builder_klass:, **, &)
-          new(*, parent: nil, builder_klass:, **, &)
-        end
-
-        protected
-
-        # Calls the corresponding method on the object for the `key` name, if it exists. For example
-        # if the `key` is `email` on `User`, this method would call `User#email` if the method is
-        # present.
-        #
-        # This method could be overwritten if the mapping between the `@object` and `key` name is not
-        # a method call. For example, a `Hash` would be accessed via `user[:email]` instead of `user.send(:email)`
-        def object_value_for(key:)
-          @object.send(key) if @object.respond_to? key
-        end
-
-        private
-
-        # Checks if the child exists. If it does then it returns that. If it doesn't, it will
-        # build the child.
-        def create_child(key, child_class, **kwargs, &block)
-          @children.fetch(key) { @children[key] = child_class.new(key, parent: self, **kwargs, &block) }
-        end
-      end
-    end
-  end
-end

data/lib/phlexi/display/structure/namespace_collection.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module Phlexi
-  module Display
-    module Structure
-      class NamespaceCollection < Node
-        include Enumerable
-
-        def initialize(key, parent:, collection: nil, &block)
-          raise ArgumentError, "block is required" unless block.present?
-
-          super(key, parent: parent)
-
-          @collection = collection
-          @block = block
-          each(&block)
-        end
-
-        def extract_input(params)
-          namespace = build_namespace(0)
-          @block.call(namespace)
-
-          inputs = params[key].map { |param| namespace.extract_input([param]) }
-          {key => inputs}
-        end
-
-        private
-
-        def each(&)
-          namespaces.each(&)
-        end
-
-        # Builds and memoizes namespaces for the collection.
-        #
-        # @return [Array<Hash>] An array of namespace hashes.
-        def namespaces
-          @namespaces ||= @collection.map.with_index do |object, key|
-            build_namespace(key, object: object)
-          end
-        end
-
-        def build_namespace(index, **)
-          parent.class.new(index, parent: self, builder_klass: parent.builder_klass, **)
-        end
-      end
-    end
-  end
-end