web-view-0.6.2: Type-safe HTML and CSS with intuitive layouts and composable styles.
Copyright(c) 2023 Sean Hess
LicenseBSD3
MaintainerSean Hess <seanhess@gmail.com>
Stabilityexperimental
Portabilityportable
Safe HaskellNone
LanguageGHC2021

Web.View

Description

Type-safe HTML and CSS with intuitive layout and composable styles. Inspired by Tailwindcss and Elm-UI

Synopsis

How to use this library

Create styled Views using composable Haskell functions

myView :: View ctx ()
myView = col (gap 10) $ do
 el (bold . fontSize 32) "My page"
 button (border 1) "Click Me"

This represents an HTML fragment with embedded CSS definitions

<style type='text/css'>
.bold { font-weight:bold }
.brd-1 { border:1px; border-style:solid }
.col { display:flex; flex-direction:column }
.fs-32 { font-size:2.0rem }
.gap-10 { gap:0.625rem }
</style>

<div class='col gap-10'>
  <div class='bold fs-32'>My page</div>
  <button class='brd-1'>Click Me</button>
</div>

Leverage the full power of Haskell functions for reuse, instead of relying on CSS.

header = bold
h1 = header . fontSize 32
h2 = header . fontSize 24
page = gap 10

myView = col page $ do
  el h1 "My Page"
...

This approach is inspired by Tailwindcss' Utility Classes

Rendering Views

renderText :: View () () -> Text Source #

Renders a View as HTML with embedded CSS class definitions

>>> renderText $ el bold "Hello"
<style type='text/css'>.bold { font-weight:bold }</style>
<div class='bold'>Hello</div>

Full HTML Documents

Create a full HTML document by embedding the view and cssResetEmbed

import Data.String.Interpolate (i)
import Web.View

toDocument :: Text -> Text
toDocument content =
  [i|<html>
    <title>My Website</title>
    <head><style type="text/css">#{cssResetEmbed}</style></head>
    <body>#{content}</body>
  </html>|]

myDocument :: Text
myDocument = toDocument $ renderText myView

Views

data View context a Source #

Views are HTML fragments that carry all CSS used by any child element.

view :: View c ()
view = col (pad 10 . gap 10) $ do
  el bold "Hello"
  el_ "World"

They can also have a context which can be used to create type-safe or context-aware elements. See context or table for an example

Instances

Instances details
Applicative (View context) Source # 
Instance details

Defined in Web.View.View

Methods

pure :: a -> View context a #

(<*>) :: View context (a -> b) -> View context a -> View context b #

liftA2 :: (a -> b -> c) -> View context a -> View context b -> View context c #

(*>) :: View context a -> View context b -> View context b #

(<*) :: View context a -> View context b -> View context a #

Functor (View context) Source # 
Instance details

Defined in Web.View.View

Methods

fmap :: (a -> b) -> View context a -> View context b #

(<$) :: a -> View context b -> View context a #

Monad (View context) Source # 
Instance details

Defined in Web.View.View

Methods

(>>=) :: View context a -> (a -> View context b) -> View context b #

(>>) :: View context a -> View context b -> View context b #

return :: a -> View context a #

IsString (View context ()) Source # 
Instance details

Defined in Web.View.View

Methods

fromString :: String -> View context () #

Mods

type Mod context = Attributes context -> Attributes context Source #

Element functions expect a modifier function as their first argument. These can add attributes and classes. Combine multiple Mods with (.)

userEmail :: User -> View c ()
userEmail user = input (fontSize 16 . active) (text user.email)
  where
    active = isActive user then bold else id

If you don't want to specify any attributes, you can use id

plainView :: View c ()
plainView = el id "No styles"

Elements

el :: Mod c -> View c () -> View c () Source #

A basic element

el (bold . pad 10) "Hello"

el_ :: View c () -> View c () Source #

A basic element, with no modifiers

el_ "Hello"

Layout

layout :: Mod c -> View c () -> View c () Source #

We can intuitively create layouts with combinations of row, col, stack, grow, and space

Wrap main content in layout to allow the view to consume vertical screen space

holygrail :: View c ()
holygrail = layout id $ do
  row section "Top Bar"
  row grow $ do
    col section "Left Sidebar"
    col (section . grow) "Main Content"
    col section "Right Sidebar"
  row section "Bottom Bar"
  where section = border 1

root :: Mod c Source #

As layout but as a Mod

holygrail = col root $ do
  ...

col :: Mod c -> View c () -> View c () Source #

Lay out children in a column.

col grow $ do
   el_ "Top"
   space
   el_ "Bottom"

row :: Mod c -> View c () -> View c () Source #

Lay out children in a row

row id $ do
   el_ "Left"
   space
   el_ "Right"

space :: View c () Source #

Space that fills the available space in the parent row or col.

row id $ do
 space
 el_ "Right"

This is equivalent to an empty element with grow

space = el grow none

nav :: Mod c -> View c () -> View c () Source #

A Nav element

stack :: Mod c -> Layer c () -> View c () Source #

Stack children on top of each other. Each child has the full width. See popout

stack id $ do
  row id "Background"
  row (bg Black . opacity 0.5) "Overlay"

data Layer c a Source #

A popout does not

Instances

Instances details
Applicative (Layer c) Source # 
Instance details

Defined in Web.View.Layout

Methods

pure :: a -> Layer c a #

(<*>) :: Layer c (a -> b) -> Layer c a -> Layer c b #

liftA2 :: (a -> b -> c0) -> Layer c a -> Layer c b -> Layer c c0 #

(*>) :: Layer c a -> Layer c b -> Layer c b #

(<*) :: Layer c a -> Layer c b -> Layer c a #

Functor (Layer c) Source # 
Instance details

Defined in Web.View.Layout

Methods

fmap :: (a -> b) -> Layer c a -> Layer c b #

(<$) :: a -> Layer c b -> Layer c a #

Monad (Layer c) Source # 
Instance details

Defined in Web.View.Layout

Methods

(>>=) :: Layer c a -> (a -> Layer c b) -> Layer c b #

(>>) :: Layer c a -> Layer c b -> Layer c b #

return :: a -> Layer c a #

layer :: View c () -> Layer c () Source #

A normal layer contributes to the size of the parent

popout :: Mod c -> View c () -> Layer c () Source #

This child of a stack can pop out of the parent, covering content outside of it. Only usable inside stack

stack id $ do
  layer id $ input (value "Autocomplete Box")
  layer (popout (TRBL 50 0 0 0)) $ do
    el_ "Item 1"
    el_ "Item 2"
    el_ "Item 3"
el_ "This is covered by the menu"

scroll :: Mod c Source #

Make a fixed layout by putting scroll on a child-element

document = row root $ do
  nav (width 300) "Sidebar"
  col (grow . scroll) "Main Content"

grow :: Mod c Source #

Grow to fill the available space in the parent row or col

row id $ do
 el grow none
 el_ "Right"

flexRow :: Mod c Source #

Set container to be a row. Favor row when possible

flexCol :: Mod c Source #

Set container to be a column. Favor col when possible

hide :: Mod c Source #

Hide an element. See display

truncate :: Mod c Source #

Cut off the contents of the element

Content

text :: Text -> View c () Source #

Add text to a view. Not required for string literals

el_ $ do
  "Hello: "
  text user.name

raw :: Text -> View c () Source #

Embed static, unescaped HTML or SVG. Take care not to use raw with user-generated content.

spinner = raw "<svg>...</svg>"

none :: View c () Source #

Do not show any content

if isVisible
 then content
 else none

pre :: Mod c -> Text -> View c () Source #

code :: Mod c -> Text -> View c () Source #

Inputs

form :: Mod c -> View c () -> View c () Source #

input :: Mod c -> View c () Source #

name :: Text -> Mod c Source #

label :: Mod c -> View c () -> View c () Source #

link :: Url -> Mod c -> View c () -> View c () Source #

A hyperlink to the given url

button :: Mod c -> View c () -> View c () Source #

Lists

ol :: Mod c -> ListItem c () -> View c () Source #

List elements do not include any inherent styling but are useful for accessibility. See list.

ol id $ do
 let nums = list Decimal
 li nums "one"
 li nums "two"
 li nums "three"

ul :: Mod c -> ListItem c () -> View c () Source #

li :: Mod c -> View c () -> ListItem c () Source #

Tables

table :: Mod c -> [dt] -> Eff '[Writer [TableColumn c dt]] () -> View c () Source #

Create a type safe data table by specifying columns

usersTable :: [User] -> View c ()
usersTable us = do
  table id us $ do
    tcol (th hd "Name") $ \u -> td cell $ text u.name
    tcol (th hd "Email") $ \u -> td cell $ text u.email
 where
  hd = cell . bold
  cell = pad 4 . border 1

tcol :: forall dt c. View (TableHead c) () -> (dt -> View dt ()) -> Eff '[Writer [TableColumn c dt]] () Source #

th :: Mod c -> View c () -> View (TableHead c) () Source #

td :: Mod () -> View () () -> View dt () Source #

data TableColumn c dt Source #

Document Metadata

script :: Text -> View c () Source #

style :: Text -> View c () Source #

CSS Modifiers

width :: Length -> Mod c Source #

Set to a specific width

height :: Length -> Mod c Source #

Set to a specific height

minWidth :: Length -> Mod c Source #

Allow width to grow to contents but not shrink any smaller than value

minHeight :: Length -> Mod c Source #

Allow height to grow to contents but not shrink any smaller than value

pad :: Sides Length -> Mod c Source #

Space surrounding the children of the element

To create even spacing around and between all elements:

col (pad 10 . gap 10) $ do
  el_ "one"
  el_ "two"
  el_ "three"

gap :: Length -> Mod c Source #

The space between child elements. See pad

shadow :: (Style Shadow a, ToClassName a) => a -> Mod c Source #

Add a drop shadow to an element

input (shadow Inner) "Inset Shadow"
button (shadow ()) "Click Me"

data Shadow Source #

Instances

Instances details
Style Shadow Inner Source # 
Instance details

Defined in Web.View.Style

Style Shadow None Source # 
Instance details

Defined in Web.View.Style

Style Shadow () Source # 
Instance details

Defined in Web.View.Style

Methods

styleValue :: () -> StyleValue Source #

data Inner Source #

Constructors

Inner 

Instances

Instances details
Show Inner Source # 
Instance details

Defined in Web.View.Style

Methods

showsPrec :: Int -> Inner -> ShowS #

show :: Inner -> String #

showList :: [Inner] -> ShowS #

ToClassName Inner Source # 
Instance details

Defined in Web.View.Style

Style Shadow Inner Source # 
Instance details

Defined in Web.View.Style

rounded :: Length -> Mod c Source #

Round the corners of the element

color :: ToColor clr => clr -> Mod ctx Source #

Set the text color. See ToColor

bg :: ToColor clr => clr -> Mod ctx Source #

Set the background color. See ToColor

border :: Sides PxRem -> Mod c Source #

Set a border around the element

el (border 1) "all sides"
el (border (X 1)) "only left and right"

borderColor :: ToColor clr => clr -> Mod ctx Source #

Set a border color. See ToColor

pointer :: Mod c Source #

Use a button-like cursor when hovering over the element

Button-like elements:

btn = pointer . bg Primary . hover (bg PrimaryLight)

options = row id $ do
  el btn "Login"
  el btn "Sign Up"

position :: Position -> Mod c Source #

position:absolute. See stack and popout

data Position Source #

Constructors

Absolute 
Fixed 
Sticky 
Relative 

Instances

Instances details
Show Position Source # 
Instance details

Defined in Web.View.Style

ToClassName Position Source # 
Instance details

Defined in Web.View.Style

ToStyleValue Position Source # 
Instance details

Defined in Web.View.Style

offset :: Sides Length -> Mod c Source #

Set Top, Right, Bottom and Left. Requires position Absolute or Fixed. Also see popup

data Align Source #

Instances

Instances details
Show Align Source # 
Instance details

Defined in Web.View.Types

Methods

showsPrec :: Int -> Align -> ShowS #

show :: Align -> String #

showList :: [Align] -> ShowS #

ToClassName Align Source # 
Instance details

Defined in Web.View.Types

ToStyleValue Align Source # 
Instance details

Defined in Web.View.Types

list :: (ToClassName a, Style ListType a) => a -> Mod c Source #

Set the list style of an item

ol id $ do
  li (list Decimal) "First"
  li (list Decimal) "Second"
  li (list Decimal) "Third"

data ListType Source #

Constructors

Decimal 
Disc 

Instances

Instances details
Show ListType Source # 
Instance details

Defined in Web.View.Style

ToClassName ListType Source # 
Instance details

Defined in Web.View.Style

ToStyleValue ListType Source # 
Instance details

Defined in Web.View.Style

Style ListType ListType Source # 
Instance details

Defined in Web.View.Style

Style ListType None Source # 
Instance details

Defined in Web.View.Style

display :: (Style Display a, ToClassName a) => a -> Mod c Source #

Set container display

el (display None) HIDDEN

data Display Source #

Constructors

Block 

Instances

Instances details
Show Display Source # 
Instance details

Defined in Web.View.Style

ToClassName Display Source # 
Instance details

Defined in Web.View.Style

ToStyleValue Display Source # 
Instance details

Defined in Web.View.Style

Style Display Display Source # 
Instance details

Defined in Web.View.Style

Style Display None Source # 
Instance details

Defined in Web.View.Style

transition :: Ms -> TransitionProperty -> Mod c Source #

Animate changes to the given property

el (transition 100 (Height 400)) "Tall"
el (transition 100 (Height 100)) "Small"

data Ms Source #

Milliseconds, used for transitions

Instances

Instances details
Num Ms Source # 
Instance details

Defined in Web.View.Types

Methods

(+) :: Ms -> Ms -> Ms #

(-) :: Ms -> Ms -> Ms #

(*) :: Ms -> Ms -> Ms #

negate :: Ms -> Ms #

abs :: Ms -> Ms #

signum :: Ms -> Ms #

fromInteger :: Integer -> Ms #

Show Ms Source # 
Instance details

Defined in Web.View.Types

Methods

showsPrec :: Int -> Ms -> ShowS #

show :: Ms -> String #

showList :: [Ms] -> ShowS #

ToClassName Ms Source # 
Instance details

Defined in Web.View.Types

ToStyleValue Ms Source # 
Instance details

Defined in Web.View.Types

Selector States

hover :: Mod c -> Mod c Source #

Apply when hovering over an element

el (bg Primary . hover (bg PrimaryLight)) "Hover"

active :: Mod c -> Mod c Source #

Apply when the mouse is pressed down on an element

even :: Mod c -> Mod c Source #

Apply to even-numbered children

odd :: Mod c -> Mod c Source #

Apply to odd-numbered children

media :: Media -> Mod c -> Mod c Source #

Apply when the Media matches the current window. This allows for responsive designs

el (width 100 . media (MinWidth 800) (width 400))
  "Big if window > 800"

data Media Source #

Media allows for responsive designs that change based on characteristics of the window. See Layout Example

Constructors

MinWidth Int 
MaxWidth Int 

Instances

Instances details
Show Media Source # 
Instance details

Defined in Web.View.Types

Methods

showsPrec :: Int -> Media -> ShowS #

show :: Media -> String #

showList :: [Media] -> ShowS #

Eq Media Source # 
Instance details

Defined in Web.View.Types

Methods

(==) :: Media -> Media -> Bool #

(/=) :: Media -> Media -> Bool #

Ord Media Source # 
Instance details

Defined in Web.View.Types

Methods

compare :: Media -> Media -> Ordering #

(<) :: Media -> Media -> Bool #

(<=) :: Media -> Media -> Bool #

(>) :: Media -> Media -> Bool #

(>=) :: Media -> Media -> Bool #

max :: Media -> Media -> Media #

min :: Media -> Media -> Media #

parent :: Text -> Mod c -> Mod c Source #

Apply when the element is somewhere inside an anscestor.

For example, the HTMX library applies an "htmx-request" class to the body when a request is pending. We can use this to create a loading indicator

el (pad 10) $ do
  el (parent "htmx-request" flexRow . hide) "Loading..."
  el (parent "htmx-request" hide . flexRow) "Normal Content"

View Context

context :: View context context Source #

Views have a Reader built-in for convienient access to static data, and to add type-safety to view functions. See 'Web.View.Element.ListItem and https://hackage.haskell.org/package/hyperbole/docs/Web-Hyperbole.html

numberView :: View Int ()
numberView = do
  num <- context
  el_ $ do
    "Number: "
    text (pack $ show num)

addContext :: context -> View context () -> View c () Source #

Run a view with a specific context in a parent View with a different context.

parentView :: View c ()
parentView = do
  addContext 1 numberView
  addContext 2 numberView
  addContext 3 numberView

Creating New Elements and Modifiers

tag :: Text -> Mod c -> View c () -> View c () Source #

Create a new element constructor with the given tag name

aside :: Mod c -> View c () -> View c ()
aside = tag "aside"

att :: Name -> AttValue -> Mod c Source #

Set an attribute, replacing existing value

hlink :: Text -> View c () -> View c ()
hlink url content = tag "a" (att "href" url) content

Types

data Sides a Source #

Options for styles that support specifying various sides. This has a "fake" Num instance to support literals

border 5
border (X 2)
border (TRBL 0 5 0 0)

Constructors

All a 
TRBL a a a a 
X a 
Y a 
XY a a 
T a 
R a 
B a 
L a 

Instances

Instances details
Num a => Num (Sides a) Source # 
Instance details

Defined in Web.View.Types

Methods

(+) :: Sides a -> Sides a -> Sides a #

(-) :: Sides a -> Sides a -> Sides a #

(*) :: Sides a -> Sides a -> Sides a #

negate :: Sides a -> Sides a #

abs :: Sides a -> Sides a #

signum :: Sides a -> Sides a #

fromInteger :: Integer -> Sides a #

data PxRem Source #

Px, converted to Rem. Allows for the user to change the document font size and have the app scale accordingly. But allows the programmer to code in pixels to match a design

Instances

Instances details
Enum PxRem Source # 
Instance details

Defined in Web.View.Types

Num PxRem Source # 
Instance details

Defined in Web.View.Types

Integral PxRem Source # 
Instance details

Defined in Web.View.Types

Real PxRem Source # 
Instance details

Defined in Web.View.Types

Methods

toRational :: PxRem -> Rational #

Show PxRem Source # 
Instance details

Defined in Web.View.Types

Methods

showsPrec :: Int -> PxRem -> ShowS #

show :: PxRem -> String #

showList :: [PxRem] -> ShowS #

Eq PxRem Source # 
Instance details

Defined in Web.View.Types

Methods

(==) :: PxRem -> PxRem -> Bool #

(/=) :: PxRem -> PxRem -> Bool #

Ord PxRem Source # 
Instance details

Defined in Web.View.Types

Methods

compare :: PxRem -> PxRem -> Ordering #

(<) :: PxRem -> PxRem -> Bool #

(<=) :: PxRem -> PxRem -> Bool #

(>) :: PxRem -> PxRem -> Bool #

(>=) :: PxRem -> PxRem -> Bool #

max :: PxRem -> PxRem -> PxRem #

min :: PxRem -> PxRem -> PxRem #

ToClassName PxRem Source # 
Instance details

Defined in Web.View.Types

ToStyleValue PxRem Source # 
Instance details

Defined in Web.View.Types

data Length Source #

Constructors

PxRem PxRem 
Pct Float 

Instances

Instances details
Num Length Source # 
Instance details

Defined in Web.View.Types

Show Length Source # 
Instance details

Defined in Web.View.Types

ToClassName Length Source # 
Instance details

Defined in Web.View.Types

ToStyleValue Length Source # 
Instance details

Defined in Web.View.Types

class ToColor a where Source #

ToColor allows you to create a type containing your application's colors:

data AppColor
  = White
  | Primary
  | Dark

instance ToColor AppColor where
  colorValue White = "#FFF"
  colorValue Dark = "#333"
  colorValue Primary = "#00F"

hello :: View c ()
hello = el (bg Primary . color White) "Hello"

Minimal complete definition

colorValue

Methods

colorValue :: a -> HexColor Source #

colorName :: a -> Text Source #

default colorName :: Show a => a -> Text Source #

Instances

Instances details
ToColor HexColor Source # 
Instance details

Defined in Web.View.Types

newtype HexColor Source #

Hexidecimal Color. Can be specified with or without the leading #. Recommended to use an AppColor type instead of manually using hex colors. See ToColor

Constructors

HexColor Text 

Instances

Instances details
IsString HexColor Source # 
Instance details

Defined in Web.View.Types

Show HexColor Source # 
Instance details

Defined in Web.View.Types

ToClassName HexColor Source # 
Instance details

Defined in Web.View.Types

ToColor HexColor Source # 
Instance details

Defined in Web.View.Types

ToStyleValue HexColor Source # 
Instance details

Defined in Web.View.Types

data None Source #

Constructors

None 

Instances

Instances details
Show None Source # 
Instance details

Defined in Web.View.Types

Methods

showsPrec :: Int -> None -> ShowS #

show :: None -> String #

showList :: [None] -> ShowS #

ToClassName None Source # 
Instance details

Defined in Web.View.Types

ToStyleValue None Source # 
Instance details

Defined in Web.View.Types

Style Display None Source # 
Instance details

Defined in Web.View.Style

Style ListType None Source # 
Instance details

Defined in Web.View.Style

Style Shadow None Source # 
Instance details

Defined in Web.View.Style

Url

type Query = [QueryItem] #

A sequence of QueryItems.