A book that tells the story of the UI elements of your Elm application.
You can create one chapter for each one of your UI elements and split it in sections to showcase all of their possible variants.
buttonsChapter : UIChapter (Html UIBookMsg)
buttonsChapter =
chapter "Buttons"
|> withSections
[ ( "Default", button [] [] )
, ( "Disabled", button [ disabled True ] [] )
]Don't be limited by this pattern though. A chapter and its sections may be used however you want. For instance, it's useful to have a catalog of possible colors or branding guidelines in your documentation. Why not dedicate a chapter to it?
Used for chapters with a single section.
Used for chapters with multiple sections.
Each chapter needs to define their "type" of Html. So for plain-html applications this would look like:
UIChapter (Html UIBookMsg)But if you're using something like elm-ui this would be:
UIChapter (Element UIBookMsg)Just be sure to use the same type throughout your book.
Your UIBook is a collection of chapters.
book : Book
book =
book "MyApp"
|> withChapters
[ colorsChapter
, buttonsChapter
, inputsChapter
, chartsChapter
]This returns a standard Browser.application. You can choose to use it just as you would any Elm application – however, this package can also be added as a NPM dependency to be used as zero-config dev server to get things started.
If you want to use our zero-config dev server, just install elm-ui-book as a devDependency then run npx elm-ui-book {MyBookModule}.elm and you should see your brand new Book running on your browser.
List the chapters that should be displayed on your book.
Should be used as the final step on your setup.
The internal messages used by UIBook.
You can configure your book with a few extra settings to make it more personalized. Want to change the theme color so it's more fitting to your brand? Sure. Want to use your app's logo as the header? Go crazy.
book "MyApp"
|> withColor "#007"
|> withSubtitle "Design System"
|> withChapters []Important: Please note that you always need to use the withChapters functions the final step of your setup.
Customize your docs to fit your app's theme.
Replace the default "UI Docs" subtitle with a custom one.
Replace the entire header with a custom one.
book "MyApp"
|> withHeader (h1 [ style "color" "crimson" ] [ text "My App" ])
|> withChapters []If you're building your UI elements with something other than elm/html, no worries. Just specify a renderer function that will transform your custom elements to what Elm's runtime is expecting and everything is going to be just fine. For instance, if you're using elm-ui, you would do something like this:
import Element exposing (layout)
book "MyApp"
|> withRenderer (layout [])
|> withChapters []Important: Please note that you always need to use the withChapters functions the final step of your setup.
When using a custom HTML library like elm-css or elm-ui, use this to easily turn all your chapters into plain HTML.
For now, you can't really create interactive elements inside your UIBook. However, you can showcase their different states and log actions that represent the intent to move between states. Something like this:
-- Will log "Clicked!" after pressing the button
button [ onClick <| logAction "Clicked!" ] []
-- Will log "Input: x" after pressing the "x" key
input [ onInput <| logActionWithString "Input: " ] []Logs an action that takes one string input. e.g. onInput
Logs an action that takes one Int input.
Logs an action that takes one Float input.
Logs an action that takes one generic input that can be transformed into a String.
eventToString : Event -> String
eventToString event =
case event of
Start ->
"Start"
Finish ->
"Finish"
myCustomElement {
onEvent =
logActionMap "My Custom Element: " eventToString
}
Creates a chapter with some title.