chore: tighten types. Make route for ReactiveController elements to work with lazy output. Test both outputs with lit/context

Author: johnjenkins

packages/core/src/declarations/stencil-public-runtime.ts

@@ -825,10 +825,7 @@ export interface ReactiveController {
   hostDidUpdate?(): void;
 }
 
-/**
- * The shape added to a component by mixing in `ReactiveControllerHost` (see below).
- */
-export interface ReactiveControllerHostInterface extends ComponentInterface {
+interface ReactiveControllerHost extends ComponentInterface {
   readonly controllers: ReadonlySet<ReactiveController>;
   addController(controller: ReactiveController): void;
   removeController(controller: ReactiveController): void;
@@ -841,6 +838,11 @@ export interface ReactiveControllerHostInterface extends ComponentInterface {
   readonly updateComplete: Promise<boolean>;
 }
 
+/**
+ * The shape added to a component by mixing in `ReactiveControllerHost` (see below).
+ */
+export type ReactiveControllerHostInterface = ReactiveControllerHost & HTMLElement;
+
 /**
  * A mixin factory (for use with `Mixin()`) that adds `ReactiveController` support to a component,
  * forwarding each Stencil lifecycle method to every registered controller's matching `hostX` hook.

packages/core/src/runtime/_test_/reactive-controller.spec.tsx

@@ -247,4 +247,31 @@ describe('reactive-controller', () => {
     await expect(pending).resolves.toBe(true);
     expect(renderCount).toBe(2);
   });
+
+  it('fires hostConnected immediately for a controller added after the host already connected', async () => {
+    const calls: string[] = [];
+    let host: any;
+
+    @Component({ tag: 'rc-late-controller' })
+    class Cmp extends Mixin(ReactiveControllerHost) {
+      constructor() {
+        super();
+        host = this;
+      }
+      render() {
+        return <div />;
+      }
+    }
+
+    await newSpecPage({ components: [Cmp], html: `<rc-late-controller></rc-late-controller>` });
+
+    class LateController implements ReactiveController {
+      hostConnected() {
+        calls.push('hostConnected');
+      }
+    }
+    host.addController(new LateController());
+
+    expect(calls).toEqual(['hostConnected']);
+  });
 });

packages/core/src/runtime/reactive-controller.ts

@@ -1,23 +1,29 @@
+import { getElement } from './element';
 import { forceUpdate } from './update-component';
 import type {
   ComponentInterface,
   ReactiveController,
   ReactiveControllerHostInterface,
+  MixedInCtor,
 } from '../declarations/stencil-public-runtime';
 
-type Ctor<T = {}> = new (...args: any[]) => T;
-
-// Explicit return type: the class below has a #private field, which the dts bundler can't
-// describe for an exported function's inferred (anonymous) return type (TS4094).
-export const ReactiveControllerHost = <B extends Ctor<ComponentInterface>>(
+export const ReactiveControllerHost = <B extends MixedInCtor<ComponentInterface & HTMLElement>>(
   Base: B,
-): Ctor<InstanceType<B> & ReactiveControllerHostInterface> => {
+): B & MixedInCtor<ReactiveControllerHostInterface> =>
   class ReactiveControllerHostMixin extends Base implements ReactiveControllerHostInterface {
     controllers = new Set<ReactiveController>();
+    #connected = false;
     #updateCompleteResolvers: Array<(value: boolean) => void> = [];
 
     addController(controller: ReactiveController) {
       this.controllers.add(controller);
+      // Matches Lit's ReactiveElement: a controller added after the host is already connected
+      // (e.g. constructed from a lifecycle hook rather than a field initializer - needed for any
+      // controller that wants a real DOM element, see connectedCallback below) would otherwise
+      // never see hostConnected - the bulk connectedCallback pass below already ran without it.
+      if (this.#connected) {
+        controller.hostConnected?.();
+      }
     }
 
     removeController(controller: ReactiveController) {
@@ -34,11 +40,31 @@ export const ReactiveControllerHost = <B extends Ctor<ComponentInterface>>(
 
     connectedCallback() {
       super.connectedCallback?.();
+      this.#connected = true;
+
+      // Under lazy-loading, `this` (the lazy instance) and the real host element are different
+      // objects - only `this` has addController/removeController/requestUpdate/updateComplete. A
+      // controller that needs genuine DOM access (addEventListener/dispatchEvent, e.g.
+      // @lit/context) needs a single object with both capabilities; bridge them onto the real
+      // element here so `@Element()`/`getElement(this)` works uniformly across build targets. In
+      // a standalone build getElement(this) === this, so this is a no-op there.
+      const el = getElement(this) as any;
+      if (el && el !== (this as unknown)) {
+        el.addController = (controller: ReactiveController) => this.addController(controller);
+        el.removeController = (controller: ReactiveController) => this.removeController(controller);
+        el.requestUpdate = () => this.requestUpdate();
+        Object.defineProperty(el, 'updateComplete', {
+          configurable: true,
+          get: () => this.updateComplete,
+        });
+      }
+
       this.controllers.forEach((c) => c.hostConnected?.());
     }
 
     disconnectedCallback() {
       super.disconnectedCallback?.();
+      this.#connected = false;
       this.controllers.forEach((c) => c.hostDisconnected?.());
     }
 
@@ -74,10 +100,4 @@ export const ReactiveControllerHost = <B extends Ctor<ComponentInterface>>(
       super.componentDidUpdate?.();
       this.controllers.forEach((c) => c.hostDidUpdate?.());
     }
-  }
-  // TS can't verify a generically-extended class satisfies InstanceType<B> - same pattern used
-  // by other mixin factories in this codebase (e.g. test/runtime's mixin-factories.ts).
-  return ReactiveControllerHostMixin as unknown as Ctor<
-    InstanceType<B> & ReactiveControllerHostInterface
-  >;
-};
+  };

test/integration/lit-context/index.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html dir="ltr" lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>lit-context interop</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+    <!-- lazy-loaded build (loader-bundle output target), default tag names -->
+    <script type="module" src="/dist/loader-bundle/app/app.js"></script>
+
+    <!-- standalone build (dist-custom-elements), tag names prefixed so it can be verified on the
+         same page without colliding with the lazy-loaded custom elements above -->
+    <script type="module">
+      import { setTagTransformer } from '/dist/standalone/index.js';
+      setTagTransformer((tag) => `standalone-${tag}`);
+      const provider = await import('/dist/standalone/lit-context-provider.js');
+      const consumer = await import('/dist/standalone/lit-context-consumer.js');
+      provider.defineCustomElement();
+      consumer.defineCustomElement();
+    </script>
+  </head>
+
+  <body>
+    <lit-context-provider>
+      <lit-context-consumer></lit-context-consumer>
+    </lit-context-provider>
+
+    <standalone-lit-context-provider>
+      <standalone-lit-context-consumer></standalone-lit-context-consumer>
+    </standalone-lit-context-provider>
+  </body>
+</html>

test/integration/lit-context/package.json

@@ -13,10 +13,7 @@
     "build": "stencil build",
     "build.dev": "stencil build --dev",
     "start": "stencil build --dev --watch --serve",
-    "test": "stencil-test && playwright test",
-    "test.e2e": "playwright test",
-    "test.spec": "stencil-test",
-    "generate": "stencil generate"
+    "test": "playwright test"
   },
   "dependencies": {
     "@lit/context": "^1.1.6",

test/integration/lit-context/src/components/lit-context-consumer/lit-context-consumer.tsx

@@ -1,18 +1,34 @@
 import { ContextConsumer } from '@lit/context';
-import { Component, Mixin, ReactiveControllerHost, State } from '@stencil/core';
+import {
+  Component,
+  Element,
+  Mixin,
+  ReactiveControllerHost,
+  ReactiveControllerHostInterface,
+  State,
+} from '@stencil/core';
 
 import { greetingContext } from '../../lit-context.js';
 
 @Component({ tag: 'lit-context-consumer' })
 export class LitContextConsumer extends Mixin(ReactiveControllerHost) {
   @State() value?: string;
+  @Element() host!: typeof this;
 
-  private consumer = new ContextConsumer(this, {
-    context: greetingContext,
-    callback: (value) => {
-      this.value = value;
-    },
-  });
+  private consumer?: ContextConsumer<typeof greetingContext, ReactiveControllerHostInterface>;
+
+  connectedCallback() {
+    super.connectedCallback?.();
+    // constructed here, not as a field initializer: the real host element (with
+    // addController/etc. bridged onto it) is only available once connected - see
+    // reactive-controller.ts's connectedCallback for why.
+    this.consumer ??= new ContextConsumer(this.host, {
+      context: greetingContext,
+      callback: (value) => {
+        this.value = value;
+      },
+    });
+  }
 
   render() {
     return <div class='value'>{this.value ?? 'no value'}</div>;

test/integration/lit-context/src/components/lit-context-provider/lit-context-provider.e2e.ts

@@ -4,16 +4,24 @@ import { test } from '@stencil/playwright';
 /**
  * Real-world interop check: @lit/context's ContextProvider/ContextConsumer, composed onto
  * Stencil components via `Mixin(ReactiveControllerHost)`, propagating a value across a real
- * `context-request` DOM event in an actual browser (dist-custom-elements, since that's what a
- * real consumer imports).
+ * `context-request` DOM event in an actual browser. The page loads both the lazy-loaded (`dist`)
+ * and standalone (`dist-custom-elements`) builds side by side - the standalone half is registered
+ * under `standalone-`-prefixed tag names (via `setTagTransformer`) so both can run without
+ * colliding - since a controller that needs real DOM access only works correctly in one of them
+ * without the mixin's host-element bridging (see reactive-controller.ts's `connectedCallback`).
  */
 test.describe('lit-context interop', () => {
-  test('propagates a value from provider to consumer via a real context-request event', async ({
-    page,
-  }) => {
-    await page.goto('/');
+  for (const [label, prefix] of [
+    ['lazy', ''],
+    ['standalone', 'standalone-'],
+  ] as const) {
+    test(`propagates a value from provider to consumer via a real context-request event (${label})`, async ({
+      page,
+    }) => {
+      await page.goto('/');
 
-    const consumer = page.locator('lit-context-consumer .value');
-    await expect(consumer).toHaveText('hello from provider');
-  });
+      const consumer = page.locator(`${prefix}lit-context-consumer .value`);
+      await expect(consumer).toHaveText('hello from provider');
+    });
+  }
 });

test/integration/lit-context/src/components/lit-context-provider/lit-context-provider.tsx

@@ -1,14 +1,23 @@
 import { ContextProvider } from '@lit/context';
-import { Component, Host, Mixin, ReactiveControllerHost } from '@stencil/core';
+import { Component, Host, Mixin, ReactiveControllerHost, Element } from '@stencil/core';
 
 import { greetingContext } from '../../lit-context.js';
 
 @Component({ tag: 'lit-context-provider' })
 export class LitContextProvider extends Mixin(ReactiveControllerHost) {
-  private provider = new ContextProvider(this, {
-    context: greetingContext,
-    initialValue: 'hello from provider',
-  });
+  @Element() host!: typeof this;
+  private provider?: ContextProvider<typeof greetingContext>;
+
+  connectedCallback() {
+    super.connectedCallback?.();
+    // constructed here, not as a field initializer: the real host element (with
+    // addController/etc. bridged onto it) is only available once connected - see
+    // reactive-controller.ts's connectedCallback for why.
+    this.provider ??= new ContextProvider(this.host, {
+      context: greetingContext,
+      initialValue: 'hello from provider',
+    });
+  }
 
   render() {
     return (

test/integration/lit-context/src/index.html

@@ -5,11 +5,7 @@ export const config: Config = {
   devServer: { port: 3336 },
   tsconfig: 'tsconfig.stencil.json',
   outputTargets: [
-    { type: 'www', hashFileNames: false },
-    {
-      type: 'standalone',
-      dir: 'www/build/standalone',
-      customElementsExportBehavior: 'auto-define-custom-elements',
-    },
+    { type: 'loader-bundle', skipInDev: false },
+    { type: 'standalone', skipInDev: false },
   ],
 };