Research is a critical step in the development of any component. It helps us understand the problem we're solving and the best way to solve it.
As OSS library authors, we want to create solutions that are not only useful, but also a joy to use. Existing projects can give us insight into how to make our components better, figure out limitations and edge cases, and come up with intuitive API design.
Take a look at the following projects and see if you can find any inspiration. This will help with the Research step of the component development process.
If you find something cool and think it fits, add it to the list!
For each component you work on, find what is common across all the projects.
Ex: Do all the Accordion implementations have a Panel or Content component?
Ex: Do most date pickers have props to select a min and max date?
Ex: Do certain DOM elements have an exact or similar role / attribute?
Is there an API that is very different from the rest? If you were going to use this component, what would you like to see in the API?
Is there an API that stands out and seems to be a better design? If you were going to use this component, what would you like to see in the API?
Each component folder should have a file called research.md or research.mdx that outlines the research that went into the component. This should include:
A comprehensive research document should cover the following areas:
Here are some links to research links for the tree component:
- [Ark UI](https://ark-ui.com/react/docs/components/tree-view)
- [Material UI](https://mui.com/x/react-tree-view/?srsltid=AfmBOor5Lu38zUPxWS633qeArjpzz9IK_DuLrAtQxqsjy33VUa5EyI3l)
- [React Headless Tree](https://headless-tree.lukasbach.com/storybook/react/index.html?path=/story/react-async-data-loading--async-data-loading)
- [React Arborist](https://github.com/brimdata/react-arborist)
- [Melt UI](https://next.melt-ui.com/components/tree/)
Preview:
List all the features the component should support, using a checklist format:
- [ ] Feature 1
- [ ] Feature 2
- [ ] Feature 3
As you add features, make sure to update the research document to reflect the latest changes.
Define the composition pieces of the component:
Pieces:
- Root
- Panel
- Handle
Document all keyboard interactions the component should support for accessibility:
- Arrow keys for navigation
- Enter/Space for activation
- Escape for dismissal
List all the attributes needed for the component to work or be accessible:
role="dialog"
- aria-labelledby
- aria-describedby
Document common use cases for the component:
- Forms
- Navigation
- Data visualization
Provide links to the example use cases.
For example, here's some use case links of the slider component:
Note any important CSS properties or techniques:
Important CSS:
- position: absolute
- position-anchor: top-left
- overflow: hidden
Document the proposed API for each component part:
Root:
- prop1 -> description
- prop2 -> description
Panel:
- propA -> description
- propB -> description
Document any known issues or challenges from similar implementations:
- Edge case handling
- Browser inconsistencies
List any open questions that need resolution:
- How should X behavior work?
- Should we support Y feature?
See the resizable component research for an example.
Don't reverse engineer the component from the research links. The links are there to help you understand the component, the spec, and the problem it solves.
Only look at the implementation if you are stuck or need to understand a specific part of the component.
Research is not a one time thing. It is a living document that should be updated as you learn more about the component.