@peassoft/mnr-web-topline

Topline widget for Memorize'n'Revise web applications.

Installation

npm i @peassoft/mnr-web-topline

Usage Example

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

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.