@ptallen63/seafarer

⛵ Seafarer

Table of Contents

🚧 Disclaimer: This project is in development and is just a proof of concept at this point. I would love any feedback and how you wish it worked and what features to add. That being said, it is not meant for hardened production environments just yet.

One of the main purposes for this project is to make creating simple step flows easier and faster. By using intentional abstractions, the only thing a developer has to worry about is the core logic of the flow itself. You should not have to worry about keeping up with the state of the flow all the time or rewriting advance and previous screen logic. With Seafarer only worry about what your flow is doing. Written with modern React Seafarer provides a simple hook to use throughout your application. You can only use the core logic engine of Seafarer or add your own screen components.

Installation

NPM

npm install --save @ptallen63/seafarer

PNPM

pnpm install --save @ptallen63/seafarer

Yarn

yarn add seafarer

Usage

<FlowProvider/>

Comes with a <FlowProvider/> to wrap the parent component where you want to use the flow.

import { FlowProvider } from '@ptallen63/seafarer';

    <FlowProvider config={{
    /* Flow Config Data */
    }}>
      <App />
    </FlowProvider>

Flow Config

When a initializing a flow, there are several options available to you.

export interface FlowConfig {
  startIndex: number;
  screens: Screen[];
  settings?: FlowSettings;
  data?: FlowData
  onSubmit?: (data?: FlowData, state?: State) => void
  onNext?: (data?: FlowData, state?: State) => void
  onPrevious?: (data?: FlowData, state?: State) => void
  onSave?: (data?: FlowData, state?: State) => void
}

Property	Required	Default	Description
startIndex	true	0	The start index of the screen in the screens array
screens	true	[]	An Array of screen objects
settings	false	see settings section	flow settings
data	false	-	Any flow data you want the flow to initialize with
onSubmit(data, state)	false	-	Hook to do an action on a submit of the flow
onNext(data, state)	false	-	Hook to do an action on a next action of the flow
onPrevious(data, state)	false	-	Hook to do an action on a previous action of the flow
onSave(data, state)	false	-	Hook to do an action on a save action of the flow

Flow Settings

Property	Required	Default	Description
verbose	'false'	false	Provide extra console output base for screen actions
strictValidation	'true'	false	A screen must have a isValid set to true for the flow to advance
enableDevTools	'false'	false	This will send actions through Redux devtools

Example Config

import { ScreenTypes } from '@ptallen63/seafarer'

const flowConfig = {

      settings: {
        strictValidation: true,
        verbose: true,
      },
      screens: [
        {
          validate(data) {
            console.log('...Validating', data);
            return data?.foo === 'bar';
          },
          name: 'screen-1',
          type: ScreenTypes.INPUT
        },
        {
          name: 'screen-2',
          type: ScreenTypes.INPUT,
          shouldSkip(data) {
            return data?.foo === 'bar';
          },
          isValid: true,

        },
        {
          name: 'screen-3',
          component: Screen3,
          type: ScreenTypes.INPUT,
          isValid: true
        },

      ],
      startIndex: 0,
      onSubmit(data, state) {
        console.log('submit', { data, state });
      },
}

Screens

This library uses the concept of a Screen as its main taxonomy. At the core it things in terms or what screen should I should and in what order.

Screen Settings

export interface Screen {
  name: string;
  type: ScreenTypes;
  component?: ScreenComponent;
  data?: {
    [key: string]: unknown;
  }
  isValid?: boolean;
  isDirty?: boolean;
  shouldSkip?: (data?: FlowData, state?: State) => boolean;
  validate?: (data?: FlowData) => boolean;

}

Property	Type	Required	Description
name	string	true	This the name of your screen.
type	enum	true	See Screen Input Types
component	React.FC	false	If you wanted to pass a component to be rendered.
data	object	false	If you wanted to have data for this screen. For example lets say you wanted to add a source or browser field where the flow is running, you could add that here.
isValid	boolean	false	defaults to true Is this screen valid. This setting can be updated programmatically as inputs or the state of the flow changes.
isDirty	boolean	false	Has a user put input into this screen
shouldSkip	function	false	Runs logic to determine if this screen should be skipped. This function is run whenever a form navigation event is running like a NEXT_SCREEN or PREVIOUS_SCREEN
validate	function	false	This will run if you have strictValidation set to true in the flow settings and will run before a NEXT_SCREEN action.

Screen Input Types

If you think there should additional screen types or a way to add your own screen types, then consider contributing :)

export enum ScreenTypes {
  INPUT = 'INPUT', // AN Input Screen
  LOADING = 'LOADING', // A Loading or interstitial screen
  SUBMIT = 'SUBMIT', // A submit screen
  DISPLAY = 'DISPLAY', // Only an informational screen
}

UseFlow()

import { useFlow } from '@ptallen63/seafarer';

function App() {

  const { flowState, flowActions } = useFlow();
  const currentScreen = flowState.screens[state.currentScreenIndex];

  return (
    <div className="App">
      <div>Hello, World</div>

      <pre>
        {JSON.stringify(currentScreen, null, 2)}
      </pre>
      <button onClick={() => flowActions.previousScreen()}>Prev</button>
      <button onClick={() => {
        flowActions.validateScreen( currentScreen, { foo: 'bar' });
        flowActions.saveAndContinue({ foo: 'bar' });
        return;
      }}>Next</button>
      <button onClick={() => flowActions.submit()}>Submit</button>

    </div>
  );
}

Contributing

Please see our contributing guide.

Project

Github Project

Table of Contents

• ⛵ Seafarer
  • Installation
    • NPM
    • PNPM
    • Yarn
  • Usage
    • <FlowProvider/>
    • Flow Config
      • Flow Settings
      • Example Config
    • Screens
      • Screen Settings
        • Screen Input Types
    • UseFlow()
  • Contributing
  • Project
  • Table of Contents