well 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fd9e1f1862a13a600b295889724ceb507a001f11
+  data.tar.gz: a8c333ed750fa9727b14491bd08ef7e1b58a46b2
+SHA512:
+  metadata.gz: cb56363ef5d2a413e1d1d61759cd8342ca88370121249d2ffea167d3fa6a8d957c47b5115721f0bc18c0b780c12ab651a47afb68ebe52ad1fdc33a4cbf4fe19b
+  data.tar.gz: 15b484ef2abb05443c7a422e9f847938b6cbef5d8e9238a1503c4bc64331347502b55ec33497a91b841698c3023bea27a352fab3fe16c11a4d26f82e4c7eec6c

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Joe Corcoran
+
+MIT License
+
+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,47 @@
+# Well
+
+BEM stuff for ActionView.
+
+[![Build](https://travis-ci.org/tape-tv/well.svg?branch=master)](https://travis-ci.org/tape-tv/well)
+[![Docs](https://inch-ci.org/github/tape-tv/well.svg?branch=master)](https://inch-ci.org/github/tape-tv/well)
+[![Gem](https://badge.fury.io/rb/well.svg)](https://rubygems.org/gems/well)
+
+## Usage
+
+Use the DSL in your views. The following view...
+
+```erb
+<%= block :div, 'container' do %>
+  Text
+  <%= element :p, 'foreword' do %>
+    More text
+  <% end %>
+<% end %>
+```
+
+...produces this HTML.
+
+```html
+<div class="container">
+  Text
+  <p class="container__foreword">
+    More text 
+  </p>
+</div>
+```
+
+For more examples, including working with modifiers, see
+[the docs](http://www.rubydoc.info/github/tape-tv/well/master).
+
+## License
+
+MIT.
+
+## Contribution
+
+Contributions welcome! Create a pull request and we'll get back to you as soon as
+possible. Open an issue to discuss anything big.
+
+This project has a code of conduct, found in the root of this repo. Please read it
+before contributing.
+

data/lib/well.rb

@@ -0,0 +1,12 @@
+# @author Joe Corcoran <joe@corcoran.io>
+# Namespace module.
+module Well
+end
+
+require 'well/block'
+require 'well/config'
+require 'well/dsl'
+require 'well/element'
+require 'well/version'
+
+ActionView::Base.send(:include, Well::DSL)

data/lib/well/block.rb

@@ -0,0 +1,30 @@
+require 'well/component'
+require 'well/config'
+
+module Well
+  # Class representing a BEM block component.
+  class Block
+    include Component
+
+    # @param [Symbol] tag_name The name of the HTML element to build
+    # @param [String] identifier The main CSS class which represents
+    #   the role of the BEM block
+    # @param [Hash] opts
+    def initialize(tag_name, identifier, opts = {})
+      @tag_name, @identifier, @opts = tag_name, identifier, opts
+    end
+
+    # Since the block is the base element in BEM, this can only return
+    #   self.
+    # @return [Block]
+    def base
+      self
+    end
+
+    # Builds CSS class representing BEM block component.
+    # @return [String]
+    def compiled_identifier
+      identifier
+    end
+  end
+end

data/lib/well/component.rb

@@ -0,0 +1,68 @@
+require 'action_view'
+
+module Well
+  # @abstract
+  #
+  # Included by both {Block} and {Element}, this is the module
+  # which contains the shared fuctionality of all BEM components.
+  module Component
+    include ActionView::Helpers
+
+    attr_reader :identifier
+
+    # Must be defined since many methods from ActionView::Helpers.
+    # expect to be able to write to an ActionView::OutputBuffer.
+    # @return [ActionView::OutputBuffer]
+    def output_buffer
+      @output_buffer ||= ActionView::OutputBuffer.new
+    end
+
+    # Extracts BEM modifier from options.
+    # @return [String]
+    def modifier
+      @modifier ||= @opts[:modifier]
+    end
+
+    # Extracts other non-BEM CSS classes from options.
+    # @return [Array<String>]
+    def other_classes
+      @other_classes ||= @opts.fetch(:class) { [] }
+    end
+
+    # Combines all CSS classes for output.
+    # @return [Array<String>]
+    def output_classes
+      @output_classes ||= (
+        (other_classes << compiled_identifier << modified_identifier).compact
+      )
+    end
+
+    # Used by the DSL to build nested BEM components.
+    # @yield Content block is evaluated in the context of self.
+    # @return [String]
+    def evaluate(&content)
+      result = instance_eval(&content) if block_given?
+      content_tag(@tag_name, result, class: output_classes)
+    end
+
+    # Must be implemented by composing classes.
+    # @abstract
+    def compiled_identifier
+      raise NotImplementedError
+    end
+
+    # Adds BEM modifier if provided.
+    # @return [String]
+    def modified_identifier
+      return unless modifier
+      "#{compiled_identifier}#{Well.config.modifier_separator}#{modifier}"
+    end
+
+    # DSL method used to add a nested element in the context of self.
+    # Both block and element components may contain further nested elements.
+    # @return [Element]
+    def element(*args, &content)
+      Element.new(base, *args).evaluate(&content)
+    end
+  end
+end

data/lib/well/config.rb

@@ -0,0 +1,23 @@
+require 'singleton'
+
+module Well
+  # Singleton class which holds configuration.
+  class Config
+    include Singleton
+
+    attr_accessor :element_separator, :modifier_separator
+
+    # Initalizes default values for component separators
+    # based on recommendations from the BEM spec.
+    def initialize
+      @element_separator  = '__'
+      @modifier_separator = '--'
+    end
+  end
+
+  # Allows access to the {Config} singleton object.
+  # @return [Config]
+  def self.config
+    Config.instance
+  end
+end

data/lib/well/dsl.rb

@@ -0,0 +1,11 @@
+module Well
+  # The module used as the entry point to the Well DSL.
+  # This is included in ActionView::Base.
+  module DSL
+    # Creates a new {Block}, passing all arguments through.
+    # @yield The content block is evaluated in the context of the new Block
+    def block(*args, &content)
+      Block.new(*args).evaluate(&content)
+    end
+  end
+end

data/lib/well/element.rb

@@ -0,0 +1,33 @@
+require 'well/component'
+require 'well/config'
+
+module Well
+  # Class representing BEM element component.
+  class Element
+    include Component
+
+    # @param [Block,Element] base The base element used as evaluation context
+    # @param [Symbol] tag_name The name of the HTML element to build
+    # @param [String] identifier The main CSS class which represents
+    #   the role of the BEM block
+    # @param [Hash] opts
+    def initialize(base, tag_name, identifier, opts = {})
+      @base, @tag_name, @identifier, @opts = base, tag_name, identifier, opts
+    end
+
+    # The base evaludation context for a BEM element can be either a {Block}
+    # or an {Element}.
+    # @return [Block,Element]
+    def base
+      @base
+    end
+
+    # Builds CSS class representing BEM element component.
+    # @return [String]
+    def compiled_identifier
+      ids = [base.identifier]
+      ids << Well.config.element_separator << identifier
+      ids.join
+    end
+  end
+end

data/lib/well/version.rb

@@ -0,0 +1,3 @@
+module Well
+  VERSION = '0.1.0'
+end

data/spec/lib/well_spec.rb

@@ -0,0 +1,81 @@
+require 'spec_helper'
+require 'well'
+
+describe Well do
+  include Well::DSL
+
+  specify 'block contains element' do
+    output = block(:div, 'container') do
+      element(:p, 'intro') { 'Hello' }
+    end
+
+    expect(output).to match_html(
+      %Q{
+        <div class="container">
+          <p class="container__intro">Hello</p>
+        </div>
+      }
+    )
+  end
+
+  specify 'block has modifier' do
+    output = block(:section, 'sidebar', modifier: 'left')
+
+    expect(output).to match_html(
+      %Q{<section class="sidebar sidebar--left"></section>}
+    )
+  end
+
+  specify 'element has modifier' do
+    output = block(:div, 'popup') do
+      element(:button, 'sign-up', modifier: 'green') { 'Sign up' }
+    end
+
+    expect(output).to match_html(
+      %Q{
+        <div class="popup">
+          <button class="popup__sign-up popup__sign-up--green">Sign up</button>
+        </div>
+      }
+    )
+  end
+
+  specify 'nested elements' do
+    output = block(:article, 'blog-post', modifier: 'old') do
+      element(:header, 'splash') do
+        element(:h1, 'splash-title') do
+          concat('My blog post')
+          concat(element(:span, 'splash-icon'))
+        end
+      end
+    end
+
+    expect(output).to match_html(
+      %Q{
+        <article class="blog-post blog-post--old">
+          <header class="blog-post__splash">
+            <h1 class="blog-post__splash-title">
+              My blog post
+              <span class="blog-post__splash-icon"></span>
+            </h1>
+          </header>
+        </article>
+      }
+    )
+  end
+
+  specify 'merged classes' do
+    output = block(:div, 'wrapper', class: ['foo', 'bar'])
+
+    expect(output).to match_html(
+      %Q{<div class="foo bar wrapper"></div>}
+    )
+  end
+
+  specify 'DSL is available inside views' do
+    view = ActionView::Base.new
+    output = view.render(inline: %Q{<%= block(:div, 'container') { 'Text' } %>})
+
+    expect(output).to eq(block(:div, 'container') { 'Text' })
+  end
+end

data/spec/matchers/match_html.rb

@@ -0,0 +1,9 @@
+require 'oga'
+
+RSpec::Matchers.define :match_html do |expected|
+  match do |actual|
+    inspect_actual = Oga.parse_html(actual.strip).inspect
+    inspect_expected = Oga.parse_html(expected.gsub(/\n\s{2,}/, '').strip).inspect
+    inspect_actual == inspect_expected
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'matchers/match_html'
+
+RSpec.configure do |config|
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: well
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Joe Corcoran
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: oga
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Helpers for working with BEM CSS classes when building Rails views.
+email:
+- opensource@tape.tv
+- joe@corcoran.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/well.rb
+- lib/well/block.rb
+- lib/well/component.rb
+- lib/well/config.rb
+- lib/well/dsl.rb
+- lib/well/element.rb
+- lib/well/version.rb
+- spec/lib/well_spec.rb
+- spec/matchers/match_html.rb
+- spec/spec_helper.rb
+homepage: https://github.com/tape-tv/well
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+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: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: BEM stuff for ActionView
+test_files:
+- spec/lib/well_spec.rb
+- spec/matchers/match_html.rb
+- spec/spec_helper.rb
+has_rdoc: