promise-portal 1.0.1 → 1.0.3

package/README.md

@@ -24,7 +24,7 @@ yarn add promise-portal --D
 import { createPromisePortal } from 'promise-portal'
 
 const app = createApp(App)
-app.use(createVuePortal())
+app.use(createPromisePortal())
 ```
 
 ### in component, use `usePortalContext` to get portal context
@@ -56,7 +56,120 @@ const onClick = async () => {
 }
 ```
 
-## Reference
+## API Reference
+
+- createPromisePortal
+
+  create promise-portal instance
+
+  ```ts
+  const instance = createPromisePortal()
+  app.use(instance) // vue instance
+  ```
+
+- getActiveInstance
+
+  get active promise-portal instance
+
+  ```ts
+  const instance = getActiveInstance()
+  ```
+
+- setActiveInstance
+
+  set promise-portal instance to be active
+
+  ```ts
+  setActiveInstance(instance)
+  ```
+
+- usePortalContext
+
+  a vue composition api, use in portal component to get context of portal
+
+  ```ts
+  const { resolve, reject, el, vNode } = usePortalContext()
+  // resolve: promise resolve handler
+  // reject: promise reject handler
+  // el: portal base element, injecting to body element
+  // vNode: portal base vue vnode
+  ```
+
+  you can use typescript generic types
+
+  ```ts
+  const { resolve } = usePortalContext<Output>()
+  resolve({ ... })    // an object of type Output
+  ```
+
+- definePortal
+
+  define a portal, return a portal function
+
+  ```ts
+  import Comp from './component.vue'
+  const portal = definePortal(Comp)
+  portal() // return a promise
+  ```
+
+  you can define generic types to check input object and output object
+
+  ```ts
+  // component.vue
+  export interface Input {
+    firstName: string
+    lastName: string
+  }
+
+  export interface Output {
+    fullName: string
+    confirm: boolean
+  }
+
+  const props = defineProps<Input>()
+  const { resolve } = usePortalContext<Output>()
+
+  // App.vue
+  import Comp, { Input, Output } from './component.vue'
+  const portal = definePortal<Output, Input>(Comp)
+  const output = await portal({
+    firstName: 'joe',
+    lastName: 'watson',
+  })
+  ```
+
+  how to define a portal with empty parameter
+
+  ```ts
+  // component.vue
+  export interface Output {
+    fullName: string
+    confirm: boolean
+  }
+
+  const { resolve } = usePortalContext<Output>()
+
+  // App.vue
+  import Comp, { Output } from './component.vue'
+  const portal = definePortal<Output, void>(Comp)
+  const output = await portal() // only allow empty parameter
+  ```
+
+  you can set a config to definePortal
+
+  ```ts
+  definePortal(Comp, {
+    // set a time gap before portal unmount,
+    // in general, it to wait for animation effect
+    unmountDelay: 1000,
+    // set promise-portal instance explicitly to render this portal
+    // not use the active instance internally
+    // of course, you can use `setActiveInstance` to set active instance
+    instance: promisePortalInstance,
+  })
+  ```
+
+## Link
 
 [@filez/portal](https://github.com/lenovo-filez/portal)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promise-portal",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "a vite plugin to load svg icon for element-plus",
   "type": "module",
   "main": "dist/index.cjs",
@@ -39,6 +39,7 @@
   "license": "MIT",
   "keywords": [
     "vue",
+    "promise",
     "portal"
   ],
   "scripts": {