@stencil/core 5.0.0-alpha.4 → 5.0.0-alpha.6

package/dist/signals/index.d.ts

@@ -0,0 +1,47 @@
+import { ReadonlySignal, ReadonlySignal as ReadonlySignal$1, Signal, batch, computed, effect, signal, untracked } from "@preact/signals-core";
+//#region src/runtime/signals.d.ts
+declare const STENCIL_SIGNALS_SYMBOL: unique symbol;
+//#endregion
+//#region src/signals/index.d.ts
+/**
+ * Returns the `ReadonlySignal` backing a `@Prop` member on a Stencil element.
+ * Requires `extras.signalBacking: true` in `stencil.config.ts`.
+ * Only `@Prop` members are exposed - `@State` is internal component state.
+ *
+ * Useful for cross-component or cross-framework reactivity without polling or events:
+ * ```ts
+ * import { getSignal, computed } from '@stencil/core/signals';
+ *
+ * const count = getSignal<number>(myEl, 'count');
+ * const doubled = computed(() => count.value * 2);
+ * ```
+ *
+ * @param elm - the Stencil host element
+ * @param prop - the `@Prop` member name
+ * @returns the `ReadonlySignal` for the prop, or `null` if not found / not signal-backed
+ */
+declare const getSignal: <T = unknown>(elm: Element, prop: string) => ReadonlySignal$1<T> | null;
+/**
+ * Marks a class method as a reactive effect. Wraps the method in `effect()` after
+ * signal initialization and registers cleanup on disconnect. Dependencies are
+ * auto-tracked - any signal read inside re-runs the method on change.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from '@stencil/core/signals';
+ *
+ * @Component({ tag: 'my-cmp' })
+ * export class MyCmp {
+ *   @State() count = 0;
+ *
+ *   @Effect()
+ *   log() {
+ *     console.log(this.count); // re-runs whenever count changes
+ *   }
+ * }
+ * ```
+ * @returns a MethodDecorator that registers the method as a reactive effect
+ */
+declare function Effect(): MethodDecorator;
+//#endregion
+export { Effect, type ReadonlySignal, STENCIL_SIGNALS_SYMBOL, type Signal, batch, computed, effect, getSignal, signal, untracked };

package/dist/signals/index.js

@@ -0,0 +1,199 @@
+import { batch, computed, effect, signal, untracked } from "@preact/signals-core";
+//#region src/app-data/index.ts
+/**
+* A collection of default build flags for a Stencil project.
+*
+* This collection can be found throughout the Stencil codebase, often imported from the `virtual:app-data` module like so:
+* ```ts
+* import { BUILD } from 'virtual:app-data';
+* ```
+* and is used to determine if a portion of the output of a Stencil _project_'s compilation step can be eliminated.
+*
+* e.g. When `BUILD.allRenderFn` evaluates to `false`, the compiler will eliminate conditional statements like:
+* ```ts
+* if (BUILD.allRenderFn) {
+*   // some code that will be eliminated if BUILD.allRenderFn is false
+* }
+* ```
+*
+* `virtual:app-data`, the module that `BUILD` is imported from, is an alias for the `@stencil/core/runtime/app-data`, and is
+* partially referenced by {@link STENCIL_APP_DATA_ID}. The `src/compiler/bundle/app-data-plugin.ts` references
+* `STENCIL_APP_DATA_ID` uses it to replace these defaults with {@link BuildConditionals} that are derived from a
+* Stencil project's contents (i.e. metadata from the components). This replacement happens at a Stencil project's
+* compile time. Such code can be found at `src/compiler/app-core/app-data.ts`.
+*/
+const BUILD = {
+	allRenderFn: false,
+	element: true,
+	event: true,
+	hasRenderFn: true,
+	hostListener: true,
+	hostListenerTargetWindow: true,
+	hostListenerTargetDocument: true,
+	hostListenerTargetBody: true,
+	hostListenerTarget: true,
+	member: true,
+	method: true,
+	mode: true,
+	observeAttribute: true,
+	prop: true,
+	propMutable: true,
+	reflect: true,
+	scoped: true,
+	shadowDom: true,
+	shadowModeClosed: false,
+	slot: true,
+	cssAnnotations: true,
+	state: true,
+	style: true,
+	formAssociated: true,
+	svg: true,
+	updatable: true,
+	vdomAttribute: true,
+	vdomXlink: true,
+	vdomClass: true,
+	vdomFunctional: true,
+	vdomKey: true,
+	vdomListener: true,
+	vdomRef: true,
+	vdomPropOrAttr: true,
+	vdomRender: true,
+	vdomStyle: true,
+	vdomText: true,
+	propChangeCallback: true,
+	taskQueue: true,
+	lifecycle: true,
+	serializer: true,
+	deserializer: true,
+	patchAll: true,
+	patchChildren: true,
+	patchClone: true,
+	patchInsert: true,
+	hotModuleReplacement: false,
+	isDebug: false,
+	isDev: false,
+	isTesting: false,
+	hydrateServerSide: false,
+	hydrateClientSide: false,
+	lifecycleDOMEvents: false,
+	lazyLoad: false,
+	profile: false,
+	slotRelocation: true,
+	lightDomPatches: true,
+	slotChildNodes: true,
+	slotCloneNode: true,
+	slotDomMutations: true,
+	slotTextContent: true,
+	hydratedAttribute: false,
+	hydratedClass: true,
+	invisiblePrehydration: true,
+	staticHydrationStyles: false,
+	propBoolean: true,
+	propNumber: true,
+	propString: true,
+	constructableCSS: true,
+	devTools: false,
+	shadowDelegatesFocus: true,
+	shadowSlotAssignmentManual: false,
+	initializeNextTick: false,
+	asyncLoading: true,
+	asyncQueue: false
+};
+BUILD.isDev, BUILD.isTesting;
+const MEMBER_FLAGS = {
+	String: 1,
+	Number: 2,
+	Boolean: 4,
+	Any: 8,
+	Unknown: 16,
+	State: 32,
+	Method: 64,
+	Event: 128,
+	Element: 256,
+	ReflectAttr: 512,
+	Mutable: 1024,
+	Getter: 2048,
+	Setter: 4096,
+	Prop: 31,
+	HasAttribute: 31,
+	PropLike: 63
+};
+//#endregion
+//#region src/client/client-host-ref.ts
+/**
+* Given a {@link d.RuntimeRef} retrieve the corresponding {@link d.HostRef}
+*
+* @param ref the runtime ref of interest
+* @returns the Host reference (if found) or undefined
+*/
+const getHostRef = (ref) => {
+	if (ref.__s_ghr) return ref.__s_ghr();
+};
+//#endregion
+//#region src/client/client-log.ts
+const STENCIL_DEV_MODE = BUILD.isTesting ? ["STENCIL:"] : ["%cstencil", "color: white;background:#4c47ff;font-weight: bold; font-size:10px; padding:2px 6px; border-radius: 5px"];
+const consoleDevWarn = (...m) => console.warn(...STENCIL_DEV_MODE, ...m);
+/*!__STENCIL_STATIC_IMPORT_SWITCH__*/
+(typeof window !== "undefined" ? window : {}).HTMLElement;
+BUILD.constructableCSS;
+//#endregion
+//#region src/runtime/signals.ts
+const STENCIL_SIGNALS_SYMBOL = Symbol.for("stencil.signals");
+BUILD.lazyLoad || globalThis.HTMLElement;
+//#endregion
+//#region src/signals/index.ts
+/**
+* Returns the `ReadonlySignal` backing a `@Prop` member on a Stencil element.
+* Requires `extras.signalBacking: true` in `stencil.config.ts`.
+* Only `@Prop` members are exposed - `@State` is internal component state.
+*
+* Useful for cross-component or cross-framework reactivity without polling or events:
+* ```ts
+* import { getSignal, computed } from '@stencil/core/signals';
+*
+* const count = getSignal<number>(myEl, 'count');
+* const doubled = computed(() => count.value * 2);
+* ```
+*
+* @param elm - the Stencil host element
+* @param prop - the `@Prop` member name
+* @returns the `ReadonlySignal` for the prop, or `null` if not found / not signal-backed
+*/
+const getSignal = (elm, prop) => {
+	const hostRef = getHostRef(elm);
+	if (!hostRef?.$signalValues$) {
+		if (BUILD.isDev) consoleDevWarn(`getSignal('${prop}'): element <${elm.tagName.toLowerCase()}> is not signal-backed. Ensure extras.signalBacking is true in stencil.config.ts.`);
+		return null;
+	}
+	if (!((hostRef.$cmpMeta$?.$members$?.[prop]?.[0] ?? 0) & MEMBER_FLAGS.Prop)) return null;
+	return hostRef.$signalValues$.get(prop) ?? null;
+};
+/**
+* Marks a class method as a reactive effect. Wraps the method in `effect()` after
+* signal initialization and registers cleanup on disconnect. Dependencies are
+* auto-tracked - any signal read inside re-runs the method on change.
+*
+* @example
+* ```ts
+* import { Effect } from '@stencil/core/signals';
+*
+* @Component({ tag: 'my-cmp' })
+* export class MyCmp {
+*   @State() count = 0;
+*
+*   @Effect()
+*   log() {
+*     console.log(this.count); // re-runs whenever count changes
+*   }
+* }
+* ```
+* @returns a MethodDecorator that registers the method as a reactive effect
+*/
+function Effect() {
+	return (target, propertyKey) => {
+		const proto = target;
+		(proto.__stencilEffects ??= []).push(propertyKey);
+	};
+}
+//#endregion
+export { Effect, STENCIL_SIGNALS_SYMBOL, batch, computed, effect, getSignal, signal, untracked };

package/dist/sys/node/index.d.mts

@@ -1,4 +1,4 @@
-import { $r as Logger, _r as CompilerSystem } from "../../index-BwTaN1Nq.mjs";
+import { $r as Logger, vr as CompilerSystem } from "../../index-D8vvsppY.mjs";
 
 //#region src/sys/node/logger/index.d.ts
 /**

package/dist/sys/node/index.mjs

@@ -1,2 +1,2 @@
-import { n as setupNodeProcess, r as createNodeLogger, t as createNodeSys } from "../../node-BF2jSfWg.mjs";
+import { n as setupNodeProcess, r as createNodeLogger, t as createNodeSys } from "../../node-klLZLdDe.mjs";
 export { createNodeLogger, createNodeSys, setupNodeProcess };

package/dist/sys/node/worker.mjs

@@ -1,5 +1,5 @@
-import { l as createWorkerMessageHandler } from "../../compiler-BYRrEeD-.mjs";
-import { t as createNodeSys } from "../../node-BF2jSfWg.mjs";
+import { l as createWorkerMessageHandler } from "../../compiler-CdUbDTbV.mjs";
+import { t as createNodeSys } from "../../node-klLZLdDe.mjs";
 //#region src/sys/node/node-worker-thread.ts
 /**
 * Initialize a worker thread, setting up various machinery for managing

package/dist/testing/index.d.mts

@@ -1,5 +1,5 @@
-import { $r as Logger, B as ComponentCompilerMeta, Bt as Module, E as CompilerCtx, Et as HostRef, Gt as NewSpecPageOptions, Qr as LogLevel, Tt as HostElement, Xr as LoadConfigInit, _r as CompilerSystem, a as BuildCtx, bn as SpecPage, fa as UserBuildConditionals, hn as RuntimeRef, la as RafCallback, na as UnvalidatedConfig, pt as ComponentRuntimeMeta, ra as ValidatedConfig, sa as ErrorHandler, ti as LoggerTimeSpan, zr as Diagnostic } from "../index-BwTaN1Nq.mjs";
-import { _ as Env, c as getMode, d as Fragment, f as createEvent, g as setAssetPath, h as getAssetPath, i as getRenderingRef, n as h, p as getElement, r as forceUpdate, t as Host, u as Mixin } from "../index-9LTuoSiw.mjs";
+import { $r as Logger, B as ComponentCompilerMeta, Br as Diagnostic, Dt as HostRef, E as CompilerCtx, Et as HostElement, Nt as Module, Qr as LogLevel, Rt as NewSpecPageOptions, Xr as LoadConfigInit, Zn as Compiler, a as BuildCtx, ca as ErrorHandler, cn as RuntimeRef, ia as ValidatedConfig, kr as Config, mt as ComponentRuntimeMeta, pa as UserBuildConditionals, pn as SpecPage, ra as UnvalidatedConfig, ti as LoggerTimeSpan, ua as RafCallback, vr as CompilerSystem } from "../index-D8vvsppY.mjs";
+import { a as h, b as Env, d as getMode, g as getElement, h as createEvent, i as Host, m as Fragment, o as forceUpdate, p as Mixin, s as getRenderingRef, v as getAssetPath, y as setAssetPath } from "../index-UUlemGuu.mjs";
 import { Mock } from "vitest";
 
 //#region src/testing/testing-logger.d.ts
@@ -98,6 +98,100 @@ declare function mockWindow(html?: string): Window;
  */
 declare const mockModule: (mod?: Partial<Module>) => Module;
 //#endregion
+//#region src/testing/create-test-compiler.d.ts
+/**
+ * Options for creating a test compiler
+ */
+interface CreateTestCompilerOptions {
+  /**
+   * Additional configuration overrides for the test compiler
+   */
+  config?: Partial<Config>;
+  /**
+   * Path to a tsconfig.json file. Defaults to {@link TESTING_TSCONFIG}.
+   * To add custom options, create a file that `extends` the base fixture:
+   * `{ "extends": "./path/to/tsconfig.testing.json", "compilerOptions": { ... } }`
+   */
+  tsconfig?: string;
+  /**
+   * Pre-validated compiler setup from {@link prepareTestCompiler}. When
+   * provided, the expensive `loadConfig` step is skipped and a fresh compiler
+   * is created directly from the cached validated config.
+   */
+  setup?: PreparedTestCompiler;
+}
+/**
+ * Result of creating a test compiler
+ */
+interface TestCompilerResult {
+  /**
+   * The compiler instance ready for testing
+   */
+  compiler: Compiler;
+  /**
+   * The validated configuration used to create the compiler
+   */
+  config: ValidatedConfig;
+  /**
+   * The compiler system instance
+   */
+  sys: CompilerSystem;
+}
+/**
+ * A pre-validated compiler configuration that can be reused across multiple
+ * `createTestCompiler` calls within the same test suite to avoid repeating
+ * the expensive `loadConfig` step.
+ *
+ * Obtain via {@link prepareTestCompiler} in a `beforeAll` block, then pass as
+ * `options.setup` to {@link createTestCompiler} in each `beforeEach`.
+ */
+interface PreparedTestCompiler {
+  /** @internal */
+  _validatedConfig: ValidatedConfig;
+  /** @internal */
+  _tsconfigPath: string;
+}
+/**
+ * Runs the expensive one-time setup for a test compiler suite: patching the
+ * sys, reading and validating the tsconfig. Use this in a `beforeAll` block
+ * when a describe block contains multiple tests that each need a fresh
+ * compiler, to avoid repeating `loadConfig` on every test.
+ *
+ * @param options - Configuration options for preparing the test compiler
+ * @returns A {@link PreparedTestCompiler} that can be passed to {@link createTestCompiler}
+ *
+ * @example
+ * ```ts
+ * let setup: PreparedTestCompiler;
+ * beforeAll(async () => { setup = await prepareTestCompiler(); });
+ * beforeEach(async () => {
+ *   const { compiler } = await createTestCompiler({ setup });
+ * });
+ * ```
+ */
+declare const prepareTestCompiler: (options?: Omit<CreateTestCompilerOptions, "setup">) => Promise<PreparedTestCompiler>;
+/**
+ * Creates a test compiler instance with a hybrid filesystem (reads from disk, writes to memory).
+ * This utility handles the common setup pattern for compiler tests.
+ *
+ * When multiple tests in the same suite need independent compiler instances,
+ * pass a {@link PreparedTestCompiler} from {@link prepareTestCompiler} as
+ * `options.setup` to skip the expensive `loadConfig` step on each test.
+ *
+ * @param options - Configuration options for the test compiler
+ * @returns An object with the compiler, validated config, and system instance
+ *
+ * @example
+ * ```ts
+ * const { compiler, config } = await createTestCompiler({
+ *   config: { minifyCss: true }
+ * });
+ * await compiler.fs.writeFile('/src/index.html', '<cmp-a></cmp-a>');
+ * const result = await compiler.build();
+ * ```
+ */
+declare const createTestCompiler: (options?: CreateTestCompilerOptions) => Promise<TestCompilerResult>;
+//#endregion
 //#region src/testing/spec-page.d.ts
 /**
  * Creates a new spec page for unit testing
@@ -206,4 +300,4 @@ declare function readTask(cb: RafCallback): void;
 //#region src/testing/platform/index.d.ts
 declare const setMode: (handler: (elm: any) => string | undefined | null) => void;
 //#endregion
-export { Build, Env, Fragment, Host, Mixin, type SpecPage, createEvent, createTestingSystem, forceUpdate, getAssetPath, getElement, getHostRef, getMode, getRenderingRef, h, mockBuildCtx, mockCompilerCtx, mockCompilerSystem, mockComponentMeta, mockConfig, mockDocument, mockLoadConfigInit, mockLogger, mockModule, mockValidatedConfig, mockWindow, newSpecPage, readTask, registerHost, registerInstance, setAssetPath, setErrorHandler, setMode, setupConsoleMocker, shuffleArray, writeTask };
+export { Build, type CreateTestCompilerOptions, Env, Fragment, Host, Mixin, type PreparedTestCompiler, type SpecPage, type TestCompilerResult, createEvent, createTestCompiler, createTestingSystem, forceUpdate, getAssetPath, getElement, getHostRef, getMode, getRenderingRef, h, mockBuildCtx, mockCompilerCtx, mockCompilerSystem, mockComponentMeta, mockConfig, mockDocument, mockLoadConfigInit, mockLogger, mockModule, mockValidatedConfig, mockWindow, newSpecPage, prepareTestCompiler, readTask, registerHost, registerInstance, setAssetPath, setErrorHandler, setMode, setupConsoleMocker, shuffleArray, writeTask };