promise-portal 1.0.0 → 1.0.2

package/README.md

@@ -1,5 +1,7 @@
 # promise-portal
 
+let you use react portal in vue, and with promise
+
 ## Install
 
 ```bash
@@ -15,7 +17,145 @@ yarn add promise-portal --D
 
 ## Use
 
-## Reference
+### install in the entry file
+
+```ts
+// ./main.ts
+import { createPromisePortal } from 'promise-portal'
+
+const app = createApp(App)
+app.use(createPromisePortal())
+```
+
+### in component, use `usePortalContext` to get portal context
+
+```ts
+// ./components/name.vue
+import { usePortalContext } from 'promise-portal'
+
+const { resolve } = usePortalContext<Output>()
+const onClose = () => {
+  resolve({ confirm: false, fullName: '' })
+}
+```
+
+### define portal, use it like a promise-style function
+
+```ts
+// ./App.vue
+import { definePortal } from 'promise-portal'
+import Comp, { Input, Output } from './components/name.vue'
+
+const func = definePortal<Output, Input>(Comp)
+const onClick = async () => {
+  const data = await func({ firstName: 'joe', lastName: 'watson' })
+  if (!data.confirm) {
+    return
+  }
+  console.log(data)
+}
+```
+
+## 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
+  ```
+
+## Link
 
 [@filez/portal](https://github.com/lenovo-filez/portal)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promise-portal",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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": {