Merge branch 'main' into docs/slot-polyfill-limitations

.github/workflows/check-markdown.yml

@@ -12,7 +12,7 @@ jobs:
     - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
     - name: Use Node from Volta
-      uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+      uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
       with:
         node-version-file: 'package.json'
         cache: 'npm'
@@ -29,7 +29,7 @@ jobs:
     - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
 
     - name: Use Node from Volta
-      uses: actions/setup-node@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+      uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
       with:
         node-version-file: 'package.json'
         cache: 'npm'

docs/components/form-associated.md

@@ -56,8 +56,7 @@ named
 method on `HTMLElement` to associate your Stencil component with an ancestor
 `<form>` element. During compilation, Stencil will generate code that calls
 this method at an appropriate point in the component lifecycle for both
-[lazy](../output-targets/dist.md) and [custom
-elements](../output-targets/custom-elements.md) builds.
+[lazy](../output-targets/dist.md) and [custom elements](../output-targets/custom-elements.md) builds.
 :::
 
 A Stencil component using this API to implement a custom text input could look
@@ -296,5 +295,4 @@ subject](https://web.dev/articles/more-capable-form-controls#restoring-form-stat
 - [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)
 
-[^1]: See <https://caniuse.com/?search=attachInternals> for up-to-date adoption
-    estimates.
+[^1]: See https://caniuse.com/?search=attachInternals for up-to-date adoption estimates.

docs/framework-integration/angular.md

@@ -5,6 +5,9 @@ description: Learn how to wrap your components so that people can use them nativ
 slug: /angular
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Angular Integration
 
 **Supports: Angular 12+ • TypeScript 4.0+ • Stencil v2.9.0+**
@@ -185,9 +188,7 @@ If the build is successful, you will now have contents in the file specified in
 
 You can now finally import and export the generated component wrappers for your component library. For example, in your library's main Angular module:
 
-```ts
-// component-library.module.ts
-
+```ts title="component-library.module.ts"
 import { DIRECTIVES } from './stencil-generated';
 
 @NgModule({
@@ -201,9 +202,7 @@ Any components that are included in the `exports` array should additionally be e
 `index.ts`). Skipping this step will lead to Angular Ivy errors when building for production. For this guide, simply add the following line to the
 automatically generated `public-api.ts` file:
 
-```ts
-// public-api.ts
-
+```ts title="public-api.ts"
 export * from './lib/component-library.module';
 export { DIRECTIVES } from './lib/stencil-generated';
 export * from './lib/stencil-generated/components';
@@ -214,9 +213,7 @@ export * from './lib/stencil-generated/components';
 The default behavior for this output target does not handle automatically defining/registering the custom elements. One strategy (and the approach
 the [Ionic Framework](https://github.com/ionic-team/ionic-framework/blob/main/packages/angular/src/app-initialize.ts#L21-L34) takes) is to use the loader to define all custom elements during app initialization:
 
-```ts
-// component-library.module.ts
-
+```ts title="component-library.module.ts"
 import { APP_INITIALIZER, NgModule } from '@angular/core';
 import { defineCustomElements } from 'stencil-library/loader';
 
@@ -270,21 +267,25 @@ however, will modify your `package.json` so it is important to make sure you do
 
 ## Consumer Usage
 
-### Creating a Consumer Angular App
-
 :::note
+
 If you already have an Angular app, skip this section.
+
 :::
 
-From your Angular workspace (`/packages/angular-workspace`), run the following command to generate an Angular application:
+### Angular with Modules
+
+#### Creating a Consumer Angular App
+
+From your Angular workspace (`/packages/angular-workspace`), run the following command to generate an Angular application with modules:
 
 ```bash
-npx -p @angular/cli ng generate app my-app
+npx -p @angular/cli ng generate app my-app --standalone=false
 ```
 
-### Consuming the Angular Wrapper Components
+#### Consuming the Angular Wrapper Components
 
-This section covers how developers consuming your Angular component wrappers will use your package and component wrappers.
+This section covers how developers consuming your Angular component wrappers will use your package and component wrappers in an Angular project using modules.
 
 In order to use the generated component wrappers in the Angular app, you'll first need to build your Angular component library. From the root
 of your Angular workspace (`/packages/angular-workspace`), run the following command:
@@ -293,12 +294,20 @@ of your Angular workspace (`/packages/angular-workspace`), run the following com
 npx -p @angular/cli ng build component-library
 ```
 
-Now you can reference your component library as a standard import. If you distributed your components through a primary `NgModule`, you can
-simply import that module into an implementation to use your components.
+<Tabs
+  groupId="outputType"
+  defaultValue="component"
+  values={[
+    { label: 'outputType: "component"', value: 'component' },
+    { label: 'outputType: "scam"', value: 'scam' },
+    { label: 'outputType: "standalone"', value: 'standalone' },
+  ]
+}>
+<TabItem value="component">
 
-```ts
-// app.module.ts
+Import your component library into your Angular app's module. If you distributed your components through a primary `NgModule`, you can simply import that module into an implementation to use your components.
 
+```ts title="app.module.ts"
 import { ComponentLibraryModule } from 'component-library';
 
 @NgModule({
@@ -307,17 +316,187 @@ import { ComponentLibraryModule } from 'component-library';
 export class AppModule {}
 ```
 
+Otherwise you will need to add the components to your module's `declarations` and `exports` arrays.
+
+```ts title="app.module.ts"
+import { MyComponent } from 'component-library';
+
+@NgModule({
+  declarations: [MyComponent],
+  exports: [MyComponent],
+})
+export class AppModule {}
+```
+
+You can now directly leverage your components in their template and take advantage of Angular template binding syntax.
+
+```html title="app.component.html"
+<my-component first="Your" last="Name"></my-component>
+```
+
+</TabItem>
+
+<TabItem value="scam">
+
+Now you can reference your component library as a standard import. Each component will be exported as a separate module.
+
+```ts title="app.module.ts"
+import { MyComponentModule } from 'component-library';
+
+@NgModule({
+  imports: [MyComponentModule],
+})
+export class AppModule {}
+```
+
 You can now directly leverage your components in their template and take advantage of Angular template binding syntax.
 
-```html
-<!-- app.component.html -->
+```html title="app.component.html"
+<my-component first="Your" last="Name"></my-component>
+```
+
+</TabItem>
+
+<TabItem value="standalone">
+
+Now you can import and reference your components in your consuming application in the same way you would with any other Angular components:
+
+```ts title="app.component.ts"
+import { Component } from '@angular/core';
+import { MyComponent } from 'component-library';
 
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+  styleUrls: ['./app.component.css'],
+  standalone: true,
+  imports: [MyComponent],
+})
+export class AppComponent {}
+```
+
+You can now leverage your components in the template and take advantage of Angular template binding syntax.
+
+```html title="app.component.html"
 <my-component first="Your" last="Name"></my-component>
 ```
 
+</TabItem>
+
+</Tabs>
+
 From your Angular workspace (`/packages/angular-workspace`), run `npm start` and navigate to `localhost:4200`. You should see the
 component rendered correctly.
 
+### Angular with Standalone Components
+
+In Angular CLI v17, the default behavior is to generate a new project with standalone components.
+
+From your Angular workspace (`/packages/angular-workspace`), run the following command to generate an Angular application:
+
+```bash
+npx -p @angular/cli ng generate app my-app
+```
+
+#### Consuming the Angular Wrapper Components
+
+This section covers how developers consuming your Angular component wrappers will use your package and component wrappers.
+
+In order to use the generated component wrappers in the Angular app, you'll first need to build your Angular component library. From the root
+of your Angular workspace (`/packages/angular-workspace`), run the following command:
+
+```bash
+npx -p @angular/cli ng build component-library
+```
+
+<Tabs
+  groupId="outputType"
+  defaultValue="component"
+  values={[
+    { label: 'outputType: "component"', value: 'component' },
+    { label: 'outputType: "scam"', value: 'scam' },
+    { label: 'outputType: "standalone"', value: 'standalone' },
+  ]
+}>
+<TabItem value="component">
+
+Import your component library into your component. You must distribute your components through a primary `NgModule` to use your components in a standalone component.
+
+```ts title="app.component.ts"
+import { Component } from '@angular/core';
+import { ComponentLibraryModule } from 'component-library';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [ComponentLibraryModule],
+  templateUrl: './app.component.html',
+})
+export class AppComponent {}
+```
+
+You can now directly leverage your components in their template and take advantage of Angular template binding syntax.
+
+```html title="app.component.html"
+<my-component first="Your" last="Name"></my-component>
+```
+
+</TabItem>
+
+<TabItem value="scam">
+
+Now you can reference your component library as a standard import. Each component will be exported as a separate module.
+
+```ts title="app.module.ts"
+import { Component } from '@angular/core';
+import { MyComponentModule } from 'component-library';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [MyComponentModule],
+  templateUrl: './app.component.html',
+})
+export class AppComponent {}
+```
+
+You can now directly leverage your components in their template and take advantage of Angular template binding syntax.
+
+```html title="app.component.html"
+<my-component first="Your" last="Name"></my-component>
+```
+
+</TabItem>
+
+<TabItem value="standalone">
+
+Now you can import and reference your components in your consuming application in the same way you would with any other standalone Angular components:
+
+```ts title="app.component.ts"
+import { Component } from '@angular/core';
+import { MyComponent } from 'component-library';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [MyComponent],
+  templateUrl: './app.component.html',
+})
+export class AppComponent {}
+```
+
+You can now leverage your components in the template and take advantage of Angular template binding syntax.
+
+```html title="app.component.html"
+<my-component first="Your" last="Name"></my-component>
+```
+
+</TabItem>
+
+</Tabs>
+
+From your Angular workspace (`/packages/angular-workspace`), run `npm start` and navigate to `localhost:4200`. You should see the component rendered correctly.
+
 ## API
 
 ### componentCorePackage
@@ -337,9 +516,7 @@ npm init stencil component my-component-lib
 
 The `componentCorePackage` would be set to:
 
-```ts
-// stencil.config.ts
-
+```ts title="stencil.config.ts"
 export const config: Config = {
   ...,
   outputTargets: [
@@ -430,7 +607,7 @@ Note: Please choose the appropriate `outputType` based on your project's require
 This lets you define which components should be integrated with `ngModel` (i.e. form components). It lets you set what the target prop is (i.e. `value`),
 which event will cause the target prop to change, and more.
 
-```tsx
+```tsx title="stencil.config.ts"
 const angularValueAccessorBindings: ValueAccessorConfig[] = [
   {
     elementSelectors: ['my-input[type=text]'],
@@ -464,9 +641,7 @@ No! By default, this output target will look to use the `dist` output, but the o
 
 To do so, change the type `outputType` argument to either `scam` or `standalone`. For more information on both these options, see the [API section](#outputtype).
 
-```ts
-// stencil.config.ts
-
+```ts title="stencil.config.ts"
 export const config: Config = {
   ...,
   outputTargets: [
@@ -492,9 +667,7 @@ In addition, all the Web Component will be automatically defined as the generate
 the Stencil loader for lazy-loading the custom elements (i.e. you can remove the `APP_INITIALIZER` logic introduced [in this section](#adding-the-angular-output-target)).
 As such, the generated Angular components can now be directly imported and declared on any Angular module implementing them:
 
-```ts
-// app.module.ts
-
+```ts title="app.module.ts"
 import { MyComponent } from 'component-library';
 
 @NgModule({

docs/guides/forms.md

@@ -88,8 +88,7 @@ export class MyName {
 }
 ```
 
-For more check out the docs for [form-association in
-Stencil](../components/form-associated.md).
+For more check out the docs for [form-association in Stencil](../components/form-associated.md).
 
 ## Advanced forms
 

docs/introduction/upgrading-to-stencil-four.md

@@ -165,8 +165,7 @@ For Stencil v4 the information included in the output of the `docs-json` output
 target was expanded to include more information about the types of properties
 and methods on Stencil components.
 
-For more context on this change, see the [documentation for the new
-`supplementalPublicTypes`](../documentation-generation/docs-json.md#supplementalpublictypes)
+For more context on this change, see the [documentation for the new `supplementalPublicTypes`](../documentation-generation/docs-json.md#supplementalpublictypes)
 option for the JSON documentation output target.
 
 ### `JsonDocsEvent`

docs/reference/support-policy.md

@@ -25,7 +25,7 @@ The current status of each Stencil version is:
 | Version |      Status      |   Released   | Maintenance Ends | Ext. Support Ends |
 |:-------:|:----------------:|:------------:|:----------------:|:-----------------:|
 |   V4    |    **Active**    | Jun 26, 2023 |       TBD        |        TBD        |
-|   V3    |    Maintenance   | Jan 25, 2023 |   Dec 26, 2023   |   Jun 26, 2024    |
+|   V3    | Extended Support | Jan 25, 2023 |   Dec 26, 2023   |   Jun 26, 2024    |
 |   V2    | Extended Support | Aug 08, 2020 |   Jul 25, 2023   |   Jan 25, 2024    |
 |   V1    |  End of Support  | Jun 03, 2019 |   Aug 08, 2020   |   Aug 08, 2020    |