npm package: @peassoft/mnr-web-topline
Description: Peassoft Topline widget for mem'n'rev web applications
Latest version: 4.1.0

# @peassoft/mnr-web-topline

Topline widget for Memorize'n'Revise web applications.

## Installation

```shell
npm i @peassoft/mnr-web-topline
```

## Usage Example

```jsx
import { useCallback, type JSX } from 'react';
import WebTopline, {
  type ToplineService,
  type ToplineUser,
  ToplineEventName,
} from '@peassoft/mnr-web-topline';

export default function Topline(): JSX.Element {
  const handleReady = useCallback(
    (toplineService: ToplineService, toplineUser: ToplineUser | null, isUserKnown: boolean) => {
      toplineService.on(ToplineEventName.Login, user => {/*...*/});
      toplineService.on(ToplineEventName.Signup, user => {/*...*/});
      toplineService.on(ToplineEventName.Logout, () => {/*...*/});
      toplineService.on(ToplineEventName.UserChange, user => {/*...*/});
      toplineService.on(ToplineEventName.SyncNotification, syncId => {/*...*/});

      // Use `toplineUser`...

      // Use `isUserKnown` e.g. to determine whether to fetch the default set of data.
    },
    [],
  );

  return (
    <WebTopline
      onReady={handleReady}
      onError={(err: Error) => {/* Handle the error */}}
    />
  );
}
```

## API Reference

### Props

```ts
type ToplineProps = {
  /** User to use in SSR */
  ssrUser?: ToplineUser | null;

  /**
   * If set to `true`, the link to the home page opens the home page in a separate window.
   *
   * For use in PWA.
   */
  forceBlankHomeLink?: boolean;

  /** Callback that is invoked after user is restored from a local DB */
  onReady?: (
    toplineService: ToplineService,
    user: ToplineUser | null,
    isUserKnown: boolean,
  ) => unknown;

  /**
   * Callback that is invoked if an unexpected error is caught by React's error boundary
   * component
   *
   * This callback invokation will almost always indicate that the user management system
   * is broken or in an undefined state. Thus, the hosting app should not try to recover
   * from this error, but take reasonable measures depending on the situation.
   */
  onError?: (err: Error) => unknown;
};
```

### `onReady` Callback Function Parameters

* `toplineService: ToplineService` - An object containing functionality of the topline (see below).

* `user: ToplineUser | null` - User data as it's restored from the local DB. Later, topline will make an attempt to fetch fresh user data from the server which may result in the following scenarios:

  * User data fetched is identical to the local data: Nothing will happen.

  * User data fetched defers from the local data: `ToplineEventName.UserChange` event will be emitted on the `toplineService`.

  * Request is not authenticated: `ToplineEventName.Logout` event will be emitted on the `toplineService`.

  * Request fails (e.g. no Internet connection): Nothing will happen.

* `isUserKnown: boolean` - Flag that if set to `true` indicates that the current browser once been used for logging in Memorize'n'Revise. The `false` value is possible when `user` value is `null`.



### `ToplineService`

#### Events

* `ToplineService.on(ToplineEventName.Login, (user: ToplineUser) => unknown)` - Emitted after user has successfully logged in (possibly, after password restoration procedure).

* `ToplineService.on(ToplineEventName.Signup, (user: ToplineUser) => unknown)` - Emitted after user has successfully created a new account and is now logged-in.

* `ToplineService.on(ToplineEventName.Logout, () => unknown)` - Emitted when:

  * user has explicitely logged out;

  * a sync notification is received about user's log-out in another application instance;

  * initialization sync request resulted in status code 401.

* `ToplineService.on(ToplineEventName.UserChange, (user: ToplineUser) => unknown)` - Emitted when:

  * a sync notification is received about user's data having been changed in another application instance;

  * initialization sync returns different user data as of stored in the local DB.

* `ToplineService.on(ToplineEventName.SyncNotification, (syncId: string) => unknown)` - Emitted when a notification about sync is received. `syncId` is supposed to be used by applications to filter out syncs which are initiated by the application itself.

#### Methods

* `ToplineService.grantToken(): string | null` - Get current `grantToken` to use in a request which requires authorization.

* `ToplineService.upgradeGrantToken(): Promise<string | null>` - Upgrade `grantToken` with `refreshToken`. Supposed to be used after a request that used an expired `grantToken` resulted in status code `401`.

* `ToplineService.logIn(): void` - Command to open logging-in form.

* `ToplineService.createAccount(): void` - Command to open creating account form.