@procore/labs-banners
v3.0.0
Published
Set of convenient components managing banners
Downloads
32
Maintainers
Keywords
Readme
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 aroundReact.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 rendersBanners
.
() => {
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>
);
};