@stencil/core 2.18.0 → 2.19.0

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,7 +1,6 @@
-import { BuildResultsComponentGraph } from '.';
-import type { BuildEvents, BuildLog, CompilerBuildResults, CompilerBuildStart, CompilerFsStats, CompilerRequestResponse, CompilerSystem, Config, CopyResults, DevServerConfig, DevServerEditor, Diagnostic, Logger, LoggerTimeSpan, OptimizeCssInput, OptimizeCssOutput, OutputTargetWww, PageReloadStrategy, PrerenderConfig, StyleDoc, LoggerLineUpdater, TaskCommand } from './stencil-public-compiler';
-import type { ComponentInterface, ListenOptions, ListenTargetOptions, VNode, VNodeData } from './stencil-public-runtime';
 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;
     mappings: string;
@@ -785,12 +784,30 @@ export interface ComponentCompilerMethod extends ComponentCompilerStaticMethod {
 export interface ComponentCompilerState {
     name: string;
 }
+/**
+ * Representation of JSDoc that is pulled off a node in the AST
+ */
 export interface CompilerJsDoc {
+    /**
+     * The text associated with the JSDoc
+     */
     text: string;
+    /**
+     * Tags included in the JSDoc
+     */
     tags: CompilerJsDocTagInfo[];
 }
+/**
+ * Representation of a tag that exists in a JSDoc
+ */
 export interface CompilerJsDocTagInfo {
+    /**
+     * The name of the tag - e.g. `@deprecated`
+     */
     name: string;
+    /**
+     * Additional text that is associated with the tag - e.g. `@deprecated use v2 of this API`
+     */
     text?: string;
 }
 export interface CompilerStyleDoc {
@@ -824,6 +841,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[];
 }
@@ -833,9 +854,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 {
@@ -1320,42 +1341,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;
@@ -2163,25 +2224,26 @@ export declare type TelemetryCallback = (...args: any[]) => void | Promise<void>
  * The model for the data that's tracked.
  */
 export interface TrackableData {
-    yarn: boolean;
-    component_count?: number;
     arguments: string[];
-    targets: string[];
-    task: TaskCommand;
-    duration_ms: number;
+    build: string;
+    component_count?: number;
+    config: Config;
+    cpu_model: string | undefined;
+    duration_ms: number | undefined;
+    has_app_pwa_config: boolean;
+    is_browser_env: boolean;
+    os_name: string | undefined;
+    os_version: string | undefined;
     packages: string[];
     packages_no_versions?: string[];
-    os_name: string;
-    os_version: string;
-    cpu_model: string;
-    typescript: string;
     rollup: string;
+    stencil: string;
     system: string;
     system_major?: string;
-    build: string;
-    stencil: string;
-    has_app_pwa_config: boolean;
-    config: Config;
+    targets: string[];
+    task: TaskCommand | null;
+    typescript: string;
+    yarn: boolean;
 }
 /**
  * Used as the object sent to the server. Value is the data tracked.

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/
@@ -512,6 +512,10 @@ export interface StencilDevServerConfig {
 export interface DevServerConfig extends StencilDevServerConfig {
     browserUrl?: string;
     devServerDir?: string;
+    /**
+     * A list of glob patterns like `subdir/*.js`  to exclude from hot-module
+     * reloading updates.
+     */
     excludeHmr?: string[];
     historyApiFallback?: HistoryApiFallback;
     openBrowser?: boolean;
@@ -1850,6 +1854,12 @@ export interface OutputTargetBaseNext {
 export interface OutputTargetDistCustomElements extends OutputTargetBaseNext {
     type: 'dist-custom-elements';
     empty?: boolean;
+    /**
+     * Triggers the following behaviors when enabled:
+     * 1. All `@stencil/core/*` module references are treated as external during bundling.
+     * 2. File names are not hashed.
+     * 3. File minification will follow the behavior defined at the root of the Stencil config.
+     */
     externalRuntime?: boolean;
     copy?: CopyTask[];
     inlineDynamicImports?: boolean;

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

@@ -42,6 +42,26 @@ export interface JsonDocsValue {
     value?: string;
     type: string;
 }
+/**
+ * A mapping of file names to their contents.
+ *
+ * This type is meant to be used when reading one or more usage markdown files associated with a component. For the
+ * given directory structure:
+ * ```
+ * src/components/my-component
+ * ├── my-component.tsx
+ * └── usage
+ *     ├── bar.md
+ *     └── foo.md
+ * ```
+ * an instance of this type would include the name of the markdown file, mapped to its contents:
+ * ```ts
+ * {
+ *   'bar': STRING_CONTENTS_OF_BAR.MD
+ *   'foo': STRING_CONTENTS_OF_FOO.MD
+ * }
+ * ```
+ */
 export interface JsonDocsUsage {
     [key: string]: string;
 }

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

@@ -221,7 +221,9 @@ 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
+ * @returns the current mode or undefined, if not found
  */
 export declare function getMode<T = string | undefined>(ref: any): T;
 export declare function setPlatformHelpers(helpers: {
@@ -234,6 +236,9 @@ 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
+ * @returns the base path
  */
 export declare function getAssetPath(path: string): string;
 /**
@@ -246,22 +251,29 @@ 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
+ * @returns the set path
  */
 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
+ * @returns a reference to the element
  */
 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;
 /**
  * getRenderingRef
+ * @returns the rendering ref
  */
 export declare function getRenderingRef(): any;
 export interface HTMLStencilElement extends HTMLElement {
@@ -272,6 +284,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 +293,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;
 /**