@primer/components 33.1.0-rc.6856bcf5 → 33.1.0

package/contributor-docs/behaviors.md

@@ -1,132 +0,0 @@
-_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

@@ -1,316 +0,0 @@
-# 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 }) {
-  const items = React.Children.toArray(children);
-  let textContent = "";
-  for (const child of items) {
-    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 listItems = items.map((i) => <li key={i}>i</li>);
-  return <Elem>{listItems}</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

@@ -1,39 +0,0 @@
-# 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.

package/docs/.gitignore

@@ -1,91 +0,0 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
-node_modules/
-jspm_packages/
-
-# TypeScript v1 declaration files
-typings/
-
-# TypeScript cache
-*.tsbuildinfo
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variables file
-.env
-.env.test
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-
-# next.js build output
-.next
-
-# nuxt.js build output
-.nuxt
-
-# vuepress build output
-.vuepress/dist
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# Gatsby
-public/

package/docs/components/PropsList.js

@@ -1,5 +0,0 @@
-import React from 'react'
-
-const PropsList = ({systemProps}) => <div>{systemProps.propNames.join(', ')}</div>
-
-export default PropsList

package/docs/components/State.js

@@ -1,9 +0,0 @@
-import React from 'react'
-
-const State = props => {
-  const result = React.useState(props.default)
-
-  return props.children(result)
-}
-
-export default State

package/docs/components/constants.js

@@ -1,34 +0,0 @@
-import {theme} from '@primer/components'
-import systemPropTypes from '@styled-system/prop-types'
-import themeGet from '@styled-system/theme-get'
-import * as styledSystem from 'styled-system'
-
-const {get: getKey, compose, system} = styledSystem
-
-export const get = key => themeGet(key, getKey(theme, key))
-
-const whiteSpace = system({
-  whiteSpace: {
-    property: 'whiteSpace',
-    cssProperty: 'whiteSpace'
-  }
-})
-
-export const TYPOGRAPHY = compose(styledSystem.typography, whiteSpace)
-
-export const COMMON = compose(styledSystem.space, styledSystem.color, styledSystem.display)
-
-export const BORDER = compose(styledSystem.border, styledSystem.shadow)
-
-// these are 1:1 with styled-system's API now,
-// so you could consider dropping the abstraction
-export const LAYOUT = styledSystem.layout
-export const POSITION = styledSystem.position
-export const FLEX = styledSystem.flexbox
-export const GRID = styledSystem.grid
-
-TYPOGRAPHY.propTypes = systemPropTypes.typography
-LAYOUT.propTypes = systemPropTypes.layout
-POSITION.propTypes = systemPropTypes.position
-FLEX.propTypes = systemPropTypes.flexbox
-GRID.propTypes = systemPropTypes.grid

package/docs/components/index.js

@@ -1,2 +0,0 @@
-export {default as PropsList} from './PropsList'
-export {COMMON, LAYOUT, BORDER, TYPOGRAPHY, FLEX, POSITION, GRID} from './constants'