import NavigationPromptCheckpointProps from 'terra-navigation-prompt/lib/NavigationPromptCheckpoint?dev-site-props-table';

# NavigationPromptCheckpoint

The NavigationPromptCheckpoint serves as a registration gateway for [NavigationPrompts](/application/terra-application/components/navigation-prompt)
rendered within it. Any NavigationPrompt rendered within the context of a NavigationPromptCheckpoint will register itself with the NavigationPromptCheckpoint
(and any other ancestor checkpoints). The component that implements the NavigationPromptCheckpoint can use the presence of registered NavigationPrompts to
influence its navigational workflows as necessary.

## Usage

```jsx
import { NavigationPromptCheckpoint } from 'terra-application/lib/navigation-prompt';
```

## Props

<NavigationPromptCheckpointProps />

## Details

Any component that navigates between stateful child components should render NavigationPromptCheckpoints around those children.
Each NavigationPrompt rendered by a child will be registered to the NavigationPromptCheckpoints above it in the component tree.
The implementer of each NavigationPromptCheckpoint can use the registered data to prompt the user before navigating or prevent navigation altogether.

### `onPromptChange`

The `onPromptChange` function prop is used to communicate NavigationPrompt registrations to the implementer of a NavigationPromptCheckpoint.
The function is called with an array of objects containing each registered NavigationPrompt's `description` and `metaData` properties.

> Note: The `onPromptChange` prop will be called after each NavigationPrompt registration and removal.
> It may be called more than once with the same array of NavigationPrompt data. Calls to `setState` within onPromptChange
> should be performed only when necessary to minimize component updates.

### `resolvePrompts`

The `resolvePrompts` function can be accessed from the ref to a NavigationPromptCheckpoint. Calling `resolvePrompts` results in a
Promise being returned and a NotificationDialog being presented to the user with options to either confirm or cancel their action.
If the user confirms the action, the dialog will close, and the returned Promise will be resolved. If the user cancels the action,
the dialog will close, and the returned Promise will be rejected. If no NavigationPrompts are detected, no dialog is presented, and
the returned Promise will be resolved.

`resolvePrompts` accepts either an Object or function argument. The Object should contain the text strings used to render the NotificationDialog.
The function should return an Object containing the text strings used to render the NotificationDialog. Additionally, the function will receive
an array of registered NavigationPrompts as an argument. The array of prompts can be used to create dynamic strings based on the current set of registered prompts.

The keys expected in the resolvePrompts Object or return value include:

|Key|Type|Description|
|---|---|---|
|`title`|String|The title of the NotificationDialog.|
|`startMessage`|String|The starting message of the NotificationDialog.|
|`content`|Node|The content of the NotificationDialog.|
|`endMessage`|String|The ending message of the NotificationDialog.|
|`acceptButtonText`|String|The text to render within the NotificationDialog's accept button.|
|`rejectButtonText`|String|The text to render within the NotificationDialog's reject button.|
|`buttonOrder`|String|A string indicating which action should be rendered first, required. Supported values include: `acceptFirst`, `rejectFirst`.|
|`emphasizedAction`|String|A string indicating which action should be rendered as emphasized. Supported values include: `accept`, `reject`, and `none`. Defaults to `none`.|

A utility function called `getUnsavedChangesPromptOptions` allows direct consumers of the NavigationPromptCheckpoint
to match the prompt messaging provided by the components within `terra-application`.

```jsx
import React, { useContext, useRef } from 'react';
import { ApplicationIntlContext } from 'terra-application/lib/application-intl';
import { NavigationPromptCheckpoint, getUnsavedChangesPromptOptions } from 'terra-application/lib/navigation-prompt';

const ExampleComponent = () => {
  const checkpointRef = useRef();
  const applicationIntl = useContext(ApplicationIntlContext);

  function resolvePrompts() {
    checkpointRef.current.resolvePrompts(getUnsavedChangesPromptOptions(applicationIntl)).then(() => { ... });
  }

  return (
    <NavigationPromptCheckpoint
      ref={checkpointRef}
    >
      {...}
    </NavigationPromptCheckpoint>
  );
}
```