refactor: rename <portal> to <teleport>

BREAKING CHANGE: `<portal>` has been renamed to `<teleport>`. `target` prop is also renmaed to `to`, so the new usage will be: ```html <Teleport to="#modal-layer" :disabled="isMobile"> <div class="modal"> hello </div> </Teleport> ``` The primary reason for the renaming is to avoid potential naming conflict with [native portals](https://wicg.github.io/portals/).
2020-03-31 10:52:42 -04:00
parent 8080c38323
commit eee5095692
26 changed files with 290 additions and 283 deletions
--- a/packages/runtime-core/src/apiOptions.ts
+++ b/packages/runtime-core/src/apiOptions.ts
@@ -88,7 +88,7 @@ export interface ComponentOptionsBase<
  call?: never
  // type-only differentiators for built-in Vnode types
  __isFragment?: never
-  __isPortal?: never
+  __isTeleport?: never
  __isSuspense?: never
 }

--- a/packages/runtime-core/src/components/Teleport.ts
+++ b/packages/runtime-core/src/components/Teleport.ts
@@ -11,26 +11,26 @@ import { VNode, VNodeArrayChildren, VNodeProps } from '../vnode'
 import { isString, ShapeFlags } from '@vue/shared'
 import { warn } from '../warning'

-export interface PortalProps {
-  target: string | RendererElement
+export interface TeleportProps {
+  to: string | RendererElement
  disabled?: boolean
 }

-export const isPortal = (type: any): boolean => type.__isPortal
+export const isTeleport = (type: any): boolean => type.__isTeleport

-const isPortalDisabled = (props: VNode['props']): boolean =>
+const isTeleportDisabled = (props: VNode['props']): boolean =>
  props && (props.disabled || props.disabled === '')

 const resolveTarget = <T = RendererElement>(
-  props: PortalProps | null,
+  props: TeleportProps | null,
  select: RendererOptions['querySelector']
 ): T | null => {
-  const targetSelector = props && props.target
+  const targetSelector = props && props.to
  if (isString(targetSelector)) {
    if (!select) {
      __DEV__ &&
        warn(
-          `Current renderer does not support string target for Portals. ` +
+          `Current renderer does not support string target for Teleports. ` +
            `(missing querySelector renderer option)`
        )
      return null
@@ -39,21 +39,21 @@ const resolveTarget = <T = RendererElement>(
      if (!target) {
        __DEV__ &&
          warn(
-            `Failed to locate Portal target with selector "${targetSelector}".`
+            `Failed to locate Teleport target with selector "${targetSelector}".`
          )
      }
      return target as any
    }
  } else {
    if (__DEV__ && !targetSelector) {
-      warn(`Invalid Portal target: ${targetSelector}`)
+      warn(`Invalid Teleport target: ${targetSelector}`)
    }
    return targetSelector as any
  }
 }

-export const PortalImpl = {
-  __isPortal: true,
+export const TeleportImpl = {
+  __isTeleport: true,
  process(
    n1: VNode | null,
    n2: VNode,
@@ -72,32 +72,32 @@ export const PortalImpl = {
      o: { insert, querySelector, createText, createComment }
    } = internals

-    const disabled = isPortalDisabled(n2.props)
+    const disabled = isTeleportDisabled(n2.props)
    const { shapeFlag, children } = n2
    if (n1 == null) {
      // insert anchors in the main view
      const placeholder = (n2.el = __DEV__
-        ? createComment('portal start')
+        ? createComment('teleport start')
        : createText(''))
      const mainAnchor = (n2.anchor = __DEV__
-        ? createComment('portal end')
+        ? createComment('teleport end')
        : createText(''))
      insert(placeholder, container, anchor)
      insert(mainAnchor, container, anchor)

      const target = (n2.target = resolveTarget(
-        n2.props as PortalProps,
+        n2.props as TeleportProps,
        querySelector
      ))
      const targetAnchor = (n2.targetAnchor = createText(''))
      if (target) {
        insert(targetAnchor, target)
      } else if (__DEV__) {
-        warn('Invalid Portal target on mount:', target, `(${typeof target})`)
+        warn('Invalid Teleport target on mount:', target, `(${typeof target})`)
      }

      const mount = (container: RendererElement, anchor: RendererNode) => {
-        // Portal *always* has Array children. This is enforced in both the
+        // Teleport *always* has Array children. This is enforced in both the
        // compiler and vnode children normalization.
        if (shapeFlag & ShapeFlags.ARRAY_CHILDREN) {
          mountChildren(
@@ -123,12 +123,12 @@ export const PortalImpl = {
      const mainAnchor = (n2.anchor = n1.anchor)!
      const target = (n2.target = n1.target)!
      const targetAnchor = (n2.targetAnchor = n1.targetAnchor)!
-      const wasDisabled = isPortalDisabled(n1.props)
+      const wasDisabled = isTeleportDisabled(n1.props)
      const currentContainer = wasDisabled ? container : target
      const currentAnchor = wasDisabled ? mainAnchor : targetAnchor

      if (n2.dynamicChildren) {
-        // fast path when the portal happens to be a block root
+        // fast path when the teleport happens to be a block root
        patchBlockChildren(
          n1.dynamicChildren!,
          n2.dynamicChildren,
@@ -153,45 +153,45 @@ export const PortalImpl = {
        if (!wasDisabled) {
          // enabled -> disabled
          // move into main container
-          movePortal(
+          moveTeleport(
            n2,
            container,
            mainAnchor,
            internals,
-            PortalMoveTypes.TOGGLE
+            TeleportMoveTypes.TOGGLE
          )
        }
      } else {
        // target changed
-        if ((n2.props && n2.props.target) !== (n1.props && n1.props.target)) {
+        if ((n2.props && n2.props.to) !== (n1.props && n1.props.to)) {
          const nextTarget = (n2.target = resolveTarget(
-            n2.props as PortalProps,
+            n2.props as TeleportProps,
            querySelector
          ))
          if (nextTarget) {
-            movePortal(
+            moveTeleport(
              n2,
              nextTarget,
              null,
              internals,
-              PortalMoveTypes.TARGET_CHANGE
+              TeleportMoveTypes.TARGET_CHANGE
            )
          } else if (__DEV__) {
            warn(
-              'Invalid Portal target on update:',
+              'Invalid Teleport target on update:',
              target,
              `(${typeof target})`
            )
          }
        } else if (wasDisabled) {
          // disabled -> enabled
-          // move into portal target
-          movePortal(
+          // move into teleport target
+          moveTeleport(
            n2,
            target,
            targetAnchor,
            internals,
-            PortalMoveTypes.TOGGLE
+            TeleportMoveTypes.TOGGLE
          )
        }
      }
@@ -211,38 +211,38 @@ export const PortalImpl = {
    }
  },

-  move: movePortal,
-  hydrate: hydratePortal
+  move: moveTeleport,
+  hydrate: hydrateTeleport
 }

-export const enum PortalMoveTypes {
+export const enum TeleportMoveTypes {
  TARGET_CHANGE,
  TOGGLE, // enable / disable
  REORDER // moved in the main view
 }

-function movePortal(
+function moveTeleport(
  vnode: VNode,
  container: RendererElement,
  parentAnchor: RendererNode | null,
  { o: { insert }, m: move }: RendererInternals,
-  moveType: PortalMoveTypes = PortalMoveTypes.REORDER
+  moveType: TeleportMoveTypes = TeleportMoveTypes.REORDER
 ) {
  // move target anchor if this is a target change.
-  if (moveType === PortalMoveTypes.TARGET_CHANGE) {
+  if (moveType === TeleportMoveTypes.TARGET_CHANGE) {
    insert(vnode.targetAnchor!, container, parentAnchor)
  }
  const { el, anchor, shapeFlag, children, props } = vnode
-  const isReorder = moveType === PortalMoveTypes.REORDER
+  const isReorder = moveType === TeleportMoveTypes.REORDER
  // move main view anchor if this is a re-order.
  if (isReorder) {
    insert(el!, container, parentAnchor)
  }
-  // if this is a re-order and portal is enabled (content is in target)
+  // if this is a re-order and teleport is enabled (content is in target)
  // do not move children. So the opposite is: only move children if this
-  // is not a reorder, or the portal is disabled
-  if (!isReorder || isPortalDisabled(props)) {
-    // Portal has either Array children or no children.
+  // is not a reorder, or the teleport is disabled
+  if (!isReorder || isTeleportDisabled(props)) {
+    // Teleport has either Array children or no children.
    if (shapeFlag & ShapeFlags.ARRAY_CHILDREN) {
      for (let i = 0; i < (children as VNode[]).length; i++) {
        move(
@@ -260,12 +260,12 @@ function movePortal(
  }
 }

-interface PortalTargetElement extends Element {
-  // last portal target
+interface TeleportTargetElement extends Element {
+  // last teleport target
  _lpa?: Node | null
 }

-function hydratePortal(
+function hydrateTeleport(
  node: Node,
  vnode: VNode,
  parentComponent: ComponentInternalInstance | null,
@@ -284,15 +284,16 @@ function hydratePortal(
  ) => Node | null
 ): Node | null {
  const target = (vnode.target = resolveTarget<Element>(
-    vnode.props as PortalProps,
+    vnode.props as TeleportProps,
    querySelector
  ))
  if (target) {
-    // if multiple portals rendered to the same target element, we need to
-    // pick up from where the last portal finished instead of the first node
-    const targetNode = (target as PortalTargetElement)._lpa || target.firstChild
+    // if multiple teleports rendered to the same target element, we need to
+    // pick up from where the last teleport finished instead of the first node
+    const targetNode =
+      (target as TeleportTargetElement)._lpa || target.firstChild
    if (vnode.shapeFlag & ShapeFlags.ARRAY_CHILDREN) {
-      if (isPortalDisabled(vnode.props)) {
+      if (isTeleportDisabled(vnode.props)) {
        vnode.anchor = hydrateChildren(
          nextSibling(node),
          vnode,
@@ -313,7 +314,7 @@ function hydratePortal(
          optimized
        )
      }
-      ;(target as PortalTargetElement)._lpa = nextSibling(
+      ;(target as TeleportTargetElement)._lpa = nextSibling(
        vnode.targetAnchor as Node
      )
    }
@@ -322,7 +323,7 @@ function hydratePortal(
 }

 // Force-casted public typing for h and TSX props inference
-export const Portal = (PortalImpl as any) as {
-  __isPortal: true
-  new (): { $props: VNodeProps & PortalProps }
+export const Teleport = (TeleportImpl as any) as {
+  __isTeleport: true
+  new (): { $props: VNodeProps & TeleportProps }
 }
--- a/packages/runtime-core/src/h.ts
+++ b/packages/runtime-core/src/h.ts
@@ -6,7 +6,7 @@ import {
  Fragment,
  isVNode
 } from './vnode'
-import { Portal, PortalProps } from './components/Portal'
+import { Teleport, TeleportProps } from './components/Teleport'
 import { Suspense, SuspenseProps } from './components/Suspense'
 import { isObject, isArray } from '@vue/shared'
 import { RawSlots } from './componentSlots'
@@ -68,7 +68,7 @@ type RawChildren =
 // fake constructor type returned from `defineComponent`
 interface Constructor<P = any> {
  __isFragment?: never
-  __isPortal?: never
+  __isTeleport?: never
  __isSuspense?: never
  new (): { $props: P }
 }
@@ -92,10 +92,10 @@ export function h(
  children?: VNodeArrayChildren
 ): VNode

-// portal (target prop is required)
+// teleport (target prop is required)
 export function h(
-  type: typeof Portal,
-  props: RawProps & PortalProps,
+  type: typeof Teleport,
+  props: RawProps & TeleportProps,
  children: RawChildren
 ): VNode

--- a/packages/runtime-core/src/hydration.ts
+++ b/packages/runtime-core/src/hydration.ts
@@ -18,7 +18,7 @@ import {
  SuspenseBoundary,
  queueEffectWithSuspense
 } from './components/Suspense'
-import { PortalImpl } from './components/Portal'
+import { TeleportImpl } from './components/Teleport'

 export type RootHydrateFunction = (
  vnode: VNode<Node, Element>,
@@ -172,11 +172,11 @@ export function createHydrationFunctions(
          return isFragmentStart
            ? locateClosingAsyncAnchor(node)
            : nextSibling(node)
-        } else if (shapeFlag & ShapeFlags.PORTAL) {
+        } else if (shapeFlag & ShapeFlags.TELEPORT) {
          if (domType !== DOMNodeTypes.COMMENT) {
            return onMismatch()
          }
-          return (vnode.type as typeof PortalImpl).hydrate(
+          return (vnode.type as typeof TeleportImpl).hydrate(
            node,
            vnode,
            parentComponent,
--- a/packages/runtime-core/src/index.ts
+++ b/packages/runtime-core/src/index.ts
@@ -53,7 +53,7 @@ export {
 } from './vnode'
 // Internal Components
 export { Text, Comment, Fragment } from './vnode'
-export { Portal, PortalProps } from './components/Portal'
+export { Teleport, TeleportProps } from './components/Teleport'
 export { Suspense, SuspenseProps } from './components/Suspense'
 export { KeepAlive, KeepAliveProps } from './components/KeepAlive'
 export {
--- a/packages/runtime-core/src/renderer.ts
+++ b/packages/runtime-core/src/renderer.ts
@@ -58,7 +58,7 @@ import {
  queueEffectWithSuspense,
  SuspenseImpl
 } from './components/Suspense'
-import { PortalImpl } from './components/Portal'
+import { TeleportImpl } from './components/Teleport'
 import { KeepAliveSink, isKeepAlive } from './components/KeepAlive'
 import { registerHMR, unregisterHMR } from './hmr'
 import {
@@ -412,8 +412,8 @@ function baseCreateRenderer(
            isSVG,
            optimized
          )
-        } else if (shapeFlag & ShapeFlags.PORTAL) {
-          ;(type as typeof PortalImpl).process(
+        } else if (shapeFlag & ShapeFlags.TELEPORT) {
+          ;(type as typeof TeleportImpl).process(
            n1,
            n2,
            container,
@@ -1207,7 +1207,7 @@ function baseCreateRenderer(
        patch(
          prevTree,
          nextTree,
-          // parent may have changed if it's in a portal
+          // parent may have changed if it's in a teleport
          hostParentNode(prevTree.el!)!,
          // anchor may have changed if it's in a fragment
          getNextHostNode(prevTree),
@@ -1653,8 +1653,8 @@ function baseCreateRenderer(
      return
    }

-    if (shapeFlag & ShapeFlags.PORTAL) {
-      ;(type as typeof PortalImpl).move(vnode, container, anchor, internals)
+    if (shapeFlag & ShapeFlags.TELEPORT) {
+      ;(type as typeof TeleportImpl).move(vnode, container, anchor, internals)
      return
    }

@@ -1739,9 +1739,9 @@ function baseCreateRenderer(
        unmountChildren(children as VNode[], parentComponent, parentSuspense)
      }

-      // an unmounted portal should always remove its children
-      if (shapeFlag & ShapeFlags.PORTAL) {
-        ;(vnode.type as typeof PortalImpl).remove(vnode, internals)
+      // an unmounted teleport should always remove its children
+      if (shapeFlag & ShapeFlags.TELEPORT) {
+        ;(vnode.type as typeof TeleportImpl).remove(vnode, internals)
      }

      if (doRemove) {
--- a/packages/runtime-core/src/vnode.ts
+++ b/packages/runtime-core/src/vnode.ts
@@ -29,7 +29,7 @@ import { DirectiveBinding } from './directives'
 import { TransitionHooks } from './components/BaseTransition'
 import { warn } from './warning'
 import { currentScopeId } from './helpers/scopeId'
-import { PortalImpl, isPortal } from './components/Portal'
+import { TeleportImpl, isTeleport } from './components/Teleport'
 import { currentRenderingInstance } from './componentRenderUtils'
 import { RendererNode, RendererElement } from './renderer'

@@ -50,7 +50,7 @@ export type VNodeTypes =
  | typeof Static
  | typeof Comment
  | typeof Fragment
-  | typeof PortalImpl
+  | typeof TeleportImpl
  | typeof SuspenseImpl

 export type VNodeRef =
@@ -113,8 +113,8 @@ export interface VNode<HostNode = RendererNode, HostElement = RendererElement> {
  // DOM
  el: HostNode | null
  anchor: HostNode | null // fragment anchor
-  target: HostElement | null // portal target
-  targetAnchor: HostNode | null // portal target anchor
+  target: HostElement | null // teleport target
+  targetAnchor: HostNode | null // teleport target anchor

  // optimization only
  shapeFlag: number
@@ -283,8 +283,8 @@ function _createVNode(
    ? ShapeFlags.ELEMENT
    : __FEATURE_SUSPENSE__ && isSuspense(type)
      ? ShapeFlags.SUSPENSE
-      : isPortal(type)
-        ? ShapeFlags.PORTAL
+      : isTeleport(type)
+        ? ShapeFlags.TELEPORT
        : isObject(type)
          ? ShapeFlags.STATEFUL_COMPONENT
          : isFunction(type)
@@ -430,7 +430,7 @@ export function normalizeChildren(vnode: VNode, children: unknown) {
  } else if (typeof children === 'object') {
    // Normalize slot to plain children
    if (
-      (shapeFlag & ShapeFlags.ELEMENT || shapeFlag & ShapeFlags.PORTAL) &&
+      (shapeFlag & ShapeFlags.ELEMENT || shapeFlag & ShapeFlags.TELEPORT) &&
      (children as any).default
    ) {
      normalizeChildren(vnode, (children as any).default())
@@ -446,8 +446,8 @@ export function normalizeChildren(vnode: VNode, children: unknown) {
    type = ShapeFlags.SLOTS_CHILDREN
  } else {
    children = String(children)
-    // force portal children to array so it can be moved around
-    if (shapeFlag & ShapeFlags.PORTAL) {
+    // force teleport children to array so it can be moved around
+    if (shapeFlag & ShapeFlags.TELEPORT) {
      type = ShapeFlags.ARRAY_CHILDREN
      children = [createTextVNode(children as string)]
    } else {