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

package/dist/testing/index.d.mts

@@ -394,6 +394,11 @@ interface JsonDocsComponent {
    * A deprecation reason/description found following a `@deprecated` tag
    */
   deprecation?: string;
+  /**
+   * `true` if this is a "CSS-only component"
+   * discovered in .css file via `@component`-marked JSDoc block
+   */
+  cssOnly?: boolean;
 }
 interface JsonDocsDependencyGraph {
   [tagName: string]: string[];
@@ -553,6 +558,16 @@ interface JsonDocsStyle {
    * The annotation used in the JSDoc of the style (e.g. `@prop`)
    */
   annotation: string;
+  /**
+   * The CSS `syntax` descriptor for a custom property, if it was registered via a native
+   * `@property` at-rule (e.g. `"<length>"`).
+   */
+  syntax?: string;
+  /**
+   * The `initial-value` descriptor for a custom property, if it was registered via a native
+   * `@property` at-rule.
+   */
+  default?: string;
   /**
    * The mode associated with the style
    */
@@ -639,6 +654,14 @@ interface StyleDoc {
    * 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
@@ -922,6 +945,15 @@ interface StencilConfig {
    * @default false
    */
   generateExportMaps?: boolean;
+  /**
+   * Set to `false` to disable discovery of "CSS-only components" - pure-CSS custom-element
+   * definitions marked with a `@component` JSDoc tag in `.css` files under `srcDir`. No JS
+   * class, never registered via `customElements.define()` - just a documented,
+   * type-checked tag name and its CSS custom properties/attribute variants.
+   *
+   * Defaults to `true`.
+   */
+  enableCssOnlyComponents?: boolean;
   /**
    * The namespace config is a string representing a namespace for the app.
    * For apps that are not meant to be a library of reusable components,
@@ -964,7 +996,7 @@ interface StencilConfig {
    */
   transformAliasedImportPaths?: boolean;
   /**
-   * Passes custom configuration down to the "@rolldown/plugin-node-resolve" that Stencil uses under the hood.
+   * Passes custom configuration to Rolldown's module resolution (its `resolve` option), e.g. `alias`.
    * For further information: https://stenciljs.com/docs/module-bundling
    */
   nodeResolve?: NodeResolveConfig;
@@ -1244,11 +1276,6 @@ interface Config extends StencilConfig {
   tsWatchOptions?: any;
   _isValidated?: boolean;
   _isTesting?: boolean;
-  /**
-   * Internal flag set when --docs CLI flag is used.
-   * Forces docs output targets to build even in dev mode.
-   */
-  _docsFlag?: boolean;
   /**
    * Whether running in a CI environment (disables interactive features, adjusts worker count)
    */
@@ -1531,7 +1558,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.
    */
@@ -1544,14 +1571,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.
    */
@@ -1576,7 +1604,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.
    *
@@ -1590,20 +1618,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.
    */
@@ -1612,7 +1634,6 @@ interface CompilerSystem {
    * The compiler's executing path.
    */
   getCompilerExecutingPath(): string;
-  getEnvironmentVar?(key: string): string;
   /**
    * Gets the absolute file path when for a dependency module.
    */
@@ -1651,11 +1672,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.
@@ -1691,6 +1708,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;
   /**
@@ -1873,6 +1893,7 @@ interface CompilerBuildResults {
   buildId: number;
   componentGraph?: BuildResultsComponentGraph;
   components: ComponentCompilerMeta[];
+  cssOnlyComponents: ComponentCompilerMeta[];
   diagnostics: Diagnostic[];
   dirsAdded: string[];
   dirsDeleted: string[];
@@ -1889,6 +1910,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;
@@ -1904,6 +1934,7 @@ interface HotModuleReplacement {
   componentsUpdated?: string[];
   excludeHmr?: string[];
   externalStylesUpdated?: string[];
+  globalStylesUpdated?: HmrGlobalStyleUpdate[];
   imagesUpdated?: string[];
   indexHtmlUpdated?: boolean;
   inlineStylesUpdated?: HmrStyleUpdate[];
@@ -1918,6 +1949,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;
@@ -2072,7 +2112,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[];
   /**
@@ -2310,7 +2352,7 @@ interface OutputTargetCollection extends OutputTargetBaseNext {
    * 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`.
+   * Paths will be left in aliased format if `false`. Defaults to `true`.
    *
    * @example
    * // tsconfig.json
@@ -2412,11 +2454,11 @@ interface OutputTargetGlobalStyle extends OutputTargetBaseNext {
    * Controls whether this global stylesheet is injected into component shadow DOMs
    * as a constructable stylesheet at runtime.
    *
-   * - `'none'` (default): Don't inject - stylesheet must be loaded externally (e.g., via `<link>`)
+   * - `'none'`: Don't inject - stylesheet must be loaded externally (e.g., via `<link>`)
    * - `'client'`: Inject only in client builds, not SSR (reduces SSR output size)
    * - `'all'`: Inject in both client and SSR builds
    *
-   * @default 'none'
+   * @default 'client' when the stylesheet comes from `globalStyle` (or an auto-detected `src/global.*`), 'none' when `input` is set
    */
   inject?: 'none' | 'client' | 'all';
 }
@@ -2474,6 +2516,10 @@ interface OutputTargetSsr extends OutputTargetBase {
    */
   cjs?: boolean;
 }
+/**
+ * Compiles the SSR hydrate app to a WASM plugin (via `extism-js`/QuickJS-ng) that can run
+ * outside of Node
+ */
 interface OutputTargetSsrWasm extends OutputTargetBase {
   type: 'ssr-wasm';
   /** Output directory. @default 'dist/ssr-wasm' */
@@ -2584,9 +2630,11 @@ interface OutputTargetDocsCustomElementsManifest extends OutputTargetBase {
   type: 'docs-custom-elements-manifest';
   /**
    * The file path where the custom-elements.json manifest will be written.
-   * Defaults to 'custom-elements.json' in the root directory.
+   * Defaults to 'dist/custom-elements.json'.
+   *
+   * The `customElements` field of the project's `package.json` is set to this path.
    */
-  file: string;
+  file?: string;
   strict?: boolean;
 }
 interface OutputTargetDocsCustom extends OutputTargetBase {
@@ -2611,7 +2659,7 @@ interface OutputTargetDocsAgentSkill extends OutputTargetBase {
   /**
    * The skill's name, used in the `SKILL.md` frontmatter.
    *
-   * Defaults to a kebab-cased form of {@link Config.namespace}.
+   * Defaults to {@link Config.namespace}, lowercased, with anything other than letters and numbers replaced by `-`.
    */
   name?: string;
   /**
@@ -2674,10 +2722,8 @@ interface OutputTargetStandalone extends OutputTargetBaseNext {
   type: 'standalone';
   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.
+   * When `true`, all `@stencil/core/*` module references are treated as external
+   * during bundling rather than being included in the generated output.
    *
    * @default false
    */
@@ -2741,8 +2787,10 @@ interface OutputTargetBase {
    * This improves dev build times by not generating production-only artifacts.
    *
    * Defaults vary by output target type:
-   * - `loader-bundle`: `false` (always builds)
-   * - `standalone`: `true` (skips in dev)
+   * - `loader-bundle`: `true` (skips the npm distribution files; the browser bundle always builds)
+   * - `standalone`: `true` if `loader-bundle` is also configured, otherwise `false`
+   * - `types`, `collection`, `ssr-wasm`: `true` (skips in dev)
+   * - `assets`, `global-style`: `false` (always runs)
    * - `ssr`: `true` (skips in dev, unless `devServer.ssr` is enabled)
    * - `docs-*`: `true` (skips in dev)
    * - `custom`: `true` (skips in dev)
@@ -2912,10 +2960,6 @@ interface Diagnostic {
   relFilePath?: string | undefined;
   type: string;
 }
-interface CacheStorage {
-  get(key: string): Promise<any>;
-  set(key: string, value: any): Promise<void>;
-}
 /**
  * Input for CSS optimization functions, including the input CSS
  * string and a few boolean options which turn on or off various
@@ -2963,8 +3007,35 @@ interface LazyRequire {
   require(fromDir: string, moduleId: string): any;
   getModulePath(fromDir: string, moduleId: string): string;
 }
+/**
+ * A Stencil `resolveId`/`load`/`transform` plugin, as accepted by {@link StencilConfig.plugins}.
+ */
+interface Plugin$1 {
+  name?: string;
+  pluginType?: string;
+  load?: (id: string, context: PluginCtx) => Promise<string> | string;
+  resolveId?: (importee: string, importer: string, context: PluginCtx) => Promise<string> | string;
+  transform?: (sourceText: string, id: string, context: PluginCtx) => Promise<PluginTransformResults> | PluginTransformResults;
+}
+type PluginTransformResults = PluginTransformationDescriptor | string | null;
+interface PluginTransformationDescriptor {
+  code?: string;
+  map?: string;
+  id?: string;
+  diagnostics?: Diagnostic[];
+  dependencies?: string[];
+}
+interface PluginCtx {
+  config: Config;
+  sys: CompilerSystem;
+  fs: InMemoryFileSystem;
+  cache: Cache;
+  diagnostics: Diagnostic[];
+}
 //#endregion
 //#region src/declarations/stencil-private.d.ts
+/** Build-time virtual `@import`s a `global-style` input can use to place Stencil-generated CSS. */
+type StencilVirtualImport = 'stencil-hydrate' | 'stencil-component-globals' | 'stencil-css-components';
 interface SourceMap$1 {
   file: string;
   mappings: string;
@@ -3103,6 +3174,7 @@ interface BuildCtx {
   esmComponentBundle: ReadonlyArray<BundleModule>;
   commonJsComponentBundle: ReadonlyArray<BundleModule>;
   components: ComponentCompilerMeta[];
+  cssOnlyComponents: ComponentCompilerMeta[];
   componentGraph: Map<string, string[]>;
   config: ValidatedConfig;
   createTimeSpan(msg: string, debug?: boolean): LoggerTimeSpan;
@@ -3151,6 +3223,9 @@ interface BuildCtx {
    */
   stylesPromise: Promise<string>;
   stylesUpdated: BuildStyleUpdate[];
+  globalStylesUpdated: BuildGlobalStyleLinkUpdate[];
+  /** Absolute path of the generated `{fsNamespace}.css`, when this build emitted one */
+  stencilCssFile?: string;
   timeSpan: LoggerTimeSpan;
   timestamp: string;
   transpileBuildCount: number;
@@ -3163,6 +3238,14 @@ interface BuildStyleUpdate {
   styleText: string;
   styleMode: string;
 }
+/**
+ * A live-reload update for a `global-style` output target's CSS, matched on
+ * the client by `fileName` against the `<link>`
+ */
+interface BuildGlobalStyleLinkUpdate {
+  fileName: string;
+  styleText: string;
+}
 type BuildTask = any;
 interface CompilerBuildStats {
   timestamp: string;
@@ -3304,6 +3387,12 @@ interface CompilerCtx {
   cssModuleImports: Map<string, string[]>;
   /** Cache of built global styles, keyed by input file path */
   globalStyleCache: Map<string, string>;
+  /** Cache of discovered CSS-only components from the last scan, keyed by absolute .css file path */
+  cssOnlyComponentsCache: Map<string, ComponentCompilerMeta[]>;
+  /** Contents of the last auto-placed `stencil-*` CSS, used to detect changes for HMR */
+  stencilCss?: string;
+  /** Virtual imports found in each built global style (post-preprocessing), keyed by input path */
+  globalStyleVirtualImports: Map<string, Set<StencilVirtualImport>>;
   collections: CollectionCompilerMeta[];
   compilerOptions: any;
   events: BuildEvents;
@@ -3449,7 +3538,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:
@@ -3519,7 +3608,7 @@ interface ComponentCompilerMeta extends ComponentCompilerFeatures {
   sourceFilePath: string;
   sourceMapPath: string;
   states: ComponentCompilerState[];
-  styleDocs: CompilerStyleDoc[];
+  styleDocs: StyleDoc[];
   styles: StyleCompiler[];
   globalStyles: ComponentGlobalStyle[];
   tagName: string;
@@ -3722,20 +3811,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
  */
@@ -3747,44 +3822,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;
@@ -3953,28 +3991,6 @@ interface Module {
   hasVdomXlink: boolean;
   hasSignalsImport: boolean;
 }
-interface Plugin$1 {
-  name?: string;
-  pluginType?: string;
-  load?: (id: string, context: PluginCtx) => Promise<string> | string;
-  resolveId?: (importee: string, importer: string, context: PluginCtx) => Promise<string> | string;
-  transform?: (sourceText: string, id: string, context: PluginCtx) => Promise<PluginTransformResults> | PluginTransformResults;
-}
-type PluginTransformResults = PluginTransformationDescriptor | string | null;
-interface PluginTransformationDescriptor {
-  code?: string;
-  map?: string;
-  id?: string;
-  diagnostics?: Diagnostic[];
-  dependencies?: string[];
-}
-interface PluginCtx {
-  config: Config;
-  sys: CompilerSystem;
-  fs: InMemoryFileSystem;
-  cache: Cache;
-  diagnostics: Diagnostic[];
-}
 interface PrerenderUrlResults {
   anchorUrls: string[];
   diagnostics: Diagnostic[];
@@ -4926,4 +4942,4 @@ declare const Host: {};
 //#region src/testing/platform/index.d.ts
 declare const setMode: (handler: (elm: any) => string | undefined | null) => void;
 //#endregion
-export { Build, Env, Fragment, Host, Mixin, ReactiveControllerHost, type SpecPage, createEvent, createTestingSystem, forceUpdate, getAssetPath, getElement, getHostRef, getMode, getRenderingRef, h, mockCompilerSystem, mockComponentMeta, mockConfig, mockDocument, mockLoadConfigInit, mockLogger, mockModule, mockValidatedConfig, mockWindow, newSpecPage, readTask, registerHost, registerInstance, setAssetPath, setErrorHandler, setMode, setupConsoleMocker, shuffleArray, writeTask };
+export { Build, Env, Fragment, Host, Mixin, type NewSpecPageOptions, ReactiveControllerHost, type SpecPage, createEvent, createTestingSystem, forceUpdate, getAssetPath, getElement, getHostRef, getMode, getRenderingRef, h, mockCompilerSystem, mockComponentMeta, mockConfig, mockDocument, mockLoadConfigInit, mockLogger, mockModule, mockValidatedConfig, mockWindow, newSpecPage, readTask, registerHost, registerInstance, setAssetPath, setErrorHandler, setMode, setupConsoleMocker, shuffleArray, writeTask };