add documentation to selects

elm-package.json

@@ -1,5 +1,5 @@
 {
-    "version": "1.0.0",
+    "version": "1.0.1",
     "summary": "Elm modules commonly used at BDT",
     "repository": "https://github.com/bluedogtraining/bdt-elm.git",
     "license": "BSD3",

src/Form/Input.elm

@@ -111,7 +111,7 @@ view (Model state) =
     View state Internal.initialViewState
 
 
-{-| Transforms an Input.View into Html Msg
+{-| Transforms an Input.View into Html Input.Msg
 
     import Form.Input as Input
 
@@ -121,6 +121,7 @@ view (Model state) =
             []
             [ Input.view model.myInput
                 |> Input.render
+                |> Html.map UpdateMyInput
             ]
 -}
 render : View -> Html Internal.Msg

src/Form/Select.elm

@@ -1,15 +1,14 @@
 module Form.Select exposing
-    ( Model, View
-    , init
+    ( Model, init
     , Msg, update
     , view, render
-    , reInitialize, reset
-    , setDefaultLabel, setToLabel
+    , reInitialise, reset
     , setInitialOption, setSelectedOption, setIsOptionDisabled
     , setIsError, setIsLocked, setIsClearable
+    , setDefaultLabel, setToLabel
     , setId
-    , getIsOpen, getIsChanged
-    , getSelectedOption, getOriginalOption
+    , getIsChanged, getIsOpen
+    , getInitialOption, getSelectedOption
     , getId
     )
 
@@ -20,9 +19,41 @@ import Tuple
 import Form.Select.Internal as Internal
 
 
--- MODEL --
+{-| This module is useful if you want to add a Select Form element to your app.
+
+# Definition
+@docs Form.Select
+
+# Initialise and update
+@docs Model, init, Msg, update
+
+# View and render
+@docs view, render
+
+# State Setters
+@docs reInitialise, reset, setInitialOption, setSelectedOption, setIsOptionDisabled
+
+# View Setters
+@docs setIsError, setIsLocked, setDefaultLabel, setToLabel, setId
+
+# Getters
+@docs getIsChanged, getIsOpen, getInitialOption, getSelectedOption, getId
 
+-}
 
+{-| Add a Select.Model to your model.
+
+    import Form.Select as Select
+
+    type Title
+        = Mr
+        | Ms
+        | Dr
+
+    type alias MyModel =
+        { mySelect : Select.Model Title
+        }
+-}
 type Model option
     = Model (Internal.State option)
 
@@ -31,138 +62,210 @@ type View option
     = View (Internal.State option) (Internal.ViewState option)
 
 
+{-| Add a Select.Model to your model.
+
+    import Form.Select as Select
+
+    myInitialModel : MyModel
+    myInitialModel =
+        { mySelect = Select.init [Mr, Ms, Dr]
+        }
+-}
 init : List option -> Model option
 init =
     Internal.init >> Model
 
 
--- UPDATE --
+{-| Add a Select.Msg to your Msg.
 
+    import Form.Select as Select
 
+    type MyMsg
+        = UpdateMySelect Select.Msg
+-}
 type alias Msg
     = Internal.Msg
 
 
+{-| Use in your update function.
+
+    import Form.Select as Select
+
+    myUpdate : Msg -> Model -> (Model, Cmd Msg)
+    myUpdate msg model =
+        case msg of
+            UpdateMySelect selectMsg ->
+                let
+                    (newSelect, cmd) =
+                        Select.update selectMsg mode.mySelect
+                in
+                    { model | mySelect = newSelect } ! [ cmd ]
+-}
 update : Internal.Msg option -> Model option -> (Model option, Cmd (Internal.Msg option))
 update msg (Model state) =
 
     Tuple.mapFirst Model (Internal.update msg state)
 
 
--- VIEW --
+{-| Transform an Select.Model into an Select.View, which allows us to pipe View Setters on it.
 
+    import Form.Select as Select
 
+    myView : Model -> Html Msg
+    myView model =
+        div
+            []
+            [ Select.view model.mySelect -- pipe view setters here, for example |> setIsLocked 'your logic here'
+            ]
+-}
 view : Model option -> View option
 view (Model state) =
 
     View state Internal.initialViewState
 
 
+{-| Transforms an Select.View into Html Select.Msg
+
+    import Form.Select as Select
+
+    myView : Model -> Html Msg
+    myView model =
+        div
+            []
+            [ Select.view model.mySelect
+                |> Select.render
+                |> Html.map UpdateMySelect
+            ]
+-}
 render : View option -> Html (Internal.Msg option)
 render (View state viewState) =
 
     Internal.render state viewState
 
 
--- STATE SETTERS --
-
-
-reInitialize : Model option -> Model option
-reInitialize (Model state) =
+{-| ReInitialise your Select.Model.
+-}
+reInitialise : Model option -> Model option
+reInitialise (Model state) =
 
-    Model <| Internal.reInitialize state
+    Model <| Internal.reInitialise state
 
 
+{-| Reset your Select.Model.
+-}
 reset : Model option -> Model option
 reset (Model state) =
 
     Model <| Internal.reset state
 
 
+{-| Set the initial option of your Select.Model.
+-}
 setInitialOption : Maybe option -> Model option -> Model option
 setInitialOption selectedOption (Model state) =
 
     Model <| Internal.setInitialOption selectedOption state
 
 
+{-| Change the option of your Select.Model.
+-}
 setSelectedOption : Maybe option -> Model option -> Model option
 setSelectedOption selectedOption (Model state) =
 
     Model <| Internal.setSelectedOption selectedOption state
 
 
--- VIEW STATE SETTERS --
-
-
-setToLabel : (option -> String) -> View option -> View option
-setToLabel toLabel (View state viewState) =
-
-    View state (Internal.setToLabel toLabel viewState)
-
-
-setDefaultLabel : String -> View option -> View option
-setDefaultLabel defaultLabel (View state viewState) =
-
-    View state (Internal.setDefaultLabel defaultLabel viewState)
-
-
+{-| This function allows you to disable specific options.
+-}
 setIsOptionDisabled : (option -> Bool) -> View option -> View option
 setIsOptionDisabled isOptionDisabled (View state viewState) =
 
     View state (Internal.setIsOptionDisabled isOptionDisabled viewState)
 
 
+{-| Set whether your select is locked (disabled).
+-}
 setIsLocked : Bool -> View option -> View option
 setIsLocked isLocked (View state viewState) =
 
     View state (Internal.setIsLocked isLocked viewState)
 
 
+{-| Set whether your select is in error mode (red border).
+-}
 setIsError : Bool -> View option -> View option
 setIsError isError (View state viewState) =
 
     View state (Internal.setIsError isError viewState)
 
 
+{-| Set whether your select is clearable (x icon).
+-}
 setIsClearable : Bool -> View option -> View option
 setIsClearable isClearable (View state viewState) =
 
     View state (Internal.setIsClearable isClearable viewState)
 
 
-setId : String -> View option -> View option
-setId id (View state viewState) =
-
-    View state (Internal.setId id viewState)
-
+{-| Set how your options are printed to the screen.
+-}
+setToLabel : (option -> String) -> View option -> View option
+setToLabel toLabel (View state viewState) =
 
--- GETTERS --
+    View state (Internal.setToLabel toLabel viewState)
 
 
-getSelectedOption : Model option -> Maybe option
-getSelectedOption (Model state) =
+{-| Set the default label, for example (-- NOTHING SELECTED --).
+-}
+setDefaultLabel : String -> View option -> View option
+setDefaultLabel defaultLabel (View state viewState) =
 
-    Internal.getSelectedOption state
+    View state (Internal.setDefaultLabel defaultLabel viewState)
 
 
-getOriginalOption : Model option -> Maybe option
-getOriginalOption (Model state) =
+{-| Give your select an id. Can be useful for DOM selectors (focus, WebComponents etc.)
+-}
+setId : String -> View option -> View option
+setId id (View state viewState) =
 
-    Internal.getOriginalOption state
+    View state (Internal.setId id viewState)
 
 
+{-| Whether your select was changed. Useful if you want to disable save buttons unless there were changes etc.
+-}
 getIsChanged : Model option -> Bool
 getIsChanged (Model state) =
 
     Internal.getIsChanged state
 
 
+{-| Whether this select is currently open.
+-}
 getIsOpen : Model option -> Bool
 getIsOpen (Model state) =
 
     Internal.getIsOpen state
 
 
+{-| Get the initial option of your select.
+-}
+getInitialOption : Model option -> Maybe option
+getInitialOption (Model state) =
+
+    Internal.getInitialOption state
+
+
+{-| Get the current option of your select. This is what you'd use to display the data somewhere outside of your select,
+or to send the data to the backend for example etc.
+-}
+getSelectedOption : Model option -> Maybe option
+getSelectedOption (Model state) =
+
+    Internal.getSelectedOption state
+
+
+{-| Useful if you need the id of the select in your update function, so set focus etc.
+-}
 getId : View option -> Maybe String
 getId (View _ viewState) =
 

src/Form/Select/Internal.elm

@@ -3,13 +3,13 @@ module Form.Select.Internal exposing
     , init, initialViewState
     , Msg, update
     , render
-    , reInitialize ,reset
+    , reInitialise, reset
     , setDefaultLabel, setToLabel
     , setInitialOption, setSelectedOption, setIsOptionDisabled
-    , setIsClearable, setIsError, setIsLocked
+    , setIsError, setIsLocked, setIsClearable
     , setId
-    , getIsOpen, getIsChanged
-    , getSelectedOption, getOriginalOption
+    , getIsChanged, getIsOpen
+    , getSelectedOption, getInitialOption
     , getId
     )
 
@@ -358,8 +358,8 @@ optionItem state viewState option =
 -- STATE SETTERS --
 
 
-reInitialize : State option -> State option
-reInitialize state =
+reInitialise : State option -> State option
+reInitialise state =
 
     { state | selectedOption = Resettable.init (Resettable.getValue state.selectedOption) }
 
@@ -430,22 +430,22 @@ setId id viewState =
 -- GETTERS --
 
 
-getSelectedOption : State option -> Maybe option
-getSelectedOption state =
+getIsChanged : State option -> Bool
+getIsChanged state =
 
-    Resettable.getValue state.selectedOption
+    Resettable.getIsChanged state.selectedOption
 
 
-getOriginalOption : State option -> Maybe option
-getOriginalOption state =
+getInitialOption : State option -> Maybe option
+getInitialOption state =
 
-    Resettable.getOriginalValue state.selectedOption
+    Resettable.getInitialValue state.selectedOption
 
 
-getIsChanged : State option -> Bool
-getIsChanged state =
+getSelectedOption : State option -> Maybe option
+getSelectedOption state =
 
-    Resettable.isChanged state.selectedOption
+    Resettable.getValue state.selectedOption
 
 
 getIsOpen : State option -> Bool