+ __Example:__ + ```tsx + import { Component, Fragment, h } from '@stencil/core' + @Component({ + tag: 'cmp-fragment', + }) + export class CmpFragment { + render() { + return ( + <> +
...
+ ...
+ ...
+
+ );
+ }
+ }
+ ```
+
+### [**h()**](./templating-and-jsx.md):
+
+Turns JSX syntax into Virtual DOM elements. Read more on the [Templating and JSX](./templating-and-jsx.md#the-h-and-fragment-functions) page.
+
+### **render()**:
+
+A utility method to render a virtual DOM created by `h()` into a container.
+
+ __Type:__ `(vnode: VNode, container: Element) => void`
+ __Example:__
+ ```tsx
+ import { render } from '@stencil/core'
+ const vdom = (
+ Hello World!
+ )
+ render(vdom, document.body)
+ ```
+
+### [**readTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing):
+
+Schedules a DOM-read task. The provided callback will be executed in the best moment to perform DOM reads without causing layout thrashing.
+
+ __Type:__ `(task: Function) => void`
+
+### [**writeTask()**](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing):
+
+Schedules a DOM-write task. The provided callback will be executed in the best moment to perform DOM mutations without causing layout thrashing.
+
+ __Type:__ `(task: Function) => void`
+
+### **forceUpdate()**:
+
+Schedules a new render of the given instance or element even if no state changed. Notice `forceUpdate()` is not synchronous and might perform the DOM render in the next frame.
+
+ __Type:__ `(ref: any) => void`+ __Example:__ + ```ts + import { forceUpdate } from '@stencil/core' + + // inside a class component function + forceUpdate(this); + ``` + +### **getAssetPath()**: + + Gets the path to local assets. Refer to the [Assets](../guides/assets.md#getassetpath) page for usage info. + + __Type:__ `(path: string) => string`
+ __Example:__ + ```tsx + import { Component, Prop, getAssetPath, h } from '@stencil/core' + @Component({ + tag: 'cmp-asset', + }) + export class CmpAsset { + @Prop() icon: string; + + render() { + return ( +
}){kind=icon}
+ );
+ }
+ }
+ ```
+
+### **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`+ __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:__ `((elm: HTMLElement) => string | undefined | null) => void`
+ __Example:__ + ```ts + import { setMode } from '@stencil/core' + + // set mode based on a property + setMode((el) => el.getAttribute('mode')); + ``` + +### **getMode()**: + +Get the current style mode of your application. Refer to the [Styling](./styling.md#style-modes) page for usage info. + + __Type:__ `(ref: any) => string | undefined`
+ __Example:__ + ```ts + import { getMode } from '@stencil/core' + + getMode(this); + ``` + +### **getElement()**: + +Retrieve a Stencil element for a given reference. + + __Type:__ `(ref: any) => HTMLStencilElement`
+ __Example:__ + ```ts + import { getElement } from '@stencil/core' + + const stencilComponent = getElement(document.querySelector('my-cmp')) + if (stencilComponent) { + stencilComponent.componentOnReady().then(() => { ... }) + } + ``` + + ### **resolveVar()**: + + Because Stencil's decorators rely heavily on static analysis, you cannot use dynamic variables within them. `resolveVar` provides a deterministic way to find the string value of a given variable at compile time: + + __Type:__ `(variable: T) => string`
+ __Example:__ + ```tsx + import { Listen, Event, resolveVar } from '@stencil/core` + + const COMPONENT_A_EVENT: string = 'componentAEvent'; + const EVENTS = { + COMPONENT_B_EVENT: 'componentBEvent', + }; + + // inside an @Component class + + @Component({ + tag: 'dynamic-event-names', + }) + export class DynamicEventNames { + @Event({ eventName: resolveVar(COMPONENT_A_EVENT) }) myEvent; + + @Listen(resolveVar(EVENTS.COMPONENT_B_EVENT)) + listenHandler(){ + // + } + } + ``` + +### **Mixin()**: + +Compose multiple classes into a single constructor using factory functions. + + __Type:__ + ```ts +
{this.propA} {this.propB} {this.propC}
+ }
+ }
+ ```
+
+:::caution
+If your Stencil component library uses `Mixin()` (or `extends`) and *might* be used by other Stencil component libraries, ensure that all mixed-in factories are imported directly and **not** via [barrel files](https://basarat.gitbook.io/typescript/main-1/barrel).
+The static-analysis that Stencil uses to find mixed-in classes does not work within 3rd party (node_module) barrel files.
+:::
+
+For detailed guidance on using `Mixin()` and `extends` for component architecture, including when to use inheritance vs composition patterns, see the [Extends & Mixins](../guides/extends.md) guide.
+
+### [**setTagTransformer()** and **transformTag()**](../guides/tag-transformation.md):
+
+Manage tag name transformation at runtime. Refer to the [Tag Transformation](../guides/tag-transformation.md) page for usage info.
\ No newline at end of file
diff --git a/versioned_docs/version-v4.42/components/attach-internals.md b/versioned_docs/version-v4.42/components/attach-internals.md
new file mode 100644
index 000000000..b624e569e
--- /dev/null
+++ b/versioned_docs/version-v4.42/components/attach-internals.md
@@ -0,0 +1,68 @@
+---
+title: Attach Internals
+sidebar_label: Attach Internals
+description: attach internals decorator
+slug: /attach-internals
+---
+
+# Attach Internals Decorator
+
+The `@AttachInternals` decorator is used to attach [ElementInternals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals) to a Stencil component.
+This allows you to leverage features such as [Custom States](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet) and [Form Association](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals#form_association).
+
+## Form Association
+
+Read the dedicated guide on [Form Associated Components](./form-associated.md) and how to use `@AttachInternals` there.
+
+## Custom States
+
+You can use the `@AttachInternals` decorator to define [Custom States](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet) for your component.
+
+```tsx
+import { Component, h, AttachInternals } from '@stencil/core';
+/**
+ * My Element component
+ */
+@Component({
+ tag: 'my-element',
+ styleUrl: 'my-element.css',
+})
+export class MyElement {
+ @AttachInternals({
+ states: {
+ /** A custom state for my element */
+ 'my-custom-state': true,
+ /** Another custom state for my element */
+ 'another-state': false
+ }
+ }) internals: ElementInternals;
+ render() {
+ return My Element
;
+ }
+}
+```
+
+In the example above, we define two custom states: `my-custom-state` and `another-state`.
+
+The initial values of the custom states can be set via the `states` object and
+later on, you can update the states dynamically using the `internals.states` property. For example:
+
+```tsx
+handleClick() {
+ this.internals.states.add('another-state'); // to add a state
+ this.internals.states.delete('my-custom-state'); // to remove a state
+}
+```
+
+You or your element users can then use custom states in CSS like so:
+
+```css
+/* Use them internally... */
+:host(:state(my-custom-state)) {
+ background-color: yellow;
+}
+/* ... Or use them externally */
+my-element:state(another-state) {
+ border: 2px solid red;
+}
+```
diff --git a/versioned_docs/version-v4.42/components/component-lifecycle.md b/versioned_docs/version-v4.42/components/component-lifecycle.md
new file mode 100644
index 000000000..72609e476
--- /dev/null
+++ b/versioned_docs/version-v4.42/components/component-lifecycle.md
@@ -0,0 +1,182 @@
+---
+title: Component Lifecycle Methods
+sidebar_label: Lifecycle Methods
+description: Component Lifecycle Methods
+slug: /component-lifecycle
+---
+
+# Component Lifecycle Methods
+
+Components have numerous lifecycle methods which can be used to know when the component "will" and "did" load, update, and render. These methods can be added to a component to hook into operations at the right time.
+
+Implement one of the following methods within a component class and Stencil will automatically call them in the right order:
+
+import LifecycleMethodsChart from '@site/src/components/LifecycleMethodsChart';
+
++This value sets the name of the custom element that Stencil will generate. +To adhere to the [HTML spec](https://html.spec.whatwg.org/#valid-custom-element-name), the tag name must contain a dash ('-'). + +Ideally, the tag name is a globally unique value. +Having a globally unique value helps prevent naming collisions with the global `CustomElementsRegistry`, where all custom elements are defined. +It's recommended to choose a unique prefix for all your components within the same collection. + +**Example**:
+```tsx +import { Component } from '@stencil/core'; + +@Component({ + tag: 'todo-list', +}) +export class TodoList { + // implementation omitted +} +``` +After compilation, the component defined in `TodoList` can be used in HTML or another TSX file: +```html + +
+`assetsDirs` is an array of relative paths from the component to a directory containing the static files (assets) the component requires. + +**Example**:
+Below is an example project's directory structure containing an example component and assets directory. + +``` +src/ +└── components/ + ├── assets/ + │ └── sunset.jpg + └── todo-list.tsx +``` + +Below, the `todo-list` component will correctly load the `sunset.jpg` image from the `assets/` directory, using Stencil's [`getAssetPath()`](../guides/assets.md#getassetpath). + +```tsx +import { Component, Prop, getAssetPath, h } from '@stencil/core'; + +@Component({ + tag: 'todo-list', + // 1. assetsDirs lists the 'assets' directory as a relative (sibling) + // directory + assetsDirs: ['assets'] +}) +export class TodoList { + image = "sunset.jpg"; + + render() { + // 2. the asset path is retrieved relative to the asset base path to use in + // the
+If `true`, the component will use [scoped stylesheets](./styling.md#scoped-css). + +Scoped CSS is an alternative to using the native [shadow DOM](./styling.md#shadow-dom) style encapsulation. +It appends a data attribute to your styles to make them unique and thereby scope them to your component. +It does not, however, prevent styles from the light DOM from seeping into your component. + +To use the native [shadow DOM](./styling.md#shadow-dom), see the configuration for [`shadow`](#shadow). + +This option cannot be set to `true` if `shadow` is enabled. + +**Example**:
+```tsx +import { Component } from '@stencil/core'; + +@Component({ + tag: 'todo-list', + scoped: true +}) +export class TodoList { + // implementation omitted +} +``` + +### shadow + +**Optional** + +**Type: `boolean | { delegatesFocus?: boolean, slotAssignment?: 'manual' | 'named' }`** + +**Default: `false`** + +**Details:**
+If `true`, the component will use [native Shadow DOM encapsulation](./styling.md#shadow-dom). +It will fall back to `scoped` if the browser does not support shadow-dom natively. + +`delegatesFocus` is a property that [provides focus](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/delegatesFocus) to the first focusable entry in a component using Shadow DOM. +If an object literal containing `delegatesFocus` is provided, the component will use [native Shadow DOM encapsulation](./styling.md#shadow-dom), regardless of the value assigned to `delegatesFocus`. + +When `delegatesFocus` is set to `true`, the component will have `delegatesFocus: true` added to its shadow DOM. + +When `delegatesFocus` is `true` and a non-focusable part of the component is clicked: +- the first focusable part of the component is given focus +- the component receives any available `focus` styling + +When `slotAssignment` is set to `'manual'` or `'named'`, the component will have `slotAssignment` added to its shadow DOM. + +`slotAssignment: 'manual'` enables [manual slot assignment](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/slotAssignment) (otherwise known as [imperative slot assignment](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Imperative-Shadow-DOM-Distribution-API.md)) for the component. + +If `shadow` is set to `false`, the component will not use native shadow DOM encapsulation. + +This option cannot be set to enabled if `scoped` is enabled. + +**Example 1**:
+```tsx +import { Component } from '@stencil/core'; + +@Component({ + tag: 'todo-list', + shadow: true +}) +export class TodoList { + // implementation omitted +} +``` + +**Example 2**:
+```tsx +import { Component } from '@stencil/core'; + +@Component({ + tag: 'todo-list', + shadow: { + delegatesFocus: true, + } +}) +export class TodoList { + // implementation omitted +} +``` + +### styleUrl + +**Optional** + +**Type: `string`** + +**Details:**
+Relative URL to an external stylesheet containing styles to apply to your component. +Out of the box, Stencil will only process CSS files (files ending with `.css`). +Support for additional CSS variants, like Sass, can be added via [a plugin](https://stenciljs.com/docs/plugins#related-plugins). + +**Example**:
+Below is an example project's directory structure containing an example component and stylesheet. +``` +src/ +└── components/ + ├── todo-list.css + └── todo-list.tsx +``` + +By setting `styleUrl`, Stencil will apply the `todo-list.css` stylesheet to the `todo-list` component: + +```tsx +import { Component } from '@stencil/core'; + +@Component({ + tag: 'todo-list', + styleUrl: './todo-list.css', +}) +export class TodoList { + // implementation omitted +} +``` + +### styleUrls + +**Optional** + +**Type: `string[] | { [modeName: string]: string | string[]; }`** + +**Details:**
+A list of relative URLs to external stylesheets containing styles to apply to your component. + +Alternatively, an object can be provided that maps a named "mode" to one or more stylesheets. + +Out of the box, Stencil will only process CSS files (ending with `.css`). +Support for additional CSS variants, like Sass, can be added via [a plugin](https://stenciljs.com/docs/plugins#related-plugins). + +**Example**:
+Below is an example project's directory structure containing an example component and stylesheet. +``` +src/ +└── components/ + ├── todo-list-1.css + ├── todo-list-2.css + └── todo-list.tsx +``` + +By setting `styleUrls`, Stencil will apply both stylesheets to the `todo-list` component: + +```tsx title="Using an array of styles" +import { Component } from '@stencil/core'; + +@Component({ + tag: 'todo-list', + styleUrls: ['./todo-list-1.css', './todo-list-2.css'] +}) +export class TodoList { + // implementation omitted +} +``` + +```tsx title="Using modes" +import { Component } from '@stencil/core'; + +@Component({ + tag: 'todo-list', + styleUrls: { + ios: 'todo-list-1.ios.scss', + md: 'todo-list-2.md.scss', + } +}) +export class TodoList { + // implementation omitted +} +``` + +Read more on styling modes in the Components [Styling](./styling.md#style-modes) section. + +### styles + +**Optional** + +**Type: `string | { [modeName: string]: any }`** + +**Details:**
+A string that contains inlined CSS instead of using an external stylesheet. +The performance characteristics of this feature are the same as using an external stylesheet. + +When using `styles`, only CSS is permitted. +See [`styleUrl`](#styleurl) if you need more advanced features. + +**Example**:
+```tsx +import { Component } from '@stencil/core'; + +@Component({ + tag: 'todo-list', + styles: 'div { background-color: #fff }' +}) +export class TodoList { + // implementation omitted +} +``` + +## Embedding or Nesting Components + +Components can be composed easily by adding the HTML tag to the JSX code. Since the components are just HTML tags, nothing needs to be imported to use a Stencil component within another Stencil component. + +Here's an example of using a component within another component: + +```tsx +import { Component, Prop, h } from '@stencil/core'; + +@Component({ + tag: 'my-embedded-component' +}) +export class MyEmbeddedComponent { + @Prop() color: string = 'blue'; + + render() { + return ( +
My favorite color is {this.color}
+ );
+ }
+}
+```
+
+```tsx
+import { Component, h } from '@stencil/core';
+
+@Component({
+ tag: 'my-parent-component'
+})
+export class MyParentComponent {
+
+ render() {
+ return (
+
+
+ );
+ }
+}
+```
+
+The `my-parent-component` includes a reference to the `my-embedded-component` in the `render()` function.
+
+## Component Architecture Patterns
+
+Stencil supports advanced component architecture patterns including class inheritance and composition. Learn more about organizing component logic with controllers in the [Extends & Mixins](../guides/extends.md) guide.
diff --git a/versioned_docs/version-v4.42/components/events.md b/versioned_docs/version-v4.42/components/events.md
new file mode 100644
index 000000000..96ed92f07
--- /dev/null
+++ b/versioned_docs/version-v4.42/components/events.md
@@ -0,0 +1,225 @@
+---
+title: Events
+sidebar_label: Events
+description: Events
+slug: /events
+---
+
+# Events
+
+There is **NOT** such a thing as *stencil events*, instead, Stencil encourages the use of [DOM events](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events).
+However, Stencil does provide an API to specify the events a component can emit, and the events a component listens to. It does so with the `Event()` and `Listen()` decorators.
+
+## Event Decorator
+
+Components can emit data and events using the Event Emitter decorator.
+
+To dispatch [Custom DOM events](https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events) for other components to handle, use the `@Event()` decorator.
+
+```tsx
+import { Event, EventEmitter } from '@stencil/core';
+
+...
+export class TodoList {
+
+ @Event() todoCompleted: EventEmitter
+ Mock Date Picker, mode: {this.view}
+ this.onInputChange(e)}>
+
+ }
+}
+```
+
+Note that the `formStateRestoreCallback` also receives a second argument,
+`mode`, which can be either `"restore"` or `"autocomplete"`, indicating the
+reason for the form restoration.
+
+For more on form restoration, including a complete example, check out [this
+great blog post on the
+subject](https://web.dev/articles/more-capable-form-controls#restoring-form-state).
+
+## Resources
+
+- [WHATWG specification for form-associated custom elements](https://html.spec.whatwg.org/dev/custom-elements.html#form-associated-custom-elements)
+- [ElementInternals and Form-Associated Custom Elements](https://webkit.org/blog/13711/elementinternals-and-form-associated-custom-elements/) from the WebKit blog
+- [Web.dev post detailing how form-associated lifecycle callbacks work](https://web.dev/articles/more-capable-form-controls#lifecycle_callbacks)
+
diff --git a/versioned_docs/version-v4.42/components/functional-components.md b/versioned_docs/version-v4.42/components/functional-components.md
new file mode 100644
index 000000000..cd3b27af2
--- /dev/null
+++ b/versioned_docs/version-v4.42/components/functional-components.md
@@ -0,0 +1,108 @@
+---
+title: Functional Components
+sidebar_label: Functional Components
+description: Functional Components
+slug: /functional-components
+---
+
+# Working with Functional Components
+
+Functional components are quite different to normal Stencil web components because they are a part of Stencil's JSX compiler. A functional component is basically a function that takes an object of props and turns it into JSX.
+
+```tsx
+const Hello = props => Hello, {props.name}!
; +``` + +When the JSX transpiler encounters such a component, it will take its attributes, pass them into the function as the `props` object, and replace the component with the JSX that is returned by the function. + +```tsx +Hello, {props.name}
, + children +]; +``` + +The JSX transpiler passes all child elements of the component as an array into the function's `children` argument. + +```tsx +I'm a child element.
+Hello, {name}!
+); +``` + +## Working with children + +The second argument of a functional component receives the passed children, but in order to work with them, `FunctionalComponent` provides a utils object that exposes a `map()` method to transform the children, and a `forEach()` method to read them. Reading the `children` array is not recommended since the stencil compiler can rename the vNode properties in prod mode. + +```tsx +export interface FunctionalUtilities { + forEach: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => void) => void; + map: (children: VNode[], cb: (vnode: ChildNode, index: number, array: ChildNode[]) => ChildNode) => VNode[]; +} +export interface ChildNode { + vtag?: string | number | Function; + vkey?: string | number; + vtext?: string; + vchildren?: VNode[]; + vattrs?: any; + vname?: string; +} +``` + +**Example:** + +```tsx +export const AddClass: FunctionalComponent = (_, children, utils) => ( + utils.map(children, child => ({ + ...child, + vattrs: { + ...child.vattrs, + class: `${child.vattrs.class} add-class` + } + } + )) +); +``` + +:::note +When using a functional component in JSX, its name must start with a capital letter. Therefore it makes sense to export it as such. +::: + + +## Disclaimer + +There are a few major differences between functional components and class components. Since functional components are just syntactic sugar within JSX, they... + +* aren't compiled into web components, +* don't create a DOM node, +* don't have a Shadow DOM or scoped styles, +* don't have lifecycle hooks, +* are stateless. + +When deciding whether to use functional components, one concept to keep in mind is that often the UI of your application can be a function of its state, i. e., given the same state, it always renders the same UI. If a component has to hold state, deal with events, etc, it should probably be a class component. If a component's purpose is to simply encapsulate some markup so it can be reused across your app, it can probably be a functional component (especially if you're using a component library and thus don't need to style it). + +:::caution +Stencil does not support re-exporting a functional component from a "barrel file" and dynamically rendering it in another component. This is a [known limitation](https://github.com/ionic-team/stencil/issues/5246) within Stencil. Instead, either use class components and remove the import or import the functional component directly. +::: \ No newline at end of file diff --git a/versioned_docs/version-v4.42/components/host-element.md b/versioned_docs/version-v4.42/components/host-element.md new file mode 100644 index 000000000..c391fbe35 --- /dev/null +++ b/versioned_docs/version-v4.42/components/host-element.md @@ -0,0 +1,159 @@ +--- +title: Working with host elements +sidebar_label: Host Element +description: Working with host elements +slug: /host-element +--- + +# Working with host elements + +Stencil components render their children declaratively in their `render` method [using JSX](./templating-and-jsx.md). Most of the time, the `render()` function describes the children elements that are about to be rendered, but it can also be used to render attributes of the host element itself. + + +## `Title
+Message
+Title
+Message
+{this.getData()}
+ );
+ }
+}
+```
diff --git a/versioned_docs/version-v4.42/components/properties.md b/versioned_docs/version-v4.42/components/properties.md
new file mode 100644
index 000000000..72ffab61a
--- /dev/null
+++ b/versioned_docs/version-v4.42/components/properties.md
@@ -0,0 +1,1020 @@
+---
+title: Properties
+sidebar_label: Properties
+description: Properties
+slug: /properties
+---
+
+# Properties
+
+Props are custom attributes/properties exposed publicly on an HTML element. They allow developers to pass data to a
+component to render or otherwise use.
+
+## The Prop Decorator (`@Prop()`)
+
+Props are declared on a component using Stencil's `@Prop()` decorator, like so:
+
+```tsx
+// First, we import Prop from '@stencil/core'
+import { Component, Prop, h } from '@stencil/core';
+
+@Component({
+ tag: 'todo-list',
+})
+export class TodoList {
+ // Second, we decorate a class member with @Prop()
+ @Prop() name: string;
+
+ render() {
+ // Within the component's class, its props are
+ // accessed via `this`. This allows us to render
+ // the value passed to `todo-list`
+ return To-Do List Name: {this.name}
+ }
+}
+```
+
+In the example above, `@Prop()` is placed before (decorates) the `name` class member, which is a string. By adding
+`@Prop()` to `name`, Stencil will expose `name` as an attribute on the element, which can be set wherever the component
+is used:
+
+```tsx
+{/* Here we use the component in a TSX file */}
+{this.thingToDo}
;
+ }
+}
+```
+
+Since `thingToDo` is a prop, we can provide a value for it when we use our `todo-list-item` component. Providing a
+value to a camelCased prop like `thingToDo` is nearly identical in TSX and HTML.
+
+When we use our component in a TSX file, an attribute uses camelCase:
+
+```tsx
+
+
+ )
+ }
+}
+```
+```tsx
+import { Component, Prop, h } from '@stencil/core';
+
+@Component({
+ tag: 'todo-list-item',
+})
+export class ToDoListItem {
+ @Prop() thingToDo: string;
+
+ render() {
+ return To-Do List Name: Stencil To Do List
+-
+ {/* Below are three Stencil components that are children of `todo-list`, each representing an item on our list */}
+
-
+
- isComplete has a value of - {this.isComplete} - and a typeof value of "{typeof this.isComplete}" +
- label has a value of - {this.label} - and a typeof value of "{typeof this.label}" +
- thingToDo has a value of - {this.thingToDo} - and a typeof value of "{typeof this.thingToDo}" +
-
+
- completeMsg has a value of - {this.completeMsg} - and a typeof value of "{typeof this.completeMsg}" +
- label has a value of - {this.label} - and a typeof value of "{typeof this.label}" +
- thingToDo has a value of - {this.thingToDo} - and a typeof value of "{typeof this.thingToDo}" +
The number is {this.aNumber} and the string is {this.aString}
+ }
+}
+```
+Regardless of if we use this component in HTML or TSX, "The number is 42 and the string is defaultValue" is displayed
+when no values are passed to our component:
+```html
+Hello, World! I'm {this.contents[0]}
;
+ }
+}
+```
+
+In the example above, updating the Prop in place using `this.contents.push('Stencil')` would have no effect.
+Stencil does not see the change to `this.contents`, since it looks at the _reference_ of the Prop, and sees that it has not changed.
+This is done for performance reasons.
+If Stencil had to walk every slot of the array to determine if it changed, it would incur a performance hit.
+Rather, it is considered better for performance and more idiomatic to re-assign the Prop (in the example above, we use the spread operator).
+
+The same holds for objects as well.
+Rather than mutating an existing object in-place, a new object should be created using the spread operator. This object will be different-by-reference and therefore will trigger a re-render:
+
+
+```tsx
+import { Component, Prop, h } from '@stencil/core';
+
+export type MyContents = {name: string};
+
+@Component({
+ tag: 'my-component',
+})
+export class MyComponent {
+ @Prop({mutable: true}) contents: MyContents;
+ timer: NodeJS.Timer;
+
+ connectedCallback() {
+ this.timer = setTimeout(() => {
+ // this does not create a new object. when stencil
+ // attempts to see if any of its Props have changed,
+ // it sees the reference to its `contents` Prop is
+ // the same, and will not trigger a render
+
+ // this.contents.name = 'Stencil';
+
+ // this does create a new object, and therefore a
+ // new reference to the Prop. Stencil will pick up
+ // this change and rerender
+ this.contents = {...this.contents, name: 'Stencil'};
+ // after 3 seconds, the component will re-render due
+ // to the reference change in `this.contents`
+ }, 3000);
+ }
+
+ disconnectedCallback() {
+ if (this.timer) {
+ clearTimeout(this.timer);
+ }
+ }
+
+ render() {
+ return Hello, World! I'm {this.contents.name}
;
+ }
+}
+```
+
+### Reflect Properties Values to Attributes (`reflect`)
+
+In some cases it may be useful to keep a Prop in sync with an attribute. In this case you can set the `reflect` option
+in the `@Prop()` decorator to `true`. When a prop is reflected, it will be rendered in the DOM as an HTML attribute.
+
+Take the following component as example:
+
+```tsx
+import { Component, Prop, h } from '@stencil/core';
+
+@Component({
+ tag: 'todo-list-item',
+})
+export class ToDoListItem {
+ @Prop({ reflect: false }) isComplete: boolean = false;
+ @Prop({ reflect: true }) timesCompletedInPast: number = 2;
+ @Prop({ reflect: true }) thingToDo: string = "Read Reflect Section of Stencil Docs";
+}
+```
+
+The component in the example above uses [default values](#default-values), and can be used in HTML like so:
+```html
+
+
+ randNumbers contains:
+
+ )
+ }
+}
+```
+
+### Updating an object
+
+The spread operator should be used to update objects.
+As with arrays, mutating an object will not trigger a view update in Stencil.
+However, using the spread operator and assigning its return value to the `@Prop()` or `@State()` class member being watched will.
+Below is an example:
+
+```tsx
+import { Component, State, Watch, h } from '@stencil/core';
+
+export type NumberContainer = {
+ val: number,
+}
+
+@Component({
+ tag: 'rand-numbers'
+})
+export class RandomNumbers {
+ // We decorate a class member with @State() so that we
+ // can apply @Watch(). This will hold a randomly generated
+ // number.
+ @State() numberContainer: NumberContainer = { val: 0 };
+
+ private timer: NodeJS.Timer;
+
+ // Apply @Watch() for the component's `numberContainer` member.
+ // Whenever `numberContainer` changes, this method will fire.
+ @Watch('numberContainer')
+ watchStateHandler(newValue: NumberContainer, oldValue: NumberContainer) {
+ console.log('The old value of numberContainer is: ', oldValue);
+ console.log('The new value of numberContainer is: ', newValue);
+ }
+
+ connectedCallback() {
+ this.timer = setInterval(() => {
+ // generate a random whole number
+ const newVal = Math.ceil(Math.random() * 100);
+
+ /**
+ * This does not create a new object. When stencil
+ * attempts to see if any Watched members have changed,
+ * it sees the reference to its `numberContainer` State is
+ * the same, and will not trigger `@Watch` or are-render
+ */
+ // this.numberContainer.val = newVal;
+
+ /**
+ * Using the spread operator, on the other hand, does
+ * create a new object. `numberContainer` is reassigned
+ * using the value returned by the spread operator.
+ * The reference to `numberContainer` has changed, which
+ * will trigger `@Watch` and a re-render
+ */
+ this.numberContainer = {...this.numberContainer, val: newVal};
+ }, 1000)
+ }
+
+ disconnectedCallback() {
+ if (this.timer) {
+ clearInterval(this.timer)
+ }
+ }
+
+ render() {
+ return -
+ {this.randNumbers.map((num) =>
- {num} )} +
numberContainer contains: {this.numberContainer.val}
;
+ }
+}
+```
diff --git a/versioned_docs/version-v4.42/components/serialization-deserialization.md b/versioned_docs/version-v4.42/components/serialization-deserialization.md
new file mode 100644
index 000000000..586cc1613
--- /dev/null
+++ b/versioned_docs/version-v4.42/components/serialization-deserialization.md
@@ -0,0 +1,196 @@
+---
+title: Serialization & Deserialization
+sidebar_label: Serialization & Deserialization
+description: Serialization & Deserialization
+slug: /serialization
+---
+
+# Serialization & Deserialization
+
+Custom elements interact with the DOM either via HTML [attributes](https://open-wc.org/guides/knowledge/attributes-and-properties/#attributes) (always strings) or JavaScript [properties](https://open-wc.org/guides/knowledge/attributes-and-properties/#properties). Stencil automatically tries to keep properties and attributes in-sync when possible via **serialization** (turning properties into strings) and **deserialization** (turning strings back into properties).
+
+For example, if you have a component defined like this:
+
+```tsx
+@Component({
+ tag: 'my-component',
+})
+export class MyComponent {
+ // Stencil 'sees' this as a number type.
+ // Numbers are easy to convert to/from strings
+ @Prop({ reflect: true }) myNumber: number;
+}
+```
+
+When the property is set via JavaScript:
+
+```js
+const myComponent = document.querySelector('my-component');
+myComponent.myNumber = 42;
+```
+
+Stencil will automatically serialize `myNumber` to an attribute:
+
+```html
+
+
+ );
+ }
+}
+```
+
+It's important to note that it's the reassignment of `this.items` that is causing the rerender in `connectedCallback()`:
+```ts
+this.items = [...this.items, newTodo];
+```
+
+Mutating the existing reference to `this.items` like in the examples below will not cause a rerender, as Stencil will
+not know that the contents of the array has changed:
+```ts
+// updating `items` either of these ways will not
+// cause a rerender
+this.items.push(newTodo);
+this.items[this.items.length - 1] = newTodo;
+```
+
+Similar to the examples above, this code sample makes use of the
+[connectedCallback() lifecycle method](./component-lifecycle.md#connectedcallback) to create a new `Item` and add
+it to `items` every 2000 milliseconds (every two seconds). The example above also makes use of the
+[disconnectedCallback() lifecycle method](./component-lifecycle.md#disconnectedcallback) to properly clean up the timer
+that was created using `setInterval` in `connectedCallback()`.
diff --git a/versioned_docs/version-v4.42/components/styling.md b/versioned_docs/version-v4.42/components/styling.md
new file mode 100644
index 000000000..1da0f41c4
--- /dev/null
+++ b/versioned_docs/version-v4.42/components/styling.md
@@ -0,0 +1,374 @@
+---
+title: Styling Components
+sidebar_label: Styling
+description: Styling Components
+slug: /styling
+---
+
+# Styling Components
+
+## Shadow DOM
+
+### What is the Shadow DOM?
+
+The [shadow DOM](https://developers.google.com/web/fundamentals/web-components/shadowdom) is an API built into the browser that allows for DOM encapsulation and style encapsulation. It is a core aspect of the Web Component standards. The shadow DOM shields a component's styles, markup, and behavior from its surrounding environment. This means that we do not need to be concerned about scoping our CSS to our component, nor worry about a component's internal DOM being interfered with by anything outside the component.
+
+When talking about the shadow DOM, we use the term "light DOM" to refer to the "regular" DOM. The light DOM encompasses any part of the DOM that does not use the shadow DOM.
+
+### Shadow DOM in Stencil
+
+The shadow DOM hides and separates the DOM of a component in order to prevent clashing styles or unwanted side effects. We can use the shadow DOM in our Stencil components to ensure our components won't be affected by the applications in which they are used.
+
+To use the Shadow DOM in a Stencil component, you can set the `shadow` option to `true` in the component decorator.
+
+```tsx
+@Component({
+ tag: 'shadow-component',
+ styleUrl: 'shadow-component.css',
+ shadow: true,
+})
+export class ShadowComponent {}
+```
+
+If you'd like to learn more about enabling and configuring the shadow DOM, see the [shadow field of the component api](./component.md#component-options).
+
+By default, components created with the [`stencil generate` command](../config/cli.md#stencil-generate) use the shadow DOM.
+
+### Styling with the Shadow DOM
+
+With the shadow DOM enabled, elements within the shadow root are scoped, and styles outside of the component do not apply. As a result, CSS selectors inside the component can be simplified, as they will only apply to elements within the component. We do not have to include any specific selectors to scope styles to the component.
+
+```css
+:host {
+ color: black;
+}
+
+div {
+ background: blue;
+}
+```
+
+:::note
+The `:host` pseudo-class selector is used to select the [`Host` element](./host-element.md) of the component
+:::
+
+With the shadow DOM enabled, only these styles will be applied to the component. Even if a style in the light DOM uses a selector that matches an element in the component, those styles will not be applied.
+
+### Shadow DOM QuerySelector
+
+When using Shadow DOM and you want to query an element inside your web component, you must first use the [`@Element` decorator](./host-element.md#element-decorator) to gain access to the host element, and then you can use the `shadowRoot` property to perform the query. This is because all of your DOM inside your web component is in a shadowRoot that Shadow DOM creates. For example:
+
+```tsx
+import { Component, Element } from '@stencil/core';
+
+@Component({
+ tag: 'shadow-component',
+ styleUrl: 'shadow-component.css',
+ shadow: true
+})
+export class ShadowComponent {
+
+ @Element() el: HTMLElement;
+
+ componentDidLoad() {
+ const elementInShadowDom = this.el.shadowRoot.querySelector('.a-class-selector');
+
+ ...
+ }
+
+}
+```
+
+### Shadow DOM Browser Support
+
+The shadow DOM is currently natively supported in the following browsers:
+
+- Chrome
+- Firefox
+- Safari
+- Edge (v79+)
+- Opera
+
+In browsers which do not support the shadow DOM we fall back to scoped CSS. This gives you the style encapsulation that comes along with the shadow DOM but without loading in a huge shadow DOM polyfill.
+
+### Scoped CSS
+
+An alternative to using the shadow DOM is using scoped components. You can use scoped components by setting the `scoped` option to `true` in the component decorator.
+
+```tsx
+@Component({
+ tag: 'scoped-component',
+ styleUrl: 'scoped-component.css',
+ scoped: true,
+})
+export class ScopedComponent {}
+```
+
+Scoped CSS is a proxy for style encapsulation. It works by appending a data attribute to your styles to make them unique and thereby scope them to your component. It does not, however, prevent styles from the light DOM from seeping into your component.
+
+## CSS Custom Properties
+
+CSS custom properties, also often referred to as CSS variables, are used to contain values that can then be used in multiple CSS declarations. For example, we can create a custom property called `--color-primary` and assign it a value of `blue`.
+
+```css
+:host {
+ --color-primary: blue;
+}
+```
+
+And then we can use that custom property to style different parts of our component
+
+```css
+h1 {
+ color: var(--color-primary);
+}
+```
+
+### Customizing Components with Custom Properties
+
+CSS custom properties can allow the consumers of a component to customize a component's styles from the light DOM. Consider a `shadow-card` component that uses a custom property for the color of the card heading.
+
+```css
+:host {
+ --heading-color: black;
+}
+
+.heading {
+ color: var(--heading-color);
+}
+```
+
+:::note
+CSS custom properties must be declared on the `Host` element (`:host`) in order for them to be exposed to the consuming application.
+:::
+
+The `shadow-card` heading will have a default color of `black`, but this can now be changed in the light DOM by selecting the `shadow-card` and changing the value of the `--heading-color` custom property.
+
+```css
+shadow-card {
+ --heading-color: blue;
+}
+```
+
+## CSS Parts
+
+CSS custom properties can be helpful for customizing components from the light DOM, but they are still a little limiting as they only allow a user to modify specific properties. For situations where users require a higher degree of flexibility, we recommend using the [CSS `::part()` pseudo-element](https://developer.mozilla.org/en-US/docs/Web/CSS/::part). You can define parts on elements of your component with the "part" attribute.
+
+```tsx
+@Component({
+ tag: 'shadow-card',
+ styleUrl: 'shadow-card.css',
+ shadow: true,
+})
+export class ShadowCard {
+ @Prop() heading: string;
+
+ render() {
+ return (
+ To-Do List
+-
+ {this.items.map((todo) =>
- {todo.description} #{todo.id} )} +
{this.heading}
+Outer Component
+Inner Component
+Hello
`, it gets transformed into function calls like `h('div', null, 'Hello')`. The `Fragment` function is used to group a list of children without adding extra nodes to the DOM.
+
+#### Set up in Stencil
+
+Within your Stencil project, make sure to add or modify your `tsconfig.json` file, adding:
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "react",
+ "jsxFactory": "h",
+ "jsxFragmentFactory": "Fragment"
+ }
+}
+```
+
+You will then need to import `h` (and `Fragment` if you plan to use it) from `@stencil/core` at the top of your component file:
+
+```tsx
+import { h, Fragment, Component } from '@stencil/core';
+
+@Component({
+ tag: 'my-component',
+})
+class MyComponent { ... }
+```
+
+(Read more about using the `Fragment` component in the [Complex Template Content](#complex-template-content) section below.)
+
+### `jsxImportSource` alternative
+
+`jsxImportSource` is a more modern approach that automatically imports the necessary JSX runtime functions instead of manually importing `h`; the compiler automatically imports what it needs from the specified package.
+
+#### Set up in Stencil
+
+To use `jsxImportSource`, modify your `tsconfig.json` file as follows:
+
+```json
+{
+ "compilerOptions": {
+ "jsx": "react-jsx",
+ "jsxImportSource": "@stencil/core"
+ }
+}
+```
+
+Using this approach means you do not need to manually import `h` or `Fragment` in your component files.
+
+### The `render` function
+
+The `render` function is used within your component to output a tree of elements that will be drawn to the screen.
+
+```tsx
+class MyComponent {
+ render() {
+ return (
+
+
+ );
+ }
+}
+```
+
+In this example we're returning the JSX representation of a `div`, with two child elements: an `h1` and a `p`.
+
+### Host Element
+
+If you want to modify the host element itself, such as adding a class or an attribute to the component itself, use the `Hello World
+This is JSX!
+Hello {this.name}
+ )
+}
+```
+
+:::note
+If you're familiar with ES6 template variables, JSX variables are very similar, just without the `$`:
+:::
+
+```tsx
+//ES6
+`Hello ${this.name}`
+
+//JSX
+Hello {this.name}
+```
+
+
+## Conditionals
+
+If we want to conditionally render different content, we can use JavaScript if/else statements:
+Here, if `name` is not defined, we can just render a different element.
+
+```tsx
+render() {
+ if (this.name) {
+ return ( Hello {this.name}
)
+ } else {
+ return ( Hello, World
)
+ }
+}
+```
+
+Additionally, inline conditionals can be created using the JavaScript ternary operator:
+
+```tsx
+render() {
+ return (
+
+ {this.name
+ ?
+ );
+}
+```
+
+**Please note:** Stencil reuses DOM elements for better performance. Consider the following code:
+
+```tsx
+{someCondition
+ ? Hello {this.name}
+ :Hello World
+ } +
+
+ );
+}
+
+```
+
+Then, if a user passes child components when creating our component `my-component`, then `my-component` will place that
+component inside of the second `A Component
+` above:
+
+```tsx
+render(){
+ return(
+
+
+ )
+}
+```
+
+Slots can also have `name`s to allow for specifying slot output location:
+
+```tsx
+// my-component.tsx
+
+render(){
+ return [
+
+
+ )
+}
+```
+
+### 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
+component trees mixing shadow and non-shadow components, or when passing a slot through many levels of components. In many cases, this behavior can
+be remedied by wrapping the `slot` in an additional element (like a `div` or `span`) so the Stencil runtime can correctly "anchor" the relocated
+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:
+ It is recommended that slot names stay consistent when slotting content through multiple levels of components. **Avoid** defining slot tags like + `
Child Element
+Here is my main content
, +I'll be placed before the h1
+I'll be placed after the h1
++ It is recommended that slot names stay consistent when slotting content through multiple levels of components. **Avoid** defining slot tags like + `
+ {this.todos.map((todo) => (
+ { todo.taskName }
+ )}
+
+
+ { todos[0].taskName }
+ { todos[1].taskName }
+
+
+ )
+}
+```
+
+If this array of children is dynamic, i.e., if any nodes may be added,
+removed, or reordered, then it's a good idea to set a unique `key` attribute on
+each element like so:
+
+```tsx
+render() {
+ return (
+
+ {this.todos.map((todo) => (
+
+ )
+}
+```
+
+When nodes in a children array are rearranged Stencil makes an effort to
+preserve DOM nodes across renders but it isn't able to do so in all cases.
+Setting a `key` attribute lets Stencil ensure it can match up new and old
+children across renders and thereby avoid recreating DOM nodes unnecessarily.
+
+:::caution
+Do not use an array index or some other non-unique value as a key. Try to
+ensure that each child has a key which does not change and which is unique
+among all its siblings.
+:::
+
+### Automatic Key Insertion
+
+During compilation Stencil will automatically add key attributes to any JSX
+nodes in your component's render method which are not nested within curly
+braces. This allows Stencil’s runtime to accurately reconcile children when
+their order changes or when a child is conditionally rendered.
+
+For instance, consider a render method looking something like this:
+
+```tsx
+ render() {
+ return (
+
+
+ ))}
+ {todo.taskName}
+
+ { this.disabled &&
+ );
+ }
+```
+
+While it might seem like adding a key attribute to the `#slot-wrapper` div
+could help ensure that elements will be matched up correctly when the component
+re-renders, this is actually superfluous because Stencil will automatically add
+a key to that element when it compiles your component.
+
+:::note
+The Stencil compiler can only safely perform automatic key insertion in certain
+scenarios where there is no danger of the keys accidentally causing elements to
+be considered different when they should be treated the same (or vice versa).
+
+In particular, the compiler will not automatically insert `key` attributes if a
+component's `render` method has more than one `return` statement or if it
+returns a [conditional
+expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_operator).
+Additionally, the compiler will not add key attributes to any JSX which is
+found within curly braces (`{ }`).
+:::
+
+## Handling User Input
+
+Stencil uses native [DOM events](https://developer.mozilla.org/en-US/docs/Web/Events).
+
+Here's an example of handling a button click. Note the use of the [Arrow function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions).
+
+```tsx
+...
+export class MyComponent {
+ private handleClick = () => {
+ alert('Received the button click!');
+ }
+
+ render() {
+ return (
+
+ );
+ }
+}
+```
+
+Here's another example of listening to input `change`. Note the use of the [Arrow function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions).
+
+```tsx
+...
+export class MyComponent {
+ private inputChanged = (event: Event) => {
+ console.log('input changed: ', (event.target as HTMLInputElement).value);
+ }
+
+ render() {
+ return (
+
+ );
+ }
+}
+```
+
+
+## Complex Template Content
+
+So far we've seen examples of how to return only a single root element. We can also nest elements inside our root element
+
+In the case where a component has multiple "top level" elements, the `render` function can return an array.
+Note the comma in between the `no key!
}
+
+
+ ` elements.
+
+```tsx
+render() {
+ return ([
+ // first top level element
+
+ // first top level element
+ );
+}
+```
+
+It is also possible to use `innerHTML` to inline content straight into an element. This can be helpful when, for example, loading an svg dynamically and then wanting to render that inside of a `div`. This works just like it does in normal HTML:
+
+```markup
+
+```
+
+## Getting a reference to a DOM element
+
+In cases where you need to get a direct reference to an element, like you would normally do with `document.querySelector`, you might want to use a `ref` in JSX. Lets look at an example of using a `ref` in a form:
+
+```tsx
+@Component({
+ tag: 'app-home',
+})
+export class AppHome {
+
+ textInput!: HTMLInputElement;
+
+ handleSubmit = (event: Event) => {
+ event.preventDefault();
+ console.log(this.textInput.value);
+ }
+
+ render() {
+ return (
+
+ );
+ }
+}
+```
+
+In this example we are using `ref` to get a reference to our input `ref={(el) => this.textInput = el as HTMLInputElement}`. We can then use that ref to do things such as grab the value from the text input directly `this.textInput.value`.
+
+## Explicitly setting attributes or properties
+
+By default, Stencil tries to intelligently determine whether to set an attribute or (more commonly) a property on an element when using JSX.
+However, in some cases you may want to explicitly set one or the other. You can do this by using the `attr:` or `prop:` prefixes. For example:
+
+```tsx
+
+```
+
+will set the `value` attribute on the input element, while:
+
+```tsx
+
+```
+
+will explicitly set the `value` property on the input element.
+
+
+## Avoid Shared JSX Nodes
+
+The renderer caches element lookups in order to improve performance. However, a side effect from this is that the exact same JSX node should not be shared within the same renderer.
+
+In the example below, the `sharedNode` variable is reused multiple times within the `render()` function. The renderer is able to optimize its DOM element lookups by caching the reference, however, this causes issues when nodes are reused. Instead, it's recommended to always generate unique nodes like the changed example below.
+
+```diff
+@Component({
+ tag: 'my-cmp',
+})
+export class MyCmp {
+
+ render() {
+- const sharedNode = ` would be registered as ``.
+
+**Note:**
+- The `tagNameTransform` option in your Stencil config enables this feature at build time.
+- The `transformTagName` function is used at runtime when registering the components.
+
+### 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/).
+
+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:
+
+1. The Stencil library must expose lazy loadable components, such as those created with the
+ [`dist` output target](../output-targets/dist.md)
+2. The Stencil library must be recompiled with this flag set to `true`
+
+This flag works by creating dynamic import statements for every lazily loadable component in a Stencil project.
+Users of this flag should note that they may see an increase in their bundle size.
+
+Defaults to `false`.
+
+### 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/).
+
+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:
+
+1. The Stencil library must expose lazy loadable components, such as those created with the
+ [`dist` output target](../output-targets/dist.md)
+2. The Stencil library must be recompiled with this flag set to `true`
+
+This flag works by creating dynamic import statements for every lazily loadable component in a Stencil project.
+Users of this flag should note that they may see an increase in their bundle size.
+
+Defaults to `false`.
+
+### experimentalScopedSlotChanges
+
+This option updates runtime behavior for Stencil's support of slots in **scoped** components to match more closely with
+the native Shadow DOM behaviors.
+
+When set to `true`, the following behaviors will be applied:
+
+- 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)
+
+Defaults to `false`.
+
+:::note
+These behaviors only apply to components using scoped encapsulation!
+:::
+
+### experimentalSlotFixes
+
+This option enables all current and future slot-related fixes. When enabled it
+will enable the following options, overriding their values if they are
+specified separately:
+
+- [`slotChildNodesFix`](#slotchildnodesfix)
+- [`scopedSlotTextContentFix`](#scopedslottextcontentfix).
+- [`appendChildSlotFix`](#appendchildslotfix)
+- [`cloneNodeFix`](#clonenodefix)
+
+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)
+- 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)
+- Slot name is not updated when it is bind to a prop [(#2982)](https://github.com/ionic-team/stencil/issues/2982) (since 4.12.1)
+- Conditionally rendered slots not working [(#5335)](https://github.com/ionic-team/stencil/issues/5335) (since 4.13.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
+
+:::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 `
+
+
+
+
,
+
+ // second top level element, note the , above
+ -
+
- Item 1 +
- Item 2 +
- Item 3 +
+ ... more html content ...
+
+ ]);
+}
+```
+
+Alternatively you can use the `Fragment` functional component, in which case you won't need to add commas:
+
+```tsx
+import { Fragment } from '@stencil/core';
+...
+render() {
+ return (
+
+
+ -
+
- Item 1 +
- Item 2 +
- Item 3 +
+ ... more html content ...
+
+ Text
;
+ return (
+
+- {sharedNode}
+- {sharedNode}
++
+ );
+ }
+}
+```
+
+Alternatively, creating a factory function to return a common JSX node could be used instead since the returned value would be a unique instance. For example:
+
+```tsx
+@Component({
+ tag: 'my-cmp',
+})
+export class MyCmp {
+
+ getText() {
+ return Text
++ Text
+ Text
;
+ }
+
+ render() {
+ return (
+
+ {this.getText()}
+ {this.getText()}
+
+ );
+ }
+}
+```
+
+## Other Resources
+
+- [Understanding JSX for StencilJS Applications](https://www.joshmorony.com/understanding-jsx-for-stencil-js-applications/)
diff --git a/versioned_docs/version-v4.42/config/01-overview.md b/versioned_docs/version-v4.42/config/01-overview.md
new file mode 100644
index 000000000..dc96c76fe
--- /dev/null
+++ b/versioned_docs/version-v4.42/config/01-overview.md
@@ -0,0 +1,586 @@
+---
+title: Config
+sidebar_label: Overview
+description: Config
+slug: /config
+---
+
+# Stencil Config
+
+In most cases, the `stencil.config.ts` file does not require any customization since Stencil comes with great default values out-of-the-box. In general, it's preferred to keep the config as minimal as possible. In fact, you could even delete the `stencil.config.ts` file entirely and an app would compile just fine. But at the same time, the compiler can be configured at the lowest levels using this config. Below are the many *optional* config properties.
+
+Example `stencil.config.ts`:
+
+```tsx
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+ namespace: 'MyApp',
+ srcDir: 'src'
+};
+```
+
+## buildDist
+
+*default: true (prod), false (dev)*
+
+Sets whether or not Stencil will execute output targets and write output to
+`dist/` when `stencil build` is called. Defaults to `false` when building for
+development and `true` when building for production. If set to `true` then
+Stencil will always build all output targets, regardless of whether the build
+is in dev or prod mode or using watch mode.
+
+```tsx
+buildDist: true
+```
+
+## buildEs5
+
+Sets if the ES5 build should be generated or not.
+It defaults to `false`.
+Setting `buildEs5` to `true` will also create ES5 builds for both dev and prod modes.
+Setting `buildEs5` to `prod` will only build ES5 in prod mode.
+
+```tsx
+buildEs5: boolean | 'prod'
+```
+
+## bundles
+
+By default, Stencil will statically analyze the application and generate a component graph of how all the components are interconnected. From the component graph it is able to best decide how components should be grouped depending on their usage with one another within the app. By doing so it's able to bundle components together in order to reduce network requests. However, bundles can be manually generated using the `bundles` config.
+
+The `bundles` config is an array of objects that represent how components are grouped together in lazy-loaded bundles. This config is rarely needed as Stencil handles this automatically behind the scenes.
+
+```tsx
+bundles: [
+ { components: ['ion-button'] },
+ { components: ['ion-card', 'ion-card-header'] }
+]
+```
+
+## cacheDir
+
+*default: '.stencil'*
+
+The directory where sub-directories will be created for caching when [`enableCache`](#enablecache) is set `true` or if using
+[Stencil's Screenshot Connector](../testing/stencil-testrunner/07-screenshot-connector.md).
+
+A Stencil config like the following:
+
+```ts title='stencil.config.ts'
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+ ...,
+ enableCache: true,
+ cacheDir: '.cache',
+ testing: {
+ screenshotConnector: 'connector.js'
+ }
+}
+```
+
+Will result in the following file structure:
+
+```tree
+stencil-project-root
+└── .cache
+ ├── .build <-- Where build related file caching is written
+ |
+ └── screenshot-cache.json <-- Where screenshot caching is written
+```
+
+## devServer
+
+Please see the [Dev-Server docs](./dev-server.md).
+
+## docs
+
+Please see the [docs config](./docs.md).
+
+## enableCache
+
+*default: `true`*
+
+Stencil will cache build results in order to speed up rebuilds. To disable this feature, set `enableCache` to `false`.
+
+```tsx
+enableCache: true
+```
+
+## excludeComponents
+
+*default: `[]`*
+
+An array of component tag names to exclude from production builds.
+Useful to remove test, demo or experimental components from final output.
+
+Supports glob patterns for matching multiple components:
+- `['demo-*']` - Excludes all components starting with "demo-"
+- `['*-test', '*-demo']` - Excludes components ending with "-test" or "-demo"
+- `['my-component']` - Excludes a specific component
+
+Components matching these patterns will be completely excluded from all output targets when *not* using the `--dev` flag.
+
+## extras
+
+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.
+
+The global script runs once before your library/app loads, so you can do things like setting up a connection to an external service or configuring a library you are using.
+
+The code to be executed should be placed within a default function that is exported by the global script. Ensure all of the code in the global script is wrapped in the function that is exported:
+
+```javascript
+export default function() { // or export default async function()
+ initServerConnection();
+}
+```
+
+:::note
+The exported function can also be `async` but be aware that this can have implications on the performance of your application as all rendering operations will be deferred until after the global script finishes.
+:::
+
+Imported methods from Stencil, such as `setMode`, `BUILD` and others, can only be accessed within the function exported by the script. They will not be available in the global scope outside of this function.
+
+```javascript
+import { setMode, BUILD } from '@stencil/core';
+
+// ❌ This won't work as Stencil primitives are not initialized at this point
+// console.log('Build mode:', BUILD.isDev);
+
+export default function() {
+ // ✅ This works - Stencil methods are available within the exported function
+ if (BUILD.isDev) {
+ console.log('Development mode detected');
+ setMode((elm) => elm.getAttribute('mode') || 'dev');
+ } else {
+ console.log('Production mode');
+ setMode((elm) => elm.getAttribute('mode') || 'prod');
+ }
+}
+```
+
+## globalStyle
+
+Stencil is traditionally used to compile many components into an app, and each component comes with its own compartmentalized styles. However, it's still common to have styles which should be "global" across all components and the website. A global CSS file is often useful to set [CSS Variables](../components/styling.md).
+
+Additionally, the `globalStyle` config can be used to precompile styles with Sass, PostCSS, etc.
+
+Below is an example folder structure containing a webapp's global css file, named `app.css`.
+
+```bash
+src/
+ components/
+ global/
+ app.css
+```
+
+The global style config takes a file path as a string. The output from this build will go to the `buildDir`. In this example it would be saved to `www/build/app.css`. Additionally, these global styles are automatically applied to all components with shadow roots via constructable stylesheets, allowing you to style shadow DOM components directly.
+
+```tsx
+globalStyle: 'src/global/app.css'
+```
+
+Check out the [styling docs](../components/styling.md#global-styles) of how to use global styles in your app.
+
+## hashedFileNameLength
+
+*default: `8`*
+
+When the `hashFileNames` config is set to `true`, and it is a production build, the `hashedFileNameLength` config is used to determine how many characters the file name's hash should be.
+
+```tsx
+hashedFileNameLength: 8
+```
+
+## hashFileNames
+
+*default: `true`*
+
+During production builds, the content of each generated file is hashed to represent the content, and the hashed value is used as the filename. If the content isn't updated between builds, then it receives the same filename. When the content is updated, then the filename is different. By doing this, deployed apps can "forever-cache" the build directory and take full advantage of content delivery networks (CDNs) and heavily caching files for faster apps.
+
+```tsx
+hashFileNames: true
+```
+
+## hydratedFlag
+
+When using the [lazy build](https://stenciljs.com/docs/distribution) Stencil
+has support for automatically applying a class or attribute to a component and
+all of its child components when they have finished hydrating. This can be used
+to prevent a [flash of unstyled content
+(FOUC)](https://en.wikipedia.org/wiki/Flash_of_unstyled_content), a
+typically-undesired 'flicker' of unstyled HTML that might otherwise occur
+during component rendering while various components are asynchronously
+downloaded and rendered.
+
+By default, Stencil will add the `hydrated` CSS class to elements to indicate
+hydration. The `hydratedFlag` config field allows this behavior to be
+customized, by changing the name of the applied CSS class, setting it to use an
+attribute to indicate hydration, or changing which type of CSS properties and
+values are assigned before and after hydrating. This config can also be used to
+turn off this behavior by setting it to `null`.
+
+If a Stencil configuration does not supply a value for `hydratedFlag` then
+Stencil will automatically generate the following default configuration:
+
+```ts
+const defaultHydratedFlag: HydratedFlag = {
+ hydratedValue: 'inherit',
+ initialValue: 'hidden',
+ name: 'hydrated',
+ property: 'visibility',
+ selector: 'class',
+};
+```
+
+If `hydratedFlag` is explicitly set to `null`, Stencil will not set a default
+configuration and the behavior of marking hydration with a class or attribute
+will be disabled.
+
+```tsx
+hydratedFlag: null | {
+ name?: string,
+ selector?: 'class' | 'attribute',
+ property?: string,
+ initialValue?: string,
+ hydratedValue?: string
+}
+```
+
+The supported options are as follows:
+
+### name
+
+*default: 'hydrated'*
+
+The name which Stencil will use for the attribute or class that it sets on
+elements to indicate that they are hydrated.
+
+```tsx
+name: string
+```
+
+### selector
+
+*default: 'class'*
+
+The way that Stencil will indicate that a component has been hydrated. When
+`'class'`, Stencil will set the `name` option on the element as a class, and
+when `'attribute'`, Stencil will similarly set the `name` option as an
+attribute.
+
+```tsx
+selector: 'class' | 'attribute'
+```
+
+### property
+
+*default: 'visibility'*
+
+The CSS property used to show and hide components. This defaults to the CSS
+`visibility` property. Other possible CSS properties might include `display`
+with the `initialValue` setting as `none`, or `opacity` with the `initialValue`
+as `0`. Defaults to `visibility`.
+
+```tsx
+property: string
+```
+
+### initialValue
+
+*default: 'hidden'*
+
+This is the value which should be set for the property specified by `property`
+on all components before hydration.
+
+```tsx
+initialValue: string
+```
+
+### hydratedValue
+
+*default: 'inherit'*
+
+This is the value which should be set for the property specified by `property`
+on all components once they've completed hydration.
+
+```tsx
+hydratedValue: string
+```
+
+## invisiblePrehydration
+
+*default: `true`*
+
+When `true`, `invisiblePrehydration` will visually hide components before they are hydrated by adding an automatically injected style tag to the document's head. Setting `invisiblePrehydration` to `false` will not inject the style tag into the head, allowing you to style your web components pre-hydration.
+
+:::note
+Setting `invisiblePrehydration` to `false` will cause everything to be visible when your page is loaded, causing a more prominent Flash of Unstyled Content (FOUC). However, you can style your web component's fallback content to your preference.
+:::
+
+```tsx
+invisiblePrehydration: true
+```
+
+## minifyCss
+
+_default: `true` in production_
+
+When `true`, the browser CSS file will be minified.
+
+## minifyJs
+
+_default: `true` in production_
+
+When `true`, the browser JS files will be minified. Stencil uses [Terser](https://terser.org/) under-the-hood for file minification.
+
+## namespace
+
+*default: `App`*
+
+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, the default of `App` is just fine. However, if the app is meant to be consumed as a third-party library, such as `Ionic`, a unique namespace is required.
+
+```tsx
+namespace: "Ionic"
+```
+## outputTargets
+
+Please see the [Output Target docs](../output-targets/01-overview.md).
+
+## plugins
+
+Please see the [Plugin docs](./plugins.md).
+
+## preamble
+
+*default: `undefined`*
+
+Used to help to persist a banner or add relevant information about the resulting build, the `preamble` configuration
+field is a `string` that will be converted into a pinned comment and placed at the top of all emitted JavaScript files,
+with the exception of any emitted polyfills. Escaped newlines may be placed in the provided value for this field and
+will be honored by Stencil.
+
+Example:
+```tsx
+preamble: 'Built with Stencil\nCopyright (c) SomeCompanyInc.'
+```
+Will generate the following comment:
+```tsx
+/*!
+ * Built with Stencil
+ * Copyright (c) SomeCompanyInc.
+ */
+```
+
+## sourceMap
+
+*default: `'dev'`*
+
+- Set to `true` to always generate source maps,
+- Set to `false` to never generate source maps
+- Set to `'dev'` to only generate source maps during development (`--dev`) builds.
+
+```tsx
+sourceMap: true | false | 'dev'
+```
+
+Sourcemaps create a translation between Stencil components that are written in TypeScript/JSX and the resulting
+JavaScript that is output by Stencil. Enabling source maps in your project allows for an improved debugging experience
+for Stencil components. For example, they allow external tools (such as an Integrated Development Environment) to add
+breakpoints directly in the original source code, which allows you to 'step through' your code line-by-line, to inspect
+the values held in variables, to observe logic flow, and more.
+
+Please note: Stencil will always attempt to minify a component's source code as much as possible during compilation.
+When `sourceMap` is enabled, it is possible that a slightly different minified result will be produced by Stencil when
+compared to the minified result produced when `sourceMap` is not enabled.
+
+Developers are responsible for determining whether or not they choose to serve sourcemaps in each environment their
+components are served and implementing their decision accordingly.
+
+## srcDir
+
+*default: `src`*
+
+The `srcDir` config specifies the directory which should contain the source typescript files for each component. The standard for Stencil apps is to use `src`, which is the default.
+
+```tsx
+srcDir: 'src'
+```
+
+## taskQueue
+
+*default: `async`*
+
+Sets the task queue used by stencil's runtime. The task queue schedules DOM read and writes
+across the frames to efficiently render and reduce layout thrashing. By default, the
+`async` is used. It's recommended to also try each setting to decide which works
+best for your use-case. In all cases, if your app has many CPU intensive tasks causing the
+main thread to periodically lock-up, it's always recommended to try
+[Web Workers](../guides/workers.md) for those tasks.
+
+* `congestionAsync`: DOM reads and writes are scheduled in the next frame to prevent layout
+ thrashing. When the app is heavily tasked and the queue becomes congested it will then
+ split the work across multiple frames to prevent blocking the main thread. However, it can
+ also introduce unnecessary reflows in some cases, especially during startup. `congestionAsync`
+ is ideal for apps running animations while also simultaneously executing intensive tasks
+ which may lock-up the main thread.
+
+* `async`: DOM read and writes are scheduled in the next frame to prevent layout thrashing.
+ During intensive CPU tasks it will not reschedule rendering to happen in the next frame.
+ `async` is ideal for most apps, and if the app has many intensive tasks causing the main
+ thread to lock-up, it's recommended to try [Web Workers](../guides/workers.md)
+ rather than the congestion async queue.
+
+* `immediate`: Makes writeTask() and readTask() callbacks to be executed synchronously. Tasks
+ are not scheduled to run in the next frame, but do note there is at least one microtask.
+ The `immediate` setting is ideal for apps that do not provide long-running and smooth
+ animations. Like the async setting, if the app has intensive tasks causing the main thread
+ to lock-up, it's recommended to try [Web Workers](../guides/workers.md).
+
+```tsx
+taskQueue: 'async'
+```
+
+## testing
+
+Please see the [testing config docs](../testing/stencil-testrunner/02-config.md).
+
+## transformAliasedImportPaths
+
+*default: `true`*
+
+This sets whether or not Stencil should transform [path aliases](
+https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) set
+in a project's `tsconfig.json` from the assigned module aliases to resolved
+relative paths. This will not transform external imports (like `@stencil/core`) or
+relative imports (like `'../utils'`).
+
+This option applies globally and will affect all code processed by Stencil,
+including `.d.ts` files and spec tests.
+
+An example of path transformation could look something like the following.
+
+First, a set of `paths` aliases in `tsconfig.json`:
+
+```json title="tsconfig.json"
+{
+ "compilerOptions": {
+ "paths": {
+ "@utils": [
+ "../path/to/utils"
+ ]
+ }
+ }
+}
+```
+
+Then with the following input:
+
+```ts title="src/my-module.ts"
+import { utilFunc, UtilInterface } from '@utils'
+
+export function util(arg: UtilInterface) {
+ utilFunc(arg)
+}
+```
+
+Stencil will produce the following output:
+
+```js title="dist/my-module.js"
+import { utilFunc } from '../path/to/utils';
+export function util(arg) {
+ utilFunc(arg);
+}
+```
+
+```ts title="dist/my-module.d.ts"
+import { UtilInterface } from '../path/to/utils';
+export declare function util(arg: UtilInterface): void;
+```
+
+## validatePrimaryPackageOutputTarget
+
+*default: `false`*
+
+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"]
+ }
+}
+```
+
+:::
diff --git a/versioned_docs/version-v4.42/config/_category_.json b/versioned_docs/version-v4.42/config/_category_.json
new file mode 100644
index 000000000..b9de453d1
--- /dev/null
+++ b/versioned_docs/version-v4.42/config/_category_.json
@@ -0,0 +1,4 @@
+{
+ "label": "Config",
+ "position": 5
+}
diff --git a/versioned_docs/version-v4.42/config/cli.md b/versioned_docs/version-v4.42/config/cli.md
new file mode 100644
index 000000000..445c42996
--- /dev/null
+++ b/versioned_docs/version-v4.42/config/cli.md
@@ -0,0 +1,111 @@
+---
+title: Stencil CLI
+sidebar_label: CLI
+description: Stencil CLI
+slug: /cli
+---
+
+# Command Line Interface (CLI)
+
+Stencil's command line interface (CLI) is how developers can build their projects, run tests, and more.
+Stencil's CLI is included in the compiler, and can be invoked with the `stencil` command in a project where `@stencil/core` is installed.
+
+## `stencil build`
+
+Builds a Stencil project. The flags below are the available options for the `build` command.
+
+| Flag | Description | Alias |
+|------|-------------|-------|
+| `--ci` | Run a build using recommended settings for a Continuous Integration (CI) environment. Defaults the number of workers to 4, allows for extra time if taking screenshots via the tests and modifies the console logs. | |
+| `--config` | Path to the `stencil.config.ts` file. This flag is not needed in most cases since Stencil will find the config. Additionally, a Stencil config is not required. | `-c` |
+| `--debug` | Adds additional runtime code to help debug, and sets the log level for more verbose output. | |
+| `--dev` | Runs a development build. | |
+| `--docs` | Generate all docs based on the component types, properties, methods, events, JSDocs, CSS Custom Properties, etc. | |
+| `--es5` | Creates an ES5 compatible build. By default ES5 builds are not created during development in order to improve build times. However, ES5 builds are always created during production builds. Use this flag to create ES5 builds during development. | |
+| `--log` | Write logs for the `stencil build` into `stencil-build.log`. The log file is written in the same location as the config. | |
+| `--prerender` | Prerender the application using the `www` output target after the build has completed. | |
+| `--prod` | Runs a production build which will optimize each file, improve bundling, remove unused code, minify, etc. A production build is the default, this flag is only used to override the `--dev` flag. | |
+| `--max-workers` | Max number of workers the compiler should use. Defaults to use the same number of CPUs the Operating System has available. | |
+| `--next` | Opt-in to test the "next" Stencil compiler features. | |
+| `--no-cache` | Disables using the cache. | |
+| `--no-open` | By default the `--serve` command will open a browser window. Using the `--no-open` command will not automatically open a browser window. | |
+| `--port` | Port for the [Integrated Dev Server](./dev-server.md). Defaults to `3333`. | `-p` |
+| `--serve` | Starts the [Integrated Dev Server](./dev-server.md). | |
+| `--stats` | Write stats about the project to `stencil-stats.json`. The stats file is written in the same location as the config. | |
+| `--verbose` | Logs additional information about each step of the build. | |
+| `--watch` | Watches files during development and triggers a rebuild when files are updated. | |
+
+## `stencil docs`
+
+Performs a one-time generation of documentation for your project.
+For more information on documentation generation, please see the [Documentation Generation section](../documentation-generation/01-overview.md).
+
+:::info
+This command runs with dev mode enabled, which does not run a full build. As a result, documentation that needs to be built first, like CSS styles, will not be generated. You will need to run `npx stencil build --docs` to generate documentation that requires building.
+:::
+
+## `stencil generate`
+
+Alias: `stencil g`
+
+Starts the interactive generator for a new Stencil component.
+The generator will ask you for a name for your component, and whether any stylesheets or testing files should be generated.
+
+If you wish to skip the interactive generator, a component tag name may be provided on the command line:
+```shell
+stencil generate my-new-component
+```
+
+All components will be generated within the `src/components` folder.
+Within `src/components`, a directory will be created with the same name as the component tag name you provided containing the generated files.
+For example, if you specify `page-home` as the component tag name, the files will be generated in `src/components/page-home`:
+```plain
+src
+└── components
+ └── page-home
+ ├── page-home.css
+ ├── page-home.e2e.ts
+ ├── page-home.spec.ts
+ └── page-home.tsx
+```
+
+It is also possible to specify one or more sub-folders to generate the component in.
+For example, if you specify `pages/page-home` as the component tag name, the files will be generated in `src/components/pages/page-home`:
+```shell
+stencil generate pages/page-home
+```
+The command above will result in the following directory structure:
+```plain
+src
+└── components
+ └── pages
+ └── page-home
+ ├── page-home.css
+ ├── page-home.e2e.ts
+ ├── page-home.spec.ts
+ └── page-home.tsx
+```
+
+## `stencil help`
+
+Aliases: `stencil --help`, `stencil -h`
+
+Prints various tasks that can be run and their associated flags to the terminal.
+
+## `stencil test`
+
+Tests a Stencil project. The flags below are the available options for the `test` command.
+
+| Flag | Description |
+|------|-------------|
+| `--spec` | Tests `.spec.ts` files using [Jest](https://jestjs.io/). |
+| `--e2e` | Tests `.e2e.ts` files using [Puppeteer](https://developers.google.com/web/tools/puppeteer) and [Jest](https://jestjs.io/). |
+| `--no-build` | Skips the build process before running end-to-end tests. When using this flag, it is assumed that your Stencil project has been built prior to running `stencil test`. Unit tests do not require this flag. |
+| `--devtools` | Opens the dev tools panel in Chrome for end-to-end tests. Setting this flag will disable `--headless` |
+| `--headless` | Sets the headless mode to use in Chrome for end-to-end tests. `--headless` and `--headless=true` will enable the "old" headless mode in Chrome, that was used by default prior to Chrome v112. `--headless=new` will enable the new headless mode introduced in Chrome v112. See [this article](https://developer.chrome.com/articles/new-headless/) for more information on Chrome's new headless mode. |
+
+## `stencil version`
+
+Aliases: `stencil -v`, `stencil --version`
+
+Prints the version of Stencil to the terminal.
diff --git a/versioned_docs/version-v4.42/config/dev-server.md b/versioned_docs/version-v4.42/config/dev-server.md
new file mode 100644
index 000000000..705b32724
--- /dev/null
+++ b/versioned_docs/version-v4.42/config/dev-server.md
@@ -0,0 +1,162 @@
+---
+title: Integrated Dev Server Config
+sidebar_label: Dev Server
+description: Integrated Dev Server Config
+slug: /dev-server
+---
+
+# Integrated Dev Server
+
+Stencil comes with an integrated dev server in order to simplify development. By integrating the build process and the dev server, Stencil is able to drastically improve the development experience without requiring complicated build scripts and configuration. As app builds and re-builds take place, the compiler is able to communicate with the dev server, and vice versa.
+
+## Hot Module Replacement
+
+The compiler already provides a watch mode, but coupled with the dev server it's able to go one step farther by reloading only what has changed within the browser. Hot Module Replacement allows the app to keep its state within the browser, while switching out individual components with their updated logic after file saves.
+
+## Style Replacement
+
+Web components can come with their own css, can use shadow dom, and can have individual style tags. Traditionally, live-reload external css links usually does the trick, however, updating components with inline styles within shadow roots has been a challenge. With the integrated dev server, Stencil is able to dynamically update styles for all components, whether they're using shadow dom or not, without requiring a page refresh.
+
+## Development Errors
+
+When errors happen during development, such as printing an error for invalid syntax, Stencil will not only log the error and the source of the error in the console, but also overlay the app with the error so it's easier to read.
+
+## Open In Editor
+
+When a development error is shown and overlays the project within the browser, line numbers pointing to the source text are clickable,
+which will open the source file directly in your IDE.
+
+## Dev Server Config
+
+### `address`
+
+**Optional**
+
+**Type: `string`**
+
+**Default: `0.0.0.0`**
+
+IP address used by the dev server. The default is `0.0.0.0`, which points to all IPv4 addresses on the local machine, such as `localhost`.
+
+### `basePath`
+
+**Optional**
+
+**Type: `string`**
+
+**Default: `/`**
+
+Base path to be used by the server. Defaults to the root pathname.
+
+### `https`
+
+**Optional**
+
+**Type: `{ key: string; cert: string; } | false`**
+
+**Default: `false`**
+
+By default the dev server runs over the http protocol. Instead you can run it over https by providing your own SSL certificate and key (see example below).
+
+#### Example
+
+```tsx
+import { readFileSync } from 'fs';
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+ devServer: {
+ reloadStrategy: 'pageReload',
+ port: 4444,
+ https: {
+ cert: readFileSync('cert.pem', 'utf8'),
+ key: readFileSync('key.pem', 'utf8'),
+ },
+ },
+};
+```
+
+### `initialLoadUrl`
+
+**Optional**
+
+**Type: `string`**
+
+**Default: `/`**
+
+The URL the dev server should first open to.
+
+### `logRequests`
+
+**Optional**
+
+**Type: `boolean`**
+
+**Default: `false`**
+
+Every request to the server will be logged within the terminal.
+
+### `openBrowser`
+
+**Optional**
+
+**Type: `boolean`**
+
+**Default: `true`**
+
+By default, when dev server is started the local dev URL is opened in your default browser. However, to prevent this URL to be opened change this value to `false`.
+
+### `pingRoute`
+
+**Optional**
+
+**Type: `string | null`**
+
+**Default: `/ping`**
+
+Route to be registered on the dev server that will respond with a 200 OK response once the Stencil build has completed. The Stencil dev server will "spin up"
+before the build process has completed, which can cause issues with processes that rely on the compiled and served output (like E2E testing). This route provides
+a way for these processes to know when the build has finished and is ready to be accessed.
+
+If set to `null`, no route will be registered.
+
+### `port`
+
+**Optional**
+
+**Type: `number`**
+
+**Default: `3333`**
+
+Sets the server's port.
+
+### `strictPort`
+
+**Optional**
+
+**Type: `boolean`**
+
+**Default: `false`**
+
+When set to `true`, the dev server will fail to start if the specified `port` is already in use. When set to `false`, the dev server will try the next available port if the specified port is in use.
+
+### `reloadStrategy`
+
+**Optional**
+
+**Type: `'hmr' | 'pageReload' | null`**
+
+**Default: `hmr`**
+
+When files are watched and updated, by default the dev server will use `hmr` (Hot Module Replacement) to update the page without a full page refresh.
+To have the page do a full refresh use `pageReload`. To disable any reloading, use `null`.
+
+### `root`
+
+**Optional**
+
+**Type: `string`**
+
+**Default: `www` output directory if exists, project root otherwise**
+
+The directory to serve files from.
diff --git a/versioned_docs/version-v4.42/config/docs.md b/versioned_docs/version-v4.42/config/docs.md
new file mode 100644
index 000000000..2ceb4458c
--- /dev/null
+++ b/versioned_docs/version-v4.42/config/docs.md
@@ -0,0 +1,44 @@
+---
+title: Documentation Generation Config
+sidebar_label: Docs Config
+description: Documentation Generation Config
+slug: /docs-config
+---
+
+# Docs Config
+
+The `docs` config option allows global configuration of certain behaviors related to [documentation generation output targets](../documentation-generation/01-overview.md).
+
+:::note
+These configurations are **global** and will be applied to all output target instances including those defined in the [`outputTargets`](../output-targets/01-overview.md)
+configuration, as well as those injected by CLI flags (like `--docs`).
+:::
+
+## markdown
+
+The `markdown` config object allows certain customizations for markdown files generated by the [`docs-readme` output target](../documentation-generation/docs-readme.md) or the
+`--docs` CLI flag.
+
+### targetComponent
+
+**Optional**
+
+**Default: `{ textColor: '#333', background: '#f9f' }`**
+
+This option allows you to change the colors used when generating the dependency graph mermaid diagrams for components. Any hex color string is a valid
+value.
+
+```tsx title="stencil.config.ts"
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+ docs: {
+ markdown: {
+ targetComponent: {
+ textColor: '#fff',
+ background: '#000',
+ },
+ },
+ },
+};
+```
diff --git a/versioned_docs/version-v4.42/config/extras.md b/versioned_docs/version-v4.42/config/extras.md
new file mode 100644
index 000000000..70085fc9e
--- /dev/null
+++ b/versioned_docs/version-v4.42/config/extras.md
@@ -0,0 +1,188 @@
+---
+title: Extras Config
+sidebar_label: Extras
+description: Extras Config
+slug: /config-extras
+---
+
+# Extras
+
+The `extras` config contains options to enable new/experimental features in
+Stencil, add & remove runtime for DOM features that require manipulations to
+polyfills, etc. For example, not all DOM APIs are fully polyfilled when using
+the Slot polyfill. Most of these are opt-in, since not all users require the
+additional runtime.
+
+### appendChildSlotFix
+
+By default, the slot polyfill does not update `appendChild()` so that it appends new child nodes into the correct child slot like how shadow dom works. This is an opt-in polyfill for those who need it.
+
+### cloneNodeFix
+
+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.
+
+### tagNameTransform
+
+The `tagNameTransform` option in the `extras` config enables support for customizing the tag names of your Stencil components at runtime. This is especially useful if you want to add a prefix, suffix, or otherwise modify the tag names when registering your custom elements, for example to avoid naming conflicts.
+
+When `tagNameTransform` is enabled in your `stencil.config.ts`:
+
+```typescript
+extras: {
+ tagNameTransform: true
+}
+```
+
+You can use the `transformTagName` function when calling `defineCustomElements` in your consuming project:
+
+```typescript
+import { defineCustomElements } from 'my-button/loader';
+
+defineCustomElements(window, {
+ transformTagName: (tagName: string) => `${tagName}`
+} as never);
+```
+
+In this example, the function simply returns the original tag name, but you can customize it as needed. For example, to add a suffix:
+
+```typescript
+defineCustomElements(window, {
+ transformTagName: (tagName: string) => `${tagName}-v1`
+} as never);
+```
+
+With this configuration, a component originally named `