phlexi-table 0.0.1

data/lib/phlexi/table/field_options/inferred_types.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Phlexi
+  module Table
+    module FieldOptions
+      module InferredTypes
+        def inferred_db_type
+          @inferred_db_type ||= infer_db_type
+        end
+
+        def inferred_display_component
+          @inferred_display_component ||= infer_display_component
+        end
+
+        private
+
+        def infer_display_component
+          case inferred_db_type
+          when :string, :text
+            infer_string_display_type(key)
+          when :integer, :float, :decimal
+            :number
+          when :date, :datetime, :time
+            :date
+          when :boolean
+            :boolean
+          when :json, :jsonb, :hstore
+            :code
+          else
+            if association_reflection
+              :association
+            elsif attachment_reflection
+              :attachment
+            else
+              :text
+            end
+          end
+        end
+
+        def infer_db_type
+          if object.class.respond_to?(:columns_hash)
+            # ActiveRecord object
+            column = object.class.columns_hash[key.to_s]
+            return column.type if column
+          end
+
+          if object.class.respond_to?(:attribute_types)
+            # ActiveModel::Attributes
+            custom_type = object.class.attribute_types[key.to_s]
+            return custom_type.type if custom_type
+          end
+
+          # Check if object responds to the key
+          if object.respond_to?(key)
+            # Fallback to inferring type from the value
+            return infer_db_type_from_value(object.send(key))
+          end
+
+          # Default to string if we can't determine the type
+          :string
+        end
+
+        def infer_db_type_from_value(value)
+          case value
+          when Integer
+            :integer
+          when Float
+            :float
+          when BigDecimal
+            :decimal
+          when TrueClass, FalseClass
+            :boolean
+          when Date
+            :date
+          when Time, DateTime
+            :datetime
+          when Hash
+            :json
+          else
+            :string
+          end
+        end
+
+        def infer_string_display_type(key)
+          key = key.to_s.downcase
+
+          return :password if is_password_field?
+
+          custom_type = custom_string_display_type(key)
+          return custom_type if custom_type
+
+          :text
+        end
+
+        def custom_string_display_type(key)
+          custom_mappings = {
+            /url$|^link|^site/ => :url,
+            /^email/ => :email,
+            /phone|tel(ephone)?/ => :phone,
+            /^time/ => :time,
+            /^date/ => :date,
+            /^number|_count$|_amount$/ => :number,
+            /^color/ => :color
+          }
+
+          custom_mappings.each do |pattern, type|
+            return type if key.match?(pattern)
+          end
+
+          nil
+        end
+
+        def is_password_field?
+          key = self.key.to_s.downcase
+
+          exact_matches = ["password"]
+          prefixes = ["encrypted_"]
+          suffixes = ["_password", "_digest", "_hash"]
+
+          exact_matches.include?(key) ||
+            prefixes.any? { |prefix| key.start_with?(prefix) } ||
+            suffixes.any? { |suffix| key.end_with?(suffix) }
+        end
+      end
+    end
+  end
+end

data/lib/phlexi/table/field_options/labels.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Table
+    module FieldOptions
+      module Labels
+        def label(label = nil)
+          if label.nil?
+            options[:label] = options.fetch(:label) { calculate_label }
+          else
+            options[:label] = label
+            self
+          end
+        end
+
+        private
+
+        def calculate_label
+          if object.class.respond_to?(:human_attribute_name)
+            object.class.human_attribute_name(key.to_s, {base: object})
+          else
+            key.to_s.humanize
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phlexi/table/field_options/placeholders.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Table
+    module FieldOptions
+      module Placeholders
+        def placeholder(placeholder = nil)
+          if placeholder.nil?
+            options[:placeholder] || "-"
+          else
+            options[:placeholder] = placeholder
+            self
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Table
+    module FieldOptions
+      module Themes
+        # Resolves theme classes for components based on their type.
+        #
+        # This method is responsible for determining the appropriate CSS classes for a given display component.
+        # It supports a hierarchical theming system, allowing for cascading themes and easy customization.
+        #
+        # @param component [Symbol, String] The type of display component (e.g., :text, :date, :boolean)
+        #
+        # @return [String, nil] A string of CSS classes for the component, or nil if no theme is applied
+        #
+        # @example Basic usage
+        #   themed(:text)
+        #   # => "text-gray-700 text-sm"
+        #
+        # @example Cascading themes
+        #   # Assuming email inherits from text in the theme definition
+        #   themed(:email)
+        #   # => "text-gray-700 text-sm text-blue-600 underline"
+        #
+        # @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 #theme
+        def themed(component)
+          return unless component
+
+          resolve_theme(component)
+        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: { email: :text, text: "text-gray-700" }
+        #   resolve_theme(:email)
+        #   # => "text-gray-700"
+        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
+
+        # Retrieves or initializes the theme hash for the display builder.
+        #
+        # This method returns a hash containing theme definitions for various display 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.
+        #
+        # @return [Hash] A hash containing theme definitions for display components
+        #
+        # @example Accessing the theme
+        #   theme[:text]
+        #   # => "text-gray-700 text-sm"
+        #
+        # @example Theme inheritance
+        #   theme[:email] # Returns :text, indicating email inherits text's theme
+        #
+        # @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 display 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.
+        # 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[:text]
+        #   # => "text-gray-700 text-sm"
+        #
+        # @example Theme inheritance
+        #   default_theme[:email]
+        #   # => :text (indicates that :email inherits from :text)
+        #
+        # @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 display builder.
+        #
+        # @see #theme
+        def default_theme
+          {
+            label: "text-base font-bold text-gray-500 dark:text-gray-400 mb-1",
+            description: "text-sm text-gray-400 dark:text-gray-500",
+            placeholder: "text-xl font-semibold text-gray-500 dark:text-gray-300 mb-1 italic",
+            string: "text-xl font-semibold text-gray-900 dark:text-white mb-1",
+            # text: :string,
+            number: :string,
+            datetime: :string,
+            # boolean: :string,
+            # code: :string,
+            # email: :text,
+            # url: :text,
+            # phone: :text,
+            # color: :text,
+            # search: :text,
+            # password: :string,
+            # association: :string,
+            attachment: :string,
+            wrapper: nil
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Table
+    module Structure
+      # Generates DOM IDs for a Field, Namespace, or Node based on
+      # norms that were established by Rails. These can be used outside of Rails in
+      # other Ruby web frameworks since it has no 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 display.
+        def value
+          @field.value.to_s
+        end
+
+        # Walks from the current node to the parent node, grabs the names, and separates
+        # 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
+
+        # 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 and value in an HTML tag-ish that doesn't have an element.
+        def inspect
+          "<#{self.class.name} id=#{id.inspect} value=#{value.inspect}/>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "phlex"
+
+module Phlexi
+  module Table
+    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::Themes
+        include FieldOptions::Associations
+        include FieldOptions::Attachments
+        include FieldOptions::InferredTypes
+        include FieldOptions::Labels
+        include FieldOptions::Placeholders
+        include FieldOptions::Description
+        # include FieldOptions::Hints
+
+        attr_reader :dom, :options, :object, :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 options [Hash] Additional options for the field.
+        def initialize(key, parent:, object: nil, value: NIL_VALUE, **options)
+          super(key, parent: parent)
+
+          @object = object
+          @value = determine_value(value)
+          @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(**, &)
+          create_component(Components::Label, :label, **, &)
+        end
+
+        # Creates a Placeholder tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the placeholder.
+        # @return [Components::Placeholder] The placeholder component.
+        def placeholder_tag(**, &)
+          create_component(Components::Placeholder, :placeholder, **, &)
+        end
+
+        # Creates a Description tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the description.
+        # @return [Components::Description] The description component.
+        def description_tag(**, &)
+          create_component(Components::Description, :description, **, &)
+        end
+
+        # Creates a string display tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the string display.
+        # @return [Components::String] The string component.
+        def string_tag(**, &)
+          create_component(Components::String, :string, **, &)
+        end
+
+        # # Creates a text display tag for the field.
+        # #
+        # # @param attributes [Hash] Additional attributes for the text display.
+        # # @return [Components::Text] The text component.
+        # def text_tag(**, &)
+        #   create_component(Components::Text, :text, **, &)
+        # end
+
+        # Creates a number display tag for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the number display.
+        # @return [Components::Number] The number component.
+        def number_tag(**, &)
+          create_component(Components::Number, :number, **, &)
+        end
+
+        # Creates a datetime display for the field.
+        #
+        # @param attributes [Hash] Additional attributes for the datetime display.
+        # @return [Components::DateTime] The datetime component.
+        def datetime_tag(**, &)
+          create_component(Components::DateTime, :datetime, **, &)
+        end
+
+        # # Creates a boolean display tag for the field.
+        # #
+        # # @param attributes [Hash] Additional attributes for the boolean display.
+        # # @return [Components::Boolean] The boolean component.
+        # def boolean_tag(**, &)
+        #   create_component(Components::Boolean, :boolean, **, &)
+        # end
+
+        # # Creates an association display tag for the field.
+        # #
+        # # @param attributes [Hash] Additional attributes for the association display.
+        # # @return [Components::Association] The association component.
+        # def association_tag(**, &)
+        #   create_component(Components::Association, :association, **, &)
+        # end
+
+        # # Creates an attachment display tag for the field.
+        # #
+        # # @param attributes [Hash] Additional attributes for the attachment display.
+        # # @return [Components::Attachment] The attachment component.
+        # def attachment_tag(**, &)
+        #   create_component(Components::Attachment, :attachment, **, &)
+        # end
+
+        # Wraps the field with additional markup.
+        #
+        # @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(**, &)
+          create_component(Components::Wrapper, :wrapper, **, &)
+        end
+
+        # Creates a repeated field collection.
+        #
+        # @param range [#each] The collection of items to generate displays for.
+        # @yield [block] The block to be executed for each item in the collection.
+        # @return [FieldCollection] The field collection.
+        def repeated(collection = [], &)
+          FieldCollection.new(field: self, collection:, &)
+        end
+
+        protected
+
+        def create_component(component_class, theme_key, **attributes, &)
+          theme_key = attributes.delete(:theme) || theme_key
+          attributes = mix({class: themed(theme_key)}, attributes) unless attributes.key?(:class!)
+          component_class.new(self, **attributes, &)
+        end
+
+        def determine_value(value)
+          return value unless value == NIL_VALUE
+
+          object.respond_to?(key) ? object.public_send(key) : nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Table
+    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, **, parent: @field).tap do |field|
+              yield field if block_given?
+            end
+          end
+        end
+
+        def initialize(field:, collection:, &)
+          @field = field
+          @collection = collection
+          each(&) if block_given?
+        end
+
+        def each(&)
+          @collection.each.with_index do |item, index|
+            yield Builder.new(item, @field, index)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Table
+    module Structure
+      # A Namespace maps an 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 single values on a Namespace, #field can be used.
+      #
+      # To access nested objects within a namespace, two methods are available:
+      #
+      # 1. #nest_one: Used for single nested objects, such as if a `User belongs_to :profile` in
+      #    ActiveRecord. This method returns another Namespace object.
+      #
+      # 2. #nest_many: Used for collections of nested objects, such as if a `User has_many :addresses` in
+      #    ActiveRecord. This method returns a NamespaceCollection object.
+      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
+
+        # 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
+        # display like this:
+        #
+        # ```ruby
+        # Phlexi::Table(user) do |display|
+        #   display.nest_one :profile do |profile|
+        #     render profile.field(:gender).text
+        #   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::Table(user) do |display|
+        #   render display.field(:email).text
+        #   render display.field(:name).text
+        #   display.nest_many :addresses do |address|
+        #     render address.field(:street).text
+        #     render address.field(:state).text
+        #     render address.field(:zip).text
+        #   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
+
+        # 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
+        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