phlexi-field 0.0.1

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Field
+    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 outside of or 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
+
+        # 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/field/structure/field_collection.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Field
+    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 = build_collection(collection)
+          each(&) if block_given?
+        end
+
+        def each(&)
+          @collection.each.with_index do |item, index|
+            yield self.class::Builder.new(item, @field, index)
+          end
+        end
+
+        private
+
+        def build_collection(collection)
+          collection
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Field
+    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
+        # form like this:
+        #
+        # ```ruby
+        # Phlexi::Form(User.new, as: :user) do
+        #   nest_one :profile do |profile|
+        #     render profile.field(:gender).input_tag
+        #   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::Form(User.new) do
+        #   render field(:email).input_tag
+        #   render field(:name).input_tag
+        #   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
+
+        # 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:)
+          return @object.send(key) if @object.respond_to?(key)
+          @object.fetch(key) if @object.is_a?(Hash)
+        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/field/structure/namespace_collection.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Field
+    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
+
+        private
+
+        def each(&)
+          namespaces.each(&)
+        end
+
+        # Builds and memoizes namespaces for the collection.
+        #
+        # @return [Array<Namespace>] An array of namespace objects.
+        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/field/structure/node.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Phlexi
+  module Field
+    module Structure
+      # Superclass for Namespace and Field classes. Represents a node in the field tree structure.
+      #
+      # @attr_reader [Symbol] key The node's key
+      # @attr_reader [Node, nil] parent The node's parent in the tree structure
+      class Node
+        attr_reader :key, :parent
+
+        # Initializes a new Node instance.
+        #
+        # @param key [Symbol, String] The key for the node
+        # @param parent [Node, nil] The parent node
+        def initialize(key, parent:)
+          @key = :"#{key}"
+          @parent = parent
+        end
+
+        def inspect
+          "<#{self.class.name} key=#{key.inspect} parent=#{id.inspect} />"
+        end
+      end
+    end
+  end
+end

data/lib/phlexi/field/theme.rb

@@ -0,0 +1,61 @@
+require "fiber/local"
+
+module Phlexi
+  module Field
+    module Theme
+      extend ActiveSupport::Concern
+
+      included do
+        extend Fiber::Local
+      end
+
+      # Retrieves the theme hash
+      #
+      # 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, allowing for a flexible and inheritance-based theming system.
+      #
+      # @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
+      def theme
+        raise NotImplementedError, "#{self.class} must implement #theme"
+      end
+
+      # 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 Basic usage
+      #   # Assuming the theme is: { text: "text-gray-700", email: :text }
+      #   themed(:text)
+      #   # => "text-gray-700 text-sm"
+      #
+      # @example Cascading themes
+      #   # Assuming the theme is: { text: "text-gray-700", email: :text }
+      #   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
+    end
+  end
+end

data/lib/phlexi/field/version.rb

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

data/lib/phlexi/field.rb

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

data/lib/phlexi-field.rb

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

data/sig/phlexi/field.rbs

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

metadata

@@ -0,0 +1,247 @@
+--- !ruby/object:Gem::Specification
+name: phlexi-field
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Stefan Froelich
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-09-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: phlex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: fiber-local
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundle-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: combustion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: phlex-testing-capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Base fields for the Phlexi libraries
+email:
+- sfroelich01@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".ruby-version"
+- Appraisals
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODO
+- config.ru
+- gemfiles/default.gemfile
+- gemfiles/default.gemfile.lock
+- gemfiles/rails_7.gemfile
+- gemfiles/rails_7.gemfile.lock
+- lib/phlexi-field.rb
+- lib/phlexi/field.rb
+- lib/phlexi/field/builder.rb
+- lib/phlexi/field/components/base.rb
+- lib/phlexi/field/options/associations.rb
+- lib/phlexi/field/options/attachments.rb
+- lib/phlexi/field/options/descriptions.rb
+- lib/phlexi/field/options/hints.rb
+- lib/phlexi/field/options/inferred_types.rb
+- lib/phlexi/field/options/labels.rb
+- lib/phlexi/field/options/placeholders.rb
+- lib/phlexi/field/structure/dom.rb
+- lib/phlexi/field/structure/field_collection.rb
+- lib/phlexi/field/structure/namespace.rb
+- lib/phlexi/field/structure/namespace_collection.rb
+- lib/phlexi/field/structure/node.rb
+- lib/phlexi/field/theme.rb
+- lib/phlexi/field/version.rb
+- sig/phlexi/field.rbs
+homepage: https://github.com/radioactive-labs/phlexi-field
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/radioactive-labs/phlexi-field
+  source_code_uri: https://github.com/radioactive-labs/phlexi-field
+  changelog_uri: https://github.com/radioactive-labs/phlexi-field
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Base fields for the Phlexi libraries
+test_files: []