react-native-pure-overlay

Easy, Light, Awesome react native overlay library. Whether it's a modal, bottom sheet, alert, loading screen, or anything else you need, this library can handle it all.

react-native-pure-overlay는 최소한의 dependancy로 modal, bottom sheet, loading 등 overlay component를 선언적으로 제어하기 위해 만들어졌습니다. 모두 View, Pressable, Animated 등 react-native 내장 객체를 이용해 만들었으며, ios에서 여러가지 제약사항을 가진 Modal 컴포넌트는 사용하지 않았습니다. (현재는 Modal, BottomSheet, Loading을 지원하지만 앞으로 SnackBar, Toast 등을 추가 지원할 예정입니다.)

react-native-pure-overlay를 사용하면 더이상 매번 스크린에 모달 컴포넌트를 배치하고 visible state를 선언하고 props를 넘길 필요 없이 선언적으로 모달을 관리할 수 있습니다.

1const { openModal, closeModal } = usePureModal();
2
3openModal({
4  title: 'hello, world',
5  body: 'this is pure modal',
6  onPressConfirm: closeModal,
7  onPressBackButton: closeModal,
8});

또한 기본 제공하는 openDeferredModal을 통해 모달에서의 사용자 행동을 가져와 훨씬 간단하고 직관적으로 코드를 설계할 수 있습니다.

1const { openDeferredModal, closeModal } = usePureModal();
2
3const onPressSubmit = async () => {
4  const action = await openDeferredModal({
5    title: 'hello, world',
6    body: 'this is pure modal',
7    onPressConfirm: closeModal,
8    onPressBackButton: closeModal,
9  });
10  if (action === 'pressedConfirm') {
11    Alert.alert('you should press confirm button, right?');
12  }
13};

Installation

npm install @pureboard/react-native-pure-overlay

# or using yarn
yarn add @pureboard/react-native-pure-overlay

Usage

사용할 컴포넌트 정의하기

react-native-pure-overlay는 직접 컴포넌트를 제공하는 방식이 아니라, 사용자가 원하는 컴포넌트를 Overlay Component로써 핸들링하는 인터페이스를 제공하는 라이브러리입니다. 사용자가 직접 Modal Component와 BottomSheet Component를 정의해야만 합니다.(BottomSheet의 경우 slide down으로 움직이는 컴포넌트 베이스는 제공합니다.)

1export interface CustomModalProps {
2  title: string;
3  body: string;
4  confirmLabel: string;
5  onPressConfirm: () => void;
6}
7
8const CustomModal = (props: CustomModalProps) => {
9    ...
10}
11
12
13export interface SampleBottomSheetProps {
14  title?: string;
15  content?: React.ReactNode;
16  onPressClose?: () => void;
17  buttonLabel?: string;
18  onPressButton?: () => void;
19}
20
21export const SampleBottomSheet = (props: SampleBottomSheetProps) => {
22    ...
23}

createPureOverlay

위에서 선언한 컴포넌트를 overlayId와 함께 propTypes를 묶어 verlayPropList 타입으로 선언합니다. overlayId는 프로젝트에서 각 컴포넌트를 식별하는데 사용되며, 자유롭게 작명하시면 됩니다.

1export type ProjectOverlayPropList = {
2  custom: CustomModalProps;
3  sample: SampleBottomSheetProps;
4  loading: {};
5};

이렇게 선언한 ProjectOverlayPropList를 createPureOverlay에 제네릭으로 넘겨 PureOverlay 객체를 반환받고, 프로젝트 루트를 Provier로 감싸줍니다.

1import { createPureOverlay } from '@pureboard/react-native-pure-overlay';
2
3const PureOverlay = createPureOverlay<ProjectOverlayPropList>();
4
5const App = () => {
6  return (
7    <PureOverlay.Provider>
8      <YourScreen />
9    </PureOverlay.Provider>
10  );
11};
12export default App;

Modal

PureOverlay.Provider 하위에 PureOverlay.Modal 컴포넌트를 배치해줍니다. PureOverlay.Modal은 총 3가지 props를 지닙니다.

• Component: Modal로써 제어할 컴포넌트를 받습니다.
• resolveKeys: Component의 props 중에 openDeferredModal의 결과로써 사용자 행동을 resolve할 prop과 어떤 값으로 resovle 할것인지에 대한 정의입니다.
• overlayId: 이후 handler를 호출할 때 식별자로써 사용됩니다.

1const App = () => {
2  return (
3    <PureOverlay.Provider>
4      <YourScreen />
5      <PureOverlay.Modal
6        Component={CustomModal}
7        resolveKeys={{ onPressConfirm: 'pressedConfirm' }}
8        overlayId={'custom'}
9      />
10    </PureOverlay.Provider>
11  );
12};
13export default App;

<PureOverlay.Modal>로 넘겨주는 컴포넌트는 프로젝트 내부 어디서든 usePureModal hook을 호출하여 핸들링할 수 있습니다.

1import { usePureModal } from '@pureboard/react-native-pure-board';
2
3const { openModal, openDeferredModal, closeModal } = usePureModal<
4  ProjectOverlayPropList,
5  'custom',
6  'pressedConfirm'
7>('custom');

openModal과 openDeferredModal은 params로 Modal Component의 props를 받으며, 모달 여백 터치에 해당하는 onPressBackDrop, 안드로이드 물리버튼에 해당하는 onPressBackButton, 모달 배경의 opacity에 해당하는 backgroundOpacity를 추가로 넘겨줄 수 있습니다.

1interface BasePureModalProps {
2  onPressBackButton?: () => void;
3  onPressBackDrop?: () => void;
4  backgroundOpacity?: number;
5}
6
7//openModal
8(params: CustomModalProps & BasePureModalProps)=> void;
9
10//openDeferredModal
11(params: CustomModalProps & BasePureModalProps)=> Promise<ResovleType>;

1openModal({
2  title: 'custom modal',
3  body: 'this params will pass to CustomModal Component as props',
4  confirmLabel: 'OK',
5  onPressConfirm: () => {
6    console.log('close modal');
7    closeModal();
8  },
9  onPressBackButton: closeModal,
10  onPressBackDrop: closeModal,
11  backgroundOpacity: 0.5,
12});
13
14openDeferredModal({
15  title: 'custom modal',
16  body: 'this params will pass to CustomModal Component as props',
17  confirmLabel: 'OK',
18  onPressConfirm: () => {
19    console.log('close modal');
20    closeModal();
21  },
22  onPressBackButton: closeModal,
23  onPressBackDrop: closeModal,
24  backgroundOpacity: 0.5,
25}).then((action) => {
26  if (action === 'pressedConfirm') {
27    return console.log('pressedConfirm');
28  }
29  if (action === 'pressedBackButton') {
30    return console.log('pressedBackButton');
31  }
32  if (action === 'pressedBackDrop') {
33    return console.log('pressedBackDrop');
34  }
35});

openDeferredModal을 사용할 때, BaseProps인 onPressBackButton은 "pressedBackButton"으로, onPressBackDrop은 "pressedBackDrop"으로 resolve됩니다. 또한, PureOverlay.Modal에 resolveKeys로 {onPressConfirm: 'pressedConfirm'}으로 바인딩 해주었기 때문에, 만약 사용자가 확인 버튼을 눌러 onPressConfirm을 호출했다면 openDeferredModal은 pressedConfirm으로 resolve 됩니다.

openDeferredModal을 사용하면 아래처럼 모달과 핵심 데이터를 주고받을 필요 없이, 모달로부터 사용자 행동을 받아와 직관적인 코드 설계가 가능해집니다.

1import { usePureModal } from "@pureboard/react-native-pure-board";
2
3const MyScreen = () => {
4  const { openDeferredModal, closeModal } = usePureModal<
5    ProjectOverlayPropList,
6    "custom"
7  >("custom");
8
9  const onPressRemoveItem = async () =>{
10    const action = await openDeferredModal({
11        title: "are you sure?",
12        body: "If you press confirm, this item will remove!",
13        onPressConfirm:closeModal,
14        onPressBackButton:closeModal,
15        onPressBackDrop:closeModal,
16    })
17    if(action === 'pressedConfirm'){
18        removeItemMutation();
19    }
20  }
21
22  return <Container>
23    <Button label={'remove item'} onPress={onPressRemoveItem}>
24  </Container>
25};

BottomSheet

1export type ProjectOverlayPropList = {
2  custom: CustomModalProps;
3  sample: SampleBottomSheetProps;
4  loading: {};
5};
6
7const PureOverlay = createPureOverlay<ProjectOverlayPropList>();
8
9const App = () => {
10  return (
11    <PureOverlay.Provider>
12      <MainScreen />
13      <PureOverlay.BottomSheet
14        Component={SampleBottomSheet}
15        resolveKeys={{
16          onPressButton: 'pressedButton',
17          onPressClose: 'pressedCloseButton',
18        }}
19        overlayId={'sample'}
20      />
21    </PureOverlay.Provider>
22  );
23};
24export default App;

BottomSheet도 전체적으로 Modal과 동일합니다. resolveKeys를 통해 BottomSheet Component Props와 resolve key를 바인딩할 수 있습니다.

이렇게 주입한 BottomSheet는 openPureBottomSheet hook을 통해 핸들링할 수 있습니다.

1const { openBottomSheet, openDeferredBottomSheet, closeBottomSheet } =
2  usePureBottomSheet<
3    ProjectOverlayPropList,
4    'sample',
5    'pressedButton' | 'pressedCloseButton'
6  >('sample');
7
8const openSampleBottomSheet = () => {
9  openBottomSheet({
10    title: 'Hello, Pure!',
11    onPressBackDrop: closeBottomSheet,
12    onPressClose: closeBottomSheet,
13    content: 'this is normal bottom sheet',
14  });
15};
16
17const openSampleDeferredBottomSheet = async () => {
18  const action = await openDeferredBottomSheet({
19    title: 'Hello, PureDeferredBottomSheet!',
20    onPressBackDrop: closeBottomSheet,
21    onPressBackButton: closeBottomSheet,
22    buttonLabel: 'resolve!',
23    onPressButton: closeBottomSheet,
24  });
25
26  Alert.alert(action);
27};

openBottomSheet와 openDeferredBottomSheet는 미리 선언한 BottomSheetProps 이외에 몇가지 BaseProps를 추가로 넘겨줄 수 있다.

1interface BasePureBottomSheetProps {
2  onPressBackDrop?: () => void;
3  onPressBackButton?: () => void;
4  backgroundOpacity?: number;
5  fullScreen?: boolean;
6  containerStyle?: StyleProp<ViewStyle>;
7}
8
9//openBottomSheet
10(params: SampleBottomSheetProps & BasePureBottomSheetProps)=> void;
11
12//openDeferredBottomSheet
13(params: SampleBottomSheetProps & BasePureBottomSheetProps)=> Promise<ResovleType>;

Loading

PureOverlay.Loading은 Component를 optional하게 받으며, 아무것도 넘기지않을 경우 기본적으로 ActivityActivity가 화면 중앙에 렌더링됩니다.

1export type ProjectOverlayPropList = {
2  custom: CustomModalProps;
3  sample: SampleBottomSheetProps;
4  loading: {};
5  viewLoading: ViewProps;
6};
7
8const PureOverlay = createPureOverlay<ProjectOverlayPropList>();
9
10const App = () => {
11  return (
12    <PureOverlay.Provider>
13      <MainScreen />
14      <PureOverlay.Loading overlayId={'loading'} />
15      <PureOverlay.Loading Component={View} overlayId={'viewLoading'} />
16    </PureOverlay.Provider>
17  );
18};
19export default App;

PureOverlay.Loading으로 주입한 Loading Overlay는 usePureLoading hook으로 핸들링할 수 있습니다.

1const { showLoading, hideLoading } = usePureLoading<
2  ProjectOverlayPropList,
3  'loading'
4>('loading');
5
6const handleLoading = () => {
7  showLoading();
8  setTimeout(hideLoading, 5000);
9};

showLoading의 params를 통해 Compoenent에 props를 넘길 수 있으며, 추가로 backgroundOpacity를 넘겨줄 수 있습니다.

1const { showLoading, hideLoading } = usePureLoading<
2  ProjectOverlayPropList,
3  'viewLoading'
4>('viewLoading');
5
6const handleLoading = () => {
7  showLoading({
8    style: {
9      width: 100,
10      heigth: 100,
11      borderRadius: 50,
12      backgroundColor: 'green',
13    },
14    backgroundOpacity: 0.5,
15  });
16  setTimeout(hideLoading, 5000);
17};