From 5e9158e54dbb66ec45b12c1253d8f27a3c260e75 Mon Sep 17 00:00:00 2001 From: Brian Kim Date: Tue, 21 Jul 2020 00:27:05 -0400 Subject: [PATCH] update guides on provisions --- website/guides/08-reusable-logic.md | 10 +++++----- website/guides/09-working-with-typescript.md | 2 +- website/guides/11-reference-for-react-developers.md | 2 +- website/guides/12-api-reference.md | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/website/guides/08-reusable-logic.md b/website/guides/08-reusable-logic.md index 0b05db7e6..2c7c2562c 100644 --- a/website/guides/08-reusable-logic.md +++ b/website/guides/08-reusable-logic.md @@ -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

{greeting}, {name}

; } @@ -51,9 +51,9 @@ console.log(document.body); // "

Hello, Brian

" 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. diff --git a/website/guides/09-working-with-typescript.md b/website/guides/09-working-with-typescript.md index 5d0471cfd..1a1cef92a 100644 --- a/website/guides/09-working-with-typescript.md +++ b/website/guides/09-working-with-typescript.md @@ -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. diff --git a/website/guides/11-reference-for-react-developers.md b/website/guides/11-reference-for-react-developers.md index d45c2a73d..4414d8c06 100644 --- a/website/guides/11-reference-for-react-developers.md +++ b/website/guides/11-reference-for-react-developers.md @@ -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. diff --git a/website/guides/12-api-reference.md b/website/guides/12-api-reference.md index b4bbfb5ed..ceed22f2b 100644 --- a/website/guides/12-api-reference.md +++ b/website/guides/12-api-reference.md @@ -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 @@ -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. @@ -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.