promise-portal

use component as a promisd-like function

Installation

1// pnpm
2pnpm add promise-portal
3
4// npm
5npm install promise-portal
6
7// yarn
8yarn add promise-portal

Online Demo

https://codesandbox.io/p/github/tjyuanpeng/promise-portal

Motivation

like element-plus, the modal is a vue component

in development, we want use modal like a function

no show property to control show/hide, gettting result is more explicit

easier to control workflow, and easier to handle life-cycles

so you can use Promise-Portal to save your life-time

before

use as a component, with ref value to control visibility and life-cycles

1<script setup lang="ts">
2import Comp from './components/name.vue'
3const show = ref(false)
4const onClick = () => {
5  show.value = true
6}
7const onClosed = () => {
8  show.value = false
9}
10</script>
11<template>
12  <el-button @click="onClick"> click to open the Dialog </el-button>
13  <Comp v-model="show" @closed="onClosed"> a dialog content </Comp>
14</template>

after

use as a normal promise-style function, so happy to develop

1<script setup lang="ts">
2import Comp from './components/name.vue'
3const func = definePortal(Comp)
4const onClick = async () => {
5  const data = await func()
6  console.log(data)
7}
8</script>
9<template>
10  <el-button @click="onClick"> open the Dialog </el-button>
11</template>

Use Case

create promise-portal instance in the entry file

1// ./main.ts
2import { createApp } from 'vue'
3import { createPromisePortal } from 'promise-portal'
4
5const app = createApp(App)
6app.use(
7  createPromisePortal({
8    unmountDelay: 200,
9  })
10)

use ContextProvider to set context globally

1<!-- ./App.vue -->
2<script setup lang="ts">
3import locale from 'ant-design-vue/es/locale/zh_CN'
4import { ContextProvider } from 'promise-portal'
5</script>
6<template>
7  <a-config-provider :locale="locale">
8    <ContextProvider>
9      <router-view></router-view>
10    </ContextProvider>
11  </a-config-provider>
12</template>

in component, use usePortalContext to use portal context

1<!-- ./components/comp.vue -->
2<script setup lang="ts">
3import { usePortalContext } from 'promise-portal'
4export interface Output {
5  confirm: boolean
6}
7export interface Output {
8  input: string
9}
10const props = defineProps<Input>()
11const { resolve, show } = usePortalContext<Output>()
12const onCancel = () => {
13  resolve({ confirm: false })
14}
15</script>
16<template>
17  <a-modal v-model:open="show" @cancel="resolve">{{ props.input }}</a-modal>
18</template>

define portal in anywhere, then use it like a promise-style function

1// ./App.vue
2import { definePortal } from 'promise-portal'
3import Comp, { Input, Output } from './components/comp.vue'
4const [func] = definePortal<Output, Input>(Comp)
5const onClick = async () => {
6  const result = await func({
7    input: 'foo',
8  })
9  console.log(result)
10}

API Reference

createPromisePortal

create promise-portal instance, set to vue instance

1const instance = createPromisePortal()
2app.use(instance)

you can set default options to instance

1const instance = createPromisePortal({
2  // set a time gap before portal unmount,
3  // in general, it is to wait for animation effect
4  unmountDelay: 200,
5
6  // initial value to property show, default value is true
7  initialShowValue: true,
8})

getActiveInstance

get active promise-portal instance

1const instance = getActiveInstance()

setActiveInstance

set active promise-portal instance

1setActiveInstance(instance)

ContextProvider

a component to set context globally

1<script setup lang="ts">
2import locale from 'ant-design-vue/es/locale/zh_CN'
3import { ContextProvider } from 'promise-portal'
4</script>
5<template>
6  <a-config-provider :locale="locale">
7    <ContextProvider>
8      <router-view></router-view>
9    </ContextProvider>
10  </a-config-provider>
11</template>

usePortalContext

a vue composition api, use in portal component to get context of portal

1const { resolve } = usePortalContext()
2
3// detail
4const {
5  resolve, // promise resolve handler
6  reject, // promise reject handler
7  el, // portal base element, injecting to body element
8  vnode, // portal base vue vnode
9  setUnmountDelay, // set delay to unmount
10  show, // a ref value to use in modal component
11} = usePortalContext({
12  // set a time gap before portal unmount,
13  // in general, it is to wait for animation effect
14  unmountDelay: 200,
15
16  // initial value to property show above, default value is true
17  initialShowValue: true,
18})

you can use typescript generic types to promise fulfilled result

1export interface Output {
2  confirm: boolean
3}
4const { resolve } = usePortalContext<Output>()
5resolve({
6  confirm: true,
7})

you can use show to control modal component

before unmount, show.value = false will be setted

use initialShowValue to set inital value, default inital value is true

1<script setup lang="ts">
2const { resolve, show } = usePortalContext<Output>({ initialShowValue: true })
3</script>
4<template>
5  <a-modal v-model:open="show" @cancel="resolve"></a-modal>
6</template>

definePortal

define a portal, return a portal function

1import Comp from './component.vue'
2const portalFunc = definePortal(Comp)
3portalFunc()

you can define generic types to check input object and output object

1// component.vue
2export interface Input {
3  firstName: string
4  lastName: string
5}
6
7export interface Output {
8  fullName: string
9  confirm: boolean
10}
11
12const props = defineProps<Input>()
13const { resolve } = usePortalContext<Output>()
14
15// App.vue
16import Comp, { Input, Output } from './component.vue'
17const portal = definePortal<Output, Input>(Comp)
18const output = await portal({
19  firstName: 'joe',
20  lastName: 'watson',
21})

define a portal with empty parameter

1// component.vue
2export interface Output {
3  fullName: string
4  confirm: boolean
5}
6
7const { resolve } = usePortalContext<Output>()
8
9// App.vue
10import Comp, { Output } from './component.vue'
11const portal = definePortal<Output, void>(Comp)
12const output = await portal() // only allow empty parameter

you can set a options to definePortal

1definePortal(Comp, {
2  // set a time gap before portal unmount,
3  unmountDelay: 200,
4
5  // initial value to property show
6  initialShowValue: true,
7
8  // set promise-portal instance explicitly to render this portal
9  instance: promisePortalInstance,
10})

detectPromisePortalInstance

detect whether the instance has been properly destroyed

1// main.ts
2if (import.meta.env.DEV) {
3  detectPromisePortalInstance()
4}

the return value is a function to stop detecting

1const stopHandler = detectPromisePortalInstance()
2stopHandler() // stop detecting

You can pass in other values to customize it.

1detectPromisePortalInstance({
2  text: 'Detected unreleased promise-portal instance',
3  style: ' /styles you like/ ',
4})

Relative Resourece

• react protal
• vue teleport
• @filez/portal
• promise-modal