bulma-phlex 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15f8b354ec9106151e857e9fa274851fd8a25c05aab5bd6206418959e5e8201c
-  data.tar.gz: 01302d8221c498b716b2b840948011f17227906246718233c43b252dd385fd22
+  metadata.gz: 4b94a61e80c3da2fb0b776323e40e381322aab22eb9e6fa9493d495d21df8f30
+  data.tar.gz: 8650e8b839631a6e642eb0e04ca33178f67006cdb848144d33f1e32359242653
 SHA512:
-  metadata.gz: 42078a30c124dc2fbc1ad6342034474204ceca1371b0d1a3394d47940926e5a42c7f44e83bab0cd9a54f24ad56860a5bbbd5f38ad72f4531ba809e0f71899cd5
-  data.tar.gz: 98dd7ea99a81ad71302ca5ca78fe2a915c083f6f7f20f520a7cdc2e004768bece733f6650ce9fe064033728877c790b8b75cbf5865d6044d0137a683c0f3ad65
+  metadata.gz: b7dfa409bfa0380dfa15ca8a2d2e0a58b904fb3e75415a497c15e0276f7422a4e5425044421b99545a3decfedaa7dc8f76b342a2addcb56020165aca309671d6
+  data.tar.gz: 7096d053b2c05c2da6ec7306bc4b4fe469d2e8ce4ab5fbf924b756c0b4962831e496e6d2c03ea3ea8ce6f5b46f5ce67cc950a8575fbda17a53537435eb208ceb

data/README.md

@@ -6,6 +6,22 @@
 
 This gem provides a set of ready-to-use [Phlex](https://github.com/phlex-ruby/phlex) components for common [Bulma](https://bulma.io/) components and elements, making it easy to build beautiful, responsive interfaces with a clean, Ruby-focused API.
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Card](#card)
+  - [Dropdown](#dropdown)
+  - [Level](#level)
+  - [NavigationBar](#navigationbar)
+  - [Pagination](#pagination)
+  - [Table](#table)
+  - [Tabs](#tabs)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Credits](#credits)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -54,7 +70,7 @@ Use the Phlex components in your Rails views or any Ruby application that suppor
 [Cards](https://bulma.io/documentation/components/card/) are flexible containers that can display various types of content including headers and content sections.
 
 ```ruby
-render Components::Bulma::Card.new do |card|
+Bulma::Card() do |card|
   card.head("Card Title")
   card.content do
     "This is some card content"
@@ -62,12 +78,27 @@ render Components::Bulma::Card.new do |card|
 end
 ```
 
+#### Rails Feature: Turbo Frame Content
+
+When the `turbo-rails` and `phlex-rails` gems are installed, the Card component also provides method `turbo_frame_content`, which allows the content to be deferred to a turbo frame. The method accepts the same parameters as [the Turbo Rails helper method `turbo_frame_tag`](https://github.com/hotwired/turbo-rails?tab=readme-ov-file#decompose-with-turbo-frames), with the addition of the following two attributes:
+
+- pending_message (default: "Loading...")
+- pending_icon (default: "fas fa-spinner fa-pulse")
+
+```ruby
+Bulma::Card() do |card|
+  card.head("Product Info")
+  card.turbo_frame_content("product", src: product_path(@product), pending_message: "Loading product...")
+end
+```
+
+
 ### Dropdown
 
 The [Dropdown](https://bulma.io/documentation/components/dropdown/) component provides a flexible dropdown menu for navigation or actions. It supports both click-to-toggle (default, requires a Stimulus controller) and hoverable modes, as well as alignment and icon customization.
 
 ```ruby
-render Components::Bulma::Dropdown.new("Next Actions...") do |dropdown|
+Bulma::Dropdown("Next Actions...") do |dropdown|
   dropdown.link "View Profile", "/profile"
   dropdown.link "Go to Settings", "/settings"
   dropdown.divider
@@ -96,7 +127,7 @@ end
 The [Level](https://bulma.io/documentation/layout/level/) component provides a flexible horizontal layout system with left and right alignment.
 
 ```ruby
-render Components::Bulma::Level.new do |level|
+Bulma::Level() do |level|
   level.left do
     button(class: "button") { "Left" }
   end
@@ -115,7 +146,7 @@ end
 The [NavigationBar](https://bulma.io/documentation/components/navbar/) component provides a responsive navigation header with support for branding, navigation links, and dropdown menus.
 
 ```ruby
-render Components::Bulma::NavigationBar.new do |navbar|
+Bulma::NavigationBar() do |navbar|
   navbar.brand_item "My App", "/"
 
   navbar.left do |menu|
@@ -145,7 +176,7 @@ The [Pagination](https://bulma.io/documentation/components/pagination/) componen
 @products = Product.page(params[:page]).per(20)
 
 # In the view:
-render Components::Bulma::Pagination.new(@products, ->(page) { products_path(page: page) })
+Bulma::Pagination(@products, ->(page) { products_path(page: page) })
 ```
 
 ### Table
@@ -155,14 +186,13 @@ The [Table](https://bulma.io/documentation/elements/table/) component provides a
 ```ruby
 users = User.all
 
-render Components::Bulma::Table.new(users) do |table|
+Bulma::Table(users, fullwidth: true, hoverable: true) do |table|
   table.column "Name" do |user|
     user.full_name
   end
 
-  table.column "Email" do |user|
-    user.email
-  end
+  # use the symbol-to-proc shortcut!
+  table.column "Email", &:email
 
   table.column "Actions" do |user|
     link_to "Edit", edit_user_path(user), class: "button is-small"
@@ -170,6 +200,77 @@ render Components::Bulma::Table.new(users) do |table|
 end
 ```
 
+**Constructor Keyword Arguments:**
+
+- `rows`: the data for the table as an enumerable (anything that responds to `each`)
+- `id`: the Id for the table element (defaults to "table")
+- `bordered`: adds the `is-bordered` class (boolean, defaults to false)
+- `striped`: adds the `is-striped` class (boolean, defaults to false)
+- `narrow`: adds the `is-narrow` class (boolean, defaults to false)
+- `hoverable`: adds the `is-hoverable` class (boolean, defaults to false)
+- `fullwidth`: adds the `is-fullwidth` class (boolean, defaults to false)
+
+**Arguments for `column` Method:**
+
+The `column` method takes the column name and any html attributes to be assigned to the table cell element. The block will be called with the row as the parameter.
+
+#### Additional Column Types
+
+Instead of calling `column`, you can also invoke the following methods to add amount, date, and icon columns:
+
+**Arguments for `amount_column` (Rails only):**
+
+- name: content for the `th` element
+- `currency` (keyword): options that will be passed to [Rails helper number_to_currency](https://api.rubyonrails.org/classes/ActiveSupport/NumberHelper.html#method-i-number_to_currency, uses Rails defaults)
+
+```ruby
+  table.amount_column("Payment Amount") { |row| row.payment_amount }
+  table.amount_column("Total", currency: { unit: "€" }, class: "is-bold", &:total)
+```
+
+**Arguments for `date_column`:**
+
+- name: content for the `th` element
+- `format` (keyword): the formatting options (will be passed to `strftime`, defaults to "%Y-%m-%d")
+
+```ruby
+  table.date_column("Due Date", format: "%B %d, %Y") { |row| row.due_date }
+```
+
+**Arguments for `conditional_icon`:**
+
+The icon column is intended to show a boolean flag: a yes / no or an on / off. When the value is true the icon shows and when the value is false it does not.
+
+- name: content for the `th` element
+- `icon_class` (keyword): the icon to show (defaults to the Font Awesome check mark: "fas fa-check")
+ 
+```ruby
+  table.conditional_icon("Completed?", &:complete)
+  table.conditional_icon("Approved?", icon_class: "fas fa-thumbs-up") { |row| row.status == "Approved" }
+```
+
+#### Pagination
+
+If the table should be paginated, invoke method `paginate` with a block that will return a path given a page number.
+
+```ruby
+  table.paginate do |page_number|
+    products_path(page: { number: page_number })
+  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.
+
+
 ### Tabs
 
 The [Tabs](https://bulma.io/documentation/components/tabs/) component provides a way to toggle between different content sections using tabbed navigation, with support for icons and active state management.
@@ -177,7 +278,7 @@ The [Tabs](https://bulma.io/documentation/components/tabs/) component provides a
 Behavior of the tabs can be driven by the data attributes, which are assigned by the object passed in as the `data_attributes_builder`. By default, this will use the `StimulusDataAttributes` class with the controller name `bulma--tabs`. The controller is not provided by this library, but you can create your own Stimulus controller to handle the tab switching logic. Here is [an implementation of a Stimulus controller for Bulma tabs](https://github.com/RockSolt/bulma-rails-helpers/blob/main/app/javascript/controllers/bulma/tabs_controller.js).
 
 ```ruby
-render Components::Bulma::Tabs.new(tabs_class: "is-boxed", contents_class: "ml-4") do |tabs|
+Bulma::Tabs(tabs_class: "is-boxed", contents_class: "ml-4") do |tabs|
   tabs.tab(id: "profile", title: "Profile", active: true) do
     "Profile content goes here"
   end
@@ -219,3 +320,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/RockSo
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+This leverages the [Bulma CSS library](https://bulma.io/documentation/) and [Phlex](https://www.phlex.fun/) but is not endorsed or certified by either. We are fans of the both and this makes using them together easier.

data/lib/bulma-phlex.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "phlex"
 require "bulma_phlex/version"
+require "phlex"
 
 require "components/bulma"
 require "components/bulma/base"
@@ -15,3 +15,5 @@ require "components/bulma/table"
 require "components/bulma/tabs"
 require "components/bulma/tab_components/content"
 require "components/bulma/tab_components/tab"
+
+require "bulma_phlex/railtie" if defined?(Rails::Railtie)

data/lib/bulma_phlex/rails/card_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Card Helper
+    #
+    # This module provides method `turbo_frame_content` to create a card with a turbo frame as its content.
+    module CardHelper
+      extend ActiveSupport::Concern
+
+      included do
+        include Phlex::Rails::Helpers::TurboFrameTag
+      end
+
+      # Renders a Bulma-styled card with a Turbo Frame as its content. This uses the same signatures as
+      # `turbo_frame_tag`, with the addition of two optional attributes: `pending_message` and `pending_icon`.
+      #
+      # The two pending attributes have the following defaults:
+      # - pending_message: "Loading..."
+      # - pending_icon: "fas fa-spinner fa-pulse"
+      def turbo_frame_content(*ids, src: nil, target: nil, **attributes)
+        pending_message = attributes.delete(:pending_message) || "Loading..."
+        pending_icon = attributes.delete(:pending_icon) || "fas fa-spinner fa-pulse"
+
+        content do
+          turbo_frame_tag ids, src: src, target: target, **attributes do
+            span(class: "icon") { i class: pending_icon }
+            span { plain pending_message }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bulma_phlex/rails/table_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  module Rails
+    # # Table Helper
+    #
+    # This module provides method `amount_column` to create an amount column in a table.
+    module TableHelper
+      extend ActiveSupport::Concern
+
+      included do
+        include Phlex::Rails::Helpers::NumberToCurrency
+      end
+
+      def amount_column(header, currency: {}, **html_attributes, &content)
+        html_attributes[:class] = [html_attributes[:class], "has-text-right"].compact.join(" ")
+
+        column(header, **html_attributes) do |row|
+          number_to_currency(content.call(row), **currency)
+        end
+      end
+    end
+  end
+end

data/lib/bulma_phlex/railtie.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "bulma_phlex/rails/card_helper"
+require "bulma_phlex/rails/table_helper"
+
+module BulmaPhlex
+  # # Railtie for BulmaPhlex
+  #
+  # This Railtie adds Rails-specific features to the BulmaPhlex library.
+  class Railtie < ::Rails::Railtie
+    initializer "bulma_phlex" do
+      ActiveSupport.on_load(:action_view) do
+        if defined?(Phlex::Rails)
+          Components::Bulma::Card.include(BulmaPhlex::Rails::CardHelper) if defined?(Turbo)
+          Components::Bulma::Table.include(BulmaPhlex::Rails::TableHelper)
+        end
+      end
+    end
+  end
+end

data/lib/bulma_phlex/version.rb

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

data/lib/components/bulma/card.rb

@@ -11,7 +11,7 @@ module Components
     # ## Example
     #
     # ```ruby
-    # render Components::Bulma::Card.new do |card|
+    # Bulma::Card() do |card|
     #   card.head("Card Title")
     #   card.content do
     #     "This is some card content"
@@ -19,6 +19,11 @@ module Components
     # end
     # ```
     #
+    # ## Rails Feature: Turbo Frame Content
+    #
+    # If the project includes Rails and the Phlex::Rails gem, the `BulmaPhlex::Rails::CardHelper` module
+    # provides a `turbo_frame_content` method to create a card with a turbo frame
+    # as its content. This allows for dynamic loading of card content.
     class Card < Components::Bulma::Base
       def view_template(&)
         div(class: "card", &)
@@ -35,24 +40,6 @@ module Components
           div(class: "content", &)
         end
       end
-
-      if defined?(Phlex::Rails)
-        include Phlex::Rails::Helpers::TurboFrameTag
-
-        # this copies the signature of the turbo_frame_tag helper,
-        # with the addition of a pending_message attribute
-        def turbo_frame_content(*ids, src: nil, target: nil, **attributes)
-          pending_message = attributes.delete(:pending_message) || "Loading..."
-          pending_icon = attributes.delete(:pending_icon) || "fas fa-spinner fa-pulse"
-
-          content do
-            turbo_frame_tag ids, src: src, target: target, **attributes do
-              span(class: "icon") { i class: pending_icon }
-              span { plain pending_message }
-            end
-          end
-        end
-      end
     end
   end
 end

data/lib/components/bulma/dropdown.rb

@@ -25,7 +25,7 @@ module Components
     # ## Example
     #
     # ```ruby
-    # render Components::Bulma::Dropdown.new("Next Actions...") do |dropdown|
+    # Bulma::Dropdown("Next Actions...") do |dropdown|
     #   dropdown.link "View Profile", "/profile"
     #   dropdown.link "Go to Settings", "/settings"
     #   dropdown.divider

data/lib/components/bulma/level.rb

@@ -10,7 +10,7 @@ module Components
     # ## Example:
     #
     # ```ruby
-    # render Components::Bulma::Level.new do |level|
+    # Bulma::Level() do |level|
     #   level.left do
     #     button(class: "button") { "Left" }
     #   end

data/lib/components/bulma/navigation_bar.rb

@@ -11,7 +11,7 @@ module Components
     # ## Example
     #
     # ```ruby
-    # render Components::Bulma::NavigationBar.new do |navbar|
+    # Bulma::NavigationBar() do |navbar|
     #   navbar.brand do
     #     a(href: "/", class: "navbar-item") { "My App" }
     #   end
@@ -26,7 +26,7 @@ module Components
     #
     #     div(class: "navbar-item has-dropdown is-hoverable") do
     #       a(class: "navbar-link") { "Account" }
-    #       render Components::Bulma::NavigationBarDropdown do |dropdown|
+    #       Bulma::NavigationBarDropdown() do |dropdown|
     #         dropdown.item "Sign In", "/login"
     #         dropdown.item "Register", "/register"
     #       end

data/lib/components/bulma/navigation_bar_dropdown.rb

@@ -10,7 +10,7 @@ module Components
     # ## Example
     #
     # ```ruby
-    # render Components::Bulma::NavigationBar.new do |navbar|
+    # Bulma::NavigationBar() do |navbar|
     #   navbar.brand_item "My App", "/"
     #
     #   navbar.right do |menu|

data/lib/components/bulma/pagination.rb

@@ -19,7 +19,7 @@ module Components
     # @products = Product.page(params[:page]).per(20)
     #
     # # In the view:
-    # render Components::Bulma::Pagination.new(@products, ->(page) { products_path(page: page) })
+    # Bulma::Pagination(@products, ->(page) { products_path(page: page) })
     # ```
     #
     class Pagination < Components::Bulma::Base

data/lib/components/bulma/table.rb

@@ -13,7 +13,7 @@ module Components
     # ```ruby
     # users = User.all
     #
-    # render Components::Bulma::Table.new(users) do |table|
+    # Bulma::Table(users) do |table|
     #   table.column "Name" do |user|
     #     user.full_name
     #   end
@@ -29,16 +29,16 @@ module Components
     # ```
     #
     class Table < Components::Bulma::Base
-      def initialize(rows, id = nil)
-        @id = id || id_from_array_or_arel(rows)
+      def initialize(rows, id_or_options = nil, **options)
         @rows = rows
+        @id, @table_class = parse_id_and_options(id_or_options, options, rows)
         @columns = []
       end
 
       def view_template(&)
         vanish(&)
 
-        table(id: @id, class: "table is-fullwidth") do
+        table(id: @id, class: @table_class) do
           thead do
             @columns.each do |column|
               table_header(column)
@@ -63,12 +63,38 @@ module Components
         @columns << { header:, html_attributes:, content: }
       end
 
+      def date_column(header, format: "%Y-%m-%d", **html_attributes, &content)
+        column(header, **html_attributes) do |row|
+          content.call(row)&.strftime(format)
+        end
+      end
+
+      def conditional_icon(header, icon_class: "fas fa-check", **html_attributes, &content)
+        html_attributes[:class] = [html_attributes[:class], "has-text-centered"].compact.join(" ")
+
+        column(header, **html_attributes) do |row|
+          icon_span(icon_class) if content.call(row)
+        end
+      end
+
       def paginate(&path_builder)
         @path_builder = path_builder
       end
 
       private
 
+      def parse_id_and_options(id_or_options, options, rows)
+        if id_or_options.is_a?(String)
+          id = id_or_options
+          opts = options
+        else
+          opts = (id_or_options || {}).merge(options)
+          id = opts.delete(:id) || id_from_array_or_arel(rows)
+        end
+        table_class = "table #{parse_table_classes(opts)}"
+        [id, table_class]
+      end
+
       def id_from_array_or_arel(rows)
         if rows.respond_to? :model
           rows.model.model_name.plural
@@ -77,6 +103,16 @@ module Components
         else
           rows.first.model_name.plural
         end
+      rescue StandardError
+        "table"
+      end
+
+      def parse_table_classes(options)
+        options.slice(*%i[bordered striped narrow hoverable fullwidth])
+               .transform_keys { |key| "is-#{key}" }
+               .select { |_, value| value }
+               .keys
+               .join(" ")
       end
 
       # this derives a th class from the column html attributes

data/lib/components/bulma/tabs.rb

@@ -21,7 +21,7 @@ module Components
     # ## Example
     #
     # ```ruby
-    # render Components::Bulma::Tabs.new do |tabs|
+    # Bulma::Tabs() do |tabs|
     #   tabs.tab(id: "profile", title: "Profile", active: true) do
     #     "Profile content goes here"
     #   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bulma-phlex
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Todd Kummer
@@ -90,6 +90,9 @@ files:
 - README.md
 - Rakefile
 - lib/bulma-phlex.rb
+- lib/bulma_phlex/rails/card_helper.rb
+- lib/bulma_phlex/rails/table_helper.rb
+- lib/bulma_phlex/railtie.rb
 - lib/bulma_phlex/version.rb
 - lib/components/bulma.rb
 - lib/components/bulma/base.rb