bulma-phlex 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afb300daa04f06472595582cc1bdfba1728e33dfcecd5c12b8d9d96ac0a595cb
-  data.tar.gz: 34d233c24acc831cb2d62544bd589e0635664be90703c65775aa0b0cc4e9fcdb
+  metadata.gz: 3136a7a0dd22a5d85922b80419ece937d391f6cbd385ba668079eb65d4387a61
+  data.tar.gz: 7553361a230fff3ecd6f121f6ec985348e4fc767a5f3927b27178676dea4de98
 SHA512:
-  metadata.gz: e4d8a16c89010c53770305c8851c43b02f6edc084713945977934a9376854a670a1950e8e710b5f4be38f7455817bcac44eb81cc4c15e228fb7b6d2dc64213b8
-  data.tar.gz: 5e3368563f12815dfce93fa79ea568b60369dd186b00202d6891aecea9c5831ccc3388cffb77a88b4edb0bcb5ff79ad5f5f2aedbb054ca95288db582cd3d35fa
+  metadata.gz: d500797827a0ef15b9ad2f5ef334d63440cce5f8501ad90b8a9e93e0bb2a3ff0edf71eadf9a47aa47e7ef2ba570418a50250a3c586e106f631a45763c8bfe096
+  data.tar.gz: f62d2ae5b7c9dbba1fc3d73a775859ede75491d78faf2b6134aa34ed0101aad3991c3e1ee3555a41fa9fd7def98e18dcd026cd8e8c6909b3e7d0a44cda94dbf0

data/README.md

@@ -26,11 +26,13 @@ Finally, the optional Rails extensions for the Card and Table components have be
 - [Usage](#usage)
   - [Card](#card)
   - [Dropdown](#dropdown)
+  - [Form Field](#form-field)
   - [Level](#level)
   - [NavigationBar](#navigationbar)
   - [Pagination](#pagination)
   - [Table](#table)
   - [Tabs](#tabs)
+  - [Tag](#tag)
   - [Title and Subtitle](#title-and-subtitle)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -137,6 +139,36 @@ end
 - `item(content = nil, &block)`: Adds a custom item (string or block).
 - `divider`: Adds a divider line.
 
+
+### Form Field
+
+The [Form Field](https://bulma.io/documentation/form/general/) component provides a way to create form fields with labels, inputs, and help text, following Bulma's form styling conventions. It also supports adding icons to the input, as well as tagging the field as a column or grid cell.
+
+```ruby
+BulmaPhlex::FormField(help: "We'll never share your email.") do |field|
+  field.label("Email Address")
+  field.control { input(name: "user[email_address]", type: "email") }
+end
+```
+
+The label can be passed in as a string or created with a block:
+
+```ruby
+  field.label do
+    span { "Email Address" }
+    span(class: "has-text-danger") { "*" }
+  end
+```
+
+**Constructor Keyword Arguments:**
+
+- `icon_left`: Icon class to display on the left side of the input (such as `fas fa-user`).
+- `icon_right`: Icon class to display on the right side of the input.
+- `help`: Help text to display below the field.
+- `column`: When true, adds the `column` class to the container. Can also be a string specifying the column size (such as `two-thirds`) or a hash with sizes by breakpoint (such as `{ mobile: "full", desktop: "half" }`).
+- `grid`: When true, adds the `cell` class to the container. Can also be a string specifying the heighth or width of the cell (such as `col-span-3`).
+
+
 ### Level
 
 The [Level](https://bulma.io/documentation/layout/level/) component provides a flexible horizontal layout system with left and right alignment.
@@ -195,13 +227,19 @@ end
 The [Pagination](https://bulma.io/documentation/components/pagination/) component provides navigation controls for paginated content, including previous/next links, page number links, and a summary of items being displayed.
 
 ```ruby
-# In a controller action:
-@products = Product.page(params[:page]).per(20)
-
-# In the view:
 BulmaPhlex::Pagination(@products, ->(page) { products_path(page: page) })
 ```
 
+In order to support pagination, the argument passed into the constructor must repond with integers to the following:
+
+- current_page
+- total_pages
+- per_page
+- total_count
+- previous_page (can be nil)
+- next_page (can be nil)
+
+
 ### Table
 
 The [Table](https://bulma.io/documentation/elements/table/) component provides a way to display data in rows and columns with customizable headers and formatting options.
@@ -272,16 +310,7 @@ If the table should be paginated, invoke method `paginate` with a block that wil
   end
 ```
 
-In order to support pagination, the `rows` argument passed into the constructor must repond with integers to the following:
-
-- current_page
-- total_pages
-- per_page
-- total_count
-- previous_page (can be nil)
-- next_page (can be nil)
-
-This generates the [Bulma pagination](https://bulma.io/documentation/components/pagination/) component, providing navigation controls for paginated content.
+This generates the [Bulma pagination](https://bulma.io/documentation/components/pagination/) component, providing navigation controls for paginated content. The rows argument is passed into the Pagination component to determine the current page, total pages, and other pagination details.
 
 
 ### Tabs

data/lib/bulma_phlex/form_control.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # # Form Control
+  #
+  # The Bulma Form Control is used to wrap form elements like inputs, selects, and textareas. Additional classes can
+  # be added via the `classes` argument.
+  #
+  # ## References
+  # - [Bulma Form Control](https://bulma.io/documentation/form/general/#form-control)
+  class FormControl < Phlex::HTML
+    def initialize(**attributes)
+      @attributes = attributes.compact
+    end
+
+    def view_template(&)
+      div(**mix({ class: "control" }, @attributes), &)
+    end
+  end
+end

data/lib/bulma_phlex/form_field.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # # Form Field Component
+  #
+  # The Bulma Form Field is a `field` container that groups a label with yielded content
+  # (usually an input). It can optionally include a help text.
+  #
+  # The label can be provided either as a string argument to the `label` method or as a
+  # block. If a string is provided, it will be rendered inside a `<label>` tag with the
+  # `label` class. The label can also be omitted entirely if not needed.
+  #
+  # ## Icons
+  #
+  # The component supports optional left and right icons within the input control. Specify
+  # icons with the `icon_left` and `icon_right` keyword arguments.
+  #
+  # ```ruby
+  # FormField(icon_left: "fas fa-user", icon_right: "fas fa-check")
+  # ```
+  #
+  # ## Column Layout
+  #
+  # If the form field is to be used within a Bulma column layout, you can specify the `column`
+  # keyword. There are three ways to use this:
+  # - `true`: makes the field a column without specific sizing.
+  # - a size string (e.g., `"half"`): makes the field a column with that size for all breakpoints.
+  # - a hash mapping breakpoints to sizes (e.g., `{ mobile: "full", desktop: "half" }`): makes the
+  #   field a column with sizes specific to breakpoints
+  #
+  # ## Example Usage
+  #
+  # Here is the label provided as a block:
+  #
+  # ```ruby
+  # FormField(help: "Enter the project name.") do |field|
+  #   field.label { label "Project Name" }
+  #   field.input { input id: "project_name", name: "project[name]", type: "text" }
+  # end
+  # ```
+  #
+  # Here is the label provided as a string:
+  #
+  # ```ruby
+  # FormField(help: "Enter the project name.") do |field|
+  #   field.label "Project Name"
+  #   field.input { input id: "project_name", name: "project[name]", type: "text" }
+  # end
+  # ```
+  #
+  # Here is no label provided:
+  #
+  # ```ruby
+  # FormField(help: "Enter the project name.") do |field|
+  #   field.input { input id: "project_name", name: "project[name]", type: "text" }
+  # end
+  # ```
+  #
+  # ## References
+  #
+  # - [Bulma Form Field](https://bulma.io/documentation/form/general/#form-field)
+  #   - [With Icons](https://bulma.io/documentation/form/general/#with-icons)
+  # - [Columns](https://bulma.io/documentation/columns/basics/)
+  # - [Grid Cells](https://bulma.io/documentation/grid/grid-cells/)
+  class FormField < Phlex::HTML
+    def initialize(help: nil, icon_left: nil, icon_right: nil, column: nil, grid: nil)
+      @help = help
+      @icon_left = icon_left
+      @icon_right = icon_right
+      @column = column
+      @grid = grid
+    end
+
+    # in order to use the method name `label`, we need to grab a reference to the method on the base class
+    # so it is stil available to us
+    alias html_label label
+
+    def label(label_string = nil, &block)
+      @label_string = label_string
+      @label_builder = block
+    end
+
+    def control(&block)
+      @control_builder = block
+    end
+
+    def view_template(&)
+      vanish(&)
+
+      div(class: field_classes) do
+        render_label
+        render FormControl.new(class: control_classes) do
+          render raw @control_builder.call
+          Icon(@icon_left, size: :small, left: true) if @icon_left
+          Icon(@icon_right, size: :small, right: true) if @icon_right
+        end
+        p(class: "help") { @help } if @help
+      end
+    end
+
+    private
+
+    def field_classes
+      [:field].tap do |classes|
+        classes.append(column_classes) if @column
+        classes.append(grid_classes) if @grid
+      end
+    end
+
+    def column_classes
+      [:column].tap do |classes|
+        if @column.is_a?(String) || @column.is_a?(Integer)
+          classes << "is-#{@column}"
+        elsif @column.is_a?(Hash)
+          @column.each do |breakpoint, size|
+            classes << "is-#{size}-#{breakpoint}"
+          end
+        end
+      end
+    end
+
+    def grid_classes
+      if @grid.is_a?(String)
+        [:cell, "is-#{@grid}"]
+      else
+        [:cell]
+      end
+    end
+
+    def render_label
+      if @label_string
+        html_label(class: "label") { @label_string }
+      elsif @label_builder
+        render raw @label_builder&.call
+      end
+    end
+
+    def control_classes
+      [].tap do |classes|
+        classes << "has-icons-left" if @icon_left
+        classes << "has-icons-right" if @icon_right
+      end
+    end
+  end
+end

data/lib/bulma_phlex/icon.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # # Icon
+  #
+  # This component implements the
+  # [Bulma icon element](https://bulma.io/documentation/elements/icon/).
+  #
+  # ## Options
+  #
+  # - `color`: Sets the [color of the icon](https://bulma.io/documentation/elements/icon/#colors)
+  # - `size`: Sets the [size of the icon](https://bulma.io/documentation/elements/icon/#sizes)
+  # - `text_right`: Text to display to the right of the icon
+  # - `text_left`: Text to display to the left of the icon
+  # - `left`: If true, adds the `is-left` class for use in form controls
+  # - `right`: If true, adds the `is-right` class for use in form controls
+  #
+  # ## Example
+  #
+  # ```ruby
+  # BulmaPhlex::Icon.new("fas fa-home")
+  # BulmaPhlex::Icon.new("fas fa-home", color: :primary, size: :large, text_right: "Home")
+  # ```
+  class Icon < BulmaPhlex::Base
+    def initialize(icon, # rubocop:disable Metrics/ParameterLists
+                   text_right: nil,
+                   text_left: nil,
+                   size: nil,
+                   color: nil,
+                   left: false,
+                   right: false)
+      @icon = icon
+      @text_right = text_right
+      @text_left = text_left
+      @size = size
+      @color = color
+      @left = left
+      @right = right
+    end
+
+    def view_template
+      optional_text_wrapper do
+        span { @text_left } if @text_left
+        span(class: icon_classes) do
+          i(class: @icon)
+        end
+        span { @text_right } if @text_right
+      end
+    end
+
+    private
+
+    def optional_text_wrapper(&)
+      if @text_right || @text_left
+        span(class: "icon-text", &)
+      else
+        yield
+      end
+    end
+
+    def icon_classes
+      classes = ["icon"]
+      classes << "is-#{@size}" if @size
+      classes << "has-text-#{@color}" if @color
+      classes << "is-left" if @left
+      classes << "is-right" if @right
+      classes.join(" ")
+    end
+  end
+end

data/lib/bulma_phlex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BulmaPhlex
-  VERSION = "0.8.2"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bulma-phlex
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Todd Kummer
 bindir: bin
 cert_chain: []
-date: 2026-01-16 00:00:00.000000000 Z
+date: 2026-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex
@@ -67,6 +67,9 @@ files:
 - lib/bulma_phlex/base.rb
 - lib/bulma_phlex/card.rb
 - lib/bulma_phlex/dropdown.rb
+- lib/bulma_phlex/form_control.rb
+- lib/bulma_phlex/form_field.rb
+- lib/bulma_phlex/icon.rb
 - lib/bulma_phlex/level.rb
 - lib/bulma_phlex/navigation_bar.rb
 - lib/bulma_phlex/navigation_bar_dropdown.rb