Merge 7fae0de into d9b7f96

docs/advanced/context.md

@@ -1,5 +1,21 @@
-!!! warning
-	Context is an unstable feature that's being *significantly* revised. See [issue #4](https://github.com/Roblox/roact/issues/4) for current progress.
+!!! danger "Unreleased API"
+	This API is not yet available in a stable Roact release.
 
-!!! info
-	This section is incomplete. It's possible that the context API will change before the existing API is ever documented.
+	It may be available from a recent pre-release or Roact's master branch.
+
+[TOC]
+
+Roact supports a feature known as context that helps pass values down the tree without having to pass them through props.
+
+## Basic Usage
+Context is defined by creating a pair of components known as the _Provider_ and the _Consumer_. Roact does this for you with the `Roact.createContext()` API:
+
+```lua
+local MyValueContext = Roact.createContext()
+```
+
+## Example: Theming
+
+
+## Legacy Context
+Roact also has a deprecated version of context that pre-dates the stable context API. It will be removed in a future release, but is currently maintained for backwards-compatibility.

docs/api-reference.md

@@ -17,7 +17,8 @@ The `children` argument is shorthand for adding a `Roact.Children` key to `props
 ---
 
 ### Roact.createFragment
-<div class="api-addition">Added in 1.0.0</div>
+
+!!! success "Added in Roact 1.0.0"
 
 ```
 Roact.createFragment(elements) -> RoactFragment
@@ -84,7 +85,8 @@ If `children` is `nil` or contains no children, `oneChild` will return `nil`.
 ---
 
 ### Roact.createBinding
-<div class="api-addition">Added in 1.0.0</div>
+
+!!! success "Added in Roact 1.0.0"
 
 ```
 Roact.createBinding(initialValue) -> Binding, updateFunction
@@ -118,7 +120,8 @@ Returns a new binding that maps the existing binding's value to something else.
 ---
 
 ### Roact.joinBindings
-<div class="api-addition">Added in 1.1.0</div>
+
+!!! success "Added in Roact 1.1.0"
 
 ```
 Roact.joinBindings(bindings) -> Binding
@@ -176,6 +179,39 @@ Creates a new reference object that can be used with [Roact.Ref](#roactref).
 
 ---
 
+### Roact.createContext
+
+!!! danger "Unreleased API"
+	This API is not yet available in a stable Roact release.
+
+	It may be available from a recent pre-release or Roact's master branch.
+
+```
+Roact.createContext(defaultValue: any) -> { Provider, Consumer }
+```
+
+Creates a new context provider and consumer. For a usage guide, see [Advanced Concepts: Context](/advanced/context).
+
+`defaultValue` is given to consumers if they have no `Provider` ancestors. It is up to consumers of Roact's context API to turn this case into an error if it is an invalid state.
+
+`Provider` and `Consumer` are both Roact components.
+
+#### `Provider`
+`Provider` accepts the following props:
+
+* `value`: The value to put into the tree for this context value.
+	* If the `Provider` is updated with a new `value`, any matching `Consumer` components will be re-rendered with the new value.
+* `[Children]`: Any number of children to render underneath this provider.
+	* Descendants of this component can receiver the provided context value by using `Consumer`.
+
+#### `Consumer`
+`Consumer` accepts just one prop:
+
+* `render(value) -> RoactElement | nil`: A function that will be invoked to render any children.
+	* `render` will be called every time `Consumer` is rendered.
+
+---
+
 ### Roact.setGlobalConfig
 ```
 Roact.setGlobalConfig(configValues: Dictionary<string, bool>) -> void
@@ -503,7 +539,8 @@ By default, components are re-rendered any time a parent component updates, or w
 ---
 
 ### validateProps
-<div class="api-addition">Added in 1.0.0</div>
+
+!!! success "Added in Roact 1.0.0"
 
 ```
 static validateProps(props) -> (false, message: string) | true
@@ -523,6 +560,9 @@ Roact.setGlobalConfig({
 
 See [setGlobalConfig](#roactsetglobalconfig) for more details.
 
+!!! note
+	`validateProps` is a *static* lifecycle method. It does not have access to `self`, and must be a pure function.
+
 !!! warning
 	Depending on the implementation, `validateProps` can impact performance. Recommended practice is to enable prop validation during development and leave it off in production environments.
 

docs/extra.css

@@ -1,28 +1,3 @@
-.api-addition {
-	display: flex;
-	align-content: center;
-	align-items: center;
-	vertical-align: middle;
-
-	padding: 0.4rem 0.6rem 0.4rem 0.5rem;
-	background-color: #efffec;
-	border-left: 0.2rem solid green;
-	border-radius: 0.1rem;
-
-	line-height: 1;
-	font-size: 0.64rem;
-	font-weight: bold;
-
-	box-shadow:
-		0 2px 2px 0 rgba(0,0,0,.14),
-		0 1px 5px 0 rgba(0,0,0,.12),
-		0 3px 1px -2px rgba(0,0,0,.2);
-}
-
-.api-addition::before {
-	flex: 0 0 1.5rem;
-	content: "+";
-	color: green;
-	font-size: 1.5em;
-	text-align: center;
+.md-typeset hr {
+	border-bottom: 2px solid rgba(0, 0, 0, 0.15);
 }