bootstrap4_rails_components 0.1.0

data/lib/bootstrap4_rails_components/bootstrap/utilities/dropdown_directionable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Allows components to supply the dropDIRECTION for menus
+      # This is applicable to more than just the Dropdown component
+      module DropdownDirectionable
+        def dropleft
+          options.fetch(:dropleft, false)
+        end
+
+        def dropright
+          options.fetch(:dropright, false)
+        end
+
+        def dropup
+          options.fetch(:dropup, false)
+        end
+
+        private
+
+        def css_classes
+          [
+            super,
+            ('dropleft' if dropleft),
+            ('dropright' if dropright),
+            ('dropup' if dropup)
+          ].join(' ').squish
+        end
+
+        def non_html_attribute_options
+          super.push(:dropleft,
+                     :dropright,
+                     :dropup)
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_rails_components/bootstrap/utilities/headable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Delivers the dismissibility of the component to the HAML partial
+      module Headable
+        def heading
+          options.fetch(:heading, nil)
+        end
+
+        private
+
+        def non_html_attribute_options
+          super.push(:heading)
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_rails_components/bootstrap/utilities/modalable.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Allows a component to utilize the :modal option
+      # Which then formats the component's HTML data attributes
+      # to connect to the desired modal. Note the :modal option requires the '#'
+      # preceding the CSS ID per bootstrap docs
+      #
+      # Correct:   { modal: '#the_modal_id' } <-- note the '#'
+      # Incorrect: { modal: 'the_modal_id' }
+      #
+      # USAGE:
+      # When to use the :modal option on a component:
+      # The :modal option should only be used when activating a modal
+      # that has been embedded on the HTML page and is not being injected
+      # from a remote ajax request via remote: true.
+      #
+      # INVALID USAGE:
+      # Do not set a modal option on a remote link in Rails
+      # Setting a component to remote: true in addition to suppling a modal
+      # will result in an ArgumentError. This is due to poor / buggy behavior resulting from
+      # remotely re-rendering a modal that is already on the page
+      #
+      # (basically: there's a high likelihood that the targeted modal will
+      # be shown / animated twice)
+      #
+      # Like when remote: true, components that contain tooltips
+      # Will also raise an ArgumentError due to the competing data-toggles
+      # and the subsequent silent failure of the tooltip.
+      #
+      # EXCEPTIONS:
+      # Exception for a modalable component with a tooltip:
+      # *Disabled* components may use a modal and a tooltip in its options
+      # (thanks to how disabled components are wrapped with an html element & the tooltip
+      # is applied to the wrapping element, not the component itself)
+      #
+      # Valid example:
+      # = ui.bootstrap :button, disabled: true, tooltip: 'The tooltip', modal: '#the_modal', ...
+      #
+      # Extra care is taken with the modal and competing options given its typical wide-ranging
+      # use in rails applications.
+      module Modalable
+        def data
+          # Raise an error when a component utilizes 'illegal' options (which are options that
+          # result in silent failures and/or directly compete with a
+          # modalable component's necessary HTML)
+          if component_includes_problematic_options_for_modal?
+            raise ArgumentError.new(I18n.t("bootstrap4_rails_components.errors.argument_error.modalable.#{error_message_i18n_path}",
+                                     modal: modal,
+                                     class_name: self.class.name,
+                                     options: options,
+                                     file: __FILE__,
+                                     method: __method__))
+          end
+
+          # Overwrites data-toggle and data-target
+          # forcing the modal to take precedence.
+          # If a tooltip is present in the options, an ArgumentError is raised
+          modal ? super.merge!(toggle: 'modal', target: options[:modal]) : super
+        end
+
+        def modal
+          options.fetch(:modal, nil)
+        end
+
+        private
+
+        # Corresponds to i18n locale: config/locales/en.yml
+        # Remote is checked first, given its importance and impact on the application
+        # Then, check for tooltip.
+        def error_message_i18n_path
+          return 'remote' if options[:remote]
+          return 'tooltip' if options[:tooltip]
+        end
+
+        # Force an error when:
+        # 1. The component includes remote: true (and the modal option is present)
+        # 2. The component includes a :tooltip in the options
+        #
+        # When a tooltip is present, the data-toggle would be overwritten with
+        # the modal data attributes (given the `data.merge!`) causing a silent failure
+        # of the tooltip (it doesn't get added to the component)
+        #
+        # Exception: when tooltip is not "illegal" (the component has a tooltip *and* is disabled)
+        def component_includes_problematic_options_for_modal?
+          modal.present? && (options.fetch(:remote, nil) || illegal_tooltip?)
+        end
+
+        # When a modalable component is disabled
+        # the tooltip is applied to a wrapping element
+        # and will not compete with the modal's data attributes.
+        def illegal_tooltip?
+          options[:tooltip].present? && !options[:disabled]
+        end
+
+        def non_html_attribute_options
+          super.push(:modal)
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_rails_components/bootstrap/utilities/progressable.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Shared methods between Progress & ProgressBar.
+      module Progressable
+        def animated
+          options.fetch(:animated, false)
+        end
+
+        def label
+          # options.fetch(:label, nil)
+          options[:label] == true ? "#{progress}%" : options[:label] || body
+        end
+
+        def progress
+          options[:progress] || 0
+        end
+
+        def striped
+          options.fetch(:striped, false)
+        end
+
+        def theme
+          options.fetch(:theme, nil)
+        end
+
+        private
+
+        def non_html_attribute_options
+          super.push(:animated,
+                     :height,
+                     :label,
+                     :progress,
+                     :striped,
+                     :theme)
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_rails_components/bootstrap/utilities/remotable.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Turns remote: true functionality on for components that need it.
+      module Remotable
+        def data
+          remote ? super.merge!(remote: remote.to_s) : super
+        end
+
+        def remote
+          options.fetch(:remote, nil)
+        end
+
+        private
+
+        def non_html_attribute_options
+          super.push(:remote)
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_rails_components/bootstrap/utilities/sizable.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Applies ability to modify the component's size
+      # Pass in :lg or :sm
+      module Sizable
+        def size
+          options.fetch(:size, nil)
+        end
+
+        private
+
+        def css_classes
+          [
+            super,
+            (size_css_class if resized?)
+          ].join(' ').squish
+        end
+
+        def non_html_attribute_options
+          super.push(:size)
+        end
+
+        def resized?
+          size == :sm || size == :lg
+        end
+
+        def size_css_class
+          "#{size_css_class_prefix}-#{size}"
+        end
+
+        def size_css_class_prefix
+          @size_css_class_prefix ||= component_css_class
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_rails_components/bootstrap/utilities/themeable.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Allows component to utilize the bootstrap4 theme color palette
+      module Themeable
+        def outlined
+          options.fetch(:outlined, false)
+        end
+
+        # To disable theme on a case by case basis, pass in { theme: nil } to options.
+        # or
+        # To disable a default theme for a component set default_theme to nil
+        def theme
+          options.fetch(:theme, default_theme)
+        end
+
+        private
+
+        def css_classes
+          [
+            super,
+            ("#{theme_css_class_prefix}#{outlined_css_class_prefix if outlined && outlineable?}#{theme}" if theme)
+          ].join(' ').squish
+        end
+
+        def default_theme
+          @default_theme ||= Bootstrap4RailsComponents::DEFAULT_BOOTSTRAP_THEME
+        end
+
+        def non_html_attribute_options
+          super.push(:theme, :outlined)
+        end
+
+        def outlined_css_class_prefix
+          @outlined_css_class_prefix ||= 'outline-'
+        end
+
+        def theme_css_class_prefix
+          @theme_css_class_prefix ||= "#{component_css_class}-"
+        end
+
+        # Explicitly turn off outlineable on components that should not allow outline
+        def outlineable?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_rails_components/bootstrap/utilities/titleable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Allows NFG design system components to utilize the :title option
+      module Titleable
+        def title
+          options.fetch(:title, nil)
+        end
+
+        private
+
+        def non_html_attribute_options
+          super.push(:title)
+        end
+      end
+    end
+  end
+end

data/lib/bootstrap4_rails_components/bootstrap/utilities/tooltipable.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Bootstrap4RailsComponents
+  module Bootstrap
+    module Utilities
+      # Tooltip doc coming soon
+      #
+      # Bootstrap documentation
+      # https://getbootstrap.com/docs/4.1/components/tooltips/
+      #
+      # Allows tooltips to be placed on any component's main wrapping element
+      #
+      # When tooltip is applied to a disabled component (via the tooltip argument)
+      # the component will return the necessary information to build a wrapper div
+      # due to the non-interactable nature of the disabled elements.
+      #
+      # Example implementation of a button in HAML:
+      #
+      # - if button.disabled_tooltipable?
+      #   %span{ button.disabled_component_tooltip_wrapper_html_options }
+      #     = content_tag button.html_wrapper_element, button.html_options do
+      #       = button.body
+
+      # - else
+      #   = content_tag button.html_wrapper_element, button.html_options do
+      #     = button.body
+      #
+      # Tooltip placement:
+      # You can override the placement if needed by setting the tooltip_placement method
+      # in your target class -- :top, :bottom, :left, :right
+      #
+      # Example:
+      #
+      # def tooltip_placement
+      #   :right
+      # end
+      module Tooltipable
+        # TODO: This include should be removed and then anything with Tooltipable
+        # needs to be evaluated that this doesn't break it.
+        # It is undesirable that every Tooltipable component also received
+        # the disableable functionality as well.
+        include Bootstrap::Utilities::Disableable
+
+        def tooltip
+          options.fetch(:tooltip, nil)
+        end
+
+        # There are a number of complex changes that need to be made to the html
+        # for disabled tooltipped buttons
+        # Read more:
+        #
+        # https://getbootstrap.com/docs/4.1/components/tooltips/#disabled-elements
+        def html_options
+          return super if options[:tooltip].nil?
+
+          component_title = disabled ? options.fetch(:title, nil) : tooltip
+          component_styles = (options[:style] || '') + (disabled ? ' pointer-events: none;' : '') if disabled
+          super.merge!(title: component_title,
+                       style: component_styles.try(:squish))
+        end
+
+        def data
+          if tooltip
+            disabled ? super : super.merge!(tooltip_data_attributes)
+          else
+            super
+          end
+        end
+
+        def disabled_component_tooltip_wrapper_html_options
+          { data: tooltip_data_attributes,
+            title: tooltip,
+            class: 'd-inline-block',
+            tabindex: '0' }
+        end
+
+        private
+
+        def tooltip_data_attributes
+          { toggle: 'tooltip',
+            placement: tooltip_placement,
+            html: 'true' }
+        end
+
+        def non_html_attribute_options
+          super.push(:tooltip)
+        end
+
+        def tooltip_placement
+          @tooltip_placement ||= :top
+        end
+      end
+    end
+  end
+end