bulma-phlex 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 358df6739ab960f7d8b3799001c40b0d80a6e1c1d599b31b115b67bdcae46645
-  data.tar.gz: 54a368dec6bf6dfa7c21f32779e63651bea141070367880f7b1b938da86c92f3
+  metadata.gz: 6a4e33701b1ed15897b743789cc3fb1923fdaf70fd065035f8342836058927ed
+  data.tar.gz: 772252cf5d5660a0a926f4d24a2ffd73898947a6db4ce3f8ea880978acdda0bf
 SHA512:
-  metadata.gz: 81cea339f39b95a17bd43e18f294944327744c81601fb03d1d7e7975e397973ebfa488350540eeb008e587c74ae3805ce8ff3ec15aa193277bd68bae03cee201
-  data.tar.gz: 021f7fc3b32d02a16c1c08a695e915b8beca73219b86da9766c58077afa5b13e205d337fd2ccace80378905076ccb821d2c9c244313ace1c1c32c38752258045
+  metadata.gz: 7ec1799752698497e06b075b7378d18a3b820e80ec9e95c7448eb1999ac93514c785d6a61f95434ba02962edb103aa398bd6994506a0954804af52becb56f9ac
+  data.tar.gz: 4071dd6000764651b7a677d1ab6ac94c15b59043692602be997924ec094977f41eaf704222554e89ce33f0a49feadc65eeb680ef8c3d36963034995c7b867570

data/README.md

@@ -20,7 +20,9 @@ This gem provides a set of ready-to-use [Phlex](https://github.com/phlex-ruby/ph
   - [Grid](#grid)
   - [Hero](#hero)
   - [Icon](#icon)
+  - [Image](#image)
   - [Level](#level)
+  - [Media Object](#media-object)
   - [Message](#message)
   - [Modal](#modal)
   - [NavigationBar](#navigationbar)
@@ -74,7 +76,6 @@ This gem requires:
 require "bulma-phlex"
 ```
 
-
 ## Usage
 
 Use the Phlex components in your Rails views or any Ruby application that supports Phlex components.
@@ -93,7 +94,6 @@ end
 
 It supports options for **alignment** (centered, right-aligned), **separator** style (arrow, bullet, dot, or succeeds), and **size** (small, medium, large). Items also support an optional `icon` argument.
 
-
 ### Button
 
 Renders a [Bulma button](https://bulma.io/documentation/elements/button/) element with support for color, size, style modifiers, and left/right icons.
@@ -110,11 +110,12 @@ The button label can be passed in as a string or in a block.
 
 ### Card
 
-Renders a [Bulma card](https://bulma.io/documentation/components/card/) with an optional header, content area, and footer links. Each section is populated via builder methods on the yielded component.
+Renders a [Bulma card](https://bulma.io/documentation/components/card/) with an optional header, image, content area, and footer links. Each section is populated via builder methods on the yielded component.
 
 ```ruby
 render BulmaPhlex::Card.new do |card|
-  card.head("Card Title")
+  card.header("Card Title")
+  card.image(src: "image.jpg", alt: "Card image")
   card.content do
     "This is some card content"
   end
@@ -123,9 +124,10 @@ render BulmaPhlex::Card.new do |card|
 end
 ```
 
-Use method `footer_item` for full control of the footer items. Class `footer-item` must be on the outer element 
-of the block.
+The `header` method accepts a string, for a simple title, or a block for custom content.
 
+Use method `footer_item` for full control of the footer items. Class `footer-item` must be on the outer element
+of the block.
 
 ### Columns
 
@@ -141,7 +143,6 @@ end
 
 The `gap:` option accepts either an integer (0–8) or a hash keyed by breakpoint for responsive gap sizes.
 
-
 ### Dropdown
 
 Renders a [Bulma dropdown](https://bulma.io/documentation/components/dropdown/) menu. Supports click-to-toggle (default, via a Stimulus controller) and hoverable (no JavaScript) modes.
@@ -158,6 +159,11 @@ end
 
 Set `click: false` to use hover mode instead of the Stimulus controller.
 
+Use method `header` to add a non-clickable header item. The method takes an optional `divider` argument. (This is not in the Bulma library.)
+
+```ruby
+  dropdown.header("Actions", divider: true)
+```
 
 ### File Upload
 
@@ -171,7 +177,6 @@ end
 
 Set `name: true` to include a file name display element. When enabled, Stimulus data attributes are wired up automatically. The controller is not included in this gem; an [example implementation](https://github.com/RockSolt/bulma-phlex-rails/blob/main/app/javascript/controllers/bulma_phlex/file_input_display_controller.js) is available in the `bulma-phlex-rails` gem.
 
-
 ### Form Field
 
 Renders a [Bulma form field](https://bulma.io/documentation/form/general/#form-field) grouping a label, control, and optional help text. Set the label via the `label` method (string or block) and the input via the `control` method.
@@ -185,7 +190,6 @@ end
 
 The `column:` and `grid:` options integrate the field into Bulma's column and grid layout systems. Both accept `true`, a size string, or a breakpoint hash.
 
-
 ### Grid
 
 Renders a [Bulma smart grid](https://bulma.io/documentation/grid/smart-grid/) layout. Supports fixed column counts, auto-count, minimum column width, and independent gap control.
@@ -198,7 +202,6 @@ render BulmaPhlex::Grid.new(minimum_column_width: 16) do
 end
 ```
 
-
 ### Hero
 
 Renders a [Bulma hero](https://bulma.io/documentation/layout/hero/) section with support for color and size options.
@@ -215,7 +218,6 @@ render BulmaPhlex::Hero.new(color: "info", size: "large") do |hero|
 end
 ```
 
-
 ### Icon
 
 Renders a [Bulma icon](https://bulma.io/documentation/elements/icon/) element. Supports color, size, optional text alongside the icon, and left/right positioning for use inside form controls.
@@ -225,6 +227,21 @@ render BulmaPhlex::Icon.new("fas fa-user")
 render BulmaPhlex::Icon.new("fas fa-home", size: :large, color: :primary, text_right: "Home")
 ```
 
+### Image
+
+Renders a [Bulma image](https://bulma.io/documentation/elements/image/) element. Supports size, ratio, rounded, and additional HTML attributes (on either the wrapping `figure` element or the `img` element).
+
+```ruby
+render BulmaPhlex::Image.new(src: "image.jpg", size: 64)
+
+render BulmaPhlex::Image.new(
+  src: "image.jpg",
+  alt: "An image",
+  rounded: true,
+  ratio: "16by9",
+  img_attributes: { class: "custom-img-class", id: "image-id" },
+  class: "custom-class", id: "figure-image-id")
+```
 
 ### Level
 
@@ -237,6 +254,26 @@ render BulmaPhlex::Level.new do |level|
 end
 ```
 
+### Media Object
+
+Renders a [Bulma media object](https://bulma.io/documentation/layout/media-object/) with an optional left image/icon, right content, and main body content. Each section is populated via builder methods on the yielded component.
+
+```ruby
+render BulmaPhlex::MediaObject.new do |media|
+  media.left { img(src: "/avatar.png", alt: "Avatar") }
+  media.content { "This is the main content of the media object." }
+  media.right { button(class: "button is-small") { "Action" } }
+end
+```
+
+If the left content is an image, method `image` can be used instead of `left` to automatically build the supporting HTML structure.
+
+```ruby
+render BulmaPhlex::MediaObject.new do |media|
+  media.image(src: "/avatar.png", alt: "Avatar", size: 64, rounded: true)
+  media.content { "This is the main content of the media object." }
+end
+```
 
 ### Message
 
@@ -248,7 +285,6 @@ render BulmaPhlex::Message.new("Hello World", color: "info", delete: true) do
 end
 ```
 
-
 ### Modal
 
 Renders a [Bulma modal](https://bulma.io/documentation/components/modal/) dialog overlay with a background, content area, and close button. Content is provided via a block.
@@ -264,7 +300,6 @@ end
 
 The modal is shown by adding the `is-active` class to the container — nothing in the component does this automatically. The default Stimulus controller (`bulma-phlex--modal`) handles open/close behavior. Pass a custom `data_attributes_builder:` to integrate with a different JavaScript setup.
 
-
 ### NavigationBar
 
 Renders a [Bulma navbar](https://bulma.io/documentation/components/navbar/) with support for branding, left/right nav links, and dropdown menus. Collapses automatically on mobile via the `bulma-phlex--navigation-bar` Stimulus controller (provided by the `bulma-phlex-rails` gem).
@@ -287,7 +322,6 @@ end
 > [!NOTE]
 > Setting `container: true` (or a constraint string like `"is-max-desktop"`) wraps the navbar content in a Bulma container for fixed-width layout. The navbar's background color still spans the full viewport width.
 
-
 ### Notification
 
 Renders a [Bulma notification](https://bulma.io/documentation/elements/notification/) alert box with support for color and mode options.
@@ -306,7 +340,6 @@ render BulmaPhlex::Notification.new(color: "warning", delete: { data: { action:
 end
 ```
 
-
 ### Pagination
 
 Renders the [Bulma pagination](https://bulma.io/documentation/components/pagination/) component with previous/next links, numbered page links, ellipses for skipped ranges, and an item count summary. Only renders when there is more than one page of results.
@@ -317,7 +350,6 @@ render BulmaPhlex::Pagination.new(@products, ->(page) { products_path(page: page
 
 The first argument must be a pager object responding to `current_page`, `total_pages`, `per_page`, `total_count`, `previous_page`, and `next_page`.
 
-
 ### Progress Bar
 
 Renders a [Bulma progress bar](https://bulma.io/documentation/elements/progress/) element. Supports color and size options.
@@ -328,7 +360,6 @@ render BulmaPhlex::ProgressBar.new(color: "success", size: "large", value: 75, m
 
 Omitting `value:` and `max:` produces an indeterminate (animated) progress bar.
 
-
 ### Table
 
 Renders a [Bulma table](https://bulma.io/documentation/elements/table/) for a collection of records. Columns are defined via builder methods on the yielded component.
@@ -354,7 +385,7 @@ To add pagination to the table, call `paginate` with a block that returns a path
 table.paginate { |page| products_path(page: page) }
 ```
 
-Pass HTML attributes to the `tr` elements via the `row` method, using either keyword arguments or a block 
+Pass HTML attributes to the `tr` elements via the `row` method, using either keyword arguments or a block
 that receives the record for the row:
 
 ```ruby
@@ -367,7 +398,6 @@ Hide columns on smaller screens with the column `hidden` option:
 table.column("Email", hidden: { mobile: true }) { |user| user.email }
 ```
 
-
 ### Tabs
 
 Renders a [Bulma tabs](https://bulma.io/documentation/components/tabs/) component with tabbed navigation and associated content panels. Supports alignment, size, and style options (boxed, toggle, rounded, fullwidth).
@@ -383,7 +413,6 @@ Tab switching is handled by the `bulma-phlex--tabs` Stimulus controller. The con
 
 An optional right-side element (e.g. a button) can be placed alongside the tab bar via `right_content`.
 
-
 ### Tag
 
 Renders the [Bulma tag](https://bulma.io/documentation/elements/tag/) component. Supports color, size, rounded, and an optional inline delete button.
@@ -395,7 +424,6 @@ render BulmaPhlex::Tag.new("Sale", light: "danger")
 
 The element type is inferred from the attributes: an `href:` produces an `<a>`, a `data-action` or `delete: true` produces a `<button>`, and otherwise a `<span>` is used.
 
-
 ### Title and Subtitle
 
 Renders a [Bulma title](https://bulma.io/documentation/elements/title/) with an optional subtitle. Supports sizes 1–6 for both elements and a `spaced:` option to increase the gap between them.
@@ -407,13 +435,12 @@ render BulmaPhlex::Title.new("Dr. Strangelove", size: 2, subtitle: "Or: How I Le
 
 When `size:` is set but `subtitle_size:` is not, the subtitle size defaults to `size + 2`.
 
-
 ## Upgrading to 0.8
 
 > [!IMPORTANT]
 > The 0.8.0 release includes breaking changes. The namespace for the components has been changed from `Components::Bulma` to `Components::BulmaPhlex`.
 
-This can generally be handled with a *Find-and-Replace*:
+This can generally be handled with a _Find-and-Replace_:
 
 **Find:** `Bulma::`
 **Replace:** `BulmaPhlex::`
@@ -422,7 +449,6 @@ Note that this change was also applied to the expected Stimulus controllers. Ref
 
 Finally, the optional Rails extensions for the Card and Table components have been moved to the `bulma-phlex-rails` gem. If you are using this with Rails, you should use [the `bulma-phlex-rails` gem](https://github.com/RockSolt/bulma-phlex-rails). It provides both the component extensions as well as JavaScript for the Dropdown, Navigation Bar, and Tabs components.
 
-
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/bulma_phlex/card.rb

@@ -3,7 +3,7 @@
 module BulmaPhlex
   # Renders a [Bulma card](https://bulma.io/documentation/components/card/) component.
   #
-  # Supports an optional **header** (with title and custom classes), a **content** area, and a
+  # Supports an optional **header** (with title and custom classes), an **image**, a **content** area, and a
   # **footer** with one or more link items (which can include icons). Each section is populated
   # via builder methods on the yielded component.
   #
@@ -32,8 +32,9 @@ module BulmaPhlex
     def view_template(&)
       vanish(&)
 
-      div(**mix(class: "card", **@html_attributes)) do
+      div(**mix({ class: "card" }, **@html_attributes)) do
         card_header
+        card_image
         card_content
         card_footer
       end
@@ -44,8 +45,28 @@ module BulmaPhlex
     # - `title` — The text to display in the card header
     # - `classes` — Optional additional CSS classes for the header element
     def head(title, classes: nil)
+      warn "[DEPRECATION] `BulmaPhlex::Card#head` is deprecated. Use `header` instead.", category: :deprecated
+
+      header(title, class: classes)
+    end
+
+    # in order to use the method name `header`, we need to grab a reference to the method on the base class
+    # so it is still available to us
+    alias html_header header
+
+    # Sets the card header. Pass in the title as a string and/or provide a block to render custom content
+    # in the header.
+    #
+    # - `title` — The text to display in the card header (optional)
+    # - `**html_attributes` — Additional HTML attributes for the header element (optional)
+    def header(title = nil, **html_attributes, &block)
       @header_title = title
-      @header_classes = classes
+      @header_attributes = html_attributes
+      @header_content = block
+    end
+
+    def image(src:, alt: nil, size: nil, rounded: false)
+      @image = BulmaPhlex::Image.new(src:, alt:, size:, rounded:)
     end
 
     # Sets the card body content.
@@ -74,10 +95,19 @@ module BulmaPhlex
     private
 
     def card_header
-      return if @header_title.nil?
+      return if @header_title.nil? && @header_content.nil?
+
+      html_header(**mix({ class: "card-header" }, @header_attributes)) do
+        p(class: "card-header-title") { plain @header_title } if @header_title
+        @header_content&.call
+      end
+    end
+
+    def card_image
+      return if @image.nil?
 
-      header(class: "card-header #{@header_classes}") do
-        p(class: "card-header-title") { plain @header_title }
+      div(class: "card-image") do
+        render @image
       end
     end
 
@@ -85,7 +115,7 @@ module BulmaPhlex
       return if @card_content.nil?
 
       div(class: "card-content") do
-        div(class: "content") { @card_content.call }
+        @card_content.call
       end
     end
 

data/lib/bulma_phlex/dropdown.rb

@@ -61,20 +61,28 @@ module BulmaPhlex
       end
     end
 
-    def item(content = nil, &)
+    # Adds a non-clickable header item to the dropdown menu. Optionally add a divider before the header with
+    # the `divder: true` parameter.
+    def header(label, divider: false)
+      self.divider if divider
+      div(class: "dropdown-item has-text-weight-semibold is-unselectable") { label }
+    end
+
+    def item(content = nil, **html_attributes, &)
+      attributes = mix({ class: "dropdown-item" }, html_attributes)
       if block_given?
-        div(class: "dropdown-item", &)
+        div(**attributes, &)
       else
-        div(class: "dropdown-item") { content }
+        div(**attributes) { content }
       end
     end
 
-    def link(label, path)
-      a(class: "dropdown-item", href: path) { label }
+    def link(label, path, **html_attributes)
+      a(**mix({ class: "dropdown-item" }, html_attributes), href: path) { label }
     end
 
-    def divider
-      hr(class: "dropdown-divider")
+    def divider(**html_attributes)
+      hr(**mix({ class: "dropdown-divider" }, html_attributes))
     end
 
     private

data/lib/bulma_phlex/image.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Renders a [Bulma image](https://bulma.io/documentation/elements/image/) component.
+  class Image < BulmaPhlex::Base
+    # **Parameters**
+    #
+    # - `src:` — The image source URL (required)
+    # - `alt:` — The image alt text (optional)
+    # - `rounded:` — Whether to apply the `is-rounded` class (optional, default: false)
+    # - `size:` — The image size (optional, e.g., 64 for `is-64x64`)
+    # - `ratio:` — The image ratio (optional, e.g., "1by1", "4by3", "16by9")
+    # - `img_attributes:` — Additional HTML attributes for the img element (optional)
+    # - `**html_attributes` — Additional HTML attributes for the figure element (optional)
+    def self.new(src:, alt: nil, rounded: false, size: nil, ratio: nil, img_attributes: {}, **html_attributes)
+      super
+    end
+
+    def initialize(src:, alt: nil, rounded: false, size: nil, ratio: nil, img_attributes: {}, **html_attributes)
+      @src = src
+      @alt = alt
+      @rounded = rounded
+      @size = size
+      @ratio = ratio
+      @img_attributes = img_attributes
+      @html_attributes = html_attributes
+    end
+
+    def view_template
+      figure(**mix({ class: figure_classes }, @html_attributes)) do
+        img(**mix({ src: @src, alt: @alt, class: img_classes }, @img_attributes))
+      end
+    end
+
+    private
+
+    def figure_classes
+      classes = ["image"]
+      classes << "is-#{@size}x#{@size}" if @size
+      classes << "is-#{@ratio}" if @ratio
+      classes.join(" ")
+    end
+
+    def img_classes
+      "is-rounded" if @rounded
+    end
+  end
+end

data/lib/bulma_phlex/media_object.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Renders a [Bulma media object](https://bulma.io/documentation/components/media-object/) component.
+  #
+  # Optional HTML attributes can be passed to the constructor as well as any of the three block methods,
+  # `left`, `content`, and `right`, to customize the rendered HTML elements.
+  #
+  # ## Example
+  #
+  #     render BulmaPhlex::MediaObject.new do |media|
+  #       media.left do
+  #         p(class: "image is-64x64") do
+  #           img(src: "/assets/images/placeholders/128x128.png")
+  #         end
+  #       end
+  #
+  #       media.content do
+  #         p { "This is the main content of the media object." }
+  #       end
+  #
+  #       media.right do
+  #         button(class: "delete")
+  #       end
+  #     end
+  class MediaObject < BulmaPhlex::Base
+    # **Parameters**
+    #
+    # - `**html_attributes` — Additional HTML attributes for the wrapping `article` element
+    def self.new(**html_attributes)
+      super
+    end
+
+    def initialize(**html_attributes)
+      @html_attributes = html_attributes
+    end
+
+    def view_template(&)
+      vanish(&)
+
+      article(**mix({ class: "media" }, @html_attributes)) do
+        render_media_left if @media_left
+        render_media_content if @media_content
+        render_media_right if @media_right
+      end
+    end
+
+    # Use a block to provide the left content, which will be wrapped in a `figure` element. Additional
+    # HTML attributes can be passed to customize the element.
+    #
+    #   <figure class="media-left">
+    #     <!-- Left content goes here -->
+    #   </figure>
+    def left(**html_attributes, &block)
+      @left_attributes = html_attributes
+      @media_left = block
+    end
+
+    # If the left content is an image, you can use this method to provide the image source,
+    # alt text, size, and whether it should be rounded. Additional HTML attributes can be
+    # passed to customize the `figure` element.
+    def image(src:, alt: nil, size: nil, rounded: false, **html_attributes)
+      left(**html_attributes) do
+        p(class: image_classes(size:)) do
+          img(src:, alt:, class: ("is-rounded" if rounded))
+        end
+      end
+    end
+
+    # Use a block to provide the main content, which will be wrapped in a `div` element. Additional
+    # HTML attributes can be passed to customize the element.
+    #
+    #   <div class="media-content">
+    #    <!-- Main content goes here -->
+    #  </div>
+    def content(**html_attributes, &block)
+      @content_attributes = html_attributes
+      @media_content = block
+    end
+
+    # Use a block to provide the right content, which will be wrapped in a `div` element. Additional
+    # HTML attributes can be passed to customize the element.
+    #
+    #   <div class="media-right">
+    #     <!-- Right content goes here -->
+    #   </div>
+    def right(**html_attributes, &block)
+      @right_attributes = html_attributes
+      @media_right = block
+    end
+
+    private
+
+    def render_media_left
+      figure(**mix({ class: "media-left" }, @left_attributes)) do
+        @media_left.call
+      end
+    end
+
+    def render_media_content
+      div(**mix({ class: "media-content" }, @content_attributes)) do
+        @media_content.call
+      end
+    end
+
+    def render_media_right
+      div(**mix({ class: "media-right" }, @right_attributes)) do
+        @media_right.call
+      end
+    end
+
+    def image_classes(size:)
+      classes = ["image"]
+      classes << "is-#{size}x#{size}" if size
+      classes.join(" ")
+    end
+  end
+end

data/lib/bulma_phlex/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bulma-phlex
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Todd Kummer
 bindir: bin
 cert_chain: []
-date: 2026-05-27 00:00:00.000000000 Z
+date: 2026-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex
@@ -76,7 +76,9 @@ files:
 - lib/bulma_phlex/grid.rb
 - lib/bulma_phlex/hero.rb
 - lib/bulma_phlex/icon.rb
+- lib/bulma_phlex/image.rb
 - lib/bulma_phlex/level.rb
+- lib/bulma_phlex/media_object.rb
 - lib/bulma_phlex/message.rb
 - lib/bulma_phlex/modal.rb
 - lib/bulma_phlex/navigation_bar.rb