@stencil/core 2.17.4 → 2.18.1

package/internal/stencil-core/index.d.ts

@@ -1,9 +1,10 @@
+export type { StencilConfig as Config, PrerenderConfig } from '../stencil-public-compiler';
 export type {
   ChildNode,
-  ComponentOptions,
   ComponentDidLoad,
   ComponentDidUpdate,
   ComponentInterface,
+  ComponentOptions,
   ComponentWillLoad,
   ComponentWillUpdate,
   EventEmitter,
@@ -11,42 +12,39 @@ export type {
   FunctionalComponent,
   FunctionalUtilities,
   JSX,
-  MethodOptions,
-  ModeStyles,
   ListenOptions,
   ListenTargetOptions,
+  MethodOptions,
+  ModeStyles,
   PropOptions,
   QueueApi,
   RafCallback,
   VNode,
   VNodeData,
 } from '../stencil-public-runtime';
-
 export {
   Build,
   Component,
   Element,
+  Env,
   Event,
+  forceUpdate,
+  Fragment,
   getAssetPath,
   getElement,
   getMode,
   getRenderingRef,
-  Fragment,
-  forceUpdate,
   h,
   Host,
-  Env,
   Listen,
   Method,
   Prop,
   readTask,
   setAssetPath,
+  setErrorHandler,
   setMode,
   setPlatformHelpers,
   State,
   Watch,
   writeTask,
-  setErrorHandler,
 } from '../stencil-public-runtime';
-
-export type { StencilConfig as Config, PrerenderConfig } from '../stencil-public-compiler';

package/internal/stencil-private.d.ts

@@ -1,5 +1,5 @@
-import { BuildResultsComponentGraph } from '.';
-import type { BuildEvents, BuildLog, BuildOutput, CompilerBuildResults, CompilerBuildStart, CompilerFsStats, CompilerRequestResponse, CompilerSystem, Config, CopyResults, DevServerConfig, DevServerEditor, Diagnostic, FsWriteOptions, Logger, LoggerTimeSpan, OptimizeCssInput, OptimizeCssOutput, OutputTargetWww, PageReloadStrategy, PrerenderConfig, StyleDoc, LoggerLineUpdater, TaskCommand } from './stencil-public-compiler';
+import type { InMemoryFileSystem } from '../compiler/sys/in-memory-fs';
+import type { BuildEvents, BuildLog, BuildResultsComponentGraph, CompilerBuildResults, CompilerBuildStart, CompilerFsStats, CompilerRequestResponse, CompilerSystem, Config, CopyResults, DevServerConfig, DevServerEditor, Diagnostic, Logger, LoggerLineUpdater, LoggerTimeSpan, OptimizeCssInput, OptimizeCssOutput, OutputTargetWww, PageReloadStrategy, PrerenderConfig, StyleDoc, TaskCommand } from './stencil-public-compiler';
 import type { ComponentInterface, ListenOptions, ListenTargetOptions, VNode, VNodeData } from './stencil-public-runtime';
 export interface SourceMap {
     file: string;
@@ -823,6 +823,10 @@ export interface ComponentConstructor {
     isProxied?: boolean;
     isStyleRegistered?: boolean;
 }
+/**
+ * A mapping from class member names to a list of methods which are watching
+ * them.
+ */
 export interface ComponentConstructorWatchers {
     [propName: string]: string[];
 }
@@ -832,9 +836,9 @@ export interface ComponentTestingConstructor extends ComponentConstructor {
         componentWillLoad?: Function;
         componentWillUpdate?: Function;
         componentWillRender?: Function;
-        __componentWillLoad?: Function;
-        __componentWillUpdate?: Function;
-        __componentWillRender?: Function;
+        __componentWillLoad?: Function | null;
+        __componentWillUpdate?: Function | null;
+        __componentWillRender?: Function | null;
     };
 }
 export interface ComponentNativeConstructor extends ComponentConstructor {
@@ -1016,51 +1020,6 @@ export interface EventEmitterData<T = any> {
     cancelable?: boolean;
     composed?: boolean;
 }
-export interface FsReadOptions {
-    useCache?: boolean;
-    setHash?: boolean;
-}
-export interface FsReaddirOptions {
-    inMemoryOnly?: boolean;
-    recursive?: boolean;
-    /**
-     * Directory names to exclude. Just the basename,
-     * not the entire path. Basically for "node_moduels".
-     */
-    excludeDirNames?: string[];
-    /**
-     * Extensions we know we can avoid. Each extension
-     * should include the `.` so that we can test for both
-     * `.d.ts.` and `.ts`. If `excludeExtensions` isn't provided it
-     * doesn't try to exclude anything. This only checks against
-     * the filename, not directory names when recursive.
-     */
-    excludeExtensions?: string[];
-}
-export interface FsReaddirItem {
-    absPath: string;
-    relPath: string;
-    isDirectory: boolean;
-    isFile: boolean;
-}
-export interface FsWriteResults {
-    changedContent: boolean;
-    queuedWrite: boolean;
-    ignored: boolean;
-}
-export declare type FsItems = Map<string, FsItem>;
-export interface FsItem {
-    fileText: string;
-    isFile: boolean;
-    isDirectory: boolean;
-    size: number;
-    mtimeMs: number;
-    exists: boolean;
-    queueCopyFileToDest: string;
-    queueWriteToDisk: boolean;
-    queueDeleteFromDisk?: boolean;
-    useCache: boolean;
-}
 export interface HostElement extends HTMLElement {
     connectedCallback?: () => void;
     attributeChangedCallback?: (attribName: string, oldVal: string, newVal: string, namespace: string) => void;
@@ -1104,66 +1063,6 @@ export interface HostElement extends HTMLElement {
     ['s-p']?: Promise<void>[];
     componentOnReady?: () => Promise<this>;
 }
-export interface InMemoryFileSystem {
-    sys?: CompilerSystem;
-    accessData(filePath: string): Promise<{
-        exists: boolean;
-        isDirectory: boolean;
-        isFile: boolean;
-    }>;
-    access(filePath: string): Promise<boolean>;
-    /**
-     * Synchronous!!! Do not use!!!
-     * (Only typescript transpiling is allowed to use)
-     * @param filePath
-     */
-    accessSync(filePath: string): boolean;
-    copyFile(srcFile: string, dest: string): Promise<void>;
-    emptyDirs(dirPaths: string[]): Promise<void>;
-    readdir(dirPath: string, opts?: FsReaddirOptions): Promise<FsReaddirItem[]>;
-    readFile(filePath: string, opts?: FsReadOptions): Promise<string>;
-    /**
-     * Synchronous!!! Do not use!!!
-     * (Only typescript transpiling is allowed to use)
-     * @param filePath
-     */
-    readFileSync(filePath: string, opts?: FsReadOptions): string;
-    remove(itemPath: string): Promise<void>;
-    stat(itemPath: string): Promise<{
-        isFile: boolean;
-        isDirectory: boolean;
-    }>;
-    /**
-     * Synchronous!!! Do not use!!!
-     * (Only typescript transpiling is allowed to use)
-     * @param itemPath
-     */
-    statSync(itemPath: string): {
-        exists: boolean;
-        isFile: boolean;
-        isDirectory: boolean;
-    };
-    writeFile(filePath: string, content: string, opts?: FsWriteOptions): Promise<FsWriteResults>;
-    writeFiles(files: {
-        [filePath: string]: string;
-    } | Map<string, String>, opts?: FsWriteOptions): Promise<FsWriteResults[]>;
-    commit(): Promise<{
-        filesWritten: string[];
-        filesDeleted: string[];
-        filesCopied: string[][];
-        dirsDeleted: string[];
-        dirsAdded: string[];
-    }>;
-    cancelDeleteFilesFromDisk(filePaths: string[]): void;
-    cancelDeleteDirectoriesFromDisk(filePaths: string[]): void;
-    clearDirCache(dirPath: string): void;
-    clearFileCache(filePath: string): void;
-    getItem(itemPath: string): FsItem;
-    getBuildOutputs(): BuildOutput[];
-    clearCache(): void;
-    keys(): string[];
-    getMemoryStats(): string;
-}
 export interface HydrateResults {
     buildId: string;
     diagnostics: Diagnostic[];
@@ -1424,42 +1323,82 @@ export declare type ComponentRuntimeMetaCompact = [
     /** listeners */
     ComponentRuntimeHostListener[]?
 ];
+/**
+ * Runtime metadata for a Stencil component
+ */
 export interface ComponentRuntimeMeta {
+    /**
+     * This number is used to hold a series of bitflags for various features we
+     * support on components. The flags which this value is intended to store are
+     * documented in the {@link CMP_FLAGS} enum.
+     */
     $flags$: number;
+    /**
+     * Just what it says on the tin - the tag name for the component, as set in
+     * the `@Component` decorator.
+     */
     $tagName$: string;
-    $members$?: ComponentRuntimeMembers;
-    $listeners$?: ComponentRuntimeHostListener[];
-    $attrsToReflect$?: [string, string][];
-    $watchers$?: ComponentConstructorWatchers;
-    $lazyBundleId$?: string;
-}
-export interface ComponentRuntimeMembers {
-    [memberName: string]: ComponentRuntimeMember;
-}
-export declare type ComponentRuntimeMember = [
     /**
-     * flags data
+     * A map of the component's members, which could include fields decorated
+     * with `@Prop`, `@State`, etc as well as methods.
      */
-    number,
+    $members$?: ComponentRuntimeMembers;
     /**
-     * attribute name to observe
+     * Information about listeners on the component.
      */
-    string?
-];
-export declare type ComponentRuntimeHostListener = [
+    $listeners$?: ComponentRuntimeHostListener[];
     /**
-     * event flags
+     * Tuples containing information about `@Prop` fields on the component which
+     * are set to be reflected (i.e. kept in sync) as HTML attributes when
+     * updated.
      */
-    number,
+    $attrsToReflect$?: ComponentRuntimeReflectingAttr[];
     /**
-     * event name,
+     * Information about which class members have watchers attached on the component.
      */
-    string,
+    $watchers$?: ComponentConstructorWatchers;
     /**
-     * event method,
+     * A bundle ID used for lazy loading.
      */
-    string
-];
+    $lazyBundleId$?: string;
+}
+/**
+ * A mapping of the names of members on the component to some runtime-specific
+ * information about them.
+ */
+export interface ComponentRuntimeMembers {
+    [memberName: string]: ComponentRuntimeMember;
+}
+/**
+ * A tuple with information about a class member that's relevant at runtime.
+ * The fields are:
+ *
+ * 1. A number used to hold bitflags for component members. The bit flags which
+ * this is intended to store are documented in the {@link MEMBER_FLAGS} enum.
+ * 2. The attribute name to observe.
+ */
+export declare type ComponentRuntimeMember = [number, string?];
+/**
+ * A tuple holding information about a host listener which is relevant at
+ * runtime. The field are:
+ *
+ * 1. A number used to hold bitflags for listeners. The bit flags which this is
+ * intended to store are documented in the {@link LISTENER_FLAGS} enum.
+ * 2. The event name.
+ * 3. The method name.
+ */
+export declare type ComponentRuntimeHostListener = [number, string, string];
+/**
+ * A tuple containing information about props which are "reflected" at runtime,
+ * meaning that HTML attributes on the component instance are kept in sync with
+ * the prop value.
+ *
+ * The fields are:
+ *
+ * 1. the prop name
+ * 2. the prop attribute.
+ */
+export declare type ComponentRuntimeReflectingAttr = [string, string | undefined];
 export declare type ModeBundleId = ModeBundleIds | string;
 export interface ModeBundleIds {
     [modeName: string]: string;
@@ -2271,13 +2210,13 @@ export interface TrackableData {
     component_count?: number;
     arguments: string[];
     targets: string[];
-    task: TaskCommand;
-    duration_ms: number;
+    task: TaskCommand | null;
+    duration_ms: number | undefined;
     packages: string[];
     packages_no_versions?: string[];
-    os_name: string;
-    os_version: string;
-    cpu_model: string;
+    os_name: string | undefined;
+    os_version: string | undefined;
+    cpu_model: string | undefined;
     typescript: string;
     rollup: string;
     system: string;

package/internal/stencil-public-compiler.d.ts

@@ -1,6 +1,6 @@
-import type { JsonDocs } from './stencil-public-docs';
-import type { PrerenderUrlResults } from '../internal';
 import type { ConfigFlags } from '../cli/config-flags';
+import type { PrerenderUrlResults } from '../internal';
+import type { JsonDocs } from './stencil-public-docs';
 export * from './stencil-public-docs';
 /**
  * https://stenciljs.com/docs/config/
@@ -372,7 +372,7 @@ declare type RequireFields<T, K extends keyof T> = T & {
 /**
  * Fields in {@link Config} to make required for {@link ValidatedConfig}
  */
-declare type StrictConfigFields = 'flags' | 'logger' | 'outputTargets' | 'sys' | 'testing';
+declare type StrictConfigFields = 'flags' | 'logger' | 'outputTargets' | 'rootDir' | 'sys' | 'testing';
 /**
  * A version of {@link Config} that makes certain fields required. This type represents a valid configuration entity.
  * When a configuration is received by the user, it is a bag of unverified data. In order to make stricter guarantees
@@ -1698,6 +1698,27 @@ export interface OutputTargetDist extends OutputTargetBase {
     buildDir?: string;
     dir?: string;
     collectionDir?: string | null;
+    /**
+     * When `true` this flag will transform aliased import paths defined in
+     * a project's `tsconfig.json` to relative import paths in the compiled output's
+     * `dist-collection` bundle if it is generated (i.e. `collectionDir` is set).
+     *
+     * Paths will be left in aliased format if `false` or `undefined`.
+     *
+     * @example
+     * // tsconfig.json
+     * {
+     *   paths: {
+     *     "@utils/*": ['/src/utils/*']
+     *   }
+     * }
+     *
+     * // Source file
+     * import * as dateUtils from '@utils/date-utils';
+     * // Output file
+     * import * as dateUtils from '../utils/date-utils';
+     */
+    transformAliasedImportPathsInCollection?: boolean | null;
     typesDir?: string;
     esmLoaderPath?: string;
     copy?: CopyTask[];
@@ -1709,6 +1730,26 @@ export interface OutputTargetDistCollection extends OutputTargetBase {
     empty?: boolean;
     dir: string;
     collectionDir: string;
+    /**
+     * When `true` this flag will transform aliased import paths defined in
+     * a project's `tsconfig.json` to relative import paths in the compiled output.
+     *
+     * Paths will be left in aliased format if `false` or `undefined`.
+     *
+     * @example
+     * // tsconfig.json
+     * {
+     *   paths: {
+     *     "@utils/*": ['/src/utils/*']
+     *   }
+     * }
+     *
+     * // Source file
+     * import * as dateUtils from '@utils/date-utils';
+     * // Output file
+     * import * as dateUtils from '../utils/date-utils';
+     */
+    transformAliasedImportPaths?: boolean | null;
 }
 export interface OutputTargetDistTypes extends OutputTargetBase {
     type: 'dist-types';
@@ -2134,13 +2175,6 @@ export interface FsStats {
     ctime: Date;
     birthtime: Date;
 }
-export interface FsWriteOptions {
-    inMemoryOnly?: boolean;
-    clearFileCache?: boolean;
-    immediateWrite?: boolean;
-    useCache?: boolean;
-    outputTargetType?: string;
-}
 export interface Compiler {
     build(): Promise<CompilerBuildResults>;
     createWatcher(): Promise<CompilerWatcher>;

package/internal/stencil-public-runtime.d.ts

@@ -221,7 +221,8 @@ export declare type ErrorHandler = (err: any, element?: HTMLElement) => void;
  */
 export declare const setMode: (handler: ResolutionHandler) => void;
 /**
- * getMode
+ * `getMode()` is used for libraries which provide multiple "modes" for styles.
+ * @param ref a reference to the node to get styles for
  */
 export declare function getMode<T = string | undefined>(ref: any): T;
 export declare function setPlatformHelpers(helpers: {
@@ -234,6 +235,8 @@ export declare function setPlatformHelpers(helpers: {
 /**
  * Get the base path to where the assets can be found. Use `setAssetPath(path)`
  * if the path needs to be customized.
+ * @param path the path to use in calculating the asset path. this value will be
+ * used in conjunction with the base asset path
  */
 export declare function getAssetPath(path: string): string;
 /**
@@ -246,18 +249,22 @@ export declare function getAssetPath(path: string): string;
  * `setAssetPath(document.currentScript.src)`, or using a bundler's replace plugin to
  * dynamically set the path at build time, such as `setAssetPath(process.env.ASSET_PATH)`.
  * But do note that this configuration depends on how your script is bundled, or lack of
- * bunding, and where your assets can be loaded from. Additionally custom bundling
+ * bundling, and where your assets can be loaded from. Additionally custom bundling
  * will have to ensure the static assets are copied to its build directory.
+ * @param path the asset path to set
  */
 export declare function setAssetPath(path: string): string;
 /**
- * getElement
+ * Retrieve a Stencil element for a given reference
+ * @param ref the ref to get the Stencil element for
  */
 export declare function getElement(ref: any): HTMLStencilElement;
 /**
  * Schedules a new render of the given instance or element even if no state changed.
  *
- * Notice `forceUpdate()` is not syncronous and might perform the DOM render in the next frame.
+ * Notice `forceUpdate()` is not synchronous and might perform the DOM render in the next frame.
+ *
+ * @param ref the node/element to force the re-render of
  */
 export declare function forceUpdate(ref: any): void;
 /**
@@ -272,6 +279,8 @@ export interface HTMLStencilElement extends HTMLElement {
  * in the best moment to perform DOM mutation without causing layout thrashing.
  *
  * For further information: https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing
+ *
+ * @param task the DOM-write to schedule
  */
 export declare function writeTask(task: RafCallback): void;
 /**
@@ -279,6 +288,8 @@ export declare function writeTask(task: RafCallback): void;
  * in the best moment to perform DOM reads without causing layout thrashing.
  *
  * For further information: https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing
+ *
+ * @param task the DOM-read to schedule
  */
 export declare function readTask(task: RafCallback): void;
 /**