@@ -162,18 +162,35 @@ Since MonadWidget depends on MonadHold and MonadHold depends on MonadSample, any
162162[W] performEventAsync :: Event t ((a -> IO ()) -> WidgetHost m ()) -> m (Event t a)
163163```
164164
165+### Creating widgets (DOM elements)
166+
167+In general, we want widgets that change over time -- why else are we using FRP? But there are two levels of dynamic behavior created by these functions. In the simple case, the *content* of a widget is dynamic but the *definition* of the widget is static (imagine a text element with changing text). The other possibility is that the definition of the widget is itself changing over time.
168+
165169```haskell
166−-- Create a static text element
170+-- Create a static text element (text' also returns the created DOM element)
167171[W] text :: String -> m ()
168−-- Additionally return the DOM element that was created.
169172[W] text' :: String -> m Text
170173-- Create a dynamic text element
171174[W] dynText :: Dynamic t String -> m ()
172175[W] display :: Show a => Dynamic t a -> m ()
173−-- Create a dynamically-redefined Widget, returning DOM elements as they're created
176+-- Create a dynamically-redefined widget. Returns Event of newly-created widgets.
174177[W] dyn :: Dynamic t (m a) -> m (Event t a)
175−-- Like holdDyn, but each Event occurrence redefines the widget
178+-- Create a dynamically-redefined widget. Returns Dynamic of created widgets.
176179[W] widgetHold :: m a -> Event t (m a) -> m (Dynamic t a)
180+-- Given a Dynamic key/value map and a function to create a widget for a given
181+-- key & Dynamic value, create a bunch of widgets. Widgets will be created,
182+-- destroyed, and updated appropriately as the map changes. Returns Dynamic map
183+-- from keys to widgets.
184+[W] listWithKey :: Ord k => Dynamic t (Map k v) -> (k -> Dynamic t v -> m a) -> m (Dynamic t (Map k a))
185+-- As above, but the supplied function creates dynamically-redefined widgets
186+-- where the definition of the widget can depend on the Dynamic via 'dyn'.
187+[W] listViewWithKey :: Ord k => Dynamic t (Map k v) -> (k -> Dynamic t v -> m (Event t a)) -> m (Event t (Map k a))
188+-- As above, but there is a "current key", and the widget constructor gets a
189+-- Dynamic Bool indicating if that widget is currently selected. This allows
190+-- widgets to render differently when selected.
191+[W] selectViewListWithKey_ :: Ord k => Dynamic t k -> Dynamic t (Map k v) -> (k -> Dynamic t v -> Dynamic t Bool -> m (Event t a)) -> m (Event t k)
192+-- As listWithKey, but takes initial values and an update Event instead of Dynamic.
193+[W] listWithKey' :: Ord k => Map k v -> Event t (Map k (Maybe v)) -> (k -> v -> Event t v -> m a) -> m (Dynamic t (Map k a))
177194
178195. . .
179196```