bulma-phlex 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5caa2176372f45d0002153e7a4272e79bd3ae01eb530e58c16a29864a3e90c09
-  data.tar.gz: 4ed606f6cb03296a7c0c52eccbe2e31bb2c7eb1c0e2fbbaef1510f8ad8f7d48f
+  metadata.gz: 5b499f6bde82abd9ba89e17560678b305bb3c1ee7f87c68f8bc4d0495e39d343
+  data.tar.gz: ec25f4dbe4c6ef3f10ba99abb961a078076b26fabba4cadff638b350dc090574
 SHA512:
-  metadata.gz: 2d3173c063bb8fc27fa653b34a2f4a57d6b653c313361d1bd1661d13feb760a31e5f8a102407a4024c5e48671031ae5d1b11b6d3414d38b17a3d43d38b2c3918
-  data.tar.gz: 9ec45c90c5060eb1d812d939ae03687c1027ed49c3959bf3f8855216c4e331c7ebb221f4a46903022a0a0d753cebab4a9ff0465528b5dfa424ce37e9b6b7340e
+  metadata.gz: b0920e4a4fb8c5d1f0effab1a35ff3993360611d4c78925403e29638ef060e15b906da7f5a5bce08ab8a42994b1cbd6c8c31362e3d0f000b4d64f97b23aaff59
+  data.tar.gz: e0b6357b7da70427297a68cc48258acd97508f3ead2b547af422fdc3ea444f9a2c04cb12c5d96f37827bd780fc5836b9c022ca0c32aa8bfc0bfdfc9c1976c38a

data/README.md

@@ -6,6 +6,20 @@
 
 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.
 
+## Upgrading to 0.8.0
+
+> [!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*:
+
+**Find:** `Bulma::`  
+**Replace:** `BulmaPhlex::`
+
+Note that this change was also applied to the expected Stimulus controllers. References such as the Navigation bar have been updated from `bulma--navigation-bar` to `bulma-phlex--navigation-bar`.
+
+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.
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -17,6 +31,7 @@ This gem provides a set of ready-to-use [Phlex](https://github.com/phlex-ruby/ph
   - [Pagination](#pagination)
   - [Table](#table)
   - [Tabs](#tabs)
+  - [Title and Subtitle](#title-and-subtitle)
 - [Development](#development)
 - [Contributing](#contributing)
 - [License](#license)
@@ -70,7 +85,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
-Bulma::Card() do |card|
+BulmaPhlex::Card() do |card|
   card.head("Card Title")
   card.content do
     "This is some card content"
@@ -86,19 +101,10 @@ end
 - href: passed to the anchor's `href` attribute
 - Any additional HTML attributes can be passed as keyword arguments.
 
-
-#### 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")
+Icons can be added to the links by passing an `icon` keyword argument with the icon class:
 
 ```ruby
-Bulma::Card() do |card|
-  card.head("Product Info")
-  card.turbo_frame_content("product", src: product_path(@product), pending_message: "Loading product...")
-end
+  card.footer_link("View", "/view", icon: "fas fa-eye")
 ```
 
 
@@ -107,7 +113,7 @@ end
 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
-Bulma::Dropdown("Next Actions...") do |dropdown|
+BulmaPhlex::Dropdown("Next Actions...") do |dropdown|
   dropdown.link "View Profile", "/profile"
   dropdown.link "Go to Settings", "/settings"
   dropdown.divider
@@ -121,7 +127,7 @@ end
 **Options:**
 
 - `label` (required): The dropdown button label.
-- `click`: Stimulus controller name for click-to-toggle (default: `"bulma--dropdown"`). Set to `false` for hoverable.
+- `click`: Stimulus controller name for click-to-toggle (default: `"bulma-phlex--dropdown"`). Set to `false` for hoverable.
 - `alignment`: `:left` (default), `:right`, or `:up`.
 - `icon`: Icon class for the dropdown arrow (default: `"fas fa-angle-down"`).
 
@@ -136,7 +142,7 @@ end
 The [Level](https://bulma.io/documentation/layout/level/) component provides a flexible horizontal layout system with left and right alignment.
 
 ```ruby
-Bulma::Level() do |level|
+BulmaPhlex::Level() do |level|
   level.left do
     button(class: "button") { "Left" }
   end
@@ -155,7 +161,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
-Bulma::NavigationBar(classes: "is-primary") do |navbar|
+BulmaPhlex::NavigationBar(classes: "is-primary") do |navbar|
   navbar.brand_item "My App", "/"
 
   navbar.left do |menu|
@@ -182,7 +188,7 @@ end
 - `container`: When true, wraps the content in a Bulma container. To set a constraint, such as "is-max-desktop", pass that string instead of true. (defaults to false)
 
 > [!NOTE]  
-> Adding a container will limit the width of the Navigation Bar content according to Bulma's container rules. The background color of the navbar will still span the full width of the viewport.
+> Adding a container will limit the width of the Navigation Bar content according to Bulma's container rules. However, the background color of the navbar will still span the full width of the viewport.
 
 ### Pagination
 
@@ -193,7 +199,7 @@ The [Pagination](https://bulma.io/documentation/components/pagination/) componen
 @products = Product.page(params[:page]).per(20)
 
 # In the view:
-Bulma::Pagination(@products, ->(page) { products_path(page: page) })
+BulmaPhlex::Pagination(@products, ->(page) { products_path(page: page) })
 ```
 
 ### Table
@@ -203,7 +209,7 @@ The [Table](https://bulma.io/documentation/elements/table/) component provides a
 ```ruby
 users = User.all
 
-Bulma::Table(users, fullwidth: true, hoverable: true) do |table|
+BulmaPhlex::Table(users, fullwidth: true, hoverable: true) do |table|
   table.column "Name" do |user|
     user.full_name
   end
@@ -233,17 +239,7 @@ The `column` method takes the column name and any html attributes to be assigned
 
 #### 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)
-```
+Instead of calling `column`, you can also invoke the following methods to add date and icon columns:
 
 **Arguments for `date_column`:**
 
@@ -292,10 +288,10 @@ This generates the [Bulma pagination](https://bulma.io/documentation/components/
 
 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.
 
-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).
+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-phlex--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
-Bulma::Tabs(tabs_class: "is-boxed", contents_class: "ml-4") do |tabs|
+BulmaPhlex::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
@@ -323,6 +319,43 @@ end
 - `active`: Adds the `is-active` class to the tab and shows the related content. Non-active content is assigned the `is-hidden` class. Defaults to `false`.
 - `icon`: Specify an optional icon class.
 
+### Tag
+
+The [Tag](https://bulma.io/documentation/elements/tag/) component provides a way to display small, colored labels or tags with customizable styles. The component generates either a `span`, `a`, or `button` element based on the provided options and HTML attributes.
+
+If the HTML attributes include an `href`, an anchor (`a`) element is generated; if not and either the `delete` option is true or there is a `data-action` attribute, a `button` element is generated; otherwise, a `span` element is used.
+
+```ruby
+BulmaPhlex::Tag("New", color: "primary", rounded: true)
+BulmaPhlex::Tag("Sale", light: "danger")
+```
+
+**Constructor Arguments:**
+- `text`: (positional, required) The tag text to display.
+- `color`: (optional) The [Bulma color class](https://bulma.io/documentation/elements/tag/#colors) to apply.
+- `light`: (optional) Use instead of `color` to apply a light color variant.
+- `rounded`: (optional) A boolean indicating whether the tag should have rounded corners.
+- `size`: (optional) The [Bulma tag size](https://bulma.io/documentation/elements/tag/#sizes): normal, medium, or large.
+- `delete`: (optional) A boolean indicating whether to include a delete button on the tag.
+
+
+### Title and Subtitle
+
+The [Title](https://bulma.io/documentation/elements/title/) component provide a way to display headings and subheadings with customizable sizes and styles.
+
+```ruby
+BulmaPhlex::Title("Hello World")
+
+BulmaPhlex::Title("Dr. Strangelove", size: 2, subtitle: "Or: How I Learned to Stop Worrying and Love the Bomb")
+```
+
+**Constructor Arguments:**
+
+- `text`: (positional, required) The main title text to display.
+- `size`: (optional) An integer from 1 to 6 indicating the size of the title. Corresponds to Bulma's `is-<size>` classes.
+- `subtitle`: (optional) The subtitle text to display below the main title.
+- `subtitle_size`: (optional) An integer from 1 to 6 indicating the size of the subtitle. If not provided and a title size is given, it defaults to `size + 2`.
+- `spaced`: (optional) A boolean indicating whether to add the `is-spaced` class to the title.
 
 ## Development
 

data/lib/bulma-phlex.rb

@@ -1,19 +1,3 @@
 # frozen_string_literal: true
 
-require "bulma_phlex/version"
-require "phlex"
-
-require "components/bulma"
-require "components/bulma/base"
-require "components/bulma/card"
-require "components/bulma/dropdown"
-require "components/bulma/level"
-require "components/bulma/navigation_bar_dropdown"
-require "components/bulma/navigation_bar"
-require "components/bulma/pagination"
-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)
+require "bulma_phlex"

data/lib/bulma_phlex/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Base component for all Bulma components
+  #
+  # This is the parent class for all Bulma components in this library.
+  # It provides common utility methods and inherits from `Phlex::HTML`.
+  #
+  class Base < Phlex::HTML
+    private
+
+    def icon_span(icon, additional_classes = nil)
+      span(class: "icon #{additional_classes}".strip) do
+        i(class: icon)
+      end
+    end
+  end
+end

data/lib/bulma_phlex/card.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Card component for content display
+  #
+  # This component implements the [Bulma card](https://bulma.io/documentation/components/card/)
+  # interface. Cards are flexible containers that can display various types of content
+  # including headers, content sections, and more.
+  #
+  # ## Example
+  #
+  # ```ruby
+  # BulmaPhlex::Card() do |card|
+  #   card.head("Card Title")
+  #   card.content do
+  #     "This is some card content"
+  #   end
+  #   card.footer_link("View", "/view", target: "_blank")
+  #   card.footer_link("Edit", "/edit", class: "has-text-primary")
+  # end
+  # ```
+  class Card < BulmaPhlex::Base
+    def view_template(&)
+      vanish(&)
+
+      div(class: "card") do
+        card_header
+        card_content
+        card_footer
+      end
+    end
+
+    def head(title, classes: nil)
+      @header_title = title
+      @header_classes = classes
+    end
+
+    def content(&block)
+      @card_content = block
+    end
+
+    def footer_link(text, href, **html_attributes)
+      (@footer_items ||= []) << [text, href, html_attributes]
+    end
+
+    private
+
+    def card_header
+      return if @header_title.nil?
+
+      header(class: "card-header #{@header_classes}") do
+        p(class: "card-header-title") { plain @header_title }
+      end
+    end
+
+    def card_content
+      return if @card_content.nil?
+
+      div(class: "card-content") do
+        div(class: "content") { @card_content.call }
+      end
+    end
+
+    def card_footer
+      return if @footer_items.nil? || @footer_items.empty?
+
+      footer(class: "card-footer") do
+        @footer_items.each do |text, href, html_attributes|
+          icon = html_attributes.delete(:icon)
+          html_attributes[:class] = [html_attributes[:class], "card-footer-item"].compact.join(" ")
+          a(href:, **html_attributes) do
+            if icon.present?
+              icon_text(icon, text)
+            else
+              plain text
+            end
+          end
+        end
+      end
+    end
+
+    def icon_text(icon, text)
+      span(class: "icon-text") do
+        span(class: "icon") { i(class: icon) }
+        span { text }
+      end
+    end
+  end
+end

data/lib/bulma_phlex/dropdown.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Dropdown component
+  #
+  # This component implements the [Bulma Dropdown](https://bulma.io/documentation/components/dropdown/).
+  #
+  # ## [Hoverable or Toggable](https://bulma.io/documentation/components/dropdown/#hoverable-or-toggable)
+  #
+  # By default the dropdown is in Click Mode and assumes a Stimulus controller named `bulma-phlex--dropdown` is present
+  # to handle the click events. The controller name can be customized using the `click` option.
+  #
+  # Set click to `false` to make the dropdown hoverable instead of togglable.
+  #
+  # ## Alignment
+  #
+  # Use the `alignment` option to control the dropdown's alignment. By default, it aligns to the left. Pass in
+  # `:right` or `:up` to change the alignment.
+  #
+  # ## Icon
+  #
+  # Use the `icon` option to customize the dropdown's icon. By default, it uses the Font Awesome angle down icon.
+  #
+  # ## Example
+  #
+  # ```ruby
+  # BulmaPhlex::Dropdown("Next Actions...") do |dropdown|
+  #   dropdown.link "View Profile", "/profile"
+  #   dropdown.link "Go to Settings", "/settings"
+  #   dropdown.divider
+  #   dropdown.item("This is just a text item")
+  #   dropdown.item do
+  #     div(class: "has-text-weight-bold") { "This is a bold item" }
+  #   end
+  # end
+  # ```
+  #
+  class Dropdown < BulmaPhlex::Base
+    def initialize(label, click: "bulma-phlex--dropdown", alignment: "left", icon: "fas fa-angle-down")
+      @label = label
+      @click = click
+      @alignment = alignment
+      @icon = icon
+    end
+
+    def view_template(&)
+      div(class: "dropdown #{"is-hoverable" unless @click} #{alignment_class}".strip, **stimulus_controller) do
+        div(class: "dropdown-trigger") do
+          button(
+            class: "button",
+            aria_haspopup: "true",
+            aria_controls: "dropdown-menu",
+            **stimulus_action
+          ) do
+            span { @label }
+            span(class: "icon is-small") do
+              i(class: @icon, aria_hidden: "true")
+            end
+          end
+        end
+
+        div(class: "dropdown-menu", id: "dropdown-menu", role: "menu") do
+          div(class: "dropdown-content", &)
+        end
+      end
+    end
+
+    def item(content = nil, &)
+      if block_given?
+        div(class: "dropdown-item", &)
+      else
+        div(class: "dropdown-item") { content }
+      end
+    end
+
+    def link(label, path)
+      a(class: "dropdown-item", href: path) { label }
+    end
+
+    def divider
+      hr(class: "dropdown-divider")
+    end
+
+    private
+
+    def alignment_class
+      case @alignment.to_sym
+      when :right
+        "is-right"
+      when :up
+        "is-up"
+      end
+    end
+
+    def stimulus_controller
+      return {} unless @click
+
+      { data: { controller: @click } }
+    end
+
+    def stimulus_action
+      return {} unless @click
+
+      { data: { action: "#{@click}#toggle" } }
+    end
+  end
+end

data/lib/bulma_phlex/level.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Level component for responsive horizontal layouts
+  #
+  # This component implements the [Bulma level](https://bulma.io/documentation/layout/level/)
+  # interface, providing a flexible horizontal layout system with left and right alignment.
+  #
+  # ## Example:
+  #
+  # ```ruby
+  # BulmaPhlex::Level() do |level|
+  #   level.left do
+  #     button(class: "button") { "Left" }
+  #   end
+  #
+  #   level.right do
+  #     button(class: "button") { "Right" }
+  #   end
+  #   level.right do
+  #     button(class: "button") { "Right 2" }
+  #   end
+  # end
+  # ```
+  #
+  class Level < BulmaPhlex::Base
+    def initialize
+      @items = []
+      @left = []
+      @right = []
+    end
+
+    def view_template(&)
+      vanish(&)
+
+      div(class: "level") do
+        div(class: "level-left") do
+          @left.each { level_item(it) }
+        end
+
+        @items.each { level_item(it) }
+
+        div(class: "level-right") do
+          @right.each { level_item(it) }
+        end
+      end
+    end
+
+    def item(&content)
+      @items << content
+    end
+
+    def left(&content)
+      @left << content
+    end
+
+    def right(&content)
+      @right << content
+    end
+
+    private
+
+    def level_item(content)
+      div(class: "level-item") { content.call }
+    end
+  end
+end

data/lib/bulma_phlex/navigation_bar.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Navigation bar component for site navigation
+  #
+  # This component implements the [Bulma navbar](https://bulma.io/documentation/components/navbar/)
+  # interface. It provides a responsive navigation header with support for branding, navigation
+  # links, and dropdown menus, automatically collapsing on mobile devices.
+  #
+  # ## Example
+  #
+  # ```ruby
+  # BulmaPhlex::NavigationBar() do |navbar|
+  #   navbar.brand do
+  #     a(href: "/", class: "navbar-item") { "My App" }
+  #   end
+  #
+  #   navbar.left do
+  #     a(href: "/", class: "navbar-item") { "Home" }
+  #     a(href: "/products", class: "navbar-item") { "Products" }
+  #   end
+  #
+  #   navbar.right do
+  #     a(href: "/about", class: "navbar-item") { "About" }
+  #
+  #     div(class: "navbar-item has-dropdown is-hoverable") do
+  #       a(class: "navbar-link") { "Account" }
+  #       BulmaPhlex::NavigationBarDropdown() do |dropdown|
+  #         dropdown.item "Sign In", "/login"
+  #         dropdown.item "Register", "/register"
+  #       end
+  #     end
+  #   end
+  # end
+  # ```
+  #
+  class NavigationBar < BulmaPhlex::Base
+    def initialize(container: false, classes: "")
+      @container = container
+      @classes = classes
+      @brand = []
+      @left = []
+      @right = []
+    end
+
+    def view_template(&)
+      vanish(&)
+
+      nav(class: "navbar #{@classes}".rstrip,
+          role: "navigation",
+          aria_label: "main navigation",
+          data: { controller: "bulma-phlex--navigation-bar" }) do
+        optional_container do
+          div(class: "navbar-brand") do
+            @brand.each(&:call)
+
+            a(class: "navbar-burger",
+              role: "button",
+              aria_label: "menu",
+              aria_expanded: "false",
+              data: {
+                action: "bulma-phlex--navigation-bar#toggle",
+                "bulma-phlex--navigation-bar-target": "burger"
+              }) do
+              4.times { span(aria_hidden: "true") }
+            end
+          end
+
+          div(class: "navbar-menu",
+              data: { "bulma-phlex--navigation-bar-target": "menu" }) do
+            div(class: "navbar-start") do
+              @left.each(&:call)
+            end
+
+            div(class: "navbar-end") do
+              @right.each(&:call)
+            end
+          end
+        end
+      end
+    end
+
+    def brand(&block)
+      @brand << block
+    end
+
+    def left(&block)
+      @left << block
+    end
+
+    def right(&block)
+      @right << block
+    end
+
+    private
+
+    def optional_container(&)
+      if @container
+        constraint = @container if @container.is_a?(String) || @container.is_a?(Symbol)
+        div(class: "container #{constraint}".rstrip, &)
+      else
+        yield
+      end
+    end
+  end
+end

data/lib/bulma_phlex/navigation_bar_dropdown.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BulmaPhlex
+  # Dropdown component for the Bulma navigation bar
+  #
+  # This component implements the dropdown portion of the [Bulma navbar](https://bulma.io/documentation/components/navbar/#dropdown-menu).
+  # It provides a structured way to add dropdown menus to a navigation bar with headers, items, and dividers.
+  #
+  # ## Example
+  #
+  # ```ruby
+  # BulmaPhlex::NavigationBar() do |navbar|
+  #   navbar.brand_item "My App", "/"
+  #
+  #   navbar.right do |menu|
+  #     menu.dropdown "Account" do |dropdown|
+  #       dropdown.header "User"
+  #       dropdown.item "Profile", "/profile"
+  #       dropdown.item "Settings", "/settings"
+  #       dropdown.divider
+  #       dropdown.item "Sign Out", "/logout"
+  #     end
+  #   end
+  # end
+  # ```
+  #
+  class NavigationBarDropdown < BulmaPhlex::Base
+    def view_template(&)
+      div(class: "navbar-dropdown is-right", &)
+    end
+
+    def header(label)
+      div(class: "navbar-item header has-text-weight-medium") { label }
+    end
+
+    def item(label, path)
+      a(class: "navbar-item", href: path) { label }
+    end
+
+    def divider
+      hr(class: "navbar-divider")
+    end
+  end
+end