chore(): sync with main (#3405)

Co-authored-by: Shawn Taylor <[email protected]> Co-authored-by: Liam DeBeasi <[email protected]> Co-authored-by: Amanda Johnston <[email protected]> Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Co-authored-by: ptmkenny <[email protected]> Co-authored-by: Brandy Carney <[email protected]> Co-authored-by: Matthew Harris <[email protected]> Co-authored-by: Nikita Barsukov <[email protected]>
ionic-team · Jan 29, 2024 · fa5d868 · fa5d868
1 parent 50546f5
commit fa5d868
Show file tree

Hide file tree

Showing 332 changed files with 11,753 additions and 10,557 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -1,10 +1,11 @@
 src/theme/DocItem
-src/theme/DocPage
+src/theme/DocRoot
 legacy-stencil-components
 scripts/bak
 
 docs/api
 docs/native
+versioned_docs/version-v*/native
 docs/cli/commands
 
 static/code/stackblitz

diff --git a/docs/angular/build-options.md b/docs/angular/build-options.md
@@ -1,3 +1,6 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Build Options
 
 Developers have two options for using Ionic components: Standalone or Modules. This guide covers both options as well as the benefits and downsides of each approach.
@@ -28,7 +31,7 @@ See the [Standalone Migration Guide](#migrating-from-modules-to-standalone) for
 
 ### Usage with Standalone-based Applications
 
-:::caution
+:::warning
 All Ionic imports should be imported from the `@ionic/angular/standalone` submodule. This includes imports such as components, directives, providers, and types. Importing from `@ionic/angular` may pull in lazy loaded Ionic code which can interfere with treeshaking.
 :::
 
@@ -175,9 +178,32 @@ export class HomePage {}
 <ion-button routerLink="/foo" routerDirection="root">Go to Foo Page</ion-button>
 ```
 
+**Testing**
+
+Ionic Angular's standalone components use ES Modules. As a result, developers using Jest should ensure that ES Modules are transpiled to a format that Jest can use. Developers using Jest should add the following to their Jest config:
+
+<Tabs groupId="package-manager" defaultValue="npm" values={[{ value: 'npm', label: 'npm' }, { value: 'pnpm', label: 'pnpm' }]}>
+<TabItem value="npm">
+
+```json
+
+"transformIgnorePatterns": ["<rootDir>/node_modules/(?!(@ionic/angular|@ionic/core|ionicons|@stencil/core|@angular/*)/)"]
+```
+
+</TabItem>
+<TabItem value="pnpm">
+
+```json
+
+"transformIgnorePatterns": ["<rootDir>/node_modules/.pnpm/(?!(@ionic/angular|@ionic/core|ionicons|@stencil/core|@angular/*)@)"]
+```
+
+</TabItem>
+</Tabs>
+
 ### Usage with NgModule-based Applications
 
-:::caution
+:::warning
 All Ionic imports should be imported from the `@ionic/angular/standalone` submodule. This includes imports such as components, directives, providers, and types. Importing from `@ionic/angular` may pull in lazy loaded Ionic code which can interfere with treeshaking.
 :::
 
@@ -315,6 +341,29 @@ export class HomePageModule {}
 <ion-button routerLink="/foo" routerDirection="root">Go to Foo Page</ion-button>
 ```
 
+**Testing**
+
+Ionic Angular's standalone components use ES Modules. As a result, developers using Jest should ensure that ES Modules are transpiled to a format that Jest can use. Developers using Jest should add the following to their Jest config:
+
+<Tabs groupId="package-manager" defaultValue="npm" values={[{ value: 'npm', label: 'npm' }, { value: 'pnpm', label: 'pnpm' }]}>
+<TabItem value="npm">
+
+```json
+
+"transformIgnorePatterns": ["<rootDir>/node_modules/(?!(@ionic/angular|@ionic/core|ionicons|@stencil/core|@angular/*)/)"]
+```
+
+</TabItem>
+<TabItem value="pnpm">
+
+```json
+
+"transformIgnorePatterns": ["<rootDir>/node_modules/.pnpm/(?!(@ionic/angular|@ionic/core|ionicons|@stencil/core|@angular/*)@)"]
+```
+
+</TabItem>
+</Tabs>
+
 ## Modules
 
 ### Overview

diff --git a/docs/angular/navigation.md b/docs/angular/navigation.md
@@ -175,7 +175,7 @@ Here, we have a typical Angular Module setup, along with a RouterModule import,
 
 ## Standalone Components
 
-:::caution Experimental API
+:::warning Experimental API
 
 Standalone components is an experimental API introduced in Angular 14.x and available in Ionic 6.3 and later. This feature may change before it is stable.
 

diff --git a/docs/angular/slides.md b/docs/angular/slides.md
@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
   />
 </head>
 
-:::caution Looking for `ion-slides`?
+:::warning Looking for `ion-slides`?
 `ion-slides` was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the Swiper.js library directly. The migration process is detailed below.
 :::
 

diff --git a/docs/angular/virtual-scroll.md b/docs/angular/virtual-scroll.md
@@ -1,6 +1,6 @@
 # Virtual Scroll
 
-:::caution Looking for `ion-virtual-scroll`?
+:::warning Looking for `ion-virtual-scroll`?
 
 `ion-virtual-scroll` was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the `@angular/cdk` package detailed below.
 

diff --git a/docs/angular/your-first-app.md b/docs/angular/your-first-app.md
@@ -19,9 +19,9 @@ Here’s the finished app running on all 3 platforms:
   width="560"
   height="315"
   src="https://www.youtube.com/embed/0ASQ13Y1Rk4"
-  frameborder="0"
+  frameBorder="0"
   allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture"
-  allowfullscreen
+  allowFullScreen
 ></iframe>
 
 :::note

diff --git a/docs/api/input.md b/docs/api/input.md
@@ -10,15 +10,15 @@ import Slots from '@ionic-internal/component-api/v8/input/slots.md';
 
 <head>
   <title>ion-input: Custom Input With Styling and CSS Properties</title>
-  <meta name="description" content="ion-input is a wrapper to the HTML input element, with custom value type styling and functionality. It works on desktops and integrates with mobile keyboards." />
+  <meta name="description" content="ion-input is a wrapper to the HTML input element, with custom value type styling and functionality. It integrates with the keyboard on mobile devices." />
 </head>
 
 import EncapsulationPill from '@components/page/api/EncapsulationPill';
 
 <EncapsulationPill type="scoped" />
 
 
-The input component is a wrapper to the HTML input element with custom styling and additional functionality. It accepts most of the same properties as the HTML input, but works great on desktop devices and integrates with the keyboard on mobile devices.
+The input component is a wrapper to the HTML input element with custom styling and additional functionality. It accepts most of the same properties as the HTML input and integrates with the keyboard on mobile devices.
 
 
 ## Basic Usage
@@ -148,6 +148,22 @@ Please submit bug reports with Maskito to the [Maskito Github repository](https:
 
 :::
 
+## Start and End Slots (experimental)
+
+The `start` and `end` slots can be used to place icons, buttons, or prefix/suffix text on either side of the input.
+
+Note that this feature is considered experimental because it relies on a simulated version of [Web Component slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots). As a result, the simulated behavior may not exactly match the native slot behavior.
+
+:::note
+In most cases, [Icon](./icon.md) components placed in these slots should have `aria-hidden="true"`. See the [Icon accessibility docs](https://ionicframework.com/docs/api/icon#accessibility) for more information.
+
+If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a [Button](./button.md). This ensures that the content can be tabbed to.
+:::
+
+import StartEndSlots from '@site/static/usage/v7/input/start-end-slots/index.md';
+
+<StartEndSlots />
+
 ## Theming
 
 ### Colors

diff --git a/docs/api/radio.md b/docs/api/radio.md
@@ -36,6 +36,14 @@ import LabelPlacement from '@site/static/usage/v8/radio/label-placement/index.md
 
 <LabelPlacement />
 
+## Object Value References
+
+By default, the radio group uses strict equality (`===`) to determine if an option is selected. This can be overridden by providing a property name or a function to the `compareWith` property.
+
+import UsingComparewith from '@site/static/usage/v7/radio/using-comparewith/index.md';
+
+<UsingComparewith />
+
 ## Alignment
 
 Developers can use the `alignment` property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox `align-items` property.

diff --git a/docs/api/select.md b/docs/api/select.md
@@ -119,7 +119,7 @@ import RespondingToInteractionExample from '@site/static/usage/v8/select/basic/r
 
 When using objects for select values, it is possible for the identities of these objects to change if they are coming from a server or database, while the selected value's identity remains the same. For example, this can occur when an existing record with the desired object value is loaded into the select, but the newly retrieved select options now have different identities. This will result in the select appearing to have no value at all, even though the original selection in still intact.
 
-By default, the select uses object equality (`===`) to determine if an option is selected. This can be overridden by providing a property name or a function to the `compareWith` property.
+By default, the select uses strict equality (`===`) to determine if an option is selected. This can be overridden by providing a property name or a function to the `compareWith` property.
 
 ### Using compareWith
 
@@ -173,6 +173,20 @@ import InterfaceOptionsExample from '@site/static/usage/v8/select/customization/
 
 <InterfaceOptionsExample />
 
+## Start and End Slots
+
+The `start` and `end` slots can be used to place icons, buttons, or prefix/suffix text on either side of the select. If the slot content is clicked, the select will not open.
+
+:::note
+In most cases, [Icon](./icon.md) components placed in these slots should have `aria-hidden="true"`. See the [Icon accessibility docs](https://ionicframework.com/docs/api/icon#accessibility) for more information.
+
+If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a [Button](./button.md). This ensures that the content can be tabbed to.
+:::
+
+import StartEndSlots from '@site/static/usage/v7/select/start-end-slots/index.md';
+
+<StartEndSlots />
+
 ## Customization
 
 There are two units that make up the Select component and each need to be styled separately. The `ion-select` element is represented on the view by the selected value(s), or placeholder if there is none, and dropdown icon. The interface, which is defined in the [Interfaces](#interfaces) section above, is the dialog that opens when clicking on the `ion-select`. The interface contains all of the options defined by adding `ion-select-option` elements. The following sections will go over the differences between styling these.

diff --git a/docs/api/textarea.md b/docs/api/textarea.md
@@ -109,6 +109,22 @@ import ClearOnEditPlayground from '@site/static/usage/v8/textarea/clear-on-edit/
 
 <ClearOnEditPlayground />
 
+## Start and End Slots (experimental)
+
+The `start` and `end` slots can be used to place icons, buttons, or prefix/suffix text on either side of the textarea.
+
+Note that this feature is considered experimental because it relies on a simulated version of [Web Component slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots). As a result, the simulated behavior may not exactly match the native slot behavior.
+
+:::note
+In most cases, [Icon](./icon.md) components placed in these slots should have `aria-hidden="true"`. See the [Icon accessibility docs](https://ionicframework.com/docs/api/icon#accessibility) for more information.
+
+If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a [Button](./button.md). This ensures that the content can be tabbed to.
+:::
+
+import StartEndSlots from '@site/static/usage/v7/textarea/start-end-slots/index.md';
+
+<StartEndSlots />
+
 ## Migrating from Legacy Textarea Syntax
 
 A simpler textarea syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an textarea, resolves accessibility issues, and improves the developer experience.

diff --git a/docs/api/toast.md b/docs/api/toast.md
@@ -72,6 +72,14 @@ import PositionAnchor from '@site/static/usage/v8/toast/position-anchor/index.md
 
 <PositionAnchor />
 
+## Swipe to Dismiss
+
+Toasts can be swiped to dismiss by using the `swipeGesture` property. This feature is position-aware, meaning the direction that users need to swipe will change based on the value of the `position` property. Additionally, the distance users need to swipe may be impacted by the `positionAnchor` property.
+
+import SwipeGesture from '@site/static/usage/v7/toast/swipe-gesture/index.md';
+
+<SwipeGesture />
+
 ## Layout
 
 Button containers within the toast can be displayed either on the same line as the message or stacked on separate lines using the `layout` property. The stacked layout should be used with buttons that have long text values. Additionally, buttons in a stacked toast layout can use a `side` value of either `start` or `end`, but not both.

diff --git a/docs/components.md b/docs/components.md
@@ -41,9 +41,8 @@ Ionic apps are made of high-level building blocks called Components, which allow
 </DocsCard>
 
 <DocsCard header="Card" href="api/card" icon="/icons/component-card-icon.png">
-  <p>
-    Cards are a great way to display an important piece of content, and can contain images, buttons, text, and more.
-  </p>
+  <!-- prettier-ignore -->
+  <p>Cards are a great way to display an important piece of content, and can contain images, buttons, text, and more.</p>
 </DocsCard>
 
 <DocsCard header="Checkbox" href="api/checkbox" icon="/icons/component-checkbox-icon.png">
@@ -67,7 +66,7 @@ Ionic apps are made of high-level building blocks called Components, which allow
 </DocsCard>
 
 <DocsCard header="Icons" href="api/icon" img="/icons/feature-component-icons-icon.png">
-  <p>Beautifully designed icons for use in web, iOS, Android, and desktop apps.</p>
+  <p>Beautifully designed icons for use in web, iOS, and Android apps.</p>
 </DocsCard>
 
 <DocsCard header="Grid" href="api/grid" icon="/icons/component-grid-icon.png">

diff --git a/docs/core-concepts/cross-platform.md b/docs/core-concepts/cross-platform.md
@@ -35,9 +35,9 @@ This bit of code can be incredibly helpful when targeting environments where acc
 
 Many native APIs that people use (for example, the File API), are not available in the browser. The APIs are always improving and catching up to native, so it is recommended to research them. Taking the first two points into consideration, it's fairly easy to create a nice experience that will adapt for the platform the app is running on.
 
-## Desktop
+## Responsive UI
 
-When planning to deploy an app to desktop, either using <a href="https://electronjs.org" target="_blank">Electron</a> or as a <strong>Progressive Web App</strong>, it is important to ensure the app works smoothly on larger devices.
+When planning to deploy an app that may be used across a variety of devices, it is important to ensure the app works smoothly on larger screen sizes.
 
 ### Layout
 
@@ -63,7 +63,7 @@ Many people rarely notice the layout of an app, but it can have a massive impact
 </ion-content>
 ```
 
-This will render 5 items with a width of 100% each. This may look great on a mobile device, as seen below, but viewing this on a desktop browser is a different story. The items become stretched to fill the entire screen because of the wide screen width, leaving screen space unused.
+This will render 5 items with a width of 100% each. This may look great on a phone, but viewing this on a larger screen is a different story. The items become stretched to fill the entire screen because of the wide screen width, leaving screen space unused.
 
 <img src={require('@site/static/img/building/cross-platform-items.png').default} />
 

diff --git a/docs/deployment/app-store.md b/docs/deployment/app-store.md
@@ -3,6 +3,9 @@ title: iOS App Store Deployment
 sidebar_label: iOS App Store
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 <head>
   <title>Publish to iOS App Store: Apple App Store Deployment for Ionic</title>
   <meta
@@ -24,6 +27,46 @@ To enroll in the Apple Developer Program, follow the instructions [listed here](
 
 ## Generating a release build
 
+<Tabs groupId="runtime">
+<TabItem value="capacitor" label="Capacitor" default>
+
+If the iOS platform is not already added, be sure to add it:
+
+```shell
+ionic cap add ios
+```
+
+With the platform added, run the build command with the `--prod` flag:
+
+```shell
+ionic build --prod
+```
+
+This will generate the minified code for the web portion of an app.
+
+For this first build, and after you make any binary changes like adding a plugin, use the sync command:
+
+```shell
+npx cap sync ios
+```
+
+This will also copy the minified web code over. However, if your build is only source change then you can just copy the minified web files using:
+
+```shell
+npx cap copy ios
+```
+
+From here, the project is now managed as if it was a native Xcode app (because it is).
+
+Open the project in `./ios/` to start Xcode:
+
+```shell
+npx cap open ios
+```
+
+</TabItem>
+<TabItem value="cordova" label="Cordova">
+
 If the iOS platform is not already added, be sure to add it:
 
 ```shell
@@ -44,6 +87,9 @@ From here, open the `.xcworkspace` file in `./platforms/ios/` to start Xcode.
 You can also have a release build generated automatically by using the `--release` flag.
 :::
 
+</TabItem>
+</Tabs>
+
 ## Generating Signing Certs
 
 Generating certificates for iOS is a bit of an involved process, so be sure to check [Apple's official documentation](https://help.apple.com/xcode/mac/current/#/dev3a05256b8) on what certificates are and how to generate them.
-Original file line number
+Diff line change
@@ Expand Up / @@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem'; @@
       />
     </head>
-    :::caution Looking for `ion-slides`?
+    :::warning Looking for `ion-slides`?
     `ion-slides` was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the Swiper.js library directly. The migration process is detailed below.
     :::
@@ Expand Down @@