bootstrap5_helper 1.0.0

data/lib/bootstrap5_helper/alert.rb

@@ -0,0 +1,69 @@
+module Bootstrap5Helper
+  # The Alert helper is meant to help you rapidly build Bootstrap Alert
+  # components quickly and easily. The dissmiss button is optional.
+  #
+  class Alert < Component
+    # Class constructor
+    #
+    # @param [Class] template - Template in which your are binding too.
+    # @param [NilClass|String|Symbol|Hash] context_or_options
+    # @param [Hash]  opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Boolean] :dismissible
+    # @return [Alert]
+    #
+    def initialize(template, context_or_options = nil, opts = {}, &block)
+      super(template)
+      @context, args = parse_context_or_options(context_or_options, opts)
+
+      @id          = args.fetch(:id,          uuid)
+      @class       = args.fetch(:class,       '')
+      @dismissible = args.fetch(:dismissible, false)
+      @content     = block || proc { '' }
+    end
+
+    # The dissmiss button, if the element has one.
+    #
+    # @return [String]
+    #
+    def close_button
+      content_tag(
+        :button,
+        '',
+        class: 'btn-close',
+        data:  { 'bs-dismiss' => 'alert' },
+        aria:  { label: 'Close' }
+      )
+    end
+
+    # Used to render out the Alert component.
+    #
+    # @return [String]
+    #
+    def to_s
+      content_tag :div, id: @id, class: container_class do
+        concat(@dismissible ? close_button : '')
+        @content.call(self)
+      end
+    end
+
+    private
+
+    # Used to get the container classes.
+    #
+    # @return [String]
+    #
+    def container_class
+      "alert alert-#{@context} #{@class} #{dismissible_class}"
+    end
+
+    # Class used on parent element to signify a dismissible button.
+    #
+    # @return [String]
+    #
+    def dismissible_class
+      @dismissible ? 'alert-dismissible fade show' : ''
+    end
+  end
+end

data/lib/bootstrap5_helper/badge.rb

@@ -0,0 +1,53 @@
+module Bootstrap5Helper
+  # Creates Bootstrap badge components that can be used anywhere.
+  #
+  #
+  class Badge < Component
+    # Class constructor
+    #
+    # @param [ActionView] template
+    # @param [NilClass|String|Symbol|Hash] context_or_options
+    # @param [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash] : :data
+    #
+    def initialize(template, context_or_options = nil, opts = {}, &block)
+      super(template)
+      @context, args = parse_context_or_options(context_or_options, opts)
+
+      @id      = args.fetch(:id,    nil)
+      @class   = args.fetch(:class, '')
+      @data    = args.fetch(:data,  {})
+      @content = block || proc { '' }
+    end
+
+    # String representation of the object.
+    #
+    # @return [String]
+    #
+    def to_s
+      content_tag(
+        config(:badges, :span),
+        id:    @id,
+        class: container_class,
+        data:  @data
+      ) do
+        @content.call(self)
+      end
+    end
+
+    private
+
+    # Used to get the container classes.
+    #
+    # @return [String]
+    #
+    def container_class
+      string = 'badge '
+      string += @context == 'secondary' ? 'bg-secondary' : "bg-#{@context}"
+      string += " #{@class}"
+      string
+    end
+  end
+end

data/lib/bootstrap5_helper/callout.rb

@@ -0,0 +1,58 @@
+module Bootstrap5Helper
+  # Builds a Toast component.
+  #
+  #
+  class Callout < Component
+    # @param  [ActionView] template - Template in which your are binding too.
+    # @param  [NilClass|String|Symbol|Hash] context_or_options - Bootstrap class context, or options hash.
+    # @param  [Hash]  opts
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @return [Callout]
+    #
+    def initialize(template, context_or_options = nil, opts = {}, &block)
+      super(template)
+      @context, args = parse_context_or_options(context_or_options, opts)
+
+      @id      = args.fetch(:id,    nil)
+      @class   = args.fetch(:class, '')
+      @data    = args.fetch(:data,  {})
+      @content = block || proc { '' }
+    end
+
+    # Creates the header component for the Callout.
+    #
+    # @param  [String|Hash] text_or_options
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @return [String]
+    #
+    def header(text_or_options = nil, opts = {}, &block)
+      text = text_or_options.is_a?(String) ? text_or_options : nil
+      content_tag(config({ callouts: :header }, :h4), text, opts, &block)
+    end
+
+    # Returns a string representation of the component.
+    #
+    # @return [String]
+    #
+    def to_s
+      content_tag :div, id: @id, class: container_class, data: @data do
+        @content.call(self)
+      end
+    end
+
+    private
+
+    # Used to get the container classes.
+    #
+    # @return [String]
+    #
+    def container_class
+      "callout callout-#{@context} #{@class}"
+    end
+  end
+end

data/lib/bootstrap5_helper/card.rb

@@ -0,0 +1,204 @@
+module Bootstrap5Helper
+  # Used to build Bootstrap Card components.  Cards are wildly used through Bootstrap 4.
+  #
+  #
+  class Card < Component
+    # Used to initialize a new Card component.
+    #
+    # @param  [ActionView] template
+    # @param  [Hash]  opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @return [Card]
+    #
+    def initialize(template, opts = {}, &block)
+      super(template)
+
+      @id      = opts.fetch(:id,    '')
+      @class   = opts.fetch(:class, '')
+      @data    = opts.fetch(:data,  nil)
+      @content = block || proc { '' }
+    end
+
+    # Builds the Header component.
+    #
+    # @param  [Symbol|Hash|NilClass] tag_or_options
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @return [String]
+    #
+    def header(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
+      build_base_component(
+        tag || config({ cards: :header }, :h5),
+        :header,
+        args,
+        &block
+      )
+    end
+
+    # Builds the Body component.
+    #
+    # @param  [Symbol|Hash|NilClass] tag_or_options
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @return [String]
+    #
+    def body(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
+      build_base_component(
+        tag || config({ cards: :body }, :div),
+        :body,
+        args,
+        &block
+      )
+    end
+
+    # Builds the Footer component.
+    #
+    # @param  [Symbol|Hash|NilClass] tag_or_options
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @return [String]
+    #
+    def footer(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
+      build_base_component(
+        tag || config({ cards: :footer }, :div),
+        :footer,
+        args,
+        &block
+      )
+    end
+
+    # Builds a Title component.
+    #
+    # @param  [Symbol|Hash|NilClass] tag_or_options
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @return [String]
+    #
+    def title(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
+      build_sub_component(
+        tag || config({ cards: :title }, :h5),
+        :title,
+        args,
+        &block
+      )
+    end
+
+    # Builds a Text component.
+    #
+    # @param  [Symbol|Hash|NilClass] tag_or_options
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @return [String]
+    #
+    def text(tag_or_options = nil, opts = {}, &block)
+      tag, args = parse_tag_or_options(tag_or_options, opts)
+      build_sub_component(
+        tag || config(:card_text, :p),
+        :text,
+        args,
+        &block
+      )
+    end
+
+    # Simple image element for cards.
+    #
+    # @param  [String] src
+    # @param  [Hash] opts
+    # @option opts [String] :id
+    # @option opts [String] :class
+    # @option opts [Hash]   :data
+    # @option opts [Hash]   :aria
+    # @return [String]
+    #
+    def image(src, opts = {})
+      (opts[:class] ||= '') << 'card-img'
+      @template.image_tag(src, opts)
+    end
+
+    # Builds an Image Cap component.
+    #
+    # @param  [String] src,
+    # @param  [Symbol|String] type
+    # @param  [Hash] opts
+    # @return [String]
+    #
+    def image_cap(src, type = :top, opts = {})
+      (opts[:class] ||= '') << "card-img-#{type}"
+      @template.image_tag(src, opts)
+    end
+
+    # Builds a Img Overlay component.
+    #
+    # @param  [Hash] args
+    # @option args [String] :id
+    # @option args [String] :class
+    # @option args [Hash]   :data
+    # @return [String]
+    #
+    def image_overlay(args = {}, &block)
+      build_base_component(:div, 'img-overlay', args, &block)
+    end
+
+    # Outputs the Object in its String representation.
+    #
+    # @return [String]
+    #
+    def to_s
+      content_tag :div, id: @id, class: "card #{@class}", data: @data do
+        @content.call(self)
+      end
+    end
+
+    private
+
+    # Used to build basic DIV components.
+    #
+    # @param  [String] type
+    # @param  [Mixed] args
+    # @return [String]
+    #
+    def build_base_component(tag, type, args, &block)
+      build_sub_component(tag, type, args, &block)
+    end
+
+    # Used to build various DOM components.
+    #
+    # @param  [Symbol] tag
+    # @param  [String] type
+    # @param  [Hash]   args
+    # @option args [String] :id
+    # @option args [String] :class
+    # @option args [Hash]   :data
+    # @return [String]
+    #
+    def build_sub_component(tag, type, args, &block)
+      id    = args.fetch(:id,    '')
+      klass = args.fetch(:class, '')
+      data  = args.fetch(:data,  {})
+
+      content_tag(
+        tag,
+        id:    id,
+        class: "card-#{type} #{klass}",
+        data:  data,
+        &block
+      )
+    end
+  end
+end

data/lib/bootstrap5_helper/component.rb

@@ -0,0 +1,156 @@
+module Bootstrap5Helper
+  # This super class is meant to contain commonly used methods that
+  # all sub classes can leverage.
+  #
+  # @note Every component that inherits from this class, needs to call the parent
+  #   initialization method! In order to properly render erb blocks within the
+  #   proper context, we need the template. The only way to get this, is to pass
+  #   in the template.
+  #
+  # @note the `context` mentioned above, refers to the context of `@template` and
+  #   not to be confused with `@context` that can be found in the sub classes.
+  #   `@context` refers to the Bootstrap class context of the component.
+  #
+  class Component
+    # Used to ensure that the helpers always have the propert context for
+    # rendering and bindings.
+    #
+    # @param [Class] template
+    #
+    def initialize(template)
+      @template = template
+    end
+
+    # rubocop:disable Style/OptionalBooleanParameter
+
+    # Used to pass all context of content_tag to the template.  This ensures
+    # proper template binding of variables and methods!
+    #
+    # @param  [String]        name
+    # @param  [Hash|NilClass] content_or_options_with_block
+    # @param  [Hash|NilClass] options
+    # @param  [Boolean]       escape
+    # @return [String]
+    #
+    def content_tag(
+      name,
+      content_or_options_with_block = nil,
+      options = nil,
+      escape = true,
+      &block
+    )
+      @template.content_tag(
+        name,
+        content_or_options_with_block,
+        options,
+        escape,
+        &block
+      )
+    end
+    # rubocop:enable Style/OptionalBooleanParameter
+
+    # Used to pass all context of the capture tag to then template.  This ensures
+    # proper template binding of variables and methods!
+    #
+    # @param  [Mixed] args
+    # @return [String]
+    #
+    def capture(*args)
+      @template.capture(*args)
+    end
+
+    # Used to pass all concat references to the template.  This ensures proper
+    # binding. Concat adds a String to the template Output buffer.  Useful when
+    # trying to add a String with no block.
+    #
+    # @param  [String] text
+    # @return [String]
+    #
+    def concat(text)
+      @template.concat(text)
+    end
+
+    # Used to parse method arguments.  If the first argument is
+    # a Hash, then it is assumed that the user left off the bootstrap
+    # contectual class.  So we will assign it to `secondary` and
+    # return the Hash to be used as options.
+    #
+    # @param  [Hash|NilClass|String|Symbol] args
+    # @return [Array]
+    #
+    def parse_context_or_options(*args)
+      parse_arguments(*args, 'secondary')
+    end
+
+    # Used to parse method arguments.  If the first argument is
+    # a Hash, then it is assumed that the user left off the tag
+    # element.  So we will assign it to <tt>NilClass</tt> and
+    # return the Hash to be used as options.
+    #
+    # @param  [Hash|NilClass|String|Symbol] args
+    # @return [Array]
+    #
+    def parse_tag_or_options(*args)
+      parse_arguments(*args, nil)
+    end
+
+    # Used to parse method arguments.  If the first argument is
+    # a Hash, then it is assumed that the user left out the text
+    # string.  So we will assign it to <tt>NilClass</tt> and
+    # return the Hash to be used as options.
+    #
+    # @param  [Hash|NilClass|String|Symbol] args
+    # @return [Array]
+    #
+    def parse_text_or_options(*args)
+      parse_arguments(*args, nil)
+    end
+
+    # Used to parse method arguments.  If the first argument is
+    # a Hash, then it is assumed that the user skipped the default
+    # argument.  So we will assign it to `default` provided and
+    # return the Hash to be used as options.
+    #
+    # @param  [Hash|NilClass|String|Symbol] args
+    # @return [Array]
+    #
+    def parse_arguments(*args, default)
+      first, second = *args
+      case first
+      when Hash, NilClass
+        [default, first || second]
+      when Symbol, String
+        [first, second]
+      end
+    end
+
+    # Used to generate a (hopefully) unique ID for DOM elements.  Used as a
+    # fallback if the user doesn't specify one.
+    #
+    # @return [String]
+    #
+    def uuid
+      (0...10).map { rand(65..90).chr }.join
+    end
+
+    # Used to get config settings inside of components quicker.
+    #
+    # @param  [Symbol|String|Hash] setting
+    # @return [Mixed]
+    #
+    def config(setting, fallback)
+      object = Bootstrap5Helper.config
+
+      value  = (
+        case setting
+        when Hash
+          object.send(setting.keys[0])[setting.values[0]] if object.send(setting.keys[0])
+        when Symbol, String
+          object.send(setting) if object.respond_to?(setting)
+        end
+      )
+
+      value || fallback
+    end
+  end
+end

data/lib/bootstrap5_helper/configuration.rb

@@ -0,0 +1,65 @@
+module Bootstrap5Helper
+  # Simple configuration object for setting options for the gem.
+  #
+  # @todo Build a better, more comprehensive system.
+  #
+  class Configuration
+    DEFAULT_SETTINGS = {
+      autoload_in_views: true,
+      accordions:        {
+        header: :h2,
+        body:   :div
+      },
+      badges:            :span,
+      callouts:          {
+        header: :h4
+      },
+      cards:             {
+        header: :h5,
+        body:   :div,
+        footer: :div,
+        title:  :h5,
+        text:   :p
+      },
+      dropdowns:         {},
+      dropdown_menus:    {
+        text:    :span,
+        header:  :h6,
+        divider: :div
+      },
+      modals:            {
+        title: :h5
+      },
+      navs:              {
+        base: :ul
+      },
+      offcanvas:         {
+        header:  :div,
+        title:   :h5,
+        close:   :button,
+        body:    :div,
+        trigger: :div
+      },
+      page_header:       :h1
+    }.freeze
+
+    attr_accessor(*DEFAULT_SETTINGS.keys)
+
+    # Class constructor
+    #
+    # @param  [Hash] _args
+    # @return [ClassName]
+    #
+    def initialize(_args = {})
+      DEFAULT_SETTINGS.each { |key, value| instance_variable_set("@#{key}", value) }
+    end
+
+    # Simple predicate method
+    #
+    # @return [Boolean]
+    #
+    def autoload_in_views?
+      @autoload_in_views
+    end
+  end
+end

data/lib/bootstrap5_helper/constants.rb

@@ -0,0 +1,28 @@
+module Bootstrap5Helper
+  # Simple class for storing constants
+  #
+  #
+  class Constants
+    COMPONENTS = %i[
+      component
+      alert
+      accordion
+      accordion/item
+      badge
+      card
+      callout
+      configuration
+      dropdown
+      dropdown/menu
+      input_group
+      modal
+      nav
+      offcanvas
+      offcanvas/content
+      page_header
+      spinner
+      tab
+      tab/content
+    ].freeze
+  end
+end