🚀 New Component: SidePanel (Labs)

[lychyi]

Summary

While, Canvas Kit already has a Side Panel, we are unifying it as an internal initiative, starting with the container itself. This means that the existing side panel would have had to change significantly. Because of that we've decided to use the Labs namespace to build this new one and eventually deprecate the original one.

Basics

The side panel is made up of 3 parts:

• The panel (a container that is expandable)
• A control (a button or something similar that controls the panel)
• A label (an arbitrary element that contains the accessible name of the panel)

It also includes a hook that wires the three together useSidePanel(). It returns an expanded state getter and setter (like any other useState hook) and 3 sets of prop objects meant to be spread to their associated parts: panelProps, labelProps, and controlProps.

The hook itself takes a config object that allows you to set: initialExpanded (initial state of the panel), panelId, and labelId (if either is defined it will be a string id, otherwise, it is uniquely generated). It can also take no arguments and return a default set of props and expanded state.

The component also ships 1 default sub-component for the control: SidePanel.ToggleButton. This is an IconButton with a default icon and is aware of whether it's a left-handed or right-handed side panel and positions the button accordingly.

In our docs and examples, we recommend that a hidden label be used as an aria-labelledby target to make sure all parts of this side panel are accessible and read well on a screen reader.

Usage

const {panelProps, labelProps, controlProps} = useSidePanel({ initialExpanded: false, panelId: 'side-panel-1'});

// somewhere in your JSX
<SidePanel {...panelProps}>
  <SidePanel.ToggleButton {...buttonProps} />
  <span hidden>Accessible Label for Panel</span>
</SidePanel>

Notable differences to the current Side Panel

• Style changes in the form of two variants. Button is located on top rather than on bottom.
• This is just the container, not menu items or anything that goes into a standard side panel. Other components will follow.
• The API is focused on composability via JSX and hooks rather than config props
• A user can set the collapsed and expanded widths but they are configurable
• This side panel can be used in both left and right side orientations. (using the origin prop)
• Animations trigger "in-between states". So we give the user two callbacks. One will alert them when the expanded prop changes (onExpandedChange) while the other is called when the panel transitions between 'collapsed' | 'collapsing' | 'expanded' | 'expanding' (onStateTransition). The latter is useful if the side panel contents need to know when things are 'collapsing' or 'expanding'.

Open Questions

• Not sure what are good names for two variants. One is more prominent than the other internally but there could be more variants in the future. Today it's "standard" and "alternate", not creative, I know.
• I'm using a hack to basically short circuit animation on the first render. This was found in Material UI but it basically prevents the component from animating when it "mounts" for the first time. Any potential downsides? Is there any way that React forces a re-render without the user specifying it?

Checklist

• branch has been rebased on the latest master commit
• tests are changed or added
• yarn test passes
• all (dev)dependencies that the module needs is added to its package.json
• code has been documented and, if applicable, usage described in README.md
• module has been added to canvas-kit-react and/or canvas-kit-css universal modules, if
  applicable
• design approved final implementation
• a11y approved final implementation
• code adheres to the API & Pattern guidelines

Additional References

Internal-only Figma Specs

Original side panel codebase

Closes #778

Blocked by #896

[cypress]

---

Test summary

498 • 0 • 1 • 0

---

Run details

Project	canvas-kit
Status	Passed
Commit	90b90f8 ℹ️
Started	Nov 5, 2020 1:28 AM
Ended	Nov 5, 2020 1:33 AM
Duration	04:45 💡
OS	Linux Ubuntu Linux - 18.04
Browser	Electron 80

View run in Cypress Dashboard ➡️

---

This comment has been generated by cypress-bot as a result of this project's GitHub integration settings. You can manage this integration in this project's settings in the Cypress Dashboard

[alanbsmith]

Looks good, @lychyi! Thanks for working on this. 👍 I left some comments and questions and only one change requested. Let me know if anything is unclear. 😄

[alanbsmith]

🦩