polaris_form_builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d6bcd0b60a0df4d1edc4b00f89144a17eab765a8d51e3374abc4fc37c4dbc8a5
+  data.tar.gz: d641170ee84b65b7cfc22852674fedc102d86629128a5945b90d03a851095a09
+SHA512:
+  metadata.gz: 65edcb87ea84066e95edcf7a52286b54a98135b97b82aa44c8b9fcb245dae6ba36f4e9bf40bbefa6bb33f9e923fa861ca63d9e70807a7bc4978a4cd0f751380e
+  data.tar.gz: 2a6a77e9e8582b672e6bef9386bf9ff4e0ce838365e993f91168cae34a3ad72e7c8dc13acfe4daba6dd0afc7454edec722774ee0282cec2e95d5257d7570fcea

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Lex Cao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,140 @@
+# PolarisFormBuilder
+
+Use Shopify Polaris Web Components as a Rails form builder, while keeping Rails form semantics.
+
+- Polaris Web Components docs: https://shopify.dev/docs/api/app-home/polaris-web-components
+
+## What This Gem Does
+
+- Provides `PolarisFormBuilder::FormBuilder` as a drop-in Rails form builder.
+- Provides `polaris_form_with` for explicit per-form opt-in.
+- Integrates via Rails Engine so helpers are available in ActionView.
+- Maps model validation errors to Polaris component `error` attributes.
+- Preserves Rails helper behavior (`name`, `value`, `checked`, etc.) by building on top of `super`.
+
+## Requirements
+
+- Ruby `>= 3.1.0`
+- Rails app using `form_with` / `ActionView::Helpers::FormBuilder`
+
+## Installation
+
+```bash
+bundle add polaris_form_builder
+bundle install
+```
+
+## Usage
+
+### Recommended: Opt in per form
+
+```erb
+<%= polaris_form_with model: @user do |f| %>
+  <%= f.text_field :email, placeholder: "Enter email" %>
+  <%= f.password_field :password %>
+  <%= f.text_area :bio %>
+  <%= f.check_box :agree_terms %>
+  <%= f.submit "Create Account" %>
+<% end %>
+```
+
+### Global default builder
+
+```ruby
+# config/application.rb (or environment files)
+config.action_view.default_form_builder = PolarisFormBuilder::FormBuilder
+```
+
+Then regular `form_with` will use Polaris components automatically.
+
+```erb
+<%= form_with model: @user do |f| %>
+  <%= f.text_field :email %>
+  <%= f.password_field :password %>
+  <%= f.submit %>
+<% end %>
+```
+
+## Supported Helpers
+
+### Core Rails-style fields
+
+- `text_field`
+- `number_field`
+- `email_field`
+- `password_field`
+- `url_field`
+- `search_field`
+- `color_field`
+- `date_field`
+- `file_field` (`drop_zone` alias)
+- `text_area`
+- `check_box`
+- `select`
+- `submit`
+
+### Polaris-oriented helpers
+
+- `drop_zone`
+- `money_field`
+- `color_picker`
+- `date_picker`
+- `switch`
+- `choice_list`
+
+## Validation Error Mapping
+
+When your model has errors, corresponding Polaris components receive `error` automatically.
+
+```ruby
+class User < ApplicationRecord
+  validates :email, presence: true
+end
+```
+
+```erb
+<%= polaris_form_with model: @user do |f| %>
+  <%= f.text_field :email %>
+<% end %>
+```
+
+If `@user.errors[:email]` is present, the rendered Polaris field gets an `error` attribute.
+
+## Development
+
+```bash
+bin/setup
+bin/rubocop
+rake test
+bin/ci
+```
+
+Useful commands:
+
+```bash
+rake test_unit
+rake test_integration
+rake test_playground
+bin/console
+```
+
+## Release
+
+1. Update `lib/polaris_form_builder/version.rb`.
+2. Update `CHANGELOG.md`.
+3. Run `bin/ci`.
+4. Publish:
+
+```bash
+bundle exec rake release
+```
+
+## Contributing
+
+Issues and pull requests are welcome:
+
+This project follows the Contributor Covenant Code of Conduct.
+
+## License
+
+Released under MIT. See `LICENSE.txt`.

data/lib/polaris_form_builder/form_builder.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "action_view"
+require_relative "tag"
+
+module PolarisFormBuilder
+  class FormBuilder < ActionView::Helpers::FormBuilder
+    include ActionView::Helpers::FormTagHelper
+
+    # Generate input field methods with identical structure
+    # Maps Rails helper name to Polaris component tag
+    {
+      text_field: "s-text-field",
+      number_field: "s-number-field",
+      email_field: "s-email-field",
+      password_field: "s-password-field",
+      url_field: "s-url-field",
+      search_field: "s-search-field",
+      color_field: "s-color-field",
+      date_field: "s-date-field",
+      file_field: "s-drop-zone"
+    }.each do |helper_name, polaris_tag|
+      define_method(helper_name) do |method, options = {}, &block|
+        error = method_error(method)
+        attrs = { error: error }.compact
+
+        html = without_field_error_proc do
+          super(method, options.merge(attrs))
+        end
+
+        polaris_input(polaris_tag, html, &block)
+      end
+    end
+
+    alias_method :drop_zone, :file_field
+
+    def text_area(method, options = {}, &block)
+      error = method_error(method)
+      attrs = { error: error }.compact
+
+      html = without_field_error_proc do
+        super(method, options.merge(attrs))
+      end
+
+      @template.raw Tag.new("s-text-area", "textarea", remove_attributes: %w[type size])
+                       .child_to_attr("value")
+                       .apply(html)
+    end
+
+    def check_box(method, options = {}, checked_value = "1", unchecked_value = "0")
+      error = method_error(method)
+      attrs = { error: error }.compact
+
+      html = without_field_error_proc do
+        super(method, options.merge(attrs), checked_value, unchecked_value)
+      end
+
+      polaris_input("s-checkbox", html)
+    end
+
+    def select(method, choices = nil, options = {}, html_options = {}, &block)
+      error = method_error(method)
+      attrs = { error: error }.compact
+
+      html = without_field_error_proc do
+        super(method, choices, options.merge(attrs), html_options)
+      end
+
+      content = capture_block(&block)
+
+      select_tag = Tag.new("s-select", "select")
+      select_tag.attr("value", object.send(method)) if object.respond_to?(method)
+
+      html = select_tag.apply(html, content)
+      html = Tag.new("s-option-group", "optgroup").apply(html)
+      html = Tag.new("s-option", "option").apply(html)
+
+      @template.raw html
+    end
+
+    def submit(value = nil, options = {})
+      html = without_field_error_proc do
+        super(value, options)
+      end
+
+      @template.raw Tag.new("s-button", "input")
+                       .attr_to_child("value")
+                       .apply(html)
+    end
+
+    def money_field(method, options = {})
+      html = text_field(method, options)
+
+      @template.raw Tag.new("s-money-field", "s-text-field").apply(html)
+    end
+
+    def color_picker(method, options = {})
+      html = text_field(method, options)
+
+      @template.raw Tag.new("s-color-picker", "s-text-field").apply(html)
+    end
+
+    def date_picker(method, options = {})
+      options = options.dup
+      picker_type = options.delete(:type)
+      html = date_field(method, options)
+
+      tag = Tag.new("s-date-picker", "s-date-field")
+      tag.attr("type", picker_type) if picker_type
+      @template.raw tag.apply(html)
+    end
+
+    def switch(method, options = {})
+      html = check_box(method, options, options.fetch(:value, "1"))
+
+      @template.raw Tag.new("s-switch", "s-checkbox").apply(html)
+    end
+
+    def choice_list(method, options = {}, &block)
+      select(method, options.delete(:choices), options, &block)
+    end
+
+    private
+
+    def method_error(method)
+      if object.respond_to?(:errors) && object.errors[method].present?
+        object.errors[method].to_sentence
+      end
+    end
+
+    def without_field_error_proc
+      original = ::ActionView::Base.field_error_proc
+      ::ActionView::Base.field_error_proc = ->(html_tag, _instance) { html_tag }
+      yield
+    ensure
+      ::ActionView::Base.field_error_proc = original
+    end
+
+    def polaris_input(tag_name, html, &block)
+      tag = Tag.new(tag_name, "input", remove_attributes: %w[type size])
+      @template.raw tag.apply(html, capture_block(&block))
+    end
+
+    def capture_block(&block)
+      return unless block_given?
+
+      # Use the buffer from the block's binding to avoid writing to a different
+      # output buffer and duplicating content when the builder is reused.
+      capture_buffer = block.binding.eval("@output_buffer") rescue nil
+      capture_buffer ||= @template.output_buffer
+
+      if capture_buffer.respond_to?(:capture)
+        capture_buffer.capture(&block)
+      else
+        @template.capture(&block)
+      end
+    end
+  end
+end

data/lib/polaris_form_builder/helpers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "form_builder"
+
+module PolarisFormBuilder
+  module Helpers
+    def polaris_form_with(**options, &block)
+      form_with(**options.merge(builder: PolarisFormBuilder::FormBuilder), &block)
+    end
+  end
+end

data/lib/polaris_form_builder/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module PolarisFormBuilder
+  class Railtie < ::Rails::Railtie
+    initializer "polaris_form_builder.view_helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include PolarisFormBuilder::Helpers
+      end
+    end
+  end
+end

data/lib/polaris_form_builder/tag.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module PolarisFormBuilder
+  class Tag
+    attr_accessor :name
+
+    def initialize(name, replace, remove_attributes: [])
+      @name = name
+      @replace = replace
+      @remove_attributes = remove_attributes
+      @transformations = []
+    end
+
+    def attr_to_child(attr_name)
+      @transformations << ->(node) {
+        if (attr = node.attr(attr_name))
+          node.add_child(attr)
+        end
+      }
+      self
+    end
+
+    def child_to_attr(attr_name)
+      @transformations << ->(node) {
+        content = node.content
+        if content.present?
+          node.set_attribute(attr_name, content)
+          node.children.remove
+        end
+      }
+      self
+    end
+
+    def attr(attr_name, value)
+      return self unless value
+
+      @transformations << ->(node) {
+        node.set_attribute(attr_name, value)
+      }
+      self
+    end
+
+    def apply(html, content = nil)
+      fragment = Nokogiri::HTML5.fragment(html)
+      fragment.css("#{@replace}:not([type=\"hidden\"])").each do |node|
+        node.name = @name
+        node.inner_html = content if content
+
+        @transformations.each { |transform| transform.call(node) }
+
+        @remove_attributes.each do |key|
+          node.remove_attribute(key)
+        end
+      end
+      fragment.to_html
+    end
+  end
+end

data/lib/polaris_form_builder/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PolarisFormBuilder
+  VERSION = "0.1.0"
+end

data/lib/polaris_form_builder.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "polaris_form_builder/version"
+require_relative "polaris_form_builder/form_builder"
+require_relative "polaris_form_builder/railtie" if defined?(Rails::Railtie)
+
+module PolarisFormBuilder
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: polaris_form_builder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lex Cao
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Rails form helpers and view bindings to build forms with Shopify Polaris
+  web components.
+email:
+- lexcao@foxmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/polaris_form_builder.rb
+- lib/polaris_form_builder/form_builder.rb
+- lib/polaris_form_builder/helpers.rb
+- lib/polaris_form_builder/railtie.rb
+- lib/polaris_form_builder/tag.rb
+- lib/polaris_form_builder/version.rb
+homepage: https://polaris-form-builder.lexcao.io
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://polaris-form-builder.lexcao.io
+  source_code_uri: https://github.com/lexcao/polaris_form_builder
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails form builder helpers for Shopify Polaris web components.
+test_files: []