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

package/docs/components/SubdomainNavBar/index.md

@@ -0,0 +1,136 @@
+---
+title: Subdomain nav bar
+description: Use the subdomain nav bar component for top level navigation for subdomain sites.
+keywords: ['navigation', 'top level']
+ready: true
+figma: https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1024%3A32796
+source: https://github.com/primer/brand/blob/main/packages/react/src/SubdomainNavBar/SubdomainNavBar.tsx
+storybook: '/brand/storybook/?path=/story/components-subdomainnavbar--playground'
+---
+
+```js
+import {SubdomainNavBar} from '@primer/react-brand'
+```
+
+## Examples
+
+> `SubdomainNavBar` is designed to fix to the top of the viewport.
+>
+> Please refer to our Storybook examples to see the component in a full-screen browser as originally intended.
+
+### Basic
+
+```jsx
+<SubdomainNavBar title="Subdomain" fixed={false}>
+  <SubdomainNavBar.Link href="#">Collections</SubdomainNavBar.Link>
+  <SubdomainNavBar.Link href="#">Topics</SubdomainNavBar.Link>
+  <SubdomainNavBar.Link href="#">Social</SubdomainNavBar.Link>
+  <SubdomainNavBar.PrimaryAction href="#">Primary CTA</SubdomainNavBar.PrimaryAction>
+  <SubdomainNavBar.SecondaryAction href="#">Secondary CTA</SubdomainNavBar.SecondaryAction>
+</SubdomainNavBar>
+```
+
+### Search
+
+`SubdomainNavBar` offers an optional search form control. The form can operate in both `onSubmit` and `onChange` modes, with the latter facilitating inline results to appear.
+
+```jsx filename="noinline"
+const App = () => {
+  const inputRef = React.useRef(null)
+  const [searchResults, setSearchResults] = React.useState([])
+  const [searchTerm, setSearchTerm] = React.useState('')
+
+  const mockSearchData = [
+    {
+      title: 'How to transform your business in a digital world',
+      description:
+        'GitHub Enterprise empowers developers with tools they already know and love, accelerates high-quality software development and secure delivery, and enhances the speed and power of innovation.\n',
+      url: 'https://resources.github.com/devops/github-enterprise-ebook',
+      date: '2022-08-29T00:00+02:00',
+    },
+    {
+      title: 'The fundamentals of continuous deployment in DevOps',
+      description:
+        'What is continuous deployment?\nContinuous deployment (CD) is an automated software release practice where code changes are deployed to different stages as they pass predefined tests. The goal of CD is to facilitate faster releases by using automation to help remove the need for human intervention as much as possible during the deployment process.',
+      url: 'https://resources.github.com/devops/fundamentals/ci-cd/deployment',
+      date: '2022-05-23T12:00+00:00',
+    },
+  ]
+
+  const handleChange = () => {
+    if (!inputRef.current) return
+    if (inputRef.current.value.length === 0) {
+      setSearchResults(undefined)
+      return
+    }
+    if (inputRef.current.value.length > 2) {
+      setTimeout(() => setSearchResults(mockSearchData), 1000)
+      setSearchTerm(inputRef.current.value)
+      return
+    }
+  }
+
+  const handleSubmit = e => {
+    e.preventDefault()
+    if (!inputRef.current) return
+    if (!inputRef.current.value) {
+      alert(`Enter a value and try again.`)
+      return
+    }
+
+    alert(`Name: ${inputRef.current.value}`)
+  }
+
+  return (
+    <SubdomainNavBar title="Subdomain" fixed={false}>
+      <SubdomainNavBar.Link href="#collections">Collections</SubdomainNavBar.Link>
+      <SubdomainNavBar.Link href="#topics">Topics</SubdomainNavBar.Link>
+      <SubdomainNavBar.Search
+        ref={inputRef}
+        searchTerm={searchTerm}
+        onSubmit={handleSubmit}
+        onChange={handleChange}
+        searchResults={searchResults}
+      />
+    </SubdomainNavBar>
+  )
+}
+
+render(App)
+```
+
+## Accessibility
+
+When the menu is open on narrow viewports, ensure that the rest of the document is hidden from screen readers. This can be achieved by adding `aria-hidden="true"` or `inert` to the main content area when the menu is open.
+
+Use the `onNarrowMenuToggle` prop to detect when the mobile menu is opened or closed.
+
+## Component props
+
+### SubdomainNavBar `Required`
+
+| Name                 | Type                                                                                                                                                 |        Default       | Description                                                                                                                            |
+| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------: | :------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`           | `'SubdomainNavBar.Link' \| 'SubdomainNavBar.Search' \| 'SubdomainNavBar.PrimaryAction' \| 'SubdomainNavBar.SecondaryAction' \| 'React.ReactElement'` |                      | Valid child nodes                                                                                                                      |
+| `className`          | `string`                                                                                                                                             |                      | Sets a custom class                                                                                                                    |
+| `id`                 | `string`                                                                                                                                             |                      | Sets a custom id                                                                                                                       |
+| `logoHref`           | `string`                                                                                                                                             | `https://github.com` | Optionally change the URL of the logo                                                                                                  |
+| `title`              | `string`                                                                                                                                             |                      | The title or name of the subdomain. Appears adjacent to the logo and is required for communicating content to assisitive technologies. |
+| `titleHref`          | `string`                                                                                                                                             |          `/`         | The URL for the site. Typically used to link the title prop value to the site root.                                                    |
+| `ref`                | `React.RefObject`                                                                                                                                    |                      | Forward a Ref to the underlying DOM node                                                                                               |
+| `onNarrowMenuToggle` | `(isOpen: boolean) => void`                                                                                                                          |                      | When the mobile menu is opened or closed, this callback is called with the new open state.                                             |
+
+### SubdomainNavBar.Link `Required`
+
+`SubdomainNavBar.Link` are anchor links.
+
+| Name         | Type              | Default | Description                                               |
+| :----------- | :---------------- | :-----: | :-------------------------------------------------------- |
+| `children`   | `string`          |         | Label text                                                |
+| `className`  | `string`          |         | Applies a custom class                                    |
+| `href`       | `string`          |         | Destination path for the anchor element                   |
+| `id`         | `string`          |         | Sets a custom id                                          |
+| `ref`        | `React.RefObject` |         | Forward a Ref to the underlying DOM node                  |
+| `isExternal` | `boolean`         | `false` | When true, renders a external link icon after to the link |
+
+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.

package/docs/components/Tabs/index.md

@@ -0,0 +1,243 @@
+---
+title: Tabs
+description: Use Tabs to display a list of tabs with associated content panels.
+keywords: ['tabs', 'tab panels', 'navigation', 'tabbed interface']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Tabs/Tabs.tsx
+storybook: '/brand/storybook/?path=/story/components-tabs--playground'
+---
+
+```js
+import {Tabs} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<Tabs aria-label="Example tabs">
+  <Tabs.Item>Tab one</Tabs.Item>
+  <Tabs.Item>Tab two</Tabs.Item>
+  <Tabs.Item>Tab three</Tabs.Item>
+  <Tabs.Item>Tab four</Tabs.Item>
+  <Tabs.Item>Tab five</Tabs.Item>
+
+  <Tabs.Panel>
+    <Text>Panel one</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel two</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel three</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel four</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel five</Text>
+  </Tabs.Panel>
+</Tabs>
+```
+
+### Accent variant
+
+```jsx
+<Tabs variant="accent" aria-label="Tabs with accent variant">
+  <Tabs.Item>Tab one</Tabs.Item>
+  <Tabs.Item>Tab two</Tabs.Item>
+  <Tabs.Item>Tab three</Tabs.Item>
+
+  <Tabs.Panel>
+    <Text>Panel one</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel two</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel three</Text>
+  </Tabs.Panel>
+</Tabs>
+```
+
+### Underline variant
+
+```jsx
+<Tabs variant="underline" aria-label="Tabs with underline variant">
+  <Tabs.Item>Tab one</Tabs.Item>
+  <Tabs.Item>Tab two</Tabs.Item>
+  <Tabs.Item>Tab three</Tabs.Item>
+
+  <Tabs.Panel>
+    <Text>Panel one</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel two</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel three</Text>
+  </Tabs.Panel>
+</Tabs>
+```
+
+### Custom panels
+
+```jsx
+function CustomPanels() {
+  const [activeTab, setActiveTab] = React.useState('0')
+
+  const handleTabChange = React.useCallback(id => {
+    setActiveTab(id)
+  }, [])
+
+  return (
+    <Stack alignItems="center">
+      <Tabs onChange={handleTabChange} aria-label="Lifecycle tabs">
+        <Tabs.Item id="tab-1" aria-controls="panel-1">
+          Code
+        </Tabs.Item>
+        <Tabs.Item id="tab-2" aria-controls="panel-2">
+          Plan
+        </Tabs.Item>
+        <Tabs.Item id="tab-3" aria-controls="panel-3">
+          Collaborate
+        </Tabs.Item>
+        <Tabs.Item id="tab-4" aria-controls="panel-4">
+          Automate
+        </Tabs.Item>
+      </Tabs>
+      <Box padding="condensed">
+        <Box id="panel-1" aria-labelledby="tab-1" role="tabpanel" tabIndex={0} hidden={activeTab !== '0'}>
+          <Stack direction="vertical" alignItems="center">
+            <Text>
+              <Icon icon={CodeIcon} size={24} hasBackground color="green" />
+            </Text>
+            <Heading size="5">Code</Heading>
+            <Text variant="muted">
+              Code quickly and more securely with GitHub Copilot embedded throughout your workflows.
+            </Text>
+          </Stack>
+        </Box>
+        <Box id="panel-2" aria-labelledby="tab-2" role="tabpanel" tabIndex={0} hidden={activeTab !== '1'}>
+          <Stack direction="vertical" alignItems="center">
+            <Text>
+              <Icon icon={PencilIcon} size={24} hasBackground color="blue" />
+            </Text>
+            <Heading size="5">Plan</Heading>
+            <Text variant="muted">
+              Track and coordinate your work with GitHub Issues, GitHub Projects, and insights.
+            </Text>
+          </Stack>
+        </Box>
+        <Box id="panel-3" aria-labelledby="tab-3" role="tabpanel" tabIndex={0} hidden={activeTab !== '2'}>
+          <Stack direction="vertical" alignItems="center">
+            <Text>
+              <Icon icon={PeopleIcon} size={24} hasBackground color="yellow" />
+            </Text>
+            <Heading size="5">Collaborate</Heading>
+            <Text variant="muted">
+              Collaborate in real time with your team and GitHub Copilot across GitHub Issues, GitHub Discussions, and
+              pull requests.
+            </Text>
+          </Stack>
+        </Box>
+        <Box id="panel-4" aria-labelledby="tab-4" role="tabpanel" tabIndex={0} hidden={activeTab !== '3'}>
+          <Stack direction="vertical" alignItems="center">
+            <Text>
+              <Icon icon={HubotIcon} size={24} hasBackground color="purple" />
+            </Text>
+            <Heading size="5">Automate</Heading>
+            <Text variant="muted">
+              Streamline your workflows with automated CI/CD, testing, planning, project management, issue labeling,
+              approvals, onboarding, and more.
+            </Text>
+          </Stack>
+        </Box>
+      </Box>
+    </Stack>
+  )
+}
+```
+
+### Start alignment
+
+```jsx
+<Tabs align="start" aria-label="Start aligned tabs">
+  <Tabs.Item>Tab one</Tabs.Item>
+  <Tabs.Item>Tab two</Tabs.Item>
+  <Tabs.Item>Tab three</Tabs.Item>
+
+  <Tabs.Panel>
+    <Text>Panel one</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel two</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel three</Text>
+  </Tabs.Panel>
+</Tabs>
+```
+
+### Custom default active tab
+
+```jsx
+<Tabs defaultActiveTab="2" aria-label="Tabs with custom default">
+  <Tabs.Item>Tab one</Tabs.Item>
+  <Tabs.Item>Tab two</Tabs.Item>
+  <Tabs.Item>Tab three</Tabs.Item>
+
+  <Tabs.Panel>
+    <Text>Panel one</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel two</Text>
+  </Tabs.Panel>
+  <Tabs.Panel>
+    <Text>Panel three (active by default)</Text>
+  </Tabs.Panel>
+</Tabs>
+```
+
+## Component props
+
+### Tabs `Required`
+
+| name                                      | type                                       | default          | required | description                                                                                                             |
+| ----------------------------------------- | ------------------------------------------ | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `children`                                | `ReactNode`                                | `undefined`      | `true`   | Named children to be rendered as tab items and panels. Must include `Tabs.Item`, and optionally `Tabs.Panel` components |
+| `aria-label`                              | `string`                                   | `undefined`      | `true`   | Accessible label for the tab list element, used by screen readers to describe the tab group                             |
+| `variant`                                 | `'default'` \| `'accent'` \| `'underline'` | `'default'`      | `false`  | Visual style variant of the tabs. Affects the appearance and styling theme                                              |
+| `align`                                   | `'start'` \| `'center'`                    | `'center'`       | `false`  | Horizontal alignment of the tab navigation                                                                              |
+| `defaultActiveTab`                        | `string`                                   | `'0'`            | `false`  | Sets the default active tab. "0" (first tab) by default                                                                 |
+| `onChange`                                | `(activeTab: string) => void`              | `undefined`      | `false`  | Callback function triggered when the active tab changes. Receives the new active tab identifier                         |
+| `className`                               | `string`                                   | `undefined`      | `false`  | Additional CSS class names to apply to the tabs container for custom styling                                            |
+| `internalAccessibleLabels`                | `object`                                   | `undefined`      | `false`  | Customizable `aria-label` values for screen readers to improve accessibility. Defaults to English.                      |
+| `internalAccessibleLabels``.controlsNext` | `string`                                   | `'Next tab'`     | `false`  | Label for the "next tab" control button, used by screen readers                                                         |
+| `internalAccessibleLabels``.controlsPrev` | `string`                                   | `'Previous tab'` | `false`  | Label for the "previous tab" control button, used by screen readers                                                     |
+
+Forwards all standard HTML attributes for `<div>` elements.
+
+### Tabs.Item `Required`
+
+Individual tab item that users can click to switch between panels.
+
+| name        | type        | default     | required | description                                   |
+| ----------- | ----------- | ----------- | -------- | --------------------------------------------- |
+| `children`  | `ReactNode` | `undefined` | `true`   | Content to be displayed inside the tab button |
+| `className` | `string`    | `undefined` | `false`  | Sets a custom class on the tab button element |
+
+Forwards all standard HTML attributes for `<button>` elements.
+
+### Tabs.Panel
+
+Content panel associated with each tab. Hidden when not active.
+
+| name        | type                                                         | default     | required | description                                      |
+| ----------- | ------------------------------------------------------------ | ----------- | -------- | ------------------------------------------------ |
+| `children`  | `ReactNode`                                                  | `undefined` | `true`   | Content to be displayed inside the panel         |
+| `animation` | `'slide-in-up'` \| `'scale-in-up'` \| `'fade-in'` \| `false` | `false`     | `false`  | Optional animation when the panel becomes active |
+| `className` | `string`                                                     | `undefined` | `false`  | Sets a custom class on the panel element         |
+
+Forwards all standard HTML attributes for `<div>` elements.

package/docs/components/Testimonial/index.md

@@ -0,0 +1,138 @@
+---
+title: Testimonial
+description: Use testimonial to display a quote from a customer or user.
+keywords: ['quote', 'review', 'feedback', 'customer', 'user', 'social proof']
+---
+
+## Anatomy
+
+![An image displaying a testimonial anatomy.](https://github.com/primer/brand/assets/912236/5072db4b-446f-4091-be35-48cc020d51ba)
+
+- Quote: The quote from the customer.
+- Name: The name of the customer.
+- Position: The position or role of the customer.
+- Avatar or Logo: Optional avatar of the customer or the company logo.
+
+## Usage
+
+Use the testimonial component to showcase a quote or a review from a customer. Use the testimonials to build credibility, trust, and provide social proof by displaying customer sentiment about the product.
+
+Testimonials should be short and concise. Quotes should be not be longer than 3-4 lines. Avoid using long quotes that can be hard to understand or that don't provide enough context.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/ca8b16f9-ada6-49b7-a627-db039f5bd3d9)
+
+_Use short and concise quotes._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/bb0ae79c-244f-4cdb-83e2-655bd99ee67e)
+
+_Don't use long quotes that can be hard to read and understand._
+
+Use highlights to alternate the color of the quote mark and emphasize specific parts of the quote.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/0f81c397-c992-41be-8242-4d8500744213)
+
+_Use emphasis to highlight the beginning of the quote and provide extra visual weight._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/107d6fc4-7010-4a7c-859b-6a15b2ad6cc8)
+
+_Don't use multiple highlights in the same quote to avoid visual noise._
+
+Avatars and logos are optional and can be used to provide more credibility about the customer or the company. When using an avatar, use an image of the customer to make the testimonial more personal. If an image is not available, use a logo or a similar visual asset that represents the customer company or the organization.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/ed537938-cc59-4d02-9285-878ea03c6f5f)
+
+_Use a real-life image of the customer or the logo of the company._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/6320c943-64e7-4ed3-b337-3734372dcf16)
+
+_Don't use illustrations or generic images. Use real life images to provide trust._
+
+Testimonials can be used individually or in a group. When using a group of testimonials, use the same size and alignment for all of them. When including an avatar or a logo, use them in all testimonials of the group and keep the same style and size— don't alternate between logos and avatars. We recommend using a maximum of 4 testimonials per group to avoid visual noise and to keep the quotes relevant.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/fc8eb38a-c765-4730-8c27-98d460d2c03e)
+
+_Use a maximum of 3 or 4 testimonials per group, with the same size and alignment._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/b8b84d81-e71e-4d44-87c7-d227222f2bc7)
+
+_Don't use different sizes, alignments or alternate avatars and logos for groups of testimonials._
+
+Use a single testimonial to highlight a specific feature or benefit of the product. Use multiple testimonials to showcase each feature when in a list or a [river](../River/index.md).
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/e6e233fd-46e1-4d7f-8b07-39bb9169d8d8)
+
+_Use testimonials to enhance the credibility of a specific feature or benefit._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/841d578b-e353-4dee-acbb-5c8bc3e7c356)
+
+_Don't use multiple testimonials to showcase the same feature to avoid visual noise._
+
+## Options
+
+### Size
+
+The testimonial component uses the small size by default. Use the large size to provide more visual weight.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/3eae1c3c-9a8d-4452-8f3a-a973fa103bd3)
+
+_Use the large size when using a single, full-width testimonial._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/163324a6-0276-4aa9-94f0-e38d4aea8a3e)
+
+_Don't use small size for full-width testimonials._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/58036813-77a1-4af6-a2dc-d2ce05ac085d)
+
+_Use the small size when paired with other components that showcase features, like rivers._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/626bae6a-4bdb-42cb-8b82-2f6615f83283)
+
+_Don't use the large size in small sized areas or components like rivers, so they don't conflict with the main
+content. Even if the quote is short, use the small size instead._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/5ac744e5-045c-4acc-8dee-38ebc740a8e4)
+
+_Use the small size for single row groups of testimonials._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/ef1e9bdb-2ab8-457f-b54b-ae224c9119c1)
+
+_Don't use the large size in single row groups, even if the content is short. Stack them vertically and use 2
+columns instead._
+
+## Related components
+
+- [Pillar](../Pillar/index.md): To display related content with less visual emphasis.
+- [Card](../Card/index.md): To display navigational related content with higher visual weight.
+- [River](../River/index.md): To display navigational related content with higher visual weight.