css_modules 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 431374aa2a26649b2dac684cf81efe66e419c84c
+  data.tar.gz: 2dffe66a072a52b0c60074940be0774a6513e7a1
+SHA512:
+  metadata.gz: b89042953316ab3a5b1b17c7c46eb5d2882e529415f5fb7a1c5247d3628ca1cd11aa796b09c9d0318c89578fe384a896f014d124f3f5616d07047b073fcc4c5f
+  data.tar.gz: 9c6387bfb0e5b68e7f5879c2999e4cd994c1b3ddfa03449ac18b5213f276ca7bff7f6c4abe9227732f8430134f68a59d2db39673594b9128fc2f992d3656dc5e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2016 Robert Mosolgo
+
+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,124 @@
+# CSSModules
+
+An alternative to "magic string" classnames in Sass or SCSS. Currently supports Sprockets 2 only 😖.
+
+Thanks to [Fatih Kadir Akın](https://twitter.com/fkadev) for his post, ["How I Implemented CSS Modules in Ruby on Rails, Easily"](https://medium.com/@fkadev/how-i-implemented-css-modules-to-ruby-on-rails-easily-abb324ce22d), which led the way on this idea!
+
+## Usage
+
+### Add modules to stylesheets
+
+Your `.sass` or `.scss` stylesheets can define modules with `:module(module_name)`:
+
+```scss
+:module(events) {
+  .header {
+    font-style: bold;
+  }
+
+  .link:visited {
+    color: purple;
+  }
+
+  #footer {
+    font-size: 0.8em;
+  }
+}
+```
+
+Sass requires an extra `\`:
+
+```sass
+\:module(events)
+  .header
+    font-style: bold
+```
+
+### Put modulized names into HTML
+
+To access the contents of a module in a view, you must include the helpers in your controller:
+
+```ruby
+class EventsController < ApplicationController
+  helper CSSModules::ViewHelper
+end
+```
+
+(To use the view helper _everywhere_, include it in `ApplicationController`.)
+
+Then, in your view, you can access the module & its contents by name:
+
+```erb
+<!-- access by module + identifier -->
+<h1 id="<%= css_module("events", "main_header") %>">
+  Events
+</h1>
+
+<!-- block helper -->
+<% css_module("events") do |events_module| %>
+  <div id="<%= events_module.selector("footer") %>">
+    <%= link_to "Home", "/", class: events_module.selector("link") %>
+    © My company
+  </div>
+<% end %>
+```
+
+### Use modulized names in JavaScript
+
+In JavaScript, you can include a helper to access module styles:
+
+```jsx
+//= require css_module
+
+// Module + identifier
+var headerClass = CSSModule("events", "header")
+$("." + headerClass).text() // => "Events"
+
+// Or module helper function
+var eventsModule = CSSModule("events")
+
+function header() {
+  var headerClass = eventsModule("header")
+  return (
+    <h1 className={headerClass}>Events</h1>
+  )
+}
+```
+
+`CSSModule` requires the global JS function `btoa`. To include a polyfill from this gem, add:
+
+```js
+//= require base64
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'css_modules'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install css_modules
+```
+
+## TODO
+
+- Support minified identifiers for Production Env
+- Dead code warning for Development env:
+  - Warn when not all styles are used?
+  - Sprockets require CSS to JS? `require_styles` ?
+- Support plain `.css`
+- Use Sass's built-in parser?
+- Support Sprockets 3+
+
+## License
+
+[MIT](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,20 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+  t.warning = false
+end
+
+
+task default: :test

data/lib/css_modules/assets/base64.js

@@ -0,0 +1,136 @@
+// btoa polyfill, from https://jsfiddle.net/gabrieleromanato/qaght/
+var Base64 = {
+
+
+    _keyStr: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=",
+
+
+    encode: function(input) {
+        var output = "";
+        var chr1, chr2, chr3, enc1, enc2, enc3, enc4;
+        var i = 0;
+
+        input = Base64._utf8_encode(input);
+
+        while (i < input.length) {
+
+            chr1 = input.charCodeAt(i++);
+            chr2 = input.charCodeAt(i++);
+            chr3 = input.charCodeAt(i++);
+
+            enc1 = chr1 >> 2;
+            enc2 = ((chr1 & 3) << 4) | (chr2 >> 4);
+            enc3 = ((chr2 & 15) << 2) | (chr3 >> 6);
+            enc4 = chr3 & 63;
+
+            if (isNaN(chr2)) {
+                enc3 = enc4 = 64;
+            } else if (isNaN(chr3)) {
+                enc4 = 64;
+            }
+
+            output = output + this._keyStr.charAt(enc1) + this._keyStr.charAt(enc2) + this._keyStr.charAt(enc3) + this._keyStr.charAt(enc4);
+
+        }
+
+        return output;
+    },
+
+
+    decode: function(input) {
+        var output = "";
+        var chr1, chr2, chr3;
+        var enc1, enc2, enc3, enc4;
+        var i = 0;
+
+        input = input.replace(/[^A-Za-z0-9\+\/\=]/g, "");
+
+        while (i < input.length) {
+
+            enc1 = this._keyStr.indexOf(input.charAt(i++));
+            enc2 = this._keyStr.indexOf(input.charAt(i++));
+            enc3 = this._keyStr.indexOf(input.charAt(i++));
+            enc4 = this._keyStr.indexOf(input.charAt(i++));
+
+            chr1 = (enc1 << 2) | (enc2 >> 4);
+            chr2 = ((enc2 & 15) << 4) | (enc3 >> 2);
+            chr3 = ((enc3 & 3) << 6) | enc4;
+
+            output = output + String.fromCharCode(chr1);
+
+            if (enc3 != 64) {
+                output = output + String.fromCharCode(chr2);
+            }
+            if (enc4 != 64) {
+                output = output + String.fromCharCode(chr3);
+            }
+
+        }
+
+        output = Base64._utf8_decode(output);
+
+        return output;
+
+    },
+
+    _utf8_encode: function(string) {
+        string = string.replace(/\r\n/g, "\n");
+        var utftext = "";
+
+        for (var n = 0; n < string.length; n++) {
+
+            var c = string.charCodeAt(n);
+
+            if (c < 128) {
+                utftext += String.fromCharCode(c);
+            }
+            else if ((c > 127) && (c < 2048)) {
+                utftext += String.fromCharCode((c >> 6) | 192);
+                utftext += String.fromCharCode((c & 63) | 128);
+            }
+            else {
+                utftext += String.fromCharCode((c >> 12) | 224);
+                utftext += String.fromCharCode(((c >> 6) & 63) | 128);
+                utftext += String.fromCharCode((c & 63) | 128);
+            }
+
+        }
+
+        return utftext;
+    },
+
+    _utf8_decode: function(utftext) {
+        var string = "";
+        var i = 0;
+        var c = c1 = c2 = 0;
+
+        while (i < utftext.length) {
+
+            c = utftext.charCodeAt(i);
+
+            if (c < 128) {
+                string += String.fromCharCode(c);
+                i++;
+            }
+            else if ((c > 191) && (c < 224)) {
+                c2 = utftext.charCodeAt(i + 1);
+                string += String.fromCharCode(((c & 31) << 6) | (c2 & 63));
+                i += 2;
+            }
+            else {
+                c2 = utftext.charCodeAt(i + 1);
+                c3 = utftext.charCodeAt(i + 2);
+                string += String.fromCharCode(((c & 15) << 12) | ((c2 & 63) << 6) | (c3 & 63));
+                i += 3;
+            }
+
+        }
+
+        return string;
+    }
+
+}
+
+if (!btoa) {
+  var btoa = function(str) { return Base64.encode(str) }
+}

data/lib/css_modules/assets/css_module.js

@@ -0,0 +1,31 @@
+// Usage:
+//
+// - Call with a module name + selector name to get a transformed (opaque) selector
+//
+//   ```js
+//   CSSModule("events_index", "header")
+//   // => "..." (some opaque string that matches the stylesheet)
+//   ```
+//
+// - Call with a module name to get a function for modulizing selectors
+//
+//   ```js
+//   var eventsModule = CSSModule("events_index")
+//   var headerSelector = eventsModule("header")
+//   var footerSelector = eventsModule("footer")
+//   ```
+//
+// This behavior has to match `CSSModules::Rewrite` in Ruby
+// so that generated selectors match.
+function CSSModule(moduleName, selectorName) {
+  // This matches `Rewrite`:
+  var opaqueString = btoa(moduleName).replace(/[^a-zA-Z0-9]/g, "")
+  var transformedModuleName = opaqueString + "_" + moduleName;
+  if (selectorName) {
+    return transformedModuleName + "_" + selectorName;
+  } else {
+    return function(selectorName) {
+      return transformedModuleName + "_" + selectorName;
+    };
+  }
+};

data/lib/css_modules/engine.rb

@@ -0,0 +1,17 @@
+module CSSModules
+  class Engine < ::Rails::Engine
+    isolate_namespace CSSModules
+
+    initializer "css_modules.register_preprocessor" do |app|
+      # Make css_module.js accessible to Sprockets
+      app.config.assets.paths << File.expand_path("../assets", __FILE__)
+
+      # This is Sprockets 2 only :S
+      app.config.assets.configure do |env|
+        env.register_postprocessor('text/css', :css_modules) do |context, data|
+          CSSModules::Rewrite.rewrite_css(data)
+        end
+      end
+    end
+  end
+end

data/lib/css_modules/rewrite.rb

@@ -0,0 +1,75 @@
+require "css_parser"
+require "base64"
+
+module CSSModules
+  module Rewrite
+    # Module Scopes
+    # :module(login) { .button {color: red;} }
+    RE_MODULE = /^\:module\((?<module_name>.*?)\)\s+(?<declarations>.*)/
+
+    module_function
+    # Take css module code as input, and rewrite it as
+    # browser-friendly CSS code. Apply opaque transformations
+    # so that selectors can only be accessed programatically,
+    # not by class name literals.
+    def rewrite_css(css_module_code)
+      parser = CssParser::Parser.new
+      parser.load_string!(css_module_code)
+
+      rules = ""
+
+      parser.each_selector do |selector, declarations, specificity|
+        prettified_declarations = declarations.gsub(/;\s+/, ";\n  ")
+        modulized_selector = parse_selector(selector)
+        rules << "#{modulized_selector} {\n  #{prettified_declarations}\n}\n"
+      end
+
+      rules.strip!
+      rules
+    end
+
+    # Combine `module_name` and `selector`, but don't prepend a `.` or `#`
+    # because this value will be inserted into the HTML page as `class=` or `id=`
+    def modulize_selector(module_name, selector)
+      transformed_name = transform_name(module_name)
+      "#{transformed_name}_#{selector}"
+    end
+
+    private
+    module_function
+
+    # This parses the selector for `:module` definitions or does nothing.
+    def parse_selector(selector)
+      matches = RE_MODULE.match(selector)
+      if matches.nil?
+        selector
+      else
+        module_name = transform_name(matches[:module_name])
+        declaration_parts = matches[:declarations].split(" ")
+        declaration_parts
+          .map { |declaration_or_operator| rebuild_selector(module_name, declaration_or_operator) }
+          .join(" ")
+      end
+    end
+
+    # If `selector` is a class or ID, scope it to this module.
+    # If it is a bare element, leave it unscoped.
+    def rebuild_selector(module_ident, selector)
+      case selector[0]
+      when "#"
+        "##{module_ident}_#{selector[1..-1]}"
+      when "."
+        ".#{module_ident}_#{selector[1..-1]}"
+      else
+        selector
+      end
+    end
+
+    def transform_name(css_module_name)
+      # Some base64 characters aren't valid for CSS (eg, `=`)
+      opaque_string = Base64.encode64(css_module_name).gsub(/[^a-zA-Z0-9]/, "")
+      # p [css_module_name, opaque_string]
+      "#{opaque_string}_#{css_module_name}"
+    end
+  end
+end

data/lib/css_modules/version.rb

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

data/lib/css_modules/view_helper.rb

@@ -0,0 +1,56 @@
+module CSSModules
+  # Provides helpers to the view layer.
+  # Add it to a controller with Rails' `helper` method.
+  #
+  # @example including ViewHelper in ApplicationController (and therefore all its descendants)
+  #   class ApplicationController < ActionController::Base
+  #     helper CSSModules::ViewHelper
+  #   end
+  module ViewHelper
+    # @overload css_module(module_name, selector_name)
+    #   Apply the styles from `module_name` for `selector_name`
+    #
+    #   @example Getting a selector within a module
+    #      css_module("events_index", "header")
+    #      # => "..." (opaque string which matches the stylesheet)
+    #
+    #   @param module_name
+    #   @param selector_name DOM id or class name
+    #   @return [String] modulized selector name for `class=` or `id=` in a view
+    #
+    # @overload css_module(module_name, &block)
+    #   Modulize selectors within a block using the yielded helper.
+    #
+    #   @example modulizing a few selectors
+    #     <% css_module("events_index") do |events_module| %>
+    #       <h1 class="<%= events_module.selector("heading") %>">All events</h1>
+    #       <p id="<%= events_module.selector("description") %>"> ... </p>
+    #     <% end %>
+    #
+    #   @param module_name
+    #   @yieldparam [ModuleLookup] a helper for modulizing selectors within `module_name`
+    #   @return [void]
+    def css_module(module_name, selector_name = nil, &block)
+      if selector_name.nil? && block_given?
+        lookup = ModuleLookup.new(module_name)
+        yield(lookup)
+        nil
+      elsif selector_name.present?
+        CSSModules::Rewrite.modulize_selector(module_name.to_s, selector_name.to_s)
+      else
+        raise("css_module must be called with a module_name and either a selector_name or a block")
+      end
+    end
+
+    # Shorthand for getting several classnames from one module
+    class ModuleLookup
+      def initialize(module_name)
+        @module_name = module_name.to_s
+      end
+
+      def selector(selector_name)
+        CSSModules::Rewrite.modulize_selector(@module_name, selector_name.to_s)
+      end
+    end
+  end
+end

data/lib/css_modules.rb

@@ -0,0 +1,4 @@
+require "css_modules/engine"
+require "css_modules/version"
+require "css_modules/rewrite"
+require "css_modules/view_helper"

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: css_modules
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Robert Mosolgo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-10-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: css_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: execjs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides a css-module-like experience to Sass/SCSS, Rails views and JavaScript
+email:
+- rdmosolgo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/css_modules.rb
+- lib/css_modules/assets/base64.js
+- lib/css_modules/assets/css_module.js
+- lib/css_modules/engine.rb
+- lib/css_modules/rewrite.rb
+- lib/css_modules/version.rb
+- lib/css_modules/view_helper.rb
+homepage: https://github.com/rmosolgo/css_modules
+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.5.1
+signing_key: 
+specification_version: 4
+summary: Prevent naming conflicts in Sass stylesheets
+test_files: []