phlexi-display 0.0.1

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

@@ -0,0 +1,236 @@
+# 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

@@ -0,0 +1,54 @@
+# 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

@@ -0,0 +1,135 @@
+# 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

@@ -0,0 +1,48 @@
+# 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

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Display
+    module Structure
+      # Superclass for Namespace and Field classes. Not much to it other than it has a `name`
+      # and `parent` node attribute. Think of it as a tree.
+      class Node
+        attr_reader :key, :parent
+
+        def initialize(key, parent:)
+          @key = key.to_s.to_sym
+          @parent = parent
+        end
+      end
+    end
+  end
+end

data/lib/phlexi/display/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Display
+    VERSION = "0.0.1"
+  end
+end

data/lib/phlexi/display.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "phlex"
+require "active_support/core_ext/object/blank"
+
+module Phlexi
+  module Display
+    Loader = Zeitwerk::Loader.new.tap do |loader|
+      loader.tag = File.basename(__FILE__, ".rb")
+      loader.inflector.inflect(
+        "phlexi-display" => "Phlexi",
+        "phlexi" => "Phlexi",
+        "dom" => "DOM"
+      )
+      loader.push_dir(File.expand_path("..", __dir__))
+      loader.ignore(File.expand_path("../generators", __dir__))
+      loader.setup
+    end
+
+    COMPONENT_BASE = (defined?(::ApplicationComponent) ? ::ApplicationComponent : Phlex::HTML)
+
+    NIL_VALUE = :__i_phlexi_display_nil_value_i__
+
+    class Error < StandardError; end
+  end
+end
+
+def Phlexi.Display(...)
+  Phlexi::Display::Base.new(...)
+end

data/lib/phlexi-display.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "phlexi/display"

data/sig/phlexi/display.rbs

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