daangn / stackflow

🧱 Mobile-first stack navigator framework with composable plugin system

Introduction

Karrotframe is rebranded with "Stackflow". View full documentation and demo on https://stackflow.so

Stackflow is a project that implements Stack Navigation UX, which is mainly used in mobile devices (iOS/Android, etc.) in a JavaScript environment. So, it can help to easily develop hybrid apps and webviews.

• Stack screens and keep scrolling state.
• It supports transition effects that stack up the screen and the transition effect that disappears when you go back.
• Supports iOS-style swipe back.
• It passes the necessary parameters to the screen to be switched.

So, what advantages does Stackflow have compared to the existing navigation library?

• You can only use the state for stacks and transitions separately without UI. You can tear off the UI and use it as you like.
• You can inject any additional extensions you want between lifecycles through the plugin interface.
• Since the core logic and integration layers are separated, it can be integrated with various front-end frameworks. (Now only supports React)
• Because render logic and UI can be injected from the outside, mobile webview and desktop development can be done in one codebase.
• Server-Side Rendering is supported. (ReactDOMServer.renderToString)

Getting Started

$ yarn add @stackflow/core @stackflow/react

import ReactDOM from 'react-dom'

import { stackflow } from '@stackflow/react';

const { Stack, useFlow } = stackflow({
  // ...
});

const App: React.FC = () => {
  return (
    <Stack />
  );
};

ReactDOM.render(<App />, ...)

Integration Examples

• Standalone
• Gatsby
• Next.js (💥 Not Recommended)

To integrate Stackflow with a specific framework with routing capabilities, the framework requires an extension to manually call the preload API. However, Next.js does not officially support the preload API.

Contributors

To contribute new features or options to Stackflow, please check Contribution Guide

License

MIT

stackflow's Issues

ESM Support

[Karrotframe] Suggest plugin to fix refresh issue

This would be fallback plugin to fix refresh issue

import { PluginType, NavigatorPluginType } from '@karrotframe/plugin'
import React, {createContext, useContext, useState} from 'react'

export const ContextPersistentPathPlugin = createContext<{
    guideMessage: any
    setGuideMessage: (guideMessage: string) => void
}>(null as any)

export const PersistentPathPluginProvider: React.FC = (props) => {
    const [guideMessage, setGuideMessage] = useState('')
    return (
        <ContextPersistentPathPlugin.Provider value={{ guideMessage, setGuideMessage }}>
            {props.children}
        </ContextPersistentPathPlugin.Provider>
    )
}

export const usePersistentPlugin = (): PluginType  & {
    setGuideMessage: (params: string) => any;
    guideMessage: string;
} => {
    const {guideMessage, setGuideMessage} = useContext(ContextPersistentPathPlugin)
        return {
          lifeCycleHooks: {
            onInsertScreenInstance: async (ctx) => {
              if(ctx.ptr === -1 && ctx.screenInstance.screenId !== '/' && ctx.screenInstances.length === 0) {
                  const previousPathInfoString = localStorage.getItem('screenPath');
                  if (!previousPathInfoString) {
                      setGuideMessage('Can not go back anymore')
                      return;
                  }
                  const {currentScreenInstances, isMatchedPath } = JSON.parse(previousPathInfoString);

                  const hasHistoryStack = isMatchedPath === ctx.screenInstance.screenId;
                  if (!hasHistoryStack) {
                      setGuideMessage('Can not go back anymore')
                      localStorage.removeItem('screenPath');
                      return;
                  }

                  const previousScreenPathArr = Object.keys(currentScreenInstances).map(index => currentScreenInstances[index]);
                  const screenPath = [...previousScreenPathArr, {...ctx.screenInstance, id: (previousScreenPathArr.length + 1).toString(), nestedRouteCount: 0}]
                  ctx.options?.setScreenInstancePtr?.(-1 + previousScreenPathArr.length);
                  ctx.options?.setScreenInstances?.(screenPath)
              }
            },
              beforePush: async (ctx) => {
                const currentScreenInstances = ctx.screenInstances.reduce((acc: any, curr: any, index: number) => {
                    acc = {
                        ...acc,
                        [index+1]: curr
                    }
                    return acc
                }, {});
                const pathInfo = {
                    currentScreenInstances,
                    isMatchedPath: ctx.to
                }
                localStorage.setItem('screenPath', JSON.stringify(pathInfo));
              }
         },
            setGuideMessage,
            guideMessage
        }
}

export const persistentPathPlugin: NavigatorPluginType = {
    name: 'persistentPathPlugin',
    provider: PersistentPathPluginProvider,
    executor: usePersistentPlugin,
}

ScreenHelmet의 onTopClick 관련해서 궁금한 점이 있습니다.

1. 아래 주석의 상단바의 의미가 궁금합니다. ㅎㅎ

  /**
   * 상단바를 클릭했을때 호출될 콜백을 설정합니다
   */
  onTopClick?: () => void

• 상단바의 의미가 Navbar 전체를 의미하나요? 아니면, 아래 푸른색 영역을 의미하나요?

2. 푸른색 영역(navbarCenterMainEdge)

• 위 그림에서 푸른색 영역(navbarCenterMainEdge)을 클릭했을 때, 최상단으로 스크롤되게 타이틀을 클릭했을 때가 구현되어 있는데,
  "네비게이션의 타이틀" 클릭했을 때로 아닌 푸른색 영역(navbarCenterMainEdge) 추가로 만드신 이유에 대해 여쭤봐도 괜찮을까요?

기능 건의해요!

현황

• si로 1일 땐 x버튼이 나오고, 1 이상일 땐 화살표 버튼이 나오면서 si가 낮은 숫자로 이동해요.

배경

• 한 페이지 컴포넌트 내에서 step이란 상태로 페이지를 그리고 싶어요.
• 덧붙이자면, 초기 상태를 step 1으로 만들고 step 2로 넘어가는 버튼을 클릭하면 하나의 페이지 이지만 step 2에 맞는 페이지를 그리고 싶어요.
• 그리고 step 2에서 뒤로가기 버튼을 눌렀을 때 step 1으로 보내고 싶어요.
• 즉, step 1일 땐 x 표시가, step 2일 땐 step 1으로 가는 화살표가 떴으면 좋겠어요.
  (지금은 한 페이지이기 때문에 step과 상관없이 뒤로가기가 돼요)
• 자세히 말하면, useState를 사용하여 step 2로 가는 버튼을 누를 때 setStep으로 step 이란 상태를 2로 만들어줄 수 있지만
• 뒤로가기를 누를 땐 setStep을 해줄 수가 없어요.

건의

• 뒤로가기 버튼에 기능을 넣을 수 있으면 좋겠어요.
• 예를 들어 setStep을 넣어 step을 1로 변형 시킬 수 있다 같이요!
• 아니면 한 페이지 내에서 또 다른 si가 있어 전체 흐름과 별개로 해당 페이지에서 캐롯프레임을 사용하고 싶어요!

transition life cycle 함수를 사용할수있도록한다.

onEntered등의 페이지 전환 완료시점에 호출되는 콜백을 전할수 있도록 합니다.

[공통] closeButtonLocation 옵션 마련하기

X 버튼의 위치를 옮길 수 있도록

안드로이드 화면 전환

Pull Request 템플릿 추가 건의

PR 템플릿이 있으면 좋을 것 같다고 생각합니다.

Depth보다 더 큰 값을 pop 할 때 발생하는 에러

page depth가 0일 때 pop을 하거나, depth가 1일 때 pop(2)를 하는 등, depth보다 큰 값을 pop 하려 할 때 에러가 발생합니다.
이 부분에 대해서 depth가 0일 때 pop하려 하면 무시하고, depth보다 큰 값을 pop하려 하면 무시하는 코드가 추가되었으면 해요.

아래 코드에서 에러가 발생하고 있어요.

// useNavigator.ts in pop at line 96:5
// Cannot read property 'id' of undefined

const promise = store.screenInstancePromises.get(targetScreenInstance.id)

[공통] 애니메이션 비활성화 기능

애니메이션을 끄는 옵션을 제공해주세요.

[Navigator] Support Web Browser environment

지금 await push() 인터페이스의 경우 "앞으로 가기" 기능을 사용하는 경우 문제가 될 수 있어요. 현재 Promise를 통해 Imperative하게 다음 화면으로부터 콜백을 받는데, 이걸 선언적으로 바꿔내야해요. v1 로드맵에 포함.

as-is:

const { push } = useNavigator()
  
const onClick = async () => {
  // 앞으로 가기 후 Submit하면 이 콜백에 걸리지를 않음.
  const data = await push(...)
  console.log(data)
}

to-be(Pseudo Code):

const { push } = useNavigator({
  onPopped(from, data) {
    switch (from) {
      case '...':
        console.log(data)
        break
    }
  }
})

const onClick = () => {
  push(...)
}

CONTRIBUTING.md 내용 추가 제안

경험

메인테이너 분들은 어떤 IDE를 쓰실진 모르겠지만, 저 같은 경우엔 vscode를 사용합니다.
기여하기 위해 karrotframe을 클론 받고 프로젝트를 열면 아래 사진과 같이 IDE가 패키지 인식을 못합니다.

근데 신기한점은 yarn && cd packages/karrotframe && yarn build:dts && yarn build:runtime --watch 명령어를 실행시 문제 없이 작동합니다.

그래서 저는 의아한 채로 IDE의 제 기능을 활용하지 못 한채 코드를 수정하며 기여를 하였습니다.

해결 방법

IDE가 패키지를 인식하도록 하는 방법은 매우 간단하였는데요.

1번 방법

settings.json에 잘 설정 되어 있어, vscode로 프로젝트를 첫 오픈 시 우측 하단에 아래와 같은 문구와 함께 TypeScript 버전을 교체하겠냐는 팝업이 뜹니다.저는 이런거 함부로 안 누르는 성격이라..

allow를 클릭 후 vscode를 껐다 키면 아래와 같이 IDE가 인식을 하게 됩니다.

2번 방법

vscode를 켜논 상태에서, ⌘ + ⇧ + P를 하면 아래와 같은 상태가 됩니다.

해당 입력창에 아래와 같이 채워주고 엔터를 누르면,
>TypeScript: Select TypeScript Version...

아래 사진과 같은 선택 창이 나오는데 Use Workspace Version 4.1.5-pnpify 부분을 클릭후 vscode를 재시작 합니다.

결론

제가 yarn2, workspace, pnp 등에 대한 지식이 없다보니 이런 실수를 범했네요.
혹시라도 저와 같이 IDE가 인식을 못해 당황해 할 수 있는 분들을 위해 CONTRIBUTING.md에 위 해결 방법에 대한 내용을 추가하는게 좋지 않을까? 라는 생각을 해보았습니다.

의견 부탁드립니다!

react-transition-group에서 findDOMNode API Warning

nodeRef API를 사용해야함

back swipe animation을 넘기다 실패했을때 history만 pop 되는 이슈

• history.push를 사용하였을때 발생함
• 실제 페이지는 뒤로가지지 않고, history만 pop되기 때문에, history가 꼬이게됨

[iOS] 상단바 탭할시에 맨 위으로 스크롤하기

[iOS] Keyboard Avoiding View

iOS에서 키보드가 활성화되면 상단바가 위로 올라가는 문제

1.0 Roadmap

Karrotframe 0.x 은 웹 기반 Transition Animation을 PoC하는 수준에서 당근마켓 내부에서 사용되었어요. 1.0은 좀 더 나은 수준의 개발 경험, React Concurrent UI 패턴 지원, 프로덕션 수준의 코드 안정화 등을 하면 좋겠어요.

• Renaming: Karrotframe은 사내에서 사용되던 프로젝트명 이에요. 이를 계속 가져가기보다는 좀 더 직관적인 새로운 이름이 필요해요.
• Zero-dependency: MobX, React Transition Group 등 무거운 Dependency들이 많이 존재합니다. 이것들을 모두 걷어내야해요.
• Suspense 등 React Concurrent UI 패턴 지원: Relay를 사용하는 프로젝트에서 useTransition과 함께 쓸 수 있도록 Concurrent UI 패턴을 지원해야해요.
• Test, Test, Test: 누구나 손 쉽게 Contribution 할 수 있도록 테스트가 지원되어야해요.

기타 1.0 로드맵에 아이디어가 있으신 분들은 댓글 부탁드려요~

MobX 걷어내기

https://bundlephobia.com/[email protected]

대부분의 번들 사이즈를 MobX가 차지하고 있어요.

바닥에 붙어다니는 메뉴가 안 따라다니는 문제

transform: translateX()

내부에서

position: absolute;
top: 0;

가 불가능한 문제. (Safari, Chrome 모두 불가능)

Suspense의 fallback으로 ScreenHelmet을 넣었을 때 의도치 않은 동작을 함

다음과 같은 코드에서 PullToRefresh를 하면 ScreenHelmet이 사라져요.

const MyPage = () => {
  return (
    <Base>
      <ScreenHelmet title="나의 페이지" />
      <PullToRefresh
        ...
      />
    </Base>
   )
}

const withSuspense = (Comp, LoadingComp) => {
  const WithSuspense = () => {
    return (
      <Suspense fallback={LoadingComp}>
        <Comp />
      </Suspense>
    )
  }

  return WithSuspense
}

export default withSuspense(
  MyPage,
  <>
    <ScreenHelmet />
    <PageLoading />
  <>
)

참고로 appendRight에 인스턴스를 넣어주면 정상 동작해요.

popAll 기능이 있으면 좋을 것 같아요

같은 페이지인데 진입점이 다른 경우 진입점에 따라 분기해주고 있는데 가끔 놓칠 때가 있어요

열려있는 screen의 depth만큼 pop을 해주는 popAll 함수가 제공되면 좋을 것 같아요

한 스크린 스택 내에서 History로 처리하기

멀티 페이지 Form 같은 경우 한 스크린에서 백버튼이 눌려야하는 문제가 있음. 처리 필요.

@beautifulife

[Android] 백버튼 누를 시에 창이 닫혀버림

세탁 → 제3자동의창 → 당근마켓제3자동의창 → 백버튼

정상

제3자동의창이 닫히고 원래 화면으로 돌아감

버그

세탁 미니가 닫혀버림

[Navigator] Support `<Suspense />` with `startTransition()`

history.push를 한 뒤, navigator.push로 페이지를 열었을때 뒤로가기가 안되는 이슈

• history.push를 통해 _si 없이 페이지를 변경한 뒤, navigator.push를 사용해서 새 page를 띄우면 새 page에서 뒤로가기를 누르거나, back swipe를 햇을 때 history는 pop이 되지만, page가 변경되지 않음

[공통] NavBar icon touch영역 이슈

icon 크기 만큼만 touch영역으로 잡혀 있어서, touch가 잘 되지않음

MemoryRouter 이슈

MemoryRouter에서 정상작동하지 않음

[공통] Depth 변경 이벤트

Card 컴포넌트 내부 loading state의 사용이 적용되는 특정 상황이 궁금합니다.

배경지식

loading state

initial state -> props.isRoot
Card.tsx#27

loading state가 쓰이는 부분

Card.tsx#193

현재 로직상 loading state가 true일 경우 Card.scss#37를 통해 display: none이 적용되는걸로 확인됩니다.

마운트 시 loading -> false

mount가 될 시 setTimeout(cb, 0)을 통해 loading state를 false로 바꿔주는 모습입니다. Card.tsx#31

궁금증

CardProps.isRoot 가 true일 경우 위와 같은 로직이 적용되는데(isRoot가 false이면 loading도 false이므로 css 미적용 Card.tsx#176) 어떤 특정 상황에서 display: none으로 해당 엘리먼트를 감추었다가 mount시 보여줘야 하는 상황이 오나요?

create-stackflow-app

Listener 기반 store 삭제

• React Concurrent Mode 지원

[Android] 텍스트 크기 조정 이슈

안드로이드 플랫폼에서 텍스트 크기 조정 시 Navbar가 깨지는 문제

[iOS] 연속으로 빠르게 두번 스와이프백 했을때 UI 이슈

[iOS] 저전력 모드 프레임드랍 문제

저전력모드에서 엣지 스와이프 동작에 프레임드랍이 있습니다

Screen 컴포넌트 unmount 동작 관련 질문(+ 동적 라우팅)

Screen 컴포넌트 unmount 동작 관련 질문(+ 동적 라우팅)

질문 하게 된 배경

토이 프로젝트를 진행하는 중에 로그인 여부에 따라 다른 컴포넌트를 라우팅 시키고 싶었습니다. 그래서 아래와 같이 코드를 작성했습니다:

<Navigator
    theme="Cupertino"
    onClose={() => {
      window.alert('닫기 버튼이 눌렸습니다')
    }}
>
    {login ? (
      <Screen key="login" path="/" component={LoginHome} />
    ) : (
      <Screen key="home" path="/" component={Home} />
    )}
</Navigator>

문제점

제가 기대한 방식대로 동작하지 않았습니다. 왜 이렇게 동작하나 Screen.tsx를 살펴 보았는데, unmount 시 mobx store에 해당 스크린에 관한 정보를 제거해 주는 부분이 없습니다.

고민 해볼 점

아직 내부 코드를 다 이해하지 못 하였지만, "Screen 컴포넌트가 unmount시 store를 변경시킨다"를 구현하려면 꽤 고려해야 할 점 이 있다고 생각이 들었습니다. 예를 들어, 스크린 하나가 제거 된다면 순서가 꼬이게 되어 _si 또는 screenInstance.id 등의 값의 관계에 이슈가 있을 것 같다고 생각합니다.
위 고민에 대한 의견 또는 동적 라우팅을 구현하는(제 방식이 틀렸을 수도 있다고 생각합니다.) 다른 모범 사례가 있는지 여쭤보고 싶습니다!

감사합니다. ☺️

@karrotframe/pull-to-refresh

[Android] present: true로 창을 열때 뒤쪽 화면 애니메이션이 작동안함

로고랑 QR 코드 이미지 SVG로 바꿔주세요

압축 잘되서 모듈 사이즈 좀 줄이게 ㅎㅎㅋㅋ

Screen에 필요한 옵션

Navigator에 필요한 옵션

전역에서 싱글톤으로 쓰고있는 unsafe한 상태들을 삭제하기

• SSR Support

Preload remote data before rendering

await push() & pop.send() 사용 시 history pop보다 promise resolve가 먼저 실행됨

• await push() & pop.send() 사용 시 history pop보다 promise resolve가 먼저 실행되기 때문에,

const response = await push<ROUTE_EVENT>(FRANCHISE_REGISTER_PATH)
        
replace(CREATE_JOB_POST_PATH)

와 같은 코드에서 route가 정상동작하지 않음

• setTimeout을 추가해도 타이밍을 정확하게 잡을 수 없음

[공통] history.push 사용 후 replace 시 history가 꼬임

ex)

Main (Navigator.push) -> 
CreatePost(history.push) -> 
page1(history.push)  -> 
page2(Navigator.replace) ->  
bizMain(Navigator.pop) -> 
Main 

• 이 플로우 대로 했을때, 마지막 pop을 했을때 Main으로 주소가 변경되지 않고 CreatePost주소로 돌아가고, Screen만 정상적으로 rendering되는 이슈
• Screen자체는 정상적으로 pop되어 보이지만 path가 replace전의 path로 변경됨

iOS + HashRouter Problem

await push를 통해 메뉴 접근 후 pop() 실행시 (백버튼, 스와이프백) Promise가 resolve가 안됨.

Breakpoint 찍으면서 디버깅시에는 작동이 잘 됨.

[Navigator] replace without animate option doesn't work after using history.push

navigator.replace without animate option doesn't work after using history.push

In my opinion, when using history.push, _si is missing.
And, Because navigator.replace with animation doesn't set _si, karrotframe route also doesn't work

[ex flow]
page load -> history.push('/same-path?with-query-string') -> navigator.replace(/some-other-path) -> the page is not changed

Navigator의 replace가 정상적으로 동작하지 않음

• 페이지 루트(_si=1)에서 replace({ animate: true }) 시 애니메이션이 정상적으로 동작하지 않아요.
• replace에 옵션으로 { animate: true }를 주면 _si가 +2씩 오르고, { animate: false }를 주면 _si가 변하지 않아요.

replace 애니메이션 의견 제시

replace

첫번째가 아닌 페이지에서 replace 하면 화면이 새로 나와요 😭
혹시 이거를 조절 가능하게 할 수 있을까요?

첫번째가 아닌 페이지에서 replace 를 할 경우

첫번째 페이지에서 replace 를 할 경우

[공통] replace 애니메이션 지원하기

예상 시나리오

글쓰기 폼을 첫 Entry 들어와서, 글쓰기를 완료했을때 해당 미니앱의 홈화면으로 보내기.
애니메이션과 함께, X 버튼을 옮겨야 된다.

필요한 기능

replace() API를 화면 전환 애니메이션과 함께 수행하기

예상 API

replace('/', {
  animate: true,
})

또는

replace('/').animate()

전자가 더 나아보여요

오픈소스 라이센스