module mode [breaking change]

new extends syntax
added :global and :local
added module mode
removed old deprecated syntax

breaking change if you are using local scope (it was experimental)

Author: sokra

README.md

@@ -64,44 +64,60 @@ By default CSS exports all class names into a global selector scope. This is a f
 
 The syntax `:local(.className)` can be used to declare `className` in the local scope. The local identifiers are exported by the module.
 
-It does it by replacing the selectors by unique identifiers. The choosen unique identifiers are exported by the module.
+With `:local` (without brackets) local mode can be switched on for this selector. `:global(.className)` can be used to declare an explicit global selector. With `:global` (without brackets) global mode can be switched on for this selector.
+
+The loader replaces local selectors with unique identifiers. The choosen unique identifiers are exported by the module.
 
 Example:
 
 ``` css
 :local(.className) { background: red; }
-:local(#someId) { background: green; }
+:local .className { color: green; }
 :local(.className .subClass) { color: green; }
-:local(#someId .subClass) { color: blue; }
+:local .className .subClass :global(.global-class-name) { color: blue; }
 ```
 
 is transformed to
 
 ``` css
 ._23_aKvs-b8bW2Vg3fwHozO { background: red; }
-#_1j3LM6lKkKzRIt19ImYVnD { background: green; }
+._23_aKvs-b8bW2Vg3fwHozO { color: green; }
 ._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 { color: green; }
-#_1j3LM6lKkKzRIt19ImYVnD ._13LGdX8RMStbBE9w-t0gZ1 { color: blue; }
+._23_aKvs-b8bW2Vg3fwHozO ._13LGdX8RMStbBE9w-t0gZ1 .global-class-name { color: blue; }
 ```
 
 and the identifiers are exported:
 
 ``` js
 exports.locals = {
   className: "_23_aKvs-b8bW2Vg3fwHozO",
-  someId: "_1j3LM6lKkKzRIt19ImYVnD",
   subClass: "_13LGdX8RMStbBE9w-t0gZ1"
 }
 ```
 
+Camelcasing is recommended for local selectors. They are easier to use in the importing javascript module.
+
+You can use `:local(#someId)`, but this is not recommended. Use classes instead of ids.
+
 You can configure the generated ident with the `localIdentName` query parameter (default `[hash:base64]`). Example: `css-loader?localIdentName=[path][name]---[local]---[hash:base64:5]` for easier debugging.
 
 Note: For prerendering with extract-text-webpack-plugin you should use `css-loader/locals` instead of `style-loader!css-loader` in the prerendering bundle. It doesn't embed CSS but only exports the identifier mappings.
 
-### Inheriting
+### Module mode
 
 (experimental)
 
+The query parameter `module` enables **CSS module** mode. (`css-loader?module`)
+
+* Local scoped by default.
+* `url(...)` URLs behave like requests in modules:
+  * `./file.png` instead of `file.png`
+  * `module/file.png` instead of `~module/file.png`
+
+Thanks to @markdalgleish for prior work on this topic.
+
+### Inheriting
+
 When declaring a local class name you can inherit from another local class name.
 
 ``` css
@@ -110,7 +126,8 @@ When declaring a local class name you can inherit from another local class name.
   color: yellow;
 }
 
-:local(.subClass):extends(.className) {
+:local(.subClass) {
+  extends: className;
   background: blue;
 }
 ```
@@ -139,18 +156,30 @@ and CSS is transformed to:
 
 ### Importing local class names
 
-(experimental)
-
 To import a local class name from another module:
 
 ``` css
-:local(.continueButton):extends(.button from "library/button.css") {
+:local(.continueButton) {
+  extends: button from "library/button.css";
   background: red;
 }
 ```
 
 ``` css
-:local(.nameEdit):extends(.edit.highlight from "./edit.css") {
+:local(.nameEdit) {
+  extends: edit highlight from "./edit.css";
+  background: red;
+}
+```
+
+To import from multiple modules use multiple `extends:` rules. You can also use `url(...)` to specify the module (it behave a bit different).
+
+``` css
+:local(.className) {
+  extends: edit hightlight from "./edit.css";
+  extends: button from url("button.css");
+  /* equal to 'extends: button from "./button.css";' */
+  extends: classFromThisModule;
   background: red;
 }
 ```

lib/generateLocals.js

@@ -10,7 +10,8 @@ module.exports = function(locals, localExtends, importedUrls, importUrlPrefix, r
 			var line = "  " + JSON.stringify(key) + ": ";
 			function addExtend(extend) {
 				if(extend.from) {
-					var importUrl = importUrlPrefix + extend.from;
+					var importUrl = importUrlPrefix +
+						(extend.fromType === "url" ? loaderUtils.urlToRequest(extend.from) : extend.from);
 					if(importedUrls && result && importedUrls.indexOf(importUrl) < 0) {
 						result.push("exports.i(require(" + loaderUtils.stringifyRequest(this, importUrl) + "), \"\");");
 						importedUrls.push(importUrl);

lib/loader.js

@@ -16,6 +16,7 @@ module.exports = function(content, map) {
 	var forceMinimize = query.minimize;
 	var importLoaders = parseInt(query.importLoaders, 10) || 0;
 	var minimize = typeof forceMinimize !== "undefined" ? !!forceMinimize : (this && this.minimize);
+	var moduleMode = query.module;
 
 	if(typeof map !== "string") {
 		map = JSON.stringify(map);
@@ -45,7 +46,8 @@ module.exports = function(content, map) {
 				JSON.stringify("@import url(" + imp.url + ");") + ", " +
 				JSON.stringify(imp.mediaQuery) + "]);");
 		} else {
-			var importUrl = importUrlPrefix + loaderUtils.urlToRequest(imp.url);
+			var importUrl = importUrlPrefix +
+				(moduleMode ? imp.url : loaderUtils.urlToRequest(imp.url));
 			result.push("exports.i(require(" + loaderUtils.stringifyRequest(this, importUrl) + "), " + JSON.stringify(imp.mediaQuery) + ");");
 			if(!imp.mediaQuery)
 				importedUrls.push(importUrl);
@@ -62,7 +64,7 @@ module.exports = function(content, map) {
 	// replace :local()
 	var locals = {};
 	var localExtends = {};
-	require("./processLocals").call(this, stuff.locals, query, replacer, locals, localExtends);
+	require("./processLocals").call(this, stuff.selectors, query, replacer, locals, localExtends);
 
 	// remove stuff
 	stuff.remove.forEach(function(rem) {
@@ -112,19 +114,23 @@ module.exports = function(content, map) {
 		if(!stuff.urls[idx]) return str;
 		var urlItem = stuff.urls[idx];
 		var url = urlItem.url;
-		if(!loaderUtils.isUrlRequest(url, root))
+		if(!moduleMode && !loaderUtils.isUrlRequest(url, root))
 			return toEmbStr(urlItem.raw);
 		idx = url.indexOf("?#");
 		if(idx < 0) idx = url.indexOf("#");
+		var urlRequest;
 		if(idx > 0) {
 			// in cases like url('webfont.eot?#iefix')
-			var urlRequest = url.substr(0, idx);
-			return "\"+require(" + loaderUtils.stringifyRequest(this, loaderUtils.urlToRequest(urlRequest, root)) + ")+\"" + url.substr(idx);
+			urlRequest = url.substr(0, idx);
+			if(!moduleMode) urlRequest = loaderUtils.urlToRequest(urlRequest, root);
+			return "\"+require(" + loaderUtils.stringifyRequest(this, urlRequest) + ")+\"" + url.substr(idx);
 		} else if(idx === 0) {
 			// only hash
 			return toEmbStr(urlItem.raw);
 		}
-		return "\"+require(" + loaderUtils.stringifyRequest(this, loaderUtils.urlToRequest(url, root)) + ")+\"";
+		urlRequest = url;
+		if(!moduleMode) urlRequest = loaderUtils.urlToRequest(url, root);
+		return "\"+require(" + loaderUtils.stringifyRequest(this, urlRequest) + ")+\"";
 	}.bind(this));
 
 	// add a SourceMap

lib/localsLoader.js

@@ -21,7 +21,7 @@ module.exports = function(content) {
 
 	var locals = {};
 	var localExtends = {};
-	require("./processLocals").call(this, stuff.locals, query, null, locals, localExtends);
+	require("./processLocals").call(this, stuff.selectors, query, null, locals, localExtends);
 
 
 	// generate the locals