cubit_components 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cb5dec0910e548ed2c02c397e6d86114e03ce01bec318de5226908b947a5d83b
+  data.tar.gz: 197294b2c0f689acd25e06bf41bbc4ca932336992768b45e594ff43d54043418
+SHA512:
+  metadata.gz: 29a419c390f2df73fd6e6783370e68aac8b028620ec9073d49d5f17bc6051a98f0ef49b676dcc1bc3019729b8f6bf4668c257d453d71ce5819544455148a6e00
+  data.tar.gz: 1f9502b054915d5071ee4f660d6cab32184ce1761e79eab82f5f0884f62a312da2771dd1af4e111a14100d36e1a78a7591f4b1a80207a37ad6fe6c863bfb8983

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Fabio Papa
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,58 @@
+# CubitComponents
+
+A collection of reusable ViewComponents with standardized styling and utility class validation.
+
+## Installation
+
+Add to your Gemfile:
+```ruby
+gem 'cubit_components'
+```
+Then run:
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Component
+```erb
+<%= render CubitComponents::BoxComponent.new do %>
+  Box content
+<% end %>
+```
+
+### With Custom Classes
+```erb
+<%= render CubitComponents::StackComponent.new(classes: "bg-gray-100") do %>
+  <div>Item 1</div>
+  <div>Item 2</div>
+<% end %>
+```
+
+### Available Components
+- BoxComponent - Basic container
+- StackComponent - Vertical layout 
+- ColumnsComponent - Horizontal layout
+- BleedComponent - Negative margins
+- ContentBlockComponent - Width-constrained container
+
+## Configuration
+
+Create an initializer to customize validation behavior:
+```ruby
+# config/initializers/cubit_components.rb
+CubitComponents.configure do |config|
+  config.invalid_vattr_behavior = :raise # :warn, :silent
+end
+```
+
+## Development
+After checking out the repo:
+```bash
+bin/setup
+bundle exec rspec
+```
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/cubit_components/application.css

@@ -0,0 +1,6 @@
+/*
+ *= require_tree .
+ *= require_self
+ */
+
+@import "tailwindcss";

data/app/assets/tailwind/cubit_components/engine.css

@@ -0,0 +1,4 @@
+@import "tailwindcss";
+
+@source inline("{sm:,md:,lg:,xl:,2xl:,}flex-row");
+@source "../../../../lib/**/*";

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/cubit_components/base_component.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "view_component"
+require_relative "vattr_validator"
+
+module CubitComponents
+  class BaseComponent < ViewComponent::Base
+    include ::CubitComponents::VattrValidator
+
+    # Valid “utility” / “variant” classes
+    VALID_VATTRS = Set.new(
+      %w[gap-small gap-medium text-left text-center text-right]
+    ).freeze
+
+    # @param vattrs [Array<String>] extra utility / variant classes
+    def initialize(element: "div", classes: "", vattrs: [])
+      @element = element
+      @classes = classes
+      @vattrs = vattrs
+
+      validate_vattrs(vattrs, self.class::VALID_VATTRS) if validate_vattrs?
+    end
+
+    def call
+      content_tag @element, content, class: all_classes
+    end
+
+    private
+
+    def all_classes
+      (Array(@vattrs) + Array(@classes.to_s.split)).join(" ").strip
+    end
+
+    # Sub-classes may disable validation
+    def validate_vattrs?
+      true
+    end
+  end
+end

data/lib/cubit_components/bleed_component.rb

@@ -0,0 +1,26 @@
+module CubitComponents
+  class BleedComponent < BaseComponent
+    # Allow negative margin utility classes.
+    # They follow Tailwind's pattern, e.g., "-m-3" or "sm:-mx-4"
+    VALID_VATTRS = Set.new(
+      begin
+        breakpoints = ["", "sm:", "md:", "lg:", "xl:"]
+        directions = ["", "x", "y", "t", "r", "b", "l"]
+        values = %w[1 2 3 4 5]
+        breakpoints.flat_map do |bp|
+          directions.flat_map do |dir|
+            values.map do |val|
+              # For no breakpoint, produces e.g. "-m-3"
+              # For a breakpoint, produces e.g. "sm:-mx-4"
+              "#{bp}-m#{dir}-#{val}"
+            end
+          end
+        end
+      end
+    ).freeze
+
+    def initialize(element: "div", classes: "", vattrs: [])
+      super
+    end
+  end
+end

data/lib/cubit_components/box_component.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CubitComponents
+  class BoxComponent < BaseComponent
+    # Accept every vattr ⇒ disable validation
+    private def validate_vattrs? = false
+  end
+end

data/lib/cubit_components/columns_component.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CubitComponents
+  # Horizontal flex-layout that can collapse into a vertical stack.
+  class ColumnsComponent < BaseComponent
+    VALID_VATTRS = Set.new(
+      %w[
+        gap-small gap-medium gap-large
+        items-start items-center items-end
+        text-left text-center text-right
+      ]
+    ).freeze
+
+    # :reverse   – Boolean, applies `flex-row-reverse`
+    # :collapse_below – breakpoint string, ex. "sm" → "sm:flex-col"
+    # `reverse` can only be true when `collapse_below` is non-nil
+    def initialize(element: "div", classes: "", vattrs: [], reverse: false, collapse_below: nil)
+      @reverse = reverse
+      @collapse_below = collapse_below
+
+      super(
+        element: element,
+        classes: build_layout_classes(classes),
+        vattrs: vattrs
+      )
+    end
+
+    # Nested column – accepts any utility classes, no validation
+    class ColumnComponent < BaseComponent
+      private def validate_vattrs? = false
+    end
+
+    private
+
+    def build_layout_classes(user)
+      base = %w[flex]
+      base << if @collapse_below && @reverse
+        "flex-col-reverse"
+      elsif @collapse_below
+        "flex-col"
+      else
+        "flex-row"
+      end
+      base << "#{@collapse_below}:flex-row" if @collapse_below
+      (base + user.to_s.split).join(" ")
+    end
+  end
+end

data/lib/cubit_components/configuration.rb

@@ -0,0 +1,18 @@
+module CubitComponents
+  class Configuration
+    attr_reader :invalid_vattr_behavior
+
+    def initialize
+      # Set default values
+      @invalid_vattr_behavior = :warn
+    end
+
+    def invalid_vattr_behavior=(value)
+      unless [:warn, :raise, :silent].include?(value)
+        raise ArgumentError, "invalid_class_behavior must be :warn, :raise, or :silent"
+      end
+
+      @invalid_vattr_behavior = value
+    end
+  end
+end

data/lib/cubit_components/content_block_component.rb

@@ -0,0 +1,21 @@
+module CubitComponents
+  class ContentBlockComponent < BaseComponent
+    DEFAULT_CLASSES = "max-w-screen mx-auto"
+    VALID_VATTRS = Set.new(
+      %w[
+        max-w-3xs max-w-2xs max-w-xs
+        max-w-sm max-w-md max-w-lg
+        max-w-xl max-w-2xl max-w-3xl max-w-4xl max-w-5xl max-w-6xl max-w-7xl
+        max-w-none max-w-full max-w-screen
+      ]
+    )
+
+    # No extra vattr validation is required, so simply merge with default classes.
+    def initialize(element: "div", classes: "", vattrs: [])
+      default_classes = DEFAULT_CLASSES.split(" ")
+      default_classes.delete("max-w-screen") if vattrs.any? { |v| v.start_with?("max-w-") }
+      merged_classes = [*default_classes, classes].join(" ").strip
+      super(element: element, classes: merged_classes, vattrs: vattrs)
+    end
+  end
+end

data/lib/cubit_components/engine.rb

@@ -0,0 +1,14 @@
+require "rails"
+require "view_component"
+
+module CubitComponents
+  class Engine < ::Rails::Engine
+    config.view_component.preview_paths << root.join("lib/cubit_components/previews")
+
+    isolate_namespace CubitComponents
+
+    initializer "cubit_components.assets" do |app|
+      app.config.assets.precompile += %w[cubit_components/application.css]
+    end
+  end
+end

data/lib/cubit_components/inline_component.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CubitComponents
+  class InlineComponent < BaseComponent
+    VALID_VATTRS = Set.new(
+      %w[gap-6 gap-small gap-medium gap-large text-left text-center text-right]
+    ).freeze
+
+    # collapse_below – e.g. "sm", "md"; adds "#{breakpoint}:flex-col"
+    def initialize(element: "div", classes: "", vattrs: [], collapse_below: nil)
+      extra_classes = %w[flex flex-wrap]
+      extra_classes << "flex-col #{collapse_below}:flex-row" if collapse_below
+
+      combined_classes = ([classes] + extra_classes).reject(&:empty?).join(" ")
+
+      super(element: element, classes: combined_classes, vattrs: vattrs)
+    end
+  end
+end

data/lib/cubit_components/page_block_component.rb

@@ -0,0 +1,37 @@
+module CubitComponents
+  class PageBlockComponent < BaseComponent
+    DEFAULT_OUTER_CLASSES = "px-4 sm:px-6".freeze
+    VALID_VATTRS = Set.new(
+      %w[
+        max-w-3xs max-w-2xs max-w-xs
+        max-w-sm max-w-md max-w-lg
+        max-w-xl max-w-2xl max-w-3xl max-w-4xl max-w-5xl max-w-6xl max-w-7xl
+        max-w-none max-w-full max-w-screen
+      ]
+    )
+
+    # Optionally allow extra classes for the inner content block if needed.
+    def initialize(element: "div", classes: "", vattrs: [], content_block_classes: "")
+      @outer_classes = [DEFAULT_OUTER_CLASSES, classes].join(" ").strip
+      @content_block_classes = content_block_classes
+      @content_block_vattrs = vattrs # Pass the vattrs wholesale to the inner content block
+
+      super(element: element, classes: @outer_classes)
+    end
+
+    def call
+      content_tag @element, class: @outer_classes do
+        render_content_block { content }
+      end
+    end
+
+    private
+
+    def render_content_block(&block)
+      # Create a ContentBlockComponent, passing in any inner classes overrides.
+      ContentBlockComponent
+        .new(classes: @content_block_classes, vattrs: @content_block_vattrs)
+        .render_in(view_context, &block)
+    end
+  end
+end

data/lib/cubit_components/page_component.rb

@@ -0,0 +1,34 @@
+module CubitComponents
+  class PageComponent < BaseComponent
+    VALID_VATTRS = %w[
+      min-h-screen flex
+    ]
+
+    # Use ViewComponent slot for footer.
+    renders_one :footer
+
+    erb_template <<~ERB
+      <<%= @element %> class="<%= classes %>">
+        <div class="grow pb-30<%= ' min-h-screen' if below_fold? %>">
+          <%= content %>
+        </div>
+        <%= footer %>
+      </<%= @element %>>
+    ERB
+
+    # @param footer_position: nil (default) or "below_fold"
+    def initialize(footer_position: nil, classes: "")
+      @footer_position = footer_position
+      @classes = ["flex", "flex-col", "min-h-screen", classes].join(" ")
+      super(element: "div", classes: @classes)
+    end
+
+    private
+
+    attr_reader :classes
+
+    def below_fold?
+      @footer_position.to_s == "below_fold"
+    end
+  end
+end

data/lib/cubit_components/previews/bleed_component_preview.rb

@@ -0,0 +1,13 @@
+class BleedComponentPreview < ViewComponent::Preview
+  def default
+    render(CubitComponents::BleedComponent.new(vattrs: ["-m-3"])) do
+      tag.div("Bleed Content", class: "bg-gray-100 p-4")
+    end
+  end
+
+  def responsive
+    render(CubitComponents::BleedComponent.new(vattrs: ["sm:-mx-2", "md:-m-4"])) do
+      tag.div("Responsive Bleed Content", class: "bg-blue-100 p-4")
+    end
+  end
+end

data/lib/cubit_components/previews/box_component_preview.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class BoxComponentPreview < ViewComponent::Preview
+  def default
+    render(CubitComponents::BoxComponent.new) { "Default Box" }
+  end
+
+  def with_utilities
+    render(CubitComponents::BoxComponent.new(classes: "p-4",
+      vattrs: %w[gap-small text-center])) { "Preview" }
+  end
+end

data/lib/cubit_components/previews/columns_component_preview.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class ColumnsComponentPreview < ViewComponent::Preview
+  # Two equal columns, default layout
+  def default
+    render(CubitComponents::ColumnsComponent.new(vattrs: %w[gap-medium])) do
+      tag.div("Col 1", class: "w-1/3") +
+        tag.div("Col 2", class: "w-1/6") +
+        tag.div("Col 3", class: "w-1/2")
+    end
+  end
+
+  # Reversed order & collapses below md
+  def reversed_and_collapsing
+    render(CubitComponents::ColumnsComponent.new(reverse: true, collapse_below: "md", vattrs: %w[gap-large items-center])) do
+      tag.div("First", class: "w-full") +
+        tag.div("Second", class: "w-full")
+    end
+  end
+end

data/lib/cubit_components/previews/components_index.rb

@@ -0,0 +1,28 @@
+module CubitComponents
+  module Previews
+    class ComponentsIndex < ViewComponent::Preview
+      # A listing of all component previews.
+      def index
+        previews = [
+          {name: "BleedComponentPreview", path: "/cubit_components/bleed_component_preview"},
+          {name: "BoxComponentPreview", path: "/cubit_components/box_component_preview"},
+          {name: "ColumnsComponentPreview", path: "/cubit_components/columns_component_preview"},
+          {name: "ContentBlockComponentPreview", path: "/cubit_components/content_block_component_preview"},
+          {name: "InlineComponentPreview", path: "/cubit_components/inline_component_preview"},
+          {name: "PageBlockComponentPreview", path: "/cubit_components/page_block_component_preview"},
+          {name: "PageComponentPreview", path: "/cubit_components/page_component_preview"},
+          {name: "SpreadComponentPreview", path: "/cubit_components/spread_component_preview"},
+          {name: "StackComponentPreview", path: "/cubit_components/stack_component_preview"},
+          {name: "TilesComponentPreview", path: "/cubit_components/tiles_component_preview"}
+        ]
+
+        html = "<h1>Components Preview Index</h1><ul>"
+        previews.each do |preview|
+          html << "<li><a href='#{preview[:path]}'>#{preview[:name]}</a></li>"
+        end
+        html << "</ul>"
+        html.html_safe
+      end
+    end
+  end
+end

data/lib/cubit_components/previews/content_block_component_preview.rb

@@ -0,0 +1,13 @@
+class ContentBlockComponentPreview < ViewComponent::Preview
+  def default
+    render(CubitComponents::ContentBlockComponent.new(vattrs: %w[max-w-sm])) do
+      tag.p("This content is constrained by the max-width and centered.")
+    end
+  end
+
+  def with_extra_classes
+    render(CubitComponents::ContentBlockComponent.new(classes: "bg-gray-100 p-4")) do
+      tag.p("Content block with extra background and padding.")
+    end
+  end
+end

data/lib/cubit_components/previews/inline_component_preview.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+class InlineComponentPreview < ViewComponent::Preview
+  def default
+    render(CubitComponents::InlineComponent.new(vattrs: ["gap-6"])) do
+      tag.div("Block 1") +
+        tag.div("Block 2") +
+        tag.div("Block 3") +
+        tag.div("Block 4") +
+        tag.div("Block 5") +
+        tag.div("Block 6")
+    end
+  end
+
+  def collapse_below_md
+    render(CubitComponents::InlineComponent.new(collapse_below: "sm", vattrs: ["gap-6"])) do
+      tag.div("Block 1") +
+        tag.div("Block 2") +
+        tag.div("Block 3") +
+        tag.div("Block 4") +
+        tag.div("Block 5") +
+        tag.div("Block 6")
+    end
+  end
+end

data/lib/cubit_components/previews/page_block_component_preview.rb

@@ -0,0 +1,13 @@
+class PageBlockComponentPreview < ViewComponent::Preview
+  def default
+    render(CubitComponents::PageBlockComponent.new(vattrs: %w[max-w-sm])) do
+      tag.p("This is a page block which wraps a content block. Outer padding is applied.")
+    end
+  end
+
+  def custom_inner
+    render(CubitComponents::PageBlockComponent.new(content_block_classes: "bg-white shadow-lg p-6")) do
+      tag.p("Page block with a customized inner content block.")
+    end
+  end
+end

data/lib/cubit_components/previews/page_component_preview.rb

@@ -0,0 +1,17 @@
+class PageComponentPreview < ViewComponent::Preview
+  def default
+    render(CubitComponents::PageComponent.new(footer_position: "screen_bottom", classes: "bg-gray-100")) do |component|
+      component.with_footer { tag.footer("Footer content", class: "p-4 bg-blue-200") }
+      tag.header("Header content", class: "p-4 bg-blue-200") +
+        tag.main("Body content", class: "p-4")
+    end
+  end
+
+  def below_fold
+    render(CubitComponents::PageComponent.new(footer_position: "below_fold", classes: "bg-gray-100")) do |component|
+      component.with_footer { tag.footer("Footer content", class: "p-4 bg-blue-200") }
+      tag.header("Header content", class: "p-4 bg-blue-200") +
+        tag.main("Body content", class: "p-4")
+    end
+  end
+end

data/lib/cubit_components/previews/preview_helper.rb

@@ -0,0 +1,15 @@
+module CubitComponents
+  module Previews
+    module PreviewHelper
+      # Returns a documentation link for the component.
+      def documentation_link(component_name)
+        "https://your.documentation.url/#{component_name}"
+      end
+
+      # Standard documentation render for previews
+      def render_documentation(component_name)
+        render plain: "See documentation: #{documentation_link(component_name)}"
+      end
+    end
+  end
+end

data/lib/cubit_components/previews/spread_component_preview.rb

@@ -0,0 +1,46 @@
+class SpreadComponentPreview < ViewComponent::Preview
+  # Default horizontal spread with items-start and text-left
+  def default
+    render(CubitComponents::SpreadComponent.new) do
+      tag.div(class: "p-2 border") { "Item 1" } +
+        tag.div(class: "p-2 border") { "Item 2" } +
+        tag.div(class: "p-2 border") { "Item 3" }
+    end
+  end
+
+  # Vertical spread layout
+  def vertical
+    render(CubitComponents::SpreadComponent.new(vattrs: ["vertical", "items-center"])) do
+      tag.div(class: "p-2 border") { "Item 1" } +
+        tag.div(class: "p-2 border") { "Item 2" } +
+        tag.div(class: "p-2 border") { "Item 3" }
+    end
+  end
+
+  # Centered items
+  def centered_items
+    render(CubitComponents::SpreadComponent.new(vattrs: ["items-center"])) do
+      tag.div(class: "p-2 border h-16") { "Tall Item" } +
+        tag.div(class: "p-2 border") { "Regular Item" } +
+        tag.div(class: "p-2 border h-12") { "Medium Item" }
+    end
+  end
+
+  # Text alignment
+  def text_alignment
+    render(CubitComponents::SpreadComponent.new(vattrs: ["text-center"])) do
+      tag.div(class: "p-2 border w-32") { "Centered Text" } +
+        tag.div(class: "p-2 border w-32") { "Centered Text" } +
+        tag.div(class: "p-2 border w-32") { "Centered Text" }
+    end
+  end
+
+  # Custom element
+  def custom_element
+    render(CubitComponents::SpreadComponent.new(element: "section", classes: "border p-4")) do
+      tag.div(class: "p-2 bg-gray-100") { "Section Item 1" } +
+        tag.div(class: "p-2 bg-gray-100") { "Section Item 2" } +
+        tag.div(class: "p-2 bg-gray-100") { "Section Item 3" }
+    end
+  end
+end

data/lib/cubit_components/previews/stack_component_preview.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class StackComponentPreview < ViewComponent::Preview
+  # Shows default classes (gap-0 text-left)
+  def default
+    render(CubitComponents::StackComponent.new) do
+      tag.div("Item 1", class: "border") +
+        tag.div("Item 2", class: "border") +
+        tag.div("Item 3", class: "border")
+    end
+  end
+
+  # gap-medium
+  # Overrides gap utility
+  def custom_gap
+    render(CubitComponents::StackComponent.new(vattrs: %w[gap-medium])) do
+      tag.div("Medium gap", class: "border") +
+        tag.div("Medium gap", class: "border") +
+        tag.div("Medium gap", class: "border")
+    end
+  end
+end

data/lib/cubit_components/previews/tiles_component_preview.rb

@@ -0,0 +1,20 @@
+class TilesComponentPreview < ViewComponent::Preview
+  # Default preview: renders three simple tiles.
+  def default
+    render(CubitComponents::TilesComponent.new(vattrs: ["grid-cols-5"])) do
+      tag.div("Tile 1", class: "border p-2") +
+        tag.div("Tile 2", class: "border p-2") +
+        tag.div("Tile 3", class: "border p-2")
+    end
+  end
+
+  # Preview with custom grid columns and gap overrides.
+  def custom_grid_and_gap
+    render(CubitComponents::TilesComponent.new(vattrs: ["md:grid-cols-3", "gap-4"])) do
+      tag.div("Tile 1", class: "border p-2") +
+        tag.div("Tile 2", class: "border p-2") +
+        tag.div("Tile 3", class: "border p-2") +
+        tag.div("Tile 4", class: "border p-2")
+    end
+  end
+end

data/lib/cubit_components/spread_component.rb

@@ -0,0 +1,59 @@
+require "debug"
+
+module CubitComponents
+  class SpreadComponent < BaseComponent
+    VALID_VATTRS = Set.new(
+      %w[
+        items-start items-center items-end
+        text-left text-center text-right
+        flex-col flex-row
+        justify-between
+      ]
+    ).freeze
+
+    DEFAULT_VATTRS = %w[flex justify-between w-full items-start text-left].freeze
+
+    # @param element [String] HTML element to use
+    # @param classes [String] additional CSS classes
+    # @param vattrs [Array<String>] utility/variant attributes
+    def initialize(element: "div", classes: "", vattrs: [])
+      vattrs = merge_default_vattrs(Array(vattrs))
+
+      extra_classes = []
+      # Add vertical class if specified, otherwise it's horizontal by default
+      if vattrs.include?("vertical")
+        extra_classes << "flex-col"
+        extra_classes << "h-full"
+        vattrs.delete("vertical")
+      else
+        extra_classes << "flex-row"
+      end
+
+      super(
+        element: element,
+        classes: [classes, extra_classes].join(" ").strip,
+        vattrs: vattrs
+      )
+    end
+
+    private
+
+    def merge_default_vattrs(custom)
+      result = DEFAULT_VATTRS.dup
+
+      # Override defaults with custom values
+      custom.each do |attr|
+        # For each attribute type (items-*, text-*), remove the default if a custom is provided
+        if attr.start_with?("items-")
+          result.delete_if { |v| v.start_with?("items-") }
+        elsif attr.start_with?("text-")
+          result.delete_if { |v| v.start_with?("text-") }
+        end
+
+        result << attr
+      end
+
+      result
+    end
+  end
+end

data/lib/cubit_components/stack_component.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CubitComponents
+  class StackComponent < BaseComponent
+    VALID_VATTRS = Set.new(
+      %w[
+        gap-0 gap-small gap-medium gap-large
+        text-left text-center text-right
+      ]
+    ).freeze
+
+    DEFAULT_VATTRS = %w[flex flex-col gap-0 text-left].freeze
+
+    # Forward element / classes, but merge-override vattrs
+    def initialize(element: "div", classes: "", vattrs: [])
+      vattrs = merge_default_vattrs(Array(vattrs))
+      super
+    end
+
+    private
+
+    # Replace default gap- or text- related vattrs when caller supplies one
+    def merge_default_vattrs(custom)
+      merged = DEFAULT_VATTRS.dup
+      custom.each do |v|
+        merged.reject! { |d| d.start_with?("gap-") } if v.start_with?("gap-")
+        merged.reject! { |d| d.start_with?("text-") } if v.start_with?("text-")
+      end
+      (merged + custom).uniq
+    end
+  end
+end

data/lib/cubit_components/tailwind_generated_classes_chat.txt

@@ -0,0 +1,127 @@
+ 
+
+Well, the thing I didn't mention is that this is a Rails engine/gem, and the host app can define other custom breakpoints and I need to have tailwind capture those too. I don't think any of the solutions you mentioned can work with that. Correct me if I'm wrong.
+
+You're absolutely right! Since this is a Rails engine/gem where the host app can define arbitrary custom breakpoints, none of my previous solutions would work. This is a tricky problem because Tailwind needs to know about classes at build time, but you don't know what breakpoints the host app will define.
+
+Here are some approaches that could work:
+
+## Solution 1: Host App Responsibility (Recommended)
+
+Document that host apps need to safelist the dynamic classes themselves:
+
+```ruby
+# In your gem's documentation/README
+# 
+# If you use custom breakpoints with CubitComponents::ColumnsComponent,
+# add them to your tailwind.config.js safelist:
+#
+# safelist: [
+#   { pattern: /^[a-z]+:flex-row$/ },
+#   // or explicitly:
+#   'custom-breakpoint:flex-row',
+#   'another-breakpoint:flex-row'
+# ]
+```
+
+## Solution 2: Configuration Hook
+
+Provide a configuration option in your engine where host apps can register their breakpoints:
+
+```ruby
+# In your engine
+module CubitComponents
+  class << self
+    attr_accessor :breakpoints
+    
+    def configure
+      yield self
+    end
+  end
+  
+  self.breakpoints = %w[sm md lg xl 2xl]
+end
+
+# Host app would do:
+CubitComponents.configure do |config|
+  config.breakpoints = %w[sm md lg xl 2xl tablet desktop custom]
+end
+```
+
+Then provide a rake task or generator that outputs the necessary Tailwind config:
+
+```ruby
+# lib/tasks/cubit_components_tasks.rake
+namespace :cubit_components do
+  desc "Generate Tailwind safelist for CubitComponents"
+  task :tailwind_safelist => :environment do
+    breakpoints = CubitComponents.breakpoints
+    safelist = breakpoints.map { |bp| "#{bp}:flex-row" }
+    
+    puts "Add this to your tailwind.config.js safelist:"
+    puts safelist.to_json
+  end
+end
+```
+
+## Solution 3: Always Use Style Attribute
+
+For truly dynamic values, you might need to bypass Tailwind classes entirely:
+
+```ruby
+private
+
+def build_layout_classes(user)
+  base = %w[flex]
+  base << if @collapse_below && @reverse
+    "flex-col-reverse"
+  elsif @collapse_below
+    "flex-col"
+  else
+    "flex-row"
+  end
+  
+  # Store the breakpoint for later use in style attribute
+  @responsive_style = @collapse_below
+  
+  (base + user.to_s.split).join(" ")
+end
+
+# Then in your component's template, use a media query
+# This would require passing the actual breakpoint value (e.g., "768px")
+```
+
+## Solution 4: JIT Arbitrary Value Support
+
+If the host app uses Tailwind JIT mode, you could potentially use arbitrary values, but this still requires the host app to configure their breakpoints properly.
+
+## Recommendation
+
+I'd recommend **Solution 1** - making it the host app's responsibility to safelist the classes they need. This is the most common pattern for UI component libraries. You could make it easier by:
+
+1. Providing clear documentation
+2. Offering a generator that creates a partial Tailwind config
+3. Providing common patterns they can use
+
+Example generator:
+```ruby
+# lib/generators/cubit_components/tailwind_generator.rb
+module CubitComponents
+  class TailwindGenerator < Rails::Generators::Base
+    def create_safelist_config
+      create_file "config/cubit_components_tailwind.js", <<~JS
+        // Add this to your tailwind.config.js safelist array
+        module.exports = {
+          // Safelist pattern for all breakpoint:flex-row combinations
+          pattern: /^[a-z0-9]+:flex-row$/,
+          
+          // Or if you prefer explicit listing:
+          // 'your-custom-breakpoint:flex-row',
+        }
+      JS
+    end
+  end
+end
+```
+
+This way, you're being transparent about the requirement while giving host apps full control over their Tailwind configuration.

data/lib/cubit_components/tiles_component.rb

@@ -0,0 +1,43 @@
+module CubitComponents
+  class TilesComponent < BaseComponent
+    # Allowed vattrs for grid columns and gap utilities.
+    VALID_VATTRS = Set.new(
+      begin
+        valid = []
+        breakpoints = ["", "sm:", "md:", "lg:", "xl:"]
+        cols = %w[none 1 2 3 4 5]
+        breakpoints.each do |bp|
+          cols.each { |col| valid << "#{bp}grid-cols-#{col}" }
+        end
+        gap_values = %w[0 1 2 3 4 5]
+        gap_values.each { |g| valid << "gap-#{g}" }
+        valid
+      end
+    ).freeze
+
+    DEFAULT_VATTRS = %w[grid-cols-1 gap-0].freeze
+
+    def initialize(element: "div", classes: "", vattrs: [])
+      # Merge defaults (grid cols and gap) with any provided overrides.
+      vattrs = merge_default_vattrs(Array(vattrs))
+      # Ensure grid display is always present.
+      classes = [classes, "grid"].join(" ").strip
+      super
+    end
+
+    private
+
+    def merge_default_vattrs(custom)
+      result = DEFAULT_VATTRS.dup
+      custom.each do |attr|
+        if attr.start_with?("grid-cols-")
+          result.reject! { |v| v.start_with?("grid-cols-") }
+        elsif attr.start_with?("gap-")
+          result.reject! { |v| v.start_with?("gap-") }
+        end
+        result << attr
+      end
+      result
+    end
+  end
+end

data/lib/cubit_components/vattr_validator.rb

@@ -0,0 +1,53 @@
+module CubitComponents
+  module VattrValidator
+    extend ActiveSupport::Concern
+
+    class InvalidVattrError < ArgumentError; end
+
+    private
+
+    def validate_vattrs(vattrs, allowed_vattrs, component_name: self.class.name)
+      return if Rails.env.production?
+
+      invalid_vattrs = Array(vattrs) - Array(allowed_vattrs)
+      return if invalid_vattrs.empty?
+
+      case CubitComponents.configuration.invalid_vattr_behavior
+      when :raise
+        handle_invalid_vattrs_with_exception(invalid_vattrs, allowed_vattrs, component_name)
+      when :warn
+        handle_invalid_vattrs_with_warning(invalid_vattrs, allowed_vattrs, component_name)
+      when :silent
+        # Do nothing
+      end
+    end
+
+    def handle_invalid_vattrs_with_exception(invalid_vattrs, allowed_vattrs, component_name)
+      message = build_error_message(invalid_vattrs, allowed_vattrs, component_name)
+      raise InvalidVattrError, message
+    end
+
+    def handle_invalid_vattrs_with_warning(invalid_vattrs, allowed_vattrs, component_name)
+      message = build_error_message(invalid_vattrs, allowed_vattrs, component_name)
+
+      # Use uplevel to show the warning at the call site
+      Kernel.warn("\n#{message}", uplevel: 3)
+
+      # Also log with color if Rails logger is available
+      if defined?(Rails.logger) && Rails.logger
+        Rails.logger.warn("\e[33m#{message}\e[0m")
+      end
+    end
+
+    def build_error_message(invalid_vattrs, allowed_vattrs, component_name)
+      <<~MESSAGE
+        ⚠️  [CubitComponents] Invalid vattrs for #{component_name}:
+           Invalid: #{invalid_vattrs.join(", ")}
+
+           Allowed vattrs: #{allowed_vattrs.join(", ")}
+
+           These vattrs will have no effect on the component.
+      MESSAGE
+    end
+  end
+end

data/lib/cubit_components/version.rb

@@ -0,0 +1,3 @@
+module CubitComponents
+  VERSION = "0.1.0"
+end

data/lib/cubit_components.rb

@@ -0,0 +1,34 @@
+require "cubit_components/version"
+require "cubit_components/engine"
+
+# components
+require_relative "cubit_components/base_component"
+require_relative "cubit_components/box_component"
+require_relative "cubit_components/stack_component"
+require_relative "cubit_components/inline_component"
+require_relative "cubit_components/columns_component"
+require_relative "cubit_components/spread_component"
+require_relative "cubit_components/tiles_component"
+require_relative "cubit_components/content_block_component"
+require_relative "cubit_components/page_block_component"
+require_relative "cubit_components/page_component"
+require_relative "cubit_components/bleed_component"
+require_relative "cubit_components/configuration"
+
+module CubitComponents
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/lib/generators/cubit/install/install_generator.rb

@@ -0,0 +1,63 @@
+require "rails/generators" if defined?(Rails::Generators)
+
+module Cubit
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("../templates", __FILE__)
+
+    def install
+      say "Installing Cubit Components...", :green
+
+      add_tailwind_import
+      verify_installation
+    end
+
+    private
+
+    def add_tailwind_import
+      target_file = "app/assets/tailwind/application.css"
+
+      if !File.exist?(target_file)
+        say "Could not find Tailwind CSS file to import into. Please manually add:", :red
+        say '@import "../builds/tailwind/cubit_components.css";', :yellow
+        say <<~TW_VERSION_WARNING, :red
+          ⚠️  Warning: Tailwind CSS file not found at #{target_file}.
+          Please ensure you have Tailwind CSS version 4.0 or higher installed and configured correctly and that you are using a CSS config file rather than `tailwind.config.js`.
+        TW_VERSION_WARNING
+        return
+      end
+
+      content = File.read(target_file)
+      import_line = '@import "../builds/tailwind/cubit_components.css";'
+
+      if content.include?(import_line)
+        say "CubitComponents is already imported in #{target_file}", :yellow
+        return
+      end
+
+      if content.include?('@import "tailwindcss";')
+        inject_into_file target_file, after: '@import "tailwindcss";' do
+          "\n#{import_line}"
+        end
+      else
+        append_to_file target_file do
+          "\n#{import_line}"
+        end
+      end
+
+      say "Added CubitComponents import to #{target_file}", :green
+    end
+
+    def verify_installation
+      say "\nVerifying installation...", :blue
+
+      # Check if any Tailwind file contains our import
+      tailwind_files = Dir.glob("app/assets/{stylesheets,tailwind}/*.css")
+      unless tailwind_files.any? { |f| File.read(f).include?("cubit_components") }
+        say "⚠️  Warning: Cubit Components import not found in any CSS files", :red
+        say "Please manually add @import \"../builds/tailwind/cubit_components.css\"; to your main CSS file", :yellow
+      end
+
+      say "✅ Verification complete", :green
+    end
+  end
+end

data/lib/tasks/cubit_components_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :cubit_components do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,208 @@
+--- !ruby/object:Gem::Specification
+name: cubit_components
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fabio Papa
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: propshaft
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: tailwindcss-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.38'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.38'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: standardrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: standard-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: CubitComponents provides a set of layout-focused ViewComponents with
+  built-in Tailwind CSS support and utility class validation.
+email:
+- me@fabiopapa.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/cubit_components/application.css
+- app/assets/tailwind/cubit_components/engine.css
+- config/routes.rb
+- lib/cubit_components.rb
+- lib/cubit_components/base_component.rb
+- lib/cubit_components/bleed_component.rb
+- lib/cubit_components/box_component.rb
+- lib/cubit_components/columns_component.rb
+- lib/cubit_components/configuration.rb
+- lib/cubit_components/content_block_component.rb
+- lib/cubit_components/engine.rb
+- lib/cubit_components/inline_component.rb
+- lib/cubit_components/page_block_component.rb
+- lib/cubit_components/page_component.rb
+- lib/cubit_components/previews/bleed_component_preview.rb
+- lib/cubit_components/previews/box_component_preview.rb
+- lib/cubit_components/previews/columns_component_preview.rb
+- lib/cubit_components/previews/components_index.rb
+- lib/cubit_components/previews/content_block_component_preview.rb
+- lib/cubit_components/previews/inline_component_preview.rb
+- lib/cubit_components/previews/page_block_component_preview.rb
+- lib/cubit_components/previews/page_component_preview.rb
+- lib/cubit_components/previews/preview_helper.rb
+- lib/cubit_components/previews/spread_component_preview.rb
+- lib/cubit_components/previews/stack_component_preview.rb
+- lib/cubit_components/previews/tiles_component_preview.rb
+- lib/cubit_components/spread_component.rb
+- lib/cubit_components/stack_component.rb
+- lib/cubit_components/tailwind_generated_classes_chat.txt
+- lib/cubit_components/tiles_component.rb
+- lib/cubit_components/vattr_validator.rb
+- lib/cubit_components/version.rb
+- lib/generators/cubit/install/install_generator.rb
+- lib/tasks/cubit_components_tasks.rake
+homepage: https://github.com/fapapa/cubit_components
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/fapapa/cubit_components
+  source_code_uri: https://github.com/fapapa/cubit_components
+  changelog_uri: https://github.com/fapapa/cubit_components/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: A collection of reusable ViewComponents with standardized styling and utility
+  class validation.
+test_files: []