bootstrap5_helper 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1dd8831d61ec067033a1681a8b91fb1b867fd55f06d36f71aa52488d1733bbf
+  data.tar.gz: b5ebdbdedc4454e8de46cf5f871159d671e66e631c660bc58f8046d82f6c5871
+SHA512:
+  metadata.gz: 4b89389edc7232c9382e4889ddf8685b8ccf3b1057ae0e0a7a0281126c3046d51560b08f7da716a3c9d03b0eccb9b53ad531d57054e128ebce54bd16b4032a87
+  data.tar.gz: ce51660eca95ab8e0d1017eed62493cfdc4b048cd718f5728ea921e9dd9d91ef796a1550d0058c814d3759703cd33eb5f6e00b365b052cd901bd9f72fa910bc2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2022 Robert David
+
+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,506 @@
+# Bootstrap5Helper
+
+Short description and motivation.
+
+## Usage
+
+How to use my plugin.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "bootstrap5_helper"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install bootstrap5_helper
+```
+
+## Usage
+
+All of the helpers will be available inside your views. If you wish to stop that behavior and only include the helpers on the views of your choosing, pass the following to the `config` object in a intializer:
+
+<em>config/initializers/bootstrap5-helper.rb</em>
+
+```ruby
+Bootstrap5Helper.config do |config|
+  config.autoload_in_views = false
+end
+```
+
+> Note: Almost all the helpers and their child components support attributes for `id`, `class`, `data` and `aria` HTML attributes.
+
+### Accordion(s):
+
+```ruby
+# @param  [Hash] opts
+# @option opts [String]  :id
+# @option opts [String]  :class
+# @option opts [Hash]    :data
+# @option opts [Boolean] :always_open
+# @option opts [Boolean] :flush
+# @return [Accordion]
+#
+def accordion_helper(opts = {}, &block)
+  Accordion.new(self, opts, &block)
+end
+```
+
+#### Example:
+
+```erb
+<%= accordion_helper id: 'custom_id' do |a| %>
+    <%= a.item expanded: true do |item| %>
+        <%= item.header do %>
+            // html or ruby here
+        <% end %>
+        <%= item.body do %>
+            // html or ruby here
+        <% end %>
+    <% end %>
+    <%= a.item do |item| %>
+        <%= item.header do %>
+            // html or ruby here
+        <% end %>
+        <%= item.body do %>
+            // html or ruby here
+        <% end %>
+    <% end %>
+<% end %>
+```
+
+### Alerts
+
+Alerts use the context helper, where you can pass the context of the object and it will render the appropriate colors.
+
+```ruby
+# @overload alert_helper(context, opts)
+#   @param [Symbol|String] context - :primary, :danger etc
+#   @param [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#   @option opts [Boolean] :dismissible
+#
+# @overload alert_helper(opts)
+#   @param [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#   @option opts [Boolean] :dismissible
+#
+# @return [String]
+#
+def alert_helper(*args, &block)
+  Alert.new(self, *args, &block)
+end
+```
+
+#### Example:
+
+```erb
+<%= alert_helper :danger, dismissble: true do %>
+    Something went wrong with your model data...
+<% end %>
+```
+
+### Badges
+
+The badge helper will build badges realitively quickly. If you are just passing a String, use the shorter curly brace block syntax. If you plan on building other HTML elements or using other Ruby proceedures, use the do/end method.
+
+```ruby
+# @overload badge_helper(context, opts)
+#   @param [Symbol|String] context - :primary, :danger etc
+#   @param [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#   @option opts [Hash] : :data
+#
+# @overload badge_helper(opts)
+#   @param [Hash] opts
+#   @option opts [String] :id
+#   @option opts [String] :class
+#   @option opts [Hash] : :data
+#
+# @return [String]
+#
+def badge_helper(*args, &block)
+  Badge.new(self, *args, &block)
+end
+```
+
+#### Example
+
+```erb
+<li>
+   Messages: <%= badge_helper(:primary) { @messages.count } %>
+</li>
+<li>
+   Notifications: <%= badge_healper { @notifications.count } %>
+</li>
+<li>
+    Users: <%= badge_helper :danger do %> Some HTML / Ruby <% end %>
+</li>
+```
+
+### Cards
+
+Cards support a few methods that make building them easier:
+
+- `body`
+- `header`
+- `footer`
+- `image_overlay`
+- `image`
+- `image_cap`
+- `text`
+- `title`
+
+For usage on various card sub components, @see https://getbootstrap.com/docs/4.0/components/card/
+
+```ruby
+# @param  [Hash] opts
+# @option opts [String] :id
+# @option opts [String] :class
+# @option opts [Hash]   :data
+# @return [String]
+#
+def card_helper(opts = {}, &block)
+  Card.new(self, opts, &block)
+end
+```
+
+#### Example
+
+```erb
+<%= card_helper do |c| %>
+    <%= c.header class: 'text-white bg-primary' do %>
+        <h4>This is the header...</h4>
+    <% end %>
+    <%= c.body do %>
+        <%= c.title { 'This is the title' } %>
+        <%= c.text { 'This card body' } %>
+        <ul>
+            <% [1, 2, 3].each do |x|  %>
+                <li>Item: <%= x %></li>
+            <% end %>
+        </ul>
+    <% end %>
+    <%= c.footer do %>
+        This is the footer...
+    <% end %>
+<% end %>
+
+<%# Horizontal %>
+
+<div class="row">
+    <div class="col-sm mt-3 mb-3">
+        <%= card_helper do |c| %>
+            <div class="row no-gutters">
+                <div class="col-md-4">
+                    <%= image_tag 'placeholder.svg', class: 'card-img' %>
+                </div>
+                <div class="col-md-8">
+                    <%= c.body do %>
+                        <%= c.title { "Card title" } %>
+                        <%= c.text { "This is a wider card with supporting text below as a natural lead-in to additional content." } %>
+                        <%= c.text do %>
+                            <small class="text-muted">Last updated 3 mins ago</small>
+                        <% end %>
+                    <% end %>
+                </div>
+            </div>
+        <% end %>
+    </div>
+</div>
+```
+
+### Dropdowns
+
+Dropdowns support the following methods:
+
+- `button`
+- `menu`
+  - `item` - Use this method when you are using the item in the menu as a trigger for tab content.
+  - `link` - Use this method when the item in the menu is nothing more than a hyperlink.
+  - `text` - simple text
+  - `header` - Is a header item
+  - `divider` - A dividing element
+
+```ruby
+# @overload dropdown_helper(type, opts)
+#   @param [Symbol|String] type - :dropdown, :dropup, :dropstart, :dropend
+#   @param [Hash] opts
+#   @option opts [String]  :id
+#   @option opts [String]  :class
+#   @option opts [Hash]    :data
+#   @option opts [Boolean] :split
+#
+# @overload dropdown(opts)
+#   @param [Hash] opts
+#   @option opts [String]  :id
+#   @option opts [String]  :class
+#   @option opts [Hash]    :data
+#   @option opts [Boolean] :split
+#
+# @return [String]
+#
+def dropdown_helper(*args, &block)
+  Dropdown.new(self, *args, &block)
+end
+```
+
+#### Example
+
+```erb
+<%= dropdown_helper do |dropdown| %>
+    <%= dropdown.button(:primary) { "Action" } %>
+    <%= dropdown.menu do |menu| %>
+        <%= menu.link 'Edit', '#' %>
+        <%= menu.link 'Delete', '#' %>
+        <%= menu.text 'Static text' %>
+    <% end %>
+<% end %>
+
+<%= dropdown_helper :group, class: 'dropright' do |dropdown| %>
+    <button type="button" class="btn btn-danger">Action 2</button>
+    <%= dropdown.button(:danger, split: true) %>
+    <%= dropdown.menu do |menu| %>
+        <%= menu.header "Crud operations" %>
+        <%= menu.divider %>
+        <%= menu.link 'Edit', 'SOME-URL' %>
+        <%= menu.link 'Delete', 'SOME-URL' %>
+    <% end %>
+<% end %>
+
+<%= dropdown_helper do |dropdown| %>
+    <%= dropdown.button :primary do %>
+        <i class="fas fa-users"></i> User
+    <% end %>
+    <%= dropdown.menu do |menu| %>
+        <form class="px-4 py-3">
+            <div class="form-group">
+                <label for="exampleDropdownFormEmail1">Email address</label>
+                <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com">
+            </div>
+            <div class="form-group">
+                <label for="exampleDropdownFormPassword1">Password</label>
+                <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
+            </div>
+            <div class="form-group">
+                <div class="form-check">
+                    <input type="checkbox" class="form-check-input" id="dropdownCheck">
+                    <label class="form-check-label" for="dropdownCheck">
+                        Remember me
+                    </label>
+                </div>
+            </div>
+            <button type="submit" class="btn btn-primary">Sign in</button>
+        </form>
+        <%= menu.divider %>
+        <%= menu.link "New around here? Sign up", "#" %>
+        <%= menu.link "Forgot password", "#" %>
+    <% end %>
+<% end %>
+```
+
+### Modals
+
+```ruby
+# @param  [Hash] opts
+# @option opts [String]  :id
+# @option opts [String]  :class
+# @option opts [Hash]    :data
+# @option opts [Boolean] :scrollable
+# @option opts [Boolean] :vcentered
+# @option opts [Boolean] :static
+# @option opts [Boolean|Symbol] :fullscreen - true, :sm, :lg, :xl etc
+# @option opts [Symbol]  :size - :sm, :md, :lg etc
+# @return [String]
+#
+def modal_helper(opts = {}, &block)
+  Modal.new(self, opts, &block)
+end
+```
+
+> Note: When the `close_button` is not passed a block, it will default to the X icon.
+
+#### Example
+
+```erb
+<%= modal_helper id: 'exampleModal' do |m| %>
+    <%= m.header do %>
+        <%= m.title { 'Example Modal' } %>
+        <%= m.close_button %>
+    <% end %>
+    <%= m.body do %>
+        Lorem ipsum dolor sit amet consectetur adipisicing elit. Vel nisi tempora, eius iste sit nobis
+        earum in harum optio dolore explicabo. Eveniet reprehenderit harum itaque ad fuga beatae, quasi
+        sequi! Laborum ea porro nihil ipsam repudiandae vel harum voluptates minima corrupti unde quas,
+        dolore possimus doloribus voluptatem sint fuga dolores odio dignissimos at molestias earum.
+    <% end %>
+    <%= m.footer do %>
+        <%= m.close_button class: 'btn btn-secondary' do %>
+            Close
+        <% end %>
+    <% end %>
+<% end %>
+```
+
+### Navs
+
+The Nav component has the following methods:
+
+- `dropwdown` - @see Dropdown for list of methods
+- `item`
+- `link`
+
+```ruby
+# @overload nav_helper(tag, opts)
+#   @param [Symbol|String] tag - :nav, :ul
+#   @param [Hash] opts
+#   @option opts [String]  :id
+#   @option opts [String]  :class
+#   @option opts [Hash]    :data
+#   @option opts [Hash]    :child - data attributes for child, NOT wrapper
+#
+# @overload nav_helper(opts)
+#   @param [Hash] opts
+#   @option opts [String]  :id
+#   @option opts [String]  :class
+#   @option opts [Hash]    :data
+#   @option opts [Hash]    :child - data attributes for child, NOT wrapper
+#
+# @return [String]
+#
+def nav_helper(*args, &block)
+  Nav.new(self, *args, &block)
+end
+```
+
+#### Example
+
+```erb
+<%= nav_helper do |nav| %>
+    <%= nav.link "Item 1", "https://www.google.com" %>
+    <%= nav.link "Item 2", "#" %>
+    <%= nav.link "Item 3", "#" %>
+    <%= nav.dropdown :more do |menu| %>
+        <%= menu.link 'People', '#' %>
+        <%= menu.link 'Records', '#' %>
+    <% end %>
+
+    <%= nav.dropdown "More 2" do |menu| %>
+        <%= menu.link 'People', '#' %>
+        <%= menu.link 'Records', '#' %>
+    <% end %>
+<% end %>
+```
+
+### Tabs
+
+```ruby
+ # @overload tab_helper(type, opts)
+#   @param [Symbol|String] type - :tabs, :pills
+#   @param  [Hash] opts
+#   @option opts [String]  :id
+#   @option opts [String]  :class
+#   @option opts [Hash]    :data
+#
+# @overload tab_helper(opts)
+#   @param  [Hash] opts
+#   @option opts [String]  :id
+#   @option opts [String]  :class
+#   @option opts [Hash]    :data
+#
+# @return [String]
+#
+def tab_helper(*args, &block)
+  Tab.new(self, *args, &block)
+end
+```
+
+#### Example
+
+```erb
+<%= tab_helper :pills do |tab| %>
+    <%= tab.nav do |nav| %>
+        <%= nav.item :item1 do %>
+            Item 1
+        <% end %>
+        <%= nav.item(:item2, class: 'active') { "Item 2" } %>
+        <%= nav.item(:item3) { "Item 3" } %>
+        <%= nav.item :item4 %>
+        <%= nav.dropdown 'More' do |dropdown| %>
+            <%= dropdown.item :item5 %>
+            <%= dropdown.item(:item6) { 'Item 6' } %>
+        <% end %>
+    <% end %>
+
+    <%= tab.content do |content| %>
+        <%= content.pane :item1, class: 'mt-3' do %>
+            Content 1
+        <% end %>
+
+        <%= content.pane :item2, class: 'active mt-3' do %>
+            Content 2
+        <% end %>
+
+        <%= content.pane :item3, class: 'mt-3' do %>
+            Content 3
+        <% end %>
+
+        <%= content.pane :item4, class: 'mt-3' do %>
+            Content 4
+        <% end %>
+
+        <%= content.pane :item5, class: 'mt-3' do %>
+            Content 5
+        <% end %>
+
+        <%= content.pane :item6, class: 'mt-3' do %>
+            Content 6
+        <% end %>
+    <% end %>
+<% end %>
+```
+
+### Spinners
+
+```ruby
+# @param  [Hash] args
+# @option opts [Symbol]  :type - :border, :grow
+# @option opts [String]  :id
+# @option opts [String]  :class
+# @option opts [Hash]    :data
+# @return [String]
+#
+def spinner_helper(opts = {}, &block)
+  Spinner.new(self, opts, &block)
+end
+```
+
+#### Example
+
+```erb
+<%= spinner_helper class: 'text-warning' %>
+<%= spinner_helper type: :grow, class: 'text-danger', id: 'loadingRecords' %>
+```
+
+## Contributing
+
+If you would like to contribution, by all means, do a PR and send up your suggestions.
+
+If there are components you would like to see added, open an issue and I will try to get to them, or you can do a PR and add them yourself :D
+
+## 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,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/lib/bootstrap5_helper/accordion/item.rb

@@ -0,0 +1,107 @@
+module Bootstrap5Helper
+  class Accordion
+    class Item < Component # :nodoc:
+      # Take note that if `parent_id` is <tt>NilClass</tt> it is because
+      # the <tt>Accordion::Item</tt> is meant to stay open and not close
+      # the previous one.
+      #
+      # @param [ActionView] template
+      # @param [String|NilClass] parent_id
+      # @param [Hash] opts
+      # @option opts [String]  :id
+      # @option opts [String]  :class
+      # @option opts [Hash]    :data
+      #
+      def initialize(template, parent_id = nil, opts = {}, &block)
+        super(template)
+
+        @parent      = parent_id
+        @id          = opts.fetch(:id,       uuid)
+        @class       = opts.fetch(:class,    '')
+        @data        = opts.fetch(:data,     {})
+        @expanded    = opts.fetch(:expanded, false)
+        @header_id   = uuid
+        @collapse_id = uuid
+        @content     = block || proc { '' }
+      end
+
+      # rubocop:disable Metrics/MethodLength
+
+      # Builds a header component for the accordion.
+      #
+      # @param  [Hash] opts
+      # @return [String]
+      #
+      def header(tag_or_options = nil, opts = {}, &block)
+        tag, args = parse_tag_or_options(tag_or_options, opts)
+
+        @header_id = args.fetch(:id,    @header_id)
+        klass      = args.fetch(:class, '')
+        data       = args.fetch(:data,  {})
+
+        content_tag(
+          tag || config({ accordions: :header }, :h2),
+          id:    @header_id,
+          class: "accordion-header #{klass}",
+          data:  data
+        ) do
+          content_tag(
+            :button,
+            type:  :button,
+            class: "accordion-button #{@expanded ? '' : 'collapsed'}",
+            data:  {
+              'bs-toggle' => 'collapse',
+              'bs-target' => "##{@collapse_id}"
+            },
+            aria:  {
+              expanded: @expanded,
+              controls: @collapse_id
+            },
+            &block
+          )
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # rubocop:disable Metrics/MethodLength
+
+      # Builds the body component for the accordion.
+      #
+      # @param  [Hash] opts
+      # @return [String]
+      #
+      def body(opts = {}, &block)
+        id     = opts.fetch(:id,    uuid)
+        klass  = opts.fetch(:class, '')
+        data   = opts.fetch(:data,  {})
+
+        content_tag(
+          :div,
+          id:    @collapse_id,
+          class: "accordion-collapse collapse #{@expanded ? 'show' : ''}",
+          aria:  { labelledby: @header_id },
+          data:  { 'bs-parent' => @parent.present? ? "##{@parent}" : nil }
+        ) do
+          content_tag(
+            :div,
+            id:    id,
+            class: "accordion-body #{klass}",
+            data:  data,
+            &block
+          )
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # String representation of the object.
+      #
+      # @return [String]
+      #
+      def to_s
+        content_tag :div, id: @id, class: "accordion-item #{@class}", data: @data do
+          @content.call(self)
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap5_helper/accordion.rb

@@ -0,0 +1,46 @@
+module Bootstrap5Helper
+  # Builds a Accordion component.
+  #
+  #
+  class Accordion < Component
+    # Class constructor
+    #
+    # @param [ActionView] template
+    # @param [Hash] opts
+    # @option opts [String]  :id
+    # @option opts [String]  :class
+    # @option opts [Hash]    :data
+    # @option opts [Boolean] :always_open
+    # @option opts [Boolean] :flush
+    #
+    def initialize(template, opts = {}, &block)
+      super(template)
+
+      @id          = opts.fetch(:id,          uuid)
+      @class       = opts.fetch(:class,       '')
+      @data        = opts.fetch(:data,        {})
+      @always_open = opts.fetch(:always_open, false)
+      @flush       = opts.fetch(:flush,       false)
+      @content     = block || proc { '' }
+    end
+
+    def item(*args, &block)
+      Accordion::Item.new(self, (@always_open ? nil : @id), *args, &block)
+    end
+
+    # String representation of the object.
+    #
+    # @return [String]
+    #
+    def to_s
+      content_tag(
+        :div,
+        id:    @id,
+        class: "accordion #{@flush ? 'accordion-flush' : ''} #{@class}",
+        data:  @data
+      ) do
+        @content.call(self)
+      end
+    end
+  end
+end