Merge pull request #514 from universal-ember/improvements-to-portals

Improvements to portals (pattern for ember-wormhole migration, elemnt support, @Append support)

Author: NullVoxPopuli

ember-primitives/src/components/portal.gts

@@ -1,3 +1,6 @@
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents */
+import { assert } from "@ember/debug";
+
 import { modifier } from "ember-modifier";
 import { cell } from "ember-resources";
 
@@ -13,9 +16,17 @@ export interface Signature {
      * The name of the PortalTarget to render in to.
      * This is the value of the `data-portal-name` attribute
      * of the element you wish to render in to.
+     *
+     * This can also be an Element which pairs nicely with query-utilities such as `wormhole`, or the platform-native `querySelector`
+     */
+    to: (Targets | (string & {})) | Element;
+
+    /**
+     * Set to true to append to the portal instead of replace
+     *
+     * Default: false
      */
-    // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
-    to: Targets | (string & {});
+    append?: boolean;
   };
   Blocks: {
     /**
@@ -25,6 +36,39 @@ export interface Signature {
   };
 }
 
+/**
+ * Polyfill for ember-wormhole behavior
+ *
+ * Example usage:
+ * ```gjs
+ * import { wormhole, Portal } from 'ember-primitives/components/portal';
+ *
+ * <template>
+ *   <div id="the-portal"></div>
+ *
+ *   <Portal @to={{wormhole "the-portal"}}>
+ *     content renders in the above div
+ *   </Portal>
+ * </template>
+ *
+ * ```
+ */
+export function wormhole(query: string | null | undefined | Element) {
+  assert(`Expected query/element to be truthy.`, query);
+
+  if (query instanceof Element) {
+    return query;
+  }
+
+  let found = document.getElementById(query);
+
+  found ??= document.querySelector(query);
+
+  assert(`Could not find element with id/selector ${query}`, found);
+
+  return found;
+}
+
 const anchor = modifier(
   (element: Element, [to, update]: [string, ReturnType<typeof ElementValue>["set"]]) => {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call
@@ -37,21 +81,43 @@ const anchor = modifier(
 
 const ElementValue = () => cell<Element | ShadowRoot>();
 
+function isElement(x: unknown): x is Element {
+  return x instanceof Element;
+}
+
 export const Portal: TOC<Signature> = <template>
-  {{#let (ElementValue) as |target|}}
-    {{! This div is always going to be empty,
+  {{#if (isElement @to)}}
+    {{#if @append}}
+      {{#in-element @to insertBefore=null}}
+        {{yield}}
+      {{/in-element}}
+    {{else}}
+      {{#in-element @to}}
+        {{yield}}
+      {{/in-element}}
+    {{/if}}
+  {{else}}
+    {{#let (ElementValue) as |target|}}
+      {{! This div is always going to be empty,
           because it'll either find the portal and render content elsewhere,
           it it won't find the portal and won't render anything.
-    }}
-    {{! template-lint-disable no-inline-styles }}
-    <div style="display:contents;" {{anchor @to target.set}}>
-      {{#if target.current}}
-        {{#in-element target.current}}
-          {{yield}}
-        {{/in-element}}
-      {{/if}}
-    </div>
-  {{/let}}
+      }}
+      {{! template-lint-disable no-inline-styles }}
+      <div style="display:contents;" {{anchor @to target.set}}>
+        {{#if target.current}}
+          {{#if @append}}
+            {{#in-element target.current insertBefore=null}}
+              {{yield}}
+            {{/in-element}}
+          {{else}}
+            {{#in-element target.current}}
+              {{yield}}
+            {{/in-element}}
+          {{/if}}
+        {{/if}}
+      </div>
+    {{/let}}
+  {{/if}}
 </template>;
 
 export default Portal;

pnpm-lock.yaml

@@ -87,6 +87,7 @@
     "prettier-plugin-ember-template-tag": "^2.0.5",
     "qunit": "^2.22.0",
     "qunit-dom": "^3.2.1",
+    "qunit-theme-ember": "^1.0.0",
     "read-package-up": "^11.0.0",
     "stylelint": "^16.19.1",
     "stylelint-config-standard": "^38.0.0",

test-app/package.json

@@ -33,4 +33,73 @@ module('Rendering | <Portal>', function (hooks) {
 
     assert.dom(`[data-portal-name="${PORTALS.popover}"]`).hasText('content');
   });
+
+  module('@append', function () {
+    test('true appends', async function (assert) {
+      await render(
+        <template>
+          <PortalTargets />
+          <Portal @to={{PORTALS.popover}}>
+            one
+          </Portal>
+          <Portal @to={{PORTALS.popover}} @append={{true}}>
+            two
+          </Portal>
+        </template>
+      );
+
+      assert.dom().hasText('one two');
+    });
+
+    test('true appends, but a third without append will replace', async function (assert) {
+      await render(
+        <template>
+          <PortalTargets />
+          <Portal @to={{PORTALS.popover}}>
+            one
+          </Portal>
+          <Portal @to={{PORTALS.popover}} @append={{true}}>
+            two
+          </Portal>
+          <Portal @to={{PORTALS.popover}}>
+            three
+          </Portal>
+        </template>
+      );
+
+      assert.dom().hasText('three');
+    });
+  });
+
+  module('@to is an element', function () {
+    test('element then Portal', async function (assert) {
+      const element = document.createElement('output');
+
+      await render(
+        <template>
+          {{element}}
+          <Portal @to={{element}}>
+            content here
+          </Portal>
+        </template>
+      );
+
+      assert.dom('output').hasText('content here');
+    });
+
+    test('Portal then element', async function (assert) {
+      const element = document.createElement('output');
+
+      await render(
+        <template>
+          <Portal @to={{element}}>
+            content here
+          </Portal>
+          {{element}}
+        </template>
+      );
+
+      assert.dom('output').hasText('content here');
+    });
+  });
 });

test-app/tests/portals/portal-rendering-test.gts

@@ -1,3 +1,5 @@
+import 'qunit-theme-ember/qunit.css';
+
 import { currentRouteName, currentURL, getSettledState, setApplication } from '@ember/test-helpers';
 import { getPendingWaiterState } from '@ember/test-waiters';
 import * as QUnit from 'qunit';