booties 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a66be60fe90b8f933b1069cd95547a3cf65c2aee
-  data.tar.gz: d7aa68425b199de2861dd327db7b4df785181f37
+  metadata.gz: 26c9342f582bef04df2c91615687875cb6b1cc8e
+  data.tar.gz: ce82e3caf2e664fa0a2c3b0c70323948ad547e25
 SHA512:
-  metadata.gz: bfc5aaa93a099d58ae25b1cdfe6a595615df279e36cb7d1b1abdace7099aeb56c12d96222d1b1fd92d6b95603f7f343eb51d9dbabd824d4b8628f1c0257aef94
-  data.tar.gz: 17d92569754f99df5a0e8276a20905ff3d7069bba910a39d889bc35d1d6a882330851eee2209bd419d421e758d5e51d8534e85cb5999c4dc585f959933916ca4
+  metadata.gz: 695beda958a1627ba5bab7cf35c8305fce7990895931c6fc13ada1cf050af21043be34ab7a2f055f7ec88cefc99f7b8c75d63bdf27df59441dd01306258b7891
+  data.tar.gz: b223bdd46a3ce55f2a40b5b80e85aa46401f4e440756e24565518a1bb21220da81feb198ed95904dfa84201d7fae48b7fdbff2a63e58a2d89ea828bb983aa5d1

data/app/helpers/booties/application_helper.rb

@@ -4,7 +4,9 @@ module Booties
 
     ##
     # Renders an ol tag with the "breadcrumb" class and fills it with the
-    # content of the block. The following:
+    # content of the block.
+    #
+    # Example:
     #
     #   <% breadcrumbs do %>
     #     <li>Foo</li>
@@ -12,8 +14,6 @@ module Booties
     #   <% end %>
     #   <%= yield :breadcrumb %>
     #
-    # will produce:
-    #
     #   <ol class="breadcrumb">
     #     <li>Foo</li>
     #     <li class="active">Bar</li>

data/app/helpers/booties/badge_helper.rb

@@ -3,43 +3,28 @@ module Booties
     include Utils
 
     ##
-    # Renders a span tag with the "badge" class. The content of the tag is
-    # passed in as +content+. The following:
+    # Renders a Bootstrap badge. The text inside the badge may passed in
+    # through +content+ or with a block. Additional HTML attributes may be
+    # passed in through the +options+ hash.
     #
-    #   <%= badge 'foo' %>
-    #
-    # will produce:
+    # Examples:
     #
+    #   <%= badge 'foo' %>
     #   <span class="badge">foo</span>
     #
-    # Alternatively, you can pass the content in as a block. The following:
-    #
-    #   <%= badge do %> foo <% end %>
-    #
-    # will produce:
-    #
+    #   <%= badge do %>
+    #     foo
+    #   <% end %>
     #   <span class="badge">foo</span>
     #
-    # Any options passed in through +options+ will be passed to #content_tag to
-    # be added as attributes to the span tag. The following:
-    #
     #   <%= badge 'foo', id: 'bar' %>
-    #
-    # will produce:
-    #
     #   <span class="badge" id="bar">foo</span>
     #
-    # If the +:class+ option is passed in, the contents will be merged with the
-    # classes required by Bootstrap badges. The following:
-    #
     #   <%= badge 'foo', class: 'bar' %>
-    #
-    # will produce:
-    #
     #   <span class="badge bar">foo</span>
-    def badge(content = nil, **options, &block)
-      content ||= capture &block
-      classes = merge_classes ['badge'], options.delete(:class)
+    def badge(content = nil, class: nil, **options, &block)
+      content ||= capture(&block) if block_given?
+      classes = merge_classes ['badge'], binding.local_variable_get(:class)
       content_tag :span, content, class: classes, **options
     end
   end

data/app/helpers/booties/flag_helper.rb

@@ -3,56 +3,33 @@ module Booties
     include Utils
 
     ##
-    # Renders a span tag with the "label" class and a contextual label class
-    # derived from +context+. Defaults to "label-default". The content of the
-    # tag is passed in as +content+. The following:
+    # Renders a Bootstrap label. The label text may be passed in through
+    # +content+ or as a block. The +context+ keyword may be used to specify the
+    # label context; the default context is +:default+. Additional HTML
+    # attributes may be passed in through the +options+ hash.
     #
-    #   <%= flag 'foo' %>
-    #
-    # will produce:
+    # Examples:
     #
+    #   <%= flag 'foo' %>
     #   <span class="label label-default">foo</span>
     #
-    # Alternatively, you can pass the content in as a block. The following:
-    #
     #   <%= flag do %>
     #     foo
     #   <% end %>
-    #
-    # will produce:
-    #
     #   <span class="label label-default">foo</span>
     #
-    # You can provide a different context for the label as +context+. The
-    # following:
-    #
     #   <%= flag 'foo', context: :primary %>
-    #
-    # will produce:
-    #
     #   <span class="label label-primary">foo</span>
     #
-    # Additional options passed in through +options+ will be passed to
-    # #content_tag to be added as attributes to the span tag. The following:
-    #
     #   <%= flag 'foo', id: 'bar' %>
-    #
-    # will produce:
-    #
     #   <span class="label label-default" id="bar">foo</span>
     #
-    # If the +:class+ option is passed in the contents will be merged with the
-    # classes required by Bootstrap labels. The following:
-    #
     #   <%= flag 'foo', class: 'bar' %>
-    #
-    # will produce:
-    #
     #   <span class="label label-default bar">foo</span>
-    def flag(content = nil, context: :default, **options, &block)
-      content ||= capture &block
+    def flag(content = nil, context: :default, class: nil, **options, &block)
+      content ||= capture(&block)
       classes = merge_classes %W[label label-#{context}],
-        options.delete(:class)
+        binding.local_variable_get(:class)
       content_tag :span, content, class: classes, **options
     end
   end

data/app/helpers/booties/modal_helper.rb

@@ -8,6 +8,8 @@ module Booties
     # Booties::Modal will be yielded as a parameter to the block (similar to
     # the way a FormBuilder works in Rails).
     #
+    # Example:
+    #
     #   <%= modal 'foo' do |m| %>
     #     <%= m.header do %>
     #       Nesciunt qui iste vel a.
@@ -27,8 +29,8 @@ module Booties
     #       <% end %>
     #     <% end %>
     #   <% end %>
-    def modal(id, fade: true, with: Modal, &block)
-      with.new(self, id: id, fade: fade).render &block
+    def modal(id, fade: true, size: nil, with: Modal, **options, &block)
+      with.new(self, id: id, fade: fade, size: size).render(**options, &block)
     end
   end
 end

data/app/helpers/booties/panel_helper.rb

@@ -6,6 +6,8 @@ module Booties
     # in as a block. An instance of the Booties::Panel will be yielded as a
     # parameter to the block (similar to the way a FormBuilder works in Rails).
     #
+    # Example:
+    #
     #   <%= panel do |p| %>
     #     <%= p.heading do %>
     #       <%= p.title 'Consequatur quibusdam quia vel et sed in.' %>
@@ -21,7 +23,7 @@ module Booties
     #     <% end %>
     #   <% end %>
     def panel(with: Panel, **options, &block)
-      with.new(self, **options).render &block
+      with.new(self, **options).render(&block)
     end
   end
 end

data/app/helpers/booties/popover_helper.rb

@@ -0,0 +1,63 @@
+module Booties
+  module PopoverHelper
+    include Utils
+
+    ##
+    # Generates a popover toggle. The text of the toggle is provided by +text+
+    # or else it is captured from +block+.
+    #
+    # The required parameter +content+ provides the main body of text for the
+    # popup. An optional title can be provided with the +title+ parameter. The
+    # +placement+ parameter can be used to control the placement of the window;
+    # valid placements are :left, :right, :top, and :bottom.
+    #
+    # The default behavior of the popover is to close when the user clicks the
+    # toggle a second time. If the +trigger+ option is passed in with a truthy
+    # value, the popover will instead close when the user clicks anywhere
+    # outside the toggle.
+    #
+    # The default output tag is an anchor (<A>), but you can use the +tag+
+    # parameter to use a different tag, e.g., :button to output a <BUTTON> tag.
+    #
+    # Any remaining options are passed through to #content_tag to be included
+    # as is.
+    #
+    # A caveat: Bootstrap popovers are opt-in. You must initialize them
+    # yourself. One way to do this is to include the following Javascript
+    # snippet on the page:
+    #
+    #   $(function() {
+    #     $('[data-toggler="popover"]').popover();
+    #   }
+    #
+    # Examples:
+    #
+    #   <%= popover 'Link text', content: 'Lorem ipsum dolor sit amet.' %>
+    #   <a role="button" data-toggle="popover" data-content="Lorem ipsum dolor sit amet.">Link text</a>
+    #
+    #   <%= popover tag: :button, content: 'Lorem ipsum dolor sit amet.', title: 'Lorem ipsum', placement: :top, trigger: 'focus', class: 'btn btn-default' do %>
+    #     Link text
+    #   <% end %>
+    #   <button class="btn btn-default" type="button" data-toggle="popover" data-content="Lorem ipsum dolor sit amet." data-placement="top" data-container="body" data-trigger="focus" title="Lorem ipsum">Link text</button>
+    def popover(text = nil, tag: :a, content:, title: nil, placement: nil, trigger: nil, **html_options, &block)
+      data = { toggle: 'popover', content: content, }
+
+      if placement
+        validate_placement! placement
+        data[:placement] = placement
+      end
+
+      if trigger
+        data[:container] = 'body'
+        data[:trigger]   = 'focus'
+      end
+
+      role_or_type = tag == :button ? :type : :role
+      html_options[role_or_type] ||= 'button'
+      html_options[:data] ||= {}
+      html_options[:data].update data
+
+      content_tag tag, text, **html_options, title: title, &block
+    end
+  end
+end

data/app/helpers/booties/tooltip_helper.rb

@@ -1,10 +1,18 @@
 module Booties
   module TooltipHelper
+    include Utils
+
     ##
     # Wraps the content provided by +block+ with a Bootstrap tooltip. The text
-    # of the tooltip is passed in through the required +title+ parameter. The
-    # optional +placement+ parameter can be used to control alignment of the
-    # tooltip. Valid placements are :top, :bottom, :left, and :right.
+    # of the tooltip is passed in through the required +title+ parameter.
+    #
+    # The optional +placement+ parameter can be used to control alignment of
+    # the tooltip. Valid placements are :top, :bottom, :left, and :right.
+    #
+    # The optional +wrapper_tag+ parameter can be used to specify an
+    # alternative container tag for the tooltip. (The default is to use a span
+    # tag.)
+    #
     # Additional paramters given in +options+ are passed through to
     # #content_tag to be placed on the resulting tag.
     #
@@ -12,37 +20,35 @@ module Booties
     # yourself. One way to do this is to include the following Javascript
     # snippet on the page:
     #
-    #   $(function() { $('[data-toggle="tooltip"]').tooltip() }
+    #   $(function() {
+    #     $('[data-toggle="tooltip"]').tooltip();
+    #   }
     #
     # Examples:
     #
     #   <%= tooltip title: 'This is a tooltip' do %>
     #     This has a tooltip.
     #   <% end %>
-    #
     #   <span data-toggle="tooltip" title="This is a tooltip">This has a tooltip.</span>
     #
     #   <%= tooltip title: 'This is a tooltip', placement: :bottom %>
     #     This has a tooltip.
     #   <% end %>
-    #
     #   <span data-toggle="tooltip" data-placement="bottom" title="This is a tooltip">This has a tooltip.</span>
     #
     #   <%= tooltip title: 'This is a tooltip', class: 'tooltip' %>
     #     This has a tooltip.
     #   <% end %>
-    #
     #   <span data-toggle="tooltip" title="This is a tooltip" class="tooltip">This has a tooltip.</span>
-    def tooltip(title:, placement: nil, **options, &block)
-      unless [nil, :top, :bottom, :right, :left].include? placement
-        raise ArgumentError, "invalid placement: #{placement.inspect}," \
-          ' valid placements are: :top, :bottom, :right, :left'
-      end
+    def tooltip(title:, placement: nil, wrapper_tag: :span, **options, &block)
+      data = { toggle: 'tooltip', }
 
-      data = { toggle: 'tooltip' }
-      data[:placement] = placement if placement
+      if placement
+        validate_placement! placement
+        data[:placement] = placement
+      end
 
-      content_tag :span, data: data, title: title, **options, &block
+      content_tag wrapper_tag, data: data, title: title, **options, &block
     end
   end
 end

data/lib/booties/modal.rb

@@ -2,20 +2,23 @@ require 'forwardable'
 
 module Booties
   class Modal
+    include Utils
     extend Forwardable
 
+    DEFAULT_DISMISSAL = '×'.freeze
+    MODAL_SIZE        = { small: 'modal-sm', large: 'modal-lg' }.freeze
+
     ##
     # Instantiates a new Modal. Several helper methods like #content_tag will
     # be delegated to +view_context+. The required keyword +id+ will be used as
     # the DOM ID of the modal element. By default, the modal will exhibit
     # fading behavior, but this can be disabled by setting +fade+ to a falsey
     # value.
-    #
-    # TODO: Pass additional arguments as attributes to top-level div.
-    def initialize(view_context, id:, fade: true)
+    def initialize(view_context, id:, fade: true, size: nil)
       @view_context = view_context
       @id           = id
       @fade         = fade ? 'fade' : nil
+      @size         = MODAL_SIZE[size]
     end
 
     def_delegators :@view_context, :button_tag, :capture, :content_tag,
@@ -25,9 +28,10 @@ module Booties
     # Renders the top-level div for the modal dialog. +block+ is passed to
     # #dialog to fill in the content of the modal. +@id+ is used as the DOM ID
     # of the modal. +@fade+ is used to include or exclude fading behavior.
-    def render(&block)
-      content_tag :div, class: ['modal', @fade], id: @id do
-        dialog &block
+    def render(**options, &block)
+      classes = merge_classes ['modal', @fade], options.delete(:class)
+      content_tag :div, class: classes, id: @id, **options do
+        dialog(&block)
       end
     end
 
@@ -35,8 +39,8 @@ module Booties
     # Renders the dialog section of the modal. +block+ is passed to #content to
     # fill in the content of the dialog.
     def dialog(&block)
-      content_tag :div, class: 'modal-dialog' do
-        content &block
+      content_tag :div, class: ['modal-dialog', @size] do
+        content(&block)
       end
     end
 
@@ -51,17 +55,26 @@ module Booties
     end
 
     ##
-    # Renders the header section of a modal. +block+ is passed to #title to
-    # render the title. In addition to the title, a dismissal button will be
-    # rendered. The content of the dismissal button is localized. It will look
-    # for +booties.modal.dismiss_html+. If that translation does not exist it
-    # will look for +booties.modal.dismiss+. If that does not exist either, it
-    # will default to the HTML times entity +×+.
-    def header(&block)
-      dismissal = t :'booties.modal.dismiss_html',
-        default: [:'booties.modal.dismiss', raw('×')]
+    # Renders the header section of a modal.
+    #
+    # +block+ will be passed to #title to generate the title portion included
+    # within the header.
+    #
+    # If +close+ is truthy, a dismissal button will be rendered within the
+    # header as well. The default is +true+. The default dismissal is a
+    # +×+ symbol, but this can be customized by adding a translation for
+    # +booties.modal.dismiss_html+ or +booties.modal.dismiss+.
+
+    # TODO: rename +close+ option to +dismissible+?
+    def header(close: true, &block)
       content_tag :div, class: 'modal-header' do
-        dismiss(dismissal) << title(&block)
+        if close
+          dismissal = t :'booties.modal.dismiss_html',
+            default: [:'booties.modal.dismiss', raw(DEFAULT_DISMISSAL)]
+          dismiss(dismissal) << title(&block)
+        else
+          title(&block)
+        end
       end
     end
 
@@ -85,7 +98,7 @@ module Booties
     #
     # #title is called automatically from #header.
     def title(content = nil, &block)
-      content ||= capture &block
+      content ||= capture(&block)
       content_tag :h4, content, class: 'modal-title'
     end
 
@@ -95,7 +108,7 @@ module Booties
     # +block+. Additional HTML attributes for the button can be passed in
     # through +options+.
     def dismiss(content = nil, **options, &block)
-      content ||= capture &block
+      content ||= capture(&block)
       options[:class] ||= 'close'
       options.update data: { dismiss: 'modal' }, type: 'button'
       button_tag content, options

data/lib/booties/panel.rb

@@ -5,15 +5,32 @@ module Booties
     include Utils
     extend Forwardable
 
+    CSS_CLASSES = {
+      heading: 'panel-heading'.freeze,
+      title:   'panel-title'.freeze,
+      body:    'panel-body'.freeze,
+      footer:  'panel-footer'.freeze,
+    }
+
     ##
     # Instantiates a new Panel. Several helper methods like #content_tag will
-    # be delegated to +view_context+. The optional +context+ argument can be
-    # passed in to specify the panel context. +context+ defaults to +:default+.
+    # be delegated to +view_context+.
+    #
+    # The optional +context+ argument can be passed in to specify the panel
+    # context; otherwise, the context +:default+ is used.
+    #
+    # The default behavior is to use a +div+ tag for to top-level panel
+    # container, but you may specify a different tag using the +wrapper_tag+
+    # keyword. (There are no guarantees on whether or not other tags will work
+    # correctly with Bootstrap panels.
+    #
     # Any additional options will be included as attributes on the top-level
-    # panel div.
-    def initialize(view_context, context: :default, **options)
+    # panel container.
+    def initialize(view_context, context: :default, wrapper_tag: 'div', **options)
       @view_context = view_context
+      @wrapper_tag  = wrapper_tag
       @context      = context
+      # TODO: pass options to #render instead of constructor
       @options      = options
     end
 
@@ -25,43 +42,58 @@ module Booties
     # object will be passed as a parameter to +block+.
     def render(&block)
       options = @options.dup
-      classes = merge_classes %W[panel panel-#@context],
-        options.delete(:class)
-      content_tag :div, class: classes, **options do
+      classes = merge_classes %W[panel panel-#@context], options.delete(:class)
+      content_tag @wrapper_tag, class: classes, **options do
         capture self, &block
       end
     end
 
     ##
     # Renders the panel heading. The content of the heading can be passed in
-    # through the +content+ parameter or as a block.
-    def heading(content = nil, &block)
-      content ||= capture &block
-      content_tag :div, content, class: 'panel-heading'
+    # through the +content+ parameter or as a block. If +class+ is given, it
+    # will be merged with the required panel heading class. Additional keyword
+    # arguments will be passed as an options Hash to #content_tag.
+    def heading(content = nil, class: nil, **options, &block)
+      content ||= capture(&block)
+      classes   = merge_classes CSS_CLASSES[:heading],
+        binding.local_variable_get(:class)
+      content_tag :div, content, class: classes, **options
     end
 
     ##
     # Renders the panel title. The content of the title can be passed in
-    # through the +content+ paramter or as a block.
-    def title(content = nil, &block)
-      content ||= capture &block
-      content_tag :h3, content, class: 'panel-title'
+    # through the +content+ paramter or as a block. If +class+ is given, it
+    # will be merged with the required panel title class. Additional keyword
+    # arguments will be passed as an options Hash to #content_tag.
+    def title(content = nil, class: nil, **options, &block)
+      content ||= capture(&block)
+      classes   = merge_classes CSS_CLASSES[:title],
+        binding.local_variable_get(:class)
+      content_tag :h3, content, class: classes, **options
     end
 
     ##
     # Renders the panel body. The content of the body can be passed in through
-    # the +content+ parameter or as a block.
-    def body(content = nil, &block)
-      content ||= capture &block
-      content_tag :div, content, class: 'panel-body'
+    # the +content+ parameter or as a block. If +class+ is given, it will be
+    # merged with the required panel body class. Additional keyword arguments
+    # will be passed as an options Hash to #content_tag.
+    def body(content = nil, class: nil, **options, &block)
+      content ||= capture(&block)
+      classes   = merge_classes CSS_CLASSES[:body],
+        binding.local_variable_get(:class)
+      content_tag :div, content, class: classes, **options
     end
 
     ##
     # Renders the panel footer. The content of the footer can be passed in
-    # through the +content+ parameter or as a block.
-    def footer(content = nil, &block)
-      content ||= capture &block
-      content_tag :div, content, class: 'panel-footer'
+    # through the +content+ parameter or as a block. If +class+ is given, it
+    # will be merged with the required panel footer class. Additional keyword
+    # arguments will be passed as an options Hash to #content_tag.
+    def footer(content = nil, class: nil, **options, &block)
+      content ||= capture(&block)
+      classes   = merge_classes CSS_CLASSES[:footer],
+        binding.local_variable_get(:class)
+      content_tag :div, content, class: classes, **options
     end
   end
 end