Skip to content

Commit

Permalink
update guides on provisions
Browse files Browse the repository at this point in the history
  • Loading branch information
brainkim committed Jul 21, 2020
1 parent 4a5e77f commit 5e9158e
Show file tree
Hide file tree
Showing 4 changed files with 10 additions and 10 deletions.
10 changes: 5 additions & 5 deletions website/guides/08-reusable-logic.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,16 @@ Depending on the state of the component, the accessed value can be an node, a st
### Provisions
**Warning:** This API is more unstable than others, and the method names and behavior of components which use this method may change.

Crank allows you to provide data to all of a component’s descendants via the methods `get` and `set`. The `set` method sets a “provision” under a specific key, and the `get` method retrieves the value set under a specific key by the nearest ancestor.
Crank allows you to provide data to all of a component’s descendants via the methods `provide` and `consume`. The `provide` method sets a “provision” under a specific key, and the `consume` method retrieves the value set under a specific key by the nearest ancestor.

```ts
function GreetingProvider({greeting, children}) {
this.set("greeting", greeting);
this.provide("greeting", greeting);
return children;
}

function Greeting({name}) {
const greeting = this.get("greeting");
const greeting = this.consume("greeting");
return <p>{greeting}, {name}</p>;
}

Expand All @@ -51,9 +51,9 @@ console.log(document.body); // "<div><p>Hello, Brian</p></div>"

Provisions allow libraries to define components which interact with their descendants without rigidly defined component hierarchies or requiring the developer to pass data manually between components as props. This makes them useful, for instance, when writing multiple components which communicate with each other, like custom `select` and `option` form elements, or drag-and-drop components.

Anything can be passed as a key to the `get` and `set` methods, so you can use a symbol to ensure that the provision you pass between your components are private and do not collide with provisions set by others.
Anything can be passed as a key to the `provide` and `consume` methods, so you can use a symbol to ensure that the provision you pass between your components are private and do not collide with provisions set by others.

**Note:** Crank does not link “providers” and “consumers” in any way, and doesn’t automatically refresh consumer components when `set` is called, so it’s up to you to make sure consumers update when providers update.
**Note:** Crank does not link “providers” and “consumers” in any way, and doesn’t automatically refresh consumer components when `provide` is called, so it’s up to you to make sure consumers update when providers update.

### `context.schedule`
You can pass a callback to the `schedule` method to listen for when the component renders. Callbacks passed to `schedule` fire synchronously after the component commits, with the rendered value of the component as its only parameter. They only fire once per call and callback function (think `requestAnimationFrame`, not `setInterval`). This means you have to continuously call the `schedule` method for each update if you want to execute some code every time your component commits.
Expand Down
2 changes: 1 addition & 1 deletion website/guides/09-working-with-typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,4 +123,4 @@ function MyButton (props) {
```

## Typing Provisions
By default, calls to `Context.prototype.get` and `Context.prototype.set` will be loosely typed. If you want stricter typings of these methods, you can use module augmentation to extend the `ProvisionMap` interface provided by Crank.
By default, calls to the context’s `provide` and `consume` methods will be loosely typed. If you want stricter typings of these methods, you can use module augmentation to extend the `ProvisionMap` interface provided by Crank.
2 changes: 1 addition & 1 deletion website/guides/11-reference-for-react-developers.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,4 +139,4 @@ Crank provides the callback-style ref API from React via the `crank-ref` prop. U
You can also access values many other ways. See the [guide on accessing rendered values](./lifecycles#accessing-rendered-values) for more information.

## React Contexts
Because we refer to the `this` keyword of components as “the component’s context” (“controller” would have been three more characters), we refer to the equivalent concept of [React’s Context API](https://reactjs.org/docs/context.html) as “provisions” instead. We use the methods `get` and `set` to define provisions between components. See [the guide on provisions](./reusable-logic#provisions) for more information.
Because we refer to the `this` keyword of components as “the component’s context” (“controller” would have been three more characters), we refer to the equivalent concept of [React’s Context API](https://reactjs.org/docs/context.html) as “provisions” instead. We use the context methods `provide` and `consume` to define provisions between ancestor and descendant components. See [the guide on provisions](./reusable-logic#provisions) for more information.
6 changes: 3 additions & 3 deletions website/guides/12-api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ declare global {

### `ProvisionMap`

An interface which can be extended to provide strongly typed provisions. See `Context.prototype.get` and `Context.prototype.set`.
An interface which can be extended to provide strongly typed provisions. See `Context.prototype.provide` and `Context.prototype.consume`.

**Example:**
```ts
Expand Down Expand Up @@ -319,7 +319,7 @@ Dispatches an event on the context. Will propagate to parent contexts according

The return value is `false` if the event is cancelable and an event listener calls the `preventDefault` method on the event, and `true` otherwise.

#### `get`
#### `consume`

Retrieves a provision set by an ancestor by key.

Expand All @@ -330,7 +330,7 @@ Retrieves a provision set by an ancestor by key.

The provision by key, or undefined if no provision is found.

#### `set`
#### `provide`

Sets a provision by key for descendant components.

Expand Down

0 comments on commit 5e9158e

Please sign in to comment.