@primer/components 29.1.0 → 29.1.1-rc.cea79543

package/docs/content/theming.md

@@ -0,0 +1,249 @@
+---
+title: Theming
+description: Theming in Primer React is made possible by a theme object that defines your application's colors, spacing, fonts, and more.
+---
+
+## ThemeProvider
+
+To give components access to the theme object, you must add `ThemeProvider` to the root of your application:
+
+```jsx
+import {ThemeProvider} from '@primer/components'
+
+function App() {
+  return (
+    <ThemeProvider>
+      <div>...</div>
+    </ThemeProvider>
+  )
+}
+```
+
+`ThemeProvider` comes with a [default theme object](/theme-reference) that includes colors, spacing, fonts, etc. for building applications at GitHub.
+
+## Customizing the theme
+
+To customize the [default theme](/theme-reference), you can pass your custom theme to `ThemeProvider` using the `theme` prop:
+
+```jsx
+import {ThemeProvider, theme} from '@primer/components'
+import deepmerge from 'deepmerge'
+
+const customTheme = deepmerge(theme, {
+  fonts: {
+    mono: 'Monolisa, monospace'
+  }
+})
+
+function App() {
+  return (
+    <ThemeProvider theme={customTheme}>
+      <div>...</div>
+    </ThemeProvider>
+  )
+}
+```
+
+Some components may break if your custom theme does not include all the same keys as the [default theme](/theme-reference). For that reason, we recommend extending the default theme using [deepmerge](https://www.npmjs.com/package/deepmerge).
+
+## Referencing theme values
+
+You can reference theme values in your application using [system props](/system-props), the [`sx` prop](/overriding-styles), the `themeGet` function, or the `useTheme` hook.
+
+### System props and the `sx` prop
+
+Some [system props](/system-props) and [`sx` prop](/overriding-styles) keys are theme-aware. For example, the `bg` prop maps to the `colors` theme key which means you can use the `bg` prop to reference values in the `colors` object:
+
+```jsx
+const theme = {
+  colors: {
+    bg: {
+      primary: '#fff'
+    }
+  }
+}
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <Box bg="bg.primary"></Box>
+      <Box sx={{bg: 'bg.primary'}}></Box>
+    </ThemeProvider>
+  )
+}
+```
+
+See the [Styled System Reference Table](https://styled-system.com/table) for a complete list of mappings.
+
+### themeGet
+
+The `themeGet` function is a convienient way to reference theme values in styled-components template literals:
+
+```js
+import {themeGet} from '@primer/components'
+import styled from 'styled-components'
+
+const Example = styled.div`
+  background-color: ${themeGet('colors.bg.primary')};
+`
+```
+
+### useTheme
+
+You can use the `useTheme` hook to reference theme values from inside any function component nested under the `ThemeProvider`:
+
+```js
+import {ThemeProvider, useTheme} from '@primer/components'
+
+function Example() {
+  const {theme} = useTheme()
+  // theme.colors.bg.primary
+}
+
+function App() {
+  return (
+    <ThemeProvider>
+      <Example />
+    </ThemeProvider>
+  )
+}
+```
+
+<Note variant="warning">
+
+Only use `useTheme` to reference theme values in places where it's not possible to use system props, the `sx` prop, or `themeGet`.
+
+</Note>
+
+## Color modes and color schemes
+
+The terms "color mode" and "color scheme" are often used interchangeably. However, in Primer React, they are two separate (but related) concepts.
+
+The "color mode" of an application can be either `day`, `night`, or `auto` (i.e. synced with the operating system).
+
+A "color scheme", on the other hand, is a collection of colors that can be associated with a color mode. The [default theme](/theme-reference) includes three color schemes: `light`, `dark`, and `dark_dimmed`. By default, the `light` scheme is displayed when the application is in `day` mode and the `dark` scheme is displayed in `night` mode.
+
+### Setting the color mode
+
+By default, Primer React is in `day` mode. To change the color mode, use the `colorMode` prop on `ThemeProvider` or the `setColorMode` function from the `useTheme` hook:
+
+#### `colorMode` prop
+
+```jsx
+import {ThemeProvider} from '@primer/components'
+
+function App() {
+  return (
+    // colorMode can be "day" (default), "night", or "auto"
+    <ThemeProvider colorMode="auto">
+      <div>...</div>
+    </ThemeProvider>
+  )
+}
+```
+
+#### `setColorMode` function
+
+```jsx
+import {useTheme} from '@primer/components'
+
+function Example() {
+  const {setColorMode} = useTheme()
+  return <button onClick={() => setColorMode('auto')}>Activate auto mode</button>
+}
+```
+
+### Setting color schemes
+
+To choose which color schemes will be displayed in `day` and `night` mode, use the `dayScheme` and `nightScheme` props on `ThemeProvider` or the `setDayScheme` and `setNightScheme` functions from the `useTheme` hook:
+
+#### `dayScheme` and `nightScheme` props
+
+```jsx
+import {ThemeProvider} from '@primer/components'
+
+function App() {
+  return (
+    // The default theme includes `light`, `dark`, and `dark_dimmed` schemes
+    <ThemeProvider dayScheme="light" nightScheme="dark_dimmed">
+      <div>...</div>
+    </ThemeProvider>
+  )
+}
+```
+
+#### `setDayScheme` and `setNightScheme` functions
+
+```jsx
+import {useTheme} from '@primer/components'
+
+function Example() {
+  const {setDayScheme, setNightScheme} = useTheme()
+  return <button onClick={() => setNightScheme('auto')}>Activate auto mode</button>
+}
+```
+
+### Customizing or adding color schemes
+
+To customize or add color schemes, update the `colorSchemes` object in the theme:
+
+```jsx
+import {ThemeProvider, theme} from '@primer/components'
+import deepmerge from 'deepmerge'
+
+const customTheme = deepmerge(theme, {
+  colorSchemes: {
+    // Customize an existing scheme
+    light: {
+      colors: {
+        text: {
+          primary: '#f00'
+        }
+      }
+    },
+    // Add a new scheme
+    my_scheme_name: {
+      colors: {...},
+      shadows: {...}
+    }
+  }
+})
+
+function App() {
+  return (
+    <ThemeProvider theme={customTheme}>
+      <div>...</div>
+    </ThemeProvider>
+  )
+}
+```
+
+### Creating local color scheme variables
+
+If you need to use a color that is not defined in the theme, avoid hard coding the color value like this:
+
+```jsx
+function Example() {
+  return (
+    // BAD: #aaa may not look good in all color schemes
+    <Box bg="#aaa">Hello world</Box>
+  )
+}
+```
+
+Instead, use the `useColorSchemeVar` hook to create a local variable that will update based on the active color scheme:
+
+```jsx
+import {useColorSchemeVar} from '@primer/components'
+import {colors} from '@primer/primitives'
+
+function Example() {
+  // GOOD: The value of `customBg` changes based on the active color scheme
+  const customBg = useColorSchemeVar({
+    light: colors.light.scale.gray[1],
+    dark: colors.dark.scale.gray[9],
+    dark_dimmed: colors.dark_dimmed.scale.gray[2]
+  })
+  return <Box bg={customBg}>Hello world</Box>
+}
+```

package/docs/content/useOnEscapePress.mdx

@@ -0,0 +1,56 @@
+---
+title: useOnEscapePress
+---
+
+`useOnEscapePress` is a simple utility Hook that calls a user-provided function when the `Escape` key is pressed. The hook sets up `keydown` event listener on `window.document` and executes the user-provided function if these conditions are met:
+
+1. The Escape key was pressed
+2. The `preventDefault` method has not yet been called on the event object.
+
+Furthermore, unlike the normal behavior for multiple event listeners existing on the same DOM Node, if multiple `useOnEscapePress` hooks are active simultaneously, the callbacks will occur in reverse order. In other words, if a parent component and a child component both call `useOnEscapePress`, when the user presses Escape, the child component's callback will execute, followed by the parent's callback. Each callback has the chance to call `.preventDefault()` on the event to prevent further callbacks.
+
+### Dependencies
+
+Similar to `useCallback`, `useOnEscapePress` takes a `React.DependencyList` as its second argument. These are the dependencies used to memoize the callback. Failing to provide the correct dependency list can result in degraded performance. If this argument is omitted, we will assume that the callback is already memoized. In the example below, that memoization occurs in `DemoComponent` with a call to `React.useCallback`, so `OverlayDemo` does not need to pass a dependency list.
+
+### Usage
+
+```javascript live noinline
+const OverlayDemo = ({onEscape, children}) => {
+  useOnEscapePress(onEscape)
+  return (
+    <Box height="200px">
+      {children}
+    </Box>
+  )
+}
+
+function DemoComponent() {
+  const [isOpen, setIsOpen] = React.useState(false)
+  const toggleOverlay = React.useCallback(() => {
+    setIsOpen(!isOpen)
+  })
+  const closeOverlay = React.useCallback(() => {
+    setIsOpen(false)
+  })
+  return (
+    <>
+      <Button onClick={toggleOverlay}>toggle</Button>
+      {isOpen &&
+        <OverlayDemo onEscape={closeOverlay}>
+          <Button>Button One</Button>
+          <Button>Button Two</Button>
+        </OverlayDemo>}
+    </>
+  )
+}
+
+render(<DemoComponent/>)
+```
+
+#### useOnEscapePress
+
+| Name | Type | Default | Description |
+| :- | :- | :-: | :- |
+| onEscape | `(event: KeyboardEvent) => void` | | Function to call when user presses the Escape key |
+| callbackDependencies | `React.DependencyList` | | Array of dependencies for memoizing the given callback |

package/docs/content/useOnOutsideClick.mdx

@@ -0,0 +1,57 @@
+---
+title: useOnOutsideClick
+---
+
+`useOnOutsideClick` is a utility Hook that calls a user provided callback function when the user clicks outside of the provided container.
+
+You can also pass an array of `ignoredRefs` to prevent calling the callback function on additional elements on the page. This can be handy for ignoring clicks on trigger buttons that already manage the open/closed state of content.
+
+### Usage
+
+```jsx live
+<State>
+  {([isOpen, setIsOpen]) => {
+    const containerRef = React.useRef(null)
+    const triggerRef = React.useRef(null)
+
+    const closeOverlay = React.useCallback(() => {
+      setIsOpen(false)
+    }, [setIsOpen])
+
+    const toggleOverlay = React.useCallback(() => {
+      setIsOpen(!isOpen)
+    }, [setIsOpen, isOpen])
+
+    useOnOutsideClick({onClickOutside: closeOverlay, containerRef, ignoreClickRefs: [triggerRef]})
+
+    return (
+      <>
+        <Button ref={triggerRef} onClick={toggleOverlay}>
+          toggle
+        </Button>
+        {isOpen && (
+          <Box
+            borderWidth="1px"
+            borderStyle="solid"
+            borderColor="border.primary"
+            borderRadius={2}
+            height="200px"
+            bg="green.4"
+            ref={containerRef}
+          >
+            content
+          </Box>
+        )}
+      </>
+    )
+  }}
+</State>
+```
+
+#### useOnOutsideClick settings
+
+| Name           | Type                              | Default | Description                                                                                                                     |
+| :------------- | :-------------------------------- | :-----: | :------------------------------------------------------------------------------------------------------------------------------ |
+| onOutsideClick | `function`                        |         | Function to call when user clicks outside of the container. Usually this manages the state of the visibilitiy of the container. |
+| ignoredRefs    | `React.RefObject<HTMLElement> []` |         | Elements outside of the container to ignore clicks on.                                                                          |
+| containerRef   | `React.RefObject<HTMLElement>`    |         | Required. A ref for the containing element.                                                                                     |

package/docs/content/useOpenAndCloseFocus.mdx

@@ -0,0 +1,49 @@
+---
+title: useOpenAndCloseFocus
+---
+
+`useOpenAndCloseFocus` is a utility Hook that manages focusing an element when a component is first mounted, and returns focus to an element on the page when that component unmounts.
+
+If no ref is passed to `inititalFocusRef` , the hook focuses the first focusable element inside of the container.
+
+
+### Usage
+
+```javascript live noinline
+const Overlay = ({returnFocusRef, initialFocusRef, children}) => {
+  const containerRef = React.useRef(null)
+  useOpenAndCloseFocus({containerRef, returnFocusRef, initialFocusRef})
+  return (
+    <Box height="200px" ref={containerRef}>
+      {children}
+    </Box>
+  )
+}
+
+function Component() {
+  const returnFocusRef = React.useRef(null)
+  const initialFocusRef = React.useRef(null)
+  const [isOpen, setIsOpen] = React.useState(false)
+  return (
+    <Box sx={{'*': { ':focus' : { backgroundColor: 'red.5'}}}}>
+      <Button ref={returnFocusRef} onClick={() => setIsOpen(!isOpen)}>toggle</Button>
+      {isOpen &&
+        <Overlay returnFocusRef={returnFocusRef} initialFocusRef={initialFocusRef}>
+          <Button>Button One</Button>
+          <Button ref={initialFocusRef}>Button Two</Button>
+        </Overlay>}
+    </Box>
+  )
+}
+
+render(<Component/>)
+```
+
+
+#### useOpenAndCloseFocus settings
+
+| Name | Type | Default | Description |
+| :- | :- | :-: | :- |
+| initialFocusRef | `React.RefObject<HTMLElement>` | | Optional. The element to focus when the container is mounted on the page. |
+| returnFocusRef | `React.RefObject<HTMLElement>` | | Required. The element to focus when the container is unmounted. |
+| containerRef | `React.RefObject<HTMLElement>` | | Required. A ref for the containing element. |

package/docs/content/useOverlay.mdx

@@ -0,0 +1,62 @@
+---
+title: useOverlay
+---
+
+`useOverlay` calls all of the relevant behavior Hooks that all `Overlay` components & composite components should have and returns a ref to be passed down to the overlay's container.
+
+These behaviors include:
+
+- Correctly positioning the component based on the values provided to `positionSettings` and `positionDeps`.
+- Trapping focus
+- Calling a user provided function when the user presses `Escape`
+- Calling a user provided function when the user clicks outside of the container
+- Focusing the either a user provided element, or the first focusable element in the container when it is opened.
+- Returning focus to an element when container is closed
+
+**Note:** `useOverlay` and `Overlay` do not manage the open state of the overlay. We leave control of the open state up to the user. All behaviors are built with the assumption that the overlay will not be rendered on the page & fully unmounted when it is not visible. See the examples for details on how to conditionally render a component in JSX.
+
+### Usage
+
+```javascript live noinline
+
+const DemoOverlay = ({onClickOutside, initialFocusRef, returnFocusRef, ignoreClickRefs, onEscape, ...rest}) => {
+    const overlayProps = useOverlay({returnFocusRef, onEscape, ignoreClickRefs, onClickOutside, initialFocusRef})
+    return <Box height="200px" bg="green.4" {...overlayProps} {...rest}/>
+}
+
+const DemoComponent = () => {
+  const returnFocusRef = React.useRef(null)
+  const initialFocusRef = React.useRef(null)
+  const [isOpen, setIsOpen] = React.useState(false)
+  const closeOverlay = () => setIsOpen(false)
+  return (
+    <>
+      <Button ref={returnFocusRef} onClick={() => setIsOpen(!isOpen)}>toggle</Button>
+      {isOpen &&
+        <DemoOverlay
+          returnFocusRef={returnFocusRef}
+          ignoreClickRefs={[returnFocusRef]}
+          initialFocusRef={initialFocusRef}
+          onEscape={closeOverlay}
+          onClickOutside={closeOverlay}
+        >
+          <Button>Button One</Button>
+          <Button ref={initialFocusRef}>Button Two</Button>
+        </DemoOverlay>}
+    </>
+  )
+}
+
+render(<DemoComponent/>)
+```
+
+
+#### UseOverlaySettings
+
+| Name | Type | Required | Description |
+| :- | :- | :-: | :- |
+| onEscapePress | `function` | required | Function to call when user presses the Escape key |
+| onOutsideClick | `function` | required | Function to call when user clicks outside of the overlay |
+| ignoreClickRefs | `React.RefObject<HTMLElement> []` | optional | Refs to click clicks on in the `onOutsideClick` function, useful for ignoring clicks on elements that trigger the overlay visibility. |
+| initialFocusRef | `React.RefObject<HTMLElement>` | optional | Ref to focus when overlay is mounted. |
+| returnFocusRef | `React.RefObject<HTMLElement>` | required | Ref to focus when overlay is unmounted. Important for accessibility. |

package/docs/content/useSafeTimeout.mdx

@@ -0,0 +1,32 @@
+---
+title: useSafeTimeout
+---
+
+`useSafeTimeout` is a utility Hook that allows you to safely call `setTimeout` and `clearTimeout` within a component, ensuring that all timeouts are cleared when the component unmounts.
+
+
+### Usage
+
+```jsx live
+<State>
+  {([]) => {
+    const {safeSetTimeout, safeClearTimeout} = useSafeTimeout()
+    let timeoutId = null
+
+    const handleOnClick = () => {
+      timeoutId = safeSetTimeout(() => window.alert('hello!'), 5000)
+    }
+
+    const cancelTimeout = () => {
+      safeClearTimeout(timeoutId)
+    }
+
+    return (
+      <>
+        <Button onClick={handleOnClick}>Click me</Button>
+        <Button onClick={cancelTimeout}>Cancel timeout</Button>
+      </>
+    )
+  }}
+</State>
+```

package/docs/gatsby-config.js

@@ -0,0 +1,30 @@
+const path = require('path')
+
+module.exports = {
+  siteMetadata: {
+    title: 'Primer React',
+    shortName: 'React',
+    description: 'React components for the Primer design system'
+  },
+  plugins: [
+    'gatsby-plugin-typescript',
+    {
+      resolve: '@primer/gatsby-theme-doctocat',
+      options: {
+        repoRootPath: '..',
+        defaultBranch: 'main'
+      }
+    },
+    {
+      resolve: `gatsby-plugin-alias-imports`,
+      options: {
+        alias: {
+          '@primer/components': path.resolve(__dirname, '../src'),
+          'styled-components': path.resolve(__dirname, '..', 'node_modules', 'styled-components'),
+          react: path.resolve(__dirname, 'node_modules', 'react')
+        }
+      }
+    }
+  ],
+  pathPrefix: '/react'
+}

package/docs/gatsby-node.js

@@ -0,0 +1,101 @@
+const defines = require('../babel-defines')
+const docgen = require('react-docgen-typescript')
+const globby = require('globby')
+
+exports.onCreateWebpackConfig = ({actions, plugins, loaders, getConfig}) => {
+  const config = getConfig()
+  // Add our `__DEV__` and `process.env.NODE_ENV` defines
+  config.plugins.push(plugins.define(defines[process.env.NODE_ENV || 'development']))
+
+  config.module.rules = [
+    ...config.module.rules,
+    // Create a custom configuration.
+    {
+      // The new configuration is based off the original...
+      ...loaders.js(),
+      test: /\.jsx?$/,
+      exclude: modulePath => /node_modules/.test(modulePath),
+      // ...except that we want to run Primer React through webpack as well.
+      // By default, Gatsby won't use the define plugin we added above on Primer React.
+      include: modulePath => /@primer\/components/.test(modulePath)
+    }
+  ]
+
+  // Polyfill `path` and stub `fs` for use in the browser
+  // https://www.gatsbyjs.com/docs/reference/release-notes/migrating-from-v2-to-v3/#webpack-5-node-configuration-changed-nodefs-nodepath-
+  config.resolve = {
+    ...config.resolve,
+    alias: {
+      ...config.resolve.alias,
+      path: require.resolve('path-browserify')
+    },
+    fallback: {
+      ...config.resolve.fallback,
+      fs: false
+    }
+  }
+
+  actions.replaceWebpackConfig(config)
+}
+
+exports.sourceNodes = ({actions, createNodeId, createContentDigest}) => {
+  const {createNode} = actions
+
+  // Extract compontent metadata from source files
+  const files = globby.sync(['../src/**/*.tsx'], {absolute: true})
+  const data = docgen.parse(files, {
+    savePropValueAsString: true,
+    propFilter: prop => {
+      if (prop.declarations !== undefined && prop.declarations.length > 0) {
+        const hasPropAdditionalDescription = prop.declarations.find(declaration => {
+          return !declaration.fileName.includes('node_modules')
+        })
+
+        return Boolean(hasPropAdditionalDescription)
+      }
+
+      return true
+    }
+  })
+
+  const components = data.map(component => {
+    return {
+      name: component.displayName,
+      description: component.description,
+      props: Object.values(component.props)
+        .map(prop => {
+          return {
+            name: prop.name,
+            description: prop.description,
+            defaultValue: prop.defaultValue ? prop.defaultValue.value : '',
+            required: prop.required,
+            type: prop.type.name
+          }
+        })
+        // Move required props to beginning of the list
+        .sort((a, b) => {
+          if (a.required && !b.required) return -1
+          if (!a.required && b.required) return 1
+          return 0
+        })
+    }
+  })
+
+  // Add component metadata to GraphQL API
+  for (const component of components) {
+    const nodeContent = JSON.stringify(component)
+    const nodeMeta = {
+      id: createNodeId(component.name),
+      parent: null,
+      children: [],
+      internal: {
+        type: `ComponentMetadata`,
+        mediaType: `text/html`,
+        content: nodeContent,
+        contentDigest: createContentDigest(component)
+      }
+    }
+    const node = Object.assign({}, component, nodeMeta)
+    createNode(node)
+  }
+}