@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-hooks
Hook: 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
null
return true - When haveVisitedSummary AND activeSectionId NOT
null
return 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.