docs(stencil): add stencil usage to components (#21261)

core/src/components/modal/readme.md

@@ -340,6 +340,155 @@ In most scenarios, setting a ref on `IonPage` and passing that ref's `current` v
 ```
 
 
+### Stencil
+
+```tsx
+import { Component, h } from '@stencil/core';
+
+import { modalController } from '@ionic/core';
+
+@Component({
+  tag: 'modal-example',
+  styleUrl: 'modal-example.css'
+})
+export class ModalExample {
+  async presentModal() {
+    const modal = await modalController.create({
+      component: 'page-modal'
+    });
+    await modal.present();
+  }
+}
+```
+
+```tsx
+import { Component, h } from '@stencil/core';
+
+@Component({
+  tag: 'page-modal',
+  styleUrl: 'page-modal.css',
+})
+export class PageModal {
+  render() {
+    return [
+      <ion-list>
+        <ion-item>
+          <ion-label>Documentation</ion-label>
+        </ion-item>
+        <ion-item>
+          <ion-label>Feedback</ion-label>
+        </ion-item>
+        <ion-item>
+          <ion-label>Settings</ion-label>
+        </ion-item>
+      </ion-list>
+    ];
+  }
+}
+```
+
+### Passing Data
+
+During creation of a modal, data can be passed in through the `componentProps`.
+The previous example can be written to include data:
+
+```tsx
+async presentModal() {
+  const modal = await modalController.create({
+    component: 'page-modal',
+    componentProps: {
+      'firstName': 'Douglas',
+      'lastName': 'Adams',
+      'middleInitial': 'N'
+    }
+  });
+  await modal.present();
+}
+```
+
+To get the data passed into the `componentProps`, set each one as a `@Prop`:
+
+```tsx
+import { Component, Prop, h } from '@stencil/core';
+
+@Component({
+  tag: 'page-modal',
+  styleUrl: 'page-modal.css',
+})
+export class PageModal {
+  // Data passed in by componentProps
+  @Prop() firstName: string;
+  @Prop() lastName: string;
+  @Prop() middleInitial: string;
+}
+```
+
+### Dismissing a Modal
+
+A modal can be dismissed by calling the dismiss method on the modal controller and optionally passing any data from the modal.
+
+```tsx
+export class ModalPage {
+  ...
+
+  dismiss(data?: any) {
+    // dismiss the closest modal and optionally pass back data
+    (this.el.closest('ion-modal') as any).dismiss({
+      'dismissed': true
+    });
+  }
+}
+```
+
+After being dismissed, the data can be read in through the `onWillDismiss` or `onDidDismiss` attached to the modal after creation:
+
+```tsx
+const { data } = await modal.onWillDismiss();
+console.log(data);
+```
+
+### Swipeable Modals
+
+Modals in iOS mode have the ability to be presented in a card-style and swiped to close. The card-style presentation and swipe to close gesture are not mutually exclusive, meaning you can pick and choose which features you want to use. For example, you can have a card-style modal that cannot be swiped or a full sized modal that can be swiped.
+
+```tsx
+import { Component, Element, h } from '@stencil/core';
+
+import { modalController } from '@ionic/core';
+
+@Component({
+  tag: 'modal-example',
+  styleUrl: 'modal-example.css'
+})
+export class ModalExample {
+  @Element() el: any;
+
+  async presentModal() {
+    const modal = await modalController.create({
+      component: 'page-modal',
+      swipeToClose: true,
+      presentingElement: this.el.closest('ion-router-outlet'),
+    });
+    await modal.present();
+  }
+
+}
+```
+
+In most scenarios, using the `ion-router-outlet` element as the `presentingElement` is fine. In cases where you are presenting a card-style modal from within another modal, you should pass in the top-most `ion-modal` element as the `presentingElement`.
+
+```tsx
+async presentModal() {
+  const modal = await modalController.create({
+    component: 'page-modal',
+    swipeToClose: true,
+    presentingElement: await modalController.getTop() // Get the top-most ion-modal
+  });
+  await modal.present();
+}
+```
+
+
 ### Vue
 
 ```html

core/src/components/modal/usage/stencil.md

@@ -0,0 +1,145 @@
+```tsx
+import { Component, h } from '@stencil/core';
+
+import { modalController } from '@ionic/core';
+
+@Component({
+  tag: 'modal-example',
+  styleUrl: 'modal-example.css'
+})
+export class ModalExample {
+  async presentModal() {
+    const modal = await modalController.create({
+      component: 'page-modal'
+    });
+    await modal.present();
+  }
+}
+```
+
+```tsx
+import { Component, h } from '@stencil/core';
+
+@Component({
+  tag: 'page-modal',
+  styleUrl: 'page-modal.css',
+})
+export class PageModal {
+  render() {
+    return [
+      <ion-list>
+        <ion-item>
+          <ion-label>Documentation</ion-label>
+        </ion-item>
+        <ion-item>
+          <ion-label>Feedback</ion-label>
+        </ion-item>
+        <ion-item>
+          <ion-label>Settings</ion-label>
+        </ion-item>
+      </ion-list>
+    ];
+  }
+}
+```
+
+### Passing Data
+
+During creation of a modal, data can be passed in through the `componentProps`.
+The previous example can be written to include data:
+
+```tsx
+async presentModal() {
+  const modal = await modalController.create({
+    component: 'page-modal',
+    componentProps: {
+      'firstName': 'Douglas',
+      'lastName': 'Adams',
+      'middleInitial': 'N'
+    }
+  });
+  await modal.present();
+}
+```
+
+To get the data passed into the `componentProps`, set each one as a `@Prop`:
+
+```tsx
+import { Component, Prop, h } from '@stencil/core';
+
+@Component({
+  tag: 'page-modal',
+  styleUrl: 'page-modal.css',
+})
+export class PageModal {
+  // Data passed in by componentProps
+  @Prop() firstName: string;
+  @Prop() lastName: string;
+  @Prop() middleInitial: string;
+}
+```
+
+### Dismissing a Modal
+
+A modal can be dismissed by calling the dismiss method on the modal controller and optionally passing any data from the modal.
+
+```tsx
+export class ModalPage {
+  ...
+
+  dismiss(data?: any) {
+    // dismiss the closest modal and optionally pass back data
+    (this.el.closest('ion-modal') as any).dismiss({
+      'dismissed': true
+    });
+  }
+}
+```
+
+After being dismissed, the data can be read in through the `onWillDismiss` or `onDidDismiss` attached to the modal after creation:
+
+```tsx
+const { data } = await modal.onWillDismiss();
+console.log(data);
+```
+
+### Swipeable Modals
+
+Modals in iOS mode have the ability to be presented in a card-style and swiped to close. The card-style presentation and swipe to close gesture are not mutually exclusive, meaning you can pick and choose which features you want to use. For example, you can have a card-style modal that cannot be swiped or a full sized modal that can be swiped.
+
+```tsx
+import { Component, Element, h } from '@stencil/core';
+
+import { modalController } from '@ionic/core';
+
+@Component({
+  tag: 'modal-example',
+  styleUrl: 'modal-example.css'
+})
+export class ModalExample {
+  @Element() el: any;
+
+  async presentModal() {
+    const modal = await modalController.create({
+      component: 'page-modal',
+      swipeToClose: true,
+      presentingElement: this.el.closest('ion-router-outlet'),
+    });
+    await modal.present();
+  }
+
+}
+```
+
+In most scenarios, using the `ion-router-outlet` element as the `presentingElement` is fine. In cases where you are presenting a card-style modal from within another modal, you should pass in the top-most `ion-modal` element as the `presentingElement`.
+
+```tsx
+async presentModal() {
+  const modal = await modalController.create({
+    component: 'page-modal',
+    swipeToClose: true,
+    presentingElement: await modalController.getTop() // Get the top-most ion-modal
+  });
+  await modal.present();
+}
+```