superform 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: accaaea2d3dd94355732e750093516e12c4dd1b113fcaecf6aae4f3cce30139d
-  data.tar.gz: 9696d2b2de96dda5d6a7a4c80c23aaed95e3db27223daf6b1744bd5cbe842417
+  metadata.gz: 41ba2a10e93238ddfea45963bbc08a28c884231e128b39becdb184ceebd9c9f9
+  data.tar.gz: 994b8448c1e72182bb5638682f4d45b42a5b2b04b6d85ec78b1cb8cab55f9263
 SHA512:
-  metadata.gz: c6bfa1a54025fce5d9caabafce96fdad1564bbdc95eaf1e7b8959d3fd7c021c595ac66de5da05cc511631f85f1791ed501a0ec7c973705712b227fa04cc4ba04
-  data.tar.gz: c908864725edfc61446f4bbf678758b4efb4a171dd2634ea96d423876e3b36b3356842b075372c9559201bef26d170c3f10e696d26928841ca413d7476106593
+  metadata.gz: ba4d34fc66ef3fae89763ed7cf091a1d41c54df4f585b650a62ba0bee14038c2a1cdf5aa8f15b15bf5f73c201b96113f71bc13e25b3ccb85b45329e3c80844fa
+  data.tar.gz: b39fdedafc3f12a84ec753e0abf34f38b28632b801f0ace6a020c8d07946931d07ba6bb15f54414f13a1c065768df3e1291ef39431c3770fe8e2ddb8765af988

data/CHANGELOG.md

@@ -1,4 +1,67 @@
-## [Unreleased]
+## [0.7.0] - 2026-03-01
+
+### Added
+
+- **Radio and checkbox groups** via `Field(:plan).radios(...)` and `Field(:roles).checkboxes(...)`.
+  Return renderable Phlex components (like `input`, `select`) so they work as one-liners
+  via Kit. Without a block, renders default `<label><input> Text</label>` markup per choice.
+  With a block, yields each `Choice` for custom markup — `choice.input` and
+  `choice.label` render directly into the component's output. Accepts the same option formats as
+  `select`. Auto-detects Rails enums when called with no arguments.
+  `choice.label` without a block defaults to rendering `choice.text`.
+  Subclass `Components::Radios` or `Components::Checkboxes` to customize defaults.
+- **Hash options** for `select`, `radios`, and `checkboxes` — e.g. `radios(1 => "Basic", 2 => "Pro")`.
+- **Radio component** with `field(:gender).radio("male")` API. Automatically handles name, value, and checked state. Each radio gets a unique DOM id based on its value (e.g. `user_gender_male`).
+- **Checkbox collection support** — three modes:
+  - **Boolean** (on/off toggle): `Field(:featured).checkbox` renders with hidden "0" input
+  - **All-options** (pick from known set): `Field(:role_ids).checkbox(value: role.id)` with `[]` name and unique ids per value
+  - **Field collection** (from existing array): `field(:role_ids).collection { |r| r.checkbox }` for values already on the model
+- **Choices module** (`Superform::Rails::Choices`) — `Choices::Choice` holds per-option state,
+  `Choices::Mapper` (renamed from `OptionMapper`) maps option args to `(value, text)` pairs.
+- **Unique DOM ids** for radio and checkbox groups via `DOM#id(*suffixes)`. Prevents duplicate ids in valid HTML and allows labels to target individual inputs.
+- **Datalist component** with `Field(:time_zone).datalist(*ActiveSupport::TimeZone.all.map(&:name))`.
+  Renders a native `<input>` + `<datalist>` for free-text input with autocomplete suggestions —
+  no JavaScript required. Accepts the same option formats as `select`. Block form available
+  for custom options.
+- **Select improvements**: blank options (`nil`) at any position, `multiple: true` support with hidden input for empty submissions, ActiveRecord relations as options.
+- **Preview server** — run `bin/preview` to view example forms at localhost:3000 with hot-reloading.
+
+### Changed
+
+- `OptionMapper` renamed to `Choices::Mapper`. If you referenced `Superform::Rails::OptionMapper` directly, update to `Superform::Rails::Choices::Mapper`.
+- **Deprecation**: Components now accept HTML attributes as keyword arguments directly instead of wrapping them in `attributes:`. The old `attributes:` keyword still works but emits a deprecation warning and will be removed in a future version.
+
+  ```ruby
+  # Before
+  MyInput.new(field, attributes: { class: "form-input" })
+
+  # After
+  MyInput.new(field, class: "form-input")
+  ```
+
+  If you have custom components that override `initialize`, update them to use `**attributes`:
+
+  ```ruby
+  # Before
+  class MyRadio < Superform::Rails::Components::Field
+    def initialize(field, value:, attributes: {})
+      super(field, attributes: attributes)
+      @value = value
+    end
+  end
+
+  # After
+  class MyRadio < Superform::Rails::Components::Field
+    def initialize(field, value:, **attributes)
+      super(field, **attributes)
+      @value = value
+    end
+  end
+  ```
+
+- Required Ruby version bumped to 2.7.0.
+
+## [0.6.1] - 2025-08-28
 
 ### Breaking Changes
 
@@ -41,6 +104,40 @@ Rails classes have been moved into separate files for better organization:
 
 ### How to Upgrade
 
+#### Phlex 2.x compatibility
+
+The `ApplicationForm` file should be moved to `Components::Form` at `./app/components/form.rb` to better match Phlex 2.x conventions.
+
+   ```ruby
+   # Before (0.5.x)
+   class ApplicationForm < Superform::Rails::Form
+     # ...
+   end
+   ```
+
+   ```ruby
+   # After (0.6.0)
+   class Components::Form < Superform::Rails::Form
+     # ...
+   end
+   ```
+
+Form variants may organized in the `./app/components/forms/` directory.
+
+   ```ruby
+   # Before (0.5.x)
+   class Forms::User < ApplicationForm
+     # ...
+   end
+   ```
+
+   ```ruby
+   # After (0.6.0)
+   class Forms::User < Components::Form
+     # ...
+   end
+   ```
+
 #### Custom Form Classes
 
 Custom form classes with Rails now automatically pass themselves as form instances (no changes needed for basic usage).
@@ -70,7 +167,7 @@ Update component class names in your custom form classes:
 
    class Field < Superform::Rails::Form::Field
      def input(**attributes)
-       MyInput.new(self, attributes: attributes)
+       MyInput.new(self, **attributes)
      end
    end
    ```
@@ -107,7 +204,7 @@ Run bundle update to update dependencies:
   - Safe mass assignment protection against unauthorized attributes
 - Field input type helper methods for Rails forms:
   - `field.email` for email input type
-  - `field.password` for password input type  
+  - `field.password` for password input type
   - `field.url` for URL input type
   - `field.tel` (with `phone` alias) for telephone input type
   - `field.number` for number input type

data/CLAUDE.md

@@ -0,0 +1,46 @@
+# Superform Development Guide
+
+## Component Argument Convention
+
+HTML components follow a strict convention for arguments:
+
+- **Positional/named keyword arguments** are for component configuration (non-HTML concerns)
+- **`**kwargs`** are for HTML attributes that pass through to the rendered element
+
+```ruby
+# field is positional, value: is config, **attributes are HTML
+class Radio < Field
+  def initialize(field, value:, **attributes)
+    super(field, **attributes)
+    @value = value
+  end
+end
+
+# options: and multiple: are config, **attributes are HTML
+class Select < Field
+  def initialize(field, options:, multiple: false, **attributes)
+    super(field, **attributes)
+    @options = options
+    @multiple = multiple
+  end
+end
+```
+
+The Field methods mirror this: config args are explicit, HTML attributes flow through as `**kwargs`.
+
+```ruby
+def radio(value, **attributes)
+  Components::Radio.new(field, value:, **attributes)
+end
+
+def select(*options, multiple: false, **attributes, &)
+  Components::Select.new(field, options:, multiple:, **attributes, &)
+end
+```
+
+## Key Architecture
+
+- **Field** is a data binding object (model, key, value, DOM name) — not HTML
+- **Components** are HTML elements — their kwargs should be HTML attributes
+- **Form** is a Phlex component that contains fields and renders the `<form>` tag
+- Customization is through subclassing, not runtime options

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    superform (0.6.1)
+    superform (0.7.0)
       phlex-rails (~> 2.0)
       zeitwerk (~> 2.6)
 
@@ -92,6 +92,7 @@ GEM
     drb (2.2.1)
     erubi (1.13.1)
     ffi (1.17.1-arm64-darwin)
+    ffi (1.17.1-x86_64-darwin)
     ffi (1.17.1-x86_64-linux-gnu)
     formatador (1.1.0)
     globalid (1.2.1)
@@ -146,6 +147,8 @@ GEM
     nio4r (2.7.4)
     nokogiri (1.18.9-arm64-darwin)
       racc (~> 1.4)
+    nokogiri (1.18.9-x86_64-darwin)
+      racc (~> 1.4)
     nokogiri (1.18.9-x86_64-linux-gnu)
       racc (~> 1.4)
     notiffany (0.1.3)
@@ -233,6 +236,7 @@ GEM
     securerandom (0.3.1)
     shellany (0.0.1)
     sqlite3 (2.7.3-arm64-darwin)
+    sqlite3 (2.7.3-x86_64-darwin)
     sqlite3 (2.7.3-x86_64-linux-gnu)
     stringio (3.1.1)
     thor (1.3.2)
@@ -252,6 +256,7 @@ PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-24
+  x86_64-darwin-21
   x86_64-linux
 
 DEPENDENCIES