bulma-phlex-rails 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44794453fc2f23bad30359fbe4c2334a3f01f492e883d149752eb7855d22926e
-  data.tar.gz: 63fafad11cdb41bb3c26e768bb9042faea483befb1802c0741b9c054cd9262a9
+  metadata.gz: 39faa4f9308c253fc3ee0c25e584fc0381ccce026a07cb3790467d0568a128fd
+  data.tar.gz: fc56dde51af79f608200b67d8efa1c2fb09f0079298bfb7ac3e8b366b5baf2fc
 SHA512:
-  metadata.gz: 88e3734a644ae73ccde892ddbae655a6e3f5e18ae1d3ec5ed951822d4ec3a1c4bd903f0f315e8811860929d4e473894e4dfd536da4c39b12bad59230459036d4
-  data.tar.gz: f36bcded467eacbc374f08b75a8033aa0e9089de882f2363c9d51f547803b7b9586478ddbdb2377ec4bb2f3091b967a6bd901f18a184b85cdeae3d170268b0d4
+  metadata.gz: 11f36f93ef95547edc84227583f99925a16c61209eb0af39722a0b1c5b77499d1be079536133a7a36115492d957ac3a55bb9bf214e9aeed8cb0bb231677479ac
+  data.tar.gz: 3bf6f35846e31edd272faecd6764640f5b18435e605649fb5775030006329d6af8f830b9631537f364be7f8215e88168814c6de49aa46d6c2d15eb76c9606914

data/app/javascript/controllers/bulma_phlex/nested_forms_add_row_controller.js

@@ -0,0 +1,50 @@
+import { Controller } from "@hotwired/stimulus";
+
+//
+// The controller also supports mixins, which are additional behaviors that can be added to the
+// controller. Mixins are defined in the application customControllerConfiguration and can be
+// used to extend the functionality of the controller. Mixins are defined as objects with a
+// beforeAdd method, which is called before the add action is executed. The mixin can modify the
+// template before it is added to the container. The mixin can also return false to prevent the
+// add action from being executed.
+export default class extends Controller {
+  static values = {
+    templateId: String,
+    containerSelector: String,
+    position: { type: String, default: "beforeend" },
+    mixin: String,
+  };
+
+  initialize() {
+    if (this.hasMixinValue) {
+      const controllerMixins = this.application.customControllerConfiguration[this.identifier];
+
+      if (controllerMixins && controllerMixins[this.mixinValue]) {
+        Object.assign(this, controllerMixins[this.mixinValue]);
+      } else {
+        console.warn(`Mixin '${this.mixinValue}' not found for ${this.identifier} controller`);
+      }
+    }
+  }
+
+  add(event) {
+    const template = this.templateTarget.cloneNode(true);
+
+    if (this.beforeAdd(event, template.content)) {
+      const content = template.innerHTML.replace(/NEW_RECORD/g, new Date().getTime().toString());
+      this.containerTarget.insertAdjacentHTML(this.positionValue, content);
+    }
+  }
+
+  beforeAdd(_event, _node) {
+    return true;
+  }
+
+  get templateTarget() {
+    return document.getElementById(this.templateIdValue);
+  }
+
+  get containerTarget() {
+    return document.querySelector(this.containerSelectorValue);
+  }
+}

data/app/javascript/controllers/bulma_phlex/nested_forms_delete_row_controller.js

@@ -0,0 +1,34 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static values = {
+    rowSelector: String,
+  };
+
+  remove(event) {
+    event.preventDefault();
+
+    const row = this.#surroundingRow(event);
+    const parent = row.parentElement;
+    if (row) {
+      row.remove();
+      this.dispatch("row-removed", { target: parent });
+    }
+  }
+
+  markForDestruction(event) {
+    event.preventDefault();
+    const row = this.#surroundingRow(event);
+    const destroyField = row.querySelector('input[name*="_destroy"]');
+
+    if (destroyField) {
+      destroyField.value = true;
+      row.classList.add("is-hidden");
+      this.dispatch("row-marked-for-destruction", { detail: { row: row } });
+    }
+  }
+
+  #surroundingRow(event) {
+    return event.target.closest(this.rowSelectorValue);
+  }
+}

data/lib/bulma_phlex/rails/components/checkbox.rb

@@ -35,12 +35,10 @@ module BulmaPhlex
       end
 
       def view_template
-        render FormField.new(**@form_field_options) do |f|
-          f.control do
-            @form_builder.label(@method, nil, class: "checkbox", skip_label_class: true) do |label_builder|
-              raw @delivered.call(@options)
-              render_label(label_builder)
-            end
+        render FormField.new(**@form_field_options) do
+          @form_builder.label(@method, nil, class: "checkbox", skip_label_class: true) do |label_builder|
+            raw @delivered.call(@options)
+            render_label(label_builder)
           end
         end
       end

data/lib/bulma_phlex/rails/components/displays/base_display.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Base Display
+    #
+    # Base class for read-only display fields styled with Bulma.
+    #
+    # This allows the model to be passed via the `model:` option
+    # or as the first argument. When the model is passed as an option,
+    # the method is assumed to be the first argument.
+    class BaseDisplay < BulmaPhlex::Base
+      # Keyword arguments accepted by BulmaPhlex::FormField
+      FORM_FIELD_OPTIONS = BulmaPhlex::FormField
+                           .instance_method(:initialize)
+                           .parameters
+                           .map { |_, name| name }
+                           .freeze
+
+      def initialize(model, method = nil, **options)
+        @model = options.fetch(:model, model)
+        @method = method || model
+        @options = options
+      end
+
+      def view_template
+        form_field_options = @options.slice(*FORM_FIELD_OPTIONS)
+        BulmaPhlex::FormField(**form_field_options) do |field|
+          field.label { label(class: "label") { label_text } }
+          field.control { control_content }
+        end
+      end
+
+      private
+
+      def label_text
+        model_name = @model.class.name.parameterize(separator: "_")
+        ActionView::Helpers::Tags::Translator.new(@model, model_name, @method, scope: "helpers.label").translate
+      end
+
+      def control_content
+        input type: "text", class: "input is-light", value: formatted_value, readonly: :readonly
+      end
+
+      def value
+        @model.public_send(@method)
+      end
+
+      def formatted_value
+        raise NotImplementedError, "Subclasses must implement the formatted_value method"
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/components/displays/currency_display.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Currency Display
+    #
+    # A read-only display field styled with Bulma that formats a numeric value as
+    # currency. This component leverages Rails' `number_to_currency` helper
+    # for formatting.
+    #
+    # Currency options can be passed as a hash to customize the formatting.
+    #
+    # #### Arguments
+    #
+    # - `model`: ActiveRecord Model - The model containing the currency attribute. This can also be passed
+    #   via the `options` (helpful when using `with_options`).
+    # - `method`: Symbol or String - The attribute method name for the currency field.
+    # - `options`: Hash - Additional options for the display field. This can include the
+    #   `currency_options` key, which should be a hash of options passed to `number_to_currency`.
+    class CurrencyDisplay < BaseDisplay
+      include Phlex::Rails::Helpers::NumberToCurrency
+
+      def initialize(model, method = nil, **options)
+        super(model, method, **options.except(:currency_options))
+        @currency_options = options.fetch(:currency_options, {})
+      end
+
+      private
+
+      def formatted_value
+        number_to_currency(value, @currency_options)
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/components/displays/formatted_display.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Formatted Display
+    #
+    # A read-only display field styled with Bulma. This requires a `format` option,
+    # which will be passed to `to_fs` for formatting the value.
+    #
+    # #### Arguments
+    #
+    # - `model`: ActiveRecord Model - The model containing the attribute to display.
+    # - `method`: Symbol or String - The attribute method name for the field.
+    # - `options`: Hash - Additional Bulma form field options can be passed, such as `:help`,
+    #   `:icon_left`, `:icon_right`, `:column`, and `:grid`. Include a `format` key to specify
+    #   the format to use with `to_fs`.
+    class FormattedDisplay < TextDisplay
+      def initialize(model, method = nil, **options)
+        super(model, method, **options.except(:format))
+        @format = options.fetch(:format, :default)
+      end
+
+      private
+
+      def formatted_value
+        value.to_fs(@format)
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/components/displays/text_display.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Text Display
+    #
+    # A read-only text display field styled with Bulma.
+    #
+    # An optional formatter can be provided to customize the display of the text
+    # value, such as &:titleize or a custom lambda.
+    #
+    # #### Arguments
+    #
+    # - `model`: ActiveRecord Model - The model containing the text attribute.
+    # - `method`: Symbol or String - The attribute method name for the text field.
+    # - `options`: Hash - Additional Bulma form field options can be passed, such as `:help`,
+    #   `:icon_left`, `:icon_right`, `:column`, and `:grid`. Use the `formatter` key to provide
+    #   a block or lambda for custom text formatting.
+    class TextDisplay < BaseDisplay
+      def initialize(model, method, **options)
+        super(model, method, **options.except(:formatter))
+        @formatter = options[:formatter]
+      end
+
+      private
+
+      def formatted_value
+        text = value.to_s
+        @formatter ? @formatter.call(text) : text
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/components/nested_form_add_button.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Nested Form Add Button Component
+    #
+    # This button can be added to a form to allow users to dynamically add new nested form rows. It uses
+    # the Stimulus controller NestedFormsAddRow to handle the addition logic.
+    #
+    # #### Arguments
+    #
+    # - `template_id`: String - The ID of the `<template>` element that contains the nested form fields to be added.
+    # - `container_selector`: String - A CSS selector that identifies the container element where new rows should
+    #   be added.
+    # - `label`: String (optional) - The text label to display on the button.
+    # - `icon_left`: String (optional) - The name of an icon to display on the left side of the button.
+    # - `icon_right`: String (optional) - The name of an icon to display on the right side of the button.
+    class NestedFormAddButton < BulmaPhlex::Base
+      def initialize(template_id:, # rubocop:disable Metrics/ParameterLists
+                     container_selector:,
+                     label: nil,
+                     icon_left: nil,
+                     icon_right: nil,
+                     **html_attributes)
+        @template_id = template_id
+        @label = label
+        @icon_left = icon_left
+        @icon_right = icon_right
+        @container_selector = container_selector
+        @html_attributes = html_attributes
+      end
+
+      def view_template
+        render BulmaPhlex::FormField.new(icon_right: @icon) do
+          button(**mix({ type: "button", class: "button", data: stimulus_controller }, @html_attributes)) do
+            render BulmaPhlex::Icon(@icon_left) if @icon_left
+            span { @label } if @label
+            render BulmaPhlex::Icon(@icon_right) if @icon_right
+          end
+        end
+      end
+
+      private
+
+      def stimulus_controller
+        { controller: "bulma-phlex--nested-forms-add-row",
+          bulma_phlex__nested_forms_add_row_container_selector_value: @container_selector,
+          bulma_phlex__nested_forms_add_row_template_id_value: @template_id,
+          action: "bulma-phlex--nested-forms-add-row#add" }
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/components/nested_form_delete_button.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Nested Form Delete Button Component
+    #
+    # This button can be added to a nested form row to allow users to remove the row. It uses
+    # the Stimulus controller NestedFormsDeleteRow to handle the deletion logic.
+    #
+    # #### Arguments
+    #
+    # - `row_selector`: String - A CSS selector that identifies the row to be deleted. This is
+    #   passed to the element's `closest` method to find the row element.
+    # - `action`: String - The action to perform when the button is clicked. This should correspond
+    #   to a method in the NestedFormsDeleteRow Stimulus controller. Either "remove" to remove the row
+    #   from the DOM, or "markForDestruction" to mark the row for destruction (for existing records).
+    # - `label`: String (optional) - The text label to display on the button.
+    # - `icon_left`: String (optional) - The name of an icon to display on the left side of the button.
+    # - `icon_right`: String (optional) - The name of an icon to display on the right side of the button.
+    class NestedFormDeleteButton < BulmaPhlex::Base
+      def initialize(row_selector:, # rubocop:disable Metrics/ParameterLists
+                     action:,
+                     label: nil,
+                     icon_left: nil,
+                     icon_right: nil,
+                     **html_attributes)
+        @label = label
+        @icon_left = icon_left
+        @icon_right = icon_right
+        @row_selector = row_selector
+        @action = action
+        @html_attributes = html_attributes
+      end
+
+      def view_template
+        render BulmaPhlex::FormField.new(icon_right: @icon) do
+          button(**mix({ type: "button", class: "button", data: stimulus_controller }, @html_attributes)) do
+            render BulmaPhlex::Icon(@icon_left) if @icon_left
+            span { @label } if @label
+            render BulmaPhlex::Icon(@icon_right) if @icon_right
+          end
+        end
+      end
+
+      private
+
+      def stimulus_controller
+        { controller: "bulma-phlex--nested-forms-delete-row",
+          bulma_phlex__nested_forms_delete_row_row_selector_value: @row_selector,
+          action: "bulma-phlex--nested-forms-delete-row##{@action}" }
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/components/radio_button.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Radio Button Component
+    #
+    # This component renders a Bulma-styled radio button within a form. It integrates with Rails' form builder
+    # to ensure proper labeling and value handling.
+    #
+    # The label is looked up using I18n based on the method and tag value. The key is the combination of the
+    # method name and the tag value, formatted as `method_tagvalue`, under the scope `helpers.label.object_name`.
+    # If no translation is found, it defaults to a humanized version of the tag value.
+    #
+    # Example usage:
+    # ```ruby
+    # form_with model: @project do |f|
+    #  f.radio_button :status, "active"
+    #  f.radio_button :status, "archived"
+    # end
+    class RadioButton < BulmaPhlex::Base
+      def initialize(form_builder, method, tag_value, options, delivered)
+        @form_builder = form_builder
+        @method = method
+        @tag_value = tag_value
+        @options = options.dup
+        @delivered = delivered
+
+        @options[:class] = Array.wrap(@options[:class]) << "mr-2"
+        @form_field_options = @options.extract!(:column, :grid)
+                                      .with_defaults(column: @form_builder.columns_flag,
+                                                     grid: @form_builder.grid_flag)
+      end
+
+      def view_template
+        render FormField.new(**@form_field_options) do
+          label(class: "radio") do
+            raw @delivered.call(@options)
+            plain label_from_tag_value
+          end
+        end
+      end
+
+      private
+
+      def label_from_tag_value
+        key = [@method, @tag_value.to_s.downcase.gsub(/\s+/, "_")].join("_")
+        I18n.translate(key, scope: [:helpers, :label, @form_builder.object_name],
+                            default: @tag_value.to_s.humanize)
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/concerns/displayable_block_options.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Displayable Block Options
+    #
+    # This concern provides methods to manage display options for Bulma Phlex components,
+    # specifically for displayable blocks such as read-only form fields. It allows options
+    # to be set for groups of fields, enabling consistent styling and layout.
+    #
+    # #### Included Methods
+    #
+    # - `with_options` - Wrap a block with specific options for displayable fields.
+    # - `in_columns` - Wrap a block to display fields in Bulma columns.
+    # - `in_grid` - Wrap a block to display fields in a Bulma grid.
+    module DisplayableBlockOptions
+      # Wrap a block with specific options for displayable fields. This allows redundant
+      # options to be specified once for multiple fields. These options are merged with
+      # any options passed directly to the individual field methods.
+      #
+      # If the `:columns` or `:grid` option is provided, the block will be wrapped
+      # in a Bulma `columns` or `grid` container, respectively.
+      #
+      # Blocks can be nested, with inner block options overriding outer block options.
+      #
+      # #### Example
+      #
+      #     with_options(model: @user, column: true) do
+      #       show_text(:username)
+      #       show_date(birthdate, format: :short)
+      #     end
+      def with_options(**block_options, &)
+        (@_block_display_options ||= BlockDisplayOptions.new).push(block_options)
+
+        if @_block_display_options.column?
+          render BulmaPhlex::Columns.new(**@_block_display_options.column_options, &)
+        elsif @_block_display_options.grid?
+          render BulmaPhlex::Grid.new(**@_block_display_options.grid_options, &)
+        else
+          yield
+        end
+
+        @_block_display_options.pop
+      end
+
+      # Retrieve the current block display options.
+      def block_display_options
+        @_block_display_options&.current || {}
+      end
+
+      # Wrap a block to display fields in Bulma columns. This adds a columns container
+      # and sets the `column: true` option for any `show_` fields within the block.
+      #
+      # This is a shorthand for `with_options(column: true) do`.
+      def in_columns(options = true, &) # rubocop:disable Style/OptionalBooleanParameter
+        with_options(columns: options, &)
+      end
+
+      # Wrap a block to display fields in a Bulma grid. This adds a grid container
+      # and sets the `grid: true` option for any `show_` fields within the block.
+      #
+      # You can optionally pass in any [Grid options](https://github.com/RockSolt/bulma-phlex#grid) as a hash.
+      def in_grid(options = true, &) # rubocop:disable Style/OptionalBooleanParameter
+        with_options(grid: options, &)
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/concerns/displayable_form_fields.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Displayable Form Fields
+    #
+    # Phlex component mixin to provide displayable form fields to views. These read-only
+    # fields provide the same Bulma styling as standard form fields, but are intended for
+    # displaying data rather than accepting user input.
+    #
+    # #### Included Methods
+    #
+    # - `show_currency` - Display a currency field in a read-only Bulma-styled format.
+    # - `show_date` - Display a date field in a read-only Bulma-styled format.
+    # - `show_text` - Display a text field in a read
+    module DisplayableFormFields
+      include BulmaPhlex::Rails::DisplayableBlockOptions
+
+      # Display a currency field in a read-only Bulma-styled format. Include a `currency_format` option
+      # to customize the currency format, which will be passed to Rails' `number_to_currency` helper.
+      #
+      # #### Arguments
+      #
+      # - `model`: ActiveRecord Model - The model containing the currency attribute. This can also be passed
+      #   via the `options` (helpful when using `with_options`).
+      # - `method`: Symbol or String - The attribute method name for the currency field.
+      # - `options`: Hash - Additional options for the display field. This can include the
+      #   `currency_options` key, which should be a hash of options passed to `number_to_currency`.
+      #
+      # #### Example
+      #
+      #     show_currency(@order, :total_amount)
+      #     show_currency(@product, :price, currency_options: { unit: "€", precision: 2 })
+      def show_currency(model, method = nil, **options)
+        render BulmaPhlex::Rails::CurrencyDisplay.new(model, method,
+                                                      **options.with_defaults(block_display_options))
+      end
+
+      # Display a date field in a read-only Bulma-styled format. Include a `format` option
+      # to customize the date format, which will be passed to `to_fs`.
+      # Defaults to `:long` format.
+      #
+      # #### Arguments
+      #
+      # - `model`: ActiveRecord Model - The model containing the date attribute. This can also be passed
+      #   via the `options` (helpful when using `with_options`).
+      # - `method`: Symbol or String - The attribute method name for the date field.
+      # - `options`: Hash - Additional options for the display field. This can include the `format` key, which gets
+      #    passed to `to_fs`.
+      #
+      # #### Example
+      #
+      #     show_date(@user, :birthdate, format: :short)
+      #     show_date(@event, :start_time)
+      #     show_date(:scheduled_at, model: @appointment, format: "%B %d, %Y")
+      def show_date(model, method = nil, **options)
+        date_options = options.with_defaults(format: :long)
+                              .with_defaults(block_display_options)
+        render BulmaPhlex::Rails::FormattedDisplay.new(model, method, **date_options)
+      end
+
+      # Display a text field in a read-only Bulma-styled format. A custom formatter
+      # block can be provided to modify the displayed text.
+      #
+      # #### Arguments
+      # - `model`: ActiveRecord Model - The model containing the text attribute. This can also be passed
+      #   via the `options` (helpful when using `with_options`).
+      # - `method`: Symbol or String - The attribute method name for the text field.
+      # - Additional Bulma form field options can be passed, such as `:help`, `:icon_left`, `:icon_right`,
+      #   `:column`, and `:grid`.
+      #
+      # #### Example
+      #
+      #     show_text(@user, :username)
+      #     show_text(@article, :title, &:titleize)
+      #     show_text(:email, model: @contact, help: "Primary contact email")
+      def show_text(model, method = nil, **options, &formatter)
+        text_options = options.with_defaults(block_display_options)
+        render BulmaPhlex::Rails::TextDisplay.new(model, method, **text_options, formatter: formatter)
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/concerns/nested_forms.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Nested Forms
+    #
+    # This modules provides support for nested forms. It overrides the `fields_for` method to
+    # capture the block for nested attributes then creates a template for adding new nested
+    # records dynamically when the `nested_form_add_button` method is called.
+    #
+    # The nested form can also include a delete button for each row using the
+    # `nested_form_delete_button` method.
+    module NestedForms
+      extend ActiveSupport::Concern
+
+      included do
+        attr_reader :nested_forms_add_buttons, :nested_forms_templates
+      end
+
+      def fields_for(record_name, record_object = nil, fields_options = {}, &block)
+        output = super
+
+        if (record_name.is_a?(Symbol) || record_name.is_a?(String)) && nested_attributes_association?(record_name)
+          if @nested_forms_add_buttons&.include?(record_name)
+            output += build_fields_for_template(record_name, fields_options, &block)
+          else
+            (@nested_forms_templates ||= {}).store(record_name, [fields_options, block])
+          end
+        end
+
+        output
+      end
+
+      # Add a button to add new nested form rows dynamically.
+      #
+      # #### Arguments
+      #
+      # - `record_name`: Symbol or String - The name of the nested association (e.g., :tasks).
+      # - `container`: String - A CSS selector that identifies the container element where new rows
+      #   should be added.
+      # - `label`: String (optional) - The text label to display on the button.
+      # - `icon`: String (optional) - The name of an icon to display on the button (appears on the left by default).
+      # - `icon_left`: String (optional) - The name of an icon to display on the left side of the button.
+      # - `icon_right`: String (optional) - The name of an icon to display on the right side of the button.
+      # - Additional HTML attributes can be passed via `html_attributes`.
+      def nested_form_add_button(record_name, # rubocop:disable Metrics/ParameterLists
+                                 container:,
+                                 label: nil,
+                                 icon: nil,
+                                 icon_left: nil,
+                                 icon_right: nil,
+                                 **html_attributes)
+        button_html = build_nested_form_add_button(record_name, container, label, icon_left || icon, icon_right,
+                                                   html_attributes)
+
+        if @nested_forms_templates&.key?(record_name)
+          field_options, block = @nested_forms_templates[record_name]
+          button_html + build_fields_for_template(record_name, field_options, &block)
+        else
+          (@nested_forms_add_buttons ||= []) << record_name
+          button_html
+        end
+      end
+
+      # Add a button to delete a nested form row.
+      #
+      # #### Arguments
+      #
+      # - `row_selector`: String - A CSS selector that identifies the row to be deleted. This is
+      #   passed to the element's `closest` method to find the row element.
+      # - `label`: String (optional) - The text label to display on the button.
+      # - `icon`: String (optional) - The name of an icon to display on the button (appears on the left by default).
+      # - `icon_left`: String (optional) - The name of an icon to display on the left side of the button.
+      # - `icon_right`: String (optional) - The name of an icon to display on the right side of the button.
+      # - Additional HTML attributes can be passed via `html_attributes`.
+      def nested_form_delete_button(row_selector:, # rubocop:disable Metrics/ParameterLists
+                                    label: nil,
+                                    icon: nil,
+                                    icon_left: nil,
+                                    icon_right: nil,
+                                    **html_attributes)
+        action = object.persisted? ? "markForDestruction" : "remove"
+
+        build_nested_form_delete_button(label, icon_left || icon, icon_right, row_selector, action, html_attributes) +
+          hidden_field(:_destroy)
+      end
+
+      private
+
+      def build_fields_for_template(record_name, fields_options, &block)
+        reflection = @object.class.reflect_on_association(record_name.to_sym)
+        new_record = reflection.klass.new
+
+        name = "#{@object_name}[#{record_name}_attributes][NEW_RECORD]"
+        @template.content_tag(:template, id: "#{@object_name}_#{record_name}_fields_template") do
+          fields_for_nested_model(name, new_record, fields_options.merge(child_index: "NEW_RECORD"), block)
+        end
+      end
+
+      def build_nested_form_add_button(record_name, # rubocop:disable Metrics/ParameterLists
+                                       container,
+                                       label,
+                                       icon_left,
+                                       icon_right,
+                                       html_attributes)
+        BulmaPhlex::Rails::NestedFormAddButton.new(
+          template_id: "#{@object_name}_#{record_name}_fields_template",
+          label: label,
+          icon_left: icon_left,
+          icon_right: icon_right,
+          container_selector: container,
+          **html_attributes
+        ).render_in(@template)
+      end
+
+      def build_nested_form_delete_button(label, # rubocop:disable Metrics/ParameterLists
+                                          icon_left,
+                                          icon_right,
+                                          row_selector,
+                                          action,
+                                          html_attributes)
+        BulmaPhlex::Rails::NestedFormDeleteButton.new(
+          label: label,
+          icon_left: icon_left,
+          icon_right: icon_right,
+          row_selector: row_selector,
+          action: action,
+          **html_attributes
+        ).render_in(@template)
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/form_builder.rb

@@ -12,7 +12,15 @@ module BulmaPhlex
     # - `icon_right`: If set, the specified icon will be rendered on the right side of the input.
     # - `column`: If true, the input will be wrapped in a Bulma column (only within a `columns` block).
     # - `grid`: If true, the input will be wrapped in a Bulma grid cell (only within a `grid` block).
+    #
+    # ## Nested Forms
+    #
+    # This form builder also includes support for nested forms. Invoke the `nested_form_add_button`
+    # method to add a button that allows users to dynamically add new nested form rows. Each
+    # nested form row can include a delete button using the `nested_form_delete_button` method.
     class FormBuilder < ActionView::Helpers::FormBuilder
+      include NestedForms
+
       attr_reader :columns_flag, :grid_flag
 
       def text_field(method, options = {}) = wrap_field(method, options) { |m, opts| super(m, opts) }
@@ -45,6 +53,11 @@ module BulmaPhlex
       end
       alias check_box checkbox
 
+      def radio_button(method, tag_value, options = {})
+        delivered = ->(opts) { super(method, tag_value, opts) }
+        RadioButton.new(self, method, tag_value, options, delivered).render_in(@template)
+      end
+
       # Override label to add Bulma's `label` class by default. Add `:skip_label_class` option
       # to skip adding the class.
       def label(method, text = nil, options = {}, &)
@@ -78,36 +91,55 @@ module BulmaPhlex
 
       # Fields declared in a column block will be wrapped in a Bulma column and carry
       # the `column` class by default (fields can use the `column` option to set sizes).
-      def columns(min_breakpoint = nil, &)
+      #
+      # ## Arguments
+      #
+      # - `minimum_breakpoint`: (Symbol, optional) Sets the minimum breakpoint for the columns; default is `:tablet`.
+      # - `multiline`: (Boolean, optional) If true, allows the columns to wrap onto multiple lines.
+      # - `gap`: (optional) Use an integer (0-8) to set the gap size between columns; use a hash keyed by breakpoints
+      #   to set responsive gap sizes.
+      # - `centered`: (Boolean, optional) If true, centers the columns.
+      # - `vcentered`: (Boolean, optional) If true, vertically centers the columns.
+      def columns(minimum_breakpoint: nil,
+                  multiline: false,
+                  gap: nil,
+                  centered: false,
+                  vcentered: false, &)
         @columns_flag = true
         columns = @template.capture(&)
         @columns_flag = false
 
-        @template.content_tag(:div, class: [:columns, min_breakpoint]) do
+        BulmaPhlex::Columns.new(minimum_breakpoint:, multiline:, gap:, centered:, vcentered:) do
           @template.concat(columns)
-        end
-      end
-
-      # Fields declared in a fixed_grid block will be wrapped in a Bulma fixed grid and
-      # carry the `grid` class by default (fields can use the `grid` option to set sizes).
-      def fixed_grid(&)
-        # TODO: Use BulmaPhlex::FixedGrid for more options
-        @template.content_tag(:div, class: "fixed-grid") do
-          grid(&)
-        end
+        end.render_in(@template)
       end
 
       # Fields declared in a grid block will be wrapped in a Bulma fixed grid and carry
       # the `grid` class by default (fields can use the `grid` option to set sizes).
-      def grid(&)
+      #
+      # ## Arguments
+      #
+      # - `fixed_columns`: (Integer, optional) Specifies a fixed number of columns for the grid.
+      # - `auto_count`: (Boolean, optional) If true, the grid will automatically adjust the number
+      #    of columns based on the content.
+      # - `minimum_column_width`: (Integer 1-32, optional) Sets a minimum width for the columns in the grid.
+      # - `gap`: (optional) Sets the gap size between grid items from 1-8 with 0.5 increments.
+      # - `column_gap`: (optional) Sets the column gap size between grid items from 1-8 with 0.5 increments.
+      # - `row_gap`: (optional) Sets the row gap size between grid items from 1-8 with 0.5 increments.
+      def grid(fixed_columns: nil, # rubocop:disable Metrics/ParameterLists
+               auto_count: false,
+               minimum_column_width: nil,
+               gap: nil,
+               column_gap: nil,
+               row_gap: nil,
+               &)
         @grid_flag = true
         cells = @template.capture(&)
         @grid_flag = false
 
-        # TODO: Use BulmaPhlex::Grid for more options
-        @template.content_tag(:div, class: "grid") do
+        BulmaPhlex::Grid.new(fixed_columns:, auto_count:, minimum_column_width:, gap:, column_gap:, row_gap:) do
           @template.concat(cells)
-        end
+        end.render_in(@template)
       end
 
       private

data/lib/bulma_phlex/rails/models/block_display_options.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Block Display Options
+    #
+    # This model enables options to be collected in a nested fashion. It translates
+    # column and grid options into a flags for the form fields and stores the full
+    # options for the column and grid containers.
+    #
+    # One small difference between the two is that the column options are specified
+    # with a plural (`columms`) in `with_options` but the flag that gets passed to the
+    # form fields is singular (`column: true`). For grid options, both are singular
+    # (`grid`).
+    class BlockDisplayOptions
+      def initialize
+        @stack = [{}]
+        @grid_options = []
+        @column_options = []
+      end
+
+      def push(options)
+        options = options.dup
+
+        # store the columns option, then add a boolean flag
+        @column_options.push(options.delete(:columns))
+        options[:column] = !!@column_options.last # rubocop:disable Style/DoubleNegation
+
+        # store the grid option, then convert it to a boolean flag
+        @grid_options.push(options[:grid])
+        options[:grid] = !!options[:grid] # rubocop:disable Style/DoubleNegation
+
+        @stack.push(current.merge(options))
+      end
+
+      def pop
+        @grid_options.pop
+        @stack.pop
+      end
+
+      def current
+        @stack.last
+      end
+
+      def column?
+        current[:column]
+      end
+
+      def grid?
+        current[:grid]
+      end
+
+      def column_options
+        return {} unless column?
+
+        opts = @column_options.last
+        opts == true ? {} : opts
+      end
+
+      def grid_options
+        return {} unless grid?
+
+        opts = @grid_options.last
+        opts == true ? {} : opts
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/version.rb

@@ -2,6 +2,6 @@
 
 module BulmaPhlex
   module Rails
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/bulma_phlex/rails.rb

@@ -13,6 +13,8 @@ end
 
 loader = Zeitwerk::Loader.for_gem_extension(BulmaPhlex)
 loader.collapse("#{__dir__}/rails/components")
+loader.collapse("#{__dir__}/rails/components/displays")
+loader.collapse("#{__dir__}/rails/concerns")
 loader.collapse("#{__dir__}/rails/helpers")
 loader.collapse("#{__dir__}/rails/models")
 loader.setup

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bulma-phlex-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Todd Kummer
 bindir: bin
 cert_chain: []
-date: 2026-01-31 00:00:00.000000000 Z
+date: 2026-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: phlex-rails
   requirement: !ruby/object:Gem::Requirement
@@ -65,8 +65,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.2'
-description: Create forms with Bulma CSS framework styles using Phlex components in
-  your Rails applications.
 email:
 - todd@rockridgesolutions.com
 executables: []
@@ -76,15 +74,28 @@ files:
 - app/javascript/controllers/bulma_phlex/dropdown_controller.js
 - app/javascript/controllers/bulma_phlex/file_input_display_controller.js
 - app/javascript/controllers/bulma_phlex/navigation_bar_controller.js
+- app/javascript/controllers/bulma_phlex/nested_forms_add_row_controller.js
+- app/javascript/controllers/bulma_phlex/nested_forms_delete_row_controller.js
 - app/javascript/controllers/bulma_phlex/tabs_controller.js
 - config/importmap.rb
 - lib/bulma-phlex-rails.rb
 - lib/bulma_phlex/rails.rb
 - lib/bulma_phlex/rails/components/checkbox.rb
+- lib/bulma_phlex/rails/components/displays/base_display.rb
+- lib/bulma_phlex/rails/components/displays/currency_display.rb
+- lib/bulma_phlex/rails/components/displays/formatted_display.rb
+- lib/bulma_phlex/rails/components/displays/text_display.rb
+- lib/bulma_phlex/rails/components/nested_form_add_button.rb
+- lib/bulma_phlex/rails/components/nested_form_delete_button.rb
+- lib/bulma_phlex/rails/components/radio_button.rb
+- lib/bulma_phlex/rails/concerns/displayable_block_options.rb
+- lib/bulma_phlex/rails/concerns/displayable_form_fields.rb
+- lib/bulma_phlex/rails/concerns/nested_forms.rb
 - lib/bulma_phlex/rails/engine.rb
 - lib/bulma_phlex/rails/form_builder.rb
 - lib/bulma_phlex/rails/helpers/card_helper.rb
 - lib/bulma_phlex/rails/helpers/table_helper.rb
+- lib/bulma_phlex/rails/models/block_display_options.rb
 - lib/bulma_phlex/rails/version.rb
 homepage: https://github.com/RockSolt/bulma-phlex-rails
 licenses:
@@ -108,5 +119,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Bulma-friendly form builder built with Phlex for Rails applications.
+summary: Simplify the view layer with a component library built on Phlex and styled
+  with Bulma CSS framework. The code is simple and the UI is clean.
 test_files: []