@stencil/core 5.0.0-beta.12 → 5.0.0-beta.13

package/dist/{client-CdFmjaQa.mjs → client-NHI55T4R.mjs}

@@ -137,7 +137,7 @@ const setErrorHandler = (handler) => customError = handler;
 //#endregion
 //#region src/client/client-style.ts
 const styles = /*@__PURE__*/ new Map();
-const modeResolutionChain = [];
+const modeResolver = [];
 //#endregion
 //#region src/runtime/runtime-constants.ts
 /**
@@ -863,10 +863,10 @@ const setAccessor = (elm, memberName, oldValue, newValue, isSvg, flags, initialR
 		const isComplex = isComplexType(newValue);
 		if (!BUILD.lazyLoad) {
 			const isStandardAttr = ln.startsWith("aria-") || ln.startsWith("data-");
-			if (!isProp && !isStandardAttr && elm.tagName?.includes("-") && elm.tagName !== "SLOT-FB" && typeof customElements !== "undefined" && !customElements.get(elm.tagName.toLowerCase())) {
+			if (!isProp && !isStandardAttr && elm.tagName?.includes("-") && elm.tagName !== "SLOT-FB" && !customElements.get(elm.tagName.toLowerCase())) {
 				if (!elm["s-pp"]) elm["s-pp"] = /* @__PURE__ */ new Map();
 				elm["s-pp"].set(memberName, newValue);
-				return;
+				if (isComplex || /[A-Z]/.test(memberName)) return;
 			}
 		}
 		if ((isProp || isComplex && newValue !== null) && !isSvg) try {
@@ -2228,7 +2228,10 @@ const validateInputProperties = (inputElm) => {
 };
 //#endregion
 //#region src/runtime/mode.ts
-const setMode = (handler) => modeResolutionChain.push(handler);
+const setMode = (handler) => {
+	modeResolver.length = 0;
+	modeResolver.push(handler);
+};
 const getMode = (ref) => getHostRef(ref)?.$modeName$;
 //#endregion
 //#region src/runtime/mixin.ts

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';
@@ -367,6 +433,7 @@ interface CompilerBuildResults {
   buildId: number;
   componentGraph?: BuildResultsComponentGraph;
   components: ComponentCompilerMeta[];
+  cssOnlyComponents: ComponentCompilerMeta[];
   diagnostics: Diagnostic[];
   dirsAdded: string[];
   dirsDeleted: string[];
@@ -383,6 +450,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 +474,7 @@ interface HotModuleReplacement {
   componentsUpdated?: string[];
   excludeHmr?: string[];
   externalStylesUpdated?: string[];
+  globalStylesUpdated?: HmrGlobalStyleUpdate[];
   imagesUpdated?: string[];
   indexHtmlUpdated?: boolean;
   inlineStylesUpdated?: HmrStyleUpdate[];
@@ -412,6 +489,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;
@@ -839,6 +925,12 @@ 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
@@ -864,6 +956,7 @@ interface TranspileResults {
   inputFilePath: string;
   map: any;
   outputFilePath: string;
+  styleDocs?: StyleDoc[];
 }
 //#endregion
 //#region src/declarations/stencil-private.d.ts
@@ -1070,7 +1163,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 +1233,7 @@ interface ComponentCompilerMeta extends ComponentCompilerFeatures {
   sourceFilePath: string;
   sourceMapPath: string;
   states: ComponentCompilerState[];
-  styleDocs: CompilerStyleDoc[];
+  styleDocs: StyleDoc[];
   styles: StyleCompiler[];
   globalStyles: ComponentGlobalStyle[];
   tagName: string;
@@ -1324,20 +1417,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 +1428,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;

package/dist/compiler/browser.js

@@ -1844,7 +1844,7 @@ const validateComponentTag = (tag) => {
 };
 //#endregion
 //#region src/version.ts
-const version = "5.0.0-beta.12";
+const version = "5.0.0-beta.13";
 //#endregion
 //#region src/compiler/events.ts
 const buildEvents = () => {
@@ -2646,7 +2646,8 @@ const getTranspileCssConfig = (compileOpts, importData, results) => {
 		minify: false,
 		autoprefixer: false,
 		module: compileOpts.module,
-		styleImportData: compileOpts.styleImportData
+		styleImportData: compileOpts.styleImportData,
+		docs: compileOpts.docs === true
 	};
 };
 const getTranspileConfigOpt = (value, validValues, defaultValue) => {
@@ -3827,6 +3828,7 @@ const validateConfig = (userConfig = {}, bootstrapConfig) => {
 		devMode,
 		compat: config.compat || {},
 		generateExportMaps: isBoolean$1(config.generateExportMaps) ? config.generateExportMaps : !isString$1(config.configPath),
+		enableCssOnlyComponents: config.enableCssOnlyComponents ?? true,
 		hydratedFlag: validateHydrated(config),
 		logLevel,
 		logger,
@@ -3884,29 +3886,137 @@ const validateConfig = (userConfig = {}, bootstrapConfig) => {
 	};
 };
 //#endregion
+//#region src/compiler/docs/css-doc-comments.ts
+/**
+* A JSDoc-style comment is `/** ... *\/` or `/*! ... *\/` - postcss's `Comment.text` already
+* strips the `/*`/`*\/` delimiters, so this checks the leading `*` or `!` that remains.
+* @param commentText a postcss `Comment` node's `.text`
+* @returns `true` if the comment is JSDoc-style
+*/
+const isJsDocComment = (commentText) => commentText.startsWith("*") || commentText.startsWith("!");
+/**
+* Strip the leading `*`/`!` marker and per-line `*` prefixes, returning trimmed lines.
+* @param commentText a postcss `Comment` node's `.text`
+* @returns the comment's lines, delimiters and leading `*`s stripped
+*/
+const normalizeJsDocLines = (commentText) => {
+	return commentText.replace(/^[*!]/, "").split(/\r?\n/).map((line) => line.trim().replace(/^\*/, "").trim()).filter((line, i, arr) => !(line === "" && (i === 0 || i === arr.length - 1)));
+};
+/**
+* @param commentText a postcss `Comment` node's `.text`
+* @returns the comment's lines joined into a single trimmed line of text
+*/
+const normalizeJsDocText = (commentText) => normalizeJsDocLines(commentText).filter(Boolean).join(" ").trim();
+/**
+* @param value a CSS descriptor value, possibly quoted (e.g. a `syntax` descriptor's `"<length>"`)
+* @returns the value with any surrounding quotes removed
+*/
+const stripQuotes = (value) => value.replace(/^['"]|['"]$/g, "");
+/**
+* Extract the `syntax`/`initial-value` descriptors from a native `@property` at-rule's body.
+* @param node a postcss `AtRule` node whose `name` is `property`
+* @returns the extracted descriptors, if present
+*/
+const parsePropertyAtRuleDescriptors = (node) => {
+	let syntax;
+	let initialValue;
+	node.each((child) => {
+		if (child.type !== "decl") return;
+		if (child.prop === "syntax") syntax = stripQuotes(child.value);
+		else if (child.prop === "initial-value") initialValue = child.value;
+	});
+	return {
+		syntax,
+		initialValue
+	};
+};
+//#endregion
 //#region src/compiler/docs/style-docs.ts
 /**
 * Parse CSS docstrings that Stencil supports, as documented here:
 * https://stenciljs.com/docs/docs-json#css-variables
 *
-* Docstrings found in the supplied style text will be added to the
-* `styleDocs` param
+* Docstrings found in the supplied style text will be added to the `styleDocs` param, via three
+* mechanisms, in order of precedence (an earlier mechanism always wins over a later one for the
+* same custom property name):
+* 1. An explicit `@prop`/`@cssprop`/`@cssproperty` annotation in a block comment, anywhere in the file.
+* 2. A doc-commented `--foo: value;` declaration inside the component's "root" rule - `:host`
+*    for `shadow`/`scoped` encapsulation, or the component's own tag selector for `none`.
+* 3. A native `@property --foo { ... }` at-rule, with the `syntax`/`initial-value` descriptors
+*    surfaced as `syntax`/`default`. Not scoped - `@property` is a global registration.
 *
 * @param styleDocs the array to hold formatted CSS docstrings
 * @param styleText the CSS text we're working with
 * @param mode a mode associated with the parsed style, if applicable (e.g. this is not applicable for global styles)
+* @param tag the component's tag name, used to scope auto-detection for `none` encapsulation
+* @param encapsulation the component's encapsulation, used to pick the "root" scope for auto-detection
 */
-function parseStyleDocs(styleDocs, styleText, mode) {
+function parseStyleDocs(styleDocs, styleText, mode, tag, encapsulation) {
 	if (typeof styleText !== "string") return;
-	let match = styleText.match(CSS_DOC_START);
+	let remainingText = styleText;
+	let match = remainingText.match(CSS_DOC_START);
 	while (match !== null) {
-		styleText = styleText.substring(match.index + match[0].length);
-		const endIndex = styleText.indexOf(CSS_DOC_END);
+		remainingText = remainingText.substring(match.index + match[0].length);
+		const endIndex = remainingText.indexOf(CSS_DOC_END);
 		if (endIndex === -1) break;
-		parseCssComment(styleDocs, styleText.substring(0, endIndex), mode);
-		styleText = styleText.substring(endIndex + CSS_DOC_END.length);
-		match = styleText.match(CSS_DOC_START);
+		parseCssComment(styleDocs, remainingText.substring(0, endIndex), mode);
+		remainingText = remainingText.substring(endIndex + CSS_DOC_END.length);
+		match = remainingText.match(CSS_DOC_START);
 	}
+	if (styleText.includes("--")) parseScopedAndNativeStyleDocs(styleDocs, styleText, mode, tag, encapsulation);
+}
+/**
+* Auto-detect doc-commented custom-property declarations within the component's "root" rule,
+* and native `@property` at-rule registrations, merging them into `styleDocs`. Mirrors the
+* equivalent detection for CSS-only components in `css-components/parse-css-component.ts`.
+*
+* @param styleDocs the array to hold formatted CSS docstrings - also consulted so an explicit
+* `@prop`/`@cssprop` annotation always wins over an auto-detected entry for the same name
+* @param styleText the CSS text we're working with
+* @param mode a mode associated with the parsed style, if applicable
+* @param tag the component's tag name
+* @param encapsulation the component's encapsulation
+*/
+function parseScopedAndNativeStyleDocs(styleDocs, styleText, mode, tag, encapsulation) {
+	let root;
+	try {
+		root = postcss().process(styleText, { from: void 0 }).root;
+	} catch {
+		return;
+	}
+	const hasName = (name) => styleDocs.some((styleDoc) => styleDoc.name === name);
+	const rootSelector = encapsulation === "shadow" || encapsulation === "scoped" ? ":host" : tag;
+	if (rootSelector) root.walkRules((rule) => {
+		if (!rule.selectors.some((selector) => selector.trim() === rootSelector)) return;
+		const children = rule.nodes;
+		for (let i = 0; i < children.length; i++) {
+			const child = children[i];
+			if (child.type !== "decl" || !child.prop.startsWith("--") || hasName(child.prop)) continue;
+			const prev = children[i - 1];
+			if (!prev || prev.type !== "comment" || !isJsDocComment(prev.text)) continue;
+			styleDocs.push({
+				name: child.prop,
+				docs: normalizeJsDocText(prev.text),
+				annotation: "prop",
+				mode
+			});
+		}
+	});
+	root.walkAtRules("property", (node) => {
+		const propName = node.params.trim();
+		if (!propName.startsWith("--") || hasName(propName)) return;
+		const { syntax, initialValue } = parsePropertyAtRuleDescriptors(node);
+		const prev = node.prev();
+		const docs = prev && prev.type === "comment" && isJsDocComment(prev.text) ? normalizeJsDocText(prev.text) : "";
+		styleDocs.push({
+			name: propName,
+			docs,
+			annotation: "prop",
+			mode,
+			...syntax && { syntax },
+			...initialValue && { default: initialValue }
+		});
+	});
 }
 /**
 * Parse a CSS comment string and insert it into the provided array of
@@ -3923,7 +4033,7 @@ function parseCssComment(styleDocs, comment, mode) {
 		return line;
 	}).join(" ").replace(/\t/g, " ").trim();
 	while (comment.includes("  ")) comment = comment.replace("  ", " ");
-	comment.split(CSS_PROP_ANNOTATION).forEach((d) => {
+	comment.split(CSS_PROP_ANNOTATION_RE).forEach((d) => {
 		const cssDocument = d.trim();
 		if (!cssDocument.startsWith(`--`)) return;
 		const splt = cssDocument.split(`:`);
@@ -3946,9 +4056,11 @@ const CSS_DOC_START = /\/\*(\*|!)/;
 */
 const CSS_DOC_END = "*/";
 /**
-* The `@prop` annotation we support within CSS docstrings
+* The `@prop` annotation we support within CSS docstrings. `@cssprop`/`@cssproperty` are also
+* recognized as synonyms (the more common names in other web-component-analyzer/docgen
+* ecosystems).
 */
-const CSS_PROP_ANNOTATION = "@prop";
+const CSS_PROP_ANNOTATION_RE = /@(?:cssproperty|cssprop|prop)\b/;
 //#endregion
 //#region src/compiler/sys/browser-stubs/browserslist.ts
 const browserslist = (_query) => [];
@@ -9230,9 +9342,9 @@ const serializeSymbol = (checker, symbol) => {
 	};
 };
 /**
-* Maps a TypeScript 4.3+ JSDocTagInfo to a flattened Stencil CompilerJsDocTagInfo.
+* Maps a TypeScript 4.3+ JSDocTagInfo to a flattened Stencil JsonDocsTag.
 * @param tags A readonly array of JSDocTagInfo objects.
-* @returns An array of CompilerJsDocTagInfo objects.
+* @returns An array of JsonDocsTag objects.
 */
 const mapJSDocTagInfo = (tags) => {
 	return tags.map((tag) => ({
@@ -9643,7 +9755,7 @@ const transformCssToEsmModule = (input) => {
 		defaultVarName: createCssVarName(input.file, input.mode),
 		styleDocs: []
 	};
-	if (input.docs) parseStyleDocs(results.styleDocs, input.input, input.mode);
+	if (input.docs) parseStyleDocs(results.styleDocs, input.input, input.mode, input.tag, input.encapsulation);
 	try {
 		const varNames = /* @__PURE__ */ new Set([results.defaultVarName]);
 		if (isString$1(input.tag) && input.encapsulation === "scoped") {
@@ -9740,7 +9852,7 @@ const getCssToEsmImports = (varNames, cssText, filePath, modeName) => {
 			isNodeModule: false
 		};
 		if (!isLocalCssImport(cssImportData.srcImportText)) continue;
-		else if (cssImportData.url === "stencil-globals" || cssImportData.url === "stencil-hydrate") continue;
+		else if (cssImportData.url === "stencil-component-globals" || cssImportData.url === "stencil-hydrate" || cssImportData.url === "stencil-css-components") continue;
 		else if (isCssNodeModule(cssImportData.url)) {
 			cssImportData.filePath = cssImportData.url.substring(1);
 			cssImportData.isNodeModule = true;
@@ -9955,6 +10067,7 @@ var BuildContext = class {
 	completedTasks = [];
 	compilerCtx;
 	components = [];
+	cssOnlyComponents = [];
 	componentGraph = /* @__PURE__ */ new Map();
 	config;
 	data = {};
@@ -9996,6 +10109,7 @@ var BuildContext = class {
 	styleBuildCount = 0;
 	stylesPromise = null;
 	stylesUpdated = [];
+	globalStylesUpdated = [];
 	timeSpan = null;
 	timestamp;
 	transpileBuildCount = 0;
@@ -10176,12 +10290,18 @@ var CompilerContext = class {
 	*/
 	prevStylesMap = /* @__PURE__ */ new Map();
 	globalStyleCache = /* @__PURE__ */ new Map();
+	cssOnlyComponentsCache = /* @__PURE__ */ new Map();
+	stencilCss;
+	globalStyleVirtualImports = /* @__PURE__ */ new Map();
 	styleModeNames = /* @__PURE__ */ new Set();
 	worker = null;
 	reset() {
 		this.cache.clear();
 		this.cssModuleImports.clear();
 		this.globalStyleCache.clear();
+		this.cssOnlyComponentsCache.clear();
+		this.stencilCss = void 0;
+		this.globalStyleVirtualImports.clear();
 		this.collections.length = 0;
 		this.compilerOptions = null;
 		this.hasSuccessfulBuild = false;
@@ -16052,6 +16172,7 @@ const transpileCss = async (transformInput, results) => {
 	results.map = cssResults.map;
 	results.imports = cssResults.imports.map((p) => ({ path: p.importPath }));
 	results.diagnostics.push(...cssResults.diagnostics);
+	if (transformInput.docs) results.styleDocs = cssResults.styleDocs;
 };
 const transpileCssSync = (transformInput, results) => {
 	const cssResults = transformCssToEsmSync(transformInput);
@@ -16059,6 +16180,7 @@ const transpileCssSync = (transformInput, results) => {
 	results.map = cssResults.map;
 	results.imports = cssResults.imports.map((p) => ({ path: p.importPath }));
 	results.diagnostics.push(...cssResults.diagnostics);
+	if (transformInput.docs) results.styleDocs = cssResults.styleDocs;
 };
 const transpileJson = (results) => {
 	results.code = dataToEsm(JSON.parse(results.code), {