bulma-phlex 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a4e33701b1ed15897b743789cc3fb1923fdaf70fd065035f8342836058927ed
-  data.tar.gz: 772252cf5d5660a0a926f4d24a2ffd73898947a6db4ce3f8ea880978acdda0bf
+  metadata.gz: d62a43330834f293718993ab3227796dbb76d3ae57b4c0efca10df5dc1e35a6b
+  data.tar.gz: 1b310813d75fe054a993a02d258a05fa52ba4f15db249d2e269c1871fdf2a025
 SHA512:
-  metadata.gz: 7ec1799752698497e06b075b7378d18a3b820e80ec9e95c7448eb1999ac93514c785d6a61f95434ba02962edb103aa398bd6994506a0954804af52becb56f9ac
-  data.tar.gz: 4071dd6000764651b7a677d1ab6ac94c15b59043692602be997924ec094977f41eaf704222554e89ce33f0a49feadc65eeb680ef8c3d36963034995c7b867570
+  metadata.gz: a0b4c95ba751e8a2f5718b08bcd389ebe055f087271a1ee77f06c2e9292088bc4a770aeeacdb31c304349ac372373cd40ae5fd90f498eef15a1c6502732028cc
+  data.tar.gz: 2579cf14a6d59153dc4e44781eba67b451513e50d551e59141be6f61be9d130862c6553643b150393941a40f7ea99f10f40ff10dd824489ea12d18afdaeff875

data/README.md

@@ -9,6 +9,7 @@ This gem provides a set of ready-to-use [Phlex](https://github.com/phlex-ruby/ph
 ## Table of Contents
 
 - [Installation](#installation)
+- [Configuration](#configuration)
 - [Usage](#usage)
   - [Breadcrumb](#breadcrumb)
   - [Button](#button)
@@ -23,6 +24,7 @@ This gem provides a set of ready-to-use [Phlex](https://github.com/phlex-ruby/ph
   - [Image](#image)
   - [Level](#level)
   - [Media Object](#media-object)
+  - [Menu](#menu)
   - [Message](#message)
   - [Modal](#modal)
   - [NavigationBar](#navigationbar)
@@ -76,6 +78,25 @@ This gem requires:
 require "bulma-phlex"
 ```
 
+## Configuration
+
+Icons chosen internally by components can be configured globally. The default icons are Font Awesome 7 solid icons, but you can change them to other icons by providing the appropriate class names.
+
+```ruby
+BulmaPhlex.configure do |config|
+  config.icons.sort = {
+    ascending: "fa-solid fa-arrow-up",
+    descending: "fa-solid fa-arrow-down",
+    inactive: "fa-solid fa-sort"
+  }
+  config.icons.dropdown = "fa-solid fa-chevron-down"
+  config.icons.file_upload = "fa-solid fa-upload"
+  config.icons.conditional = "fa-solid fa-check"
+end
+```
+
+Sortable columns also accept an `icons:` hash for a per-column override. Dropdowns accept `icon:` and conditional table columns accept `icon_class:`.
+
 ## Usage
 
 Use the Phlex components in your Rails views or any Ruby application that supports Phlex components.
@@ -101,7 +122,7 @@ Renders a [Bulma button](https://bulma.io/documentation/elements/button/) elemen
 The component generates a `<button>` by default. Pass an `href:` attribute to generate an `<a>` element instead. Pass `input: "submit"` (or `"button"` or `"reset"`) to generate an `<input>` element.
 
 ```ruby
-BulmaPhlex::Button("Like", color: "primary", size: "large", icon: "fas fa-thumbs-up")
+BulmaPhlex::Button("Like", color: "primary", size: "large", icon: "fa-solid fa-thumbs-up")
 BulmaPhlex::Button(href: "/profile") { "View Profile" }
 BulmaPhlex::Button(input: "submit", color: "success")
 ```
@@ -120,7 +141,7 @@ render BulmaPhlex::Card.new do |card|
     "This is some card content"
   end
   card.footer_link("View", "/view", target: "_blank")
-  card.footer_link("Edit", "/edit", icon: "fas fa-edit")
+  card.footer_link("Edit", "/edit", icon: "fa-solid fa-pen-to-square")
 end
 ```
 
@@ -222,9 +243,12 @@ end
 
 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.
 
+When text is rendered alongside the icon, Bulma allows the text and icon to wrap by default. Pass `nowrap: true` when they form a compact UI unit that should stay together, such as a sortable table heading, toolbar action, button label, or navigation item. Leave it unset when the text should be allowed to wrap in a constrained container.
+
 ```ruby
-render BulmaPhlex::Icon.new("fas fa-user")
-render BulmaPhlex::Icon.new("fas fa-home", size: :large, color: :primary, text_right: "Home")
+render BulmaPhlex::Icon.new("fa-solid fa-user")
+render BulmaPhlex::Icon.new("fa-solid fa-home", size: :large, color: :primary, text_right: "Home")
+render BulmaPhlex::Icon.new("fa-solid fa-sort", text_left: "Revenue", nowrap: true)
 ```
 
 ### Image
@@ -275,6 +299,45 @@ render BulmaPhlex::MediaObject.new do |media|
 end
 ```
 
+### Menu
+
+Renders a [Bulma menu](https://bulma.io/documentation/components/menu/) with support for labels, lists, and nested lists.
+
+```ruby
+render BulmaPhlex::Menu.new do |menu|
+  menu.label("General")
+  menu.list do
+    menu.item("Dashboard", href: "/dashboard", active: true)
+    menu.item("Customers", href: "/customers")
+  end
+
+  menu.label("Administration")
+  menu.list do
+    menu.item("Team Settings", href: "/teams/settings")
+    menu.item("Manage Your Team", href: "/teams/dashboard") do
+      menu.item("Members", href: "/members")
+      menu.item("Plugins", href: "/plugins")
+      menu.item("Add a member", href: "/add-member")
+    end
+  end
+end
+```
+
+Nested lists can be created by passing a block to the `item` method. An expandable section (header opens and closes but is not a link) can be created with the `expandable_item` method.
+
+```ruby
+render BulmaPhlex::Menu.new do |menu|
+  menu.label("General")
+  menu.list do
+    menu.item("Dashboard", href: "/dashboard", active: true)
+    menu.expandable_item("Customers") do
+      menu.item("Active Customers", href: "/customers/active")
+      menu.item("Inactive Customers", href: "/customers/inactive")
+    end
+  end
+end
+```
+
 ### Message
 
 Renders a [Bulma message](https://bulma.io/documentation/components/message/) component with a header, optional delete button, and body.
@@ -377,7 +440,32 @@ end
 In addition to `column`, two specialized column methods are available:
 
 - `date_column(header, format: "%Y-%m-%d")` — formats the value with `strftime`
-- `conditional_icon(header, icon_class: "fas fa-check")` — shows an icon when the block returns truthy
+- `conditional_icon(header, icon_class:)` — shows the configured conditional icon, or the supplied icon, when the block returns truthy
+
+#### Sortable columns
+
+Pass a sort hash with the URL for the next sort state to add a sortable header. The component renders the sort link, icon, and accessible sort state; your application remains responsible for interpreting the sort parameters and ordering the records.
+
+```ruby
+render BulmaPhlex::Table.new(@users) do |table|
+  table.column(
+    "Name",
+    sort: { href: users_path(sort: "name") }
+  ) { |user| user.full_name }
+
+  table.date_column(
+    "Joined",
+    sort: {
+      href: users_path(sort: "created_at"),
+      current_direction: :descending
+    }
+  ) { |user| user.created_at }
+end
+```
+
+Set `current_direction:` to `:ascending` or `:descending` for the currently active column. Pass additional attributes for the generated link with `link_attributes:`. The component generates an accessible label from the column header and sort state.
+
+#### Pagination
 
 To add pagination to the table, call `paginate` with a block that returns a path given a page number:
 
@@ -385,6 +473,8 @@ To add pagination to the table, call `paginate` with a block that returns a path
 table.paginate { |page| products_path(page: page) }
 ```
 
+#### Custom row attributes
+
 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:
 
@@ -392,6 +482,8 @@ that receives the record for the row:
 table.row(class: "custom-row-class") { |row| { id: "row-id-#{row.id}" } }
 ```
 
+#### Responsive columns
+
 Hide columns on smaller screens with the column `hidden` option:
 
 ```ruby
@@ -405,7 +497,7 @@ Renders a [Bulma tabs](https://bulma.io/documentation/components/tabs/) componen
 ```ruby
 render BulmaPhlex::Tabs.new(boxed: true) do |tabs|
   tabs.tab(id: "profile", title: "Profile", active: true) { "Profile content" }
-  tabs.tab(id: "settings", title: "Settings", icon: "fas fa-cog") { "Settings content" }
+  tabs.tab(id: "settings", title: "Settings", icon: "fa-solid fa-gear") { "Settings content" }
 end
 ```
 

data/lib/bulma_phlex/card.rb

@@ -80,7 +80,7 @@ module BulmaPhlex
     #
     # - `text` — The link label text
     # - `href` — The URL the link points to
-    # - `icon:` — Optional icon class string (e.g. `"fas fa-edit"`) to render an icon alongside the text
+    # - `icon:` — Optional icon class string (e.g. `"fa-solid fa-pen-to-square"`) to render an icon alongside the text
     # - `**html_attributes` — Additional HTML attributes for the `<a>` element (e.g. `target:`, `class:`)
     def footer_link(text, href, **html_attributes)
       (@footer_items ||= []) << [text, href, html_attributes]

data/lib/bulma_phlex/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Stores application-wide defaults for component-owned icons.
+  class Configuration
+    # Stores the icon classes used by components when no local override is supplied.
+    class Icons
+      attr_accessor :sort, :dropdown, :file_upload, :conditional
+
+      def initialize
+        @sort = {
+          ascending: "fa-solid fa-sort-up",
+          descending: "fa-solid fa-sort-down",
+          inactive: "fa-solid fa-sort"
+        }
+        @dropdown = "fa-solid fa-angle-down"
+        @file_upload = "fa-solid fa-upload"
+        @conditional = "fa-solid fa-check"
+      end
+    end
+
+    attr_reader :icons
+
+    def initialize
+      @icons = Icons.new
+    end
+  end
+end

data/lib/bulma_phlex/dropdown.rb

@@ -23,19 +23,19 @@ module BulmaPhlex
     # - `label` — The text displayed in the dropdown trigger button
     # - `click` — Stimulus controller name for toggling; set to `false` for hover mode instead
     # - `alignment` — Alignment of the dropdown menu: `"left"` (default), `"right"`, or `"up"`
-    # - `icon` — Icon class for the trigger button (default: `"fas fa-angle-down"`)
+    # - `icon` — Icon class for the trigger button (default: configured dropdown icon)
     # - `**html_attributes` — Additional HTML attributes for the outermost dropdown element
-    def self.new(label, click: "bulma-phlex--dropdown", alignment: "left", icon: "fas fa-angle-down",
+    def self.new(label, click: "bulma-phlex--dropdown", alignment: "left", icon: nil,
                  **html_attributes)
       super
     end
 
-    def initialize(label, click: "bulma-phlex--dropdown", alignment: "left", icon: "fas fa-angle-down",
+    def initialize(label, click: "bulma-phlex--dropdown", alignment: "left", icon: nil,
                    **html_attributes)
       @label = label
       @click = click
       @alignment = alignment
-      @icon = icon
+      @icon = icon || BulmaPhlex.config.icons.dropdown
       @html_attributes = html_attributes
     end
 

data/lib/bulma_phlex/file_upload.rb

@@ -25,6 +25,7 @@ module BulmaPhlex
     # - `align` — Aligns the file input: `"right"` or `"centered"`
     # - `fullwidth` — If `true`, makes the file input full width
     # - `boxed` — If `true`, makes the file input boxed
+    # - `icon` — Icon class for the upload control (default: configured file upload icon)
     # - `data_attributes_builder` — A custom builder for the data attributes used for Stimulus integration;
     #   defaults to a builder with the controller name `"bulma-phlex--file-input-display"`
     def self.new(color: nil,
@@ -33,6 +34,7 @@ module BulmaPhlex
                  align: nil,
                  fullwidth: false,
                  boxed: false,
+                 icon: nil,
                  data_attributes_builder: nil)
       super
     end
@@ -43,6 +45,7 @@ module BulmaPhlex
                    align: nil,
                    fullwidth: false,
                    boxed: false,
+                   icon: nil,
                    data_attributes_builder: nil)
       @color = color
       @size = size
@@ -50,6 +53,7 @@ module BulmaPhlex
       @align = align
       @fullwidth = fullwidth
       @boxed = boxed
+      @icon = icon || BulmaPhlex.config.icons.file_upload
 
       return unless @name
 
@@ -63,7 +67,7 @@ module BulmaPhlex
           yield(@data_attributes_builder&.for_file_input)
           span(class: "file-cta") do
             span(class: "file-icon") do
-              i(class: "fas fa-upload")
+              i(class: @icon)
             end
             span(class: "file-label") { plain " Choose a file… " }
           end

data/lib/bulma_phlex/form_control.rb

@@ -6,8 +6,8 @@ module BulmaPhlex
   class FormControl < Base
     # **Parameters**
     #
-    # - `icon_left` — Icon class for the left side of the control (e.g. `"fas fa-check"`)
-    # - `icon_right` — Icon class for the right side of the control (e.g. `"fas fa-check"`)
+    # - `icon_left` — Icon class for the left side of the control (e.g. `"fa-solid fa-check"`)
+    # - `icon_right` — Icon class for the right side of the control (e.g. `"fa-solid fa-check"`)
     # - `**html_attributes` — Additional HTML attributes for the control element
     def self.new(icon_left: nil, icon_right: nil, **html_attributes)
       super

data/lib/bulma_phlex/form_field.rb

@@ -21,8 +21,8 @@ module BulmaPhlex
     # **Parameters**
     #
     # - `help` — Optional help text displayed below the input
-    # - `icon_left` — Icon class for an icon to the left of the input (e.g. `"fas fa-user"`)
-    # - `icon_right` — Icon class for an icon to the right of the input (e.g. `"fas fa-check"`)
+    # - `icon_left` — Icon class for an icon to the left of the input (e.g. `"fa-solid fa-user"`)
+    # - `icon_right` — Icon class for an icon to the right of the input (e.g. `"fa-solid fa-check"`)
     # - `column` — If `true`, makes the field a column; a size string (e.g. `"half"`) sets the size for
     #   all breakpoints; a hash (e.g. `{ mobile: "full", desktop: "half" }`) sets responsive sizes
     # - `grid` — If `true`, makes the field a grid cell; a size string sets the cell size

data/lib/bulma_phlex/icon.rb

@@ -5,27 +5,31 @@ module BulmaPhlex
   # form control positioning.
   #
   # Supports **color** and **size** options, optional **text** to the left or right of the icon,
-  # and **positioning** helpers (`left`/`right`) for use inside form controls. When text is provide,
+  # and **positioning** helpers (`left`/`right`) for use inside form controls. When text is provided,
   # the icon and text are wrapped in a container with the `icon-text` class for proper spacing, and
-  # the icon includes `aria-hidden="true"` for accessibility.
+  # the icon includes `aria-hidden="true"` for accessibility. Use `nowrap: true` when the icon and
+  # text form a compact unit that should remain on one line, such as a sortable table heading or
+  # toolbar action; leave it unset when text should be allowed to wrap.
   #
   # Additional HTML attributes can be passed to the icon's `<span>` element via `**html_attributes`,
   # and to the inner `<i>` by nested them under `icon_attributes`.
   #
   # ## Example
   #
-  #     render BulmaPhlex::Icon.new("fas fa-home")
-  #     render BulmaPhlex::Icon.new("fas fa-home", color: :primary, size: :large, text_right: "Home")
+  #     render BulmaPhlex::Icon.new("fa-solid fa-home")
+  #     render BulmaPhlex::Icon.new("fa-solid fa-home", color: :primary, size: :large, text_right: "Home")
   class Icon < BulmaPhlex::Base
     # **Parameters**
     #
-    # - `icon` — The icon class string (e.g. `"fas fa-home"`)
+    # - `icon` — The icon class string (e.g. `"fa-solid fa-home"`)
     # - `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
+    # - `nowrap` — If `true`, prevents text and the icon from wrapping onto separate lines. Use for
+    #     compact icon-label units; leave unset when the text should be allowed to wrap.
     # - `**html_attributes` — Additional HTML attributes for the icon span element. Nest attributes under
     #     `icon_attributes` to apply them to the inner `<i>` element instead.
     def self.new(icon,
@@ -35,6 +39,7 @@ module BulmaPhlex
                  color: nil,
                  left: false,
                  right: false,
+                 nowrap: false,
                  **html_attributes)
       super
     end
@@ -46,6 +51,7 @@ module BulmaPhlex
                    color: nil,
                    left: false,
                    right: false,
+                   nowrap: false,
                    **html_attributes)
       @icon = icon
       @text_right = text_right
@@ -54,6 +60,7 @@ module BulmaPhlex
       @color = color
       @left = left
       @right = right
+      @nowrap = nowrap
       @html_attributes = html_attributes.clone
       @icon_attributes = @html_attributes.delete(:icon_attributes) || {}
     end
@@ -73,12 +80,18 @@ module BulmaPhlex
     def optional_text_wrapper(&)
       if @text_right || @text_left
         add_aria_hidden_to_icon_attributes
-        span(class: "icon-text", &)
+        span(class: icon_text_classes, &)
       else
         yield
       end
     end
 
+    def icon_text_classes
+      classes = ["icon-text"]
+      classes << "is-flex-wrap-nowrap" if @nowrap
+      classes.join(" ")
+    end
+
     def add_aria_hidden_to_icon_attributes
       @icon_attributes = mix({ aria: { hidden: "true" } }, @icon_attributes)
     end

data/lib/bulma_phlex/menu.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Renders a [Bulma menu](https://bulma.io/documentation/components/menu/) component with a label and list of items.
+  #
+  # The menu supports headers with the `label` method, lists with the `list` method, and items with the `item` method.
+  # If an item has nested items, use a block within the `item` method to add the nested items. An item can be marked as
+  # active by passing `active: true` to the `item` method.
+  #
+  # Additional HTML attributes can be passed to the constructor as well as any of the methods.
+  #
+  # ## Example
+  #
+  #     render BulmaPhlex::Menu.new do |menu|
+  #       menu.label "General"
+  #       menu.list do |list|
+  #         list.item "Dashboard", href: "#dashboard"
+  #         list.item "Customers", href: "#customers" do |nested|
+  #           nested.item "Active Customers", href: "#active-customers"
+  #           nested.item "Inactive Customers", href: "#inactive-customers"
+  #         end
+  #       end
+  #     end
+  class Menu < BulmaPhlex::Base
+    # **Parameters**
+    #
+    # - `**html_attributes` — Additional HTML attributes for the menu element
+    def self.new(**html_attributes)
+      super
+    end
+
+    def initialize(**html_attributes)
+      @html_attributes = html_attributes
+    end
+
+    def view_template(&)
+      aside(**mix({ class: "menu" }, @html_attributes)) do
+        yield(self) if block_given?
+      end
+    end
+
+    # Adds a header label to the menu. Additional HTML attributes can be passed to customize the label element.
+    def label(text, **attributes)
+      p(**mix({ class: "menu-label" }, attributes)) { text }
+    end
+
+    # Pass a block to add a list of items to the menu. Additional HTML attributes can be passed to customize the
+    # list element.
+    def list(**attributes, &)
+      ul(**mix({ class: "menu-list" }, attributes)) do
+        yield(self) if block_given?
+      end
+    end
+
+    # Adds an item to the menu list. The `href` parameter is required to specify the link for the item. If the item is
+    # active, pass `active: true`. Additional HTML attributes can be passed to customize the link element. If the item
+    # has nested items, pass a block to add the nested items.
+    def item(label, href:, active: false, **attributes, &)
+      li_attributes, attributes = parse_li_attributes(attributes)
+
+      li(**li_attributes) do
+        attributes = mix({ class: "is-active" }, attributes) if active
+        a(**mix({ href: }, attributes)) { label }
+        nested_list(&) if block_given?
+      end
+    end
+
+    def expandable_item(label, open: false, **attributes, &)
+      li_attributes, attributes = parse_li_attributes(attributes)
+
+      li(**li_attributes) do
+        details(open:) do
+          summary(**mix({ class: "menu-item is-clickable" }, attributes)) { label }
+          nested_list(&)
+        end
+      end
+    end
+
+    private
+
+    def parse_li_attributes(attributes)
+      if attributes.key?(:li_attributes)
+        [attributes[:li_attributes], attributes.except(:li_attributes)]
+      else
+        [{}, attributes]
+      end
+    end
+
+    def nested_list(&)
+      ul(class: "menu-list") do
+        yield(self)
+      end
+    end
+  end
+end

data/lib/bulma_phlex/modal.rb

@@ -8,9 +8,14 @@ module BulmaPhlex
   # `data_attributes_builder` option.
   class Modal < BulmaPhlex::Base
     StimulusDataAttributes = Data.define(:stimulus_controller) do
-      def for_container = { controller: stimulus_controller }
-      def for_background = { action: "click->bulma-phlex--modal#close" }
-      def for_close_button = { action: "bulma-phlex--modal#close" }
+      def for_container
+        { controller: stimulus_controller,
+          action: ["keydown.esc@document->#{stimulus_controller}#close",
+                   "command->#{stimulus_controller}#openOrCloseByCommand"] }
+      end
+
+      def for_background = { action: "click->#{stimulus_controller}#close" }
+      def for_close_button = { action: "#{stimulus_controller}#close" }
     end
 
     # **Parameters**

data/lib/bulma_phlex/navigation_bar_dropdown.rb

@@ -3,12 +3,16 @@
 module BulmaPhlex
   # Renders a dropdown menu for the [Bulma navbar](https://bulma.io/documentation/components/navbar/#dropdown-menu).
   #
-  # Provides structured content for a navbar dropdown, including **headers**, **links**, and **dividers**.
-  # Intended to be used inside a {BulmaPhlex::NavigationBar} block.
+  # Provides structured content for a navbar dropdown, including **headers**, **links**, and **dividers**. Pass boolean
+  # flags `right` or `boxed` to the constructor to customize the dropdown. This component is intended to be used inside
+  # a {BulmaPhlex::NavigationBar} block.
+  #
+  # The constructor and each of the three methods (`header`, `item`, and `divider`) can accept additional HTML
+  # attributes.
   #
   # ## Example
   #
-  #     render BulmaPhlex::NavigationBar.new do |navbar|
+  #     render BulmaPhlex::NavigationBar.new(right: true) do |navbar|
   #       navbar.brand_item "My App", "/"
   #
   #       navbar.right do |menu|
@@ -17,28 +21,56 @@ module BulmaPhlex
   #           dropdown.item "Profile", "/profile"
   #           dropdown.item "Settings", "/settings"
   #           dropdown.divider
-  #           dropdown.item "Sign Out", "/logout"
+  #           dropdown.item "Sign Out", "/logout", data: { turbo_prefetch: "false" }
   #         end
   #       end
   #     end
   class NavigationBarDropdown < BulmaPhlex::Base
+    # **Parameters**
+    #
+    # - `right` — If `true`, aligns the dropdown to the right side of the navbar
+    # - `boxed` — If `true`, applies the Bulma `is-boxed` style to the dropdown
+    # - `**html_attributes` — Additional HTML attributes for the dropdown container
+    def self.new(right: false, boxed: false, **html_attributes)
+      super
+    end
+
+    def initialize(right: false, boxed: false, **html_attributes)
+      @right = right
+      @boxed = boxed
+      @html_attributes = html_attributes
+    end
+
     def view_template(&)
-      div(class: "navbar-dropdown is-right", &)
+      div(**mix({ class: navbar_dropdown_classes }, @html_attributes), &)
     end
 
     # 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)
+    def header(label, divider: false, **html_attributes)
       self.divider if divider
-      div(class: "navbar-item has-text-weight-semibold") { label }
+
+      attributes = mix({ class: "navbar-item has-text-weight-semibold" }, html_attributes)
+      div(**attributes) { label }
+    end
+
+    def item(label, path, **html_attributes)
+      attributes = mix({ class: "navbar-item", href: path }, html_attributes)
+      a(**attributes) { label }
     end
 
-    def item(label, path)
-      a(class: "navbar-item", href: path) { label }
+    def divider(**html_attributes)
+      attributes = mix({ class: "navbar-divider" }, html_attributes)
+      hr(**attributes)
     end
 
-    def divider
-      hr(class: "navbar-divider")
+    private
+
+    def navbar_dropdown_classes
+      classes = ["navbar-dropdown"]
+      classes << "is-right" if @right
+      classes << "is-boxed" if @boxed
+      classes.join(" ")
     end
   end
 end

data/lib/bulma_phlex/tab_components/tab.rb

@@ -11,7 +11,7 @@ module BulmaPhlex
       #
       # - `id` — Unique identifier for the tab
       # - `title` — The text displayed on the tab
-      # - `icon` — Optional icon class to display on the tab (e.g. `"fas fa-cog"`)
+      # - `icon` — Optional icon class to display on the tab (e.g. `"fa-solid fa-gear"`)
       # - `active` — If `true`, marks the tab as currently active
       # - `data_attributes_proc` — A proc that generates data attributes for the tab
       def self.new(id:, title:, icon:, active:,

data/lib/bulma_phlex/table/sort.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  class Table
+    # Internal component for rendering a sortable table header.
+    class Sort < BulmaPhlex::Base
+      DIRECTIONS = %i[asc desc].freeze
+
+      # **Parameters**
+      #
+      # - `header_label` — The text to display in the table header
+      # - `header_classes` — CSS classes for the `<th>` element
+      # - `href` — The URL to navigate to when the header is clicked
+      # - `current_direction` — The current sort direction (`:asc`, `:desc`, or `nil`)
+      # - `link_attributes` — Additional HTML attributes for the `<a>` element
+      # - `icons` — Icon classes for `ascending`, `descending`, and `inactive` states
+      def self.new(header_label:, header_classes:, href:, current_direction: nil, link_attributes: {}, icons: nil)
+        super
+      end
+
+      def initialize(header_label:, header_classes:, href:, current_direction: nil, link_attributes: {}, icons: nil)
+        validate_direction!(current_direction)
+        validate_link_attributes!(link_attributes)
+        validate_icons!(icons) unless icons.nil?
+
+        @header_label = header_label
+        @header_classes = header_classes
+        @href = href
+        @direction = current_direction
+        @link_attributes = link_attributes
+        @icons = BulmaPhlex.config.icons.sort.merge(icons || {})
+      end
+
+      def view_template
+        th(**header_attributes) do
+          a(**link_attributes) do
+            render Icon.new(icon, text_left: @header_label, nowrap: true, icon_attributes: { aria: { hidden: "true" } })
+          end
+        end
+      end
+
+      def active?
+        !@direction.nil?
+      end
+
+      def ascending?
+        @direction == :asc
+      end
+
+      def descending?
+        @direction == :desc
+      end
+
+      attr_reader :href, :direction
+
+      private
+
+      def header_attributes
+        attributes = { class: @header_classes }
+        if active?
+          attributes[:aria_sort] = ascending? ? "ascending" : "descending"
+        end
+        attributes
+      end
+
+      def link_attributes
+        unless @link_attributes[:class]&.include?("has-text-")
+          @link_attributes = mix(@link_attributes,
+                                 class: "has-text-grey-dark")
+        end
+        mix(
+          @link_attributes,
+          href!: @href,
+          aria!: mix(@link_attributes.fetch(:aria, {}), label!: link_label)
+        )
+      end
+
+      def link_label
+        label = @header_label.to_s
+        return "Sort by #{label}" unless active?
+
+        sort_dir = ascending? ? "ascending" : "descending"
+        "#{label}, sorted #{sort_dir}. Activate to change sort order."
+      end
+
+      def icon
+        return @icons[:ascending] if ascending?
+        return @icons[:descending] if descending?
+
+        @icons[:inactive]
+      end
+
+      def validate_direction!(value)
+        return if value.nil? || DIRECTIONS.include?(value)
+
+        valid_directions = DIRECTIONS.map { |direction| ":#{direction}" }.join(", ")
+        raise ArgumentError, "current_direction must be #{valid_directions}, or nil"
+      end
+
+      def validate_link_attributes!(value)
+        raise ArgumentError, "link_attributes must be a Hash" unless value.is_a?(Hash)
+      end
+
+      def validate_icons!(value)
+        raise ArgumentError, "icons must be a Hash" unless value.is_a?(Hash)
+      end
+    end
+
+    private_constant :Sort
+  end
+end

data/lib/bulma_phlex/table.rb

@@ -4,7 +4,8 @@ module BulmaPhlex
   # Renders the [Bulma table](https://bulma.io/documentation/elements/table/) component.
   #
   # Displays a collection of records in rows and columns. Columns are defined via the `column`,
-  # `date_column`, and `conditional_icon` builder methods. Supports Bulma **style** options
+  # `date_column`, and `conditional_icon` builder methods. Headers can optionally be sortable by
+  # passing a sort hash to the column. Supports Bulma **style** options
   # (bordered, striped, hoverable) and **layout** options (narrow, fullwidth). An optional
   # **pagination** control can be added to the table footer via the `paginate` method.
   #
@@ -24,9 +25,11 @@ module BulmaPhlex
   #
   #     render BulmaPhlex::Table.new(users) do |table|
   #       table.row(class: "has-background-light") { |user| { id: "user-row-#{user.id}" } }
-  #       table.column("Name", &:full_name)
+  #       table.column("Name", sort: { href: "/users?sort=name" }, &:full_name)
   #       table.column("Email", hidden: "touch", &:email)
-  #       table.date_column("Joined", hidden: "mobile", &:created_at, format: "%B %d, %Y")
+  #       table.date_column("Joined", hidden: "mobile", sort: {
+  #         href: "/users?sort=created_at", current_direction: :descending
+  #       }, &:created_at, format: "%B %d, %Y")
   #       table.conditional_icon("Admin?", &:admin?)
   #       table.column "Actions" do |user|
   #         link_to "Edit", edit_user_path(user), class: "button is-small"
@@ -104,11 +107,15 @@ module BulmaPhlex
     # Adds a column to the table. Can be called multiple times to define all columns.
     #
     # - `header` — The column header text
+    # - `sort` — Optional hash containing `href`, `current_direction`, `link_attributes`,
+    #   and `icons` for the generated link
     # - `**html_attributes` — Additional HTML attributes for each `<td>` cell in this column
     #
     # Expects a block that receives each `row` object and returns the cell content.
-    def column(header, hidden: false, **html_attributes, &content)
-      @columns << { header:, hidden:, html_attributes:, content: }
+    def column(header, hidden: false, sort: nil, **html_attributes, &content)
+      raise ArgumentError, "sort must be a Hash or nil" unless sort.nil? || sort.is_a?(Hash)
+
+      @columns << { header:, hidden:, html_attributes:, content:, sort: }
     end
 
     # Adds a date-formatted column to the table. Can be called multiple times.
@@ -118,8 +125,8 @@ module BulmaPhlex
     # - `**html_attributes` — Additional HTML attributes for each `<td>` cell in this column
     #
     # Expects a block that receives each `row` object and returns a `Date` or `Time` value.
-    def date_column(header, hidden: false, format: "%Y-%m-%d", **html_attributes, &content)
-      column(header, hidden:, **html_attributes) do |row|
+    def date_column(header, hidden: false, format: "%Y-%m-%d", sort: nil, **html_attributes, &content)
+      column(header, hidden:, sort:, **html_attributes) do |row|
         content.call(row)&.strftime(format)
       end
     end
@@ -127,14 +134,15 @@ module BulmaPhlex
     # Adds a column that displays an icon when the block returns a truthy value. Can be called multiple times.
     #
     # - `header` — The column header text
-    # - `icon_class` — The CSS class(es) for the icon element (default: `"fas fa-check"`)
+    # - `icon_class` — The CSS class(es) for the icon element (default: configured conditional icon)
     # - `**html_attributes` — Additional HTML attributes for each `<td>` cell in this column
     #
     # Expects a block that receives each `row` object and returns a truthy or falsy value.
-    def conditional_icon(header, hidden: false, icon_class: "fas fa-check", **html_attributes, &content)
+    def conditional_icon(header, hidden: false, icon_class: nil, sort: nil, **html_attributes, &content)
       html_attributes[:class] = [html_attributes[:class], "has-text-centered"].compact.join(" ")
+      icon_class ||= BulmaPhlex.config.icons.conditional
 
-      column(header, hidden:, **html_attributes) do |row|
+      column(header, hidden:, sort:, **html_attributes) do |row|
         Icon(icon_class) if content.call(row)
       end
     end
@@ -150,7 +158,14 @@ module BulmaPhlex
     private
 
     def table_header(column)
-      th(class: header_classes(column)) { column[:header] }
+      sort = column[:sort]
+      return th(class: header_classes(column)) { column[:header] } unless sort
+
+      render Sort.new(
+        header_label: column[:header],
+        header_classes: header_classes(column),
+        **sort
+      )
     end
 
     def header_classes(column)

data/lib/bulma_phlex/tabs.rb

@@ -18,11 +18,11 @@ module BulmaPhlex
   #         "Profile content goes here"
   #       end
   #
-  #       tabs.tab(id: "settings", title: "Settings", icon: "fas fa-cog") do
+  #       tabs.tab(id: "settings", title: "Settings", icon: "fa-solid fa-gear") do
   #         "Settings content goes here"
   #       end
   #
-  #       tabs.tab(id: "notifications", title: "Notifications", icon: "fas fa-bell") do
+  #       tabs.tab(id: "notifications", title: "Notifications", icon: "fa-solid fa-bell") do
   #         "Notifications content goes here"
   #       end
   #     end
@@ -98,7 +98,7 @@ module BulmaPhlex
     #
     # - `id:` — A unique identifier for the tab, used to link the tab button to its content panel
     # - `title:` — The text label displayed on the tab button
-    # - `icon:` — Optional icon class string (e.g. `"fas fa-cog"`) displayed alongside the title
+    # - `icon:` — Optional icon class string (e.g. `"fa-solid fa-gear"`) displayed alongside the title
     # - `active:` — If `true`, this tab is shown as selected on initial render (default: `false`)
     #
     # Expects a block that renders the content for this tab's panel.

data/lib/bulma_phlex/version.rb

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

data/lib/bulma_phlex.rb

@@ -14,4 +14,14 @@ loader.setup # ready!
 # Bulma-styled applications with a Ruby-focused components.
 module BulmaPhlex
   extend Phlex::Kit
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bulma-phlex
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.18.0
 platform: ruby
 authors:
 - Todd Kummer
 bindir: bin
 cert_chain: []
-date: 2026-07-21 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: phlex
@@ -69,6 +69,7 @@ files:
 - lib/bulma_phlex/button.rb
 - lib/bulma_phlex/card.rb
 - lib/bulma_phlex/columns.rb
+- lib/bulma_phlex/configuration.rb
 - lib/bulma_phlex/dropdown.rb
 - lib/bulma_phlex/file_upload.rb
 - lib/bulma_phlex/form_control.rb
@@ -79,6 +80,7 @@ files:
 - lib/bulma_phlex/image.rb
 - lib/bulma_phlex/level.rb
 - lib/bulma_phlex/media_object.rb
+- lib/bulma_phlex/menu.rb
 - lib/bulma_phlex/message.rb
 - lib/bulma_phlex/modal.rb
 - lib/bulma_phlex/navigation_bar.rb
@@ -89,6 +91,7 @@ files:
 - lib/bulma_phlex/tab_components/content.rb
 - lib/bulma_phlex/tab_components/tab.rb
 - lib/bulma_phlex/table.rb
+- lib/bulma_phlex/table/sort.rb
 - lib/bulma_phlex/tabs.rb
 - lib/bulma_phlex/tag.rb
 - lib/bulma_phlex/title.rb