Merge branch 'main' into sp/react-output-target

.github/workflows/check-markdown.yml

@@ -9,10 +9,10 @@ jobs:
   markdown-link-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
 
     - name: Use Node from Volta
-      uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+      uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
       with:
         node-version-file: 'package.json'
         cache: 'npm'
@@ -26,10 +26,10 @@ jobs:
   markdown-spelling-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
+    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
 
     - name: Use Node from Volta
-      uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+      uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
       with:
         node-version-file: 'package.json'
         cache: 'npm'

.github/workflows/format.yml

@@ -11,13 +11,13 @@ jobs:
     runs-on: 'ubuntu-latest'
     steps:
       - name: Checkout Code
-        uses: actions/checkout@1d96c772d19495a3b5c517cd2bc0cb401ea0529f # v4.1.3
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
 
       # this overrides previous versions of the node runtime that was set.
       # jobs that need a different version of the Node runtime should explicitly
       # set their node version after running this step
       - name: Use Node Version from Volta
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
+        uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
         with:
           node-version-file: './package.json'
           cache: 'npm'

cspell-wordlist.txt

@@ -30,6 +30,7 @@ prerenders
 proxied
 pseudocode
 runtimes
+shadowrootmode
 sourcemaps
 templating
 transpiles

docs/components/api.md

@@ -152,6 +152,15 @@ The following primitives can be imported from the `@stencil/core` package and us
   }
   ```
 
+- **setAssetPath()**: Sets the path for Stencil to resolve local assets. Refer to the [Assets](../guides/assets.md#setassetpath) page for usage info.
+
+  __Type:__ `(path: string) => string`<br />
+  __Example:__
+  ```ts
+  import { setAssetPath } from '@stencil/core';
+  setAssetPath(`{window.location.origin}/`);
+  ```
+
 - **setMode()**: Sets the style mode of a component. Refer to the [Styling](./styling.md#style-modes) page for usage info.
 
   __Type:__ `(ref: HTMLElement) => string`<br />

docs/components/component-lifecycle.md

@@ -131,7 +131,7 @@ Even if some components may or may not be already loaded, the entire component h
 
 ## Async Lifecycle Methods
 
-Lifecycle methods can also return promises which allows the method to asynchronously retrieve data or perform any async tasks. A great example of this is fetching data to be rendered in a component. For example, this very site you're reading first fetches content data before rendering. But because `fetch()` is async, it's important that `componentWillLoad()` returns a `Promise` to ensure its parent component isn't considered "loaded" until all of its content has rendered.
+Some lifecycle methods, e.g. `componentWillRender`, `componentWillLoad` and `componentWillUpdate`, can also return promises which allows the method to asynchronously retrieve data or perform any async tasks. A great example of this is fetching data to be rendered in a component. For example, this very site you're reading first fetches content data before rendering. But because `fetch()` is async, it's important that `componentWillLoad()` returns a `Promise` to ensure its parent component isn't considered "loaded" until all of its content has rendered.
 
 Below is a quick example showing how `componentWillLoad()` is able to have its parent component wait on it to finish loading its data.
 
@@ -145,7 +145,6 @@ componentWillLoad() {
 }
 ```
 
-
 ## Example
 
 This simple example shows a clock and updates the current time every second. The timer is started when the component is added to the DOM. Once it's removed from the DOM, the timer is stopped.

docs/config/01-overview.md

@@ -108,6 +108,47 @@ enableCache: true
 
 Please see the [Extras docs](./extras.md).
 
+## env
+
+*default: `{}`*
+
+An object that can hold environment variables for your components to import and use. These variables can hold data objects depending on the environment you compile the components for. For example, let's say we want to provide an URL to our API based on a specific environment, we could provide it as such:
+
+```ts title="stencil.config.ts"
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+  ...,
+  env: {
+    API_BASE_URL: process.env.API_BASE_URL
+  }
+}
+```
+
+Now when you build your components with this environment variable set, you can import it in your component as follows:
+
+```ts
+import { Component, h, Env, Host } from '@stencil/core';
+
+@Component({
+  tag: 'api-component',
+})
+export class APIComponent {
+  async connectedCallback () {
+    const res = await fetch(Env.API_BASE_URL)
+    // ...
+  }
+}
+```
+
+## generateExportMaps
+
+*default: `false`*
+
+Stencil will generate [export maps](https://nodejs.org/api/packages.html#packages_exports) that correspond with various output target outputs. This includes the root
+entry point based on the [primary output target](../output-targets/01-overview.md#primary-package-output-target-validation) (or first eligible output target if not specified),
+the entry point for the lazy-loader (if using the `dist` output target), and entry points for each component (if using `dist-custom-elements`).
+
 ## globalScript
 
 The global script config option takes a file path as a string.
@@ -470,3 +511,37 @@ export declare function util(arg: UtilInterface): void;
 
 When `true`, validation for common `package.json` fields will occur based on setting an output target's `isPrimaryPackageOutputTarget` flag.
 For more information on package validation, please see the [output target docs](../output-targets/01-overview.md#primary-package-output-target-validation).
+
+## rollupConfig
+
+Passes custom configuration down to rollup itself. The following options can be overwritten:
+
+- `inputOptions`: [`context`](https://rollupjs.org/configuration-options/#context), [`external`](https://rollupjs.org/configuration-options/#external), [`moduleContext`](https://rollupjs.org/configuration-options/#modulecontext) [`treeshake`](https://rollupjs.org/configuration-options/#treeshake)
+- `outputOptions`: [`globals`](https://rollupjs.org/configuration-options/#output-globals) 
+
+*default: `{}`*
+
+## watchIgnoredRegex
+
+*default: `[]`*
+
+*type: `RegExp | RegExp[]`*
+
+A regular expression (or array of regular expressions) that can be used to omit files from triggering a rebuild in watch mode. During compile-time, each file in the Stencil
+project will be tested against each regular expression to determine if changes to the file (or directory) should trigger a project rebuild.
+
+:::note
+If you want to ignore TS files such as `.ts`/`.js` or `.tsx`/`.jsx` extensions, these files will also need to be specified in your project's tsconfig's
+[`watchOptions`](https://www.typescriptlang.org/docs/handbook/configuring-watch.html#configuring-file-watching-using-a-tsconfigjson) _in addition_ to the
+`watchIgnoredRegex` option. For instance, if we wanted to ignore the `my-component.tsx` file, we'd specify:
+
+```json title="tsconfig.json"
+{
+  ...,
+  "watchOptions": {
+    "excludeFiles": ["src/components/my-component/my-component.tsx"]
+  }
+}
+```
+
+:::

docs/config/extras.md

@@ -130,6 +130,10 @@ An experimental flag that when set to `true`, aligns the behavior of invoking th
 
 ### scriptDataOpts
 
+:::caution
+This option has been deprecated and will be removed in the next major Stencil release.
+:::
+
 It is possible to assign data to the actual `<script>` element's `data-opts` property, which then gets passed to Stencil's initial bootstrap. This feature is only required for very special cases and rarely needed. When set to `false` it will not read this data. Defaults to `false`.
 
 ### slotChildNodesFix

docs/config/plugins.md

@@ -47,7 +47,7 @@ export const config = {
 
 - [@stencil/sass](https://www.npmjs.com/package/@stencil/sass)
 - [@stencil-community/postcss](https://www.npmjs.com/package/@stencil-community/postcss)
-- (Deprecated) [@stencil/less](https://www.npmjs.com/package/@stencil/less)
+- [@stencil-community/less](https://www.npmjs.com/package/@stencil-community/less)
 - (Deprecated) [@stencil/stylus](https://www.npmjs.com/package/@stencil/stylus)
 
 

docs/documentation-generation/docs-json.md

@@ -100,22 +100,48 @@ CSS file like the following:
 
 Then you'd get the following in the JSON output:
 
-```json
-"styles": [
+```json title="Example docs-json Output"
+[
+  {
+    "name": "--background",
+    "annotation": "prop",
+    "docs": "Background of the button"
+  },
+  {
+    "name": "--background-activated",
+    "annotation": "prop",
+    "docs": "Background of the button when activated"
+  },
+  {
+    "name": "--background-focused",
+    "annotation": "prop",
+    "docs": "Background of the button when focused"
+  }
+]
+```
+
+If the style sheet is configured to be used with [a specific mode](../components/styling.md), the mode associated with
+the CSS property will be provided as well:
+
+```diff title="Example docs-json Output with Mode"
+[
   {
     "name": "--background",
     "annotation": "prop",
     "docs": "Background of the button"
++   "mode": "ios",    
   },
   {
     "name": "--background-activated",
     "annotation": "prop",
     "docs": "Background of the button when activated"
++   "mode": "ios",    
   },
   {
     "name": "--background-focused",
     "annotation": "prop",
     "docs": "Background of the button when focused"
++   "mode": "ios",    
   }
 ]
 ```

docs/framework-integration/angular.md

@@ -294,6 +294,22 @@ of your Angular workspace (`/packages/angular-workspace`), run the following com
 npx -p @angular/cli ng build component-library
 ```
 
+:::note
+In the output of the `ng build` command you may see a warning that looks like this: 
+
+```
+▲ [WARNING] The glob pattern import("./**/.entry.js") did not match any files [empty-glob]
+
+node_modules/@stencil/core/internal/client/index.js:3808:2:
+  3808 │   `./${bundleId}.entry.js${BUILD.hotModuleReplacement && hmrVers...
+       ╵   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```
+
+This is a known issue in esbuild (used under the hood by `ng build`) and should
+not cause an issue, but at present there's unfortunately no way to suppress
+this warning.
+:::
+
 <Tabs
   groupId="outputType"
   defaultValue="component"
@@ -409,6 +425,22 @@ of your Angular workspace (`/packages/angular-workspace`), run the following com
 npx -p @angular/cli ng build component-library
 ```
 
+:::note
+In the output of the `ng build` command you may see a warning that looks like this: 
+
+```
+▲ [WARNING] The glob pattern import("./**/.entry.js") did not match any files [empty-glob]
+
+node_modules/@stencil/core/internal/client/index.js:3808:2:
+  3808 │   `./${bundleId}.entry.js${BUILD.hotModuleReplacement && hmrVers...
+       ╵   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```
+
+This is a known issue in esbuild (used under the hood by `ng build`) and should
+not cause an issue, but at present there's unfortunately no way to suppress
+this warning.
+:::
+
 <Tabs
   groupId="outputType"
   defaultValue="component"

docs/guides/assets.md

@@ -62,6 +62,8 @@ When using `getAssetPath`, the assets in the directory structure above are resol
 The code sample below demonstrates the return value of `getAssetPath` for different `path` arguments.
 The return value is a path that Stencil has built to retrieve the asset on the filesystem.
 ```ts
+import { getAssetPath } from '@stencil/core';
+
 // with an asset base path of "/build/":
 
 // '/build/assets/logo.png'
@@ -210,6 +212,8 @@ declare function getAssetPath(path: string): string;
 
 The code sample below demonstrates the return value of `getAssetPath` for different `path` arguments, when an asset base path of `/build/` has been set.
 ```ts
+import { getAssetPath } from '@stencil/core';
+
 // with an asset base path of "/build/":
 // "/build/"
 getAssetPath('');
@@ -227,7 +231,7 @@ getAssetPath('/assets/my-image.png');
 
 ### setAssetPath
 
-`setAssetPath` is an API provided by Stencil to manually set the asset base path where assets can be found.
+`setAssetPath` is an API provided by Stencil's runtime to manually set the asset base path where assets can be found. If you are using `getAssetPath` to compose the path for your component assets, `setAssetPath` allows you or the consumer of the component to change that path.
 
 ```ts
 /**
@@ -238,13 +242,43 @@ getAssetPath('/assets/my-image.png');
 export declare function setAssetPath(path: string): string;
 ```
 
-Calling this API will set the asset base path for all Stencil components attached to a Stencil runtime.
-As a result, calling `setAssetPath` should not be done from within a component in order to prevent unwanted side effects
-when using a component.
+Calling this API will set the asset base path for all Stencil components attached to a Stencil runtime. As a result, calling `setAssetPath` should not be done from within a component in order to prevent unwanted side effects when using a component.
+
+Make sure as component author to export this function as part of your module in order to also make it accessible to the consumer of your component, e.g. in your package entry file export the function via:
+
+```ts title="/src/index.ts"
+export { setAssetPath } from '@stencil/core';
+```
+
+Now your users can import it directly from your component library, e.g.:
 
-If the file calling `setAssetPath` is a module, it's recommended to use `import.meta.url`.
+```ts
+import { setAssetPath } from 'my-component-library';
+setAssetPath(`${window.location.protocol}//assets.${window.location.host}/`);
+```
 
-Alternatively, one may use [`document.currentScript.src`](https://developer.mozilla.org/en-US/docs/Web/API/Document/currentScript)
-when working in the browser and not using modules or environment variables (e.g. `document.env.ASSET_PATH`) to set the
-asset base path. 
-This configuration depends on how your script is bundled, (or lack of bundling), and where your assets can be loaded from.
+Alternatively, one may use [`document.currentScript.src`](https://developer.mozilla.org/en-US/docs/Web/API/Document/currentScript) when working in the browser and not using modules or environment variables (e.g. `document.env.ASSET_PATH`) to set the
+asset base path. This configuration depends on how your script is bundled, (or lack of bundling), and where your assets can be loaded from.
+
+:::note
+
+If your component library exports components compiled with [`dist-output-target`](/output-targets/custom-elements.md) and `externalRuntime` set to `true`, then `setAssetPath` has to be imported from `@stencil/core` directly.
+
+:::
+
+In case you import a component directly via script tag, this would look like:
+
+```html
+<html>
+  <head>
+    <script src="https://cdn.jsdelivr.net/npm/my-component-library/dist/my-component-library.js"></script>
+    <script type="module">
+      import { setAssetPath } from 'https://cdn.jsdelivr.net/npm/my-component-library/dist/my-component-library.js';
+      setAssetPath(`${window.location.origin}/`);
+    </script>
+  </head>
+  <body>
+    <ion-toggle></ion-toggle>
+  </body>
+</html>
+```