Merge branch 'main' into cb/vitest-tutorial

.github/workflows/check-markdown.yml

@@ -9,7 +9,7 @@ jobs:
   markdown-link-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+    - uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5
 
     - name: Use Node from Volta
       uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2
@@ -26,7 +26,7 @@ jobs:
   markdown-spelling-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+    - uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5
 
     - name: Use Node from Volta
       uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2

.github/workflows/format.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: 'ubuntu-latest'
     steps:
       - name: Checkout Code
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b # v4.1.5
 
       # this overrides previous versions of the node runtime that was set.
       # jobs that need a different version of the Node runtime should explicitly

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/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>
+```

docs/reference/support-policy.md

@@ -124,12 +124,12 @@ compatibility tables to describe the interoperability requirements of these piec
 
 ### JavaScript Runtime
 
-| Stencil Version | Node v10 | Node v12 | Node v14 | Node v16 | Node v18 | Node v20 |
-|:---------------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|
-|       V4        | ❌ | ❌ | ❌ | ✅  | ✅  | ✅  |
-|       V3        | ❌ | ❌ | ✅  | ✅  | ✅  | ✅  |
-|       V2        | ❌ | ✅  | ✅  | ✅  | ⚠  | ❌ |
-|       V1        | ✅  | ✅  | ✅  | ✅  | ❌ | ❌ |
+| Stencil Version | Node v10 | Node v12 | Node v14 | Node v16 | Node v18 | Node v20 | Node v22 |
+|:---------------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|:--------:|
+|       V4        | ❌ | ❌ | ❌ | ✅  | ✅  | ✅  | ✅  |
+|       V3        | ❌ | ❌ | ✅  | ✅  | ✅  | ✅  | ❌ |
+|       V2        | ❌ | ✅  | ✅  | ✅  | ⚠  | ❌ | ❌ |
+|       V1        | ✅  | ✅  | ✅  | ✅  | ❌ | ❌ | ❌ |
 
 ### Testing Libraries
 

docs/testing/playwright/01-overview.md

@@ -36,18 +36,22 @@ To install the Stencil Playwright adapter in an existing Stencil project, follow
 
    ```ts title="playwright.config.ts"
    import { expect } from '@playwright/test';
-   import { matchers, createStencilPlaywrightConfig } from '@stencil/playwright';
+   import { matchers, createConfig } from '@stencil/playwright';
 
    // Add custom Stencil matchers to Playwright assertions
    expect.extend(matchers);
 
-   export default createStencilPlaywrightConfig({
+   export default createConfig({
      // Overwrite Playwright config options here
    });
    ```
 
-   The `createStencilPlaywrightConfig()` is a utility that will create a default Playwright configuration based on your project's Stencil config. Read
-   more about how to use this utility in the [API docs](./03-api.md#createstencilplaywrightconfig-function).
+   The `createConfig()` function is a utility that will create a default Playwright configuration based on your project's Stencil config. Read
+   more about how to use this utility in the [API docs](./03-api.md#createconfig-function).
+
+   :::note
+   For `createConfig()` to work correctly, your Stencil config must be named either `stencil.config.ts` or `stencil.config.js`.
+   :::
 
 1. update your project's `tsconfig.json` to add the `ESNext.Disposable` option to the `lib` array:
 
@@ -67,7 +71,7 @@ To install the Stencil Playwright adapter in an existing Stencil project, follow
    :::
 
 1. Ensure the Stencil project has a [`www` output target](../../output-targets/www.md). Playwright relies on pre-compiled output running in a dev server
-   to run tests against. When using the `createStencilPlaywrightConfig()` helper, a configuration for the dev server will be automatically created based on
+   to run tests against. When using the `createConfig()` helper, a configuration for the dev server will be automatically created based on
    the Stencil project's `www` output target config and [dev server config](../../config/dev-server.md). If no `www` output target is specified,
    tests will not be able to run.
 
@@ -107,7 +111,7 @@ options:
 - **Option 1:** Update the Playwright config to match a different test file pattern:
 
   ```ts title="playwright.config.ts"
-  export default createStencilPlaywrightConfig({
+  export default createConfig({
     // Example: match all test files with the 'e2e.playwright.ts' naming convention
     testMatch: '*.e2e.playwright.ts',
   });

docs/testing/playwright/02-e2e-testing.md

@@ -87,6 +87,8 @@ test.describe('my-component', () => {
     await page.goto('/components/my-component/test/my-component.e2e.html');
 
     // Rest of test
+    const component = await page.locator('my-component');
+    await expect(component).toHaveText(`Hello World! I’m Stencil`);
   });
 });
 ```
@@ -96,8 +98,8 @@ In the above snippet, the path string passed to `page.goto()` should be the _abs
 
 #### `page.setContent()`
 
-The `setContent()` method allows tests to define their own HTML code on a test-by-test basis. This pattern is helpful if the HTML for a test is small, or to
-avoid affecting other tests is using the `page.goto()` pattern and modifying a shared HTML template file. With this pattern, the `script` tags pointing to Stencil
+The `setContent()` method allows tests to define their own HTML code on a test-by-test basis. This pattern is helpful if the HTML for a test is small or to
+avoid affecting other tests using the `page.goto()` pattern and modifying a shared HTML template file. With this pattern, the `script` tags pointing to Stencil
 entry code will be automatically injected into the generated HTML.
 
 ```ts title="my-component.e2e.ts"
@@ -127,7 +129,7 @@ test.describe('my-component', () => {
     await page.goto('/my-component/my-component.e2e.html');
 
     const button = page.locator('button');
-    // Assmume clicking the button changes the `@Prop()` values on `my-component`
+    // Assume clicking the button changes the `@Prop()` values on `my-component`
     button.click();
     await page.waitForChanges();
   });
@@ -141,7 +143,7 @@ Playwright command.
 
 By default, the adapter will execute all tests in a project with a `.e2e.ts` file suffix. This can be modified by passing the
 [`testDir`](https://playwright.dev/docs/api/class-testproject#test-project-test-dir) and/or [`testMatch`](https://playwright.dev/docs/api/class-testproject#test-project-test-match)
-configuration options as overrides to `createStencilPlaywrightConfig()`.
+configuration options as overrides to `createConfig()`.
 
 ## Debugging