feat: new docs for 4.42

Author: johnjenkins

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

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) 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/templating-and-jsx.md

@@ -468,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/documentation-generation/docs-custom-elements-manifest.md

@@ -0,0 +1,204 @@
+---
+title: Docs Custom Elements Manifest Output Target
+sidebar_label: CEM (docs-custom-elements-manifest)
+description: Custom Elements Manifest
+slug: /docs-custom-elements-manifest
+---
+
+# Generating Documentation in Custom Elements Manifest (CEM) format
+
+Since Stencil v4.42, Stencil supports automatically generating a [Custom Elements Manifest (CEM)](https://custom-elements-manifest.open-wc.org/)
+file in your project. The CEM format is a standardized JSON format for describing
+custom elements and is supported by a variety of tools in the web components ecosystem.
+
+
+```tsx title="stencil.config.ts"
+import { Config } from '@stencil/core';
+
+export const config: Config = {
+  outputTargets: [
+    {
+      type: 'docs-custom-elements-manifest',
+      file: 'path/to/cem.json'
+    }
+  ]
+};
+```
+
+The JSON file output by Stencil conforms to the [CEM Schema interface](https://github.com/webcomponents/custom-elements-manifest/blob/main/schema.d.ts).
+
+## Properties, Methods, Events, and Attributes
+
+The CEM output target includes information about your components' properties,
+methods, events, and attributes based on the decorators you use in your Stencil
+components.
+
+## CSS Properties
+
+Stencil can document CSS variables if you annotate them with JSDoc-style
+comments in your CSS/SCSS files. If, for instance, you had a component with a
+CSS file like the following:
+
+```css title="src/components/my-button/my-button.css"
+:host {
+  /**
+   * @prop --background: Background of the button
+   * @prop --background-activated: Background of the button when activated
+   * @prop --background-focused: Background of the button when focused
+   */
+  --background: pink;
+  --background-activated: aqua;
+  --background-focused: fuchsia;
+}
+```
+
+Then you'd get the following in the JSON output:
+
+```json title="Example docs-custom-elements-manifest Output"
+[
+  {
+    "cssProperties": [
+      {
+        "name": "background",
+        "description": "Background of the button"
+      },
+      {
+        "name": "background-activated",
+        "description": "Background of the button when activated"
+      },
+      {
+        "name": "background-focused",
+        "description": "Background of the button when focused"
+      }
+    ]
+  }
+]   
+```
+
+## Slots
+
+If one of your Stencil components makes use of
+[slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) for
+rendering children you can document them by using the `@slot` JSDoc tag in the
+component's comment.
+
+For instance, if you had a `my-button` component with a slot you might document
+it like so:
+
+```tsx title="src/components/my-button/my-button.tsx"
+import { Component, h } from '@stencil/core';
+
+/**
+ * @slot buttonContent - Slot for the content of the button
+ */
+@Component({
+  tag: 'my-button',
+  styleUrl: 'my-button.css',
+  shadow: true,
+})
+export class MyButton {
+  render() {
+    return <button><slot name="buttonContent"></slot></button>
+  }
+}
+```
+
+This would show up in the generated JSON file like so:
+
+```json
+"slots": [
+  {
+    "name": "buttonContent",
+    "description": "Slot for the content of the button"
+  }
+]
+```
+
+:::caution
+Stencil does not check that the slots you document in a component's JSDoc
+comment using the `@slot` tag are actually present in the JSX returned by the
+component's `render` function.
+
+It is up to you as the component author to ensure the `@slot` tags on a
+component are kept up to date.
+:::
+
+## Custom States
+
+You can document [Custom States](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet) for your components using the `@AttachInternals` decorator
+and JSDoc comments. 
+
+For example:
+
+```tsx title="src/components/my-element/my-element.tsx"
+import { Component, h, AttachInternals } from '@stencil/core';
+/**
+ * My Element component
+ */
+@Component({
+  tag: 'my-element',
+  styleUrl: 'my-element.css',
+  shadow: true,
+})
+export class MyElement {
+  @AttachInternals({
+    states: {
+      new: true, 
+      /** If this item is older than 6 months old. Use via `:state(archived)` */
+      archived: false
+  },
+  }) internals!: ElementInternals;
+```
+
+This would show up in the generated JSON file like so:
+
+```json
+"customStates": [
+  {
+    "name": "new",
+    "description": ""
+  },
+  {    
+    "name": "archived",
+    "description": "If this item is older than 6 months old. Use via `:state(archived)"
+  }
+]
+```
+
+## Demos
+
+You can save demos for a component in the `usage/` subdirectory within
+that component's directory. The content of these files will be added to the
+`demos` property of the generated JSON. This allows you to keep examples right
+next to the code, making it easy to include them in a documentation site or
+other downstream consumer(s) of your docs.
+
+:::caution
+Stencil doesn't check that your demos are up-to-date! If you make any
+changes to your component's API you'll need to remember to update your demos
+manually.
+:::
+
+If, for instance, you had a usage example like this:
+
+````md title="src/components/my-button/usage/my-button-usage.md"
+# How to use `my-button`
+
+A button is often a great help in adding interactivity to an app!
+
+You could use it like this:
+
+```html
+<my-button>My Button!</my-button>
+```
+````
+
+
+You'd get the following in the JSON output under the `"usage"` key:
+
+```json
+"demos": [{
+  "url": "my-button-usage.md",
+  "description": "# How to use `my-button`\n\nA button is often a great help in adding interactivity to an app!\n\nYou could use it like this:\n\n```html\n<my-button>My Button!</my-button>\n```\n"
+}]
+```

docs/documentation-generation/docs-json.md

@@ -101,7 +101,7 @@ CSS file like the following:
 Then you'd get the following in the JSON output:
 
 ```json title="Example docs-json Output"
-[
+"styles": [
   {
     "name": "--background",
     "annotation": "prop",
@@ -184,10 +184,12 @@ export class MyButton {
 This would show up in the generated JSON file like so:
 
 ```json
-"slots": {
-  "name": "buttonContent",
-  "docs": "Slot for the content of the button"
-}
+"slots": [
+  {
+    "name": "buttonContent",
+    "description": "Slot for the content of the button"
+  }
+]
 ```
 
 :::caution
@@ -199,6 +201,49 @@ It is up to you as the component author to ensure the `@slot` tags on a
 component are kept up to date.
 :::
 
+## Custom States
+
+You can document [Custom States](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet) for your components using the `@AttachInternals` decorator
+and JSDoc comments. 
+
+For example:
+
+```tsx title="src/components/my-element/my-element.tsx"
+import { Component, h, AttachInternals } from '@stencil/core';
+/**
+ * My Element component
+ */
+@Component({
+  tag: 'my-element',
+  styleUrl: 'my-element.css',
+  shadow: true,
+})
+export class MyElement {
+  @AttachInternals({
+    states: {
+      new: true, 
+      /** If this item is older than 6 months old. Use via `:state(archived)` */
+      archived: false
+  },
+  }) internals!: ElementInternals;
+```
+
+This would show up in the generated JSON file like so:
+
+```json
+"states": [
+  {
+    "name": "new",
+    "initialValue": true,
+    "description": ""
+  },
+  {    
+    "name": "archived",
+    "initialValue": false,
+    "description": "If this item is older than 6 months old. Use via `:state(archived)"
+  }
+]
+```
 
 ## Usage