phlexi-display 0.0.1

data/lib/phlexi/display/field_options/themes.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Display
+    module FieldOptions
+      module Themes
+        # Resolves theme classes for components based on their type and the validity state of the field.
+        #
+        # This method is responsible for determining the appropriate CSS classes for a given form component.
+        # It considers both the base theme for the component type and any additional theming based on the
+        # component's validity state (valid, invalid, or neutral). The method supports a hierarchical
+        # theming system, allowing for cascading themes and easy customization.
+        #
+        # @param component [Symbol, String] The type of form component (e.g., :input, :label, :wrapper)
+        #
+        # @return [String, nil] A string of CSS classes for the component, or nil if no theme is applied
+        #
+        # @example Basic usage
+        #   themed(:input)
+        #   # => "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700"
+        #
+        # @example Usage with validity state
+        #   # Assuming the field has errors
+        #   themed(:input)
+        #   # => "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700 bg-red-50 border-red-500 text-red-900"
+        #
+        # @example Cascading themes
+        #   # Assuming textarea inherits from input in the theme definition
+        #   themed(:textarea)
+        #   # => "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700"
+        #
+        # @note The actual CSS classes returned will depend on the theme definitions in the `theme` hash
+        #       and any overrides specified in the `options` hash.
+        #
+        # @see #resolve_theme
+        # @see #resolve_validity_theme
+        # @see #theme
+        def themed(component)
+          return unless component
+
+          tokens(resolve_theme(component), resolve_validity_theme(component)).presence
+        end
+
+        protected
+
+        # Recursively resolves the theme for a given property, handling nested symbol references
+        #
+        # @param property [Symbol, String] The theme property to resolve
+        # @param visited [Set] Set of already visited properties to prevent infinite recursion
+        # @return [String, nil] The resolved theme value or nil if not found
+        #
+        # @example Resolving a nested theme
+        #   # Assuming the theme is: { input: :base_input, base_input: "some-class" }
+        #   resolve_theme(:input)
+        #   # => "some-class"
+        def resolve_theme(property, visited = Set.new)
+          return nil if !property.present? || visited.include?(property)
+          visited.add(property)
+
+          result = theme[property]
+          if result.is_a?(Symbol)
+            resolve_theme(result, visited)
+          else
+            result
+          end
+        end
+
+        # Resolves the theme for a component based on its current validity state
+        #
+        # This method determines the validity state of the field (valid, invalid, or neutral)
+        # and returns the corresponding theme by prepending the state to the component name.
+        #
+        # @param property [Symbol, String] The base theme property to resolve
+        # @return [String, nil] The resolved validity-specific theme or nil if not found
+        #
+        # @example Resolving a validity theme
+        #   # Assuming the field has errors and the theme includes { invalid_input: "error-class" }
+        #   resolve_validity_theme(:input)
+        #   # => "error-class"
+        def resolve_validity_theme(property)
+          validity_property = if has_errors?
+            :"invalid_#{property}"
+          elsif object_valid?
+            :"valid_#{property}"
+          else
+            :"neutral_#{property}"
+          end
+
+          resolve_theme(validity_property)
+        end
+
+        # Retrieves or initializes the theme hash for the form builder.
+        #
+        # This method returns a hash containing theme definitions for various form components.
+        # If a theme has been explicitly set in the options, it returns that. Otherwise, it
+        # initializes and returns a default theme.
+        #
+        # The theme hash defines CSS classes or references to other theme keys for different
+        # components and their states (e.g., valid, invalid, neutral).
+        #
+        # @return [Hash] A hash containing theme definitions for form components
+        #
+        # @example Accessing the theme
+        #   theme[:input]
+        #   # => "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700"
+        #
+        # @example Accessing a validity-specific theme
+        #   theme[:invalid_input]
+        #   # => "bg-red-50 border-red-500 text-red-900 placeholder-red-700 focus:ring-red-500 focus:border-red-500"
+        #
+        # @example Theme inheritance
+        #   theme[:textarea] # Returns :input, indicating textarea inherits input's theme
+        #   theme[:valid_textarea] # Returns :valid_input
+        #
+        # @note The actual content of the theme hash depends on the default_theme method
+        #       and any theme overrides specified in the options when initializing the field builder.
+        #
+        # @see #default_theme
+        def theme
+          @theme ||= options[:theme] || default_theme
+        end
+
+        # Defines and returns the default theme hash for the field builder.
+        #
+        # This method returns a hash containing the base theme definitions for various components.
+        # It sets up the default styling and relationships between different components and their states.
+        # The theme uses a combination of explicit CSS classes and symbolic references to other theme keys,
+        # allowing for a flexible and inheritance-based theming system.
+        #
+        # @return [Hash] A frozen hash containing default theme definitions for components
+        #
+        # @example Accessing the default theme
+        #   default_theme[:input]
+        #   # => nil (indicates that :input doesn't have a default and should be defined by the user)
+        #
+        # @example Theme inheritance
+        #   default_theme[:textarea]
+        #   # => :input (indicates that :textarea inherits from :input)
+        #
+        # @example Validity state theming
+        #   default_theme[:valid_textarea]
+        #   # => :valid_input (indicates that :valid_textarea inherits from :valid_input)
+        #
+        # @note This method returns a frozen hash to prevent accidental modifications.
+        #       To customize the theme, users should provide their own theme hash when initializing the field builder.
+        # @note Most theme values are set to nil or commented out in the default theme to encourage users
+        #       to define their own styles while maintaining the relationships between components and states.
+        #
+        # @see #theme
+        def default_theme
+          {
+            # # input
+            # input: nil,
+            # valid_input: nil,
+            # invalid_input: nil,
+            # neutral_input: nil,
+
+            # textarea
+            textarea: :input,
+            valid_textarea: :valid_input,
+            invalid_textarea: :invalid_input,
+            neutral_textarea: :neutral_input,
+
+            # select
+            select: :input,
+            valid_select: :valid_input,
+            invalid_select: :invalid_input,
+            neutral_select: :neutral_input,
+
+            # file
+            file: :input,
+            valid_file: :valid_input,
+            invalid_file: :invalid_input,
+            neutral_file: :neutral_input,
+
+            # misc
+            # label: nil,
+            # hint: nil,
+            # error: nil,
+            full_error: :error,
+            # wrapper: nil,
+            # inner_wrapper: nil,
+            submit_button: :button
+
+            # # label themes
+            # label: "md:w-1/6 mt-2 block mb-2 text-sm font-medium",
+            # invalid_label: "text-red-700 dark:text-red-500",
+            # valid_label: "text-green-700 dark:text-green-500",
+            # neutral_label: "text-gray-700 dark:text-white",
+            # # input themes
+            # input: "w-full p-2 border rounded-md shadow-sm font-medium text-sm dark:bg-gray-700",
+            # invalid_input: "bg-red-50 border-red-500 dark:border-red-500 text-red-900 dark:text-red-500 placeholder-red-700 dark:placeholder-red-500 focus:ring-red-500 focus:border-red-500",
+            # valid_input: "bg-green-50 border-green-500 dark:border-green-500 text-green-900 dark:text-green-400 placeholder-green-700 dark:placeholder-green-500 focus:ring-green-500 focus:border-green-500",
+            # neutral_input: "border-gray-300 dark:border-gray-600 dark:placeholder-gray-400 dark:text-white focus:ring-primary-500 focus:border-primary-500",
+            # # hint themes
+            # hint: "mt-2 text-sm text-gray-500 dark:text-gray-200",
+            # # error themes
+            # error: "mt-2 text-sm text-red-600 dark:text-red-500",
+            # # wrapper themes
+            # wrapper: "flex flex-col md:flex-row items-start space-y-2 md:space-y-0 md:space-x-2 mb-4",
+            # inner_wrapper: "md:w-5/6 w-full",
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/phlexi/display/field_options/validators.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Display
+    module FieldOptions
+      module Validators
+        private
+
+        def has_validators?
+          @has_validators ||= object.class.respond_to?(:validators_on)
+        end
+
+        def attribute_validators
+          object.class.validators_on(key)
+        end
+
+        def reflection_validators
+          reflection ? object.class.validators_on(reflection.name) : []
+        end
+
+        def valid_validator?(validator)
+          !conditional_validators?(validator) && action_validator_match?(validator)
+        end
+
+        def conditional_validators?(validator)
+          validator.options.include?(:if) || validator.options.include?(:unless)
+        end
+
+        def action_validator_match?(validator)
+          return true unless validator.options.include?(:on)
+
+          case validator.options[:on]
+          when :save
+            true
+          when :create
+            !object.persisted?
+          when :update
+            object.persisted?
+          end
+        end
+
+        def find_validator(kind)
+          attribute_validators.find { |v| v.kind == kind && valid_validator?(v) } if has_validators?
+        end
+      end
+    end
+  end
+end

data/lib/phlexi/display/option_mapper.rb

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

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