Introduction

Zustand와 Framer Motion기반의 History 탐색을 지원하는 React Sheet Layer입니다. Framer Motion의 Variant로 손쉽게 Sheet Layer의 Mount, Unmount 애니메이션을 변경할 수 있습니다.

Install

npm install react-sheet-layer-router

Peer dependencies

Layer 요소의 애니메이션을 Framer Motion으로 구현합니다. 따라서, framer-motion도 함께 설치해 주세요.

npm install framer-motion

Getting started

Basic usage

import {
  SheetLayerRoute,
  SheetLayerRouteProvider,
  useSheetLayerRouter,
  mainAnimationVariants,
  subAnimationVariants,
} from "react-sheet-layer-router";

const Home = () => {
  const sheetLayerRouter = useSheetLayerRouter();

  const closeOwnLayer = () => {
    sheetLayerRouter.push(null);
  };

  const openHomeOverviewLayer = () => {
    sheetLayerRouter.push("home.overview");
  };

  return (
    <section>
      <h1>HOME</h1>

      <button onClick={closeOwnLayer}>Close Layer</button>
      <button onClick={openHomeOverviewLayer}>Open Home Overview Layer</button>
    </section>
  );
};

const HomeOverview = () => {
  const sheetLayerRouter = useSheetLayerRouter();

  const closeOwnLayer = () => {
    sheetLayerRouter.push("home");
  };

  return (
    <section>
      <h1>HOME OVERVIEW</h1>

      <button onClick={closeOwnLayer}>Close Layer</button>
    </section>
  );
};

const Main = () => {
  const sheetLayerRouter = useSheetLayerRouter();

  const openHomeLayer = () => {
    sheetLayerRouter.push("home");
  };

  return (
    <main>
      <button onClick={openHomeLayer}>OPEN LAYER</button>

      <p>Main Page Contents...</p>
    </main>
  );
};

const App = () => {
  return (
    <>
      <Main />

      <SheetLayerRouteProvider baseZIndex={1000}>
        <SheetLayerRoute
          routeId="home"
          contentElement={<Home />}
          animationVariants={mainAnimationVariants}
        />

        <SheetLayerRoute
          routeId="home.overview"
          contentElement={<HomeOverview />}
          animationVariants={subAnimationVariants}
        />
      </SheetLayerRouteProvider>
    </>
  );
};

export default App;

With custom animations

import {
  SheetLayerRoute,
  SheetLayerRouteProvider,
  useSheetLayerRouter,
  SheetAnimationVariants,
} from "react-sheet-layer-router";

/** @type {SheetAnimationVariants} */
const customAnimationVariants = {
  /**
   * SheetLayerRoute의 애니메이션은 Label "opened", "closed"의 Variants를 기준으로 재생됩니다.
   * Variants의 작성 방법은 Framer-Motion의 공식 문서를 참조하세요.
   *
   * @see https://www.framer.com/motion/animation/#variants
   */
  opened: {
    transform: "scale(1)",
    opacity: 1,
    transition: {
      duration: 0.3,
      ease: "backOut",
    },
  },
  closed: {
    transform: "scale(0.85)",
    opacity: 0.5,
    transition: {
      duration: 0.2,
      ease: "backIn",
    },
  },
};

const Main = () => {
  const sheetLayerRouter = useSheetLayerRouter();

  const openHomeLayer = () => {
    sheetLayerRouter.push("custom-animation");
  };

  return (
    <main>
      <button onClick={openHomeLayer}>OPEN LAYER</button>

      <p>Main Page Contents...</p>
    </main>
  );
};

const App = () => {
  return (
    <>
      <Main />

      <SheetLayerRouteProvider>
        <SheetLayerRoute
          routeId="custom-animation"
          contentElement={<div>layer contents...</div>}
          animationVariants={customAnimationVariants}
        />
      </SheetLayerRouteProvider>
    </>
  );
};

export default App;

Customizing CSS

구성 요소는 다음 스타일 선택자로 커스터마이징 할 수 있습니다.

.react-sheet-layer-route-layer {
  /** layer styles... */
}

.react-sheet-layer-route-backdrop {
  /** backdrop styles.. */
}

API

SheetLayerRouteProvider

SheetLayerRoute 요소들에게 Context를 전달하는 컴포넌트입니다.

Properties

| Props name | Type | Default | Description | | ----------------- | :--------------------------------------------------------------------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | baseZIndex | number | 1 | 각 레이어의 기준이 되는 zIndex 값을 지정합니다. | | animationVariants | {  opened?: Variant,  closed?: Variant} | undefined | SheetLayerRoute의 기본 Mount, Unmount 애니메이션을 정의합니다.기본으로 제공하는 mainAnimationVariants, subAnimationVariants을 사용할 수 있습니다.또는, 동일한 타입의 사용자 정의 animationVariants를 사용할 수도 있습니다.Variant는 Framer-Motion의 공식 문서를 참조하세요. |

SheetLayerRoute

Sheet Layer Router에서 routeId에 따라 Sheet Layer를 렌더링하는 컴포넌트입니다.

Properties

| Props name | Type | Default | Description | | :---------------- | :--------------------------------------------------------------------------------- | :---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | routeId | string | undefined | 각 라우트의 경로를 나타내는 고유 Id입니다. 객체의 속성 접근자(Property accessors) 중 점 표기법(Dot notation)을 따릅니다. "."(Dot) 문자열은 routeId를 구분하기 위해 사용해야 합니다.중첩된 레이어 구조에서 각 Route의 routeId를 다음과 같이 나타낼 수 있습니다.Home 레이어 Id: homeHome - Overview 레이어 Id: home.overview Home - Overview - Detail 레이어 Id: home.overview.detail | | contentElement | React.ReactNode | undefined | 레이어에서 렌더링할 콘텐츠 노드입니다. | | children | React.ReactNode | undefined | SheetLayerRoute를 react-router-dom의 Nesting 방식으로 작성할 수 있도록 지원하는 속성입니다. | | animationVariants | {  opened?: Variant,  closed?: Variant} | undefined | SheetLayerRoute의 Mount, Unmount 애니메이션을 정의합니다.기본으로 제공하는 mainAnimationVariants, subAnimationVariants을 사용할 수 있습니다.또는, 동일한 타입의 사용자 정의 animationVariants를 사용할 수도 있습니다. Variant는 Framer-Motion의 공식 문서를 참조하세요. |

useSheetLayerRouter

Sheet Layer Router의 현재 Location 정보에 접근하거나, History 상태를 변경할 수 있는 Hook입니다.

Properties

| Props name | Type | Description | | :--------- | :------------------------------------------------ | :----------------------------------------------------------- | | location | RouteHistoryItem | Sheet Layer Route의 현재 위치 정보를 나타내는 상태값입니다. | | push | (partial: RouteHistoryItem | string) => void | 새로운 Location으로 이동합니다. | | replace | (partial: RouteHistoryItem | string) => void | 현재 Location을 새로운 Location으로 대체합니다. | | go | (step: number) => void | History 스택 상의 현재 위치에서 step 만큼 이동합니다. | | forward | () => void | History 스택 상의 현재 위치에서 바로 다음 위치로 이동합니다. | | back | () => void | History 스택 상의 현재 위치에서 바로 이전 위치로 이동합니다. | | clear | () => void | 모든 History 스택과 Location 정보를 초기화합니다. |