Digging into Reakit in Menu and Disclosure

[hharnisc]

In DySys office hours @aayushpi asked me to take a look at our components that use Reakit, specifically the Menu and Disclosure components. Generally speaking these components look great and have solid developer ergonomics.

I do have one concern about the Disclosure that may need to be addressed at some point. As y'all know we're building the sidebar component out of the Disclosure (and a few other components). At one point we had a requirement to preserve the open/closed state of the sidebar items, but we decided to go a different direction at least for the MLP and drop the requirement. If we did end up with this as a requirement or in the future need this I'm not sure if we could use the Disclosure since open/closed state is local to the component. This seems to be the tradeoff with Reakit, you get A11y and keyboard functionality but you lose control over the component and have to keep 2 state stores in sync.

Are there any alternatives or plugins for Reakit that can help us out in these cases where we need more control? I can see a future where we need to implement something and drop A11y because of another requirement or spend a considerable amount of time building out a fully accessible/keyboard controlled component.

[SiTaggart]

Disclosure is a relatively simple component and something we could refactor whilst keeping the same API and palm off handling the "visible" state of the component to the consumer. There's not a whole lot of danger in regressing the accessibility of the control.

What I am curious in though is posing the following question to Paste consumers:

Given that components must follow the W3C ARIA authoring practices, the majority of which come with pretty complex keyboard and user interactions that require multiple internal parts of the component to stay in sync to achieve an accessible user interaction, what would be your proposal as an alternative?

[hharnisc]

I understand where you're coming from, we don't want to end up in a case where people aren't building things accessible by default. But it comes down to having an escape hatch. If we don't have have one, eventually we'll have to work around the component library. And we'll have to make some trade offs that y'all may or may not agree with.

[SiTaggart]

Sure, but given your requirements and given accessibility requirements, what is a good alternative proposal to Reakit / encapsulated accessibility and keyboard interactions?

I'm seeing two possible solutions at the moment, one of which we're currently using.

1. We basically inverse control of the component to the consumer. But that requires you to handle what to do with all the key presses, moving the roving index, focus and and other states. Pros: full control. Negatives: we put alot of work onto the consumer.

2. We encapsulate the accessibility requirements. Allow consumers to set initial state, and a callback of some kind (depending on the component)to use to keep state in sync. Pros: accessibility out the box, ver little work on the consumer. Cons: Uncontrolled and consumer has to do some state syncing.

Is there an option 3 that I'm not seeing, is the question I'm posing.

[hharnisc]

I'm avoiding implementation details here, those are up to y'all for Paste. Option 3, which is what we're looking for as a consumer of Paste, would be option 2 by default but an escape hatch that gives up control over certain props.

[TheSisb]

I'd like to remark that while uncontrolled components are a poor developer experience on DOM (namely form) elements, it is actually a positive developer experience for complex stateful UI component interactions.

You may already know much of what I’m about to say below, but for the sake of clearly documenting my rationale to other possible readers, I'm going to break down how I came to the above conclusion:

Differences between controlled and uncontrolled components

Controlled components require two things to work: the current state to render, and [1..n] callback functions for you to manage that state. When the controlled component needs to change, it fires the corresponding callback function with some (optional) parameters.

Basic controlled input example:

const ControlledInput = ({value, handleChange}) => {
  return <input value={value} onChange={e => handleChange(e.target.value)} />
}

Your code that wraps controlled components must define and provide this callback handler logic. That logic typically updates the state you maintain, and that state in turn gets passed down to the controlled component for the update to become visual for the user.

Basic wrapping code:

const App = () => {
  const [username, setUsername] = React.useState(‘’);
  return (
    <ControlledInput value={username} handleChange={setUsername} />
  );
}

In summary, controlled components hold no state. It is up to the developer to manage the state and pass new props when appropriate to re-render these components. This gives you the power to manage that state the way you want, at the cost of having to do some extra coding work.

---

Uncontrolled components require one thing to work: the initial state. These components manage state internally, providing all the pros/cons of code encapsulation in general. Passing a new state does not force an update to the internal state, it is simply ignored. Uncontrolled components usually provide some mechanism for you to track the current state value.

If your uncontrolled component wraps a DOM element, the only way to retrieve the current value (its state), is to use refs and query the DOM node directly. If it’s a React component, you usually have more convenient tools at your disposal.

Basic uncontrolled input example:

const UncontrolledInput = ({initialValue}) => {
  return <input defaultValue={initialValue} />
}

Your code that wraps uncontrolled components can rely on the fact that the component will just work. You cannot change how these components manage state, you get what you get. For a simple example, you can’t make it so that every time the user types the letter “a” it shows up as “x”.

Basic wrapping code:

const App = () => {
  return (
    <UncontrolledInput initialValue=”” />
  );
}

In summary, uncontrolled components hold all the runtime state. It is up to the developer to seed in the initial state and, if necessary, keep tabs on the last state for storage purposes. This provides convenience at the cost of control.

Official docs for more reading:

• https://reactjs.org/docs/forms.html#controlled-components
• https://reactjs.org/docs/uncontrolled-components.html)

Pros and Cons

Controlled Component Pros:

1. You don't ever have to wonder "What is the current state of my component?" (i.e.: what value does my input currently have?). This is nice because when a user goes to submit a form and you need to get all the current values to send to a server, you have them already because it’s part of your business logic.
2. You can change how components behave in different scenarios when it comes to state. For example, automatically capitalizing certain words in an input. This is really powerful and allows much more freedom and flexibility to developers.

Controlled Component Cons:

1. You now need to manage the state for these components, so they don't work "out of the box" without plugging in all the logic.
2. You have to think about how to encapsulate the data, which can be hefty when you consider more complicated components. (Pretty much why libraries like Formik exist)
3. Since you are now passing in handlers to update your state, this leads to thinking about and building behaviors. This now becomes a consumer responsibility and not something the author of the component can define. These behaviors could be inconsistent from one implementation to another (i.e.: do we track changes onBlur or onKeyUp?)
4. Managing frequent or unnecessary re-renders is potentially an issue. Consumers of these components need to reach for PureComponent functions (React.memo in newer React) for complex interfaces possibly.

Uncontrolled Component Pros:

1. Works "out of the box"; you don't need to be concerned about how to keep track of all the possible changes because they are in-built.
2. The only data you need to be concerned about (initialState) is typically optional. It can be provided in order to “resume” a state of the data, in case you re-initialize the component on page navigation.
3. Behaviors are encapsulated, so you won't have inconsistent UX from one implementation to another.
4. Pretty safe when it comes to frequent re-renders, because it handles state internally so it's a single source of truth when it comes to optimizing.

Uncontrolled Component Cons:

1. You can’t change the behavior of how state is managed in these components.
2. Knowing the current state of the uncontrolled component for DOM elements is somewhat inelegant.
3. If you are tracking the state of an uncontrolled component, you may have two copies of it at the same time (one within the component, one in your app). This is usually inexpensive, but worth calling out because improperly built wrapping code may cause inconsistencies (highly unlikely to occur and not necessarily a big deal anyway as this is just seeding initial state).

Why do we recommend using controlled components for forms?

In most cases, we recommend using controlled components to implement forms - React docs

Conventional wisdom recommends controlled components for forms because forms are made up of disparate elements that share common state. For example, changing a selection of one dropdown might affect the visibility of another element. It makes sense to manage that state yourself to control the presentation of the UI. Another benefit is easily serializing the data to send to a server or to localstorage. The concern of data for forms isn't really attached to any one element, it's attached to the whole form.

Why I think uncontrolled components are sometimes fine

In the case of Disclosure and Menu I think uncontrolled components are a more convenient paradigm to achieve a consistent UX. As a developer, you really only care to set the initial state of the component and the user should be able to toggle things at will. There usually isn't an interdependence between Disclosure & Menu and some other part of your app; it's an isolated interaction. The state is usually ephemeral, being discarded when you navigate off the page or click away.

Accessible Menus are complex to build because they have many possible events they need to manage (i.e.: keyboard nav), so wiring all the possible event handlers could be tedious and result in different behaviors for consuming products. Managing the current state of an input’s current value is pretty trivial, while managing the state of more complex interactions like in a Menu is fairly demanding. For most applications of Menu, setting some initial state is enough as their active state shouldn't be pertinent to the rest of the application.

In some cases you may want to keep a copy of the state (i.e.: is the disclosure open?) for the next time the user lands on the page, and there usually is a simple way to do that because these are React components and not DOM elements.

From a design system point of view, we’re aiming to maximize leveragability by solving for the common denominator (pareto principle). In our case, it makes sense to abstract these complexities in an uncontrolled component. As a result consumers can get these components working correctly and easily for most applications.

---

Whew, big wall of text, but I hope this helped clarify why I think this is a reasonable decision for us to make. If you encounter a situation where the encapsulation of state is blocking a certain UX/UI design, please bring that to crit and we can evaluate a path forward based on a more concrete example.

[hharnisc]

Thank you for the thoughtful response @TheSisb! I largely agree with you and @SiTaggart on the points between the tradeoffs of uncontrolled vs controlled components.

I think we're on the same page with the tradeoffs that are made in Paste around using uncontrolled inputs to make components accessible and keyboard friendly by default. I think this is classic case of differing philosophies that end up getting us to the same place.

My personal philosophy falls a little closer to the "do one thing well" and "build highly composable components" portions of Unix philosophy. In my past experience it has meant building the uncontrolled (stateful) components from controlled (stateless) components. The uncontrolled component is usually an HOC or wrapper to handle things like focus, hover, onChange, value etc -- so long as the controlled components follow a uniform property api. Most cases teams will use the uncontrolled component since it covers the common cases (the 80% if we're talking Pareto Principle) and the special cases teams end up building their own HOC to wrap around the controlled component. These cases are very clearly communicated as AT YOUR OWN RISK and the extra work falls on the team that needs the functionality. You would have to go down this path intentionally and with good reason.

Reakit roughly translates to the uncontrolled HOC in the above pattern, and solves for the 80%. This gives us accessible and keyboard friendly components by default. Since the Reakit uses hooks like APIs for state, I think we can end up with the smart defaults with overrides pattern where the smart defaults are what you've built today and the overrides are an extra prop that lets you bring your own state management. (and frankly I've found that you discover new common patterns when observing customizations that teams have built that eventually end up on the main branch -- its another excellent feedback loop)

In the case of Disclosure you would be able to pass in a prop to override the disclosure primitive state:

https://github.com/twilio-labs/paste/blob/main/packages/paste-core/components/disclosure/src/Disclosure.tsx#L24

You would have to conform to Reakit's API and extend/modify state: https://reakit.io/docs/composition/#state-hooks

This leaves the door open for the other 20% of the cases in a way that has still has smart defaults, minimizes rework and provides a valuable feedback loop for common component functionality.

[SiTaggart]

For transparency into an offline discussion I had with @hharnisc, we'll dig into the possibility of following this pattern and providing a stateHook prop to components so you can use composition with Reakit state and your own state to give greater control over the state the component is using.

Obviously with some warnings that you can totally destroy the accessibility of the component if you're not caareful.

https://reakit.io/docs/composition/#state-hooks

[richbachman]

@hharnisc I've opened this PR adding a stateHook (name TBD) prop to Disclosure. Will you take a look and let me know if this will meet your needs? TIA.

[hharnisc]

Thank you for working on this @richbachman 🙌 added some comments on the PR

[richbachman]

@hharnisc just merged the PR