feat(runtime): expose ReactiveController and ReactiveControllerHost

Moves ReactiveController interface and ReactiveControllerHost class from
test utilities to @stencil/core runtime, making them publicly available
for component composition patterns.

This enables developers to:
- Create reusable reactive controllers that hook into component lifecycle
- Compose multiple controllers in a single component
- Share stateful logic across components without inheritance

Components extending ReactiveControllerHost can use addController() to
register controllers that automatically receive lifecycle callbacks
(hostConnected, hostDisconnected, hostWillLoad, etc.) and can trigger
updates via requestUpdate().

Known Limitation: Components extending ReactiveControllerHost cannot use
<Host> as their root element since ReactiveControllerHost does not extend
HTMLElement. Components must return regular elements (e.g., <div>) as root.

Changes:
- Add ReactiveController interface to src/runtime/reactive-controller.ts
- Add ReactiveControllerHost class to src/runtime/reactive-controller.ts
- Export from src/runtime/index.ts and src/hydrate/platform/index.ts
- Add type declarations to src/declarations/stencil-public-runtime.ts
- Update transformer to preserve ReactiveControllerHost in imports
- Update test components to import from @stencil/core

Author: OS-paulvisciano

src/compiler/transformers/update-stencil-core-import.ts

@@ -15,7 +15,27 @@ export const updateStencilCoreImports = (updatedCoreImportPath: string): ts.Tran
       tsSourceFile.statements.forEach((s) => {
         if (ts.isImportDeclaration(s)) {
           if (s.moduleSpecifier != null && ts.isStringLiteral(s.moduleSpecifier)) {
-            if (s.moduleSpecifier.text === STENCIL_CORE_ID) {
+            const moduleSpecifierText = s.moduleSpecifier.text;
+
+            // Handle @stencil/core/jsx-runtime and @stencil/core/jsx-dev-runtime imports
+            if (
+              moduleSpecifierText === '@stencil/core/jsx-runtime' ||
+              moduleSpecifierText === '@stencil/core/jsx-dev-runtime'
+            ) {
+              // Rewrite to import from the updated core import path
+              const newImport = ts.factory.updateImportDeclaration(
+                s,
+                s.modifiers,
+                s.importClause,
+                ts.factory.createStringLiteral(updatedCoreImportPath),
+                s.attributes,
+              );
+              newStatements.push(newImport);
+              madeChanges = true;
+              return;
+            }
+
+            if (moduleSpecifierText === STENCIL_CORE_ID) {
               if (
                 s.importClause &&
                 s.importClause.namedBindings &&
@@ -92,4 +112,8 @@ const KEEP_IMPORTS = new Set([
   'setTagTransformer',
   'transformTag',
   'Mixin',
+  'jsx',
+  'jsxs',
+  'jsxDEV',
+  'ReactiveControllerHost',
 ]);

src/declarations/stencil-public-runtime.ts

@@ -638,6 +638,47 @@ export interface ComponentInterface {
   [memberName: string]: any;
 }
 
+/**
+ * Interface for reactive controllers that can be attached to a ReactiveControllerHost.
+ * Controllers implement lifecycle hooks that are called by the host during component lifecycle.
+ */
+export interface ReactiveController {
+  hostConnected?(): void;
+  hostDisconnected?(): void;
+  hostWillLoad?(): Promise<void> | void;
+  hostDidLoad?(): void;
+  hostWillRender?(): Promise<void> | void;
+  hostDidRender?(): void;
+  hostWillUpdate?(): Promise<void> | void;
+  hostDidUpdate?(): void;
+}
+
+/**
+ * Base class that implements ComponentInterface and provides reactive controller functionality.
+ * Components can extend this class to enable reactive controller composition.
+ * 
+ * Known Limitation: Components extending ReactiveControllerHost cannot use
+ * `<Host>` as their root element in the render method. This is because
+ * ReactiveControllerHost does not extend HTMLElement. Instead, return a
+ * regular element (like `<div>`) as the root.
+ */
+export declare class ReactiveControllerHost implements ComponentInterface {
+  controllers: Set<ReactiveController>;
+
+  addController(controller: ReactiveController): void;
+  removeController(controller: ReactiveController): void;
+  requestUpdate(): void;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  componentWillLoad(): void;
+  componentDidLoad(): void;
+  componentWillRender(): void;
+  componentDidRender(): void;
+  componentWillUpdate(): void;
+  componentDidUpdate(): void;
+  [memberName: string]: any;
+}
+
 // General types important to applications using stencil built components
 export interface EventEmitter<T = any> {
   emit: (data?: T) => CustomEvent<T>;

src/hydrate/platform/index.ts

@@ -229,6 +229,7 @@ export {
   postUpdateComponent,
   proxyComponent,
   proxyCustomElement,
+  ReactiveControllerHost,
   renderVdom,
   setAssetPath,
   setMode,

src/runtime/index.ts

@@ -13,6 +13,7 @@ export { setNonce } from './nonce';
 export { parsePropertyValue } from './parse-property-value';
 export { setPlatformOptions } from './platform-options';
 export { proxyComponent } from './proxy-component';
+export { ReactiveController, ReactiveControllerHost } from './reactive-controller';
 export { render } from './render';
 export { HYDRATED_STYLE_ID } from './runtime-constants';
 export { getValue, setValue } from './set-value';

src/runtime/reactive-controller.ts

@@ -0,0 +1,84 @@
+import type { ComponentInterface } from '../declarations/stencil-public-runtime';
+import { forceUpdate } from './update-component';
+
+export interface ReactiveController {
+  hostConnected?(): void;
+  hostDisconnected?(): void;
+  hostWillLoad?(): Promise<void> | void;
+  hostDidLoad?(): void;
+  hostWillRender?(): Promise<void> | void;
+  hostDidRender?(): void;
+  hostWillUpdate?(): Promise<void> | void;
+  hostDidUpdate?(): void;
+}
+
+/**
+ * Base class for components that want to use reactive controllers.
+ * 
+ * Components extending this class can use the composition pattern to share
+ * stateful logic via reactive controllers.
+ * 
+ * Known Limitation: Components extending ReactiveControllerHost cannot use
+ * `<Host>` as their root element in the render method. This is because
+ * ReactiveControllerHost does not extend HTMLElement. Instead, return a
+ * regular element (like `<div>`) as the root.
+ * 
+ * @example
+ * ```tsx
+ * @Component({ tag: 'my-component' })
+ * export class MyComponent extends ReactiveControllerHost {
+ *   private myController = new MyController(this);
+ *   
+ *   render() {
+ *     return <div>...</div>; // Use <div>, not <Host>
+ *   }
+ * }
+ * ```
+ */
+export class ReactiveControllerHost implements ComponentInterface {
+  controllers = new Set<ReactiveController>();
+
+  addController(controller: ReactiveController) {
+    this.controllers.add(controller);
+  }
+
+  removeController(controller: ReactiveController) {
+    this.controllers.delete(controller);
+  }
+
+  requestUpdate() {
+    forceUpdate(this);
+  }
+
+  connectedCallback() {
+    this.controllers.forEach((controller) => controller.hostConnected?.());
+  }
+
+  disconnectedCallback() {
+    this.controllers.forEach((controller) => controller.hostDisconnected?.());
+  }
+
+  componentWillLoad() {
+    this.controllers.forEach((controller) => controller.hostWillLoad?.());
+  }
+
+  componentDidLoad() {
+    this.controllers.forEach((controller) => controller.hostDidLoad?.());
+  }
+
+  componentWillRender() {
+    this.controllers.forEach((controller) => controller.hostWillRender?.());
+  }
+
+  componentDidRender() {
+    this.controllers.forEach((controller) => controller.hostDidRender?.());
+  }
+
+  componentWillUpdate() {
+    this.controllers.forEach((controller) => controller.hostWillUpdate?.());
+  }
+
+  componentDidUpdate() {
+    this.controllers.forEach((controller) => controller.hostDidUpdate?.());
+  }
+}

test/wdio/ts-target/components.d.ts

@@ -307,8 +307,6 @@ export namespace Components {
      */
     interface ExtendsRender {
     }
-    interface ExtendsViaHostCmp {
-    }
     /**
      * WatchCmp - Demonstrates
      * @Watch decorator inheritance
@@ -606,12 +604,6 @@ declare global {
         prototype: HTMLExtendsRenderElement;
         new (): HTMLExtendsRenderElement;
     };
-    interface HTMLExtendsViaHostCmpElement extends Components.ExtendsViaHostCmp, HTMLStencilElement {
-    }
-    var HTMLExtendsViaHostCmpElement: {
-        prototype: HTMLExtendsViaHostCmpElement;
-        new (): HTMLExtendsViaHostCmpElement;
-    };
     /**
      * WatchCmp - Demonstrates
      * @Watch decorator inheritance
@@ -708,7 +700,6 @@ declare global {
         "extends-mixin-cmp": HTMLExtendsMixinCmpElement;
         "extends-props-state": HTMLExtendsPropsStateElement;
         "extends-render": HTMLExtendsRenderElement;
-        "extends-via-host-cmp": HTMLExtendsViaHostCmpElement;
         "extends-watch": HTMLExtendsWatchElement;
         "inheritance-checkbox-group": HTMLInheritanceCheckboxGroupElement;
         "inheritance-radio-group": HTMLInheritanceRadioGroupElement;
@@ -906,8 +897,6 @@ declare namespace LocalJSX {
      */
     interface ExtendsRender {
     }
-    interface ExtendsViaHostCmp {
-    }
     /**
      * WatchCmp - Demonstrates
      * @Watch decorator inheritance
@@ -986,7 +975,6 @@ declare namespace LocalJSX {
         "extends-mixin-cmp": ExtendsMixinCmp;
         "extends-props-state": ExtendsPropsState;
         "extends-render": ExtendsRender;
-        "extends-via-host-cmp": ExtendsViaHostCmp;
         "extends-watch": ExtendsWatch;
         "inheritance-checkbox-group": InheritanceCheckboxGroup;
         "inheritance-radio-group": InheritanceRadioGroup;
@@ -1071,7 +1059,6 @@ declare module "@stencil/core" {
              * - CSS Class Inheritance: CSS classes from parent template maintained in component extension
              */
             "extends-render": LocalJSX.ExtendsRender & JSXBase.HTMLAttributes<HTMLExtendsRenderElement>;
-            "extends-via-host-cmp": LocalJSX.ExtendsViaHostCmp & JSXBase.HTMLAttributes<HTMLExtendsViaHostCmpElement>;
             /**
              * WatchCmp - Demonstrates
              * @Watch decorator inheritance

test/wdio/ts-target/extends-composition-scaling/checkbox-group-cmp.tsx

@@ -1,5 +1,4 @@
-import { Component, h, State, Element, Event, EventEmitter } from '@stencil/core';
-import { ReactiveControllerHost } from './reactive-controller-host.js';
+import { Component, h, ReactiveControllerHost, State, Element, Event, EventEmitter } from '@stencil/core';
 import { ValidationController } from './validation-controller.js';
 import { FocusController } from './focus-controller.js';
 
@@ -15,7 +14,7 @@ export class CheckboxGroupCmp extends ReactiveControllerHost {
 
   // Controllers via composition
   private validation = new ValidationController(this);
-  private focus = new FocusController(this);
+  private focusController = new FocusController(this);
 
   private inputId = `checkbox-group-${Math.random().toString(36).substr(2, 9)}`;
   private helperTextId = `${this.inputId}-helper-text`;
@@ -55,16 +54,16 @@ export class CheckboxGroupCmp extends ReactiveControllerHost {
   };
 
   private handleFocus = () => {
-    this.focus.handleFocus();
+    this.focusController.handleFocus();
   };
 
   private handleBlur = () => {
-    this.focus.handleBlur();
+    this.focusController.handleBlur();
     this.validation.handleBlur(this.values);
   };
 
   render() {
-    const focusState = this.focus.getFocusState();
+    const focusState = this.focusController.getFocusState();
     const validationData = this.validation.getValidationMessageData(this.helperTextId, this.errorTextId);
 
     return (

test/wdio/ts-target/extends-composition-scaling/focus-controller.ts

@@ -7,7 +7,7 @@
  * 3. Provides methods to handle focus lifecycle
  */
 import { forceUpdate } from '@stencil/core';
-import type { ReactiveControllerHost, ReactiveController } from './reactive-controller-host.js';
+import type { ReactiveControllerHost, ReactiveController } from '@stencil/core';
 
 export class FocusController implements ReactiveController {
   private host: ReactiveControllerHost;

test/wdio/ts-target/extends-composition-scaling/radio-group-cmp.tsx

@@ -1,5 +1,4 @@
-import { Component, h, State, Element, Event, EventEmitter } from '@stencil/core';
-import { ReactiveControllerHost } from './reactive-controller-host.js';
+import { Component, h, ReactiveControllerHost, State, Element, Event, EventEmitter } from '@stencil/core';
 import { ValidationController } from './validation-controller.js';
 import { FocusController } from './focus-controller.js';
 
@@ -15,7 +14,7 @@ export class RadioGroupCmp extends ReactiveControllerHost {
 
   // Controllers via composition
   private validation = new ValidationController(this);
-  private focus = new FocusController(this);
+  private focusController = new FocusController(this);
 
   private inputId = `radio-group-${Math.random().toString(36).substr(2, 9)}`;
   private helperTextId = `${this.inputId}-helper-text`;
@@ -50,16 +49,16 @@ export class RadioGroupCmp extends ReactiveControllerHost {
   };
 
   private handleFocus = () => {
-    this.focus.handleFocus();
+    this.focusController.handleFocus();
   };
 
   private handleBlur = () => {
-    this.focus.handleBlur();
+    this.focusController.handleBlur();
     this.validation.handleBlur(this.value);
   };
 
   render() {
-    const focusState = this.focus.getFocusState();
+    const focusState = this.focusController.getFocusState();
     const validationData = this.validation.getValidationMessageData(this.helperTextId, this.errorTextId);
 
     return (

test/wdio/ts-target/extends-composition-scaling/text-input-cmp.tsx

@@ -1,5 +1,4 @@
-import { Component, h, State, Element } from '@stencil/core';
-import { ReactiveControllerHost } from './reactive-controller-host.js';
+import { Component, h, ReactiveControllerHost, State, Element } from '@stencil/core';
 import { ValidationController } from './validation-controller.js';
 import { FocusController } from './focus-controller.js';
 
@@ -13,7 +12,7 @@ export class TextInputCmp extends ReactiveControllerHost {
 
   // Controllers via composition
   private validation = new ValidationController(this);
-  private focus = new FocusController(this);
+  private focusController = new FocusController(this);
 
   private inputId = `text-input-${Math.random().toString(36).substr(2, 9)}`;
   private helperTextId = `${this.inputId}-helper-text`;
@@ -47,16 +46,16 @@ export class TextInputCmp extends ReactiveControllerHost {
   };
 
   private handleFocus = () => {
-    this.focus.handleFocus();
+    this.focusController.handleFocus();
   };
 
   private handleBlur = () => {
-    this.focus.handleBlur();
+    this.focusController.handleBlur();
     this.validation.handleBlur(this.value);
   };
 
   render() {
-    const focusState = this.focus.getFocusState();
+    const focusState = this.focusController.getFocusState();
     const validationState = this.validation.getValidationState();
     const validationData = this.validation.getValidationMessageData(this.helperTextId, this.errorTextId);