diff --git a/Makefile b/Makefile index 6423890..2f11ade 100644 --- a/Makefile +++ b/Makefile @@ -6,9 +6,7 @@ comp: demo: (cd demo; elm-make Demo.elm --warn --output ../elm.js) -docs: docs.json - -docs.json: +docs: elm-make --docs=docs.json wip-pages : diff --git a/demo/Demo/Grid.elm b/demo/Demo/Grid.elm index adc4502..51c0600 100644 --- a/demo/Demo/Grid.elm +++ b/demo/Demo/Grid.elm @@ -46,7 +46,7 @@ std = democell 200 color : Int -> Style color k = - Array.get ((k + 11) % Array.length Color.palette) Color.palette + Array.get ((k + 11) % Array.length Color.hues) Color.hues |> Maybe.withDefault Color.Teal |> flip Color.color Color.S500 |> Color.background diff --git a/demo/Demo/Snackbar.elm b/demo/Demo/Snackbar.elm index 6d39938..9d8a269 100644 --- a/demo/Demo/Snackbar.elm +++ b/demo/Demo/Snackbar.elm @@ -190,8 +190,8 @@ transitionOuter = clickView : Model -> Square -> Html clickView model (k, square) = let - palette = - Array.get ((k + 4) % Array.length Color.palette) Color.palette + hue = + Array.get ((k + 4) % Array.length Color.hues) Color.hues |> Maybe.withDefault Color.Teal shade = @@ -203,7 +203,7 @@ clickView model (k, square) = Color.S500 color = - Color.color palette shade + Color.color hue shade selected' = square == Active diff --git a/src/Material.elm b/src/Material.elm index 217f88b..40914ab 100644 --- a/src/Material.elm +++ b/src/Material.elm @@ -32,13 +32,29 @@ it is not an alternative architecture. # Getting started The easiest way to get started is to start with one of the minimal examples above. -We recommend going with the library's -[component support](http://github.com/debois/elm-mdl/blob/master/examples/Component.elm) -rather than working directly in plain Elm Architecture. +We recommend going with the one that uses +[the one that uses](http://github.com/debois/elm-mdl/blob/master/examples/Component.elm) +the library's component support rather than working directly in plain Elm +Architecture. -# TODO +# Colors and CSS + +The view function of most components has this signature: + + view : Signal.Address -> Model -> List Style -> Html + +The address is standard, and `Model` is just the model type of the component. +The third argument, `List Style`, is a mechanism for you to specify additional +classes and CSS for the component. You need this, e.g., when you want to +specify the width of a button. See the +[Style](http://package.elm-lang.org/packages/debois/elm-mdl/latest/Material-Style) +module for details. + +Material Design defines a color palette. The +[Color](http://package.elm-lang.org/packages/debois/elm-mdl/latest/Material-Color) +module contains various `Style` values and helper functions for working with +this color palette. -Using TEA, Style. # Component Support @@ -132,14 +148,11 @@ but now it's not boilerplate, its "business logic".) Using this module will force all elm-mdl components to be built and included in your application. If this is unacceptable, you can custom-build a version of this -module that uses only the components you need. To do so, you need to re-implement -the present module, modifying the values `model` and `Model` by commenting out the -components you are not using. The module source can be found -[here](https://github.com/debois/elm-mdl/blob/master/src/Material.elm). - -You do not need to re-build the entire elm-mdl library; simply copy the -source of this module, give it a new name, modify as it as indicated above, -then use your modified module rather than this one. +module that uses only the components you need. To do so, you need to provide your +own versions of the type `Model` and the value `model` of the present module. +Use the corresponding definitions in this module as a starting point +([source](https://github.com/debois/elm-mdl/blob/master/src/Material.elm)) +and simply comment out the components you do not need. @docs Model, model, Action, update -} @@ -180,7 +193,9 @@ type alias Action obs = Component.Action Model obs -{-| Update function for the above Action. +{-| Update function for the above Action. Provide as the first +argument a lifting function that embeds the generic MDL action in +your own Action type. -} update : (Action obs -> obs) diff --git a/src/Material/Badge.elm b/src/Material/Badge.elm index 1e2e9f9..88731a0 100644 --- a/src/Material/Badge.elm +++ b/src/Material/Badge.elm @@ -27,6 +27,10 @@ module Material.Badge > discover additional relevant content. Their design and use is therefore an important > factor in the overall user experience. +Refer to +[this site](https://debois.github.io/elm-mdl/#/badges) +for a live demo. + @docs withBadge, noBackground, overlap -} diff --git a/src/Material/Button.elm b/src/Material/Button.elm index b31a605..68ae6fa 100644 --- a/src/Material/Button.elm +++ b/src/Material/Button.elm @@ -26,6 +26,11 @@ module Material.Button See also the [Material Design Specification]([https://www.google.com/design/spec/components/buttons.html). +Refer to +[this site](https://debois.github.io/elm-mdl/#/buttons) +for a live demo. + + # Elm architecture @docs Model, model, Action, update, View @@ -39,8 +44,12 @@ for details about what type of buttons are appropriate for which situations. @docs flat, raised, fab, minifab, icon -# Component -@docs Container, Observer, Instance, instance, fwdClick +# Component support +@docs instance, fwdClick + +## Component instance types + +@docs Container, Observer, Instance -} @@ -278,12 +287,31 @@ type alias Instance container obs = Model container Action obs (List Style -> List Html -> Html) -{-| Component instance. +{-| Create a component instance. Example usage, assuming you have a type +`Action` with a constructor `MyButtonAction : Action`, and that your +`model` has a field `mdl : Material.Model`. + + type alias Mdl = + Material.Model + + + myButton : Button.Instance Mdl Action + myButton = + Button.instance 0 MDL + Button.raised (Button.model True) + [ Button.fwdClick MyButtonAction ] + + + -- in your view: + ... + div + [] + [ myButton.view addr model.mdl ] -} instance : Int -> (Component.Action (Container c) obs -> obs) - -> (Address Action -> Model -> List Style -> List Html -> Html) + -> View -> Model -> List (Observer obs) -> Instance (Container c) obs @@ -293,7 +321,7 @@ instance id lift view model0 observers = view update .button (\x y -> {y | button = x}) id lift model0 observers -{-| Lift the button Click action to your own action. E.g., +{-| Lift the button Click action to your own action. -} fwdClick : obs -> (Observer obs) fwdClick obs action = diff --git a/src/Material/Color.elm b/src/Material/Color.elm index 602e68d..2dddc69 100644 --- a/src/Material/Color.elm +++ b/src/Material/Color.elm @@ -1,5 +1,5 @@ module Material.Color - ( Palette(..), palette + ( Hue(..), hues , Shade(..), shades , Color , color @@ -14,8 +14,6 @@ module Material.Color {-| Material Design color palette. -@docs Color - # Palette From the @@ -26,7 +24,7 @@ From the > using the 500 colors as the primary colors in your app and the other colors as > accents colors. -@docs Color, white, black, Palette, Shade, color +@docs Color, white, black, Hue, Shade, color # Color Schemes @@ -52,7 +50,7 @@ colors. @docs background, text # Misc -@docs palette, shades, scheme +@docs hues, shades, scheme -} @@ -68,7 +66,7 @@ import Material.Style exposing (..) {-| Color palette. -} -type Palette +type Hue = Indigo | Blue | LightBlue @@ -90,10 +88,10 @@ type Palette | DeepPurple -{-| Color palette as array. Mostly useful for demos. +{-| Hues as array. Mostly useful for demos. -} -palette : Array Palette -palette = +hues : Array Hue +hues = Array.fromList [ Indigo , Blue @@ -117,8 +115,8 @@ palette = ] -paletteName : Palette -> String -paletteName color = +hueName : Hue -> String +hueName color = case color of Indigo -> "indigo" Blue -> "blue" @@ -212,9 +210,9 @@ type Color = C String {-| Construct a specific color given a palette base hue and a shade. -} -color : Palette -> Shade -> Color -color palette shade = - C (paletteName palette ++ "-" ++ shadeName shade) +color : Hue -> Shade -> Color +color hue shade = + C (hueName hue ++ "-" ++ shadeName shade) {-| White color. @@ -280,14 +278,14 @@ text (C color) = {-| Given primary and accent base colors, compute name of appropriate MDL .css-file. (You are not likely to need to call this function.) -} -scheme : Palette -> Palette -> String +scheme : Hue -> Hue -> String scheme primary accent = let cssFile = case accent of Grey -> "" Brown -> "" BlueGrey -> "" - _ -> "." ++ paletteName primary ++ "-" ++ paletteName accent + _ -> "." ++ hueName primary ++ "-" ++ hueName accent in "material" ++ cssFile ++ ".min.css" diff --git a/src/Material/Elevation.elm b/src/Material/Elevation.elm index ba7e189..6aa55e8 100644 --- a/src/Material/Elevation.elm +++ b/src/Material/Elevation.elm @@ -31,6 +31,10 @@ You are encouraged to visit the [Material Design specification](https://www.google.com/design/spec/what-is-material/elevation-shadows.html) for details about appropriate use of shadows. +Refer to +[this site](https://debois.github.io/elm-mdl/#/elevation) +for a live demo. + # Component @docs shadow, validElevations, transition @@ -41,7 +45,7 @@ import Material.Style exposing (..) {-| Indicate the elevation of an element by giving it a shadow. -The `z` argument indicates intended elevation; valid values +The argument indicates intended elevation; valid values are 2, 3, 4, 6, 8, 16, 24. Invalid values produce no shadow. (The specification uses only the values 1-6, 8, 9, 12, 16, 24 for standard UI @@ -62,7 +66,7 @@ validElevations = {-| Add a CSS-transition to changes in elevation. Supply a transition duration in milliseconds as argument. -NB! This style dictated by neither MDL nor the Material Design +NB! This Style is dictated by neither MDL nor the Material Design Specification. -} transition : String -> Style diff --git a/src/Material/Grid.elm b/src/Material/Grid.elm index 7e6183a..288ce7b 100644 --- a/src/Material/Grid.elm +++ b/src/Material/Grid.elm @@ -29,6 +29,10 @@ module Material.Grid > of columns for the current screen size, it takes up the entirety of its > row. +Refer to +[this site](https://debois.github.io/elm-mdl/#/grid) +for a live demo. + Example use: import Material.Grid exposing (grid, cell, size, Device(..)) diff --git a/src/Material/Layout.elm b/src/Material/Layout.elm index 26f88e0..ebd42b7 100644 --- a/src/Material/Layout.elm +++ b/src/Material/Layout.elm @@ -29,6 +29,9 @@ module Material.Layout > consistency in outward appearance and behavior while maintaining development > flexibility and ease of use. +# Setup +@docs setupSignals + # Model & Actions @docs Mode, Model, defaultLayoutModel, initState, Action, update @@ -38,10 +41,9 @@ module Material.Layout ## Sub-views @docs row, spacer, title, navigation, link -# Setup -@docs setupSignals -} +-- TODO: Component support import Array exposing (Array) import Maybe exposing (andThen, map) diff --git a/src/Material/Scheme.elm b/src/Material/Scheme.elm index 8746c8e..99c3a24 100644 --- a/src/Material/Scheme.elm +++ b/src/Material/Scheme.elm @@ -30,10 +30,10 @@ import String import Html exposing (..) import Html.Attributes exposing (..) -import Material.Color exposing (Palette(..), Color) +import Material.Color exposing (Hue(..), Color) -scheme : Palette -> Palette -> String +scheme : Hue -> Hue -> String scheme primary accent = [ "https://code.getmdl.io/1.1.3/" ++ Material.Color.scheme primary accent , "https://fonts.googleapis.com/icon?family=Material+Icons" @@ -60,7 +60,7 @@ elm-reactor. TODO: Usage example -} -topWithScheme: Palette -> Palette -> Html -> Html +topWithScheme: Hue -> Hue -> Html -> Html topWithScheme primary accent content = div [] <| {- Trick from Peter Damoc to load CSS outside of . diff --git a/src/Material/Snackbar.elm b/src/Material/Snackbar.elm index acbf2b2..20b0e53 100644 --- a/src/Material/Snackbar.elm +++ b/src/Material/Snackbar.elm @@ -4,10 +4,17 @@ module Material.Snackbar , view ) where -{-| Material Design "Snackbar" component. +{-| From the [Material Design Lite documentation](https://www.getmdl.io/components/index.html#snackbar-section): -For live demo and intended use, see -[here](http://localhost:8000/Demo.elm#/snackbar). +> The Material Design Lite (MDL) __snackbar__ component is a container used to +> notify a user of an operation's status. It displays at the bottom of the +> screen. A snackbar may contain an action button to execute a command for the +> user. Actions should undo the committed action or retry it if it failed for +> example. Actions should not be to close the snackbar. By not providing an +> action, the snackbar becomes a __toast__ component. + +Refer to [this site](http://debois.github.io/elm-mdl#/snackbar) +for a live demo. # Generating messages @docs Contents, toast, snackbar, add diff --git a/src/Material/Style.elm b/src/Material/Style.elm index 9ba6ea4..ac5d0f3 100644 --- a/src/Material/Style.elm +++ b/src/Material/Style.elm @@ -94,8 +94,8 @@ styled ctor styles attrs' = ) -{-| Handle the ultra-common case of setting attributes of a div element. -Use like this: +{-| Convenience function for the ultra-common case of setting attributes of a +div element. Use like this: myDiv : Html myDiv = @@ -171,7 +171,7 @@ nop = NOP {-| Construct an Html element contributing to the global stylesheet. -The resulting Html is a