diff --git a/website/docs/for-android/upgrade-guides.md b/website/docs/for-android/upgrade-guides.md index c248703..dcc928f 100644 --- a/website/docs/for-android/upgrade-guides.md +++ b/website/docs/for-android/upgrade-guides.md @@ -9,12 +9,12 @@ import CodeBlock from '@theme/CodeBlock'; If you need help configuring specific versions of Portals with Capacitor or Capacitor Plugins, check out our [SDK Version Compatibility](./version-matrix) page. -## IonicPortals Android 0.7.x -> 0.8.0 +## Portals for Android 0.7.x → 0.8.0 -IonicPortals Android version 0.8.0 is compatible with '@ionic/portals' version 0.8.x +- Portals for Android version `0.8.0` is compatible with Portals Web Plugin version `0.8.x`. :::caution -Ionic Portals 0.8.0 is a notable update that upgrades the Capacitor dependency to version 5. Care should be taken to update dependencies across your web content and native apps to ensure compatibility. +Portals 0.8.0 is a notable update that upgrades the Capacitor dependency to version 5. Care should be taken to update dependencies across your web content and native apps to ensure compatibility. ::: First review the [Capacitor 5 Update Guide](https://capacitorjs.com/docs/updating/5-0) for an overview of necessary changes. Some will not be relevant for Portals apps, but this will be a useful reference in case you encounter issues with your upgrade. @@ -29,14 +29,14 @@ Here are a few examples of how to migrate from the previous API to the new API: ##### Subscribing -```kotlin +```kotlin // Before 0.8.0 -val subscriptionRef = PortalsPlugin.subscribe("eventName") { result -> +val subscriptionRef = PortalsPlugin.subscribe("eventName") { result -> // do something with the result } // After 0.8.0 -val subscriptionRef = PortalsPubSub.shared.subscribe("eventName") { result -> +val subscriptionRef = PortalsPubSub.shared.subscribe("eventName") { result -> // do something with the result } ``` @@ -67,7 +67,7 @@ We recommend updating your version of Android Studio to Flamingo (2022.2.1) or n ### Dependency Version Alignment -IonicPortals for Android version 0.8.0 is compatible with the following dependency versions. Update as needed: +Portals for Android version 0.8.0 is compatible with the following dependency versions. Update as needed: { @@ -114,15 +114,15 @@ kotlinOptions { Projects should be updated to compile and target Android SDK version 33 or higher (Android 13). -## Live Updates SDK 0.3.x -> 0.4.0 +## Live Updates SDK 0.3.x → 0.4.0 A breaking change was introduced in the Live Updates SDK. The [SyncCallback](https://ionic.io/docs/live-updates-sdk-android/live-updates/io.ionic.liveupdates.network/-sync-callback/index.html) structure changed slightly to allow for more information to be returned about a sync. If you are calling [sync](https://ionic.io/docs/live-updates-sdk-android/live-updates/io.ionic.liveupdates/-live-update-manager/sync.html) and using the callback to act on the results, make sure to adapt the structure of your callback when upgrading to version `0.4.x` of the Live Updates SDK. -## @ionic/portals 0.6.x -> 0.7.0 +## Portals for Android 0.6.x → 0.7.0 -IonicPortals Android version 0.7.0 is compatible with '@ionic/portals' version 0.7.x +- Portals for Android version `0.7.0` is compatible with Portals Web Plugin version `0.7.x`. :::caution Ionic Portals 0.7.0 is a notable update that upgrades the Capacitor dependency to version 4. Care should be taken to update dependencies across your web content and native apps to ensure compatibility. @@ -138,7 +138,7 @@ Update the Portals Plugin in your web content to `0.7.0`. Then, follow the [Capa #### Dependency Version Alignment -IonicPortals for Android version 0.7.0 is compatible with the following dependency versions. Update as needed: +Portals for Android version 0.7.0 is compatible with the following dependency versions. Update as needed: { @@ -198,97 +198,3 @@ export interface InitialContext { value: T | undefined; } ``` - -## @ionic/portals 0.0.x -> 0.6.0 - -### `Portals.publish()` - -The method signature of `Portals.publish()` now allows generic typing over `PortalMessage` instead of restricting generic typing to the `data` parameter of `PortalMessage`. The `message` parameter must be of type `string` but can be predefined to prevent typos, invalid topic names, etc. - -Before: - -```typescript -Portals.publish({ topic: "foo", data: "bar" }); -``` - -After: - -```typescript -type ValidMessage = { topic: "foo"; data: string }; - -// TypeScript will reject the following statement: -Portals.publish({ topic: "food", data: 1 }); -``` - -### `Portals.getInitialContext()` - -`Portals.getInitialContext()` is no longer asynchronous and has been moved out of the `Portals` class. - -Before: - -```typescript -import React from "react"; -import ReactDOM from "react-dom"; -import App from "./App"; -import Portals from "@ionic/portals"; -import { Capacitor } from "@capacitor/core"; - -if (!Capacitor.isNativePlatform()) { - // do something - (window as any).portalInitialContext = { - value: { startingRoute: "/" }, - }; -} - -Portals.getInitialContext<{ startingRoute: string }>().then((context) => { - ReactDOM.render( - - - , - document.getElementById("root") - ); -}); -``` - -After: - -```typescript -import React from 'react'; -import ReactDOM from 'react-dom'; -import App from './App'; -import Portals, { getInitialContext } from '@ionic/portals'; -import { Capacitor } from '@capacitor/core'; - -const initialContext = getInitialContext<{ startingRoute: string }>; -const startingRoute = initialContext?.value ?? { startingRoute: '/' }; - -ReactDOM.render( - - - , - document.getElementById('root'), -); -``` - -## @ionic/portals-react-native 0.0.x -> 0.1.0 - -The props on `PortalView` have changed from having individual props of `name` and `initialContext` to a single prop named `portal`. - -Before: - -```javascript - -``` - -After: - -```javascript - -``` diff --git a/website/docs/for-ios/upgrade-guides.md b/website/docs/for-ios/upgrade-guides.md index 7a35af6..1840fa1 100644 --- a/website/docs/for-ios/upgrade-guides.md +++ b/website/docs/for-ios/upgrade-guides.md @@ -6,9 +6,9 @@ sidebar_label: Upgrade Guides import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -## IonicPortals iOS 0.7.x -> 0.8.0 +## Portals for iOS 0.7.x → 0.8.0 -IonicPortals iOS version 0.8.0 is compatible with '@ionic/portals' version 0.8.x. +- Portals for iOS version `0.8.0` is compatible with Portals Web Plugin version `0.8.x`. This release requires Xcode 14.1 or higher in accordance with [Apple's requirements](https://developer.apple.com/news/upcoming-requirements/?id=04252023a). @@ -17,6 +17,9 @@ IonicPortals 0.8.0 is a notable update that requires Capacitor 5. Care should be taken to update dependencies across your web content and native apps to ensure compatibility. ::: +First review the [Capacitor 5 Update Guide](https://capacitorjs.com/docs/updating/5-0) for an overview of necessary changes. +Some will not be relevant for Portals apps, but this will be a useful reference in case you encounter issues with your upgrade. + ### Breaking Changes #### Pub/Sub @@ -34,12 +37,13 @@ There is no longer a `PluginRegistrationStrategy` on `Portal`. All plugins must be explicitly registered on the Portal. In certain cases, automatic registration can cause unexpected crashes in applications. -## @ionic/portals 0.6.x -> 0.7.0 +## Portals for iOS 0.6.x → 0.7.0 -IonicPortals iOS version 0.7.0 is compatible with '@ionic/portals' version 0.7.x +- Portals for iOS version `0.7.0` is compatible with Portals Web Plugin version `0.7.x`. :::caution -Ionic Portals 0.7.0 is a notable update that upgrades the Capacitor dependency to version 4. Care should be taken to update dependencies across your web content and native apps to ensure compatibility. +Portals 0.7.0 is a notable update that requires Capacitor 4. +Care should be taken to update dependencies across your web content and native apps to ensure compatibility. ::: First review the [Capacitor 4 Update Guide](https://capacitorjs.com/docs/updating/4-0) for an overview of necessary changes. Some will not be relevant for Portals apps, but this will be a useful reference in case you encounter issues with your upgrade. @@ -76,80 +80,9 @@ export interface InitialContext { } ``` -## @ionic/portals 0.0.x -> 0.6.0 - -### `Portals.publish()` - -The method signature of `Portals.publish()` now allows generic typing over `PortalMessage` instead of restricting generic typing to the `data` parameter of `PortalMessage`. The `message` parameter must be of type `string` but can be predefined to prevent typos, invalid topic names, etc. - -Before: - -```typescript -Portals.publish({ topic: "foo", data: "bar" }); -``` - -After: - -```typescript -type ValidMessage = { topic: "foo"; data: string }; - -// TypeScript will reject the following statement: -Portals.publish({ topic: "food", data: 1 }); -``` - -### `Portals.getInitialContext()` - -`Portals.getInitialContext()` is no longer asynchronous and has been moved out of the `Portals` class. - -Before: - -```typescript -import React from "react"; -import ReactDOM from "react-dom"; -import App from "./App"; -import Portals from "@ionic/portals"; -import { Capacitor } from "@capacitor/core"; - -if (!Capacitor.isNativePlatform()) { - // do something - (window as any).portalInitialContext = { - value: { startingRoute: "/" }, - }; -} - -Portals.getInitialContext<{ startingRoute: string }>().then((context) => { - ReactDOM.render( - - - , - document.getElementById("root") - ); -}); -``` - -After: - -```typescript -import React from 'react'; -import ReactDOM from 'react-dom'; -import App from './App'; -import Portals, { getInitialContext } from '@ionic/portals'; -import { Capacitor } from '@capacitor/core'; - -const initialContext = getInitialContext<{ startingRoute: string }>; -const startingRoute = initialContext?.value ?? { startingRoute: '/' }; - -ReactDOM.render( - - - , - document.getElementById('root'), -); -``` - -## IonicPortals iOS 0.6.0 -> 0.6.1 +## Portals for iOS 0.6.0 → 0.6.1 -IonicPortals iOS version 0.6.1 is compatible with '@ionic/portals' version 0.5.x +- Portals for iOS version `0.6.1` is compatible with Portals Web Plugin version `0.5.x`. ### Swift Package Manager Support @@ -161,13 +94,13 @@ is "Up to Next Minor Version" to prevent auto-updating to a breaking version bef The 0.5.x versions of Ionic Portals iOS required iOS 14.0. In this release we have included support for iOS 13.0 and up. To support iOS 13.0 in your app, you should update your target to support the OS. -## IonicPortals iOS 0.5.x -> 0.6.0 +## Portals for iOS 0.5.x → 0.6.0 -IonicPortals iOS version 0.6.0 is compatible with '@ionic/portals' version 0.5.x +- Portals for iOS version `0.6.0` is compatible with Portals Web Plugin version `0.5.x`. ### PortalManager & PortalBuilder Removal -#### PortalManager -> PortalsRegistrationManager +#### PortalManager → PortalsRegistrationManager `PortalManager` has been removed. It's registration functionality has been replaced with [`PortalsRegistrationManager`](https://ionic-portals-ios.vercel.app/documentation/ionicportals/portalsregistrationmanager). @@ -332,7 +265,7 @@ Portal now has conformance for `ExpressibleByStringLiteral` for simple use-cases let portalView = PortalUIView(portal: "checkout") ``` -### PortalWebView -> PortalUIView & PortalUIWebView -> PortalView +### PortalWebView → PortalUIView & PortalUIWebView → PortalView The PortalWebView (the UIKit class) name has been changed to `PortalUIView`. `PortalUIWebView` (the SwiftUI struct) name as been changed to `PortalView`. All other functionality remains the same. diff --git a/website/docs/for-react-native/upgrade-guides.md b/website/docs/for-react-native/upgrade-guides.md index a7e62cc..b2bfdd6 100644 --- a/website/docs/for-react-native/upgrade-guides.md +++ b/website/docs/for-react-native/upgrade-guides.md @@ -6,9 +6,9 @@ sidebar_label: Upgrade Guides import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -## @ionic/portals-react-native 0.4.0 -> 0.5.0 +## Portals for React Native 0.4.0 → 0.5.0 -`@ionic/protals-react-native` version 0.5.0 updates the underlying native IonicPortals libraries to ^0.8.0. This update includes breaking changes to the API. Please read the following carefully to ensure a smooth upgrade. +Portals for React Native version 0.5.0 updates the underlying native Portals libraries to ^0.8.0. This update includes breaking changes to the API. Please read the following carefully to ensure a smooth upgrade. ### API Changes @@ -20,7 +20,7 @@ The pub/sub functionality has been overhauled to lean on React Native's existing method been updated to return an `EmitterSubscription` and the `unsubscribe` method has been removed. To stop receiving events, call the `remove()` method on the `EmitterSubscription` returned from `subscribe`. -## @ionic/portals-react-native 0.3.0 -> 0.4.0 +## Portals for React Native 0.3.0 → 0.4.0 ### API Changes @@ -52,11 +52,11 @@ device to pull assets from. See [Sharing Assets](../for-react-native/how-to/shar It is now possible to measure a number of web vitals metrics from your portals in React Native. See [Web Vitals](../for-web/web-vitals#react-native) for more information. -## @ionic/portals-react-native 0.2.0 -> 0.3.0 +## Portals for React Native 0.2.0 → 0.3.0 The iOS, Android, and web libraries have all been updated to depend on Capacitor 4. There are no React Native specific code changes needed to adopt these features. However, it will be necessary to follow the [iOS](../for-ios/upgrade-guides#ionicportals-06x---070) and [Android](../for-android/upgrade-guides#ionicportals-06x---070) upgrade guides to ensure a successful migration. -## @ionic/portals-react-native 0.1.x -> 0.2.0 +## Portals for React Native 0.1.x → 0.2.0 ### API Changes @@ -113,78 +113,7 @@ type LiveUpdate = { At a minimum, when including a `portals.config.json` it must at least have the `portals` key defined with at least one valid `Portal` definition in the array. If you are using Live Updates, you must include a `LiveUpdate` configuration. If you are using Secure Live Updates, you must include the `liveUpdatesKey` in the configuration. -## @ionic/portals 0.0.x -> 0.6.0 - -### `Portals.publish()` - -The method signature of `Portals.publish()` now allows generic typing over `PortalMessage` instead of restricting generic typing to the `data` parameter of `PortalMessage`. The `message` parameter must be of type `string` but can be predefined to prevent typos, invalid topic names, etc. - -Before: - -```typescript -Portals.publish({ topic: "foo", data: "bar" }); -``` - -After: - -```typescript -type ValidMessage = { topic: "foo"; data: string }; - -// TypeScript will reject the following statement: -Portals.publish({ topic: "food", data: 1 }); -``` - -### `Portals.getInitialContext()` - -`Portals.getInitialContext()` is no longer asynchronous and has been moved out of the `Portals` class. - -Before: - -```typescript -import React from "react"; -import ReactDOM from "react-dom"; -import App from "./App"; -import Portals from "@ionic/portals"; -import { Capacitor } from "@capacitor/core"; - -if (!Capacitor.isNativePlatform()) { - // do something - (window as any).portalInitialContext = { - value: { startingRoute: "/" }, - }; -} - -Portals.getInitialContext<{ startingRoute: string }>().then((context) => { - ReactDOM.render( - - - , - document.getElementById("root") - ); -}); -``` - -After: - -```typescript -import React from 'react'; -import ReactDOM from 'react-dom'; -import App from './App'; -import Portals, { getInitialContext } from '@ionic/portals'; -import { Capacitor } from '@capacitor/core'; - -const initialContext = getInitialContext<{ startingRoute: string }>; -const startingRoute = initialContext?.value ?? { startingRoute: '/' }; - -ReactDOM.render( - - - , - document.getElementById('root'), -); -``` - -## @ionic/portals-react-native 0.0.x -> 0.1.0 +## Portals for React Native 0.0.x → 0.1.0 The props on `PortalView` have changed from having individual props of `name` and `initialContext` to a single prop named `portal`. diff --git a/website/docs/for-web/upgrade-guides.md b/website/docs/for-web/upgrade-guides.md index aee3b93..70fb4ff 100644 --- a/website/docs/for-web/upgrade-guides.md +++ b/website/docs/for-web/upgrade-guides.md @@ -6,13 +6,12 @@ sidebar_label: Upgrade Guides import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -## @ionic/portals 0.7.x -> 0.8.0 - -`@ionic/portals@0.8.0` is compatible with IonicPortals Android and iOS versions 0.8.x. +## Portals Web Plugin 0.7.x → 0.8.0 +- Portals Web Plugin `0.8.0` is compatible with Portals for Android and Portals for iOS versions `0.8.x`. :::caution -@ionic/portals 0.8.0 is a notable update that requires Capacitor 5. +Portals Web Plugin `0.8.0` is a notable update that requires Capacitor 5. Care should be taken to update dependencies across your web content and native apps to ensure compatibility. ::: @@ -21,15 +20,20 @@ Some will not be relevant for Portals apps, but this will be a useful reference ### Breaking Changes -The `Portals` default export is no longer exposed. All methods are made available as individual module exports. -If you wish to still use a `Portals` namespace to call, simply `import * as Portals from '@ionic/portals';` +The `Portals` default export is no longer exposed. All methods are made available as individual module exports. +If you wish to still use a `Portals` namespace just import like the following. + +```ts +import * as Portals from "@ionic/portals"; +``` The `subscribe` function now returns a `Promise` instead of a number representing a "subscription reference". `PluginListenerHandle` has a `remove` method that can be used for unsubscribing from events. -Since `PluginListenerHandle` is able to manage unsubscribing from events, the `unsubscribe` function has been removed from the API. +Since `PluginListenerHandle` is able to manage unsubscribing from events, the `unsubscribe` function has been removed from the API. +## Portals Web Plugin 0.6.x → 0.7.0 -## @ionic/portals 0.6.x -> 0.7.0 +- Portals Web Plugin `0.7.0` is compatible with Portals for Android and Portals for iOS versions `0.7.x`. :::caution Ionic Portals 0.7.0 is a notable update that upgrades the Capacitor dependency to version 4. Care should be taken to update dependencies across your web content and native apps to ensure compatibility. @@ -45,7 +49,7 @@ Update the Portals Plugin in your web content to `0.7.0`. Then, follow the [Capa #### Dependency Version Alignment -The only necessary steps to use Portals version 0.7.0 should be to update dependencies. IonicPortals for iOS version 0.7.0 is compatible with Live Updates 0.2.2 and Official Capacitor Plugins over version 4.0. +The only necessary steps to use Portals version 0.7.0 should be to update dependencies. Portals for iOS version 0.7.0 is compatible with Live Updates 0.2.2 and Official Capacitor Plugins over version 4.0. ### InitialContext Update @@ -69,7 +73,7 @@ export interface InitialContext { } ``` -## @ionic/portals 0.0.x -> 0.6.0 +## Portals Web Plugin 0.0.x → 0.6.0 ### `Portals.publish()` @@ -139,4 +143,3 @@ ReactDOM.render( document.getElementById('root'), ); ``` - diff --git a/website/sidebars.js b/website/sidebars.js index 73c4583..4045d22 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -205,7 +205,7 @@ module.exports = { { type: "category", className: "bottom-item", - label: "Web", + label: "Portals Web Plugin", collapsed: true, items: [ "for-web/overview",