phlexi-field 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ba4c98ff7c81ff95503b3045f7564f86e91a529789a4408d51e100e764d91e8
-  data.tar.gz: 940a9ff9e19deb86247956307e8903f24f3ce54691646742fb36e5394fe39b53
+  metadata.gz: 23043c21dcd13b30389b9abde3064b5ad3cd6e3a3d113632812b08a81146e50d
+  data.tar.gz: 807e164c121afec7d2cfc376f1d09b9bed972d3adf8cfef73774ee95b48cd3e4
 SHA512:
-  metadata.gz: 780d445e6b6e4501c89c6030c46a405858ff6dfc2de75c5d2cec398309152bdfdd65536f09fe736ac0dd31f284b86db3f8405e6943e414aa9566d2bef162d8c8
-  data.tar.gz: b5371cb3beb7e43475a68e704e53558191c469cc2f5f80156e0db8ce5be2cd435d012fd14c6b9f74683b7d60a5c9cb23d46ef532f0623fde1677ba3937239366
+  metadata.gz: bb81612c85d3d0bca6391940735150391e53c6a40208791142ba97dff7bb35257a7bfa02bf5d908025758e2b6f62c20635299170c9ebfbabc9b52b2ae19d00e9
+  data.tar.gz: 1a0c409e68029ba5b702ad3642f7e2f8720ccbfcbe5ea25564a72e3759ac91dabb46fd8b7588fb3bb1b7e0c5ee1c3c2a9e11fa56003afe2852a0f0d12a5aa7c9

data/.standard.yml

@@ -0,0 +1,2 @@
+ignore:
+  - 'gemfiles/**/*'

data/Appraisals

@@ -1,8 +1,17 @@
+# frozen_string_literal: true
+
 appraise "default" do
-  # gem "phlex", "~> 1.10"
+  # Default dependencies
 end
 
-appraise "rails-7" do
-  gem "rails", "~> 7.1.3", ">= 7.1.3.4"
+appraise "rails-7.1" do
+  gem "rails", "~> 7.1.3", ">= 7.1.3.4", "< 8.0.0"
   gem "sqlite3", "~> 1.4"
+  gem "phlex-rails", "~> 2.2"
+end
+
+appraise "rails-8" do
+  gem "rails", "~> 8.0.0"
+  gem "sqlite3", "~> 2.1"
+  gem "phlex-rails", "~> 2.2"
 end

data/README.md

@@ -1,195 +1,334 @@
-# Phlexi::Form 
+# Phlexi::Field
 
-Phlexi::Form is a flexible and powerful form builder for Ruby applications. It provides a more customizable and extensible way to create forms compared to traditional form helpers.
+[![Gem Version](https://badge.fury.io/rb/phlexi-field.svg)](https://badge.fury.io/rb/phlexi-field)
+[![CI](https://github.com/radioactive-labs/phlexi-field/actions/workflows/main.yml/badge.svg)](https://github.com/radioactive-labs/phlexi-field/actions/workflows/main.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[![Ruby](https://github.com/radioactive-labs/phlexi-form/actions/workflows/main.yml/badge.svg)](https://github.com/radioactive-labs/phlexi-form/actions/workflows/main.yml)
+Phlexi::Field is a field component framework for Ruby applications that provides a unified field abstraction across forms, displays, and tables. Built on a namespace-based architecture for handling complex object relationships.
+It's designed to work with [Phlex](https://github.com/phlex-ruby/phlex), a framework for building view components in Ruby.
 
-## Features
+## Design Philosophy & Purpose
 
-- Customizable form components (input, select, checkbox, radio button, etc.)
-- Automatic field type and attribute inference based on model attributes
-- Built-in support for validations and error handling
-- Flexible form structure with support for nested attributes
-- Works with Phlex or erb views
-- Extract input from parameters that match your form definition. No need to strong paramters.
-- Rails compatible form inputs
+Phlexi::Field serves as the foundation for field rendering across multiple contexts in web applications. Unlike traditional form builders that focus solely on forms, Phlexi::Field creates a unified abstraction for working with fields that can be used for:
 
+- Form inputs
+- Read-only displays
+- Table columns
+- Any other UI context where object fields are presented
+
+It is designed around a **namespace-based architecture** that creates a hierarchical tree structure for complex object graphs, handling nested relationships and collections gracefully.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'phlexi-form'
+gem 'phlexi-field'
 ```
 
 And then execute:
 
-```
+```bash
 $ bundle install
 ```
 
 Or install it yourself as:
 
-```
-$ gem install phlexi-form
+```bash
+$ gem install phlexi-field
 ```
 
-## Usage
+## Requirements
+
+- Ruby >= 3.2.2
+- Phlex ~> 2.0
+- ActiveSupport >= 7.1
 
-There are 2 ways to use Phlexi::Form:
+## Core Architecture
 
-### Direct Usage
+### Namespace Pattern
+
+The foundation of Phlexi::Field is the `Namespace` concept:
+
+1. A Namespace maps an object (like an ActiveRecord model) to a key
+2. Fields are created within a namespace
+3. Namespaces can be nested to represent complex object relationships
 
 ```ruby
-Phlexi::Form(User.new) do
-  field(:name) do |name|
-    render name.label_tag
-    render name.input_tag
-  end
+# Create a root namespace for a user object
+namespace = Phlexi::Field::Structure::Namespace.new(
+  :user,                           # The key/name 
+  parent: nil,                     # Root namespace has no parent
+  builder_klass: Phlexi::Field::Builder,  # Field builder class
+  object: @user                    # The data object
+)
+
+# Create a field within the namespace
+email_field = namespace.field(:email)
+
+# Access field properties
+email_field.dom.id      # => "user_email"
+email_field.dom.name    # => "user[email]"
+email_field.value       # => The email value from @user
+```
 
-  field(:email) do |email|
-    render email.label_tag
-    render email.input_tag
-  end
+### Nested Objects and Collections
 
-  nest_one(:address) do |address|
-    address.field(:street) do |street|
-      render street.label_tag
-      render street.input_tag
-    end
+One of Phlexi::Field's strengths is handling complex object graphs:
 
-    address.field(:city) do |city|
-      render city.label_tag
-      render city.input_tag
-    end
-  end
+```ruby
+# For a has_one relationship
+namespace.nest_one(:profile) do |profile|
+  first_name = profile.field(:first_name)
+  # DOM properties: id="user_profile_first_name", name="user[profile][first_name]"
+end
 
-  render submit_button
+# For a has_many relationship
+namespace.nest_many(:addresses) do |address_builder|
+  street = address_builder.field(:street)
+  # DOM properties: id="user_addresses_street", name="user[addresses][][street]"
 end
 ```
 
-> **Important**
->
-> If you are rendering your form inline e.g. 
-> ```ruby
-> render Phlexi::Form(User.new) {
->   render field(:name).label_tag
->   render field(:name).input_tag
-> }
-> ```
->
-> Make sure you use `{...}` in defining your block instead of `do...end`
-> This might be fixed in a future version.
+### Field Builders and Components
+
+Phlexi::Field separates field creation from rendering:
+
+- `Builder` classes handle field creation, value access, and configuration
+- `Component` classes handle presentation and rendering
+
+This separation allows the same field structure to be rendered differently in various contexts.
+
+## Field Configuration Options
+
+Phlexi::Field provides a rich set of options for configuring how fields are displayed and behave:
+
+### Labels
+
+Labels can be explicitly set or automatically generated from the object's attribute name:
+
+```ruby
+# Custom label
+field = namespace.field(:email, label: "Email Address")
+
+# Get the current label (automatically falls back to humanized attribute name)
+field.label  # => "Email Address" or "Email" if not explicitly set
+
+# Rails integration: Uses human_attribute_name if available
+# user.class.human_attribute_name(:email) => "Email Address"
+```
+
+### Hints and Descriptions
 
-### Inherit form
+Hints provide contextual help for users, while descriptions offer more detailed explanations:
 
 ```ruby
-class UserForm < Phlexi::Form::Base
-  def form_template
-    field(:name) do |name|
-      render name.label_tag
-      render name.input_tag
-    end
+# Setting a hint for a field
+field = namespace.field(:password, hint: "Must be at least 8 characters")
+field.hint  # => "Must be at least 8 characters"
+field.has_hint?  # => true
+
+# Setting a description
+field = namespace.field(:terms_accepted, 
+                      description: "By accepting our terms, you agree to our privacy policy.")
+field.description  # => "By accepting our terms, you agree to our privacy policy."
+field.has_description?  # => true
+```
 
-    field(:email) do |email|
-      render email.label_tag
-      render email.input_tag
-    end
+### Placeholders
 
-    nest_one(:address) do |address|
-      address.field(:street) do |street|
-        render street.label_tag
-        render street.input_tag
-      end
+Text placeholders can be set for input fields:
 
-      address.field(:city) do |city|
-        render city.label_tag
-        render city.input_tag
-      end
-    end
+```ruby
+field = namespace.field(:email, placeholder: "john@example.com")
+field.placeholder  # => "john@example.com"
+```
 
-    render submit_button
-  end
-end
+### Type Inference
+
+Phlexi::Field automatically infers the appropriate field type based on multiple signals:
+
+```ruby
+# Based on attribute/column type in ActiveRecord/ActiveModel
+# email_field.inferred_field_type  # => :string, :integer, :boolean, etc.
+
+# For string fields, it can also infer more specific types
+# email_field.inferred_string_field_type  # => :email, :password, :url, etc. 
+```
+
+The type inference algorithm considers:
+1. ActiveRecord column types
+2. ActiveModel attribute types  
+3. Value type inspection
+4. Field name conventions (email, password, url, etc.)
+5. Validation rules (email format, numericality, etc.)
+
+### Validators
+
+When using ActiveModel validations, Phlexi::Field can access them:
+
+```ruby
+# Check if a field is required based on presence validators
+field.required?  # => true/false based on presence validators
 
+# Access the validation errors
+field.errors  # => ["can't be blank", etc.]
+```
 
-# In your view or controller
-form = UserForm.new(User.new)
+### Multiple Options
 
-# Render the form
-render form
+For fields that support multiple selections:
 
-# Extract params
-form.extract_input({
-  name: "Brad Pitt",
-  email: "brad@pitt.com",
-  address: {
-    street: "Plumbago",
-    city: "Accra",
-  }
-})
+```ruby
+field = namespace.field(:categories, multiple: true)
+field.multiple?  # => true
 ```
 
-## Advanced Usage
+## Usage
+
+Phlexi::Field provides a foundation for building components that handle object fields such as forms and other UI components. It handles DOM structure, field values, configuration of labels, descriptions, hints, and more.
 
-### Custom Components
+It serves as a foundation for [Phlexi::Form](https://github.com/radioactive-labs/phlexi-form), [Phlexi::Display](https://github.com/radioactive-labs/phlexi-display) and [Phlexi::Table](https://github.com/radioactive-labs/phlexi-table).
 
-You can create custom form components by inheriting from `Phlexi::Form::Components::Base`:
+### Basic Example
 
 ```ruby
-class CustomInput < Phlexi::Form::Components::Base
+class UserForm < Phlex::HTML
+  def initialize(user)
+    super()
+    @user = user
+  end
+  
   def view_template
-    div(class: "custom-input") do
-      input(**attributes)
-      span(class: "custom-icon")
+    namespace = Phlexi::Field::Structure::Namespace.new(
+      :user, 
+      parent: nil, 
+      builder_klass: Phlexi::Field::Builder, 
+      object: @user
+    )
+    
+    form(action: "/users", method: "post") do
+      # Create a name field
+      name_field = namespace.field(:name)
+      label(for: name_field.dom.id) { name_field.label }
+      input(
+        id: name_field.dom.id, 
+        name: name_field.dom.name, 
+        value: name_field.value, 
+        type: "text"
+      )
+      
+      # Create an email field
+      email_field = namespace.field(:email)
+      label(for: email_field.dom.id) { email_field.label }
+      input(
+        id: email_field.dom.id, 
+        name: email_field.dom.name, 
+        value: email_field.value, 
+        type: "email"
+      )
+      
+      # Submit button
+      button(type: "submit") { "Submit" }
     end
   end
 end
 
-# Usage in your form
-field(:custom_field) do |field|
-  render CustomInput.new(field)
+# Usage in a controller
+def new
+  user = User.new
+  render UserForm.new(user)
 end
 ```
 
-### Theming
+### Nested Forms
 
-Phlexi::Form supports theming through a flexible theming system:
+Phlexi::Field supports nested forms for complex data structures:
 
 ```ruby
-class ThemedForm < Phlexi::Form::Base
-  class FieldBuilder < FieldBuilder
-    private
-    
-    def default_theme
-      {
-        input: "border rounded px-2 py-1",
-        label: "font-bold text-gray-700",
-        # Add more theme options here
-      }
-    end
-  end
+# For a has_one relationship
+namespace.nest_one(:profile) do |profile|
+  profile.field(:first_name) # => Creates a field for user[profile][first_name]
 end
+
+# For a has_many relationship
+namespace.nest_many(:addresses) do |address_builder|
+  address_field = address_builder.field(:id)
+  # Creates fields like user[addresses][][id]
+end
+```
+
+### Field Options
+
+Fields support various options for customization:
+
+```ruby
+# Custom label
+field = namespace.field(:email, label: "Email Address")
+
+# Required fields
+field = namespace.field(:email, required: true)
+
+# Placeholder text
+field = namespace.field(:email, placeholder: "Enter your email")
+
+# Description/hint text
+field = namespace.field(:password, hint: "Must be at least 8 characters")
 ```
 
-<!-- ## Configuration
+## Components
 
-You can configure Phlexi::Form globally by creating an initializer:
+Phlexi::Field comes with a base component architecture that you can extend:
 
 ```ruby
-# config/initializers/phlexi_form.rb
-Phlexi::Form.configure do |config|
-  config.default_theme = {
-    # Your default theme options
-  }
-  # Add more configuration options here
+class MyInputComponent < Phlexi::Field::Components::Base
+  def view_template
+    input(
+      id: field.dom.id,
+      name: field.dom.name,
+      value: field.value,
+      type: "text",
+      **attributes
+    )
+  end
 end
-``` -->
+
+# Usage
+my_component = MyInputComponent.new(field, class: "custom-input")
+render my_component
+```
+
+## Comparison with Other Libraries
+
+Phlexi::Field differs from traditional Rails form helpers and gems like Simple Form in several key ways:
+
+1. **Unified Field API**: Creates a consistent interface for fields across forms, displays, and tables
+2. **Component-Based**: Built on Phlex's component system rather than Rails' helper-based approach
+3. **Separation of Concerns**: Cleanly separates field structure (namespace), data handling (builder), and presentation (components)
+4. **True Object Orientation**: Works with complete objects and their relationships rather than flat attribute lists
+
+## Integration with Rails
+
+While Phlexi::Field works standalone with Phlex, it has first-class support for Rails:
+
+```ruby
+# In your Gemfile
+gem 'phlexi-field'
+gem 'phlex-rails'
+```
+
+The library automatically uses Rails conventions when available:
+- Humanized attribute names via `human_attribute_name`
+- Association detection via `reflect_on_association`
+- Primary key handling
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/radioactive-labs/phlexi-form.
+Bug reports and pull requests are welcome on GitHub at https://github.com/radioactive-labs/phlexi-field.
 
 ## License
 

data/Rakefile

@@ -3,6 +3,7 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
 require "standard/rake"
+require "appraisal"
 
 task default: %i[test standard]
 
@@ -12,3 +13,31 @@ Rake::TestTask.new do |t|
   t.test_files = FileList["test/**/*_test.rb"]
   t.verbose = true
 end
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+namespace :test do
+  desc "Run core tests that don't depend on Rails"
+  Rake::TestTask.new(:core) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/phlexi/field/**/*_test.rb"].exclude("test/phlexi/rails/**/*_test.rb")
+  end
+
+  desc "Run Rails integration tests"
+  Rake::TestTask.new(:rails) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/phlexi/rails/**/*_test.rb"]
+  end
+end
+
+desc "Run tests across all appraisals"
+task :test_all do
+  sh "bundle exec appraisal install"
+  sh "bundle exec appraisal test"
+end

data/gemfiles/default.gemfile

@@ -2,4 +2,11 @@
 
 source "https://rubygems.org"
 
+gem "rails", "~> 7.1"
+gem "sqlite3", "~> 1.4"
+
+platforms :ruby, :x86_64_linux, :arm64_darwin do
+
+end
+
 gemspec path: "../"