@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/contributor-docs/adrs/adr-002-behavior-isolation.md

@@ -0,0 +1,106 @@
+# Isolating Behaviors through Custom Elements and Vanilla JavaScript
+
+## Status
+
+## Related Documents
+
+- April 18th, 2018: [Custom Elements Example](https://github.com/primer/react/pull/13)
+- May 8th, 2018: [Custom Elements Experiment](https://github.com/primer/react/pull/14)
+- May 18th 2018: [React & Custom Elements](https://docs.google.com/document/d/1b6D2jW3ztQJiKEtQINbb4JoHJ3F3szU6lBX-fGce6aY/edit?usp=sharing)
+- October 16th 2019: [Issue exploring pros & cons of reusing .com JS in React](https://github.com/github/issues-index-experiment/issues/90)
+- November 15th 2019: [Experiment porting PRC to web components](https://github.com/github/ui-engineering/issues/12#issuecomment-558257842)
+- November 27th 2019: [Usage of custom elements in IIE project](https://github.com/github/issues-index-experiment/pull/133)
+- November 27th 2019: [Styling custom elements with styled components](https://github.slack.com/archives/CMZ4DC9BL/p1574883198055600)
+- June 9th 2020: [Discussion in Slack about using skatejs for SSR](https://github.slack.com/archives/C0ER2LCG2/p1591707104461300)
+- November 10th 2020: [Replace dialog with details-dialog](https://github.com/primer/react/issues/907)
+- January 27th 2021: [Guidelines for authoring behaviors](https://github.com/primer/react/pull/992)
+- February 1st 2021: [Example of a vanilla JS behavior & accompanying hook](https://github.com/T-Hugs/components/commit/105c3a191681381377f5aa193cb241a2189db8a6)
+
+## Providing Behaviors via Custom Elements
+
+### Context
+
+Throughout the last few years folks from the Design Infrastructure, Web Systems & UI Platform teams have discussed the idea of using custom elements for behaviors in Primer React Components. The main goal of using custom elements in PRC is to be able to author behaviors once and reuse them in any framework. Several experiments have been conducted which are listed above.
+
+### Assumptions
+
+De-duplication is not our highest or only priority. Attempts at de-duplication must be weighed against changes to the maintainer, developer, and customer experience.
+
+### Findings
+
+#### Developer Experience Regressions
+
+- Custom elements rendering their own subtrees (ShadowDOM) requires polyfills for as-yet implemented specifications. This means PRC will accumulate added complexity if we were to implement Custom Elements with ShadowDOM.
+
+- Implementing Custom Elements in PRC will require a division of client side and server side code, as Custom Elements should only be executed in a browser environment. Currently PRC is "isomorphic" - in that the code can be executed anywhere that React can be, which includes NodeJS server runtimes, as well as the client side. While not insurmountable this does mean PRC will accumulate added complexity, which likely will be surfaced to the user.
+
+- While it's possible to add server side libraries to enable Custom Elements to be rendered on the Server, this adds more complexity and is antithetical to the usage patterns of Custom Elements.
+
+- As of this writing, you cannot style custom elements with styled-components[^1]. This means that if a component wants to use a custom element to get behaviors and you also want to style that component, you must use another wrapper div to apply styles. This is a bug in styled-components and should be fixed in the next release.
+
+#### Incompatibility with some React tools
+
+Some of our GitHub custom elements such as details-dialog and details-menu make assumptions about the DOM tree. For example, details-dialog expects a `details` element to wrap the custom element and uses this assumption[^2] to determine whether or not clicks are happening inside or outside of the dialog and closes the dialog if the click happened outside of the dialog. This makes sense in most cases and is a nice way of enforcing proper usage of the details element, but breaks down when used with [React Portals](https://reactjs.org/docs/portals.html) which are often used to ensure menus are displayed correctly in cases where a parent has an overflow: hidden applied to it, or incompatible z-index.
+
+#### Extensibility
+
+Building behaviors in React Hooks gives us the ability to provide things like state and state change hooks to the consumer of the component. This allows the user to build on additional behaviors to the component based on the state or other variables provided to the component consumer. Doing the same with custom elements would require listening to events on the document[^3] and reacting to them. This is certainly do-able, but goes against some of the foundational principles of React (reacting to changes in the DOM vs changes in React state).
+
+#### Organizational Overhead
+
+- GitHub’s custom elements are all managed in different repos which introduces more maintenance overhead.
+  - You'd need to npm link while developing if you want to test changes out with the presentational components themselves instead of making changes and seeing updates instantly. npm link usually doesn't work well with hot module reloading either.
+  - You'd need to draft & publish releases to both libraries every time you want to update the behavior
+  - If the behaviors are shared between .com and PRC you'd need to do careful testing in both environments to make sure that changes don't create any regressions. That greatly widens the context that engineers need to keep in mind every time a change is made.
+- Reacting to changes will take a bit more time, as we’ll need to orchestrate releases between custom elements and Primer React Components - as opposed to having behaviors already present in PRC which can be versioned in lockstep.
+- Engineers who want to contribute to Primer React Components to build new components and behaviors would need to be familiar with both custom elements and React, two very different paradigms, and context switch between the two.
+
+#### Other
+
+- The custom element & web component API progress slower than React due to changes needing to go through the whatwq standards process.
+
+#### Risks of not switching to custom elements for behaviors
+
+- We spend extra time building behaviors in React that have already been built in our [custom elements library](https://github.github.io/web-systems-documentation/#custom-elements).
+  - There are currently 19 behaviors/components listed on the custom elements documentation site. Several of these we have already implemented in React in either PRC, Doctocat, or other React applications at GitHub which can be upstreamed (details-dialog, details-menu, clipboard-copy, text-expander, autocomplete, task-list via drag and drop hooks, tab-container, text-expander).
+- We decide not to invest further in React at GitHub and have wasted time we could have spent building more custom elements.
+  - This seems unlikely as there seems to be clear consensus that we will continue to build more and more highly interactive products.
+- The React library is abandoned and becomes obsolete
+  - This is a risk with any technology that we may use, seems highly unlikely in the near term.
+  - While also a possibility for Custom Elements, the track record demonstrates deprecations of Web APIs is extremely rare and has a long deprecation path.
+- Behaviors in .com using custom elements and behaviors in PRC diverge, leading to an inconsistent experience
+  - This is probably the biggest risk we face, but moving to custom elements isn’t necessarily the only or best solution. We should explore other ways of detecting divergence such as integration tests.
+
+## Providing Behaviors through Vanilla JavaScript
+
+A simpler method of isolating component behaviors is to implement them in vanilla JavaScript (or TypeScript). This way, they can be shared between React Components and Web Components. Both types of consumers would need to hook up the vanilla behavior to the component(s) that use(s) them.
+
+In some cases, this strategy is very straightforward. When a behavior can be made to have no dependencies other than the DOM, it is easy to isolate and consume in various frameworks. Behaviors that have effects on interactions/events, shared state, and component styles will be more difficult to isolate in this manner.
+
+### Interactions and Events
+
+Many user interactions rely on DOM events, such as `click`, `keypress`, and `focus`. React's event system is _not_ the same as the native DOM event system. React implements a [SyntheticEvent](https://reactjs.org/docs/events.html) that wraps native events. Working with both `SyntheticEvent`s and native events simultaneously is significant additional complexity for maintainers and consumers. However, vanilla JavaScript must operate only using native events. This makes isolating behaviors that automatically hook up event listeners to DOM elements difficult to achieve, and the resulting simultaneous usage of native events and `SyntheticEvent` has the potential to degrade both the maintainer's and the consumer's developer experience using Primer Components.
+
+### Shared State
+
+There are countless ways to manage state in a web application. React has its own ecosystem of state management strategies and libraries (in addition to its own primitive constructs for state management). Since there is no standard state management pattern in vanilla JavaScript, introducing such a pattern would add a new layer of complexity to the component behavior API.
+
+### Component Styles
+
+Since Primer Components uses styled-components to manage CSS styles, any behaviors that affect styles should be doing so with styled-components. Any vanilla JavaScript behaviors that affect styles will add complexity by introducing a second mechanism for applying styles, since they will not be able to use styled-components.
+
+## Decision
+
+### Custom Elements
+
+Due to the challenges listed above and our priorities listed in the [Assumptions](#assumptions) section, we are not investing time in building out behaviors with custom elements in our Primer React Components library. Instead, we should spend time expanding coverage using React Hooks and focus on finding other approaches for making sure implementation of behaviors in our different stacks are consistent (such as integration tests).
+
+### Vanilla JavaScript Behaviors
+
+Some behaviors can be implemented as vanilla JavaScript without introducing additional complexity to Primer Components or its consumers. In cases where this is possible, behaviors will be implemented with no dependencies except the DOM and consumed within React Hooks to provide their functionality to Primer Components.
+
+In general, _portions of behaviors_ that affect or rely on **user interactions and events**, **shared state**, or **CSS styles** should be kept in React Hooks. Parts of the behavior that can be implemented in isolation of these concepts should be built with no dependency on React or other libraries.
+
+[^1]: https://codesandbox.io/s/demo-styling-custom-element-g973d?file=/src/index.tsx
+[^2]: https://github.com/github/details-dialog-element/blob/main/src/index.ts#L195
+[^3]: https://github.com/github/details-dialog-element#details-dialog-close

package/contributor-docs/behaviors.md

@@ -0,0 +1,132 @@
+_Note: This documentation is a draft and is expected to undergo several revisions before being adopted._
+
+# Implementing Behaviors in Primer Components
+
+Behaviors in Primer Components are implemented via React Hooks. Primer Components provides two types of behaviors: generic behaviors and component behaviors.
+
+## Dependencies
+
+**External dependencies:** Third-party/external dependencies are not allowed, except under very strict circumstances. If you need to use an external dependency, open an issue and discuss with the team.
+
+**Internal dependencies:** Internal dependencies are fine and encouraged to reduce code duplication and maintain consistency. When taking an internal dependency, observe the following:
+
+- No circular dependencies
+- Components may depend on other components and component behaviors, but should avoid depending directly on generic behaviors.
+- Component behaviors may depend on other component behaviors and generic behaviors.
+- Generic behaviors may only depend on other generic behaviors.
+
+See below for a visualization of allowed dependencies.
+
+```
+               ____________
+              |            \*
++-------------V--------+   /
+|   Generic behaviors  |---
++----------------------+
+           ^
+          *|     ___________
+           |    |           \*
++----------|----V-------+   /
+|  Component behaviors  |---
++-----------------------+
+         ^
+        1|    _____
+         |   |     \*
++--------|---V-+   /
+|  Components  |---
++--------------+
+
+```
+
+## Generic behaviors
+
+Generic behaviors provide functionality that is not specific to any single component or class of components. If you can't tell which component it should operate on, it's probably a generic behavior. Generic behaviors are _low-level_. Generic behaviors may only have dependencies on other generic behaviors.
+
+### Examples
+
+- `useProvidedRefOrCreate`
+- `usePosition`
+- `useClickAway`
+- `useTypeAhead`
+
+## Component behaviors
+
+Component behaviors specifically implement behaviors for components. Therefore, hooks that implement component behaviors should always return an object containing props objects to be spread across the elements that make up the component's JSX. While component behaviors do not necessarily have to be one-to-one, **a component may only use one component behavior**. Sometimes it makes sense to use the same component behavior on several components. For example: the Dialog, Popover, and PointerBox components may all use the `usePopover` component behavior.
+
+### Examples
+
+- `usePopover`
+- `useComboBox`
+- `useFilteredSearch`
+- `useDetails`
+
+## Implementation guidelines
+
+All behaviors should be implemented as [React Hooks](https://reactjs.org/docs/hooks-intro.html).
+
+Component behaviors should be relatively brief. A component behavior should build a component's experience through the combination of several configured generic behaviors.
+
+Example: The Dialog component uses a `usePopover` behavior. The `usePopover` behavior in turn may call generic behaviors such as `usePosition` (to position the popover on the screen), `useClickAway` (to set up an event handler for clicking outside of the dialog), and `useFocusTrap` (to prevent focus from leaving the dialog while it is being shown).
+
+### Component implementation
+
+Component implementation is [discussed elsewhere](https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md#developing-components), but with respect to behaviors, follow these guidelines.
+
+- If a component has behaviors, it should make a call to exactly one component behavior hook.
+- The hook will return an object containing multiple props objects. Each of the returned objects are props that should be spread onto the appropriate JSX element.
+- Component implementations should be as clean as possible, mostly consisting of the JSX tree definition that the component renders.
+- Component props and, in some circumstances, context values, should serve as arguments to component behavior hooks.
+
+### Balancing API surface with supported scenarios
+
+The [YAGNI Principle](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it) cautions developers against building out functionality that isn't presently needed, but as a library, Primer Components should carefully balance the API surface area with building a library that functions for a wide range of use cases. Since it is difficult to define a quantitative test to determine whether or not a component or a behavior should support a certain scenario, there will be some subjectivity when it comes to choosing to build certain features. When adding a feature that seems too specific, try to _generalize_ it. Can multiple use cases be accounted for by implementing a single generalized feature? Can a known needed use case be extrapolated into a feature that supports that use case along with other use cases that are not yet known to be needed? If so, use these considerations when designing your APIs.
+
+### Sensible defaults, powerful configuration, and last-resort "escape hatches"
+
+- Defaults should take users down the “happy path” and place them into the “pit of success.”
+- Configuration allows the component to reach more use cases. Components that use configurations to deviate from defaults should be viewed as first-class supported scenarios, just as important as the defaults.
+- Escape hatches may be necessary to support consumers with requirements that we haven’t considered. It should be cleared that using escape hatches “voids your warranty,” yet, they should be fully documented.
+
+### Arguments to behaviors
+
+- As mentioned above, behaviors should have sensible defaults but powerful configuration. Behaviors are configured via arguments passed to the hook.
+- When possible, a hook should be able to be called with zero arguments to get all the defaults.
+- Each argument that is required should have an individual parameter on the hook function.
+- Optional arguments (i.e. “settings”) should be provided via a strongly typed settings object as the last argument to a hook function.
+
+### Return value of behavior hooks
+
+#### Component behavior hook return value
+
+Component behavior hooks produce _props_. Therefore, the return value of a component behavior should be a collection of props objects, intended to be spread onto JSX elements that render a component.
+
+- Each element of the object returned from a component behavior hook is a props object that can be spread onto a JSX element
+- The names of the keys should accurately indicate the JSX element onto which those props should be spread
+
+Example: The Dialog component uses a `usePopover` component behavior, which may return an object like:
+
+```
+{
+  popoverProps: PropsObject,
+  openClickTargetProps: PropsObject,
+  closeClickTargetProps: PropsObject
+}
+```
+
+Each of these props objects would then get spread onto their respective JSX elements.
+
+#### Generic behavior hook return value
+
+There are no restrictions on return values of generic behavior hooks. In fact, some behavioral hooks might not need to return anything. For example, a `useEscape` hook might simply set up a callback for an `Escape` keypress.
+
+### Refs
+
+- Often, a behavior will need to act on a real DOM element.
+- In this case, the hook should return a ref as part of the returned props for that element. The ref will get spread onto the element, giving the ref access to it.
+- Whenever you need a ref, it must be accepted as an optional setting to the hook. The hook then uses the `useProvidedRefOrCreate` hook to resolve a usable ref. Remember to return the resulting ref from the hook.
+
+## Testing behaviors
+
+- Whenever possible, test your changes in another application that makes heavy use of Primer Components.
+- You may even want to build and “marinate” your component in another application before merging a change to Primer Components.
+- Build the component, start using it in the application, and see how the component API feels. This approach works best for engineers at GitHub already working on a product written in React.

package/contributor-docs/component-contents-api-patterns.md

@@ -0,0 +1,315 @@
+# React Component APIs: Contents as data vs. Contents as children
+
+Consider a React component that renders a list of items. Here are two possible APIs that component might expose, both achieving an equivalent result.
+
+### A: Contents passed as React children
+
+```jsx
+<List>
+  <List.Item>New file</List.Item>
+  <List.Divider />
+  <List.Item>Copy link</List.Item>
+  <List.Item>Edit file</List.Item>
+  <List.Item variant="danger">Delete file</List.Item>
+</List>
+```
+
+### B: Contents passed as data
+
+```jsx
+<List
+  items={[
+    { text: "New file" },
+    ActionList.Divider,
+    { text: "Copy link" },
+    { text: "Edit file" },
+    { text: "Delete file", variant: "danger" },
+  ]}
+/>
+```
+
+Is one API better than the other generally? What about in this context (a "List" component)? Are there situations where it is better to choose one over the other? Let's try to answer these questions.
+
+## Both APIs have valid use cases
+
+This section simply argues that both of the patterns above are valid. Once we do this, we can attempt to define the criteria that helps the API designer choose one over the other.
+
+### Contents passed as React children
+
+This is the most common way to define the structure of content in React. In fact, all HTML elements work this way:
+
+```jsx
+<div>
+  <div>Some content</div>
+  <div>More content</div>
+</div>
+```
+
+```jsx
+<ul>
+  <li>Item 1</li>
+  <li>Item 2</li>
+</ul>
+```
+
+```jsx
+<select>
+  <option value="1">First option</option>
+  <option value="1">Second option</option>
+</select>
+```
+
+Though less common, sometimes the HTML schema puts tight restrictions on the kinds of children an element may contain:
+
+- `<select>` elements may only contain `<option>` and `<optgroup>` children.
+- `<ul>` may only contain `<li>` children.
+- `<span>` elements may only contain [phrasing content](https://html.spec.whatwg.org/multipage/dom.html#phrasing-content-2).
+
+Furthermore, for custom React components, there is a first-class approach for rendering your component's children:
+
+```jsx
+function MyFancyBox({ children }) {
+  return <div style="border: 4px double cornflowerblue;">{children}</div>;
+}
+
+// usage
+<MyFancyBox>I have a blue border!</MyFancyBox>;
+```
+
+I call this "first class" because the JSX children that are defined between your component's opening and closing tags are wrapped up into a special prop called `children`. It is the component's responsibility to render those children in the appropriate spot.
+
+**Clearly, this is a valid approach for a component API.**
+
+### Contents passed as data
+
+An alternative approach is to accept data in the form of a prop, which eventually gets turned into a React element by the component's implementation. In plain HTML, this is far less common. One example is the `title` attribute, which results in a tooltip:
+
+```html
+<button title="Save">💾</button>
+```
+
+One _could_ imagine a parallel universe where a tooltip is achieved by some other means!
+
+```html
+<button>
+    <title>Save</title>
+    💾
+</button>
+```
+
+In custom React components, this pattern can be more common. In this example, the text to render is passed as a prop, as data rather than as pre-created React elements (i.e. JSX):
+
+```jsx
+function WordWrap({ text, charactersPerLine }) {
+  const lines = [];
+  for (
+    let low = 0;
+    low + charactersPerLine < text.length;
+    low += charactersPerLine
+  ) {
+    lines.push(text.substr(low, charactersPerLine));
+  }
+  const remaining = text.length % charactersPerLine;
+  if (remaining !== 0) {
+    lines.push(text.substr(text.length - remaining));
+  }
+  return (
+    <>
+      {lines.map((l, index) => (
+        <div key={index + l}>{l}</div>
+      ))}
+    </>
+  );
+}
+
+// usage
+<WordWrap
+  text="the quick brown fox jumps over the lazy dog"
+  charactersPerLine={5}
+/>;
+```
+
+For further customization, one could imagine an optional `renderLine` prop that is used to give consumers control over the way a single line is rendered (see the section "Customization of content passed as data" below).
+
+## Can't we just stick to one of the two patterns?
+
+As shown above, both patterns can be valid approaches based on the component. But _why_ did we choose the data API for `WordWrap`, and _why_ did we choose the React children API for `MyFancyBox`?
+
+### Let's try swapping
+
+Since both patterns are equally powerful, we should be able to write equivalent components using the alternate approach.
+
+#### MyFancyBox
+
+Let's start with `MyFancyBox`:
+
+```jsx
+function MyFancyBox({ contents }) {
+  const boxChildren = [];
+  if (typeof contents === "string" || React.isValidElement(contents)) {
+    boxChildren.push(contents);
+  } else if (typeof contents === "function") {
+    boxChildren.push(contents());
+  } // implementation abbreviated for clarity
+  return <div style="border: 4px double cornflowerblue;">{boxChildren}</div>;
+}
+
+// usage
+<MyFancyBox contents="I have a blue border!" />;
+```
+
+This example is so esoteric that I think it's obvious which is superior. The original has a less-complex implementation and a clearer API (in the second, just looking at the usage example, there is no way to know that contents can also accept a React element or a function callback).
+
+#### WordWrap
+
+Now let's dive into `WordWrap`, implemented with a React children-based API:
+
+```jsx
+function WordWrap({ children, charactersPerLine }) {
+  let textContent = "";
+  React.Children.forEach(children, (child) => {
+    if (typeof child === "string") {
+      textContent += child;
+    }
+  });
+  const lines = [];
+  for (
+    let low = 0;
+    low + charactersPerLine < textContent.length;
+    low += charactersPerLine
+  ) {
+    lines.push(textContent.substr(low, charactersPerLine));
+  }
+  const remaining = textContent.length % charactersPerLine;
+  if (remaining !== 0) {
+    lines.push(textContent.substr(textContent.length - remaining));
+  }
+  return (
+    <>
+      {lines.map((l, index) => (
+        <div key={index + l}>{l}</div>
+      ))}
+    </>
+  );
+}
+
+// usage
+<WordWrap charactersPerLine={5}>
+  the quick brown fox jumps over the lazy dog
+</WordWrap>;
+```
+
+Let's get the obvious out of the way: the component implementation is more complex. Instead of receiving the raw text as a prop, the component has to iterate through its children, figure out which ones are text nodes, and build up the string.
+
+But sometimes we are willing to make the sacrifice of increasing the complexity of our components if they become easier to use for our consumers. Is that what is happening here? One could argue that our new API is more straightforward and more readable! It's clear that the child text node of `WordWrap` will serve as the eventually-rendered contents, whereas the prop passed (`charactersPerLine`) is more of a configuration of the behavior.
+
+On the other hand, if you are consuming this `WordWrap`, you might be left more confused. It is not clear without reading the code what is allowed as a child node. Can I include links or styled elements? How does it respond to receiving component children? In fact, if we want to the [principle of least surprise](https://en.wikipedia.org/wiki/Principle_of_least_astonishment), it may be necessary to support links or bolded text. While possible, this greatly increases the complexity of the component. Even if we do support this, it might be hard to discover this feature unless the user reads the docs or source code.
+
+The first `WordWrap` implementation comparatively has a very strict API, easily discovered (with strong typing), and there is no possible way to use it which would produce a surprising result.
+
+Because of the trade-offs described, I postulate that the first implementation of `WordWrap` is superior.
+
+### The hybrid approach
+
+It is possible to build a component API that supports both patterns. In other words, the consumer can pass data as a prop, which gets rendered into React elements, while also accepting those children being passed in directly.
+
+We do not recommend this approach. The resulting behavior can be very hard to predict. How do the elements generated from data interact with the passed-in children? How are they ordered? Furthermore, the approach likely does not improve the developer experience.
+
+## The ownership of React elements
+
+I shall make the following claim:
+
+> The owner of a React element is the component that _originally_ added it to the component tree.
+
+For example, take the following two implementations of a simple (contrived) List component:
+
+```jsx
+function List({ children, ordered }) {
+  const Elem = ordered ? "ol" : "ul";
+  return <Elem>{children}</Elem>;
+}
+function Item({ children }) {
+  return <li>{children}</li>;
+}
+
+// usage
+function MyApp() {
+  return (
+    <List ordered={true}>
+      <Item>Apple</Item>
+      <Item>Banana</Item>
+      <Item>Cantaloupe</Item>
+    </List>
+  );
+}
+```
+
+```jsx
+function List({ items, ordered }) {
+  const Elem = ordered ? "ol" : "ul";
+  const items = items.map((i) => <li key={i}>i</li>);
+  return <Elem>{items}</Elem>;
+}
+
+// usage
+function MyApp() {
+  return <List ordered={true} items={["Apple", "Banana", "Cantaloupe"]} />;
+}
+```
+
+In the first example, `MyApp` "owns" the `List` and its 3 `Item`s. In the second example, `MyApp` only "owns" `List`, while the `List` owns the `Item`s it renders.
+
+Why do I bring this up? If you assume that the _owner_ of an element has the _highest authority_ to configure that element (i.e. change the element type, its props, and its children), then any component API should strive to be designed to respect this assumption.
+
+I believe this is a reasonable assumption: an element owner should be able to expect that the element will be rendered as close to the definition as possible. Otherwise, this violates the principle of least surprise.
+
+### The `React.Children` anti-pattern
+Based on the above assumption, using `React.Children` can be an anti-pattern. `React.Children` allows a component to reach into elements that it does not own. In our `WordWrap` example that uses React children, it is clear that we do not respect the owner (as defined above) of these elements. We iterate through children, ignoring anything that is not a text node.
+
+With this reasoning, it's also easy to argue that `React.cloneElement` should be an anti-pattern. While that is true, there are ways to use `React.cloneElement` to simply augment children without altering their primary purpose or function. Adding additional props is a common use.
+
+While anti-patterns sometimes have their valid uses, those uses should be individually scrutinized and avoided where possible.
+
+## Customization of content passed as data
+
+One significant benefit to the contents as children pattern is the fact that it lends itself very naturally to customization. Since the parent owns the children, it can create whatever children it likes, deciding their props and element types. This level of customization can be achieved using the contents as data pattern too, but it's not quite as straightforward (for the component author or the component consumer).
+
+One common practice is for a component to accept a "render prop." The render prop is a function that returns JSX (the same as a function component). That function should be passed any data that may be needed for rendering. Of course, components should ship with a default renderer and not rely on being passed a render prop. 
+
+## How to decide
+
+At this point we have shown that both patterns are valid, so how do we know which to use? Here is a comparison of the two approaches:
+
+### Advantages of data contract
+
+- Strongly typed
+- All use cases are clearly defined
+- Easy to manipulate data
+- Easy to define a "pit of success" and lead the user there
+- Can support "escape hatches"
+- Component retains ownership of rendered contents
+- Usually less code in the implementation
+
+### Advantages of children-based contract
+
+- Indicates flexibility
+- Leaves room for a flexible implementation
+- Recognizable from HTML
+- Easier to read
+- Ownership of contents remains with a parent or ancestor component
+
+Based on these observations, here are some guidelines to decide which type of API to build:
+
+### When to use a data contract
+- Data doesn't cleanly transfer to an element structure
+- Data needs to be manipulated before being converted to an element structure
+- Certain well-defined scenarios need to be supported
+- You want to control the types and structure of child elements
+- The default rendering of the component is useful in many cases
+- You are building a composite component
+
+### When to use a children-based contract
+- Your component doesn't care about the structure of children
+- Your component doesn't need to use `React.Children`
+- Your component is flexible enough to accommodate almost any child structure
+- You are building an intermediate component that provides behaviors or styles to a container

package/contributor-docs/principles.md

@@ -0,0 +1,39 @@
+# Principles
+
+### Communication
+
+Design systems provide a vocabulary between design and engineering, the language we use should be correct but not at the expense of providing clarity. Use words and descriptions that both designers and engineers can understand.
+
+* Be a bridge not a barrier. Use vocabulary that provides meaning to both designers and engineers.
+* Choose language that provides mutual understanding between engineering and design over specificity.
+* Support new vocabulary with descriptions and examples.
+* Be consistent in the application of vocabulary in written and verbal communication to reinforce understandings.
+* Articulate what you are aiming to achieve as well as what you are not doing.
+
+### Judgment
+
+There's often more than one way to do things, and there aren't always best-practice examples to follow. Despite this we still need to make decisions and keep moving forward. To deal with an uncertain future and still move forward we should have _strong opinions, weakly held_.
+
+* Make decisions that move us forward rather than halting progress due to ambiguity or difference of opinion.
+* Make decisions based on long term goals rather than this week's ship.
+* Evaluate technology by the risk they present, not just the solution they offer. High risk deserves careful consideration, low risk deserves less attention.
+* Have opinions and arguments for them, but remain open to seeing and hearing evidence that clashes with them when those opinions become wrong.
+* Prioritize solutions for people who use the system and how it serves the customers who use products built with the system.
+* Seek feedback on code review often, and more often when a solution takes you down a new path.
+* Take time to provide good code review, encompassing the above values when providing feedback.
+
+### Innovation
+
+* Treat everything as an experiment. Make small incremental steps that provide proof towards goals, or disprove them.
+* Ship often. We learn more from tangible outcomes than something that only lives as an idea.
+* Work on reducing complexity and simplifying solutions to enable us to innovate faster.
+
+### Implementation
+
+* Engineer just enough of a solution, value declarative over abstraction.
+* A little verbosity is better than clever code. Avoid implementations that reduce the ability for people to contribute.
+* Automate and abstract when repetition is a hindrance.
+* Seek feedback on implementations as often as possible.
+* Everything is a component.
+* Provide flexibility, but within the boundaries of the system.
+* Assume that people will break the rules, and provide safe ways for them to do so.