@primer/react-brand 0.69.1-rc.0a4e5ff5 → 0.70.0-rc.11ae3568

package/README.md

@@ -0,0 +1,19 @@
+# @primer/react-brand
+
+GitHub's design system for building React-based marketing websites and brand-led digital experiences.
+
+> **Are you an AI agent or tool?** Version-matched documentation is bundled with this package. Start at `node_modules/@primer/react-brand/llms.txt`. Prefer bundled documentation over the website linked below, which tracks the latest release only, and could describe unreleased features, or omit ones that were retired in the version you have installed.
+
+## Installation
+
+```bash
+npm install @primer/react-brand
+```
+
+## Documentation
+
+We publish our docs in two ways:
+
+1. Bundled and matched to your installed version: This is recommended for agents and humans using older versions of the library. Start with [`llms.txt`](./llms.txt) at the package root, which indexes every component and links into [`docs/`](./docs/).
+
+2. Latest docs at [primer.style/brand](https://primer.style/brand), which is the latest version of our docs, and may show unreleased features.

package/docs/components/ActionMenu/index.md

@@ -0,0 +1,156 @@
+---
+title: Action menu
+description: Use the action menu component to display a list of actions or selections that expand through a trigger button.
+keywords: ['dropdown', 'select', 'menu', 'options', 'popup']
+ready: true
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=4912%3A32799'
+source: https://github.com/primer/brand/blob/main/packages/react/src/ActionMenu/ActionMenu.tsx
+storybook: '/brand/storybook/?path=/story/components-actionmenu--default'
+---
+
+```js
+import {ActionMenu} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<ActionMenu onSelect={newValue => alert(`Pressed ${newValue}`)}>
+  <ActionMenu.Button>Open menu</ActionMenu.Button>
+  <ActionMenu.Overlay aria-label="GitHub features">
+    <ActionMenu.Item value="Copilot" selected>
+      Copilot
+    </ActionMenu.Item>
+    <ActionMenu.Item value="Codespaces">Codespaces</ActionMenu.Item>
+    <ActionMenu.Item value="CodeQL">CodeQL</ActionMenu.Item>
+  </ActionMenu.Overlay>
+</ActionMenu>
+```
+
+### Single selection
+
+In single selection mode it is important to apply an `aria-label` to the
+`ActionMenu.Button` child. This provides the user with important and durable
+context on the selection they need to make.
+
+```jsx filename="noinline"
+const App = () => {
+  const [selection, setSelection] = React.useState('Copilot')
+
+  return (
+    <ActionMenu onSelect={newValue => setSelection(newValue)} selectionVariant="single">
+      <ActionMenu.Button>Select a GitHub feature</ActionMenu.Button>
+      <ActionMenu.Overlay aria-label="GitHub features">
+        <ActionMenu.Item value="Copilot" selected={'Copilot' === selection}>
+          Copilot
+        </ActionMenu.Item>
+        <ActionMenu.Item value="Codespaces" selected={'Codespaces' === selection}>
+          Codespaces
+        </ActionMenu.Item>
+        <ActionMenu.Item value="CodeQL" selected={'CodeQL' === selection}>
+          CodeQL
+        </ActionMenu.Item>
+      </ActionMenu.Overlay>
+    </ActionMenu>
+  )
+}
+
+render(<App />)
+```
+
+### Split-button layout
+
+In this `mode`, the `ActionMenu` can be shown as a split button with an action (left) and dropdown button (right) with an additional list of actions.
+
+> In split-button mode, each action must be rendered as a link element using the as="a" prop, including the main button
+> and all menu items.
+
+```jsx
+<ActionMenu mode="split-button">
+  <ActionMenu.Button variant="subtle" as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
+    Action 1
+  </ActionMenu.Button>
+  <ActionMenu.Overlay aria-label="Alternative actions">
+    <ActionMenu.Item as="a" href="#location-for-link" leadingVisual={<StarIcon />}>
+      Action 1
+    </ActionMenu.Item>
+    <ActionMenu.Item as="a" href="#location-for-link-2" leadingVisual={<StarIcon />}>
+      Action 2
+    </ActionMenu.Item>
+    <ActionMenu.Item as="a" href="#location-for-link-3" leadingVisual={<StarIcon />}>
+      Action 3
+    </ActionMenu.Item>
+    <ActionMenu.Item as="a" href="#location-for-link-4" leadingVisual={<StarIcon />}>
+      Action 4
+    </ActionMenu.Item>
+  </ActionMenu.Overlay>
+</ActionMenu>
+```
+
+### Sizes
+
+`ActionMenu` is currently available in `small` and `medium` sizes, with the latter being the default.
+
+```jsx
+<Stack direction="horizontal" alignItems="center" gap={112}>
+  <ActionMenu size="small">
+    <ActionMenu.Button>Small</ActionMenu.Button>
+    <ActionMenu.Overlay aria-label="Menu items">
+      <ActionMenu.Item value="Item 1">Item 1</ActionMenu.Item>
+      <ActionMenu.Item value="Item 2">Item 2</ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+  <ActionMenu size="medium">
+    <ActionMenu.Button>Medium</ActionMenu.Button>
+    <ActionMenu.Overlay aria-label="Menu items">
+      <ActionMenu.Item value="Item 1">Item 1</ActionMenu.Item>
+      <ActionMenu.Item value="Item 2">Item 2</ActionMenu.Item>
+    </ActionMenu.Overlay>
+  </ActionMenu>
+</Stack>
+```
+
+## Component props
+
+### ActionMenu `Required`
+
+| name               | type                                                                                                                                                                 | default     | required | description                                                           |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------- | --------------------------------------------------------------------- |
+| `disabled`         | `boolean`                                                                                                                                                            | `false`     | `false`  | Controls the ActionMenu active/inactive state                         |
+| `open`             | `boolean`                                                                                                                                                            | `false`     | `false`  | Determines whether the ActionMenu is open by default                  |
+| `onSelect`         | `(newValue: string) => void`                                                                                                                                         |             | `false`  | Callback that is called when an item is selected                      |
+| `selectionVariant` | `'single' \| 'none'`                                                                                                                                                 | `'none'`    | `false`  | The selection variant of the ActionMenu                               |
+| `menuAlignment`    | `'start' \| 'end'`                                                                                                                                                   | `start`     | `false`  | Horizontal alignment of the menu relative to the bottom of the button |
+| `size`             | `'small' \| 'medium'`                                                                                                                                                | `medium`    | `false`  | Size configuration of the ActionMenu                                  |
+| `menuSide`         | `'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'` | `undefined` | `false`  | Location of the menu overlay                                          |
+| `mode`             | `ActionMenuButtonModes`                                                                                                                                              | `default`   | `false`  | Alternative behavior for the button and menu items                    |
+
+### ActionMenu.Button `Required`
+
+| name        | type           | default | required | description                        |
+| ----------- | -------------- | ------- | -------- | ---------------------------------- |
+| `className` | `string`       |         |          | Sets a custom class on the element |
+| `children`  | `ReactElement` |         |          |                                    |
+| `id`        | `string`       |         |          | Sets a custom `id`                 |
+
+### ActionMenu.Overlay `Required`
+
+| name         | type           | default | required | description                                                      |
+| ------------ | -------------- | ------- | -------- | ---------------------------------------------------------------- |
+| `aria-label` | `string`       |         | `true`   | Required for describing the relationship between button and menu |
+| `className`  | `string`       |         |          | Sets a custom class on the element                               |
+| `children`   | `ReactElement` |         |          |                                                                  |
+| `id`         | `string`       |         |          | Sets a custom `id`                                               |
+
+### ActionMenu.Item `Required`
+
+| name        | type           | default | required | description                                                   |
+| ----------- | -------------- | ------- | -------- | ------------------------------------------------------------- |
+| `className` | `string`       |         |          | Sets a custom class on the element                            |
+| `children`  | `ReactElement` |         |          |                                                               |
+| `disabled`  | `boolean`      | `false` | `false`  | Allows control over an individual items active/inactive state |
+| `id`        | `string`       |         |          | Sets a custom `id`                                            |
+| `selected`  | `boolean`      |         |          | Indicates the item is selected in `single` selection mode     |
+| `value`     | `string`       |         |          | The underlying value passed to the selection handler          |

package/docs/components/AnchorNav/index.md

@@ -0,0 +1,220 @@
+---
+title: Anchor nav
+description: Use the anchor nav component for prompt navigation to different sections of a page.
+keywords: ['navigation', 'menu', 'sticky', 'links', 'sections']
+ready: true
+figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=3359%3A30494&t=7vT79cAF1kbiMd2j-4
+source: https://github.com/primer/brand/blob/main/packages/react/src/AnchorNav/AnchorNav.tsx
+storybook: '/brand/storybook/?path=/story/components-anchornav--playground'
+---
+
+```js
+import {AnchorNav} from '@primer/react-brand'
+```
+
+## Examples
+
+> `AnchorNav` is designed to fix to the top of the viewport, and requires markup outside of the scope of the component to behave correctly.
+>
+> Please refer to our Storybook examples to see the component in a full-screen context as originally intended.
+
+### Basic
+
+```jsx
+<div style={{position: 'relative', overflowX: 'scroll', width: '100%'}}>
+  <AnchorNav>
+    <AnchorNav.Link href="#basic-section1">Section one</AnchorNav.Link>
+    <AnchorNav.Link href="#basic-section2">Section two</AnchorNav.Link>
+    <AnchorNav.Link href="#basic-section3">Section three</AnchorNav.Link>
+    <AnchorNav.Link href="#basic-section4">Section four</AnchorNav.Link>
+    <AnchorNav.Link href="#basic-section5">Section five</AnchorNav.Link>
+    <AnchorNav.Action href="#">Sign up</AnchorNav.Action>
+  </AnchorNav>
+  <section
+    id="basic-section1"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-lemon-0)',
+    }}
+  >
+    Section 1
+  </section>
+  <section
+    id="basic-section2"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-yellow-0)',
+    }}
+  >
+    Section 2
+  </section>
+  <section
+    id="basic-section3"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-lime-0)',
+    }}
+  >
+    Section 3
+  </section>
+  <section
+    id="basic-section4"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-green-0)',
+    }}
+  >
+    Section 4
+  </section>
+  <section
+    id="basic-section5"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-teal-0)',
+    }}
+  >
+    Section 5
+  </section>
+</div>
+```
+
+### Secondary action
+
+`AnchorNav` can also feature secondary actions. When two actions are present, the first will be presented as the `primary` variant.
+
+```jsx
+<div style={{position: 'relative', overflowX: 'scroll', width: '100%'}}>
+  <AnchorNav>
+    <AnchorNav.Link href="#fewer-links-section1">Section one</AnchorNav.Link>
+    <AnchorNav.Link href="#fewer-links-section2">Section two</AnchorNav.Link>
+    <AnchorNav.Link href="#fewer-links-section3">Section three</AnchorNav.Link>
+    <AnchorNav.Action href="#">Sign up</AnchorNav.Action>
+    <AnchorNav.SecondaryAction href="#">Learn more</AnchorNav.SecondaryAction>
+  </AnchorNav>
+  <section
+    id="fewer-links-section1"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-lemon-0)',
+    }}
+  >
+    Section 1
+  </section>
+  <section
+    id="fewer-links-section2"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-yellow-0)',
+    }}
+  >
+    Section 2
+  </section>
+  <section
+    id="fewer-links-section3"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-lime-0)',
+    }}
+  >
+    Section 3
+  </section>
+</div>
+```
+
+### Fewer links
+
+`AnchorNav` implementations with fewer than `5` links, will automatically align links to the `start`.
+
+```jsx
+<div style={{position: 'relative', overflowX: 'scroll', width: '100%'}}>
+  <AnchorNav>
+    <AnchorNav.Link href="#fewer-links-section1">Section one</AnchorNav.Link>
+    <AnchorNav.Link href="#fewer-links-section2">Section two</AnchorNav.Link>
+    <AnchorNav.Link href="#fewer-links-section3">Section three</AnchorNav.Link>
+    <AnchorNav.Action href="#">Sign up</AnchorNav.Action>
+  </AnchorNav>
+  <section
+    id="fewer-links-section1"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-lemon-0)',
+    }}
+  >
+    Section 1
+  </section>
+  <section
+    id="fewer-links-section2"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-yellow-0)',
+    }}
+  >
+    Section 2
+  </section>
+  <section
+    id="fewer-links-section3"
+    style={{
+      padding: '100px 2rem',
+      backgroundColor: 'var(--base-color-scale-lime-0)',
+    }}
+  >
+    Section 3
+  </section>
+</div>
+```
+
+## Component props
+
+### AnchorNav `Required`
+
+| Name                   | Type                                                    | Default | Description                                                             |
+| :--------------------- | :------------------------------------------------------ | :-----: | :---------------------------------------------------------------------- |
+| `children`             | `'AnchorNav.Link' \| 'AnchorNav.Action' \| 'ReactNode'` |         | Valid child nodes                                                       |
+| `className`            | `string`                                                |         | Sets a custom class                                                     |
+| `enableDefaultBgColor` | `boolean`                                               | `false` | Enable the idle state background color, which is transparent by default |
+| `hideUntilSticky`      | `boolean`                                               | `false` | When true, the anchor nav will hide until it is sticky.                 |
+| `id`                   | `string`                                                |         | Sets a custom id                                                        |
+| `ref`                  | `React.RefObject`                                       |         | Forward a Ref to the underlying DOM node                                |
+
+### AnchorNav.Link `Required`
+
+`AnchorNav.Link` are anchor links that feature in the menubar
+
+| Name        | Type              | Default | Description                                         |
+| :---------- | :---------------- | :-----: | :-------------------------------------------------- |
+| `children`  | `string`          |         | Required. Label text                                |
+| `className` | `string`          |         | Applies a custom class                              |
+| `href`      | `string`          |         | Required. Local identifier for the anchored element |
+| `id`        | `string`          |         | Sets a custom id                                    |
+| `isActive`  | `boolean`         | `false` | Manually indicate that the link is active           |
+| `ref`       | `React.RefObject` |         | Forward a Ref to the underlying DOM node            |
+
+Additional props can be passed to the `<a>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes) accepted by the `<anchor>` element.
+
+### AnchorNav.Action
+
+`AnchorNav.Action` is the primary call to action for the AnchorNav
+
+| Name        | Type              | Default | Description                                         |
+| :---------- | :---------------- | :-----: | :-------------------------------------------------- |
+| `children`  | `string`          |         | Required. Label text                                |
+| `className` | `string`          |         | Applies a custom class                              |
+| `href`      | `string`          |         | Required. Local identifier for the anchored element |
+| `id`        | `string`          |         | Sets a custom id                                    |
+| `ref`       | `React.RefObject` |         | Forward a Ref to the underlying DOM node            |
+
+Additional props can be passed to the `<a>` element. Refer to [Button](../Button/index.md) for more details or [MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes) accepted by the `<anchor>` element.
+
+### AnchorNav.SecondaryAction
+
+`AnchorNav.SecondaryAction` is an alternative call to action available for the AnchorNav
+
+| Name        | Type              | Default | Description                                         |
+| :---------- | :---------------- | :-----: | :-------------------------------------------------- |
+| `children`  | `string`          |         | Required. Label text                                |
+| `className` | `string`          |         | Applies a custom class                              |
+| `href`      | `string`          |         | Required. Local identifier for the anchored element |
+| `id`        | `string`          |         | Sets a custom id                                    |
+| `ref`       | `React.RefObject` |         | Forward a Ref to the underlying DOM node            |
+
+Additional props can be passed to the `<a>` element. Refer to [Button](../Button/index.md) for more details or [MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes) accepted by the `<anchor>` element.

package/docs/components/Avatar/index.md

@@ -0,0 +1,30 @@
+---
+title: Avatar
+description: Use the avatar component to display a thumbnail representation of a person.
+keywords: ['image', 'thumbnail', 'profile', 'user', 'organization']
+---
+
+![An image showing two different avatars, a circular and a square one.](https://user-images.githubusercontent.com/175638/234820833-c803cb11-2bc3-4597-88f3-2cf630a46702.png)
+
+## Usage
+
+Use avatars to display a thumbnail that represents individuals in various contexts, such as testimonials, speaker sessions, blog post authors, and beyond.
+
+## Options
+
+### Size
+
+Avatar offers various sizes to fit different layout and visual scale needs. Sizes range from 32 to 80 pixels. Ensure the avatar is proportionate to its accompanying text.
+
+![An image showing the size scale of the avatar component: 32, 40, 48, 64, and 80 pixels](https://user-images.githubusercontent.com/175638/234826575-1d1d5019-f714-41b1-b8bc-c0d312a46cfe.png)
+
+### Shape
+
+Avatars appear as two different shapes: circle and square. The choice depends on the desired visual impression and the overall design aesthetic of your project.
+
+![An image showing the two different shapes of the avatar component: circle and square](https://user-images.githubusercontent.com/175638/234827120-da548115-450b-4ec8-a6e6-5dcbe98e77c5.png)
+
+## Related components
+
+- [Image](../Image/index.md)
+- [Testimonial](../Testimonial/index.md)

package/docs/components/Avatar/react.md

@@ -0,0 +1,71 @@
+---
+title: Avatar
+description: Use the avatar component to display a thumbnail representation of a person.
+keywords: ['image', 'thumbnail', 'profile', 'user', 'organization']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Avatar/Avatar.tsx
+storybook: '/brand/storybook/?path=/story/components-avatar--playground'
+---
+
+```js
+import {Avatar, Stack} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<Avatar src="/images/avatar-mona.png" alt="Mona profile" />
+```
+
+### Sizes
+
+The size of the avatar can be controlled by the `size` prop.
+
+```jsx
+<Stack direction="horizontal" alignItems="center" justifyContent="center" gap="spacious" style={{height: 200}}>
+  <Avatar size={32} src="/images/avatar-mona.png" alt="Mona avatar at 32px" />
+  <Avatar size={40} src="/images/avatar-mona.png" alt="Mona avatar at 40px" />
+  <Avatar size={48} src="/images/avatar-mona.png" alt="Mona avatar at 48px" />
+  <Avatar size={64} src="/images/avatar-mona.png" alt="Mona avatar at 64px" />
+  <Avatar size={80} src="/images/avatar-mona.png" alt="Mona avatar at 80px" />
+</Stack>
+```
+
+#### Responsive Sizes
+
+Passing an Object of a particular shape will allow granular control of `size` at various supported breakpoints.
+
+Supported breakpoints are `narrow`, `regular` and `wide`.
+
+The Object value does not require all properties be passed, but rather operates on the basis of `min-width`.
+
+E.g. Providing only `narrow` will apply that value to all larger breakpoints, but not the other way.
+
+```jsx
+<Avatar size={{narrow: 32, regular: 40, wide: 80}} src="/images/avatar-mona.png" alt="Mona avatar at 32px" />
+```
+
+### Shapes
+
+The shape of the avatar can be controlled by the `shape` prop.
+
+```jsx
+<Stack direction="horizontal" alignItems="center" justifyContent="center" gap="spacious" style={{height: 200}}>
+  <Avatar size={64} shape="circle" src="/images/avatar-mona.png" alt="A circular avatar picture" />
+  <Avatar size={64} shape="square" src="/images/avatar-mona.png" alt="A square avatar picture" />
+</Stack>
+```
+
+## Component props
+
+### Avatar `Required`
+
+| name        | type           | default  | required | description                       |
+| ----------- | -------------- | -------- | -------- | --------------------------------- |
+| `alt`       | `string`       |          | `true`   | The alt text of the image         |
+| `className` | `string`       |          | `false`  | Avatar custom class               |
+| `size`      | `AvatarSizes`  | `40`     | `false`  | The size (in pixels) of the image |
+| `shape`     | `AvatarShapes` | `circle` | `false`  | The shape of the image            |
+| `src`       | `string`       |          | `true`   | A url to the person's image       |