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

package/docs/content/Token.mdx

@@ -0,0 +1,381 @@
+---
+title: Token
+status: Alpha
+source: https://github.com/primer/react/tree/main/src/Token
+---
+
+import {Props} from '../src/props'
+import {AvatarToken, IssueLabelToken, Token} from '@primer/components'
+
+A Token represents a piece of data. They are typically used to show a collection of related attributes.
+
+The default `Token` can be used for most cases, but specialized token components are provided for specific use cases (see below for more info).
+
+All types of tokens may have the same interactive qualities as links or buttons. They also have a sense of being "selected" and ready for user interaction such as being removed from a collection.
+
+## Basic Example
+
+```jsx live
+<>
+  <Text fontSize={0} display="block" color="fg.subtle">
+    Token
+  </Text>
+  <Token text="Default Token" />
+</>
+```
+
+### Interactive tokens
+
+If any token is interactive (it is a link or a button), it will become focusable, and react to being hovered or focused on.
+
+If a token is interactive _and_ has a remove button (appears when passing `onRemove`), the remove button should not get focus. To invoke the `onRemove` callback without using the cursor, press 'Backspace' when the token is focused.
+
+These rules apply to all token components mentioned in this document.
+
+#### Example: Interactive tokens with and without an `onRemove` prop
+
+```jsx live
+<Box
+  display="flex"
+  sx={{
+    alignItems: 'start',
+    flexDirection: 'column',
+    gap: 6
+  }}
+>
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      Interactive
+    </Text>
+    <Box
+      display="flex"
+      sx={{
+        alignItems: 'start',
+        gap: 2
+      }}
+    >
+      <Token as="a" href="http://google.com/" text="Link" />
+      <Token as="button" onClick={() => console.log('clicked')} text="Button" />
+      <Token as="span" tabIndex={0} onFocus={() => console.log('focused')} text="Focusable Span" />
+    </Box>
+  </div>
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      Interactive with `onRemove` passed
+    </Text>
+    <Box
+      display="flex"
+      sx={{
+        alignItems: 'start',
+        gap: 2
+      }}
+    >
+      <Token
+        as="a"
+        href="http://google.com/"
+        text="Link"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <Token
+        as="button"
+        onClick={() => console.log('clicked')}
+        text="Button"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <Token
+        as="span"
+        tabIndex={0}
+        onFocus={() => console.log('focused')}
+        text="Focusable Span"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+    </Box>
+  </div>
+</Box>
+```
+
+## Token
+
+The default `Token` component
+
+### Component Props
+
+<Props of={Token} />
+
+### Example
+
+```jsx live
+<Box
+  display="flex"
+  sx={{
+    alignItems: 'start',
+    flexDirection: 'column',
+    gap: 6
+  }}
+>
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      Resting
+    </Text>
+    <Token text="Default Token" />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      isSelected
+    </Text>
+    <Token text="Default Token" isSelected />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      With `leadingVisual` passed
+    </Text>
+    <Token text="Default Token" leadingVisual={() => <span>✨</span>} />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      With `onRemove` passed
+    </Text>
+    <Token
+      text="Default Token"
+      onRemove={() => {
+        console.log('remove me')
+      }}
+    />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      Size options
+    </Text>
+    <Box
+      display="flex"
+      sx={{
+        alignItems: 'start',
+        gap: 2
+      }}
+    >
+      <Token
+        size="small"
+        text="'small' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <Token
+        size="medium"
+        text="'medium' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <Token
+        size="large"
+        text="'large' Token (default)"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <Token
+        size="extralarge"
+        text="'extralarge' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+    </Box>
+  </div>
+</Box>
+```
+
+## IssueLabelToken
+
+Tokens that represent Issue labels should use the `IssueLabelToken` component.
+
+### Component Props
+
+<Props of={IssueLabelToken} />
+
+```jsx live
+<Box
+  display="flex"
+  sx={{
+    alignItems: 'start',
+    flexDirection: 'column',
+    gap: 6
+  }}
+>
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      Resting
+    </Text>
+    <IssueLabelToken text="good first issue" fillColor="#0366d6" />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      isSelected
+    </Text>
+    <IssueLabelToken text="good first issue" fillColor="#0366d6" isSelected />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      With `onRemove` passed
+    </Text>
+    <IssueLabelToken
+      text="good first issue"
+      fillColor="#0366d6"
+      onRemove={() => {
+        console.log('remove me')
+      }}
+    />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      Size options
+    </Text>
+    <Box
+      display="flex"
+      sx={{
+        alignItems: 'start',
+        gap: 2
+      }}
+    >
+      <IssueLabelToken
+        fillColor="#0366d6"
+        size="small"
+        text="'small' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <IssueLabelToken
+        fillColor="#0366d6"
+        size="medium"
+        text="'medium' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <IssueLabelToken
+        fillColor="#0366d6"
+        size="large"
+        text="'large' Token (default)"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <IssueLabelToken
+        fillColor="#0366d6"
+        size="extralarge"
+        text="'extralarge' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+    </Box>
+  </div>
+</Box>
+```
+
+## AvatarToken
+
+Tokens that represent GitHub users should use the `AvatarToken` component.
+
+### Component Props
+
+<Props of={AvatarToken} />
+
+```jsx live
+<Box
+  display="flex"
+  sx={{
+    alignItems: 'start',
+    flexDirection: 'column',
+    gap: 6
+  }}
+>
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      Resting
+    </Text>
+    <AvatarToken avatarSrc="https://avatars.githubusercontent.com/mperrotti" text="Default Token" />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      isSelected
+    </Text>
+    <AvatarToken avatarSrc="https://avatars.githubusercontent.com/mperrotti" text="Default Token" isSelected />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      With `onRemove` passed
+    </Text>
+    <AvatarToken
+      avatarSrc="https://avatars.githubusercontent.com/mperrotti"
+      text="Default Token"
+      onRemove={() => {
+        console.log('remove me')
+      }}
+    />
+  </div>
+
+  <div>
+    <Text fontSize={0} display="block" color="fg.subtle">
+      Size options
+    </Text>
+    <Box
+      display="flex"
+      sx={{
+        alignItems: 'start',
+        gap: 2
+      }}
+    >
+      <AvatarToken
+        avatarSrc="https://avatars.githubusercontent.com/mperrotti"
+        size="small"
+        text="'small' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <AvatarToken
+        avatarSrc="https://avatars.githubusercontent.com/mperrotti"
+        size="medium"
+        text="'medium' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <AvatarToken
+        avatarSrc="https://avatars.githubusercontent.com/mperrotti"
+        size="large"
+        text="'large' Token (default)"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+      <AvatarToken
+        avatarSrc="https://avatars.githubusercontent.com/mperrotti"
+        size="extralarge"
+        text="'extralarge' Token"
+        onRemove={() => {
+          console.log('remove me')
+        }}
+      />
+    </Box>
+  </div>
+</Box>
+```

package/docs/content/Tooltip.md

@@ -0,0 +1,33 @@
+---
+title: Tooltip
+status: Alpha
+---
+
+The Tooltip component adds a tooltip to add context to elements on the page.
+
+**_⚠️ Usage warning! ⚠️_**
+
+Tooltips as a UI pattern should be our last resort for conveying information because it is hidden by default and often with zero or little visual indicator of its existence.
+
+Before adding a tooltip, please consider: Is this information essential and necessary? Can the UI be made clearer? Can the information be shown on the page by default?
+
+**Attention:** we use aria-label for tooltip contents, because it is crucial that they are accessible to screen reader users. However, aria-label replaces the text content of an element in screen readers, so only use Tooltip on elements with no existing text content, or consider using `title` for supplemental information.
+
+## Default example
+
+```jsx live
+<Box borderWidth="1px" borderStyle="solid" borderColor="border.default" borderRadius={2} p={3}>
+  <Tooltip aria-label="Hello, Tooltip!">Text with a tooltip</Tooltip>
+</Box>
+```
+
+## Component props
+
+| Name       | Type              | Default | Description                                                                                                         |
+| :--------- | :---------------- | :-----: | :------------------------------------------------------------------------------------------------------------------ |
+| align      | String            |         | Can be either `left` or `right`.                                                                                    |
+| direction  | String            |         | Can be one of `n`, `ne`, `e`, `se`, `s`, `sw`, `w`, `nw`. Sets where the tooltip renders in relation to the target. |
+| noDelay    | Boolean           |         | When set to `true`, tooltip appears without any delay                                                               |
+| aria-label | String            |         | Text used in `aria-label` (for accessibility).                                                                      |
+| wrap       | Boolean           |         | Use `true` to allow text within tooltip to wrap.                                                                    |
+| sx         | SystemStyleObject |   {}    | Style to be applied to the component                                                                                |

package/docs/content/Truncate.md

@@ -0,0 +1,56 @@
+---
+title: Truncate
+status: Alpha
+---
+
+The Truncate component will shorten text with an ellipsis. Always add a `title` attribute to the truncated element so the full text remains accessible.
+
+## Default example
+
+Truncate will prevent text that overflows from wrapping. The default max-width is 125px.
+
+```jsx live
+<Truncate title="Some text with a branch-name-that-is-really-long">
+  Some text with a branch-name-that-is-really-long
+</Truncate>
+```
+
+## Custom max-width example
+
+You can override the maximum width of the truncated text with the `maxWidth` prop.
+
+```jsx live
+<Truncate maxWidth={250} title="Some text with a branch-name-that-is-really-long">
+  Some text with a branch-name-that-is-really-long
+</Truncate>
+```
+
+## Inline example
+
+You can use the `inline` boolean prop for inline (or inline-block) elements with a fixed maximum width (default: 125px).
+
+```jsx live
+<Truncate as="strong" inline title="branch-name-that-is-really-long">
+  Some text with a branch-name-that-is-really-long
+</Truncate>
+```
+
+## Expandable example
+
+You can use the `expandable` boolean prop to display the truncated text on hover.
+
+```jsx live
+<Truncate expandable title="Some text with a branch-name-that-is-really-long">
+  Some text with a branch-name-that-is-really-long
+</Truncate>
+```
+
+## Component props
+
+| Name       | Type              | Default | Description                                                  |
+| :--------- | :---------------- | :-----: | :----------------------------------------------------------- |
+| as         | String            |  `div`  | Sets the HTML tag for the component                          |
+| maxWidth   | Number            |   125   | Sets the max-width of the text                               |
+| inline     | Boolean           |  false  | displays text as inline block and vertical aligns to the top |
+| expandable | Boolean           |  false  | allows the truncated text to be displayed on hover           |
+| sx         | SystemStyleObject |   {}    | Style to be applied to the component                         |

package/docs/content/UnderlineNav.md

@@ -0,0 +1,46 @@
+---
+title: UnderlineNav
+status: Alpha
+---
+
+Use the UnderlineNav component to style navigation with a minimal underlined selected state, typically used for navigation placed at the top of the page.
+
+To use UnderlineNav with [react-router](https://github.com/ReactTraining/react-router) or
+[react-router-dom](https://www.npmjs.com/package/react-router-dom), pass
+`as={NavLink}` and omit the `selected` prop.
+This ensures that the NavLink gets `activeClassName='selected'`
+
+**Attention:** Make sure to properly label your `UnderlineNav` with an `aria-label` to provide context about the type of navigation contained in `UnderlineNav`.
+
+## Default example
+
+```jsx live
+<UnderlineNav aria-label="Main">
+  <UnderlineNav.Link href="#home" selected>
+    Home
+  </UnderlineNav.Link>
+  <UnderlineNav.Link href="#documentation">Documentation</UnderlineNav.Link>
+  <UnderlineNav.Link href="#support">Support</UnderlineNav.Link>
+</UnderlineNav>
+```
+
+## Component props
+
+### UnderlineNav
+
+| Name       | Type              | Default | Description                                                                            |
+| :--------- | :---------------- | :-----: | :------------------------------------------------------------------------------------- |
+| actions    | Node              |         | Place another element, such as a button, to the opposite side of the navigation items. |
+| align      | String            |         | Use `right` to have navigation items aligned right.                                    |
+| full       | Boolean           |         | Used to make navigation fill the width of the container.                               |
+| aria-label | String            |         | Used to set the `aria-label` on the top level `<nav>` element.                         |
+| sx         | SystemStyleObject |   {}    | Style to be applied to the component                                                   |
+
+### UnderlineNav.Link
+
+| Name     | Type              | Default | Description                                      |
+| :------- | :---------------- | :-----: | :----------------------------------------------- |
+| as       | String            |         | sets the HTML tag for the component              |
+| href     | String            |         | URL to be used for the Link                      |
+| selected | Boolean           |         | Used to style the link as selected or unselected |
+| sx       | SystemStyleObject |   {}    | Style to be applied to the component             |