You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An abstracted util factory for creating declarative and reactive contexts component in Vue. This API abstraction is greatly inspired by [`React.createContexts`](https://reactjs.org/docs/context.html#reactcreatecontext). The usage and its behaviour is exactly the same as you may expect if you already familiar with React. Under the hood, it uses Vue's reactive system with its `provide/inject`and scoped-slot API. It is light weight, declarative, and easy to use.
5
+
An abstracted util factory for creating **scoped**, **declarative**, and **reactive** context-components in Vue. This API abstraction is greatly inspired by [`React.createContext`](https://reactjs.org/docs/context.html) using Vue's [`prvide/inject` API](https://vuejs.org/v2/api/#provide-inject) under the hood. The usage and its behaviour is exactly the same as you may expect if you already familiar with React. With this library to power up your Vue application, you then now able to use `prvide/inject`in an explicit, but declarative manner for managing application contexts using component composition. It's just that easy.
6
6
7
7
## 🧰 Requirements
8
8
9
-
This library requires Vue 2.6+, where Vue introduces the `v-slot` derivative, opening a new declarative pattern for passing component props in a compositional manner.
9
+
This library recommend to have Vue 2.6+, where Vue introduces the `v-slot` derivative, opening a clean declarative pattern for passing component props in a compositional manner.
10
10
11
11
## 🎬 Getting started
12
12
13
13
To get it started, add this package into your project:
14
14
15
15
```bash
16
-
yarn add -D vue-create-context
16
+
yarn add vue-create-context
17
17
```
18
18
19
19
## 📔 API
@@ -25,17 +25,17 @@ import { createContext } from 'vue-create-context';
25
25
constMyContext=createContext(defaultValue);
26
26
```
27
27
28
-
Calling `createContext` with the `defaultValue` to create a context object. The `defaultValue` can be either a reference object or primitive, which is **ONLY** used when the `Consumer` component can not find its paired`Provider` above the rendering tree. The behaviour is the same as the one in React, so you can also have a look at [React.createContext](https://reactjs.org/docs/context.html#reactcreatecontext).
28
+
Calling `createContext` with the `defaultValue` to create a context object. The `defaultValue` can be either a referential object or primitive, which is **ONLY** used when the `Consumer` component can not find its conjugated`Provider` above the rendering tree.
29
29
30
30
### `Context.Provider`
31
31
32
32
```vue
33
-
<MyContext.Provider :value={/* the provided value */}>
33
+
<MyContext.Provider value={/* the provided value */}>
34
34
```
35
35
36
-
The `Provider` accept a `value` prop to be any value you want it to pass down the rendering tree. Similar to React, you can use this component multiple times an any level of the rendering tree. Its conjugated `Consumer` will receive the value from the closest `Provider` among its ancestors.
36
+
The `Provider` accept a `value` prop to be any value you want it to pass down the rendering tree. Similar to React, you can use this component multiple times an any level of the tree. Its conjugated `Consumer` will receive the value from the closest `Provider` among its ancestors.
37
37
38
-
Note: If the provided value is reactive, update this value "reactively" will also update all its subscribed descended `Consumers`.
38
+
Note: If the provided value is reactive, update this value "reactively" will also update all its subscribed descended `Consumers`. Also, make the value `undefined` (either explicitly passed in or implicitly set to) **WON'T** letting `Consumer` to use the `defaultValue`, which is the same as in React.
39
39
40
40
### `Context.Consumer`
41
41
@@ -45,48 +45,86 @@ Note: If the provided value is reactive, update this value "reactively" will als
45
45
</MyContext.Consumer>
46
46
```
47
47
48
-
The `Consumer` gives the access to the injected value from the closest `Provider`. Unlike React, where uses the CAAF (children as a function, also known as the "render prop") pattern to access the value, we uses `v-slot` inside the component block template to access the value (the so called "slot props"). If you uses single file component (SFC) or browsers supports ES6+ object spread operator, you can take the advantage of object destructuring (see more on [Vue's official page](https://vuejs.org/v2/guide/components-slots.html#Destructuring-Slot-Props)).
48
+
The `Consumer` gives the access to the injected value from the closest `Provider`. Unlike React, where uses the CAAF (children as a function, also known as the "render prop") pattern to access the value, we uses `v-slot` inside the component block template to access the value (the so called "slot props"). If you uses single file component (SFC) or browsers supports ES6+ object spread operator, you can take the advantage of object destructuring (see more on [Vue's official documentation](https://vuejs.org/v2/guide/components-slots.html#Destructuring-Slot-Props)).
49
49
50
-
It is worth to mention that due to the current limitation of Vue's scoped slot API, the slot props have to be an object, so it is recommended to give the value as an plan old javascript object (POJO). In the case of the provided value to be a primitive, it will be normalized as an object with a `value` key to get the passed value in `v-slot`, i.e. `{ value: /* your provided value */ }`.
50
+
It is worth to mention that due to the current implementation of Vue's scoped slot API, the slot props have to be an object, so it is recommended to give the value as an plan old javascript object (POJO). In the case of the provided value to be a primitive, it will be normalized as an object with a `value` key to get the passed value in `v-slot`, i.e. `{ value: /* your provided value */ }`.
51
51
52
-
Note. You might be tempted to mutate the injected value from the consumer. This is a bad idea since it violate the "[props down event up principle](https://vuejs.org/v2/style-guide/#Implicit-parent-child-communication-use-with-caution)". Under the hood, the library leverage the `computed` property in the `Consumer`, and you would not able to update/mutate on the source value. This is also consistent with the behaviour of Vue's`provide/inject` API.
52
+
Note. You might be tempted to mutate the injected value from the consumer block. This is generally a bad idea since it violate the principle of "[props down, event up](https://vuejs.org/v2/style-guide/#Implicit-parent-child-communication-use-with-caution)"; therefore, it is recommend to treat the slot props as read only properties. Under the hood, this reactivity behaviour of slot props is just a reflection of the`provide/inject` API.
53
53
54
54
## 💎 Example
55
55
56
-
There is an example in [the Official Storybook Vue](https://storybooks-vue.netlify.com/?path=/story/addon-contexts--languages) as an example of the `createContexts`.
56
+
There is a story in [the Official Storybook Vue](https://monorepo-git-add-addon-contextsvue-i.storybook.now.sh/examples/vue-kitchen-sink/?path=/story/addon-contexts--languages) as an example of the `createContexts`.
57
57
58
-
For people using the SFC format, here is an conceptual example:
58
+
For people using the SFC format, here is an conceptual example.
0 commit comments