@josiahayres/react-hooks v0.1.3
@josiahayres/react-hooks
react-hooks is a collection of React Hooks, written in Typescript.
Installation
Use the package manager npm to install @josiahayres/react-hooks.
npm install @josiahayres/react-hooksHook: useFormSectionControl()
When you have forms with multiple sections, this hook helps by enforcing the following rules:
- Only one section can be active at a time.
- Optionally, can only edit one section at a time.
- Each section
You are responsible for ensuring each Section must control
- validation of each section, when to let user go to next section.
- Section State: Active vs Summary & what is displaye at each point
- Data collection from each section & what to do with the data once submitted.
- Showing user submit button
import { useFormSectionsControl } from 'josiahayres/react-hooks';
// Create a Union type with all valid section IDs
type ValidFormSectionIds =
| 'sectionOne'
| 'sectionTwo'
| 'sectionThree'
| 'sectionFour';
// This form uses three sections.
const sectionIds = ['sectionOne', 'sectionTwo', 'sectionThree'];
// Initialize hook in component
const formSectionsControl =
useFormSectionControl<ValidFormSectionIds>(sectionIds);formSectionControl
This is what the hook returns. Is a tuple with the following:
const [store, dispatch, canEditSection] = formSectionsControl;formSectionControl.store
Also accessable as formSectionsControl[0].
// Store object can be destructured like this
const { activeSectionId, haveVisitedSummary, formSections, options } = store;| Store | Notes |
|---|---|
| activeSectionId | One of provided formSections or null |
| haveVisitedSummary | True once dispatch({type:"gotToNextSection"}) called when activeSectionId is last id in provided list |
| formSections | Same as provided list of formSections, see section below for more |
| options | Same as provided options object, see section below for more |
store.options
This is the options object as provided to the hook on setup. All options in this object are optional.
| Key | When key has value: | Notes |
|---|---|---|
| initialActiveSectionId | null | haveVisitedSummary=true, activeSectionId=null |
| initialActiveSectionId | "sectionOne" | haveVisitedSummary=false, activeSectionId="sectionOne" |
| initialActiveSectionId | Not provided | haveVisitedSummary=false, activeSectionId=first section in provided list |
formSectionControl.dispatch
Also accessable as formSectionsControl[1]({type:""}).
| Action Type | Action Parameters | Notes |
|---|---|---|
| reset | None | Will reset internal hook state to value at initial render |
| goToNextSection | None | Will step through each section in list provided, until no more sections are active. |
| goTo | sectionId | Sets a specific sectionId active |
Examples:
// Typescript will help dispatching the correct actions
dispatch({ type: 'goToNextSection' });
dispatch({ type: 'goTo', sectionId: 'sectionTwo' });
dispatch({ type: 'reset' });formSectionControl.canEditSection
Function takes a sectionId and returns if that sectionId can be edited. These checks are used internally, in this order.
- When activeSectionId === sectionId return false
- When activeSectionId is
nullreturn true - When haveVisitedSummary AND activeSectionId NOT
nullreturn false - When position of sectionId is before position of activeSectionId return true
- When position of sectionId is equal to or after activeSectionId return true
const sectionOneEditable = canEditSection('sectionOne');Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.