@procore/labs-banners

Banners

A handy component you can insert into a form or inline on a page to communicate results of an application action which was performed with some status (e.g. success, warnings, failure or just information and others).

Installation

yarn add @procore/labs-banners

Dependencies

@procore/core-react and react are listed as external peer dependencies. The package will not bundle the code, and requires the app client to provide it as a dependency. The external peer dep is to assure React Context is consistent in a client's React tree, the child consumers can reference the correct parent provider. If the package uses latest features or bug fixes and a new minimum version of core-react is required, it should be considered a breaking change as the peer dependency version must be met.

Usage

import { I18nProvider } from '@procore/core-react';
import { Banners } from '@procore/labs-banners';

Motivation

A large amount of components need to interact with users and provide feedback messages for users actions. Main reason of Banners component is to prevent code duplication and create common and consistent interface to handle storing and displaying important informations for users.

Key points:

• Straightforward API

const INFO_BANNER = 'INFO_BANNER';

showBanner({
  id: INFO_BANNER,
  msg: 'Some important information',
  variant: 'success',
});

• Easy configuration

const ACTION_BANNER = 'ACTION_BANNER';

showBanner({
  id: ACTION_BANNER,
  msg: 'Some important information',
  variant: 'success',
  action: {
    title: 'Button title',
    handler: (banner) => console.log('button clicked', banner),
  },
  dismissible: true,
  afterClose: (banner) => console.log('button clicked', banner),
});

• Delete programmatically by ID

const INFO_BANNER = 'INFO_BANNER';

hideBanner(INFO_BANNER);

• Id uniqueness handling (we remove previous banner with the same id)

// state - [{id: 'INFO_BANNER', msg: 'Some important information', variant: 'success'}]
const INFO_BANNER = 'INFO_BANNER';

showBanner({
  id: INFO_BANNER,
  msg: 'Another important information',
  variant: 'success',
});

// state - [{id: 'INFO_BANNER', msg: 'Another important information', variant: 'success'}]

Using built-in BannersContext

• Banners.Provider: Component that supply store for banners.
• Banners: Component that consumes values from the nearest context (Banners.Provider) and renders to the tree.
• useBanners: A function wrapper around React.useContext(BannersContext).

() => {
  const Inner = () => {
    const { showBanner, hideBanner, hideAllBanners } = useBanners();

    return (
      <FlexList marginBottom="xl">
        <Button
          variant="secondary"
          onClick={() =>
            showBanner({
              id: '2',
              variant: 'success',
              msg: 'Success banner description',
            })
          }
        >
          Show Success Banner
        </Button>
        <Button variant="secondary" onClick={() => hideBanner('2')}>
          Hide Success Banner
        </Button>
        <Button variant="secondary" onClick={() => hideAllBanners()}>
          Hide All Banners
        </Button>
      </FlexList>
    );
  };

  const bannersShownByDefault: Banner[] = [
    {
      id: '1',
      msg: 'Info banner description',
      variant: 'info',
      dismissible: false,
    },
  ];

  return (
    <I18nProvider>
      <Banners.Provider initialValue={bannersShownByDefault}>
        <Inner />
        <Banners />
      </Banners.Provider>
    </I18nProvider>
  );
};

Using own State

• Banners.Bar: Component that consumes and renders Banners.

() => {
  const Inner = () => {
    const bannersShownByDefault: Banner[] = [
      {
        id: "1",
        msg: "Info banner description",
        variant: "info",
        dismissible: false,
      },
    ];

    const [banners, setBanners] = React.useState<Banner[]>(
      bannersShownByDefault
    );

    const hideBanner = (id: Banner["id"]) => {
      setBanners((prevBanners) =>
        prevBanners.filter((banner) => banner.id !== id)
      );
    };

    const showBanner = (newBanner: Banner) => {
      const isBannerExists = banners.find(
        (banner) => banner.id === newBanner.id
      );
      if (!isBannerExists) {
        setBanners((prevBanners) => [newBanner, ...prevBanners]);
      }
    };

    const hideAllBanners = () => setBanners([]);

    return (
      <>
        <FlexList marginBottom="xl">
          <Button
            variant="secondary"
            onClick={() =>
              showBanner({
                id: "2",
                variant: "success",
                msg: "Success banner description",
              })
            }
          >
            Show Success Banner
          </Button>
          <Button variant="secondary" onClick={() => hideBanner("2")}>
            Hide Success Banner
          </Button>
          <Button variant="secondary" onClick={() => hideAllBanners()}>
            Hide All Banners
          </Button>
        </FlexList>
        <Banners.Bar banners={banners} hideBanner={hideBanner} />
      </>
    );
  };
  return (
    <I18nProvider>
      <Inner />
    </I18nProvider>
  );
};