[terra-application-docs] Add upgrade-guide for terra-application v2 (#…

…388)

packages/terra-application-docs/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 3.3.0 - (May 20, 2024)
+
+* Added
+  * Added upgrade guide for terra-application v2.
+
 * Changed
   * Moved docs from the `terra-application` package.
 

packages/terra-application-docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerner/terra-application-docs",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Contains documentation for packages in the terra-application monorepo",
   "author": "Cerner Corporation",
   "repository": {

packages/terra-application-docs/src/terra-dev-site/app/Application.1.app.mdx

@@ -37,64 +37,124 @@ Terra Application contains many components designed to help solve common web app
 
 The ApplicationBase component is the entrypoint into the Terra application framework. Applications must render ApplicationBase around their content to provide the content with ApplicationBase's features.
 
-- [Application Base API](/application/terra-application/components/application-base)
+```js
+import ApplicationBase from 'terra-application/application-base';
+```
+
+- [Application Base API](./components/application-base)
 
 ### Application Navigation
 
 Consistent navigation throughout Cerner applications helps provide a positive user experience by teaching users what to expect when interacting with applications. The ApplicationNavigation component provides a styled layout and controls used for navigating within an application.
 
-- [Application Navigation API](/application/terra-application/components/application-navigation)
+```js
+import ApplicationNavigation, {  
+  ApplicationNavigationActionsContext,
+  extensionItemsPropType,
+  navigationItemsPropType,
+  titleConfigPropType,
+  userConfigPropType,
+  utilityItemsPropType,
+} from 'terra-application/application-navigation';
+```
+
+- [Application Navigation API](./components/application-navigation)
 
 ### JS Error Handling
 
 Typically when a javascript error occurs in a web application, the entire page will be broken. Using [react error boundaries](https://reactjs.org/docs/error-boundaries.html), Terra provides a way to isolate the error to prevent the entire application from being taken down.
 
-- [Application Error Boundary API](/application/terra-application/components/application-error-boundary)
+```js
+import ApplicationErrorBoundary from 'terra-application/application-error-bounary';
+```
+
+- [Application Error Boundary API](./components/application-error-boundary)
 
 ### Overlays
 
 Presenting overlays over content being loaded or saved to a server is a common application pattern. Terra provides an application overlay to overlay loading content, as well as an application overlay provider to redefine what portion of the page should be overlaid.
 
-- [Application Overlay API](/application/terra-application/components/application-loading-overlay)
-- [Application Overlay Provider API](/application/terra-application/components/application-loading-overlay-provider)
+```js
+import ApplicationLoadingOverlay, { ApplicationLoadingOverlayContext, ApplicationLoadingOverlayProvider } from 'terra-application/application-loading-overlay';
+```
+
+- [Application Overlay API](./components/application-loading-overlay)
+- [Application Overlay Provider API](./components/application-loading-overlay-provider)
 
 ### Status Views
 
 Presenting status views to show the current state of the page is a common application pattern. Terra provides an application status view to present a status view over the content, as well as an application status view provider to redefine what portion of the page should be overlaid.
 
-- [Application Status View API](/application/terra-application/components/application-status-overlay)
-- [Application Status View Provider API](/application/terra-application/components/application-status-overlay-provider)
+```js
+import ApplicationStatusOverlay, { ApplicationStatusOverlayContext, ApplicationStatusOverlayProvider } from 'terra-application/application-status-overlay';
+```
+
+- [Application Status View API](./components/application-status-overlay)
+- [Application Status View Provider API](./components/application-status-overlay-provider)
 
 ### Notification Banners
 
 Notification Banners are used to bring the user's attention to important displayed information. This common interface pattern requires strategic placement and ordering on the application screen to be effective. Terra Application provides banner management to align with these needs.
 
-- [Notification Banners API](/application/terra-application/components/notification-banner)
+```js
+import NotificationBanner from 'terra-application/notification-banner';
+```
+
+- [Notification Banners API](./components/notification-banner)
 
 ### Modal disclosure
 
 Presenting content within a modal is a common, yet tricky pattern. To help reduce this complexity Terra provides API's, through the disclosure manager, to present modal content.
 
-- [Disclosure Manager API](/application/terra-application/contexts/disclosure-manager-context)
+```js
+import DisclosureManager,{
+  DisclosureManagerContext, 
+  DisclosureManagerDelegate, 
+  DisclosureManagerHeaderAdapter, 
+  DisclosureManagerHeaderAdapterContext, 
+  availableDisclosureHeights, 
+  availableDisclosureSizes, 
+  availableDisclosureWidths,
+  closeMostRecentDisclosure, 
+  disclosureManagerShape, 
+  getActiveDisclosureCount
+  withDisclosureManager, 
+} from 'terra-application/disclosure-manager';
+```
+
+- [Disclosure Manager API](./contexts/disclosure-manager-context)
 
 ### Unsaved Changes
 
 Unsaved form data is another common pattern. Terra provides the Navigation prompt to prevent navigating away from unsaved changes.
 
-- [Navigation Prompt API](/application/terra-application/components/navigation-prompt)
+```js
+import NavigationPrompt,{
+NavigationPromptCheckpoint,
+PromptRegistrationContext,
+getUnsavedChangesPromptOptions,
+navigationPromptResolutionOptionsShape,
+} from 'terra-application/navigation-prompt';
+```
+
+- [Navigation Prompt API](./components/navigation-prompt)
 
 ### Slide panel disclosure
 
 Presenting content to a slide panel is less common, yet still tricky. Similar to modal manager we provide the disclosure manager api to disclose content to slide panels, as well as a slide panel manager to define the slide panel in the application.
 
-- [Slide Panel Manager](/application/terra-application/components/slide-panel-manager)
-- [Disclosure Manager API](/application/terra-application/contexts/disclosure-manager-context)
+```js
+import SlidePanelManager from 'terra-application/slide-panel-manager';
+```
+
+- [Slide Panel Manager](./components/slide-panel-manager)
+- [Disclosure Manager API](./contexts/disclosure-manager-context)
 
 ### Active Breakpoints
 
 Many applications respond to the current active breakpoint to adjust for screen size. We provide the active breakpoint as a context to limit the number of component that listen to the browser resize event.
 
-- [Active Breakpoint Context API](/application/terra-application/contexts/active-breakpoint-context)
+- [Active Breakpoint Context API](./contexts/active-breakpoint-context)
 
 ### Internationalization
 
@@ -106,7 +166,11 @@ Terra applications must work for many locales, `react-intl` should be utilized f
 
 Applications commonly switch between light and dark modes. Terra provides theme APIs to allow theming of custom components within a terra application.
 
-- [Theme Context API](/application/terra-application/contexts/theme-context)
+```js
+import { ThemeContext } from 'terra-application/theme';
+```
+
+- [Theme Context API](./contexts/theme-context)
 
 ### Component Composition
 

packages/terra-application-docs/src/terra-dev-site/app/UpgradeGuide.4.app.mdx

@@ -0,0 +1,116 @@
+# Upgrade Guide
+
+## Upgrading from terra-application v1 to terra-application v2
+
+### Unsupported functionality from V1
+
+The following features are no longer supported with terra-application-v2
+
+- **Custom locales**:
+Custom locales are no longer are supported due to react-intl v5 & webpack limitations.
+Terra currently supports the following locales:
+
+  * en
+  * en-AU
+  * en-CA
+  * en-US
+  * en-GB
+  * es
+  * es-US
+  * es-ES
+  * de
+  * fr
+  * fr-FR
+  * nl
+  * nl-BE
+  * pt
+  * pt-BR
+  * sv
+  * sv-SE
+
+- **Custom terra-base implementation**:
+  `terra-base` and `terra-i18n` are deprecated and not supported alongside terra-application v2.
+  If these dependencies are installed, then they must be removed.
+  If there are custom implementations utilizing these dependencies then they must be rewritten to utilize `terra-application/application-base`.
+
+### Prerequisites
+Upgrading to terra-application v2 has the following requirements:
+
+- Upgrading the project to Node 14. Terra-application v2 requires a minimum of Node 14, therefore the project must be up
+- Upgrading the project to Jest 29. If `jest-config-terra` is used, then it should be upgraded to v3.
+  Refer to the upgrade guide for `jest-config-terra` on how to upgrade to v3.
+
+It is recommended to complete these prerequisites before upgrading to terra-application v2 to make the upgrade easier.
+
+### Code changes
+
+#### Dependency updates
+
+Once the prerequisites listed above are complete, the project can be upgraded to terra-application v2.
+terra-application v2 requires the following dependences versions to be updated as part of the upgrade process:
+* terra-aggregate-translations must be updated to v3.
+* webpack-config-terra must be updated to v4. 
+* terra-dev-site must be updated to v8.
+* rect-intl must be updated to v5 as the above dependences and terra-application v2 all require v5 as a peerDependency.
+
+```diff
+"peerDependencies": {
+-  "react-intl": "2",
++  "react-intl": "5",
+-  "terra-application": "1",
++  "terra-application": "2",
+},
+"devDependencies": {
+-  "@cerner/terra-aggregate-translations": "2",
+-  "@cerner/terra-dev-site": "7",
+-  "@cerner/webpack-config-terra": "3",
++  "@cerner/terra-aggregate-translations": "3",
++  "@cerner/terra-dev-site": "8",
++  "@cerner/webpack-config-terra": "4",
+}
+```
+
+#### Import updates
+
+Terra-application now uses proper submodule export partterns.
+The table below maps the old imports to the new imports.
+
+|                              old imports                               |                            new imports                             |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `import ApplicationBase from 'terra-application'`                      | `import ApplicationBase from 'terra-application/application-base'` |
+| `import ApplicationBase from 'terra-application/lib/application-base'` | `import ApplicationBase from 'terra-application/application-base'` |
+| `import * from 'terra-application/lib/action-menu'`                    | `import * from 'terra-application/action-menu'`                    |
+| `import * from 'terra-application/lib/application-container'`          | `import * from 'terra-application/application-container'`          |
+| `import * from 'terra-application/lib/application-error-boundary'`     | `import * from 'terra-application/application-error-boundary'`     |
+| `import * from 'terra-application/lib/application-intl'`               | `import * from 'terra-application/application-intl'`               |
+| `import * from 'terra-application/lib/application-loading-overlay'`    | `import * from 'terra-application/application-loading-overlay'`    |
+| `import * from 'terra-application/lib/application-navigation'`         | `import * from 'terra-application/application-navigation'`         |
+| `import * from 'terra-application/lib/application-status-overlay'`     | `import * from 'terra-application/application-status-overlay'`     |
+| `import * from 'terra-application/lib/breakpoints'`                    | `import * from 'terra-application/breakpoints'`                    |
+| `import * from 'terra-application/lib/disclosure-manager'`             | `import * from 'terra-application/disclosure-manager'`             |
+| `import * from 'terra-application/lib/modal-manager'`                  | `import * from 'terra-application/modal-manager'`                  |
+| `import * from 'terra-application/lib/navigation-prompt'`              | `import * from 'terra-application/navigation-prompt'`              |
+| `import * from 'terra-application/lib/notification-banner'`            | `import * from 'terra-application/notification-banner'`            |
+| `import * from 'terra-application/lib/slide-panel-manager'`            | `import * from 'terra-application/slide-panel-manager'`            |
+| `import * from 'terra-application/lib/theme'`                          | `import * from 'terra-application/theme'`                          |
+| `import Logger from 'terra-application/lib/utils/logger'`              | `import { Logger } from 'terra-application/utils'`                 |
+| `import EventEmitter from 'terra-application/lib/utils/event-emitter'` | `import { EventEmitter } from 'terra-application/utils'`           |
+| `import * from 'terra-application/lib/workspace'`                      | `import * from 'terra-application/workspace'`                      |
+
+
+#### `react-intl` updates
+
+react-intl v5 no longer exports `intlShape`. All usage of `intlShape` would need to be updated as follows:
+
+```diff
+- intl: intlShape.isRequired,
++ intl: PropTypes.shape({ formatMessage: PropTypes.func }).isRequired,
+```
+
+For more information, refer to the react-intl upgrade guides. You may need to refer to the v3 & v4 upgrade guides in addition to v5.
+
+https://formatjs.io/docs/react-intl/upgrade-guide-5x
+
+https://formatjs.io/docs/react-intl/upgrade-guide-4x
+
+https://formatjs.io/docs/react-intl/upgrade-guide-3x

packages/terra-application-docs/src/terra-dev-site/tool/terra-dev-site/UpgradeGuides.f/v8.0.0.r.tool.mdx

@@ -0,0 +1,4 @@
+# v8 Upgrade Guide
+
+`terra-dev-site v8` requires `react-intl v5` and `terra-application v2` as peerDependencies.
+For more information, refer to the [terra-application v2 upgrade guide](../../app/upgrade-guide).