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

@@ -1,15 +1,32 @@
-src/theme/DocItem
-src/theme/DocRoot
+# Ejected components keep upstream's formatting so they stay diffable against
+# @docusaurus/theme-classic. Refer to `src/theme/README.md`.
+# Wrapped components are our own code, so they follow the repo's formatting.
+src/theme/DocItem/Layout/index.tsx
+src/theme/EditMetaRow/index.tsx
+src/theme/Icon/Edit/index.tsx
+src/theme/Icon/Language/index.tsx
+src/theme/Layout/index.tsx
+src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx
+src/theme/prism-include-languages.ts
+
 legacy-stencil-components
 scripts/bak
 
 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/lifecycle.md

@@ -97,7 +97,7 @@ Below are some tips on use cases for each of the life cycle events.
 
 - `ngOnInit` - Initialize your component and load data from services that don't need refreshing on each subsequent visit.
 - `ionViewWillEnter` - Since `ionViewWillEnter` is called every time the view is navigated to (regardless if initialized or not), it's a good method to load data from services. However, if your data comes back during the animation, it can start lots of DOM manipulation, which can cause some janky animations.
-- `ionViewDidEnter` - If you see performance problems from using `ionViewWillEnter` when loading data, you can do your data calls in `ionViewDidEnter` instead. This event won't fire until after the page is visible by the user, however, so you might want to use either a loading indicator or a skeleton screen, so content doesn't flash in un-naturally after the transition is complete.
+- `ionViewDidEnter` - If you encounter performance problems from using `ionViewWillEnter` when loading data, you can do your data calls in `ionViewDidEnter` instead. This event won't fire until after the page is visible by the user, however, so you might want to use either a loading indicator or a skeleton screen, so content doesn't flash in un-naturally after the transition is complete.
 - `ionViewWillLeave` - Can be used for cleanup, like unsubscribing from observables. Since `ngOnDestroy` might not fire when you navigate from the current page, put your cleanup code here if you don't want it active while the screen is not in view.
 - `ionViewDidLeave` - When this event fires, you know the new page has fully transitioned in, so any logic you might not normally do when the view is visible can go here.
 - `ngOnDestroy` - Cleanup logic for your pages that you don't want to clean up in `ionViewWillLeave`.

docs/angular/navigation.md

@@ -15,7 +15,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 This guide covers how routing works in an app built with Ionic and Angular.
 
-The Angular Router is one of the most important libraries in an Angular application. Without it, apps would be single view/single context apps or would not be able to maintain their navigation state on browser reloads. With Angular Router, we can create rich apps that are linkable and have rich animations (when paired with Ionic of course). Let's look at the basics of the Angular Router and how we can configure it for Ionic apps.
+The Angular Router is one of the most important libraries in an Angular application. Without it, apps would be single view/single context apps or would not be able to maintain their navigation state on browser reloads. With Angular Router, we can create rich apps that are linkable and have rich animations (when paired with Ionic of course). Let's walk through the basics of the Angular Router and how we can configure it for Ionic apps.
 
 ## A simple Route
 
@@ -120,15 +120,15 @@ Both options provide the same navigation mechanism, just fitting different use c
 
 ### Navigating using LocationStrategy.historyGo
 
-Angular Router has a [LocationStrategy.historyGo](https://angular.io/api/common/LocationStrategy#historyGo) method that allows developers to move forward or backward through the application history. Let's take a look at an example.
+Angular Router has a [LocationStrategy.historyGo](https://angular.io/api/common/LocationStrategy#historyGo) method that allows developers to move forward or backward through the application history. Let's walk through an example.
 
 Say you have the following application history:
 
 `/pageA` --> `/pageB` --> `/pageC`
 
 If you were to call `LocationStrategy.historyGo(-2)` on `/pageC`, you would be brought back to `/pageA`. If you then called `LocationStrategy.historyGo(2)`, you would be brought to `/pageC`.
 
-An key characteristic of `LocationStrategy.historyGo()` is that it expects your application history to be linear. This means that `LocationStrategy.historyGo()` should not be used in applications that make use of non-linear routing. See [Linear Routing versus Non-Linear Routing](#linear-routing-versus-non-linear-routing) for more information.
+An key characteristic of `LocationStrategy.historyGo()` is that it expects your application history to be linear. This means that `LocationStrategy.historyGo()` should not be used in applications that make use of non-linear routing. Refer to [Linear Routing versus Non-Linear Routing](#linear-routing-versus-non-linear-routing) for more information.
 
 ## Lazy loading routes
 
@@ -265,9 +265,9 @@ We recommend keeping your application as simple as possible until you need to ad
 
 The two most common uses of non-linear routing is with tabs and nested `ion-router-outlet`s. We recommend only using non-linear routing if your application meets the tabs or nested router outlet use cases.
 
-For more on tabs, please see [Working with Tabs](#working-with-tabs).
+For more on tabs, please refer to [Working with Tabs](#working-with-tabs).
 
-For more on nested router outlets, please see [Nested Routes](#nested-routes).
+For more on nested router outlets, please refer to [Nested Routes](#nested-routes).
 
 ## Shared URLs versus Nested Routes
 
@@ -321,13 +321,13 @@ The above routes are nested because they are in the `children` array of the pare
 
 Shared URLs are great when you want to transition from page A to page B while preserving the relationship between the two pages in the URL. In our previous example, a button on the `/dashboard` page could transition to the `/dashboard/stats` page. The relationship between the two pages is preserved because of a) the page transition and b) the url.
 
-Nested routes should be used when you want to render content in outlet A while also rendering sub-content inside of a nested outlet B. The most common use case you will run into is tabs. When you load up a tabs Ionic starter application, you will see `ion-tab-bar` and `ion-tabs` components rendered in the first `ion-router-outlet`. The `ion-tabs` component renders another `ion-router-outlet` which is responsible for rendering the contents of each tab.
+Nested routes should be used when you want to render content in outlet A while also rendering sub-content inside of a nested outlet B. The most common use case you will run into is tabs. When you load up a tabs Ionic starter application, the first `ion-router-outlet` renders the `ion-tab-bar` and `ion-tabs` components. The `ion-tabs` component renders another `ion-router-outlet` which is responsible for rendering the contents of each tab.
 
 There are very few use cases in which nested routes make sense in mobile applications. When in doubt, use the shared URL route configuration. We strongly caution against using nested routing in contexts other than tabs as it can quickly make navigating your app confusing.
 
 ## Working with Tabs
 
-With Tabs, the Angular Router provides Ionic the mechanism to know what components should be loaded, but the heavy lifting is actually done by the tabs component. Let's look at a simple example.
+With Tabs, the Angular Router provides Ionic the mechanism to know what components should be loaded, but the heavy lifting is actually done by the tabs component. Let's walk through a simple example.
 
 ```ts
 const routes: Routes = [
@@ -380,7 +380,7 @@ Each tab in Ionic is treated as an individual navigation stack. This means if yo
 
 This behavior is important to note as it is different than most tab implementations that are found in other web based UI libraries. Other libraries typically manage tabs as one single history stack.
 
-Since Ionic is focused on helping developers build mobile apps, the tabs in Ionic are designed to match native mobile tabs as closely as possible. As a result, there may be certain behaviors in Ionic's tabs that differ from tabs implementations you have seen in other UI libraries. Read on to learn more about some of these differences.
+Since Ionic is focused on helping developers build mobile apps, the tabs in Ionic are designed to match native mobile tabs as closely as possible. As a result, there may be certain behaviors in Ionic's tabs that differ from tabs implementations in other UI libraries. Read on to learn more about some of these differences.
 
 ### Child Routes within Tabs
 
@@ -444,7 +444,7 @@ Since each tab is its own navigation stack, it is important to note that these n
 
 A good example of this in practice is the iOS App Store and Google Play Store mobile applications. These apps both provide tabbed interfaces, but neither one ever routes the user across tabs. For example, the "Games" tab in the iOS App Store app never directs users to the "Search" tab and vice versa.
 
-Let's take a look at a couple common mistakes that are made with tabs.
+Let's go over a couple common mistakes that are made with tabs.
 
 **A Settings Tab That Multiple Tabs Reference**
 

docs/angular/overlays.md

@@ -202,7 +202,7 @@ import type { ModalOptions, PopoverOptions } from '@ionic/angular';
 
 ## Docs for Overlays in Ionic
 
-For full docs and to see usage examples, visit the docs page for each of the overlays in Ionic:
+For full docs and usage examples, visit the docs page for each of the overlays in Ionic:
 
 - [Action Sheet](https://ionicframework.com/docs/api/action-sheet)
 - [Alert](https://ionicframework.com/docs/api/alert)

docs/angular/performance.md

@@ -42,7 +42,7 @@ trackItems(index: number, itemObject: any) {
 
 In this example, we have an array of objects called `items`. Each object contains a `value` and an `id`. Using `trackBy`, we pass a `trackItems` function which returns the `id` of each object. This `id` is used to provide a stable identity for each loop element.
 
-For more information on how Angular manages change propagation with `ngFor` see https://angular.io/api/common/NgForOf#change-propagation.
+For more information, refer to the [Angular NgForOf change propagation documentation](https://angular.io/api/common/NgForOf#change-propagation).
 
 ## From the Ionic Team
 
@@ -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/pwa.md

@@ -60,7 +60,7 @@ After `@angular/pwa` has been added, a new `ngsw-config.json` file will be creat
 }
 ```
 
-There are two sections in here, one for app specific resources (JS, CSS, HTML) and assets the app will load on demand. Depending on your app, these options can be customized. For a more detailed guide, read [the official guide from the Angular Team.](https://angular.io/guide/service-worker-config)
+There are two sections in here, one for app specific resources (JS, CSS, HTML) and assets the app will load on demand. Depending on your app, these options can be customized. For a more detailed guide, read [the official guide from the Angular Team](https://angular.io/guide/service-worker-config).
 
 ## Deploying
 
@@ -149,7 +149,7 @@ The last thing needed is to make sure caching headers are being set correctly. T
 }
 ```
 
-For more information about the `firebase.json` properties, see the [Firebase documentation](https://firebase.google.com/docs/hosting/full-config#section-firebase-json).
+For more information about the `firebase.json` properties, refer to the [Firebase documentation](https://firebase.google.com/docs/hosting/full-config#section-firebase-json).
 
 Next, build an optimized version of the app by running: