@primer/react-brand 0.69.1-rc.0a4e5ff5 → 0.70.0-rc.138127ad

package/docs/components/Testimonial/react.md

@@ -0,0 +1,191 @@
+---
+title: Testimonial
+description: Use testimonial to display a quote from a customer or user.
+keywords: ['quote', 'review', 'feedback', 'customer', 'user', 'social proof']
+ready: true
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1852%3A27522'
+source: https://github.com/primer/brand/blob/main/packages/react/src/Testimonial/Testimonial.tsx
+storybook: '/brand/storybook/?path=/story/components-testimonial--playground'
+---
+
+```js
+import {Testimonial} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<Testimonial>
+  <Testimonial.Quote>
+    GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+    of code we&apos;re writing.
+  </Testimonial.Quote>
+  <Testimonial.Name position="Staff Security Engineer">David Ross</Testimonial.Name>
+  <Testimonial.Avatar src="/images/avatar-mona.png" alt="Circular avatar from David Ross's GitHub profile" />
+</Testimonial>
+```
+
+### Variants
+
+For an alternative visual appearance and layout, without altering semantic meaning.
+
+```jsx
+<Stack direction="horizontal" gap="spacious" padding="none">
+  <Testimonial variant="default">
+    <Testimonial.Quote>
+      GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+      of code we&apos;re writing.
+    </Testimonial.Quote>
+    <Testimonial.Name position="Staff Security Engineer">David Ross</Testimonial.Name>
+    <Testimonial.Avatar src="/images/avatar-mona.png" alt="Circular avatar from David Ross's GitHub profile" />
+  </Testimonial>
+  <Testimonial variant="subtle">
+    <Testimonial.Quote>
+      GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+      of code we&apos;re writing.
+    </Testimonial.Quote>
+    <Testimonial.Name position="Staff Security Engineer">David Ross</Testimonial.Name>
+    <Testimonial.Avatar src="/images/avatar-mona.png" alt="Circular avatar from David Ross's GitHub profile" />
+  </Testimonial>
+</Stack>
+```
+
+### Logo
+
+A logo (or similar) visual can be provided as an alternative to avatars.
+
+```jsx
+<Testimonial>
+  <Testimonial.Quote>
+    GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+    of code we&apos;re writing.
+  </Testimonial.Quote>
+  <Testimonial.Name>David Ross</Testimonial.Name>
+  <Testimonial.Logo>
+    <img alt="GitHub Logo" src="https://github.githubassets.com/images/modules/logos_page/GitHub-Logo.png" width={60} />
+  </Testimonial.Logo>
+</Testimonial>
+```
+
+### Size
+
+Use `size` to alternate the text size. Available options are `small` (default) and `large`.
+
+```jsx
+<Testimonial size="large">
+  <Testimonial.Quote>
+    GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+    of code we&apos;re writing.
+  </Testimonial.Quote>
+  <Testimonial.Name position="Staff Software Engineer">David Ross</Testimonial.Name>
+</Testimonial>
+```
+
+### Layout
+
+`Testimonial` will expand to fill the width of its parent by default.
+
+Use `Stack` to help position multiple, adjacent Testimonials alongside one another.
+
+```jsx
+<Stack direction="horizontal" gap="spacious" padding="spacious">
+  <Testimonial>
+    <Testimonial.Quote>
+      GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+      of code we&apos;re writing.
+    </Testimonial.Quote>
+    <Testimonial.Name>David Ross</Testimonial.Name>
+  </Testimonial>
+  <Testimonial>
+    <Testimonial.Quote>
+      GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+      of code we&apos;re writing.
+    </Testimonial.Quote>
+    <Testimonial.Name>David Ross</Testimonial.Name>
+  </Testimonial>
+</Stack>
+```
+
+Use the `expressive` variant to place the quote on the left and the attribution on the right.
+
+```jsx
+<Testimonial variant="expressive">
+  <Testimonial.Quote>
+    GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+    of code we&apos;re writing.
+  </Testimonial.Quote>
+  <Testimonial.Name position="Staff Security Engineer">David Ross</Testimonial.Name>
+  <Testimonial.Logo>
+    <img alt="GitHub Logo" src="https://github.githubassets.com/images/modules/logos_page/GitHub-Logo.png" width={60} />
+  </Testimonial.Logo>
+</Testimonial>
+```
+
+### Position
+
+Pass additional content about the testimonial provider using `position`.
+
+```jsx
+<Testimonial>
+  <Testimonial.Quote>
+    GitHub helps us ensure that we have our security controls baked into our pipelines all the way from the first line
+    of code we&apos;re writing.
+  </Testimonial.Quote>
+  <Testimonial.Name position="Staff Software Engineer">David Ross</Testimonial.Name>
+</Testimonial>
+```
+
+## Component props
+
+### Testimonial `Required`
+
+`Testimonial` passes contextual data to its child inputs, labels, validation messaging and more.
+
+| Name             | Type                                                                                                           |   Default   | Description                                             |
+| :--------------- | :------------------------------------------------------------------------------------------------------------- | :---------: | :------------------------------------------------------ |
+| `children`       | `'Testimonial.Quote' \| 'Testimonial.Name' \| 'Testimonial.Logo' \| 'Testimonial.Avatar' \| 'React.ReactNode'` |             | Valid child nodes                                       |
+| `className`      | `string`                                                                                                       |             | Sets a custom class                                     |
+| `id`             | `string`                                                                                                       |             | Sets a custom id                                        |
+| `ref`            | `React.RefObject`                                                                                              |             | Forward a Ref to the underlying DOM node                |
+| `size`           |                                                                                                                |  `'small'`  | Set size of quote's text                                |
+| `quoteMarkColor` |                                                                                                                | `'default'` | Color or gradient fill of the the quote mark.           |
+| `variant`        |                                                                                                                | `'minimal'` | Alternative visual appearance.                          |
+| `hasBorder`      | `boolean`                                                                                                      |    `true`   | Applies an optional border where a variant supports it. |
+
+### Testimonial.Name `Required`
+
+`Testimonial.Name` indicates the name of the person (or organisation) that provided the testimonial.
+
+| Name        | Type              | Default | Description                                                         |
+| :---------- | :---------------- | :-----: | :------------------------------------------------------------------ |
+| `children`  | `string`          |         | Label text                                                          |
+| `className` | `string`          |         | Applies a custom class                                              |
+| `id`        | `string`          |         | Sets a custom id                                                    |
+| `ref`       | `React.RefObject` |         | Forward a Ref to the underlying DOM node                            |
+| `position`  | `string`          |         | Optional. Applies additional content adjancent to the primary text. |
+
+### Testimonial.Avatar
+
+`Testimonial.Avatar` represent users or organizations.
+
+| Name        | Type              | Default | Description                                                        |
+| :---------- | :---------------- | :-----: | :----------------------------------------------------------------- |
+| `children`  | `string`          |         | Label text                                                         |
+| `className` | `string`          |         | Applies a custom class                                             |
+| `id`        | `string`          |         | Sets a custom id                                                   |
+| `ref`       | `React.RefObject` |         | Forward a Ref to the underlying DOM node                           |
+| `src`       | `string`          |         | Required. A url to the user or organisations GitHub profile avatar |
+| `alt`       | `string`          |         | Required. Applied as alt text to the avatar.                       |
+
+### Testimonial.Logo
+
+`Testimonial.Logo` passes a visual that represents the users or organizations.
+
+| Name        | Type              | Default | Description                                            |
+| :---------- | :---------------- | :-----: | :----------------------------------------------------- |
+| `children`  |                   |         | Accepts `<img>` and `<svg>` HTML elements as children. |
+| `className` | `string`          |         | Applies a custom class                                 |
+| `id`        | `string`          |         | Sets a custom id                                       |
+| `ref`       | `React.RefObject` |         | Forward a Ref to the underlying DOM node               |