Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(style): add forward ref docs #12775

Merged
merged 2 commits into from
Dec 6, 2022
Merged

docs(style): add forward ref docs #12775

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74c4be8
docs(style): add forward ref docs
tay1orjones Dec 5, 2022
2df0f10
Merge branch 'main' into forward-ref-style-docs
kodiakhq[bot] Dec 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions docs/style.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ row before the </tbody></table> line.
- [React](#react)
- [Guidelines](#guidelines)
- [Writing a component](#writing-a-component)
- [When to use `React.ForwardRef`](#when-to-use-reactforwardref)
- [Translating a component](#translating-a-component)
- [Working with messages that depend on state](#working-with-messages-that-depend-on-state)
- [Using `useCallback` and `useMemo`](#using-usecallback-and-usememo)
Expand All @@ -72,6 +73,14 @@ row before the </tbody></table> line.
- [Style](#style-1)
- [Naming event handlers](#naming-event-handlers)
- [Naming experimental code](#naming-experimental-code)
- [Testing](#testing)
- [Strategy](#strategy)
- [Organization](#organization)
- [Recipes](#recipes)
- [`ComponentName-test.js`](#componentname-testjs)
- [`ComponentName-test.a11y.js`](#componentname-testa11yjs)
- [`ComponentName-test.server.js`](#componentname-testserverjs)
- [Notes on manual testing](#notes-on-manual-testing)
- [Sass](#sass)
- [Guidelines](#guidelines-1)
- [Author component styles using mixins](#author-component-styles-using-mixins)
Expand All @@ -82,6 +91,9 @@ row before the </tbody></table> line.
- [Annotate relevant Sass values with SassDoc](#annotate-relevant-sass-values-with-sassdoc)
- [Style](#style-2)
- [Comments](#comments)
- [Testing](#testing-1)
- [Recipes](#recipes-1)
- [Public API](#public-api)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->
<!-- prettier-ignore-end -->
Expand Down Expand Up @@ -224,6 +236,25 @@ _Note: not every component will mirror the structure above. Some will need to
incorporate `useEffect`, some will not. You can think of the outline above as
slots that you can fill if you need this functionality in a component._

##### When to use `React.ForwardRef`

From the [react docs](https://reactjs.org/docs/forwarding-refs.html),

> Ref forwarding is an opt-in feature that lets some components take a ref they
> receive, and pass it further down (in other words, “forward” it) to a child.

For the most part, components should utilize `React.ForwardRef` so that
consumers can impact or control the managing of focus, selection, or animations.

Cases where a component _may not_ need to forward a ref include components that
render static content or do not render elements that are focusable, interactive,
or animatable.

Note that adding a forwarded ref to a component should be considered a breaking
change. When creating a new component, even if you do not anticipate an explicit
need to provide a forwarded ref, it's likely still worthwhile to include one to
avoid unecessary breaking changes in the future.

#### Translating a component

Certain components will need to expose a way for the caller to pass in
Expand Down