formtastic_tristate_radio 0.1.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c29b06aadeb4938a06be81d4b33c23c904d7033011aec8346d43b765f54d262
-  data.tar.gz: 471d66686e0aa7db2526642214602aa49ede7ab6183100877e9bda5954bab37d
+  metadata.gz: 8fdf4d000b01b98679b7b2e4eb9bbb8ac43e2bdec9dfe79aba6e07ed580f0cbf
+  data.tar.gz: 7734d39327b809b599b058362e091df2e6153749ff6cfad5a7cb7ac91756e1a2
 SHA512:
-  metadata.gz: 7292702606d47a360a308d89c322bb3dda27adc62866c4bc0fa45e6939ebb841a30760684b8b299b7312838b83ebc800d1d5b83624a6d73b37d2f21f2ea33cc5
-  data.tar.gz: 97251242621b60cc2d1c9f381f29a58f408eddd44c202ba9f57ddf6c7075c54212733c70c9b7ef83c317e8fde8991b7aaaa9f79439e7d060f8f111fc6d0f6c11
+  metadata.gz: e67a6dfe2440683e483d9d2bb677b66a87d335625a1ca7622888e641b3b0c36d8602ef502708d2098e78b4d3f15985ca59b6105d17f661adb4e72ea5661f07a1
+  data.tar.gz: 9fcd6fe99ddfba81237d17305abcc6e1de6febcc05765c442c265bdb5293adaea88bd9364affac0c374929a4ebc1113cba8c98ad7eb82dd11440cde462fa7606

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [0.2.2] - 2021-11-05
+
+- Make the gem configurable
+- Pull the key used for “unset” choice value into configuration
+
+## [0.2.1] - 2021-11-04
+
+- Updates docs URL in gemspec
+- Updates change-log URL in gemspec
+- Removes development gems
+- Adds roadmap items
+
+## [0.2.0] - 2021-11-04
+
+- Custom translation override from form via options
+- Custom error class
+- YARD documentation for everything
+- Inherits from `Formtastic::Inputs::RadioInput` and patches only necessary methods
+- Error YAML example for ActiveAdmin included only if ActiveAdmin is detected
+
+## [0.1.0] - 2021-11-01
+
+Initial release

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec # Specify your gem's dependencies in .gemspec

data/Gemfile.lock

@@ -0,0 +1,162 @@
+PATH
+  remote: .
+  specs:
+    formtastic_tristate_radio (0.2.3)
+      formtastic (>= 3, < 5)
+      rails (>= 4, < 7)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    actioncable (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activejob (= 6.1.4.1)
+      activerecord (= 6.1.4.1)
+      activestorage (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      mail (>= 2.7.1)
+    actionmailer (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      actionview (= 6.1.4.1)
+      activejob (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      mail (~> 2.5, >= 2.5.4)
+      rails-dom-testing (~> 2.0)
+    actionpack (6.1.4.1)
+      actionview (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      rack (~> 2.0, >= 2.0.9)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activerecord (= 6.1.4.1)
+      activestorage (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      nokogiri (>= 1.8.5)
+    actionview (6.1.4.1)
+      activesupport (= 6.1.4.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.1.4.1)
+      activesupport (= 6.1.4.1)
+      globalid (>= 0.3.6)
+    activemodel (6.1.4.1)
+      activesupport (= 6.1.4.1)
+    activerecord (6.1.4.1)
+      activemodel (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+    activestorage (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activejob (= 6.1.4.1)
+      activerecord (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      marcel (~> 1.0.0)
+      mini_mime (>= 1.1.0)
+    activesupport (6.1.4.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    builder (3.2.4)
+    concurrent-ruby (1.1.9)
+    crass (1.0.6)
+    diff-lcs (1.4.4)
+    erubi (1.10.0)
+    formtastic (4.0.0)
+      actionpack (>= 5.2.0)
+    globalid (0.5.2)
+      activesupport (>= 5.0)
+    i18n (1.8.11)
+      concurrent-ruby (~> 1.0)
+    loofah (2.12.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (1.0.2)
+    method_source (1.0.0)
+    mini_mime (1.1.2)
+    minitest (5.14.4)
+    nio4r (2.5.8)
+    nokogiri (1.12.5-x86_64-darwin)
+      racc (~> 1.4)
+    racc (1.6.0)
+    rack (2.2.3)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.1.4.1)
+      actioncable (= 6.1.4.1)
+      actionmailbox (= 6.1.4.1)
+      actionmailer (= 6.1.4.1)
+      actionpack (= 6.1.4.1)
+      actiontext (= 6.1.4.1)
+      actionview (= 6.1.4.1)
+      activejob (= 6.1.4.1)
+      activemodel (= 6.1.4.1)
+      activerecord (= 6.1.4.1)
+      activestorage (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      bundler (>= 1.15.0)
+      railties (= 6.1.4.1)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.4.2)
+      loofah (~> 2.3)
+    railties (6.1.4.1)
+      actionpack (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+      method_source
+      rake (>= 0.13)
+      thor (~> 1.0)
+    rake (13.0.6)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.3)
+    sprockets (4.0.2)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.2)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    thor (1.1.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    websocket-driver (0.7.5)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+    yard (0.9.26)
+    zeitwerk (2.5.1)
+
+PLATFORMS
+  x86_64-darwin-17
+
+DEPENDENCIES
+  formtastic_tristate_radio!
+  rspec (~> 3)
+  yard (>= 0.9.20, < 1)
+
+BUNDLED WITH
+   2.2.27

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 Sergey Pedan
+
+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

@@ -1,50 +1,57 @@
 # Formtastic tri-state radio
 
+[![Gem Version](https://badge.fury.io/rb/formtastic_tristate_radio.svg)](https://badge.fury.io/rb/formtastic_tristate_radio)
+[![Maintainability](https://api.codeclimate.com/v1/badges/c2508d7f23238fb2b87f/maintainability)](https://codeclimate.com/github/sergeypedan/formtastic-tristate-radio/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/c2508d7f23238fb2b87f/test_coverage)](https://codeclimate.com/github/sergeypedan/formtastic-tristate-radio/test_coverage)
+
 ## What is “tri-state”?
 
-— that which has 3 states.
+— that which has 3 states.
 
-By defenition Boolean values have 2 states: True | False.
+By defenition Boolean values have 2 states: True & False.
 
-However, if you store a Boolean value in a database column with no `NOT FULL` restriction, it aquires a 3d possible state: `null`.
+However, if you store a Boolean value in a database column with no `NOT NULL` restriction, it aquires a 3<sup>d</sup> possible state: `null`.
 
-Some may say this is a questionable practice — I don’t think so. In real life you always have a case when the answer to your question may be only “yes” or “no”, but you don’t know the answer yet. Using a string type column, storing there `"yes"`, `"no"` and `"unset"` + using a state machine + validations — feels overkill to me.
+Some may consider this practice questionable — I don’t think so. In real life you always have a case when the answer to your question may be only “yes” or “no”, but you don’t know the answer yet. Using a string type column, storing there `"yes"`, `"no"` and `"unset"` + using a state machine + validations — feels overkill to me.
 
 
 ## What the gem does
 
-1. Provides a custom Formtastic input type `:tristate_radio` which renders 3 radios (“Yes”, “No”, “Unset”) instead of a checkbox (only where you put it).
-1. Teaches Rails recognize `"null"` and `"nil"` param values as `nil`. See “[How it works](#how-it-works)” ☟ section for technical details on this.
-1. Encourages you to add translations for ActiveAdmin “status tag” so that `nil` be correctly translated as “Unset” instead of “False”.
+1. Provides a custom Formtastic input type `:tristate_radio` which renders 3 radios (“Yes”, “No”, “Unset”) instead of a checkbox (only where you put it).
+1. Teaches Rails recognize `"null"` and `"nil"` param values as `nil`. See “[How it works](#how-it-works)” ☟ section for technical details on this.
+1. Encourages you to add translations for ActiveAdmin “status tag” so that `nil` be correctly translated as “Unset” instead of “False”.
 
 
 ## Usage
 
-For a Boolean column with 3 possible states:
+For a Boolean column with 3 possible states:
 
 ```ruby
-f.input :column_name, as: :tristate_radio
+f.input :am_i_awake, as: :tristate_radio
 ```
 
-You get (HTML is simplified):
+You get (HTML is simplified, actually there are more classes etc.):
 
 ```html
 <fieldset>
-  <input name="column_name" type="radio" value="true">  <label>Yes</label>
-  <input name="column_name" type="radio" value="false"> <label>No</label>
-  <input name="column_name" type="radio" value="null">  <label>Unset</label>
+  <legend>Am i awake?</legend>
+  <input name="am_i_awake" type="radio" value="true">  <label>Yes</label>
+  <input name="am_i_awake" type="radio" value="false"> <label>No</label>
+  <input name="am_i_awake" type="radio" value="null">  <label>Unset</label>
 </fieldset>
 ```
 
-In the future `:tristate_radio` will be registered for Boolean columns with `null` by default. Until then you have to assign it manually.
-
 
 ## Installation
 
+### Gem
+
 ```ruby
 gem "formtastic_tristate_radio"
 ```
 
+### Translations
+
 Add translation for the new “unset” option:
 
 ```yaml
@@ -55,7 +62,15 @@ ru:
     null: Неизвестно # <- this you must provide youself
 ```
 
-ActiveAdmin will automatically translate `nil` as “No”, so if you use ActiveAdmin, add translation like so:
+As noted in [Usage](#usage), you can override individual translations like so:
+
+```ruby
+f.input :attribute, as: :tristate_radio, null: "Your text"
+```
+
+### ActiveAdmin translations
+
+ActiveAdmin will automatically translate `nil` as “No”, so if you use ActiveAdmin, add translation like so:
 
 ```yaml
 ru:
@@ -63,23 +78,47 @@ ru:
     status_tag:
       :yes: Да
       :no: Нет
-      null: Неизвестно
+      unset: Неизвестно
 ```
 
+Notice that the key ActiveAdmin uses is “unset”, not “null”.
+
 
 ## Configuration
 
-Nothing is configurable yet. I think of making configurable which values are regognized as `nil`.
+It’s difficult to come up with a reasonable use case for that, but you can configure what will be used as inputs value:
+
+```ruby
+# config/initializers/formtastic.rb
+FormtasticTristateRadio.configure do |config|
+  config.unset_key = "__unset" # default is :null
+end
+```
+
+which will result in:
+
+```html
+<input type="radio" name="am_i_awake" value="true">
+<input type="radio" name="am_i_awake" value="false">
+<input type="radio" name="am_i_awake" value="__unset">
+```
+
+Mind that for your custom value to work, you also need to configure `ActiveModel` to recognize that value as `nil`. Currently that is done [like so](https://github.com/sergeypedan/formtastic-tristate-radio/blob/master/config/initializers/activemodel_type_boolean.rb#L9).
+
+
+## Documentation
+
+Low-level methods are properly documented in RubyDoc [here](https://www.rubydoc.info/gems/formtastic_tristate_radio/TristateRadioInput).
 
 
 ## Dependencies
 
-Now the gem depends on [Formtastic](https://github.com/formtastic/formtastic) (naturally) and Rails. Frankly I am not sure whether I will have time to make it work with other frameworks.
+Now the gem depends on [Formtastic](https://github.com/formtastic/formtastic) (naturally) and Rails. Frankly I am not sure whether I will have time to make it work with other frameworks.
 
 
 ## How it works
 
-In Ruby any String is cast to `true`:
+In Ruby any String is cast to `true`:
 
 ```ruby
 !!""      #=> true
@@ -89,11 +128,11 @@ In Ruby any String is cast to `true`:
 !!"null"  #=> true
 ```
 
-Web form params are passed as plain text and are interpreted as String by Rack.
+Web form params are passed as plain text and are interpreted as String by Rack.
 
-So how Boolean values are transfered as strings if a `"no"` or `"0"` and even `""` is truthy in Ruby?
+So how are Boolean values transfered as strings if a `"no"` or `"0"` and even `""` is truthy in Ruby?
 
-Frameworks just have a list of string values to be recognized and mapped to Boolean values:
+Frameworks just have a list of string values to be recognized and mapped to Boolean values:
 
 ```ruby
 ActiveModel::Type::Boolean::FALSE_VALUES
@@ -115,7 +154,7 @@ ActiveModel::Type::Boolean.new.cast("off")  #=> false
 # etc
 ```
 
-So what [I do in this gem](https://github.com/sergeypedan/formtastic_tristate_radio/blob/master/config/initializers/activemodel_type_boolean.rb) is extend `ActiveModel::Type::Boolean` in a consistent way to teach it recognize null-ish values as `nil`:
+So what [I do in this gem](https://github.com/sergeypedan/formtastic_tristate_radio/blob/master/config/initializers/activemodel_type_boolean.rb) is extend `ActiveModel::Type::Boolean` in a consistent way to teach it recognize null-ish values as `nil`:
 
 ```ruby
 module ActiveModel
@@ -143,9 +182,21 @@ ActiveModel::Type::Boolean.new.cast("nil")  #=> nil
 ActiveModel::Type::Boolean.new.cast(:nil)   #=> nil
 ```
 
-**Warning**: as you might have noticed, default Rails behavior is changed. If you rely on Rails’ automatic conversion of strings with value `"null"` into `true`, this gem might not be for you (and you are definitely doing something weird).
+**Warning**: as you might have noticed, default Rails behavior is changed. If you rely on Rails’ automatic conversion of strings with value `"null"` into `true`, this gem might not be for you (and you are definitely doing something weird).
+
+
+## Roadmap
+
+- [ ] Remove `require_relative "../app/models/active_record/base"` from main file
+- [x] Make the gem configurable
+- [x] Pull the key used for “unset” choice value into configuration
+- [ ] Load translations from gem
+- [ ] Add translations into most popular languages
+- [ ] Rgister `:tristate_radio` for Boolean columns with `null`
+- [ ] Decouple `ActiveModel::Type::Boolean` thing from Formtastic things, maybe into a separate gem
+- [ ] Decouple from Rails
 
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/inputs/tristate_radio_input.rb

@@ -3,168 +3,110 @@
 require "formtastic"
 
 # It may also be appropriate to put this file in `app/inputs`
-class TristateRadioInput
+class TristateRadioInput < Formtastic::Inputs::RadioInput
 
-  include Formtastic::Inputs::Base
-  include Formtastic::Inputs::Base::Collections
-  include Formtastic::Inputs::Base::Choices
-
-
-  # UNSET_KEY = :null
-  UNSET_KEY = ActiveModel::Type::Boolean::NULL_VALUES.reject(&:blank?).first
+  # No equals `:null`.
+  # Should equal one of `ActiveModel::Type::Boolean::NULL_VALUES`
   #
-  # Mind ActiveAdmin status resolving logic:
-  # https://github.com/activeadmin/activeadmin/blob/master/lib/active_admin/views/components/status_tag.rb#L51
-  # In status tag builder the value is lowercased before casting into boolean, and the keyword for nil is "unset", so
-  # if we have lowercase "unset", translations from `ru.formtastic.unset` will be overriden by `ru.active_admin.status_tag.unset`.
-
-  MISSING_TRANSLATION_ERROR_MSG = <<~HEREDOC
-
+  # Mind ActiveAdmin [status resolving logic](https://github.com/activeadmin/activeadmin/blob/master/lib/active_admin/views/components/status_tag.rb#L51):
+  # in status tag builder the value is lowercased before casting into Boolean, and the keyword for nil is `"unset"`.
+  # So if we have lowercase `"unset"`, translations from `ru.formtastic.unset` will be overriden by `ru.active_admin.status_tag.unset`.
+  #
+  UNSET_KEY = FormtasticTristateRadio.config.unset_key
 
-    For ActiveAdmin status tags in index & view tables:
+  I18N_EXAMPLE_ACTIVEADMIN = <<~YAML.chomp
     ru:
       active_admin:
         status_tag:
           :yes: Да
           :no: Нет
           :#{UNSET_KEY}: Неизвестно
+  YAML
 
-    For radiobutton labels in forms:
+  I18N_EXAMPLE_FORMTASTIC = <<~YAML.chomp
     ru:
       formtastic:
         :yes: Да
         :no: Нет
         :#{UNSET_KEY}: Неизвестно
-
-    Note: “yes”, “no”, “null” and some other words are reserved, converted into Boolean values in YAML, so you need to quote or symbolize them.
-  HEREDOC
+  YAML
 
 
-  # template => an instance of ActionView::Base
+  # @note In you have ActiveAdmin installed, it will give you YAML example for ActiveAdmin as well, otherwise only for Formtastic
   #
-  # @param choice [Array], ["Completed", "completed"]
+  # @return [String] error message with YAML examples for the “unset” label translation lookup error
   #
-  def choice_html(choice)
-    template.content_tag(:label, tag_content(choice), tag_options(choice))
+  def self.missing_i18n_error_msg
+    msg = []
+    msg << "Add translations for the “unset” radio label"
+    msg << ["For radiobutton labels in forms:", I18N_EXAMPLE_FORMTASTIC].join("\n")
+    msg << "Note: “yes”, “no” and some other reserved words are converted into Boolean values in YAML, so you need to quote or symbolize them."
+    msg << ["For ActiveAdmin status tags in index & view tables:", I18N_EXAMPLE_ACTIVEADMIN].join("\n") if !!defined?(ActiveAdmin)
+    msg.join("\n\n")
   end
 
 
-  # collection => [["Completed", "completed"], ["In progress", "in_progress"], ["Unknown", "unset"]]
+  # @see https://github.com/formtastic/formtastic/blob/35dc806964403cb2bb0a6074b951ceef906c8581/lib/formtastic/inputs/base/choices.rb#L59 Original Formtastic method
   #
-  # @return [Array]
+  # @return [Hash] HTML options for the `<input type="radio" />` tag
   #
-  def collection_with_unset
-    collection + [[unset_label_translation, UNSET_KEY]]
+  # Adds `{ selected: true }` to the original options Hash if the choice value equals attribute value (to ultimately set for `checked="checked"`)
+  #
+  def choice_html_options(choice)
+    super.merge({ checked: selected?(choice) })
   end
 
 
-  # Override to remove the for attribute since this isn't associated with any element, as it's nested inside the legend
-  # @return [Hash]
+  # @example Original method
+  #   def collection_for_boolean
+  #     true_text  = options[:true]  || Formtastic::I18n.t(:yes)
+  #     false_text = options[:false] || Formtastic::I18n.t(:no)
+  #     [ [true_text, true], [false_text, false] ]
+  #   end
   #
-  # @example
-  #   { for: nil, class: ["label"] }
+  #   collection_for_boolean #=> [["Да", true], ["Нет", false]]
   #
-  def label_html_options
-    super.merge({ for: nil })
-  end
-
-
-  # choice_value(choice) => true | false | UNSET_KEY <- in our version
-  # choice_value(choice) => true | false | ?         <- in regular radio-buttons version
-  # method               => :status
-  # object               => ActiveRecord::Base model subclass, `User`
+  # @example This patched method
+  #   collection_for_boolean #=> [["Да", true], ["Нет", false], ["Неизвестно", :null]]
   #
-  # @param choice [Array], ["Completed", "completed"]
+  # @return [Array<[String, (Boolean|String|Symbol)]>] an array of “choices”, each presented as an array with 2 items: HTML label text and HTML input value
   #
-  # For this to work, ActiveModel::Type::Boolean must be patched to resolve `UNSET_KEY` as nil
+  # @see https://github.com/formtastic/formtastic/blob/e34baba470d2fda75bf9748cff8898ee0ed29075/lib/formtastic/inputs/base/collections.rb#L131 Original Formtastic method
   #
-  def selected?(choice)
-    ActiveModel::Type::Boolean.new.cast(choice_value(choice)) == object.public_send(method)
+  def collection_for_boolean
+    super + [[label_text_for_unset, UNSET_KEY]]
   end
 
 
-  # @returns [String]
-  #   "<input ...> Text..."
-  #
-  # @param choice [Array], ["Completed", "completed"]
+  # Checks translation passed as option, then checks in locale
   #
-  # input_html_options => { id: "task_status", required: false, autofocus: false, readonly: false}
-  #
-  # input_html_options.merge(choice_html_options(choice)).merge({ required: false })
-  # => { id: "task_status_completed", required: false, autofocus: false, readonly: false }
-  #
-  # builder                     => an instance of ActiveAdmin::FormBuilder
-  # choice_label(choice)        => "Completed"
-  # choice_html_options(choice) => { id: "task_status_completed" }
-  # choice_value(choice)        => "completed"
-  # input_name                  => :status
+  # @example
+  #   label_text_for_unset #=> "Неизвестно"
   #
-  def tag_content(choice)
-    builder.radio_button(
-      input_name,
-      choice_value(choice),
-      input_html_options.merge(choice_html_options(choice)).merge({ required: false, checked: selected?(choice) })
-    ) << choice_label(choice)
-  end
-
-
-  # choice_input_dom_id(choice) => "task_status_completed"
-  # label_html_options          => { for: nil, class: ["label"] }
+  # @return [String] Label of the radio that stands for the unknown choice
   #
-  # @param choice [Array], ["Completed", "completed"]
+  # @raise [StandardError] if the translation could not be found
+  # @see missing_i18n_error_msg
   #
-  def tag_options(choice)
-    label_html_options.merge({ for: choice_input_dom_id(choice), class: nil })
+  def label_text_for_unset
+    options.fetch(:null, Formtastic::I18n.t(UNSET_KEY)).presence or \
+      fail FormtasticTristateRadio::MissingTranslationError.new(self.class.missing_i18n_error_msg)
   end
 
 
-  # choice_wrapping_html_options(choice) #=> { class: "choice" }
+  # @example For each item of `collection` it runs:
+  #   selected?(["Да", true]) #=> false
+  #   selected?(["Нет", false]) #=> false
+  #   selected?(["Неизвестно", :null]) #=> true
   #
-  # legend_html         => "<legend class="label">
-  #                           <label>Status</label>
-  #                         </legend>"
+  # @param choice [Array<[String, (Boolean|String|Symbol)]>]
   #
-  # choice_html(choice) => "<label for="task_status_completed">
-  #                           <input type="radio" value="completed" name="task[status]" /> Completed
-  #                         </label>"
+  # @return [Boolean] answer to the question “Is the passed option selected?”
   #
-  # collection.map do |choice|
-  #   choice_wrapping({ class: "choice" }) do
-  #     choice_html(choice)
-  #   end
-  # end
-  # => ["<li class="choice">
-  #        <label for="task_status_completed">
-  #          <input type="radio" value="completed" name="task[status]" /> Completed
-  #        </label>
-  #      </li>",
-  #     "<li class="choice">
-  #      ...
-  #    ]
-  #
-  # This method relies on ActiveAdmin
-  #
-  def to_html
-    choices = collection_with_unset #=> [["Completed", "completed"], ["In progress", "in_progress"], ["Unknown", "unset"]]
-
-    input_wrapping do
-      choices_wrapping do
-        legend_html <<  choices_group_wrapping do
-                          choices.map { |choice|
-                            choice_wrapping(choice_wrapping_html_options(choice)) do
-                              choice_html(choice)
-                            end
-                          }.join("\n").html_safe
-                        end
-      end
-    end
-  end
-
-
-  # @return [String] Label of the radio that stands for the unknown choice
+  # @note For this to work, `ActiveModel::Type::Boolean` must be patched to resolve `UNSET_KEY` as `nil`.
   #
-  def unset_label_translation
-    Formtastic::I18n.t(UNSET_KEY).presence or fail StandardError.new(MISSING_TRANSLATION_ERROR_MSG)
+  def selected?(choice)
+    ActiveModel::Type::Boolean.new.cast(choice_value(choice)) == object.public_send(method)
   end
 
 end

data/app/models/active_record/base.rb

@@ -2,7 +2,11 @@
 
 class ActiveRecord::Base
 
-  # @return [Array] of symbols — names of Boolean columns, which can be `NULL`
+  # @return [Array<Symbol>] names of Boolean columns which can store `NULL` values
+  # @example
+  #  Company.tristate_column_names
+  #  #=> [:is_profitable, :is_run_by_psychopaths, :evades_taxation, ...]
+  #
   def self.tristate_column_names
     columns.select { |col| col.type == :boolean && col.null }.map(&:name)
   end

data/config/initializers/activemodel_type_boolean.rb

@@ -4,7 +4,7 @@ module ActiveModel
   module Type
     class Boolean < Value
 
-      NULL_VALUES = [nil, "", "null", :null, "nil", :nil].to_set.freeze
+      NULL_VALUES = [nil, "", :null, "null", :nil, "nil"].to_set.freeze
 
       private def cast_value(value)
         NULL_VALUES.include?(value) ? nil : !FALSE_VALUES.include?(value)

data/config/locales/active_admin.yml

@@ -0,0 +1,60 @@
+---
+ca:
+  active_admin:
+    status_tag:
+      :null: No establert
+---
+de:
+  active_admin:
+    status_tag:
+      :null: Nicht eingestellt
+---
+fr:
+  active_admin:
+    status_tag:
+      :null: Pas défini
+---
+it:
+  active_admin:
+    status_tag:
+      :null: Sconosciuto
+---
+ja:
+  active_admin:
+    status_tag:
+      :null: 不明
+---
+en:
+  active_admin:
+    status_tag:
+      :null: Unset
+---
+es:
+  active_admin:
+    status_tag:
+      :null: No establecido
+---
+pl:
+  active_admin:
+    status_tag:
+      :null: Nie ustawiony
+---
+pt-BR:
+  active_admin:
+    status_tag:
+      :null: Não configurado
+---
+pt:
+  active_admin:
+    status_tag:
+      :null: Não configurado
+---
+ru:
+  active_admin:
+    status_tag:
+      :null: Неизвестно
+---
+tr:
+  active_admin:
+    status_tag:
+      :null: Ayarlanmadı

data/config/locales/formtastic.yml

@@ -0,0 +1,48 @@
+---
+ca:
+  formtastic:
+    :null: No establert
+---
+de:
+  formtastic:
+    :null: Nicht eingestellt
+---
+fr:
+  formtastic:
+    :null: Pas défini
+---
+it:
+  formtastic:
+    :null: Sconosciuto
+---
+ja:
+  formtastic:
+    :null: 不明
+---
+en:
+  formtastic:
+    :null: Unset
+---
+es:
+  formtastic:
+    :null: No establecido
+---
+pl:
+  formtastic:
+    :null: Nie ustawiony
+---
+pt-BR:
+  formtastic:
+    :null: Não configurado
+---
+pt:
+  formtastic:
+    :null: Não configurado
+---
+ru:
+  formtastic:
+    :null: Неизвестно
+---
+tr:
+  formtastic:
+    :null: Ayarlanmadı

data/formtastic_tristate_radio.gemspec

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# https://guides.rubygems.org/name-your-gem/
+# https://bundler.io/guides/creating_gem.html
+# https://guides.rubyonrails.org/engines.html
+# https://guides.rubyonrails.org/plugins.html
+
+require_relative "lib/formtastic_tristate_radio/version"
+
+Gem::Specification.new do |spec|
+  spec.name             = "formtastic_tristate_radio"
+  spec.version          =  FormtasticTristateRadio::VERSION
+  spec.authors          = ["Sergey Pedan"]
+  spec.email            = ["sergey.pedan@gmail.com"]
+  spec.license          =  "MIT"
+
+  spec.summary          =  "Have 3-state radiobuttons instead of a 2-state checkbox for your Boolean columns which can store NULL"
+  spec.description      = <<~HEREDOC
+                            #{spec.summary}.
+
+                            What the gem does?
+
+                            1. Provides a custom Formtastic input type `:tristate_radio` which renders 3 radios (“Yes”, “No”, “Unset”) instead of a checkbox (only where you put it).
+                            1. Teaches Rails recognize `"null"` and `"nil"` param values as `nil`. See “[How it works](#how-it-works)” ☟ section for technical details on this.
+                            1. Encourages you to add translations for ActiveAdmin “status tag” so that `nil` be correctly translated as “Unset” instead of “False”.
+
+                            Does not change controls, you need to turn it on via `as: :tristate_radio` option.
+
+                            By defenition Boolean values have 2 states: True & False.
+
+                            However, if you store a Boolean value in a database column with no `NOT NULL` restriction, it aquires a 3<sup>d</sup> possible state: `null`.
+
+                            Some may consider this practice questionable — I don’t think so. In real life you always have a case when the answer to your question may be only “yes” or “no”, but you don’t know the answer yet. Using a string type column, storing there `"yes"`, `"no"` and `"unset"` + using a state machine + validations — feels overkill to me.
+                          HEREDOC
+
+  spec.homepage         =  "https://github.com/sergeypedan/formtastic-tristate-radio"
+  spec.extra_rdoc_files = ["README.md", "CHANGELOG.md"]
+  spec.rdoc_options     = ["--charset=UTF-8"]
+  spec.metadata         = { "changelog_uri"     => "#{spec.homepage}/blob/master/CHANGELOG.md",
+                            "documentation_uri" => "https://www.rubydoc.info/gems/#{spec.name}",
+                            "homepage_uri"      => spec.homepage,
+                            "source_code_uri"   => spec.homepage }
+
+  spec.require_paths    = ["app/inputs", "app/models/active_record", "config/initializers", "config/locales", "lib"]
+  spec.bindir           = "exe"
+  spec.executables      = []
+  spec.files            = Dir.chdir(File.expand_path(__dir__)) do
+                            `git ls-files`.split("\n")
+                              .reject { |f| %w[bin spec test].any? { |dir| f.start_with? dir } }
+                              .reject { |f| f.start_with? "." }
+                          end
+
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+
+  spec.add_dependency "formtastic", ">= 3", "< 5"
+  spec.add_dependency "rails",      ">= 4", "< 7"
+
+  spec.add_development_dependency "rspec", "~> 3"
+  spec.add_development_dependency "yard",  ">= 0.9.20", "< 1"
+end

data/lib/formtastic_tristate_radio/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FormtasticTristateRadio
+
+  class << self
+    attr_writer :config
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.configure
+    yield(config)
+  end
+
+  class Configuration
+    attr_accessor :unset_key
+
+    def initialize
+      @unset_key = :null
+    end
+  end
+
+end

data/lib/formtastic_tristate_radio/engine.rb

@@ -1,4 +1,11 @@
+# frozen_string_literal: true
+
 module FormtasticTristateRadio
+
+  # This is standard Rails way to autoload gem’s contents dynamically as an “engine”
+  # https://guides.rubyonrails.org/engines.html
+  #
   class Engine < ::Rails::Engine
   end
+
 end

data/lib/formtastic_tristate_radio/missing_translation_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module FormtasticTristateRadio
+  class MissingTranslationError < I18n::MissingTranslationData
+  end
+end

data/lib/formtastic_tristate_radio/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FormtasticTristateRadio
-  VERSION = '0.1.0'
+  VERSION = '0.2.3'
 end

data/lib/formtastic_tristate_radio.rb

@@ -1,8 +1,9 @@
-require "formtastic_tristate_radio/version"
-require "formtastic_tristate_radio/engine"
+require_relative "formtastic_tristate_radio/version"
+require_relative "formtastic_tristate_radio/missing_translation_error"
+require_relative "formtastic_tristate_radio/configuration"
+require_relative "formtastic_tristate_radio/engine"
 
 require_relative "../app/models/active_record/base"
-# require_relative "../app/inputs/tristate_radio_input"
 
 module FormtasticTristateRadio
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: formtastic_tristate_radio
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.3
 platform: ruby
 authors:
 - Sergey Pedan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-11-03 00:00:00.000000000 Z
+date: 2021-11-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: formtastic
@@ -51,102 +51,98 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '7'
 - !ruby/object:Gem::Dependency
-  name: coveralls
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '3'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.14'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.14'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+        version: 0.9.20
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '13'
+        version: '1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+        version: 0.9.20
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.9'
-description: 'Have 3-state radiobuttons instead of a 2-state checkbox for your Boolean
-  columns which can store NULL. Does not change controls, you need to turn it on via
-  `as: :tristate_radio` option.'
+        version: '1'
+description: |
+  Have 3-state radiobuttons instead of a 2-state checkbox for your Boolean columns which can store NULL.
+
+  What the gem does?
+
+  1. Provides a custom Formtastic input type `:tristate_radio` which renders 3 radios (“Yes”, “No”, “Unset”) instead of a checkbox (only where you put it).
+  1. Teaches Rails recognize `"null"` and `"nil"` param values as `nil`. See “[How it works](#how-it-works)” ☟ section for technical details on this.
+  1. Encourages you to add translations for ActiveAdmin “status tag” so that `nil` be correctly translated as “Unset” instead of “False”.
+
+  Does not change controls, you need to turn it on via `as: :tristate_radio` option.
+
+  By defenition Boolean values have 2 states: True & False.
+
+  However, if you store a Boolean value in a database column with no `NOT NULL` restriction, it aquires a 3<sup>d</sup> possible state: `null`.
+
+  Some may consider this practice questionable — I don’t think so. In real life you always have a case when the answer to your question may be only “yes” or “no”, but you don’t know the answer yet. Using a string type column, storing there `"yes"`, `"no"` and `"unset"` + using a state machine + validations — feels overkill to me.
 email:
 - sergey.pedan@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
 - README.md
+- CHANGELOG.md
 files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- MIT-LICENSE
 - README.md
 - Rakefile
 - app/inputs/tristate_radio_input.rb
 - app/models/active_record/base.rb
 - config/initializers/activemodel_type_boolean.rb
-- config/locales/active_admin.en.yml
-- config/locales/active_admin.ru.yml
-- config/locales/formtastic.en.yml
-- config/locales/formtastic.ru.yml
+- config/locales/active_admin.yml
+- config/locales/formtastic.yml
 - config/routes.rb
+- formtastic_tristate_radio.gemspec
 - lib/formtastic_tristate_radio.rb
+- lib/formtastic_tristate_radio/configuration.rb
 - lib/formtastic_tristate_radio/engine.rb
+- lib/formtastic_tristate_radio/missing_translation_error.rb
 - lib/formtastic_tristate_radio/version.rb
-- lib/tasks/formtastic_tristate_radio_tasks.rake
 homepage: https://github.com/sergeypedan/formtastic-tristate-radio
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://github.com/sergeypedan/formtastic-tristate-radio/blob/master/Changelog.md
-  documentation_uri: https://github.com/sergeypedan/formtastic-tristate-radio#usage
+  changelog_uri: https://github.com/sergeypedan/formtastic-tristate-radio/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/formtastic_tristate_radio
   homepage_uri: https://github.com/sergeypedan/formtastic-tristate-radio
   source_code_uri: https://github.com/sergeypedan/formtastic-tristate-radio
 post_install_message:
 rdoc_options:
 - "--charset=UTF-8"
 require_paths:
-- lib
 - app/inputs
 - app/models/active_record
 - config/initializers
 - config/locales
+- lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/config/locales/active_admin.en.yml

@@ -1,5 +0,0 @@
----
-en:
-  active_admin:
-    status_tag:
-      unset: Unset

data/config/locales/active_admin.ru.yml

@@ -1,7 +0,0 @@
----
-ru:
-  active_admin:
-    status_tag:
-      :no: Нет
-      :yes: Да
-      unset: Неизвестно

data/config/locales/formtastic.en.yml

@@ -1,4 +0,0 @@
----
-en:
-  formtastic:
-    :null: Unset

data/config/locales/formtastic.ru.yml

@@ -1,6 +0,0 @@
----
-ru:
-  formtastic:
-    :no: Нет
-    :null: Неизвестно
-    :yes: Да

data/lib/tasks/formtastic_tristate_radio_tasks.rake

@@ -1,4 +0,0 @@
-# desc "Explaining what the task does"
-# task :formtastic_tristate_radio do
-#   # Task goes here
-# end