Readme + documentation (#7)

Author: turboMaCk

.travis.yml

@@ -40,4 +40,5 @@ install:
   - pushd tests && elm-package install --yes && popd
 
 script:
+  - elm-make --yes
   - npm test

README.md

@@ -0,0 +1,81 @@
+# Class Namespaces
+
+[![Build Status](https://travis-ci.org/GlobalWebIndex/class-namespaces.svg?branch=master)](https://travis-ci.org/GlobalWebIndex/class-namespaces)
+
+Abstraction for easier work with conventional namespaced class names in Elm + TEA.
+Currently only our in-house [WeakCss](https://github.com/GlobalWebIndex/weak-css) style is supported.
+We're considering adding classic [BEM](http://getbem.com/) style support in future though.
+
+**This package is highly experimental and might change a lot over time.**
+
+Feedback and contributions to both code and documentation are very welcome.
+
+## Installation
+
+Usual elm package install:
+
+```
+$ elm package install GlobalWebIndex/class-namespaces
+```
+
+## Usage
+
+Just simply use `WeakCss` module's API instead of using `Html.Attributes.class` directly.
+
+```elm
+import Html exposing (Html, Attribute)
+import WeakCss exposing (ClassName)
+
+moduleClass : ClassName
+moduleClass =
+    WeakCss.namespace "menu"
+
+view : Html msg
+view =
+    let
+        navClass =
+            moduleClass
+                |> WeakCss.addElement "nav"
+
+        itemClass =
+            navClass
+                |> WeakCss.addElement "item"
+    in
+        Html.aside
+            [ moduleClass |> WeakCss.toClass ]
+            [ Html.nav
+                [ navClass |> WeakCss.toClass ]
+                [ Html.ul
+                    [ navClass |> nested "list" ]
+                    [ Html.li [ itemClass |> WeakCss.withStates [] ] [ Html.text "first item"]
+                    , Html.li [ itemClass |> WeakCss.withStates ["active"] ] [ Html.text "second active item"]
+                    ]
+                ]
+            ]
+```
+
+This is structure of corresponding CSS file written in [SCSS](http://sass-lang.com/):
+
+```scss
+.menu {
+    &__nav {
+        &--list {
+        }
+
+        &--item {
+            &.active {
+            }
+        }
+    }
+}
+```
+
+And this is how selectors in compiled CSS file will look like:
+
+```css
+.menu {}
+.menu__nav {}
+.menu__nav--list {}
+.menu__nav--item {}
+.menu__nav--item.active {}
+```

elm-package.json

@@ -6,7 +6,7 @@
     "source-directories": [
         "src"
     ],
-    "exposed-modules": ["NamespaceClass"],
+    "exposed-modules": ["WeakCss"],
     "dependencies": {
         "elm-lang/core": "5.1.1 <= v < 6.0.0",
         "elm-lang/html": "2.0.0 <= v < 3.0.0"

src/Escape.elm

@@ -4,22 +4,7 @@ import Regex exposing (Regex)
 
 
 sanitizeNamespace : String -> String
-sanitizeNamespace =
-    sanitize_
-
-
-sanitize : String -> String
-sanitize str =
-    let
-        regex =
-            Regex.regex "_{2,}|-{2,}" |> Regex.caseInsensitive
-    in
-        sanitize_ str
-            |> Regex.replace Regex.All regex (\_ -> "")
-
-
-sanitize_ : String -> String
-sanitize_ str =
+sanitizeNamespace str =
     let
         sanitizeRegex =
             Regex.regex "[^a-z0-9\\-_]"
@@ -35,3 +20,13 @@ sanitize_ str =
         str
             |> Regex.replace Regex.All sanitizeRegex replacement
             |> Regex.replace Regex.All leadNumbers replacement
+
+
+sanitize : String -> String
+sanitize str =
+    let
+        regex =
+            Regex.regex "_{2,}|-{2,}" |> Regex.caseInsensitive
+    in
+        sanitizeNamespace str
+            |> Regex.replace Regex.All regex (\_ -> "")

src/WeakCss.elm

@@ -2,25 +2,26 @@ module WeakCss
     exposing
         ( ClassName
         , namespace
-        , element
+        , addElement
         , toClass
         , nested
         , withStates
         )
 
-{-| Abstraction for generating convetional class names
+{-| Abstraction for working with [`Weak Css`](https://github.com/GlobalWebIndex/weak-css)
+style class names.
 
 # Type and Constructor
 
 @docs ClassName, namespace
 
 # Adding Elements
 
-@docs element
+@docs addElement
 
 # Convert to Attribute
 
-@docs toClass, element, nested, withStates
+@docs toClass, nested, withStates
 
 -}
 
@@ -32,13 +33,16 @@ import Escape
 -- Type
 
 
-{-| ClassName type describes selector used to style element.
+{-| ClassName type describes class selector used to style element.
+
+All strings are sanitized to prevent missuse and odd resulting selectors.
+**It's highly recommended to avoid spaces, `__` and `--` in arguments though.**
 -}
 type ClassName
     = ClassName String (List String)
 
 
-{-| Construct [`ClassName`](#ClassName) with given namespace
+{-| Construct [`ClassName`](#ClassName) with given namespace.
 
     >>> import Html.Attributes exposing (class)
 
@@ -51,28 +55,28 @@ namespace name =
 
 
 
--- Add nested element
+-- Add nested element to element path.
 
 
 {-| Add element
 
     >>> import Html.Attributes exposing (class)
 
     >>> namespace "menu"
-    ... |> element "list"
+    ... |> addElement "list"
     ... |> toClass
     class "menu__list"
 -}
-element : String -> ClassName -> ClassName
-element name (ClassName namespace list) =
+addElement : String -> ClassName -> ClassName
+addElement name (ClassName namespace list) =
     ClassName namespace <| (Escape.sanitize name) :: list
 
 
 
 -- Convert to Html.Attribute
 
 
-{-| Convert [`ClassName`](#ClassName) to `Html.Attribute msg`
+{-| Convert [`ClassName`](#ClassName) to `Html.Attribute msg`.
 
     >>> import Html.Attributes exposing (class)
 
@@ -81,7 +85,7 @@ element name (ClassName namespace list) =
     class "menu"
 
     >>> namespace "menu"
-    ... |> element "list"
+    ... |> addElement "list"
     ... |> toClass
     class "menu__list"
 -}
@@ -90,7 +94,7 @@ toClass =
     class << toString
 
 
-{-| Add new element and turn to `Html.Attribute msg`
+{-| Add new element and convert to `Html.Attribute msg`.
 
     >>> import Html.Attributes exposing (class)
 
@@ -99,21 +103,21 @@ toClass =
     class "menu__item"
 
     >>> namespace "menu"
-    ... |> element "item"
+    ... |> addElement "item"
     ... |> nested "link"
     class "menu__item--link"
 -}
 nested : String -> ClassName -> Attribute msg
 nested name =
-    toClass << element name
+    toClass << addElement name
 
 
-{-| Add state to [`ClassName`](#ClassName) and turn to `Html.Attrinute msg`
+{-| Add state to last element [`ClassName`](#ClassName) and convert to `Html.Attrinute msg`.
 
     >>> import Html.Attributes exposing (class)
 
     >>> namespace "menu"
-    ... |> element "item"
+    ... |> addElement "item"
     ... |> withStates ["active", "highlighted"]
     class "menu__item active highlighted"
 

tests/Tests.elm

@@ -16,7 +16,7 @@ namespaced =
 
 
 inElement =
-    element "list" namespaced
+    addElement "list" namespaced
 
 
 all : Test
@@ -45,19 +45,19 @@ namespaceClassTest =
         , test "more elements" <|
             \() ->
                 inElement
-                    |> element "item"
+                    |> addElement "item"
                     |> nested "link"
                     |> Expect.equal (class "menu__list--item--link")
         , test "with state" <|
             \() ->
                 inElement
-                    |> element "item"
+                    |> addElement "item"
                     |> withStates [ "active", "edited" ]
                     |> Expect.equal (class "menu__list--item active edited")
         , test "with empty state" <|
             \() ->
                 inElement
-                    |> element "item"
+                    |> addElement "item"
                     |> withStates []
                     |> Expect.equal (class "menu__list--item")
         ]