#0: release v1.1.0

Author: Leo Y. Li

CHANGELOG.md

@@ -5,7 +5,18 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ---
 
-## [1.0.2] - 2019-04-26
+## [1.1.0] - 2019-04-28
+
+## Feature
+
+- Expose `._context` object for manual `inject` binding without the `Consumer` component.
+
+## Documentation
+
+- Update API documentation and add library highlights.
+
+
+## [1.0.2] - 2019-04-27
 
 ## Documentation
 

README.md

@@ -4,9 +4,17 @@
 
 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.
 
+## ✨ Highlights
+
+- Solve **prop-drilling** without the full state management solution; good for library development.
+- Declarative, reusable, but explicit, you know where your data came from and how to access it.
+- Easier to debug, just search `Context.Provider` in the devTool then you know where data get injected.
+- Free from name clash, there are just no chance to mess up `provide/inject`. Zero overhead!
+- Seamless developing experiences for people came from React.
+
 ## 🧰 Requirements
 
-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.
+This library recommend to have Vue 2.6+, so we can leverage the `v-slot` derivative to write readable code.
 
 ## 🎬 Getting started
 
@@ -18,11 +26,14 @@ yarn add vue-create-context
 
 ## 📔 API
 
+It is recommended to read [React context doc](https://reactjs.org/docs/context.html) to have a better idea on the API design. The doc here will just focus on the usage and the difference in Vue.
+
 ### `createContext`
 
 ```js
-import { createContext } from 'vue-create-context';
-const MyContext = createContext(defaultValue);
+import { createContext } from 'vue-create-context'
+
+const MyContext = createContext(defaultValue)
 ```
 
 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.
@@ -41,18 +52,34 @@ Note: If the provided value is reactive, update this value "reactively" will als
 
 ```vue
 <MyContext.Consumer v-slot="/* slot props: the value injected by the closed Provider */">
-  /* you can access the value within the block */
-  /* note: as a normal renderless component, this block have no access to computed properties */
+  <!-- you can access the value within the block -->
 </MyContext.Consumer>
 ```
 
-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)).
+The `Consumer` is a _functional_ component 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)).
 
-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 */ }`.
+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` property to get the passed value in `v-slot`, i.e. `{ value: /* your provided value */ }`.
 
 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.
 
-⚠️ **Caveat**: After chat with Vue's core team member @linusborg in Discord, the current constrain limits the template inside `Consumer` block have no access to the computed properties, but it can access to state value defined in `data` though.  Please use it with caution!
+### `Context._context`
+
+Internally, calling `createContext` will generate an unique identifier as a key to access the inject value at runtime, that is why there are no such chance to have clashes. But if you need the injected value to be used in `computed` property, then you manually have to setup `inject` property on the component instance (thanks to Vue's core team member @linusborg for pointing out this). For such usage, you can bind the injected context as the following:
+
+```js
+{
+  inject: {
+    [name]: MyContext._context,
+  },
+  computed: {
+    [something]() {
+      return this[name]() // please note 'this[name]' is a accessor function with reactivity.
+    },
+  },
+}
+```
+
+Node: the bound property is a **function** that returns the injected value, which follows the same rule as in `Consumer`. You can still expect to receive the `defaultValue` in case have no `Provider` being traced.
 
 ## 💎 Example
 
@@ -64,6 +91,7 @@ For people using the SFC format, here is an conceptual example.
 
 ```js
 import { createContext } from 'vue-create-context';
+
 export const CurrentUserContext = createContext({ firstName: 'Null', lastName: 'Unknown' });
 ```
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vue-create-context",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "An abstracted util factory for creating scoped, declarative, and reactive context-components in Vue.",
   "keywords": [
     "vue"

src/index.ts

@@ -3,13 +3,19 @@ import { Component } from 'vue';
 type createContext = (defaultValue: unknown) => { Provider: Component; Consumer: Component };
 
 export const createContext: createContext = (defaultValue) => {
-  const key = `_${Date.now()}${Math.random()}`;
+  const _key = `_${Date.now()}${Math.random()}`;
+  const _context = {
+    from: _key,
+    default: () => () =>
+      defaultValue instanceof Object ? { ...defaultValue } : { value: defaultValue },
+  };
+
   return {
     Provider: {
       name: 'Context.Provider',
       props: ['value'],
       provide(this: any) {
-        return { [key]: () => this.value };
+        return { [_key]: () => this.value };
       },
       render(this: any) {
         return this.$slots.default;
@@ -19,13 +25,10 @@ export const createContext: createContext = (defaultValue) => {
       name: 'Context.Consumer',
       functional: true,
       inject: {
-        value: {
-          from: key,
-          default: () => () =>
-            defaultValue instanceof Object ? { ...defaultValue } : { value: defaultValue },
-        },
+        value: _context,
       },
       render: (h, contexts: any) => contexts.scopedSlots.default(contexts.injections.value()),
     },
+    _context,
   };
 };