Merge branch 'main' into dependabot/npm_and_yarn/multi-c8afcbbcd8

Author: johnjenkins

cspell-wordlist.txt

@@ -41,4 +41,5 @@ usingtheplatform
 vnode
 webapps
 wdio
-webdriverio
+webdriverio
+hyperscript

docs/components/api.md

@@ -25,6 +25,7 @@ Once all the metadata has been collected, all the decorators are removed from th
 - [@Listen()](./events.md#listen-decorator) listens for DOM events
 - [@AttrDeserialize()](./serialization-deserialization.md#the-attrdeserialize-decorator-attrdeserialize) declares a hook to translate a component's attribute string to its JS property
 - [@PropSerialize()](./serialization-deserialization.md#the-propserialize-decorator-propserialize) declares a hook that translates a component's JS property to its attribute string
+- [@AttachInternals()](./attach-internals.md) attaches ElementInternals to a component
 
 
 ## Lifecycle hooks
@@ -119,9 +120,11 @@ The following primitives can be imported from the `@stencil/core` package and us
 
 ### [**h()**](./templating-and-jsx.md): 
 
-It's used within the `render()` to turn the JSX into Virtual DOM elements.
+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.
+### **render()**: 
+
+A utility method to render a virtual DOM created by `h()` into a container.
 
   __Type:__ `(vnode: VNode, container: Element) => void`
   __Example:__
@@ -290,7 +293,7 @@ Compose multiple classes into a single constructor using factory functions.
   @Component({
     tag: 'its-mixing-time',
   })
-  export class X extends Mixin(aFactory, aFactory, cFactory) {
+  export class X extends Mixin(aFactory, bFactory, cFactory) {
     render() {
       return <div>{this.propA} {this.propB} {this.propC}</div>
     }
@@ -302,7 +305,8 @@ If your Stencil component library uses `Mixin()` (or `extends`) and *might* be u
 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 **tagTransform()**](../guides/tag-transformation.md): 
+### [**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.

docs/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 <div>My Element</div>;
+  }
+}
+``` 
+
+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;
+} 
+```

docs/components/component.md

@@ -394,3 +394,7 @@ export class MyParentComponent {
 ```
 
 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.

docs/components/templating-and-jsx.md

@@ -11,7 +11,59 @@ Stencil components are rendered using JSX, a popular, declarative template synta
 
 ## Basics
 
-The `render` function is used to output a tree of components that will be drawn to the screen.
+### The `h` and `Fragment` functions
+
+The `h` function (short for "hyperscript") is a factory function that creates virtual DOM elements. When you write JSX like `<div>Hello</div>`, 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 {
@@ -416,6 +468,23 @@ export class AppHome {
 
 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
+<input attr:value="Hello" />
+```
+
+will set the `value` attribute on the input element, while:
+
+```tsx
+<input prop:value="Hello" />
+```
+
+will explicitly set the `value` property on the input element.  
+
 
 ## Avoid Shared JSX Nodes
 

docs/config/dev-server.md

@@ -130,6 +130,16 @@ If set to `null`, no route will be registered.
 
 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**

docs/config/extras.md

@@ -184,5 +184,5 @@ You can turn this behavior off by setting this flag to `false`.
 
 ### additionalTagTransformers
 
-Auto-apply `tagTransform` to most static tag names within your component library (including CSS selectors).
+Auto-apply `transformTag` to most static tag names within your component library (including CSS selectors).
 Refer to the [Tag Transformation](../guides/tag-transformation.md) page for more information.

docs/documentation-generation/01-overview.md

@@ -9,6 +9,7 @@ slug: /doc-generation
 
 - [`docs-readme`: Documentation readme files formatted in markdown](./docs-readme.md)
 - [`docs-json`: Documentation data formatted in JSON](./docs-json.md)
+- [`docs-custom-elements-manifest`: Custom Elements Manifest (CEM) format](./docs-custom-elements-manifest.md)
 - [`docs-custom`: Custom documentation generation](./docs-custom.md)
 - [`docs-vscode`: Documentation generation for VS Code](./docs-vscode.md)
 - [`stats`: Stats about the compiled files](./docs-stats.md)