react-hierarchical-view-controller

A hierarchical view controller for react. The core concept is that the controller has a stack of views. You can push a new view onto the stack, or change your position in the stack by popping into a specific position. Views are laid out from left to right as they are pushed onto the stack.

There are two modes to run in. Controlled & Uncontrolled. Controlled means that a single view component is on the screen at a time. Pushing onto the stack will transition the current view component off screen, and the new one on screen. Uncontrolled means that all view components are laid out next to each other, such that a user can scroll between them, so it is possible to see a portion of multiple view components at once. The default behavior is to scroll the latest view into the view, but this can be disabled.

The example directory shows an example of both controlled and uncontrolled versions of the view controller.

API

This is a bare minimum example of creating a view controller component and using its internal provider context to push and pop into the view stack.

import {
  HierarchicalViewController,
  HierarchicalViewControllerContext,
}  from 'react-hierarchical-view-controller'
import { useContext, useCallback } from 'react'

function ViewComponent (props) {
  const { stackPush, stackPop } = useContext(HierarchicalViewControllerContext)
  const setUiForward = useCallback(() => {
    stackPush({
      component: <ViewComponent position={props.position + 1} />,
      position: (props?.hvcPosition || 0) + 1,
    })
  }, [])

  let setUiBackward = useCallback(() => {
    if (props.position === 0) return
    stackPop({ position: props.position - 1 })
  }, [props.position])
  
  return <>
    <p>position in the stack: {props.hvcPosition}</p>
    <button onClick={() => setUiBackward()}>backward</button>
    <button onClick={() => setUiForward()}>foward</button>
  </>
}

function App () {
  return <>
    <HierarchicalViewController
      isControlled={true}
      stack={[{
        component: <ViewComponent position={0} />,
        parentProps: {
          className: 'view-component-parent'
        }
      }]}
    />
  </>
}

Pushing a new view component onto the stack can be done by calling stackPush with an action object that includes the component to render with its props already applied. position will determine where in the stack to place view component.

Similarly, in a controlled view controller context, stackPop can be called with an action that just includes the position to pop back to. Doing so does not mutate the stack. Only pushing into the stack will rewrite it, preserving entries at indicies before action.position, and removing those at the end of the stack.