Add documentation notes related to recent issues/questions (#113)

* Add section in tutorials about 'No instance for (Typeable s)' compilation error

* Add note about WidgetEnv's widgetKeyMap usage

* Update Changelog

ChangeLog.md

@@ -6,6 +6,7 @@
 - Lens tutorial sample code ([PR #95](https://github.com/fjvallarino/monomer/pull/95) and [PR #98](https://github.com/fjvallarino/monomer/pull/98)). Thanks @Clindbergh!
 - ColorPicker's numericFields vertical alignment ([PR #108](https://github.com/fjvallarino/monomer/pull/108)).
 - Differences in glyphs positions used by FontManager and nanovg ([PR #105](https://github.com/fjvallarino/monomer/pull/105)).
+- `nodeInfoFromKey` relies on `nodeInfoFromPath` to retrieve information instead of fetching it directly from `WidgetEnv`'s `widgetKeyMap`, which can be stale ([PR #110](https://github.com/fjvallarino/monomer/pull/110))
 
 ### Added
 

docs/tutorials/01-basics.md

@@ -95,7 +95,9 @@ First of all, it has the type signature. You don't really need to include it,
 but in general it's preferable to do it in order to have clearer compiler
 errors. Both `WidgetEnv` (environment information that can be used when building
 the UI) and `WidgetNode` (the result of building the UI) receive the type of
-your model and the type of your events as type parameters.
+your model and the type of your events as type parameters (sometimes referred to
+as `s` and `e` in the tutorials when being general about the return type, as in
+`WidgetNode s e`).
 
 Next, it declares the parameters the function receives:
 

docs/tutorials/02-styling.md

@@ -79,6 +79,43 @@ In general, all components which display text support the following styles:
 
 All dimensions in Monomer are expressed in pixels.
 
+### Note: Possible compilation issue
+
+When creating a custom widget using a function similar to `titleText`, you may
+run into a compilation issue along the lines of _*"No instance for (Typeable s)
+arising from a use of"*_ (or the same with `e`). This will happen if your
+function uses `box`, `button` or any other widget that generates events,
+especially if the function is written in point free format. For example, this
+will fail unless it's used in the same file where it is declared:
+
+```haskell
+boxedLabel = box . label
+```
+
+The solution in those cases is having a explicit type signature. If you use
+`AppModel` and `AppEvent`, or the corresponding names for your application,
+a type signature similar to the one of `buildUI` is good. For example, this
+will work:
+
+```haskell
+boxedLabel :: Text -> WidgetNode AppModel AppEvent
+boxedLabel = box . label
+```
+
+Sometimes you don't want to tie your utility functions to specific types,
+because you want to reuse them in other parts of the application that may use
+different model/events. In those cases you can return a more general type, as
+long as you satisfy the constraints for the `s` and `e` arguments of
+`WidgetNode` (sometimes, being explicit only about `e` is enough). Monomer
+exports two types (`WidgetModel` and `WidgetEvent`) that are just aliases of
+`Typeable`, but have a more specific name and the extra import for `Typeable` is
+not needed. Extending the previous example, this will work too:
+
+```haskell
+boxedLabel :: (WidgetModel s, WidgetEvent e) => Text -> WidgetNode s e
+boxedLabel = box . label
+```
+
 ## Padding, border and radius
 
 Besides using spacer and filler for having some room between widgets, you can

src/Monomer/Core/WidgetTypes.hs

@@ -322,7 +322,11 @@ data WidgetEnv s e = WidgetEnv {
   _weWindowSize :: Size,
   -- | The active map of shared data.
   _weWidgetShared :: MVar (Map Text WidgetShared),
-  -- | The active map of WidgetKey -> WidgetNode, if any.
+  {-
+  The active map of WidgetKey -> WidgetNode, if any. This map is restricted to
+  to the parent 'Composite'. Do not use this map directly, rely instead on the
+  'widgetIdFromKey', 'nodeInfoFromKey' and 'nodeInfoFromPath' utility functions.
+  -}
   _weWidgetKeyMap :: WidgetKeyMap s e,
   -- | The currently hovered path, if any.
   _weHoveredPath :: Maybe Path,