Merge branch 'main' into cb/document-dynamic-render-limitation

.github/workflows/format.yml

@@ -0,0 +1,31 @@
+name: Format Stencil Docs (Check)
+
+on:
+  workflow_call:
+    # Make this a reusable workflow, no value needed
+    # https://docs.github.com/en/actions/using-workflows/reusing-workflows
+
+jobs:
+  format:
+    name: Check
+    runs-on: 'ubuntu-latest'
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+      # 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@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+        with:
+          node-version-file: './package.json'
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm ci
+        shell: bash
+
+      - name: Prettier Check
+        run: npm run prettier.dry-run
+        shell: bash

.github/workflows/main.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - 'main'
+  pull_request:
+    branches:
+      - '**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  format:
+    name: Format
+    uses: ./.github/workflows/format.yml

.prettierignore

@@ -0,0 +1,4 @@
+package.json
+package-lock.json
+# auto-generated/maintained by docusaurus
+versions.json

cspell.json

@@ -7,9 +7,5 @@
       "addWords": true
     }
   ],
-  "ignoreRegExpList": [
-    "/(```+)[\\s\\S]+?\\1/g",
-    "/`[a-zA-Z-_]+`/g",
-    "/:[a-z_]+:/g"
-  ]
+  "ignoreRegExpList": ["/(```+)[\\s\\S]+?\\1/g", "/`[a-zA-Z-_]+`/g", "/:[a-z_]+:/g"]
 }

docs/components/templating-and-jsx.md

@@ -175,6 +175,8 @@ render(){
 }
 ```
 
+### Slots Outside Shadow DOM
+
 :::caution
 Slots are native to the [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM), but Stencil polyfills
 the behavior to work for non-shadow components as well. However, you may encounter issues using slots outside the Shadow DOM especially with
@@ -183,6 +185,12 @@ be remedied by wrapping the `slot` in an additional element (like a `div` or `sp
 content in its new location.
 :::
 
+There are known use cases that the Stencil runtime is not able to support:
+
+- Forwarding slotted content to another slot with a different name:<br/>
+  It is recommended that slot names stay consistent when slotting content through multiple levels of components. **Avoid** defining slot tags like
+  `<slot name="start" slot="main" />`.
+
 ## Dealing with Children
 
 The children of a node in JSX correspond at runtime to an array of nodes,

docs/config/extras.md

@@ -21,18 +21,12 @@ By default, the slot polyfill does not update `appendChild()` so that it appends
 
 By default, the runtime does not polyfill `cloneNode()` when cloning a component that uses the slot polyfill. This is an opt-in polyfill for those who need it.
 
-### experimentalImportInjection
-
-:::caution
-This flag has been deprecated in favor of [`enableImportInjection`](#enableimportinjection), which provides the same
-functionality. `experimentalImportInjection` will be removed in a future major version of Stencil.
-:::
+### enableImportInjection
 
 In some cases, it can be difficult to lazily load Stencil components in a separate project that uses a bundler such as
 [Vite](https://vitejs.dev/).
 
-This is an experimental flag that, when set to `true`, will allow downstream projects that consume a Stencil library
-and use a bundler such as Vite to lazily load the Stencil library's components.
+Enabling this flag will allow downstream projects that consume a Stencil library and use a bundler such as Vite to lazily load the Stencil library's components.
 
 In order for this flag to work:
 
@@ -45,12 +39,18 @@ Users of this flag should note that they may see an increase in their bundle siz
 
 Defaults to `false`.
 
-### enableImportInjection
+### experimentalImportInjection
+
+:::caution
+This flag has been deprecated in favor of [`enableImportInjection`](#enableimportinjection), which provides the same
+functionality. `experimentalImportInjection` will be removed in a future major version of Stencil.
+:::
 
 In some cases, it can be difficult to lazily load Stencil components in a separate project that uses a bundler such as
 [Vite](https://vitejs.dev/).
 
-Enabling this flag will allow downstream projects that consume a Stencil library and use a bundler such as Vite to lazily load the Stencil library's components.
+This is an experimental flag that, when set to `true`, will allow downstream projects that consume a Stencil library
+and use a bundler such as Vite to lazily load the Stencil library's components.
 
 In order for this flag to work:
 
@@ -63,30 +63,22 @@ Users of this flag should note that they may see an increase in their bundle siz
 
 Defaults to `false`.
 
-### lifecycleDOMEvents
+### experimentalScopedSlotChanges
 
-Dispatches component lifecycle events. By default these events are not dispatched, but by enabling this to `true` these events can be listened for on `window`. Mainly used for testing.
+This option updates runtime behavior for Stencil's support of slots in **scoped** components to match more closely with
+the native Shadow DOM behaviors.
 
-| Event Name                    | Description                                            |
-| ----------------------------- | ------------------------------------------------------ |
-| `stencil_componentWillLoad`   | Dispatched for each component's `componentWillLoad`.   |
-| `stencil_componentWillUpdate` | Dispatched for each component's `componentWillUpdate`. |
-| `stencil_componentWillRender` | Dispatched for each component's `componentWillRender`. |
-| `stencil_componentDidLoad`    | Dispatched for each component's `componentDidLoad`.    |
-| `stencil_componentDidUpdate`  | Dispatched for each component's `componentDidUpdate`.  |
-| `stencil_componentDidRender`  | Dispatched for each component's `componentDidRender`.  |
+When set to `true`, the following behaviors will be applied:
 
-### scopedSlotTextContentFix
-
-An experimental flag that when set to `true`, aligns the behavior of invoking the `textContent` getter/setter on a scoped component to act more like a component that uses the shadow DOM. Specifically, invoking `textContent` on a component will adhere to the return values described in [MDN's article on textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent#description). Defaults to `false`.
+- Stencil will hide projected nodes that do not have a destination `slot` ([#2778](https://github.com/ionic-team/stencil/issues/2877)) (since v4.10.0)
+- The `textContent` getter will return the text content of all nodes located in a slot (since v4.10.0)
+- The `textContent` setter will overwrite all nodes located in a slot (since v4.10.0)
 
-### scriptDataOpts
-
-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
+Defaults to `false`.
 
-For browsers that do not support shadow dom (IE11 and Edge 18 and below), slot is polyfilled to simulate the same behavior. However, the host element's `childNodes` and `children` getters are not patched to only show the child nodes and elements of the default slot. Defaults to `false`.
+:::note
+These behaviors only apply to components using scoped encapsulation!
+:::
 
 ### experimentalSlotFixes
 
@@ -103,9 +95,41 @@ Slot-related fixes to the runtime will be added over the course of Stencil v4,
 with the intent of making these the default behavior in Stencil v5. When set to
 `true` fixes for the following issues will be applied:
 
-- [Elements rendered outside of slot when shadow not enabled (#2641)](https://github.com/ionic-team/stencil/issues/2641) (since v4.2.0)
+- Elements rendered outside of slot when shadow not enabled [(#2641)](https://github.com/ionic-team/stencil/issues/2641) (since v4.2.0)
+- A slot gets the attribute hidden when it shouldn't [(#4523)](https://github.com/ionic-team/stencil/issues/4523) (since v4.7.0)
+- Nested slots mis-ordered when not using Shadow DOM [(#2997)](https://github.com/ionic-team/stencil/issues/2997) (since v4.7.0)
+- Inconsistent behavior: slot-fb breaks styling of default slot content in component with 'shadow: false' [(#2937)](https://github.com/ionic-team/stencil/issues/2937) (since v4.7.2)
+- Slot content went missing within dynamic component [(#4284)](https://github.com/ionic-team/stencil/issues/4284) (since v4.8.2)
+- Slot element loses its parent reference and disappears when its parent is rendered conditionally [(#3913)](https://github.com/ionic-team/stencil/issues/3913) (since v4.8.2)
+- Failed to execute 'removeChild' on 'Node' [(#3278)](https://github.com/ionic-team/stencil/issues/3278) (since v4.9.0)
+- React fails to manage children in Stencil slot [(#2259)](https://github.com/ionic-team/stencil/issues/2259) (since v4.9.0)
 
 :::note
 New fixes enabled by this experimental flag are not subject to Stencil's
 [semantic versioning policy](../reference/versioning.md).
 :::
+
+### lifecycleDOMEvents
+
+Dispatches component lifecycle events. By default these events are not dispatched, but by enabling this to `true` these events can be listened for on `window`. Mainly used for testing.
+
+| Event Name                    | Description                                            |
+| ----------------------------- | ------------------------------------------------------ |
+| `stencil_componentWillLoad`   | Dispatched for each component's `componentWillLoad`.   |
+| `stencil_componentWillUpdate` | Dispatched for each component's `componentWillUpdate`. |
+| `stencil_componentWillRender` | Dispatched for each component's `componentWillRender`. |
+| `stencil_componentDidLoad`    | Dispatched for each component's `componentDidLoad`.    |
+| `stencil_componentDidUpdate`  | Dispatched for each component's `componentDidUpdate`.  |
+| `stencil_componentDidRender`  | Dispatched for each component's `componentDidRender`.  |
+
+### scopedSlotTextContentFix
+
+An experimental flag that when set to `true`, aligns the behavior of invoking the `textContent` getter/setter on a scoped component to act more like a component that uses the shadow DOM. Specifically, invoking `textContent` on a component will adhere to the return values described in [MDN's article on textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent#description). Defaults to `false`.
+
+### scriptDataOpts
+
+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
+
+For browsers that do not support shadow dom (IE11 and Edge 18 and below), slot is polyfilled to simulate the same behavior. However, the host element's `childNodes` and `children` getters are not patched to only show the child nodes and elements of the default slot. Defaults to `false`.

docs/reference/support-policy.md

@@ -86,6 +86,7 @@ The table below describes recent versions of Stencil and the version of TypeScri
 
 | Stencil Version | TypeScript Version |
 |:---------------:|:------------------:|
+|     v4.10.0     |       v5.3.0       |
 |     v4.4.0      |       v5.2.2       |
 |     v4.2.0      |       v5.1.6       |
 |     v3.3.0      |       v5.0.4       |

docs/testing/01-overview.md

@@ -88,6 +88,26 @@ export const config: Config = {
 };
 ```
 
+### Command Line Arguments
+
+While the Stencil CLI offers a certain set of command line flags to specify e.g. which types of tests to run, you also have access to all Jest options through the CLI. For example to specify a single test, you can pass in a positional argument to Jest by adding a `--`, e.g.:
+
+```sh
+# run a single unit test
+npx stencil test --spec -- src/components/my-component/my-component.spec.ts
+# run a single e2e test
+npx stencil test --e2e -- src/components/my-component/my-component.e2e.ts
+```
+
+Next to positional arguments, Stencil also passes along [certain](https://github.com/ionic-team/stencil/blob/54d4ee252768e1d225baababee0093fdb0562b83/src/cli/config-flags.ts#L38-L85) Jest specific flags, e.g.:
+
+```sh
+# enable code coverage
+npx stencil test --spec --coverage
+```
+
+You can find more information about [Jest CLI options](https://jestjs.io/docs/cli) in the project documentation.
+
 ## Running and Debugging Tests in VS Code
 
 Adding the following configurations to `.vscode/launch.json` will allow you to use the VS Code Debugger to run the Stencil test runner for the currently active file in your editor.