chore: clarity

Issue number: N/A
---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

- Syncs the `feature.8.0` branch with the latest from `main`.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

.github/CODEOWNERS

@@ -13,30 +13,7 @@
 
 * @ionic-team/framework
 
-# Frameworks
-
-## Angular
-
-/packages/angular/ @sean-perkins @thetaPC
-/packages/angular-server @sean-perkins @thetaPC
-/packages/angular/test @thetaPC
-
-## Vue
-
-/packages/vue/ @thetaPC
-/packages/vue-router/ @liamdebeasi @thetaPC
-/packages/vue/test/ @thetaPC
-/packages/vue-router/__tests__ @thetaPC
-
-# Components
-
-/core/src/components/datetime/ @sean-perkins
-
-/core/src/components/nav/ @sean-perkins
-/core/src/components/nav-link/ @sean-perkins
-
 # Utilities
 
-/core/src/utils/content/ @sean-perkins
 /core/src/utils/gesture/ @liamdebeasi
 /core/src/utils/input-shims/ @liamdebeasi

.github/PULL_REQUEST_TEMPLATE.md

@@ -25,7 +25,7 @@ Issue number: resolves #
   If this introduces a breaking change:
   1. Describe the impact and migration path for existing applications below.
   2. Update the BREAKING.md file with the breaking change.
-  3. Add "BREAKING CHANGE: [...]" to the commit description when merging. See https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer for more information.
+  3. Add "BREAKING CHANGE: [...]" to the commit description when merging. See https://github.com/ionic-team/ionic-framework/blob/main/docs/CONTRIBUTING.md#footer for more information.
 -->
 
 

README.md

@@ -20,7 +20,7 @@
   <a href="https://github.com/ionic-team/ionic-framework/blob/main/LICENSE">
     <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Ionic Framework is released under the MIT license." />
   </a>
-  <a href="https://github.com/ionic-team/ionic/blob/main/.github/CONTRIBUTING.md">
+  <a href="https://github.com/ionic-team/ionic/blob/main/docs/CONTRIBUTING.md">
     <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome!" />
   </a>
   <a href="https://twitter.com/Ionicframework">
@@ -38,7 +38,7 @@
     Documentation
   </a>
   <span> · </span>
-  <a href="https://github.com/ionic-team/ionic/blob/main/.github/CONTRIBUTING.md">Contribute</a>
+  <a href="https://github.com/ionic-team/ionic/blob/main/docs/CONTRIBUTING.md">Contribute</a>
   <span> · </span>
   <a href="https://blog.ionicframework.com/">Blog</a>
   <br />
@@ -88,7 +88,7 @@ The Ionic Conference App is a full featured Ionic app. It is the perfect startin
 ### Contributing
 
 Thanks for your interest in contributing! Read up on our guidelines for
-[contributing](https://github.com/ionic-team/ionic/blob/main/.github/CONTRIBUTING.md)
+[contributing](https://github.com/ionic-team/ionic/blob/main/docs/CONTRIBUTING.md)
 and then look through our issues with a [help wanted](https://github.com/ionic-team/ionic/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
 label.
 

core/api.txt

@@ -361,6 +361,7 @@ ion-col,css-prop,--ion-grid-columns
 
 ion-content,shadow
 ion-content,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true
+ion-content,prop,fixedSlotPlacement,"after" | "before",'after',false,false
 ion-content,prop,forceOverscroll,boolean | undefined,undefined,false,false
 ion-content,prop,fullscreen,boolean,false,false,false
 ion-content,prop,scrollEvents,boolean,false,false,false
@@ -549,10 +550,11 @@ ion-infinite-scroll-content,prop,loadingText,IonicSafeString | string | undefine
 
 ion-input,scoped
 ion-input,prop,autocapitalize,string,'off',false,false
-ion-input,prop,autocomplete,"name" | "on" | "off" | "honorific-prefix" | "given-name" | "additional-name" | "family-name" | "honorific-suffix" | "nickname" | "email" | "username" | "new-password" | "current-password" | "one-time-code" | "organization-title" | "organization" | "street-address" | "address-line1" | "address-line2" | "address-line3" | "address-level4" | "address-level3" | "address-level2" | "address-level1" | "country" | "country-name" | "postal-code" | "cc-name" | "cc-given-name" | "cc-additional-name" | "cc-family-name" | "cc-number" | "cc-exp" | "cc-exp-month" | "cc-exp-year" | "cc-csc" | "cc-type" | "transaction-currency" | "transaction-amount" | "language" | "bday" | "bday-day" | "bday-month" | "bday-year" | "sex" | "tel" | "tel-country-code" | "tel-national" | "tel-area-code" | "tel-local" | "tel-extension" | "impp" | "url" | "photo",'off',false,false
+ion-input,prop,autocomplete,"name" | "email" | "tel" | "url" | "on" | "off" | "honorific-prefix" | "given-name" | "additional-name" | "family-name" | "honorific-suffix" | "nickname" | "username" | "new-password" | "current-password" | "one-time-code" | "organization-title" | "organization" | "street-address" | "address-line1" | "address-line2" | "address-line3" | "address-level4" | "address-level3" | "address-level2" | "address-level1" | "country" | "country-name" | "postal-code" | "cc-name" | "cc-given-name" | "cc-additional-name" | "cc-family-name" | "cc-number" | "cc-exp" | "cc-exp-month" | "cc-exp-year" | "cc-csc" | "cc-type" | "transaction-currency" | "transaction-amount" | "language" | "bday" | "bday-day" | "bday-month" | "bday-year" | "sex" | "tel-country-code" | "tel-national" | "tel-area-code" | "tel-local" | "tel-extension" | "impp" | "photo",'off',false,false
 ion-input,prop,autocorrect,"off" | "on",'off',false,false
 ion-input,prop,autofocus,boolean,false,false,false
 ion-input,prop,clearInput,boolean,false,false,false
+ion-input,prop,clearInputIcon,string | undefined,undefined,false,false
 ion-input,prop,clearOnEdit,boolean | undefined,undefined,false,false
 ion-input,prop,color,"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined,undefined,false,true
 ion-input,prop,counter,boolean,false,false,false
@@ -829,6 +831,7 @@ ion-modal,prop,backdropDismiss,boolean,true,false,false
 ion-modal,prop,breakpoints,number[] | undefined,undefined,false,false
 ion-modal,prop,canDismiss,((data?: any, role?: string | undefined) => Promise<boolean>) | boolean,true,false,false
 ion-modal,prop,enterAnimation,((baseEl: any, opts?: any) => Animation) | undefined,undefined,false,false
+ion-modal,prop,focusTrap,boolean,true,false,false
 ion-modal,prop,handle,boolean | undefined,undefined,false,false
 ion-modal,prop,handleBehavior,"cycle" | "none" | undefined,'none',false,false
 ion-modal,prop,htmlAttributes,undefined | { [key: string]: any; },undefined,false,false
@@ -977,6 +980,7 @@ ion-popover,prop,componentProps,undefined | { [key: string]: any; },undefined,fa
 ion-popover,prop,dismissOnSelect,boolean,false,false,false
 ion-popover,prop,enterAnimation,((baseEl: any, opts?: any) => Animation) | undefined,undefined,false,false
 ion-popover,prop,event,any,undefined,false,false
+ion-popover,prop,focusTrap,boolean,true,false,false
 ion-popover,prop,htmlAttributes,undefined | { [key: string]: any; },undefined,false,false
 ion-popover,prop,isOpen,boolean,false,false,false
 ion-popover,prop,keepContentsMounted,boolean,false,false,false
@@ -1173,7 +1177,7 @@ ion-row,shadow
 ion-searchbar,scoped
 ion-searchbar,prop,animated,boolean,false,false,false
 ion-searchbar,prop,autocapitalize,string,'off',false,false
-ion-searchbar,prop,autocomplete,"name" | "on" | "off" | "honorific-prefix" | "given-name" | "additional-name" | "family-name" | "honorific-suffix" | "nickname" | "email" | "username" | "new-password" | "current-password" | "one-time-code" | "organization-title" | "organization" | "street-address" | "address-line1" | "address-line2" | "address-line3" | "address-level4" | "address-level3" | "address-level2" | "address-level1" | "country" | "country-name" | "postal-code" | "cc-name" | "cc-given-name" | "cc-additional-name" | "cc-family-name" | "cc-number" | "cc-exp" | "cc-exp-month" | "cc-exp-year" | "cc-csc" | "cc-type" | "transaction-currency" | "transaction-amount" | "language" | "bday" | "bday-day" | "bday-month" | "bday-year" | "sex" | "tel" | "tel-country-code" | "tel-national" | "tel-area-code" | "tel-local" | "tel-extension" | "impp" | "url" | "photo",'off',false,false
+ion-searchbar,prop,autocomplete,"name" | "email" | "tel" | "url" | "on" | "off" | "honorific-prefix" | "given-name" | "additional-name" | "family-name" | "honorific-suffix" | "nickname" | "username" | "new-password" | "current-password" | "one-time-code" | "organization-title" | "organization" | "street-address" | "address-line1" | "address-line2" | "address-line3" | "address-level4" | "address-level3" | "address-level2" | "address-level1" | "country" | "country-name" | "postal-code" | "cc-name" | "cc-given-name" | "cc-additional-name" | "cc-family-name" | "cc-number" | "cc-exp" | "cc-exp-month" | "cc-exp-year" | "cc-csc" | "cc-type" | "transaction-currency" | "transaction-amount" | "language" | "bday" | "bday-day" | "bday-month" | "bday-year" | "sex" | "tel-country-code" | "tel-national" | "tel-area-code" | "tel-local" | "tel-extension" | "impp" | "photo",'off',false,false
 ion-searchbar,prop,autocorrect,"off" | "on",'off',false,false
 ion-searchbar,prop,cancelButtonIcon,string,config.get('backButtonIcon', arrowBackSharp) as string,false,false
 ion-searchbar,prop,cancelButtonText,string,'Cancel',false,false

core/package-lock.json

@@ -1759,9 +1759,9 @@
       }
     },
     "node_modules/@stencil/core": {
-      "version": "4.13.0",
-      "resolved": "https://registry.npmjs.org/@stencil/core/-/core-4.13.0.tgz",
-      "integrity": "sha512-gg+gtBWekQ08mDja8GVAUHNu+rrFhQaKZDvfhnS3l/5JbYiJddTimuDPPhuc0sR0JZL1iRdJTJSa+JbvmnQ1cQ==",
+      "version": "4.14.0",
+      "resolved": "https://registry.npmjs.org/@stencil/core/-/core-4.14.0.tgz",
+      "integrity": "sha512-+s0u/KsNolXZ7tC2hEMgMA3jaNaqOhZvYKwSzjQbc0Wv+cB481Isxzo7ifgEWRYqsJzNSyqhO6cyu/EJrGGTdg==",
       "bin": {
         "stencil": "bin/stencil"
       },
@@ -11229,9 +11229,9 @@
       "requires": {}
     },
     "@stencil/core": {
-      "version": "4.13.0",
-      "resolved": "https://registry.npmjs.org/@stencil/core/-/core-4.13.0.tgz",
-      "integrity": "sha512-gg+gtBWekQ08mDja8GVAUHNu+rrFhQaKZDvfhnS3l/5JbYiJddTimuDPPhuc0sR0JZL1iRdJTJSa+JbvmnQ1cQ=="
+      "version": "4.14.0",
+      "resolved": "https://registry.npmjs.org/@stencil/core/-/core-4.14.0.tgz",
+      "integrity": "sha512-+s0u/KsNolXZ7tC2hEMgMA3jaNaqOhZvYKwSzjQbc0Wv+cB481Isxzo7ifgEWRYqsJzNSyqhO6cyu/EJrGGTdg=="
     },
     "@stencil/react-output-target": {
       "version": "0.5.3",

core/package.json

@@ -77,7 +77,7 @@
     "build.docs.json": "stencil build --docs-json dist/docs.json",
     "clean": "node scripts/clean.js",
     "css.minify": "cleancss -O2 -o ./css/ionic.bundle.css ./css/ionic.bundle.css",
-    "css.sass": "sass --embed-sources src/css:./css",
+    "css.sass": "sass --embed-sources --style compressed src/css:./css",
     "eslint": "eslint src",
     "lint": "npm run lint.ts && npm run lint.sass && npm run prettier -- --write --cache",
     "lint.fix": "npm run lint.ts.fix && npm run lint.sass.fix && npm run prettier -- --write --cache",

core/scripts/readme.md

@@ -1,44 +1,4 @@
 
-## Build
+# Core Scripts
 
-### 1. Clone ionic
-
-    git@github.com:ionic-team/ionic.git
-    cd ionic
-
-### 2. Run `npm install`
-
-  cd core
-  npm install
-
-
-Notice that `@ionic/core` lives in `core`.
-
-### 3. Run `npm start`
-
-Make sure you are inside the `core` directory.
-
-    npm start
-
-With the `dev` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and http://localhost:3333/ will open in a browser.
-
-### 4. Preview
-
-Navigate to http://localhost:3333/src/components/. Each component has small e2e apps found in the `test` directory, for example: http://localhost:3333/src/components/button/test/basic
-
-As changes are made in an editor to source files, the e2e app will live-reload.
-
-## How to contribute
-
-1. `npm start` allows you to modify the components and have live reloading, just like another ionic app.
-
-2. When everything looks good, run  `npm run validate` to verify the tests linter and production build passes.
-
-
-# Deploy
-
-1. `npm run prepare.deploy`
-2. Review/update changelog
-3. Commit updates using the package name and version number as the commit message.
-4. `npm run deploy`
-5. :tada:
+This file has been moved to [/docs/core/testing/preview-changes.md](/docs/core/testing/preview-changes.md).

core/src/components.d.ts

@@ -762,6 +762,10 @@ export namespace Components {
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
         "color"?: Color;
+        /**
+          * Controls where the fixed content is placed relative to the main content in the DOM. This can be used to control the order in which fixed elements receive keyboard focus. For example, if a FAB in the fixed slot should receive keyboard focus before the main page content, set this property to `'before'`.
+         */
+        "fixedSlotPlacement": 'after' | 'before';
         /**
           * If `true` and the content does not cause an overflow scroll, the scroll interaction will cause a bounce. If the content exceeds the bounds of ionContent, nothing will change. Note, this does not disable the system bounce on iOS. That is an OS level setting.
          */
@@ -1162,6 +1166,10 @@ export namespace Components {
           * If `true`, a clear icon will appear in the input when there is a value. Clicking it clears the input.
          */
         "clearInput": boolean;
+        /**
+          * The icon to use for the clear button. Only applies when `clearInput` is set to `true`.
+         */
+        "clearInputIcon"?: string;
         /**
           * If `true`, the value will be cleared after focus upon edit. Defaults to `true` when `type` is `"password"`, `false` for all other types.
          */
@@ -1715,6 +1723,10 @@ export namespace Components {
           * Animation to use when the modal is presented.
          */
         "enterAnimation"?: AnimationBuilder;
+        /**
+          * If `true`, focus will not be allowed to move outside of this overlay. If 'false', focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
+         */
+        "focusTrap": boolean;
         /**
           * Returns the current breakpoint of a sheet style modal
          */
@@ -2131,6 +2143,10 @@ export namespace Components {
           * The event to pass to the popover animation.
          */
         "event": any;
+        /**
+          * If `true`, focus will not be allowed to move outside of this overlay. If 'false', focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
+         */
+        "focusTrap": boolean;
         "getParentPopover": () => Promise<HTMLIonPopoverElement | null>;
         "hasController": boolean;
         /**
@@ -5478,6 +5494,10 @@ declare namespace LocalJSX {
           * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
          */
         "color"?: Color;
+        /**
+          * Controls where the fixed content is placed relative to the main content in the DOM. This can be used to control the order in which fixed elements receive keyboard focus. For example, if a FAB in the fixed slot should receive keyboard focus before the main page content, set this property to `'before'`.
+         */
+        "fixedSlotPlacement"?: 'after' | 'before';
         /**
           * If `true` and the content does not cause an overflow scroll, the scroll interaction will cause a bounce. If the content exceeds the bounds of ionContent, nothing will change. Note, this does not disable the system bounce on iOS. That is an OS level setting.
          */
@@ -5886,6 +5906,10 @@ declare namespace LocalJSX {
           * If `true`, a clear icon will appear in the input when there is a value. Clicking it clears the input.
          */
         "clearInput"?: boolean;
+        /**
+          * The icon to use for the clear button. Only applies when `clearInput` is set to `true`.
+         */
+        "clearInputIcon"?: string;
         /**
           * If `true`, the value will be cleared after focus upon edit. Defaults to `true` when `type` is `"password"`, `false` for all other types.
          */
@@ -6441,6 +6465,10 @@ declare namespace LocalJSX {
           * Animation to use when the modal is presented.
          */
         "enterAnimation"?: AnimationBuilder;
+        /**
+          * If `true`, focus will not be allowed to move outside of this overlay. If 'false', focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
+         */
+        "focusTrap"?: boolean;
         /**
           * The horizontal line that displays at the top of a sheet modal. It is `true` by default when setting the `breakpoints` and `initialBreakpoint` properties.
          */
@@ -6787,6 +6815,10 @@ declare namespace LocalJSX {
           * The event to pass to the popover animation.
          */
         "event"?: any;
+        /**
+          * If `true`, focus will not be allowed to move outside of this overlay. If 'false', focus will be allowed to move outside of the overlay.  In most scenarios this property should remain set to `true`. Setting this property to `false` can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to `false` when absolutely necessary.  Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
+         */
+        "focusTrap"?: boolean;
         "hasController"?: boolean;
         /**
           * Additional attributes to pass to the popover.

core/src/components/content/content.tsx

@@ -75,6 +75,15 @@ export class Content implements ComponentInterface {
    */
   @Prop() fullscreen = false;
 
+  /**
+   * Controls where the fixed content is placed relative to the main content
+   * in the DOM. This can be used to control the order in which fixed elements
+   * receive keyboard focus.
+   * For example, if a FAB in the fixed slot should receive keyboard focus before
+   * the main page content, set this property to `'before'`.
+   */
+  @Prop() fixedSlotPlacement: 'after' | 'before' = 'after';
+
   /**
    * If `true` and the content does not cause an overflow scroll, the scroll interaction will cause a bounce.
    * If the content exceeds the bounds of ionContent, nothing will change.
@@ -423,7 +432,7 @@ export class Content implements ComponentInterface {
   }
 
   render() {
-    const { isMainContent, scrollX, scrollY, el } = this;
+    const { fixedSlotPlacement, isMainContent, scrollX, scrollY, el } = this;
     const rtl = isRTL(el) ? 'rtl' : 'ltr';
     const mode = getIonMode(this);
     const forceOverscroll = this.shouldForceOverscroll();
@@ -446,6 +455,9 @@ export class Content implements ComponentInterface {
         }}
       >
         <div ref={(el) => (this.backgroundContentEl = el)} id="background-content" part="background"></div>
+
+        {fixedSlotPlacement === 'before' ? <slot name="fixed"></slot> : null}
+
         <div
           class={{
             'inner-scroll': true,
@@ -467,7 +479,7 @@ export class Content implements ComponentInterface {
           </div>
         ) : null}
 
-        <slot name="fixed"></slot>
+        {fixedSlotPlacement === 'after' ? <slot name="fixed"></slot> : null}
       </Host>
     );
   }

core/src/components/content/test/content.spec.ts

@@ -0,0 +1,31 @@
+import { newSpecPage } from '@stencil/core/testing';
+
+import { Content } from '../content';
+
+describe('content: fixed slot placement', () => {
+  it('should should fixed slot after content', async () => {
+    const page = await newSpecPage({
+      components: [Content],
+      html: '<ion-content></ion-content>',
+    });
+
+    const content = page.body.querySelector('ion-content')!;
+    const fixedSlot = content.shadowRoot!.querySelector('slot[name="fixed"]')!;
+    const scrollEl = content.shadowRoot!.querySelector('[part="scroll"]')!;
+
+    expect(fixedSlot.nextElementSibling).not.toBe(scrollEl);
+  });
+
+  it('should should fixed slot before content', async () => {
+    const page = await newSpecPage({
+      components: [Content],
+      html: `<ion-content fixed-slot-placement="before"></ion-content>`,
+    });
+
+    const content = page.body.querySelector('ion-content')!;
+    const fixedSlot = content.shadowRoot!.querySelector('slot[name="fixed"]')!;
+    const scrollEl = content.shadowRoot!.querySelector('[part="scroll"]')!;
+
+    expect(fixedSlot.nextElementSibling).toBe(scrollEl);
+  });
+});

core/src/components/datetime/datetime.tsx

@@ -541,7 +541,7 @@ export class Datetime implements ComponentInterface {
     }
 
     if (closeOverlay) {
-      this.closeParentOverlay();
+      this.closeParentOverlay(CONFIRM_ROLE);
     }
   }
 
@@ -566,7 +566,7 @@ export class Datetime implements ComponentInterface {
     this.ionCancel.emit();
 
     if (closeOverlay) {
-      this.closeParentOverlay();
+      this.closeParentOverlay(CANCEL_ROLE);
     }
   }
 
@@ -616,13 +616,13 @@ export class Datetime implements ComponentInterface {
     return Array.isArray(activeParts) ? activeParts[0] : activeParts;
   };
 
-  private closeParentOverlay = () => {
+  private closeParentOverlay = (role: string) => {
     const popoverOrModal = this.el.closest('ion-modal, ion-popover') as
       | HTMLIonModalElement
       | HTMLIonPopoverElement
       | null;
     if (popoverOrModal) {
-      popoverOrModal.dismiss();
+      popoverOrModal.dismiss(undefined, role);
     }
   };
 
@@ -2645,5 +2645,7 @@ export class Datetime implements ComponentInterface {
 }
 
 let datetimeIds = 0;
+const CANCEL_ROLE = 'datetime-cancel';
+const CONFIRM_ROLE = 'datetime-confirm';
 const WHEEL_ITEM_PART = 'wheel-item';
 const WHEEL_ITEM_ACTIVE_PART = `active`;

core/src/components/datetime/test/overlay-roles/datetime.e2e.ts

@@ -0,0 +1,41 @@
+import { expect } from '@playwright/test';
+import { configs, test } from '@utils/test/playwright';
+
+configs({ modes: ['ios'], directions: ['ltr'] }).forEach(({ config, title }) => {
+  test.describe(title('datetime: overlay roles'), () => {
+    test.beforeEach(async ({ page }) => {
+      await page.setContent(
+        `
+          <ion-modal>
+            <ion-datetime></ion-datetime>
+          </ion-modal>  
+        `,
+        config
+      );
+    });
+    test('should pass role to overlay when calling confirm method', async ({ page }) => {
+      const ionModalDidDismiss = await page.spyOnEvent('ionModalDidDismiss');
+      const modal = page.locator('ion-modal');
+      const datetime = page.locator('ion-datetime');
+
+      await modal.evaluate((el: HTMLIonModalElement) => el.present());
+
+      await datetime.evaluate((el: HTMLIonDatetimeElement) => el.confirm(true));
+
+      await ionModalDidDismiss.next();
+      expect(ionModalDidDismiss).toHaveReceivedEventDetail({ data: undefined, role: 'datetime-confirm' });
+    });
+    test('should pass role to overlay when calling cancel method', async ({ page }) => {
+      const ionModalDidDismiss = await page.spyOnEvent('ionModalDidDismiss');
+      const modal = page.locator('ion-modal');
+      const datetime = page.locator('ion-datetime');
+
+      await modal.evaluate((el: HTMLIonModalElement) => el.present());
+
+      await datetime.evaluate((el: HTMLIonDatetimeElement) => el.cancel(true));
+
+      await ionModalDidDismiss.next();
+      expect(ionModalDidDismiss).toHaveReceivedEventDetail({ data: undefined, role: 'datetime-cancel' });
+    });
+  });
+});

core/src/components/datetime/test/overlay-roles/index.html

@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Datetime - Overlay Roles</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0" />
+    <link href="../../../../../css/ionic.bundle.css" rel="stylesheet" />
+    <link href="../../../../../scripts/testing/styles.css" rel="stylesheet" />
+    <script src="../../../../../scripts/testing/scripts.js"></script>
+    <script type="module" src="../../../../../dist/ionic/ionic.esm.js"></script>
+    <style>
+      ion-modal.ios,
+      ion-popover.datetime-popover.ios {
+        --width: 350px;
+        --height: 420px;
+      }
+
+      ion-modal.md,
+      ion-popover.datetime-popover.md {
+        --width: 350px;
+        --height: 450px;
+      }
+
+      ion-datetime {
+        width: 350px;
+      }
+    </style>
+  </head>
+  <body>
+    <ion-app>
+      <ion-header translucent="true">
+        <ion-toolbar>
+          <ion-title>Datetime - Overlay Roles</ion-title>
+        </ion-toolbar>
+      </ion-header>
+      <ion-content class="ion-padding">
+        <ion-button onclick="presentModal()">Present Modal</ion-button>
+      </ion-content>
+    </ion-app>
+    <script>
+      const presentModal = async () => {
+        const modal = await createModal();
+
+        await modal.present();
+        console.log(await modal.onDidDismiss());
+      };
+
+      const createModal = () => {
+        // create component to open
+        const element = document.createElement('div');
+        element.innerHTML = `
+            <ion-datetime show-default-buttons="true"></ion-datetime>
+          `;
+
+        // present the modal
+        const modalElement = Object.assign(document.createElement('ion-modal'), {
+          component: element,
+        });
+
+        const app = document.querySelector('ion-app');
+        app.appendChild(modalElement);
+        return modalElement;
+      };
+    </script>
+  </body>
+</html>

core/src/components/input/input.tsx

@@ -92,6 +92,11 @@ export class Input implements ComponentInterface {
    */
   @Prop() clearInput = false;
 
+  /**
+   * The icon to use for the clear button. Only applies when `clearInput` is set to `true`.
+   */
+  @Prop() clearInputIcon?: string;
+
   /**
    * If `true`, the value will be cleared after focus upon edit. Defaults to `true` when `type` is `"password"`, `false` for all other types.
    */
@@ -681,11 +686,13 @@ export class Input implements ComponentInterface {
   }
 
   render() {
-    const { disabled, fill, readonly, shape, inputId, labelPlacement, el, hasFocus } = this;
+    const { disabled, fill, readonly, shape, inputId, labelPlacement, el, hasFocus, clearInputIcon } = this;
     const mode = getIonMode(this);
     const value = this.getValue();
     const inItem = hostContext('ion-item', this.el);
     const shouldRenderHighlight = mode === 'md' && fill !== 'outline' && !inItem;
+    const defaultClearIcon = mode === 'ios' ? closeCircle : closeSharp;
+    const clearIconData = clearInputIcon ?? defaultClearIcon;
 
     const hasValue = this.hasValue();
     const hasStartEndSlots = el.querySelector('[slot="start"], [slot="end"]') !== null;
@@ -784,7 +791,7 @@ export class Input implements ComponentInterface {
                 }}
                 onClick={this.clearTextInput}
               >
-                <ion-icon aria-hidden="true" icon={mode === 'ios' ? closeCircle : closeSharp}></ion-icon>
+                <ion-icon aria-hidden="true" icon={clearIconData}></ion-icon>
               </button>
             )}
             <slot name="end"></slot>

core/src/components/input/test/input.spec.ts

@@ -99,3 +99,19 @@ describe('input: label rendering', () => {
     expect(labelText.textContent).toBe('Label Prop Text');
   });
 });
+
+// https://github.com/ionic-team/ionic-framework/issues/26974
+describe('input: clear icon', () => {
+  it('should render custom icon', async () => {
+    const page = await newSpecPage({
+      components: [Input],
+      html: `
+        <ion-input clear-input-icon="foo" clear-input="true"></ion-input>
+      `,
+    });
+
+    const icon = page.body.querySelector<HTMLIonIconElement>('ion-input ion-icon')!;
+
+    expect(icon.getAttribute('icon')).toBe('foo');
+  });
+});

core/src/components/modal/gestures/sheet.ts

@@ -1,5 +1,6 @@
 import { createGesture } from '@utils/gesture';
 import { clamp, raf } from '@utils/helpers';
+import { FOCUS_TRAP_DISABLE_CLASS } from '@utils/overlays';
 
 import type { Animation } from '../../../interface';
 import type { GestureDetail } from '../../../utils/gesture';
@@ -91,7 +92,7 @@ export const createSheetGesture = (
      * as inputs should not be focusable outside
      * the sheet.
      */
-    baseEl.classList.remove('ion-disable-focus-trap');
+    baseEl.classList.remove(FOCUS_TRAP_DISABLE_CLASS);
   };
 
   const disableBackdrop = () => {
@@ -105,7 +106,7 @@ export const createSheetGesture = (
      * Adding this class disables focus trapping
      * for the sheet temporarily.
      */
-    baseEl.classList.add('ion-disable-focus-trap');
+    baseEl.classList.add(FOCUS_TRAP_DISABLE_CLASS);
   };
 
   /**

core/src/components/modal/modal.tsx

@@ -16,6 +16,7 @@ import {
   present,
   createTriggerController,
   setOverlayId,
+  FOCUS_TRAP_DISABLE_CLASS,
 } from '@utils/overlays';
 import { getClassMap } from '@utils/theme';
 import { deepReady, waitForMount } from '@utils/transition';
@@ -257,6 +258,25 @@ export class Modal implements ComponentInterface, OverlayInterface {
    */
   @Prop() keepContentsMounted = false;
 
+  /**
+   * If `true`, focus will not be allowed to move outside of this overlay.
+   * If 'false', focus will be allowed to move outside of the overlay.
+   *
+   * In most scenarios this property should remain set to `true`. Setting
+   * this property to `false` can cause severe accessibility issues as users
+   * relying on assistive technologies may be able to move focus into
+   * a confusing state. We recommend only setting this to `false` when
+   * absolutely necessary.
+   *
+   * Developers may want to consider disabling focus trapping if this
+   * overlay presents a non-Ionic overlay from a 3rd party library.
+   * Developers would disable focus trapping on the Ionic overlay
+   * when presenting the 3rd party overlay and then re-enable
+   * focus trapping when dismissing the 3rd party overlay and moving
+   * focus back to the Ionic overlay.
+   */
+  @Prop() focusTrap = true;
+
   /**
    * Determines whether or not a modal can dismiss
    * when calling the `dismiss` method.
@@ -905,7 +925,8 @@ export class Modal implements ComponentInterface, OverlayInterface {
   };
 
   render() {
-    const { handle, isSheetModal, presentingElement, htmlAttributes, handleBehavior, inheritedAttributes } = this;
+    const { handle, isSheetModal, presentingElement, htmlAttributes, handleBehavior, inheritedAttributes, focusTrap } =
+      this;
 
     const showHandle = handle !== false && isSheetModal;
     const mode = getIonMode(this);
@@ -926,6 +947,7 @@ export class Modal implements ComponentInterface, OverlayInterface {
           [`modal-card`]: isCardModal,
           [`modal-sheet`]: isSheetModal,
           'overlay-hidden': true,
+          [FOCUS_TRAP_DISABLE_CLASS]: focusTrap === false,
           ...getClassMap(this.cssClass),
         }}
         onIonBackdropTap={this.onBackdropTap}

core/src/components/modal/test/basic/modal.spec.tsx

@@ -2,6 +2,7 @@ import { h } from '@stencil/core';
 import { newSpecPage } from '@stencil/core/testing';
 
 import { Modal } from '../../modal';
+import { FOCUS_TRAP_DISABLE_CLASS } from '@utils/overlays';
 
 describe('modal: htmlAttributes inheritance', () => {
   it('should correctly inherit attributes on host', async () => {
@@ -15,3 +16,26 @@ describe('modal: htmlAttributes inheritance', () => {
     await expect(modal.getAttribute('data-testid')).toBe('basic-modal');
   });
 });
+
+describe('modal: focus trap', () => {
+  it('should set the focus trap class when disabled', async () => {
+    const page = await newSpecPage({
+      components: [Modal],
+      template: () => <ion-modal focusTrap={false} overlayIndex={1}></ion-modal>,
+    });
+
+    const modal = page.body.querySelector('ion-modal')!;
+
+    expect(modal.classList.contains(FOCUS_TRAP_DISABLE_CLASS)).toBe(true);
+  });
+  it('should not set the focus trap class by default', async () => {
+    const page = await newSpecPage({
+      components: [Modal],
+      template: () => <ion-modal overlayIndex={1}></ion-modal>,
+    });
+
+    const modal = page.body.querySelector('ion-modal')!;
+
+    expect(modal.classList.contains(FOCUS_TRAP_DISABLE_CLASS)).toBe(false);
+  });
+});

core/src/components/popover/popover.tsx

@@ -5,7 +5,15 @@ import { CoreDelegate, attachComponent, detachComponent } from '@utils/framework
 import { addEventListener, raf, hasLazyBuild } from '@utils/helpers';
 import { createLockController } from '@utils/lock-controller';
 import { printIonWarning } from '@utils/logging';
-import { BACKDROP, dismiss, eventMethod, prepareOverlay, present, setOverlayId } from '@utils/overlays';
+import {
+  BACKDROP,
+  dismiss,
+  eventMethod,
+  prepareOverlay,
+  present,
+  setOverlayId,
+  FOCUS_TRAP_DISABLE_CLASS,
+} from '@utils/overlays';
 import { isPlatform } from '@utils/platform';
 import { getClassMap } from '@utils/theme';
 import { deepReady, waitForMount } from '@utils/transition';
@@ -236,6 +244,25 @@ export class Popover implements ComponentInterface, PopoverInterface {
    */
   @Prop() keyboardEvents = false;
 
+  /**
+   * If `true`, focus will not be allowed to move outside of this overlay.
+   * If 'false', focus will be allowed to move outside of the overlay.
+   *
+   * In most scenarios this property should remain set to `true`. Setting
+   * this property to `false` can cause severe accessibility issues as users
+   * relying on assistive technologies may be able to move focus into
+   * a confusing state. We recommend only setting this to `false` when
+   * absolutely necessary.
+   *
+   * Developers may want to consider disabling focus trapping if this
+   * overlay presents a non-Ionic overlay from a 3rd party library.
+   * Developers would disable focus trapping on the Ionic overlay
+   * when presenting the 3rd party overlay and then re-enable
+   * focus trapping when dismissing the 3rd party overlay and moving
+   * focus back to the Ionic overlay.
+   */
+  @Prop() focusTrap = true;
+
   @Watch('trigger')
   @Watch('triggerAction')
   onTriggerChange() {
@@ -656,7 +683,7 @@ export class Popover implements ComponentInterface, PopoverInterface {
 
   render() {
     const mode = getIonMode(this);
-    const { onLifecycle, parentPopover, dismissOnSelect, side, arrow, htmlAttributes } = this;
+    const { onLifecycle, parentPopover, dismissOnSelect, side, arrow, htmlAttributes, focusTrap } = this;
     const desktop = isPlatform('desktop');
     const enableArrow = arrow && !parentPopover;
 
@@ -676,6 +703,7 @@ export class Popover implements ComponentInterface, PopoverInterface {
           'overlay-hidden': true,
           'popover-desktop': desktop,
           [`popover-side-${side}`]: true,
+          [FOCUS_TRAP_DISABLE_CLASS]: focusTrap === false,
           'popover-nested': !!parentPopover,
         }}
         onIonPopoverDidPresent={onLifecycle}

core/src/components/popover/test/basic/popover.spec.tsx

@@ -3,6 +3,8 @@ import { newSpecPage } from '@stencil/core/testing';
 
 import { Popover } from '../../popover';
 
+import { FOCUS_TRAP_DISABLE_CLASS } from '@utils/overlays';
+
 describe('popover: htmlAttributes inheritance', () => {
   it('should correctly inherit attributes on host', async () => {
     const page = await newSpecPage({
@@ -15,3 +17,26 @@ describe('popover: htmlAttributes inheritance', () => {
     await expect(popover.getAttribute('data-testid')).toBe('basic-popover');
   });
 });
+
+describe('popover: focus trap', () => {
+  it('should set the focus trap class when disabled', async () => {
+    const page = await newSpecPage({
+      components: [Popover],
+      template: () => <ion-popover focusTrap={false} overlayIndex={1}></ion-popover>,
+    });
+
+    const popover = page.body.querySelector('ion-popover')!;
+
+    expect(popover.classList.contains(FOCUS_TRAP_DISABLE_CLASS)).toBe(true);
+  });
+  it('should not set the focus trap class by default', async () => {
+    const page = await newSpecPage({
+      components: [Popover],
+      template: () => <ion-popover overlayIndex={1}></ion-popover>,
+    });
+
+    const popover = page.body.querySelector('ion-popover')!;
+
+    expect(popover.classList.contains(FOCUS_TRAP_DISABLE_CLASS)).toBe(false);
+  });
+});

core/src/utils/overlays.ts

@@ -199,7 +199,7 @@ const trapKeyboardFocus = (ev: Event, doc: Document) => {
    * behind the sheet should be focusable until
    * the backdrop is enabled.
    */
-  if (lastOverlay.classList.contains('ion-disable-focus-trap')) {
+  if (lastOverlay.classList.contains(FOCUS_TRAP_DISABLE_CLASS)) {
     return;
   }
 
@@ -990,3 +990,5 @@ const revealOverlaysToScreenReaders = () => {
     }
   }
 };
+
+export const FOCUS_TRAP_DISABLE_CLASS = 'ion-disable-focus-trap';

core/src/utils/test/playwright/docs/README.md

@@ -1,11 +1,3 @@
 # Ionic E2E Tests Guide
 
-This directory contains information on how to get the most out of Ionic's E2E test infrastructure when writing tests.
-
-## Directory
-
-| Directory | Description |
-| - | - |
-| [Usage Instructions](./usage-instructions.md) | How to run tests and update screenshots |
-| [Best Practices](./best-practices.md) | Contains information on conventions to follow as well as pitfalls to avoid when writing tests |
-| [API](./api.md) | Documents the custom functionality that has been built on top of Playwright |
+Refer to the [Core Testing documentation](/docs/core/testing/README.md) in order to build and run the e2e tests.

docs/CONTRIBUTING.md

@@ -1,10 +1,11 @@
 # Contributing
 
-Thanks for your interest in contributing to the Ionic Framework! :tada:
+Thanks for your interest in contributing to the Ionic Framework! 🎉
 
 - [Contributing Etiquette](#contributing-etiquette)
 - [Creating an Issue](#creating-an-issue)
   * [Creating a Good Code Reproduction](#creating-a-good-code-reproduction)
+- [Using VS Code on Windows](#using-vs-code-on-windows)
 - [Creating a Pull Request](#creating-a-pull-request)
   * [Requirements](#requirements)
   * [Setup](#setup)
@@ -81,6 +82,19 @@ Without a reliable code reproduction, it is unlikely we will be able to resolve
 * **No secret code needed:** Creating a minimal reproduction of the issue prevents you from having to publish any proprietary code used in your project.
 * **Get help fixing the issue:** If we can reliably reproduce an issue, there is a good chance we will be able to address it.
 
+## Using VS Code on Windows
+
+To contribute on Windows, do the following:
+
+- Configure VS Code to read/save files using line breaks (LF) instead of carriage returns (CRLF). Set it globally by navigating to: Settings -> Text Editor -> Files -> Eol. Set to `\n`.
+
+  - You can optionally use the following settings in your `.vscode/settings.json`:
+    ```json
+    { "files.eol": "\n" }
+    ```
+
+- Check that the Git setting `core.autocrlf` is set to `false`: run `git config -l | grep autocrlf`. Switch it to false using: `git config --global core.autocrlf false`.
+- If you've already cloned the `ionic-framework` repo, the files may already be cached as LF. To undo this, you need to clean the cache files of the repository. Run the following (make sure you stage or commit your changes first): `git rm --cached -r .` then `git reset --hard`.
 
 ## Creating a Pull Request
 
@@ -246,6 +260,14 @@ npm install file:/~/ionic-vue-router-7.0.1.tgz
 
 #### Lint Changes
 
+> [!IMPORTANT]
+> If you are using a Windows machine, you will need to configure your local development environment to use the correct line endings.
+> - Check that the Git setting `core.autocrlf` is set to `false`: run `git config -l | grep autocrlf`. Switch it to false using: `git config --global core.autocrlf false`.
+> - If you've already cloned the `ionic-docs` repo, the files may already be cached as LF. To undo this, you need to clean the cache files of the repository. Run the following (make sure you stage or commit your changes first): `git rm --cached -r .` then `git reset --hard`.
+
+
+
+
 1. Run `npm run lint` to lint the TypeScript and Sass.
 2. If there are lint errors, run `npm run lint.fix` to automatically fix any errors. Repeat step 1 to ensure the errors have been fixed, and manually fix them if not.
 3. To lint and fix only TypeScript errors, run `npm run lint.ts` and `npm run lint.ts.fix`, respectively.

docs/README.md

@@ -0,0 +1,36 @@
+<p align="center">
+  <img alt="Ionic Logo" src="https://github.com/ionic-team/ionic-framework/blob/main/.github/assets/logo.png?raw=true" width="60" />
+</p>
+
+<h1 align="center">
+  Ionic Framework Developer Resources
+</h1>
+
+<p align="center">
+  This documentation includes guidelines on contributing, coding conventions, best practices, testing steps, and more. It should serve as a collective resource for all documentation related to developing Ionic Framework.
+</p>
+
+## What is Ionic Framework?
+
+Ionic Framework is an open source app development toolkit for building modern, fast, top-quality cross-platform native and Progressive Web Apps from a single codebase with JavaScript and the Web.
+
+It is based on <a href="https://www.webcomponents.org/introduction">Web Components</a>, which enables significant performance, usability, and feature improvements alongside support for popular web frameworks like <a href="https://angular.io/">Angular</a>, <a href="https://reactjs.com/">React</a>, and <a href="https://vuejs.org/">Vue</a>.
+
+## Guides
+
+| Guide                                   | Description                                                                              |
+| ----------------------------------------| ---------------------------------------------------------------------------------------- |
+| [Contributing](./CONTRIBUTING.md)       | How to contribute including creating pull requests, commit message guidelines, and more. |
+| [Component Guide](./component-guide.md) | Guidelines for implementing component states, accessibility, and more.                   |
+| [Sass Guidelines](./sass-guidelines.md) | Outlines scenarios where Sass members and comments should be used.                       |
+
+## Packages
+
+| Project          | Package                                                                    | Documentation                    | Guides                                                            |
+| ---------------- | -------------------------------------------------------------------------- | ---------------------------------| ----------------------------------------------------------------- |
+| **Core**         | [`@ionic/core`](https://www.npmjs.com/package/@ionic/core)                 | [Readme](core/README.md)         | [Testing](core/testing/README.md)                                 |
+| **Angular**      | [`@ionic/angular`](https://www.npmjs.com/package/@ionic/angular)           | [Readme](angular/README.md)      | [Testing](angular/testing.md)                                     |
+| **React**        | [`@ionic/react`](https://www.npmjs.com/package/@ionic/react)               | [Readme](react/README.md)        | [Testing](react/testing.md)                                       |
+| **React Router** | [`@ionic/react-router`](https://www.npmjs.com/package/@ionic/react-router) | [Readme](react-router/README.md) | [Testing](react-router/testing.md)                                |
+| **Vue**          | [`@ionic/vue`](https://www.npmjs.com/package/@ionic/vue)                   | [Readme](vue/README.md)          | [Testing](vue/testing.md)                                         |
+| **Vue Router**   | [`@ionic/vue-router`](https://www.npmjs.com/package/@ionic/vue-router)     | [Readme](vue-router/README.md)   | [Testing](vue-router/testing.md)                                  |

docs/_config.yml

@@ -0,0 +1,2 @@
+name: Ionic Framework
+include: [ CONTRIBUTING.md ]

docs/angular/README.md

@@ -0,0 +1,11 @@
+# Ionic Angular
+
+The [@ionic/angular](https://www.npmjs.com/package/@ionic/angular) package builds on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components.
+
+## Contributing
+
+See our [Contributing Guide](/docs/CONTRIBUTING.md).
+
+## Testing
+
+Refer to the [Angular Testing documentation](./testing.md) for testing the Angular package.

docs/angular/testing.md

@@ -0,0 +1,118 @@
+# Angular Testing
+
+Ionic Framework supports multiple versions of Angular. As a result, we need to verify that Ionic works correctly with each of these Angular versions.
+
+## Syncing Local Changes
+
+The Angular test app supports syncing your locally built changes for validation.
+
+1. Build the `core` and `packages/angular` directories using `npm run build`.
+2. [Build the Angular test app](#test-app-build-structure).
+3. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng14`).
+4. Install dependencies using `npm install`.
+5. Sync your local changes using `npm run sync`.
+
+From here you can either build the application or start a local dev server. When re-syncing changes, you will need to [wipe or disable the application cache](#application-cache).
+
+## Application Cache
+
+Angular CLI creates a cache of several files on disk by default in the `.angular` directory. This decreases the time taken to build the test application. However, the cache makes it difficult to quickly sync and check local changes of Ionic. As a result, the `.angular` cache is disabled by default in the test app projects.
+
+See https://angular.io/cli/cache for more information.
+
+### Disable Cache
+
+```shell
+ng cache disable
+```
+
+> [!NOTE]
+> You may need to manually remove the `.angular` directory once after running this command.
+
+### Enable Cache
+
+```shell
+ng cache enable
+```
+
+> [!NOTE]
+> You will need to delete the `.angular` cache and restart the dev server every time you want to sync local changes of Ionic.
+
+## Test App Build Structure
+
+> [!NOTE]
+> Please confirm your current directory as `packages/angular/test` before proceeding with any of the following commands.
+
+Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
+
+**apps** - This directory contains partial applications for each version of Angular we want to test. Typically these directories contain new `package.json` files, `angular.json` files, and more. If you have code that is specific to a particular version of Angular, put it in this directory.
+
+**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
+
+**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
+
+**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
+
+Usage:
+
+```shell
+# Build a test app using apps/ng14 as a reference
+./build.sh ng14
+```
+
+## How to modify test apps
+
+To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
+
+If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.spec.ts` in `apps/ng14`, make sure you place the file in `apps/ng14/e2e/src/test.spec.ts`.
+
+### Version-specific tests
+
+If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
+
+### Testing Lazy Loaded Ionic Components
+
+Tests for lazy loaded Ionic UI components should only be added under the `/lazy` route. This ensures the `IonicModule` is added.
+
+### Testing Standalone Ionic Components
+
+Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation.
+
+## Adding New Test Apps
+
+As we add support for new versions of Angular, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
+
+1. Navigate to the built app for the most recent version of Angular that Ionic tests.
+2. Update the application by following the steps on https://update.angular.io/.
+3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, `angular.json`, etc).
+4. Copy the changed files to a new directory in `apps`.
+5. Add a new entry to the matrix for `test-core-angular` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
+6. Commit these changes and push.
+
+Example:
+
+In this example, we are going to add the Angular 14 test app.
+
+1. Build the Angular 13 test app using `./build.sh ng13`.
+2. Navigate to `build/ng13`.
+3. Perform the upgrade steps on https://update.angular.io/. The "From" field should say "13.0" and the "To" field should say "14.0".
+
+Note: You may encounter some other peer dependency issues not covered by the Angular Upgrade Guide. These peer dependency issues can be resolved manually by updating the installed version of each dependency.
+
+4. Observe that the output of the Angular upgrade indicates that the following files were modified:
+
+`angular.json`
+`package-lock.json`
+`package.json`
+`tsconfig.json`
+`src/app/form/form.component.ts`
+`src/app/modal-example/modal-example.component.ts`
+
+5. Create a directory in `apps` named `ng14`.
+6. Copy the modified files to the `apps/ng14` directory.
+7. Open `./github/workflows/build.yml` and find the `test-angular-e2e` job.
+8. Find the `apps` field under `matrix`.
+9. Add "ng14" to the `apps` field.
+10. Open `./github/workflows/stencil-nightly.yml` and find the `test-angular-e2e` job.
+11. Repeat steps 8 and 9.
+12. Commit these changes and push.

docs/component-guide.md

@@ -728,7 +728,7 @@ To work around this, you should set an RTL class on the host of your component a
 <Host
 class={{
   'my-cmp-rtl': document.dir === 'rtl'
-})
+}}
 >
  ...
 </Host>

docs/core/README.md

@@ -0,0 +1,11 @@
+# Ionic Core
+
+The [@ionic/core](https://www.npmjs.com/package/@ionic/core) package contains the Web Components that make up the reusable UI building blocks of Ionic Framework. These components are designed to be used in traditional frontend view libraries/frameworks (such as React, Angular, or Vue), or on their own through traditional JavaScript in the browser.
+
+## Contributing
+
+See our [Contributing Guide](/docs/CONTRIBUTING.md).
+
+## Testing
+
+Refer to the [Core Testing documentation](./testing/README.md) for testing the Core package.

docs/core/testing/README.md

@@ -0,0 +1,13 @@
+
+# Core Testing
+
+## Directory
+
+| Directory                                     | Description                                                                                   |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| [Preview Changes](./preview-changes.md)       | Steps on building core and previewing changes                                                 |
+| [Usage Instructions](./usage-instructions.md) | How to run tests and update screenshots                                                       |
+| [Best Practices](./best-practices.md)         | Contains information on conventions to follow as well as pitfalls to avoid when writing tests |
+| [API](./api.md)                               | Documents the custom functionality that has been built on top of Playwright                   |
+
+

docs/core/testing/preview-changes.md

@@ -0,0 +1,29 @@
+# Preview Changes
+
+## Build
+
+### 1. Clone ionic
+
+    git clone https://github.com/ionic-team/ionic-framework.git
+    cd ionic-framework
+
+### 2. Run `npm install`
+
+    cd core
+    npm install
+
+Notice that `@ionic/core` lives in `core`.
+
+### 3. Run `npm start`
+
+Make sure you are inside the `core` directory.
+
+    npm start
+
+With the `start` command, Ionic components will be built with [Stencil](https://stenciljs.com/), changes to source files are watched, a local http server will startup, and [http://localhost:3333/](http://localhost:3333/) will open in a browser.
+
+### 4. Preview
+
+Navigate to [http://localhost:3333/src/components/](http://localhost:3333/src/components/). Each component has small e2e apps found in the `test` directory, for example: [http://localhost:3333/src/components/button/test/basic](http://localhost:3333/src/components/button/test/basic)
+
+As changes are made in an editor to source files, the e2e app will live-reload.

docs/react-router/README.md

@@ -0,0 +1,11 @@
+# Ionic React Router
+
+The [@ionic/react-router](https://www.npmjs.com/package/@ionic/react-router) package is the routing integration for [@ionic/react](https://www.npmjs.com/package/@ionic/react). It uses the [React Router](https://github.com/remix-run/react-router) library beneath the surface.
+
+## Contributing
+
+See our [Contributing Guide](/docs/CONTRIBUTING.md).
+
+## Testing
+
+Refer to the [React Router Testing documentation](./testing.md) for testing the React Router package.

docs/react-router/testing.md

@@ -0,0 +1,55 @@
+# React Router Testing
+
+Ionic Framework supports multiple versions of React Router. As a result, we need to verify that Ionic works correctly with each of these React Router versions.
+
+## Syncing Local Changes
+
+The React test app supports syncing your locally built changes for validation.
+
+1. Build the `@ionic/core`, `@ionic/react`, and `@ionic/react-router` projects using `npm run build`.
+2. [Build the React test app](#test-app-build-structure).
+3. Navigate to the built test app.
+4. Install dependencies using `npm install`.
+5. Sync your local changes using `npm run sync`.
+
+From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build.
+
+## Test App Build Structure
+
+Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
+
+**apps** - This directory contains partial applications for each version of React we want to test. Typically these directories contain new `package.json` files, `cypress.config.ts` files, and more. If you have code that is specific to a particular version of React, put it in this directory.
+
+**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
+
+**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
+
+**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
+
+Usage:
+
+```shell
+# Build a test app using apps/reactrouter5 as a reference
+./build.sh reactrouter5
+```
+
+## How to modify test apps
+
+To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
+
+If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/reactrouter5`, make sure you place the file in `apps/react17/tests/e2e/test.e2e.ts`.
+
+### Version-specific tests
+
+If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
+
+## Adding New Test Apps
+
+As we add support for new versions of React Router, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
+
+1. Navigate to the built app for the most recent version of React Router that Ionic tests.
+2. Update the application to the latest version of React Router.
+3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc).
+4. Copy the changed files to a new directory in `apps`.
+5. Add a new entry to the matrix for `test-react-router-e2e` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
+6. Commit these changes and push.

docs/react/README.md

@@ -0,0 +1,11 @@
+# Ionic React
+
+The [@ionic/react](https://www.npmjs.com/package/@ionic/react) package builds on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components.
+
+## Contributing
+
+See our [Contributing Guide](/docs/CONTRIBUTING.md).
+
+## Testing
+
+Refer to the [React Testing documentation](./testing.md) for testing the React package.

docs/react/testing.md

@@ -0,0 +1,55 @@
+# React Testing
+
+Ionic Framework supports multiple versions of React. As a result, we need to verify that Ionic works correctly with each of these React versions.
+
+## Syncing Local Changes
+
+The React test app supports syncing your locally built changes for validation.
+
+1. Build the `core`, `packages/react`, and `packages/react-router` directories using `npm run build`.
+2. [Build the React test app](#test-app-build-structure).
+3. Navigate to the built test app.
+4. Install dependencies using `npm install`.
+5. Sync your local changes using `npm run sync`.
+
+From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build.
+
+## Test App Build Structure
+
+Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
+
+**apps** - This directory contains partial applications for each version of React we want to test. Typically these directories contain new `package.json` files, `cypress.config.ts` files, and more. If you have code that is specific to a particular version of React, put it in this directory.
+
+**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
+
+**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
+
+**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
+
+Usage:
+
+```shell
+# Build a test app using apps/react17 as a reference
+./build.sh react17
+```
+
+## How to modify test apps
+
+To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
+
+If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/react17`, make sure you place the file in `apps/react17/tests/e2e/test.e2e.ts`.
+
+### Version-specific tests
+
+If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
+
+## Adding New Test Apps
+
+As we add support for new versions of React, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
+
+1. Navigate to the built app for the most recent version of React that Ionic tests.
+2. Update the application to the latest version of React.
+3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc).
+4. Copy the changed files to a new directory in `apps`.
+5. Add a new entry to the matrix for `test-react-e2e` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
+6. Commit these changes and push.

docs/sass-guidelines.md

@@ -0,0 +1,685 @@
+# Sass Guidelines
+
+- [Definitions](#definitions)
+- [Scope](#scope)
+- [Historical Usage](#historical-usage)
+- [Current Usage](#current-usage)
+- [Recommended Usage](#recommended-usage)
+  * [Comments](#comments)
+  * [Variables](#variables)
+    + [✅ Global](#-global)
+    + [✅ Theming](#-theming)
+    + [✅ Reusable values](#-reusable-values)
+    + [✅ Media queries](#-media-queries)
+    + [✅ Dynamic calculations](#-dynamic-calculations)
+    + [🚫 Consistency](#-consistency)
+    + [🚫 Text Alignment](#-text-alignment)
+    + [🚫 Structural Changes](#-structural-changes)
+    + [🚫 Font Properties](#-font-properties)
+
+## Definitions
+
+**Sass:** An extension to CSS that reduces the repetition in CSS and allows developers to use shared functions, mixins and variables. [^1]
+
+**Members:** Refers to variables, functions and mixins in Sass.
+
+## Scope
+
+Sass provides members that make it easier to reuse code throughout the Ionic Framework repository. Variables hold values that can be used by other stylesheets. Mixins define reusable blocks of styles that can be included in other selectors. Functions allow the manipulation of values and can perform calculations.
+
+The purpose of this document is to identify the scenarios in which Sass variables should be used.
+
+## Historical Usage
+
+In Ionic Framework v1 through v3, the project was built with Sass variables that developers could change at runtime. While the default values were provided by Ionic Framework, anyone developing with it could override these values to rebuild the Ionic Framework CSS with their own values. [^2]
+
+Due to this, Ionic Framework documented the Sass variables as part of the public API using `@prop` comments as early as [v2.0.0](https://github.com/ionic-team/ionic-framework/blob/v2.0.0/src/components/alert/alert.ios.scss):
+
+```scss
+// alert.ios.scss
+
+/// @prop - Max width of the alert
+$alert-ios-max-width:                           270px !default;
+
+/// @prop - Border radius of the alert
+$alert-ios-border-radius:                       13px !default;
+```
+
+If a Sass variable was deprecated or hidden from the public API, the `@prop` comment would be removed, or it would never be added, as seen in [v3.9.2](https://github.com/ionic-team/ionic-framework/blob/v3.9.2/src/components/alert/alert.ios.scss#L18-L19):
+
+```scss
+// alert.ios.scss
+
+// deprecated
+$alert-ios-head-padding:                        null !default;
+```
+
+To ensure proper documentation of variables for customizing Ionic Framework, Sass variables were added for components even if they were not used multiple times within the same component or elsewhere:
+
+```scss
+// alert.ios.scss
+
+/// @prop - Text color of the label for the checked radio alert
+$alert-ios-radio-label-text-color-checked:      $alert-ios-button-text-color !default;
+
+.alert-ios [aria-checked=true] .alert-radio-label {
+  color: $alert-ios-radio-label-text-color-checked;
+}
+```
+
+## Current Usage
+
+The abundance of Sass variables currently in Ionic Framework is a result of their historical usage, being used to rebuild the CSS and customize Ionic Framework components.
+
+The comments for Sass variables are also still visible today in [v7.7.0](https://github.com/ionic-team/ionic-framework/blob/v7.7.0/core/src/components/alert/alert.ios.vars.scss), even though they are no longer used by any documentation generators:
+
+```scss
+// alert.ios.vars.scss
+
+/// @prop - Max width of the alert
+$alert-ios-max-width:                                   dynamic-font-clamp(1, 270px, 1.2) !default;
+
+/// @prop - Border radius of the alert
+$alert-ios-border-radius:                               13px !default;
+```
+
+These comments aren't necessary when the naming describes its use thoroughly. The comments for the variables above do not need to be there, as it is fairly obvious what they are used for.
+
+However, the comment for the following variable might be helpful in explaining where it is used because on first glance it reads like it could be used for a sub title inside of a title:
+
+```scss
+// action-sheet.ios.vars.scss
+
+/// @prop - Font weight of the action sheet title when it has a sub title
+$action-sheet-ios-title-with-sub-title-font-weight:               600 !default;
+```
+
+It could be argued though that the comment doesn't really help, as seeing the variable in use will explain its purpose the best. Additionally, this is an example of a variable that isn't necessary, given it is only used in one place, which is why it is so specific in the first place.
+
+## Recommended Usage
+
+There are two things that need to be outlined here: when we should use comments and when we should use variables. The sections below detail the recommended usage for each of these.
+
+### Comments
+
+We should update the comments for Sass variables in one of the following ways:
+
+1. If we don't intend to ever publicly document the Sass variables again, we should update the comments to remove the syntax that was added for documentation generation:
+    ```diff
+    // alert.ios.vars.scss
+
+    -/// @prop - Border radius of the alert
+    +// Border radius of the alert
+    $alert-ios-border-radius:                               13px !default;
+    ```
+
+2. If we don't find the comments to be helpful, and want to stick with keeping the variable names specific, we should remove the comments entirely:
+    ```diff
+    // alert.ios.vars.scss
+
+    -/// @prop - Border radius of the alert
+    $alert-ios-border-radius:                               13px !default;
+    ```
+
+3. If we find the comments to be helpful for certain variables or situations, like when there are math calculations involved, we should keep only the comments that are necessary to explain what is going on:
+    ```diff
+    -/// @prop - Height of the alert button
+    /**
+    * We want the height of the button to
+    * scale with the text so the next never runs
+    * into the edge of the button. We change the height
+    * instead of adding padding because we would need to offset
+    * the height the padding and the border. Since the border uses
+    * a hairline (<1px) width, this will cause subpixel rendering
+    * differences across browsers.
+    */
+    $alert-ios-button-height:                           dynamic-font-min(1, 44px) !default;
+    ```
+
+### Variables
+
+The table below outlines the recommended approach for when to use Sass variables. Each scenario links to a section that explains it in more detail.
+
+|    | Scenario                                                       |
+| ---| ---------------------------------------------------------------|
+| ✅ | [Global](#white_check_mark-global)                             |
+| ✅ | [Theming](#white_check_mark-theming)                           |
+| ✅ | [Reusable values](#white_check_mark-reusable-values)           |
+| ✅ | [Media queries](#white_check_mark-media-queries)               |
+| ✅ | [Dynamic calculations](#white_check_mark-dynamic-calculations) |
+| 🚫 | [Consistency](#no_entry_sign-consistency)                      |
+| 🚫 | [Text Alignment](#no_entry_sign-text-alignment)                |
+| 🚫 | [Structural Changes](#no_entry_sign-structural-changes)        |
+| 🚫 | [Font Properties](#no_entry_sign-font-properties)              |
+
+#### ✅ Global
+
+Global variables that are used in multiple places include `font-family`, `z-index`, and `opacity`. These should continue to be set in variables as they affect multiple components that use them.
+
+Example of global variables:
+
+```scss
+// ionic.globals.scss
+
+$font-family-base:              var(--ion-font-family, inherit) !default;
+
+$hairlines-width:               .55px !default;
+
+$placeholder-opacity:           0.6 !default;
+```
+
+#### ✅ Theming
+
+Storing colors and other design-related values makes it easy to update an entire theme by modifying a few variables.
+
+Example of theme variables:
+
+```scss
+// ionic.theme.default.scss
+
+$background-color-value:        #fff !default;
+$background-color-rgb-value:    255, 255, 255 !default;
+
+$text-color-value:              #000 !default;
+$text-color-rgb-value:          0, 0, 0 !default;
+
+$background-color:              var(--ion-background-color, $background-color-value) !default;
+$background-color-rgb:          var(--ion-background-color-rgb, $background-color-rgb-value) !default;
+$text-color:                    var(--ion-text-color, $text-color-value) !default;
+$text-color-rgb:                var(--ion-text-color-rgb, $text-color-rgb-value) !default;
+```
+
+```scss
+// ionic.theme.default.ios.scss
+
+$backdrop-ios-color:            var(--ion-backdrop-color, #000) !default;
+$overlay-ios-background-color:  var(--ion-overlay-background-color, var(--ion-color-step-100, #f9f9f9)) !default;
+```
+
+#### ✅ Reusable values
+
+Use variables for values that are repeated throughout stylesheets, such as spacing, `border-radius`, `font-size`, or any other value used in multiple places. A value should only be considered reusable if it is used more than once and related among the elements it is being applied to in some way. For instance, a value is not considered related if it changes a common property, such as border style. While many components use `border-style: solid`, it does not need to be stored unless these components will require updates with design changes. Currently, the border styles have consistently been set to `solid`, with the exception of `none` for a CSS reset.
+
+Example of reusable values:
+
+<table>
+<thead>
+<tr>
+<th>Do ✅</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// alert.ios.vars.scss
+
+/// @prop - Padding end of the alert head
+$alert-ios-head-padding-end:     16px !default;
+
+/// @prop - Padding start of the alert head
+$alert-ios-head-padding-start:   $alert-ios-head-padding-end !default;
+```
+
+```scss
+// alert.ios.scss
+
+.alert-head {
+  padding-top: 12px;
+  padding-inline-end: $alert-ios-head-padding-end;
+  padding-bottom: 7px;
+  padding-inline-start: $alert-ios-head-padding-start;
+}
+```
+
+</td>
+</tr>
+<tr></tr>
+<tr>
+<th>Don't :x:</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// alert.ios.vars.scss
+
+/// @prop - Padding top of the alert head
+$alert-ios-head-padding-top:     12px !default;
+
+/// @prop - Padding bottom of the alert head
+$alert-ios-head-padding-bottom:  7px !default;
+```
+
+```scss
+// alert.ios.scss
+
+.alert-head {
+  padding-top: $alert-ios-head-padding-top;
+  padding-bottom: $alert-ios-head-padding-bottom;
+}
+```
+
+</td>
+</tr>
+</table>
+
+If a value is shared among multiple components, it should be made into a [global variable](#white_check_mark-global) instead of importing the variable from a specific component. For example, variables that are shared between list components (item, item divider, list header) should be defined in a global theme file:
+
+<table>
+<thead>
+<tr>
+<th>Do ✅</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// ionic.theme.default.md.scss
+
+$global-md-item-padding-end: 16px;
+$global-md-item-padding-start: $global-md-item-padding-end;
+```
+
+```scss
+// item.md.vars.scss
+
+@import "../../themes/ionic.globals.md";
+
+/// @prop - Padding end for the item content
+$item-md-padding-end: $global-md-item-padding-end !default;
+
+/// @prop - Padding start for the item content
+$item-md-padding-start: $global-md-item-padding-start !default;
+```
+
+```scss
+// item-divider.md.vars.scss
+
+@import "../../themes/ionic.globals.md";
+
+/// @prop - Padding start for the divider
+$item-divider-md-padding-start: $global-md-item-padding-start !default;
+
+/// @prop - Padding end for the divider
+$item-divider-md-padding-end: $global-md-item-padding-end !default;
+```
+
+</td>
+</tr>
+<tr></tr>
+<tr>
+<th>Don't :x:</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// item.md.vars.scss
+
+@import "../../themes/ionic.globals.md";
+
+/// @prop - Padding end for the item content
+$item-md-padding-end:                   16px !default;
+
+/// @prop - Padding start for the item content
+$item-md-padding-start:                 16px !default;
+```
+
+```scss
+// item-divider.md.vars.scss
+
+@import "../../themes/ionic.globals.md";
+@import "../item/item.md.vars";
+
+/// @prop - Padding start for the divider
+$item-divider-md-padding-start:        $item-md-padding-start !default;
+
+/// @prop - Padding end for the divider
+$item-divider-md-padding-end:          $item-md-padding-end !default;
+```
+
+</td>
+</tr>
+</table>
+
+> [!TIP]
+> The names of the global variables are just an example. We do not currently have a naming convention for global variables.
+
+#### ✅ Media queries
+
+Define breakpoints for responsive design to allow easy adjustments as needed.
+
+Example of breakpoints used by media queries:
+
+```scss
+// ionic.globals.scss
+
+// The minimum dimensions at which your layout will change,
+// adapting to different screen sizes, for use in media queries
+$screen-breakpoints: (
+  xs: 0,
+  sm: 576px,
+  md: 768px,
+  lg: 992px,
+  xl: 1200px
+) !default;
+```
+
+#### ✅ Dynamic calculations
+
+Variables can be useful for dynamic calculations, such as storing a base font size in a variable and then using it in calculations for other font sizes or spacing values. Variables should not be used for storing a function call, even if the function itself has dynamic calculations.
+
+<table>
+<thead>
+<tr>
+<th>Do ✅</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// chip.vars.scss
+
+/// @prop - Unitless font size of the chip before scaling
+$chip-base-font-size: 14;
+
+/// @prop - Font size of the chip in rem before scaling
+$chip-base-font-size-rem: #{math.div($chip-base-font-size, 16)}rem;
+
+/// @prop - Size of an icon within a chip (in em to scale as the font size of the chip scales)
+$chip-icon-size: math.div(20em, $chip-base-font-size);
+
+/// @prop - Size of an avatar within a chip (in em to scale as the font size of the chip scales)
+$chip-avatar-size: math.div(24em, $chip-base-font-size);
+```
+
+</td>
+</tr>
+<tr></tr>
+<tr>
+<th>Don't :x:</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// alert.vars.scss
+
+/// @prop - Font size of the alert button
+$alert-button-font-size:          dynamic-font(14px) !default;
+```
+
+</td>
+</tr>
+</table>
+
+#### 🚫 Consistency
+
+While we usually aim for consistency across different modes, this isn't always necessary when dealing with Sass variables. If certain styles are present in one mode but absent in another, there's no need to include a Sass variable for the mode lacking those styles.
+
+For example, the color of the label changes when focused in `md` mode. However, in `ios`, the label does not receive different styling when focused, therefore it does not require the same styles or a Sass variable defined:
+
+<table>
+<thead>
+<tr>
+<th>Do ✅</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// label.md.vars.scss
+
+/// @prop - Text color of the stacked/floating label when it is focused
+$label-md-text-color-focused:            ion-color(primary, base) !default;
+```
+
+```scss
+// label.md.scss
+
+:host-context(.ion-focused).label-stacked:not(.ion-color),
+:host-context(.ion-focused).label-floating:not(.ion-color),
+:host-context(.item-has-focus).label-stacked:not(.ion-color),
+:host-context(.item-has-focus).label-floating:not(.ion-color) {
+  color: $label-md-text-color-focused;
+}
+```
+
+</td>
+</tr>
+<tr></tr>
+<tr>
+<th>Don't :x:</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// label.ios.vars.scss
+
+/// @prop - Text color of the stacked/floating label when it is focused
+$label-ios-text-color-focused:         null !default;
+```
+
+```scss
+// label.ios.scss
+
+:host-context(.ion-focused).label-stacked:not(.ion-color),
+:host-context(.ion-focused).label-floating:not(.ion-color),
+:host-context(.item-has-focus).label-stacked:not(.ion-color),
+:host-context(.item-has-focus).label-floating:not(.ion-color) {
+  color: $label-ios-text-color-focused;
+}
+```
+
+</td>
+</tr>
+</table>
+
+#### 🚫 Text Alignment
+
+A text alignment property should not be stored in a Sass variable, even if it is used in multiple places. This is because the alignment may be tied to a specific design, and the design may change, causing them to become disconnected.
+
+<table>
+<thead>
+<tr>
+<th>Do ✅</th>
+<th>Don't :x:</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// action-sheet.ios.scss
+
+:host {
+  text-align: center;
+}
+
+.action-sheet-title {
+  text-align: center;
+}
+```
+
+</td>
+<td valign="top">
+
+```scss
+// action-sheet.ios.vars.scss
+
+/// @prop - Text align of the action sheet
+$action-sheet-ios-text-align:        center !default;
+```
+
+```scss
+// action-sheet.ios.scss
+
+:host {
+  text-align: $action-sheet-ios-text-align;
+}
+
+.action-sheet-title {
+  text-align: $action-sheet-ios-text-align;
+}
+```
+
+</td>
+</tr>
+</table>
+
+
+#### 🚫 Structural Changes
+
+Variables should not be used when they are structural changes of an element. This includes `display` properties, `flex` properties, `grid` properties, and more.
+
+<table>
+<thead>
+<tr>
+<th>Do ✅</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// alert.ios.scss
+
+.alert-button-group {
+  flex-wrap: wrap;
+}
+
+.alert-button {
+  flex: 1 1 auto;
+}
+```
+
+</td>
+</tr>
+<tr></tr>
+<tr>
+<th>Don't :x:</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+
+```scss
+// alert.ios.vars.scss
+
+/// @prop - Flex wrap of the alert button group
+$alert-ios-button-group-flex-wrap:        wrap !default;
+
+/// @prop - Flex of the alert button
+$alert-ios-button-flex:                   1 1 auto !default;
+```
+
+```scss
+// alert.ios.scss
+
+.alert-button-group {
+  flex-wrap: $alert-ios-button-group-flex-wrap;
+}
+
+.alert-button {
+  flex: $alert-ios-button-flex;
+}
+```
+
+</td>
+</tr>
+</table>
+
+#### 🚫 Font Properties
+
+We shouldn't use variables for changing things such as `font-size` or `font-weight`, as these are not changed based on a theme and do not need to be updated globally. When updating the `font-size` and `font-weight` for these elements, it will always be done on a case-by-case basis:
+
+<table>
+<thead>
+<tr>
+<th>Do ✅</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// action-sheet.ios.scss
+
+.action-sheet-title {
+  font-size: dynamic-font-min(1, 13px);
+  font-weight: 400;
+}
+
+.action-sheet-sub-title {
+  font-size: dynamic-font-min(1, 13px);
+  font-weight: 400;
+}
+```
+
+</td>
+</tr>
+<tr></tr>
+<tr>
+<th>Don't :x:</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td valign="top">
+
+```scss
+// action-sheet.ios.vars.scss
+
+/// @prop - Font size of the action sheet title
+$action-sheet-ios-title-font-size:          dynamic-font-min(1, 13px) !default;
+
+/// @prop - Font weight of the action sheet title
+$action-sheet-ios-title-font-weight:        400 !default;
+
+/// @prop - Font size of the action sheet sub title
+$action-sheet-ios-sub-title-font-size:      dynamic-font-min(1, 13px) !default;
+```
+
+```scss
+// action-sheet.ios.scss
+
+.action-sheet-title {
+  font-size: $action-sheet-ios-title-font-size;
+  font-weight: $action-sheet-ios-title-font-weight;
+}
+
+.action-sheet-sub-title {
+  font-size: $action-sheet-ios-sub-title-font-size;
+  font-weight: $action-sheet-ios-title-font-weight;
+}
+```
+
+</td>
+</tr>
+</table>
+
+[^1]: Sass Documentation, https://sass-lang.com/documentation/
+
+[^2]: Ionic Framework v3 Documentation - Theming - Overriding Ionic Variables, https://ionicframework.com/docs/v3/theming/overriding-ionic-variables/

docs/vue-router/README.md

@@ -0,0 +1,11 @@
+# Ionic Vue Router
+
+The [@ionic/vue-router](https://www.npmjs.com/package/@ionic/vue-router) package is the routing integration for [@ionic/vue](https://www.npmjs.com/package/@ionic/vue). It uses the [Vue Router](https://router.vuejs.org/) library beneath the surface.
+
+## Contributing
+
+See our [Contributing Guide](/docs/CONTRIBUTING.md).
+
+## Testing
+
+Refer to the [Vue Router Testing documentation](./testing.md) for testing the Vue Router package.

docs/vue-router/testing.md

@@ -0,0 +1,7 @@
+# Vue Router Testing
+
+## Tests
+
+* Tests are found in the `__tests__` directory and use Jest.
+* Tests can be run using `npm run test.spec`
+* Bug fix and feature PRs should have new tests verifying the PR functionality.

docs/vue/README.md

@@ -0,0 +1,11 @@
+# Ionic Vue
+
+The [@ionic/vue](https://www.npmjs.com/package/@ionic/vue) package builds on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components.
+
+## Contributing
+
+See our [Contributing Guide](/docs/CONTRIBUTING.md).
+
+## Testing
+
+Refer to the [Vue Testing documentation](./testing.md) for testing the Vue package.

docs/vue/testing.md

@@ -0,0 +1,58 @@
+# Vue Testing
+
+Ionic Framework supports multiple versions of Vue. As a result, we need to verify that Ionic works correctly with each of these Vue versions.
+
+## Syncing Local Changes
+
+The Vue test app supports syncing your locally built changes for validation.
+
+1. [Build](../README.md#building) the `core`, `packages/vue`, and `packages/vue-router` projects using `npm run build`.
+2. [Build the Vue test app](#test-app-build-structure).
+3. Navigate to the built test app directory (e.g. `packages/vue/test/build/vue3`).
+4. Install dependencies using `npm install`.
+5. Sync your local changes using `npm run sync`.
+
+From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build.
+
+## Test App Build Structure
+
+> [!NOTE]
+> Please confirm your current directory as `packages/vue/test` before proceeding with any of the following commands.
+
+Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
+
+**apps** - This directory contains partial applications for each version of Vue we want to test. Typically these directories contain new `package.json` files, `jest.config.js` files, and more. If you have code that is specific to a particular version of Vue, put it in this directory.
+
+**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
+
+**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
+
+**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
+
+Usage:
+
+```shell
+# Build a test app using apps/vue3 as a reference
+./build.sh vue3
+```
+
+## How to modify test apps
+
+To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
+
+If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/vue3`, make sure you place the file in `apps/vue3/tests/e2e/test.e2e.ts`.
+
+### Version-specific tests
+
+If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
+
+## Adding New Test Apps
+
+As we add support for new versions of Vue, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
+
+1. Navigate to the built app for the most recent version of Vue that Ionic tests.
+2. Update the application to the latest version of Vue.
+3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc).
+4. Copy the changed files to a new directory in `apps`.
+5. Add a new entry to the matrix for `test-core-vue` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
+6. Commit these changes and push.

packages/angular/src/directives/proxies.ts

@@ -592,7 +592,7 @@ export declare interface IonCol extends Components.IonCol {}
 
 
 @ProxyCmp({
-  inputs: ['color', 'forceOverscroll', 'fullscreen', 'scrollEvents', 'scrollX', 'scrollY'],
+  inputs: ['color', 'fixedSlotPlacement', 'forceOverscroll', 'fullscreen', 'scrollEvents', 'scrollX', 'scrollY'],
   methods: ['getScrollElement', 'scrollToTop', 'scrollToBottom', 'scrollByPoint', 'scrollToPoint']
 })
 @Component({
@@ -600,7 +600,7 @@ export declare interface IonCol extends Components.IonCol {}
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['color', 'forceOverscroll', 'fullscreen', 'scrollEvents', 'scrollX', 'scrollY'],
+  inputs: ['color', 'fixedSlotPlacement', 'forceOverscroll', 'fullscreen', 'scrollEvents', 'scrollX', 'scrollY'],
 })
 export class IonContent {
   protected el: HTMLElement;
@@ -955,7 +955,7 @@ export declare interface IonInfiniteScrollContent extends Components.IonInfinite
 
 
 @ProxyCmp({
-  inputs: ['autocapitalize', 'autocomplete', 'autocorrect', 'autofocus', 'clearInput', 'clearOnEdit', 'color', 'counter', 'counterFormatter', 'debounce', 'disabled', 'enterkeyhint', 'errorText', 'fill', 'helperText', 'inputmode', 'label', 'labelPlacement', 'max', 'maxlength', 'min', 'minlength', 'mode', 'multiple', 'name', 'pattern', 'placeholder', 'readonly', 'required', 'shape', 'spellcheck', 'step', 'type', 'value'],
+  inputs: ['autocapitalize', 'autocomplete', 'autocorrect', 'autofocus', 'clearInput', 'clearInputIcon', 'clearOnEdit', 'color', 'counter', 'counterFormatter', 'debounce', 'disabled', 'enterkeyhint', 'errorText', 'fill', 'helperText', 'inputmode', 'label', 'labelPlacement', 'max', 'maxlength', 'min', 'minlength', 'mode', 'multiple', 'name', 'pattern', 'placeholder', 'readonly', 'required', 'shape', 'spellcheck', 'step', 'type', 'value'],
   methods: ['setFocus', 'getInputElement']
 })
 @Component({
@@ -963,7 +963,7 @@ export declare interface IonInfiniteScrollContent extends Components.IonInfinite
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['autocapitalize', 'autocomplete', 'autocorrect', 'autofocus', 'clearInput', 'clearOnEdit', 'color', 'counter', 'counterFormatter', 'debounce', 'disabled', 'enterkeyhint', 'errorText', 'fill', 'helperText', 'inputmode', 'label', 'labelPlacement', 'max', 'maxlength', 'min', 'minlength', 'mode', 'multiple', 'name', 'pattern', 'placeholder', 'readonly', 'required', 'shape', 'spellcheck', 'step', 'type', 'value'],
+  inputs: ['autocapitalize', 'autocomplete', 'autocorrect', 'autofocus', 'clearInput', 'clearInputIcon', 'clearOnEdit', 'color', 'counter', 'counterFormatter', 'debounce', 'disabled', 'enterkeyhint', 'errorText', 'fill', 'helperText', 'inputmode', 'label', 'labelPlacement', 'max', 'maxlength', 'min', 'minlength', 'mode', 'multiple', 'name', 'pattern', 'placeholder', 'readonly', 'required', 'shape', 'spellcheck', 'step', 'type', 'value'],
 })
 export class IonInput {
   protected el: HTMLElement;

packages/angular/standalone/src/directives/proxies.ts

@@ -659,7 +659,7 @@ export declare interface IonCol extends Components.IonCol {}
 
 @ProxyCmp({
   defineCustomElementFn: defineIonContent,
-  inputs: ['color', 'forceOverscroll', 'fullscreen', 'scrollEvents', 'scrollX', 'scrollY'],
+  inputs: ['color', 'fixedSlotPlacement', 'forceOverscroll', 'fullscreen', 'scrollEvents', 'scrollX', 'scrollY'],
   methods: ['getScrollElement', 'scrollToTop', 'scrollToBottom', 'scrollByPoint', 'scrollToPoint']
 })
 @Component({
@@ -667,7 +667,7 @@ export declare interface IonCol extends Components.IonCol {}
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['color', 'forceOverscroll', 'fullscreen', 'scrollEvents', 'scrollX', 'scrollY'],
+  inputs: ['color', 'fixedSlotPlacement', 'forceOverscroll', 'fullscreen', 'scrollEvents', 'scrollX', 'scrollY'],
   standalone: true
 })
 export class IonContent {

packages/angular/test/README.md

@@ -1,118 +1,3 @@
 # Angular E2E Test Apps
 
-Ionic Framework supports multiple versions of Angular. As a result, we need to verify that Ionic works correctly with each of these Angular versions.
-
-## Syncing Local Changes
-
-The Angular test app supports syncing your locally built changes for validation.
-
-1. Build the `core` and `packages/angular` directories using `npm run build`.
-2. [Build the Angular test app](#test-app-build-structure).
-3. Navigate to the built test app directory (e.g. `packages/angular/test/build/ng17`).
-4. Install dependencies using `npm install`.
-5. Sync your local changes using `npm run sync`.
-
-From here you can either build the application or start a local dev server. When re-syncing changes, you will need to [wipe or disable the application cache](#application-cache).
-
-## Application Cache
-
-Angular CLI creates a cache of several files on disk by default in the `.angular` directory. This decreases the time taken to build the test application. However, the cache makes it difficult to quickly sync and check local changes of Ionic. As a result, the `.angular` cache is disabled by default in the test app projects.
-
-See https://angular.io/cli/cache for more information.
-
-### Disable Cache
-
-```shell
-ng cache disable
-```
-
-> [!NOTE]
-> You may need to manually remove the `.angular` directory once after running this command.
-
-### Enable Cache
-
-```shell
-ng cache enable
-```
-
-> [!NOTE]
-> You will need to delete the `.angular` cache and restart the dev server every time you want to sync local changes of Ionic.
-
-## Test App Build Structure
-
-> [!NOTE]
-> Please confirm your current directory as `packages/angular/test` before proceeding with any of the following commands.
-
-Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
-
-**apps** - This directory contains partial applications for each version of Angular we want to test. Typically these directories contain new `package.json` files, `angular.json` files, and more. If you have code that is specific to a particular version of Angular, put it in this directory.
-
-**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
-
-**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
-
-**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
-
-Usage:
-
-```shell
-# Build a test app using apps/ng17 as a reference
-./build.sh ng17
-```
-
-## How to modify test apps
-
-To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
-
-If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.spec.ts` in `apps/ng17`, make sure you place the file in `apps/ng17/e2e/src/test.spec.ts`.
-
-### Version-specific tests
-
-If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
-
-### Testing Lazy Loaded Ionic Components
-
-Tests for lazy loaded Ionic UI components should only be added under the `/lazy` route. This ensures the `IonicModule` is added.
-
-### Testing Standalone Ionic Components
-
-Tests for standalone Ionic UI components should only be added under the `/standalone` route. This allows for an isolated environment where the lazy loaded `IonicModule` is not initialized. The standalone components use Stencil's custom element bundle instead of the lazy loaded bundle. If `IonicModule` is initialized then the Stencil components will fall back to using the lazy loaded implementation instead of the custom elements bundle implementation.
-
-## Adding New Test Apps
-
-As we add support for new versions of Angular, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
-
-1. Navigate to the built app for the most recent version of Angular that Ionic tests.
-2. Update the application by following the steps on https://update.angular.io/.
-3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, `angular.json`, etc).
-4. Copy the changed files to a new directory in `apps`.
-5. Add a new entry to the matrix for `test-core-angular` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
-6. Commit these changes and push.
-
-Example:
-
-In this example, we are going to add the Angular 14 test app.
-
-1. Build the Angular 13 test app using `./build.sh ng13`.
-2. Navigate to `build/ng13`.
-3. Perform the upgrade steps on https://update.angular.io/. The "From" field should say "13.0" and the "To" field should say "14.0".
-
-Note: You may encounter some other peer dependency issues not covered by the Angular Upgrade Guide. These peer dependency issues can be resolved manually by updating the installed version of each dependency.
-
-4. Observe that the output of the Angular upgrade indicates that the following files were modified:
-
-`angular.json`
-`package-lock.json`
-`package.json`
-`tsconfig.json`
-`src/app/form/form.component.ts`
-`src/app/modal-example/modal-example.component.ts`
-
-5. Create a directory in `apps` named `ng14`.
-6. Copy the modified files to the `apps/ng14` directory.
-7. Open `./github/workflows/build.yml` and find the `test-angular-e2e` job.
-8. Find the `apps` field under `matrix`.
-9. Add "ng14" to the `apps` field.
-10. Open `./github/workflows/stencil-nightly.yml` and find the `test-angular-e2e` job.
-11. Repeat steps 8 and 9.
-12. Commit these changes and push.
+Refer to the [Angular Testing documentation](/docs/angular/testing.md) in order to build and run the test app.

packages/react-router/README.md

@@ -1,2 +1,2 @@
-## @ionic/react-router (beta)
+# @ionic/react-router
 

packages/react-router/test/README.md

@@ -1,55 +1,3 @@
 # React Router E2E Test Apps
 
-Ionic Framework supports multiple versions of React Router. As a result, we need to verify that Ionic works correctly with each of these React Router versions.
-
-## Syncing Local Changes
-
-The React test app supports syncing your locally built changes for validation.
-
-1. Build the `@ionic/core`, `@ionic/react`, and `@ionic/react-router` projects using `npm run build`.
-2. [Build the React test app](#test-app-build-structure).
-3. Navigate to the built test app.
-4. Install dependencies using `npm install`.
-5. Sync your local changes using `npm run sync`.
-
-From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build.
-
-## Test App Build Structure
-
-Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
-
-**apps** - This directory contains partial applications for each version of React we want to test. Typically these directories contain new `package.json` files, `cypress.config.ts` files, and more. If you have code that is specific to a particular version of React, put it in this directory.
-
-**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
-
-**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
-
-**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
-
-Usage:
-
-```shell
-# Build a test app using apps/reactrouter5 as a reference
-./build.sh reactrouter5
-```
-
-## How to modify test apps
-
-To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
-
-If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/reactrouter5`, make sure you place the file in `apps/react17/tests/e2e/test.e2e.ts`.
-
-### Version-specific tests
-
-If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
-
-## Adding New Test Apps
-
-As we add support for new versions of React Router, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
-
-1. Navigate to the built app for the most recent version of React Router that Ionic tests.
-2. Update the application to the latest version of React Router.
-3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc).
-4. Copy the changed files to a new directory in `apps`.
-5. Add a new entry to the matrix for `test-react-router-e2e` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
-6. Commit these changes and push.
+Refer to the [React Router Testing documentation](/docs/react-router/testing.md) in order to build and run the test app.

packages/react/README.md

@@ -1,4 +1,4 @@
-## @ionic/react
+# @ionic/react
 
 These are React specific building blocks on top of [@ionic/core](https://www.npmjs.com/package/@ionic/core) components/services.
 

packages/react/test/README.md

@@ -1,55 +1,3 @@
 # React E2E Test Apps
 
-Ionic Framework supports multiple versions of React. As a result, we need to verify that Ionic works correctly with each of these React versions.
-
-## Syncing Local Changes
-
-The React test app supports syncing your locally built changes for validation.
-
-1. Build the `core`, `packages/react`, and `packages/react-router` directories using `npm run build`.
-2. [Build the React test app](#test-app-build-structure).
-3. Navigate to the built test app.
-4. Install dependencies using `npm install`.
-5. Sync your local changes using `npm run sync`.
-
-From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build.
-
-## Test App Build Structure
-
-Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
-
-**apps** - This directory contains partial applications for each version of React we want to test. Typically these directories contain new `package.json` files, `cypress.config.ts` files, and more. If you have code that is specific to a particular version of React, put it in this directory.
-
-**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
-
-**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
-
-**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
-
-Usage:
-
-```shell
-# Build a test app using apps/react17 as a reference
-./build.sh react17
-```
-
-## How to modify test apps
-
-To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
-
-If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/react17`, make sure you place the file in `apps/react17/tests/e2e/test.e2e.ts`.
-
-### Version-specific tests
-
-If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
-
-## Adding New Test Apps
-
-As we add support for new versions of React, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
-
-1. Navigate to the built app for the most recent version of React that Ionic tests.
-2. Update the application to the latest version of React.
-3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc).
-4. Copy the changed files to a new directory in `apps`.
-5. Add a new entry to the matrix for `test-react-e2e` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
-6. Commit these changes and push.
+Refer to the [React Testing documentation](/docs/react/testing.md) in order to build and run the test app.

packages/react/test/base/README.md

@@ -1,47 +1,3 @@
 # React Test App
 
-## Getting Started
-
-### Setup
-
-Make sure you are using the latest versions of node and npm. If you do not have these, [download the installer](https://nodejs.org/) for the LTS version of Node.js. This is the best way to also [install npm](https://blog.npmjs.org/post/85484771375/how-to-install-npm#_=_).
-
-### Building Dependencies
-
-Navigate to the `core`, `packages/react` and `packages/react-router` directories and build each of them:
-
-```bash
-npm i
-npm run build
-```
-
-Then, install dependencies from this directory for this test app:
-
-```
-npm i
-```
-
-### Syncing Changes
-
-When making changes to the React package, run the following from this directory to sync the changes:
-
-```bash
-npm run sync
-```
-
-### Previewing App
-
-To preview this app locally, run the following from this directory:
-
-```bash
-npm start
-```
-
-### Running Tests
-
-To run the e2e tests, run the following from this directory:
-
-```
-npm run build
-npm run e2e
-```
+Refer to the [React Testing documentation](/docs/react/testing.md) in order to build and run the test app.

packages/vue/src/proxies.ts

@@ -262,6 +262,7 @@ export const IonCol = /*@__PURE__*/ defineContainer<JSX.IonCol>('ion-col', defin
 export const IonContent = /*@__PURE__*/ defineContainer<JSX.IonContent>('ion-content', defineIonContent, [
   'color',
   'fullscreen',
+  'fixedSlotPlacement',
   'forceOverscroll',
   'scrollX',
   'scrollY',
@@ -402,6 +403,7 @@ export const IonInput = /*@__PURE__*/ defineContainer<JSX.IonInput, JSX.IonInput
   'autocorrect',
   'autofocus',
   'clearInput',
+  'clearInputIcon',
   'clearOnEdit',
   'counter',
   'counterFormatter',

packages/vue/src/vue-component-lib/utils.ts

@@ -91,17 +91,8 @@ export const defineContainer = <Props, VModelType = string | number | boolean>(
         const eventsNames = Array.isArray(modelUpdateEvent) ? modelUpdateEvent : [modelUpdateEvent];
         eventsNames.forEach((eventName: string) => {
           el.addEventListener(eventName.toLowerCase(), (e: Event) => {
-            /**
-             * Only update the v-model binding if the event's target is the element we are
-             * listening on. For example, Component A could emit ionChange, but it could also
-             * have a descendant Component B that also emits ionChange. We only want to update
-             * the v-model for Component A when ionChange originates from that element and not
-             * when ionChange bubbles up from Component B.
-             */
-            if (e.target.tagName === el.tagName) {
-              modelPropValue = (e?.target as any)[modelProp];
-              emit(UPDATE_VALUE_EVENT, modelPropValue);
-            }
+            modelPropValue = (e?.target as any)[modelProp];
+            emit(UPDATE_VALUE_EVENT, modelPropValue);
           });
         });
       },

packages/vue/test/README.md

@@ -1,58 +1,3 @@
 # Vue E2E Test Apps
 
-Ionic Framework supports multiple versions of Vue. As a result, we need to verify that Ionic works correctly with each of these Vue versions.
-
-## Syncing Local Changes
-
-The Vue test app supports syncing your locally built changes for validation.
-
-1. [Build](../README.md#building) the `core`, `packages/vue`, and `packages/vue-router` projects using `npm run build`.
-2. [Build the Vue test app](#test-app-build-structure).
-3. Navigate to the built test app directory (e.g. `packages/vue/test/build/vue3`).
-4. Install dependencies using `npm install`.
-5. Sync your local changes using `npm run sync`.
-
-From here you can either build the application or start a local dev server. When re-syncing changes, you will need to wipe the build cache in `node_modules/.cache` and restart the dev server/re-build.
-
-## Test App Build Structure
-
-> [!NOTE]
-> Please confirm your current directory as `packages/vue/test` before proceeding with any of the following commands.
-
-Unlike other test applications, these test apps are broken up into multiple directories. These directories are then combined to create a single application. This allows us to share common application code, tests, etc so that each app is being tested the same way. Below details the different pieces that help create a single test application.
-
-**apps** - This directory contains partial applications for each version of Vue we want to test. Typically these directories contain new `package.json` files, `jest.config.js` files, and more. If you have code that is specific to a particular version of Vue, put it in this directory.
-
-**base** - This directory contains the base application that each test app will use. This is where tests, application logic, and more live. If you have code that needs to be run on every test app, put it in this directory.
-
-**build** - When the `apps` and `base` directories are merged, the final result is put in this directory. The `build` directory should never be committed to git.
-
-**build.sh** - This is the script that merges the `apps` and `base` directories and places the built application in the `build` directory.
-
-Usage:
-
-```shell
-# Build a test app using apps/vue3 as a reference
-./build.sh vue3
-```
-
-## How to modify test apps
-
-To add new tests, components, or pages, modify the `base` project. This ensures that tests are run for every tested version.
-
-If you want to add a version-specific change, add the change inside of the appropriate projects in `apps`. Be sure to replicate the directory structure. For example, if you are adding a new E2E test file called `test.e2e.ts` in `apps/vue3`, make sure you place the file in `apps/vue3/tests/e2e/test.e2e.ts`.
-
-### Version-specific tests
-
-If you need to add E2E tests that are only run on a specific version of the JS Framework, replicate the `VersionTest` component on each partial application. This ensures that tests for framework version X do not get run for framework version Y.
-
-## Adding New Test Apps
-
-As we add support for new versions of Vue, we will also need to update this directory to test against new applications. The following steps can serve as a guide for adding new apps:
-
-1. Navigate to the built app for the most recent version of Vue that Ionic tests.
-2. Update the application to the latest version of Vue.
-3. Make note of any files that changed during the upgrade (`package.json`, `package-lock.json`, etc).
-4. Copy the changed files to a new directory in `apps`.
-5. Add a new entry to the matrix for `test-core-vue` in `./github/workflows/build.yml`. This will allow the new test app to run against all PRs.
-6. Commit these changes and push.
+Refer to the [Vue Testing documentation](/docs/vue/testing.md) in order to build and run the test app.