chore: merge main into major-9.0

.github/workflows/CI.yml

@@ -2,7 +2,7 @@
 # https://help.github.com/en/articles/about-github-actions
 # https://help.github.com/en/articles/workflow-syntax-for-github-actions
 
-name: Install Dependencies, Lint
+name: Validate Docs
 
 on: [pull_request]
 
@@ -13,24 +13,30 @@ jobs:
     strategy:
       matrix:
         node_version: [20]
+        # Build processes work differently across operating systems, so the 
+        # checks run on each one to make sure anyone can contribute to the
+        # docs.
         os: [windows-latest, macOS-latest]
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Use Node.js ${{ matrix.node_version }}
-      uses: actions/setup-node@v4
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+    - name: ⚙️ Use Node.js ${{ matrix.node_version }}
+      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
       with:
         node-version: ${{ matrix.node_version }}
-    - name: Install Dependencies
+    - name: 🕸️ Install Dependencies
       run: npm ci --legacy-peer-deps
-    - name: Lint
+    - name: 🖌️ Lint
       run: npm run lint
     - name: Test
       run: npm run test
-    - name: Spell Check
+    - name: 🔤 Spell Check
       run: npm run spellcheck
+    - uses: ./.github/workflows/actions/check-translations
     # Lint and spell check changes should be pushed
     # to the branch before the branch is merge eligible.
-    - name: Check Diff
+    #
+    # The translation keys check should not produce any changes.
+    - name: 🔍 Check Diff
       run: git diff --exit-code
       shell: bash

.github/workflows/actions/check-translations/action.yml

@@ -0,0 +1,20 @@
+name: 'Check Translations'
+description: 'Validates the translated locales without building them'
+runs:
+  using: 'composite'
+  steps:
+    # Surfaces failures unique to a translated locale, such as duplicate
+    # translation keys, while the changes are still in review. Previews only
+    # build the default locale, so translated locale issues would not surface
+    # until after merging into main.
+    #
+    # The sidebars reference the native and CLI docs, which are generated rather
+    # than committed, so those have to exist before the translations can be
+    # extracted.
+    - name: 🇯🇵 Extract Translations
+      shell: bash
+      run: |
+        trap 'rm -rf i18n' EXIT
+        node scripts/native.mjs
+        node scripts/cli.mjs
+        npx docusaurus write-translations --locale ja

.prettierignore

@@ -7,9 +7,17 @@ docs/api
 docs/native
 versioned_docs/version-v*/native
 docs/cli/commands
+# Each definition in these files is one line of prose inside a JSX <section>.
+# Prettier's mdx parser reflows those children and moves link text onto its own
+# line, which MDX then wraps in a paragraph, rendering invalid HTML such as
+# <a><p>Android SDK</p></a>. Formatting these files reintroduces that markup.
 docs/reference/glossary.md
 versioned_docs/version-v*/reference/glossary.md
 
+# Archived versions
+versioned_docs/version-v5
+versioned_docs/version-v6
+
 static/code/stackblitz
 
 .docusaurus

CONTRIBUTING.md

@@ -35,6 +35,42 @@ npm install
 npm start
 ```
 
+#### GitHub Token
+
+The documentation build requires a GitHub Personal Access Token to fetch Ionic Framework release notes. The build will still work locally without it (release notes will be empty), but it's required for Vercel preview and production builds.
+
+**Local Development:**
+
+1. Create a [fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new) with:
+
+   - **Repository access**: Public repositories (read-only)
+   - **Expiration**: 366 days (update annually)
+
+2. Add the token to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):
+
+   ```sh
+   export GITHUB_TOKEN=github_pat_...
+   ```
+
+3. Reload your shell or run `source ~/.zshrc` (or equivalent)
+
+**Vercel:**
+
+1. Create a [fine-grained Personal Access Token](https://github.com/settings/personal-access-tokens/new) with the same settings as above, but with:
+
+   - **Owner**: ionic-team organization (not your personal account)
+
+2. Add the token to Vercel project settings:
+
+   - Go to your project on Vercel
+   - Navigate to **Settings → Environment Variables**
+   - Add `GITHUB_TOKEN` with the token value
+   - Select Production and Preview environments
+
+3. Redeploy the project for the token to take effect
+
+Without the token, the build will fail with an error message indicating the token is missing.
+
 ### Linting Documentation
 
 This repository uses [Prettier](https://prettier.io/), an opinionated code formatter, in order to keep consistent formatting throughout the documentation. Run the following command to automatically fix all formatting, and then push any changes:

cspell.json

@@ -18,6 +18,8 @@
     "versioned_docs/**/api",
     "versioned_docs/**/cli",
     "versioned_docs/**/native",
+    "versioned_docs/version-v5",
+    "versioned_docs/version-v6",
     "node_modules"
   ],
   "flagWords": [

docs/angular/build-options.md

@@ -29,7 +29,7 @@ Refer to the [Standalone Migration Guide](#migrating-from-modules-to-standalone)
 
 1. Ionic components need to be imported into every Angular component they are used in which can be time consuming to set up.
 
-:::info Code splitting
+:::info[Code splitting]
 Ionic ships standalone components from a single entry point (`@ionic/angular`). Bundlers such as Webpack and esbuild cannot split code from a single entry point across separate chunks, so the Ionic components you import are included in the main bundle rather than in the chunk for the route or component where they are used. Unused components are still tree-shaken out of the build.
 :::
 
@@ -365,7 +365,7 @@ Ionic Angular's standalone components use ES Modules. As a result, developers us
 
 ## Modules
 
-:::warning Deprecation Notice
+:::warning[Deprecation Notice]
 The Modules approach, including `IonicModule`, is **deprecated** and will be removed in a future major release. Existing applications will continue to work during the deprecation period but should migrate using the [Standalone migration guide](#migrating-from-modules-to-standalone). New applications should use the [Standalone](#standalone) approach.
 :::
 

docs/angular/performance.md

@@ -56,7 +56,7 @@ For more information on how Angular manages change propagation with `ngFor` see
 
 ## From the Community
 
-<!-- cspell:disable -->
+{/* cspell:disable */}
 
 [High Performance Animations in Ionic](https://www.joshmorony.com/high-performance-animations-in-ionic/) - Josh Morony
 
@@ -66,7 +66,7 @@ For more information on how Angular manages change propagation with `ngFor` see
 
 [Ionic Framework is Fast (But Your Code Might Not Be)](https://www.joshmorony.com/ionic-framework-is-fast-but-your-code-might-not-be/) - Josh Morony
 
-<!-- cspell:enable -->
+{/* cspell:enable */}
 
 :::note
 Do you have a guide you'd like to share? Click the _Edit this page_ button below.

docs/angular/quickstart.md

@@ -174,7 +174,7 @@ And the template, in the `home.page.html` file, uses those components:
 
 This creates a page with a header and scrollable content area. The second header shows a [collapsible large title](/docs/api/title.md#collapsible-large-titles) that displays on iOS devices when at the top of the content, then condenses to show the smaller title in the first header when scrolling down.
 
-:::tip Learn More
+:::tip[Learn More]
 For detailed information about Ionic layout components, see the [Header](/docs/api/header.md), [Toolbar](/docs/api/toolbar.md), [Title](/docs/api/title.md), and [Content](/docs/api/content.md) documentation.
 :::
 

docs/angular/slides.md

@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
   />
 </head>
 
-:::warning Looking for `ion-slides`?
+:::warning[Looking for `ion-slides`?]
 `ion-slides` was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the Swiper.js library directly. The migration process is detailed below.
 :::
 
@@ -71,7 +71,7 @@ From there, we just have to replace `ion-slides` elements with `swiper-container
 
 By default, make sure you import the `register` function from `swiper/element/bundle`. This uses the bundled version of Swiper, which automatically includes all modules and stylesheets needed to run Swiper's various features.
 
-If you would like to use the Core version instead, which does not include additional modules automatically, see <a href="https://swiperjs.com/element#core-version-and-modules" target="_blank" rel="noopener noreferrer">https://swiperjs.com/element#core-version-and-modules</a>. The rest of this migration guide will assume you are using the bundled version.
+If you would like to use the Core version instead, which does not include additional modules automatically, refer to <a href="https://swiperjs.com/element#core-version-and-modules" target="_blank" rel="noopener noreferrer">Swiper's core version and modules documentation</a>. The rest of this migration guide will assume you are using the bundled version.
 
 ## Swiping with Style
 
@@ -93,7 +93,7 @@ If you were using the CSS custom properties found on `ion-slides`, below is a li
 | `--scroll-bar-background`          | `--swiper-scrollbar-bg-color`               |
 | `--scroll-bar-background-active`   | `--swiper-scrollbar-drag-bg-color`          |
 
-For additional custom CSS, because Swiper Element uses Shadow DOM encapsulation, styles will need to be injected into the Shadow DOM scope. See <a href="https://swiperjs.com/element#injecting-styles" target="_blank" rel="noopener noreferrer">https://swiperjs.com/element#injecting-styles</a> for instructions.
+For additional custom CSS, because Swiper Element uses Shadow DOM encapsulation, styles will need to be injected into the Shadow DOM scope. Refer to <a href="https://swiperjs.com/element#injecting-styles" target="_blank" rel="noopener noreferrer">Swiper's guide on injecting styles</a> for instructions.
 
 ### Additional `ion-slides` Styles
 
@@ -227,7 +227,7 @@ Below is a full list of property changes when going from `ion-slides` to Swiper
 | pager   | Use the `pagination` property instead.                                                                                                  |
 
 :::note
-All properties available in Swiper Element can be found at <a href="https://swiperjs.com/swiper-api#parameters" target="_blank" rel="noopener noreferrer">https://swiperjs.com/swiper-api#parameters</a>.
+All properties available in Swiper Element can be found in the <a href="https://swiperjs.com/swiper-api#parameters" target="_blank" rel="noopener noreferrer">Swiper API parameters documentation</a>.
 :::
 
 ## Events
@@ -276,7 +276,7 @@ Below is a full list of event name changes when going from `ion-slides` to Swipe
 | `ionSlidesDidLoad`        | `swiperinit`                       |
 
 :::note
-All events available in Swiper Element can be found at <a href="https://swiperjs.com/swiper-api#events" target="_blank" rel="noopener noreferrer">https://swiperjs.com/swiper-api#events</a> and should be lowercased and prefixed with the word `swiper`.
+All events available in Swiper Element can be found in the <a href="https://swiperjs.com/swiper-api#events" target="_blank" rel="noopener noreferrer">Swiper API events documentation</a> and should be lowercased and prefixed with the word `swiper`.
 :::
 
 ## Methods
@@ -328,7 +328,7 @@ Below is a full list of method changes when going from `ion-slides` to Swiper El
 | `stopAutoplay()`     | Use the `autoplay` property instead.                                                 |
 
 :::note
-All methods and properties available on the Swiper instance can be found at <a href="https://swiperjs.com/swiper-api#methods-and-properties" target="_blank" rel="noopener noreferrer">https://swiperjs.com/swiper-api#methods-and-properties</a>.
+All methods and properties available on the Swiper instance can be found in the <a href="https://swiperjs.com/swiper-api#methods-and-properties" target="_blank" rel="noopener noreferrer">Swiper API methods and properties documentation</a>.
 :::
 
 ## Effects
@@ -340,7 +340,7 @@ Effects such as Cube or Fade can be used in Swiper Element with no additional im
 ```
 
 :::note
-For more information on effects in Swiper, please see <a href="https://swiperjs.com/swiper-api#fade-effect" target="_blank" rel="noopener noreferrer">https://swiperjs.com/swiper-api#fade-effect</a>.
+For more information on effects in Swiper, please refer to the <a href="https://swiperjs.com/swiper-api#fade-effect" target="_blank" rel="noopener noreferrer">Swiper API fade effect documentation</a>.
 :::
 
 ## Wrap Up
@@ -361,6 +361,6 @@ If you are running into issues with the migration, please create a post on the [
 
 Before opening an issue, please consider creating a post on the <a href="https://github.com/nolimits4web/swiper/discussions" target="_blank" rel="noopener noreferrer">Swiper Discussion Board</a> or the <a href="https://forum.ionicframework.com" target="_blank">Ionic Forum</a> to see if your issue can be resolved by the community.
 
-If you are running into problems with the Swiper library, new bugs should be filed on the Swiper repo: <a href="https://github.com/nolimits4web/swiper/issues" target="_blank" rel="noopener noreferrer">https://github.com/nolimits4web/swiper/issues</a>
+If you are running into problems with the Swiper library, new bugs should be filed on the <a href="https://github.com/nolimits4web/swiper/issues" target="_blank" rel="noopener noreferrer">Swiper issue tracker</a>.
 
-If you are running into problems with the `IonicSlides` module, new bugs should be filed on the Ionic Framework repo: <a href="https://github.com/ionic-team/ionic-framework/issues" target="_blank" rel="noopener noreferrer">https://github.com/ionic-team/ionic-framework/issues</a>
+If you are running into problems with the `IonicSlides` module, new bugs should be filed on the <a href="https://github.com/ionic-team/ionic-framework/issues" target="_blank" rel="noopener noreferrer">Ionic Framework issue tracker</a>.

docs/angular/testing.md

@@ -109,6 +109,34 @@ describe('TabsPage', () => {
 
 When doing component class testing, the component object is accessed using the component object defined via `component = fixture.componentInstance;`. This is an instance of the component class. When doing DOM testing, the `fixture.nativeElement` property is used. This is the actual `HTMLElement` for the component, which allows the test to use standard HTML API methods such as `HTMLElement.querySelector` in order to examine the DOM.
 
+### Waiting for Components
+
+When testing Ionic components, use the `componentOnReady` helper exported from `@ionic/core` rather than calling `el.componentOnReady()` directly. The `el.componentOnReady()` method only exists on lazy-loaded elements and calling it directly throws an error on custom-element builds, which is what standalone projects use. The helper handles both. It awaits the element's own `componentOnReady()` promise when that exists. Otherwise it waits one animation frame, giving the component's inner contents a chance to render. Wait for the callback before asserting against the rendered DOM or running accessibility tests.
+
+```tsx
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { componentOnReady } from '@ionic/core';
+import { HomePage } from './home.page';
+
+describe('HomePage', () => {
+  let fixture: ComponentFixture<HomePage>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [HomePage],
+    }).compileComponents();
+    fixture = TestBed.createComponent(HomePage);
+    fixture.detectChanges();
+  });
+
+  it('renders the submit button', async () => {
+    const button = fixture.nativeElement.querySelector('ion-button');
+    await new Promise<void>((resolve) => componentOnReady(button, () => resolve()));
+    expect(button.textContent).toContain('Submit');
+  });
+});
+```
+
 ## Services
 
 Services often fall into one of two broad categories: utility services that perform calculations and other operations, and data services that perform primarily HTTP operations and data manipulation.

docs/angular/virtual-scroll.md

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

docs/angular/zoneless.md

@@ -26,7 +26,7 @@ You do not need to change these. Angular schedules change detection for them in
 - Ionic page lifecycle hooks (`ionViewWillEnter`, `ionViewDidEnter`, `ionViewWillLeave`, `ionViewDidLeave`) that set state synchronously. Ionic notifies Angular after each hook runs.
 - Navigation, route transitions, and tab switching.
 
-:::note Angular 22
+:::note[Angular 22]
 Angular 22 also makes `OnPush` the default change detection strategy. Under `OnPush`, synchronous state set as a plain field (including in the lifecycle hooks above) no longer re-renders on its own, even though Ionic notifies Angular. Signals still update the view. For the migration path, refer to the [OnPush Change Detection section of the Ionic 9 upgrade guide](/docs/updating/9-0.md#onpush-change-detection-on-angular-22).
 :::
 

docs/api/buttons.md

@@ -62,7 +62,7 @@ This feature is only available for iOS.
 
 :::
 
-<!-- Reuse the playground from the Title directory -->
+{/* Reuse the playground from the Title directory */}
 import CollapsibleLargeTitleButtons from '@site/static/usage/v9/title/collapsible-large-title/buttons/index.md';
 
 <CollapsibleLargeTitleButtons />

docs/api/datetime-button.md

@@ -47,19 +47,12 @@ import FormatOptions from '@site/static/usage/v9/datetime-button/format-options/
 
 `ion-datetime-button` must be associated with a mounted `ion-datetime` instance. As a result, [Inline Modals](./modal#inline-modals-recommended) and [Inline Popovers](./popover#inline-popovers) with the `keepContentsMounted` property set to `true` must be used.
 
-<!--
-## Customization
-
-TODO
-
-### Buttons
-
-TODO
-
-### Theming
-
-TODO
--->
+{/* ## Customization */}
+{/* TODO */}
+{/* ### Buttons */}
+{/* TODO */}
+{/* ### Theming */}
+{/* TODO */}
 
 ## Properties
 <Props />

docs/api/img.md

@@ -18,7 +18,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill';
 
 <EncapsulationPill type="shadow" />
 
-:::warning Deprecated
+:::warning[Deprecated]
 `ion-img` is deprecated and will be removed in Ionic 10. Use a native `<img>` tag with [loading="lazy"](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#loading) instead. Refer to the [migration guide](../updating/9-0.md#img) for details on replacing events and styling.
 :::
 

docs/api/item.md

@@ -284,19 +284,12 @@ import DetailArrows from '@site/static/usage/v9/item/detail-arrows/index.md';
 <DetailArrows />
 
 
-<!--
-
-TODO add this functionality back as a css variable
-
-This feature is not enabled by default on clickable items for the `md` mode, but it can be enabled by setting the following CSS variable:
-
-```css
---item-detail-push-show: true;
-```
-
-See the [theming documentation](/docs/theming/css-variables) for more information.
-
--->
+{/* TODO add this functionality back as a css variable */}
+{/* This feature is not enabled by default on clickable items for the `md` mode, but it can be enabled by setting the following CSS variable: */}
+{/* ```css */}
+{/* --item-detail-push-show: true; */}
+{/* ``` */}
+{/* See the [theming documentation](/docs/theming/css-variables) for more information. */}
 
 
 ## Item Lines

docs/api/progress-bar.md

@@ -48,7 +48,7 @@ import Indeterminate from '@site/static/usage/v9/progress-bar/indeterminate/inde
 
 ## Progress Bars in Toolbars
 
-<!-- Reuse the playground from the Toolbar directory -->
+{/* Reuse the playground from the Toolbar directory */}
 import Toolbar from '@site/static/usage/v9/toolbar/progress-bars/index.md';
 
 <Toolbar />

docs/api/searchbar.md

@@ -58,7 +58,7 @@ import CancelButton from '@site/static/usage/v9/searchbar/cancel-button/index.md
 
 Searchbars are styled to look native when placed inside of a toolbar. In iOS, searchbars should be placed in their own toolbar, under a toolbar that contains the page title. In Material Design, searchbars are either persistently displayed in their own toolbar, or expand over a toolbar containing the page title.
 
-<!-- Reuse the playground from the Toolbar directory -->
+{/* Reuse the playground from the Toolbar directory */}
 import Toolbar from '@site/static/usage/v9/toolbar/searchbars/index.md';
 
 <Toolbar />