@stencil/core 5.0.0-beta.3 → 5.0.0-beta.30

package/dist/compiler/browser.d.ts

@@ -1,11 +1,77 @@
 import ts from "typescript";
 import "rolldown";
 //#region src/declarations/stencil-public-docs.d.ts
+/**
+ * A descriptor for a single JSDoc tag found in a block comment
+ */
+interface JsonDocsTag {
+  /**
+   * The tag name (immediately following the '@')
+   */
+  name: string;
+  /**
+   * The description that immediately follows the tag name
+   */
+  text?: string;
+}
 interface JsonDocMethodParameter {
   name: string;
   type: string;
   docs: string;
 }
+/**
+ * A descriptor for a Custom State defined via @AttachInternals({ states: {...} })
+ *
+ * Custom states are exposed via the ElementInternals.states CustomStateSet
+ * and can be targeted with the CSS `:state()` pseudo-class.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet
+ */
+interface JsonDocsCustomState {
+  /**
+   * The name of the custom state (without dashes)
+   */
+  name: string;
+  /**
+   * The initial/default value of the state
+   */
+  initialValue: boolean;
+  /**
+   * A textual description of the custom state
+   */
+  docs: string;
+}
+/**
+ * Represents a parsed block comment in a CSS, Sass, etc. file for a custom property.
+ */
+interface StyleDoc {
+  /**
+   * The name of the CSS property
+   */
+  name: string;
+  /**
+   * The user-defined description of the CSS property
+   */
+  docs: string;
+  /**
+   * The JSDoc-style annotation (e.g. `@prop`) that was used in the block comment to detect the comment.
+   * Used to inform Stencil where the start of a new property's description starts (and where the previous description
+   * ends).
+   */
+  annotation: 'prop';
+  /**
+   * The Stencil style-mode that is associated with this property.
+   */
+  mode: string | undefined;
+  /**
+   * The CSS `syntax` descriptor, if this property was registered via a native `@property` at-rule.
+   */
+  syntax?: string;
+  /**
+   * The `initial-value` descriptor, if this property was registered via a native `@property` at-rule.
+   */
+  default?: string;
+}
 //#endregion
 //#region src/declarations/stencil-public-runtime.d.ts
 type ListenTargetOptions = 'body' | 'document' | 'window';
@@ -25,7 +91,7 @@ interface CompilerSystem {
   name: 'node' | 'in-memory';
   version: string;
   events?: BuildEvents;
-  details?: SystemDetails;
+  details: SystemDetails;
   /**
    * Add a callback which will be ran when destroy() is called.
    */
@@ -38,14 +104,15 @@ interface CompilerSystem {
    * SYNC! Always returns a boolean, does not throw.
    */
   accessSync(p: string): boolean;
-  applyGlobalPatch?(fromDir: string): Promise<void>;
   applyPrerenderGlobalPatch?(opts: {
     devServerHostUrl: string;
     window: any;
   }): void;
-  cacheStorage?: CacheStorage;
-  checkVersion?: (logger: Logger, currentVersion: string) => Promise<() => void>;
-  copy?(copyTasks: Required<CopyTask>[], srcDir: string): Promise<CopyResults>;
+  /**
+   * Check npm for a newer Stencil version. Resolves a function that logs the result.
+   */
+  checkVersion(logger: Logger, currentVersion: string): Promise<() => void>;
+  copy(copyTasks: Required<CopyTask>[], srcDir: string): Promise<CopyResults>;
   /**
    * Always returns a boolean if the files were copied or not. Does not throw.
    */
@@ -70,7 +137,7 @@ interface CompilerSystem {
   /**
    * Each platform has a different way to dynamically import modules.
    */
-  dynamicImport?(p: string): Promise<any>;
+  dynamicImport(p: string): Promise<any>;
   /**
    * Creates the worker controller for the current system.
    *
@@ -84,20 +151,14 @@ interface CompilerSystem {
    * process.exit()
    */
   exit(exitCode: number): Promise<void>;
-  /**
-   * Optionally provide a fetch() function rather than using the built-in fetch().
-   * First arg is a url string or Request object (RequestInfo).
-   * Second arg is the RequestInit. Returns the Response object
-   */
-  fetch?(input: string | any, init?: any): Promise<any>;
   /**
    * Generates a sha1 digest encoded as HEX
    */
-  generateContentHash?(content: string | any, length?: number): Promise<string>;
+  generateContentHash(content: string | any, length?: number): Promise<string>;
   /**
    * Generates a sha1 digest encoded as HEX from a file path
    */
-  generateFileHash?(filePath: string | any, length?: number): Promise<string>;
+  generateFileHash(filePath: string | any, length?: number): Promise<string>;
   /**
    * Get the current directory.
    */
@@ -106,7 +167,6 @@ interface CompilerSystem {
    * The compiler's executing path.
    */
   getCompilerExecutingPath(): string;
-  getEnvironmentVar?(key: string): string;
   /**
    * Gets the absolute file path when for a dependency module.
    */
@@ -145,11 +205,7 @@ interface CompilerSystem {
    * Normalize file system path.
    */
   normalizePath(p: string): string;
-  onProcessInterrupt?(cb: () => void): void;
-  parseYarnLockFile?: (content: string) => {
-    type: 'success' | 'merge' | 'conflict';
-    object: any;
-  };
+  onProcessInterrupt(cb: () => void): void;
   platformPath: PlatformPath;
   /**
    * All return paths are full normalized paths, not just the basenames. Always returns an array, does not throw.
@@ -185,6 +241,9 @@ interface CompilerSystem {
    * Rename old path to new path. Does not throw.
    */
   rename(oldPath: string, newPath: string): Promise<CompilerSystemRenameResults>;
+  /**
+   * Assigned by the compiler. Used by plugins (e.g. `@stencil/sass`) to resolve `~` imports.
+   */
   resolveModuleId?(opts: ResolveModuleIdOptions): Promise<ResolveModuleIdResults>;
   resolvePath(p: string): string;
   /**
@@ -367,6 +426,7 @@ interface CompilerBuildResults {
   buildId: number;
   componentGraph?: BuildResultsComponentGraph;
   components: ComponentCompilerMeta[];
+  cssOnlyComponents: ComponentCompilerMeta[];
   diagnostics: Diagnostic[];
   dirsAdded: string[];
   dirsDeleted: string[];
@@ -383,6 +443,15 @@ interface CompilerBuildResults {
   namespace: string;
   fsNamespace: string;
   outputs: BuildOutput[];
+  /**
+   * Absolute paths to every global stylesheet, in cascade order: each `global-style` output
+   * target's compiled CSS in the order those targets are declared in `config.outputTargets` - or,
+   * with none configured, the generated `{fsNamespace}.css` holding Stencil's auto-placed CSS (when
+   * emitted). Unlike `outputs`, which groups files by type and sorts them alphabetically, this
+   * preserves author-intended order for consumers like the dev-server's auto-generated component
+   * preview.
+   */
+  globalStyleFiles: string[];
   rootDir: string;
   srcDir: string;
   timestamp: string;
@@ -398,6 +467,7 @@ interface HotModuleReplacement {
   componentsUpdated?: string[];
   excludeHmr?: string[];
   externalStylesUpdated?: string[];
+  globalStylesUpdated?: HmrGlobalStyleUpdate[];
   imagesUpdated?: string[];
   indexHtmlUpdated?: boolean;
   inlineStylesUpdated?: HmrStyleUpdate[];
@@ -412,6 +482,15 @@ interface HmrStyleUpdate {
   styleTag: string;
   styleText: string;
 }
+/**
+ * A live-reload update for a `global-style` output target's CSS. Applied on
+ * the client by matching `fileName` against the `<link>` that loads it and
+ * inserting/updating an adjacent `<style>` override
+ */
+interface HmrGlobalStyleUpdate {
+  fileName: string;
+  styleText: string;
+}
 type BuildOnEventRemove = () => boolean;
 interface BuildEvents extends BuildOnEvents, BuildEmitEvents {
   unsubscribeAll(): void;
@@ -559,7 +638,9 @@ interface CopyTask {
   /**
    * Additional glob patterns to exclude from the copy operation, merged with
    * the built-in defaults: `__mocks__`, `__fixtures__`, `dist`, hidden dirs,
-   * `.ds_store`, `.gitignore`, `desktop.ini`, `thumbs.db`.
+   * `.ds_store`, `.gitignore`, `desktop.ini`, `thumbs.db`. For a directory
+   * `src`, patterns match paths relative to that directory; an explicitly
+   * named `src` file is never ignored.
    */
   ignore?: string[];
   /**
@@ -689,10 +770,6 @@ interface Diagnostic {
   relFilePath?: string | undefined;
   type: string;
 }
-interface CacheStorage {
-  get(key: string): Promise<any>;
-  set(key: string, value: any): Promise<void>;
-}
 interface LazyRequire {
   ensure(fromDir: string, moduleIds: string[]): Promise<Diagnostic[]>;
   require(fromDir: string, moduleId: string): any;
@@ -839,13 +916,19 @@ interface TranspileOptions {
    * that the specified flags take effect for this component at runtime.
    */
   buildOverrides?: BuildOverrides;
+  /**
+   * When `true`, a `.css`/`.scss` transpile also collects CSS custom-property docs
+   * onto {@link TranspileResults.styleDocs}. Off by default, since it costs an extra parse
+   * of the style text.
+   */
+  docs?: boolean;
 }
 /**
  * Keys of {@link BuildConditionals} that can be meaningfully overridden at
  * transpile time — config-driven flags that are not derived from component
  * scanning or runtime environment detection.
  */
-type BuildOverrideKeys = 'hotModuleReplacement' | 'signalBacking' | 'vdomSignals' | 'lightDomPatches' | 'slotChildNodes' | 'slotCloneNode' | 'slotDomMutations' | 'slotTextContent' | 'lifecycleDOMEvents' | 'initializeNextTick';
+type BuildOverrideKeys = 'isDev' | 'isTesting' | 'hotModuleReplacement' | 'signalBacking' | 'vdomSignals' | 'lightDomPatches' | 'slotChildNodes' | 'slotCloneNode' | 'slotDomMutations' | 'slotTextContent' | 'lifecycleDOMEvents' | 'initializeNextTick';
 /**
  * Subset of Stencil's BUILD feature flags that can be overridden at transpile
  * time. Derived from {@link BuildConditionals} via `Pick` so the field list
@@ -864,6 +947,7 @@ interface TranspileResults {
   inputFilePath: string;
   map: any;
   outputFilePath: string;
+  styleDocs?: StyleDoc[];
 }
 //#endregion
 //#region src/declarations/stencil-private.d.ts
@@ -1070,7 +1154,7 @@ interface ComponentCompilerMeta extends ComponentCompilerFeatures {
    * Custom states to initialize on the ElementInternals.states CustomStateSet.
    * These are defined via @AttachInternals({ states: {...} }).
    */
-  attachInternalsCustomStates: ComponentCompilerCustomState[];
+  attachInternalsCustomStates: JsonDocsCustomState[];
   componentClassName: string;
   /**
    * A list of web component tag names that are either:
@@ -1140,7 +1224,7 @@ interface ComponentCompilerMeta extends ComponentCompilerFeatures {
   sourceFilePath: string;
   sourceMapPath: string;
   states: ComponentCompilerState[];
-  styleDocs: CompilerStyleDoc[];
+  styleDocs: StyleDoc[];
   styles: StyleCompiler[];
   globalStyles: ComponentGlobalStyle[];
   tagName: string;
@@ -1324,20 +1408,6 @@ interface ComponentCompilerState {
  * Custom states are exposed via the ElementInternals.states CustomStateSet
  * and can be targeted with the CSS :state() pseudo-class.
  */
-interface ComponentCompilerCustomState {
-  /**
-   * The name of the custom state (without dashes)
-   */
-  name: string;
-  /**
-   * The initial value of the state
-   */
-  initialValue: boolean;
-  /**
-   * Optional JSDoc description for the state
-   */
-  docs: string;
-}
 /**
  * Representation of JSDoc that is pulled off a node in the AST
  */
@@ -1349,44 +1419,7 @@ interface CompilerJsDoc {
   /**
    * Tags included in the JSDoc
    */
-  tags: CompilerJsDocTagInfo[];
-}
-/**
- * Representation of a tag that exists in a JSDoc
- */
-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;
-}
-/**
- * The (internal) representation of a CSS block comment in a CSS, Sass, etc. file. This data structure is used during
- * the initial compilation phases of Stencil, as a piece of {@link ComponentCompilerMeta}.
- */
-interface CompilerStyleDoc {
-  /**
-   * The name of the CSS property
-   */
-  name: string;
-  /**
-   * The user-defined description of the CSS property
-   */
-  docs: string;
-  /**
-   * The JSDoc-style annotation (e.g. `@prop`) that was used in the block comment to detect the comment.
-   * Used to inform Stencil where the start of a new property's description starts (and where the previous description
-   * ends).
-   */
-  annotation: 'prop';
-  /**
-   * The Stencil style-mode that is associated with this property.
-   */
-  mode: string;
+  tags: JsonDocsTag[];
 }
 interface CompilerAssetDir {
   absolutePath?: string;
@@ -1526,7 +1559,7 @@ declare const transpileSync: (code: string, opts?: TranspileOptions) => Transpil
  * @param cmp the metadata for the component that a type definition string is generated for
  * @param typeImportData locally/imported/globally used type names, which may be used to prevent naming collisions
  * @param areTypesInternal `true` if types being generated are for a project's internal purposes, `false` otherwise
- * @param signalBacking `true` if the component is using signal backing for its props; includes the signals map on the element interface
+ * @param signalBacking `true` if the component is using signal backing for its props; includes the signals map on the element interface and unions JSX prop types with `ReadonlySignal<T>`
  * @returns the generated types string alongside additional metadata
  */
 declare const generateComponentTypes: (cmp: ComponentCompilerMeta, typeImportData: TypesImportData, areTypesInternal: boolean, signalBacking?: boolean) => TypesModule;