npm - @primer/react-brand - Versions diffs - 0.69.1-rc.0a4e5ff5 → 0.70.0-rc.11ae3568 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (702) hide show

package/docs/components/Timeline/index.md ADDED Viewed

@@ -0,0 +1,68 @@
+---
+title: Timeline
+description: Use the timeline component to display a list of connected items as a vertical timeline.
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Timeline/Timeline.tsx
+storybook: '/brand/storybook/?path=/story/components-timeline--default'
+---
+```js
+import {Timeline} from '@primer/react-brand'
+```
+## Examples
+> Timeline requires the `dir` attribute to be set on the `<html>` element to ensure the correct visual appearance of timeline items.
+### Default
+```jsx
+<Timeline>
+  <Timeline.Item>
+    GitHub Codespaces offers a complete dev environment in seconds, so you can code, build, test, and open pull requests
+    from any repo anywhere.
+  </Timeline.Item>
+  <Timeline.Item>
+    GitHub Copilot is your AI pair programmer that empowers you to complete tasks 55% faster by turning natural language
+    prompts into coding suggestions.
+  </Timeline.Item>
+  <Timeline.Item>
+    GitHub Actions automates your build, test, and deployment workflow with simple and secure CI/CD.
+  </Timeline.Item>
+</Timeline>
+```
+### With emphasis
+Use a `<b>` element within the timeline items to apply a duotone style and emphasize part of the text.
+```jsx
+<Timeline>
+  <Timeline.Item>
+    <b>GitHub Codespaces</b> offers a complete dev environment in seconds, so you can code, build, test, and open pull
+    requests from any repo anywhere.
+  </Timeline.Item>
+  <Timeline.Item>
+    <b>GitHub Copilot</b> is your AI pair programmer that empowers you to complete tasks 55% faster by turning natural
+    language prompts into coding suggestions.
+  </Timeline.Item>
+  <Timeline.Item>
+    <b>GitHub Actions</b> automates your build, test, and deployment workflow with simple and secure CI/CD.
+  </Timeline.Item>
+</Timeline>
+```
+### Timeline
+| Name        | Type                               | Default | Description                                  |
+| :---------- | :--------------------------------- | :-----: | :------------------------------------------- |
+| `className` | `string`                           |         | Sets a custom class on the root element      |
+| `children`  | `Timeline.Item`, `Timeline.Item[]` |         | Content to be displayed within the component |
+| `fullWidth` | `boolean`                          | `false` | Fills available space                        |
+### Timeline.Item
+| Name        | Type                                   | Default | Description                              |
+| :---------- | :------------------------------------- | :-----: | :--------------------------------------- |
+| `className` | `string`                               |         | Sets a custom class on the root element  |
+| `children`  | `React.ReactNode`, `React.ReactNode[]` |         | Content to be displayed within the item. |

package/docs/components/Token/index.md ADDED Viewed

@@ -0,0 +1,86 @@
+---
+title: Token
+description: Token is a compact representation of an object, and is typically used to show a collection of related metadata.
+keywords: ['tag', 'metadata', 'category', 'chip', 'link']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/Token/Token.tsx
+storybook: '/brand/storybook/?path=/story/components-token--playground'
+a11yReviewed: false
+---
+```js
+import {Avatar, Stack, Token} from '@primer/react-brand'
+```
+`Token` is a compact representation of an object, and is typically used to show a collection of related metadata.
+Keep `Token` content short and easy to scan. A single word is ideal. Two short words are acceptable when the category or type needs more context.
+## Examples
+### Default
+```jsx
+<Token>Guide</Token>
+```
+### Variants
+```jsx
+<Stack direction="horizontal" alignItems="flex-start" padding="none" style={{flexWrap: 'wrap'}}>
+  <Token variant="default">Default</Token>
+  <Token variant="accent">Accent</Token>
+  <Token variant="outline">Outline</Token>
+  <Token variant="invisible">Invisible</Token>
+</Stack>
+```
+### Interactive tokens
+When the entire `Token` should act as a link, render it as an anchor. Use interactive Tokens for secondary navigation, filters, or related metadata links. Do not use Tokens as primary calls to action.
+Use `as="a"` when the whole `Token` should act as a link.
+```jsx
+<Stack direction="horizontal" alignItems="flex-start" padding="none" style={{flexWrap: 'wrap'}}>
+  <Token as="a" href="https://github.com" variant="default">
+    Guide
+  </Token>
+  <Token as="a" href="https://github.com" variant="outline">
+    Actions
+  </Token>
+</Stack>
+```
+### Leading visual
+Use a leading visual when it helps users scan the Token more quickly. Octicons, logos, and small square avatars work well here. Keep the visual decorative and compact.
+```jsx
+<Stack direction="horizontal" alignItems="flex-start" padding="none" style={{flexWrap: 'wrap'}}>
+  <Token leadingVisual={<CopilotIcon />}>Copilot</Token>
+  <Token variant="outline" leadingVisual={<CopilotIcon />}>
+    Compare
+  </Token>
+  <Token leadingVisual={<Avatar shape="square" size={32} src="/images/avatar-mona.png" alt="Mona profile" />}>
+    With an optional Avatar
+  </Token>
+</Stack>
+```
+## Component props
+### Token
+| name            | type            | default     | required | description                                         |
+| --------------- | --------------- | ----------- | -------- | --------------------------------------------------- |
+| `as`            | `'span' \| 'a'` | `'span'`    | `false`  | The HTML element rendered by Token                  |
+| `leadingVisual` | `ReactElement`  | `undefined` | `false`  | The leading visual appears before the Token content |
+| `variant`       | `TokenVariants` | `'default'` | `false`  | The variant variations available in Token           |
+| `href`          | `string`        | `undefined` | `false`  | Anchor destination when `as="a"`                    |
+## Related components
+- [Label](../Label/index.md): For larger non-interactive status and metadata treatments.
+- Link: For inline navigational text.
+- [Button](../Button/index.md): For higher-emphasis actions.

package/docs/components/Tooltip/index.md ADDED Viewed

@@ -0,0 +1,61 @@
+---
+title: Tooltip
+description: Use the tooltip component to display a short message when a user hovers or focuses an interactive element.
+keywords: ['tooltip', 'help', 'popup', 'information', 'hint']
+source: https://github.com/primer/brand/blob/main/packages/react/src/Tooltip/Tooltip.tsx
+storybook: '/brand/storybook/?path=/story/components-tooltip--playground'
+ready: true
+---
+```js
+import {Tooltip} from '@primer/react-brand'
+```
+## Examples
+### Default
+```jsx
+<Tooltip text="Sample tooltip content">
+  <Button>Action</Button>
+</Tooltip>
+```
+### Custom direction
+By default, tooltips appear below the element. You can change the direction by passing the `direction` prop with a value of `n`, `e`, `s`, or `w`.
+As long as there is enough room in the viewport, the tooltip will appear in the specified direction. If there is not enough room, the tooltip will appear in whatever direction it can place the tooltip without overflowing the viewport.
+```jsx
+<Tooltip text="Sample tooltip content" direction="e">
+  <Button>Action</Button>
+</Tooltip>
+```
+### Substitute a visible label
+If a ubiquitously understood icon is used in place of a text label, you can use the `type` to provide a text label for assistive technologies such as screen readers.
+Use this with caution. It is generally better to use a visible label for better usability and accessibility.
+```jsx
+<Tooltip text="Go fullscreen" type="label">
+  <Button>
+    <ScreenFullIcon />
+  </Button>
+</Tooltip>
+```
+## Component props
+| name        | type                       | default         | required | description                                                                                                                                                                                                |
+| ----------- | -------------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `direction` | `'n' \| 'e' \| 's' \| 'w'` | `'s'`           | `false`  | The side the tooltip appears on                                                                                                                                                                            |
+| `text`      | `string`                   | `undefined`     | `true`   | The text to be displayed in the tooltip                                                                                                                                                                    |
+| `type`      | `'description' \| 'label'` | `'description'` | `false`  | The type of tooltip. `label` is used for labelling the element that triggers tooltip. `description` is used for describing or adding a supplementary information to the element that triggers the tooltip. |
+## Related components
+- Popover: For displaying more complex interactive content that appears when triggered
+- [Button](../Button/index.md): Often used in conjunction with tooltips

package/docs/components/UnorderedList/index.md ADDED Viewed

@@ -0,0 +1,67 @@
+---
+title: Unordered list
+description: Use the unordered list component to present a collection of items without specific ordering.
+keywords: ['bullet list']
+---
+## Anatomy
+![Unordered list renders as a list with a visual indicator such as a checkmark](https://github.com/primer/brand/assets/912236/646a4719-dddf-47f5-9b34-85f6addb828e)
+## Usage
+Use an unordered list to group related items together. It is suitable for presenting a collection of items that do not require a specific order or ranking. The unordered list provides visual dashes for each item, which helps to emphasize the individuality of each point and makes it easier for users to scan and comprehend the information.
+**✅ Do**
+![](https://github.com/primer/brand/assets/912236/3746552a-8fd2-4fbf-9ad5-ed9b1bdcff0d)
+_Use an unordered list to present and group a list of items that don't require a specific order._
+**❌ Don't**
+![](https://github.com/primer/brand/assets/912236/5df3fd9d-5508-48b1-a4e4-7891d6ecabb3)
+_Don't use an unordered list to present a sequence of steps. Use an ordered list instead._
+Use the unordered list to effectively provide a quick reference or highlight key points. This allows users to easily grasp the main ideas or features without having to read lengthy paragraphs. For lists that require a linear order, consider using an [ordered list](../OrderedList/index.md) instead.
+The unordered list should have concise and short items. Avoid using long sentences or paragraphs as they can be difficult to scan and comprehend. If you need to include a long item or even headings and links, consider using a [pillar](../Pillar/index.md), a [card](../Card/index.md) or a [river](../River/index.md) instead.
+**✅ Do**
+![](https://github.com/primer/brand/assets/912236/990a350b-cc8c-42f1-88db-662b5609a179)
+_Use an unordered list for short and concise content items._
+**❌ Don't**
+![](https://github.com/primer/brand/assets/912236/a416e1e6-58e6-4710-a2f9-646513853dcc)
+_Don't use an unordered list for long and rich sentences, paragraphs, headings or links. Use a pillar, card or
+river components instead._
+## Options
+### Variant
+The unordered list uses a dash to indicate each item in the list. The dash is the default variant and is suitable for most use cases. You can use check icons to indicate a list of features or benefits that are supported by the application. This way users can easily check off or easily compare the features that they might be interested in.
+**✅ Do**
+![](https://github.com/primer/brand/assets/912236/afd68e16-0345-4085-b549-82647ca8136a)
+_Use the check variant to indicate a list of features that are supported._
+**❌ Don't**
+![](https://github.com/primer/brand/assets/912236/7d8ddb4b-1a37-4b7b-a773-1eaeb9027d46)
+_Don't include mutliple benefits in one single items, split them into multiple ones for better readability._
+## Related components
+- [Ordered list](../OrderedList/index.md): to display a list of plain content items.
+- [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 a list of content items with a visual asset.

package/docs/components/UnorderedList/react.md ADDED Viewed

@@ -0,0 +1,89 @@
+---
+title: Unordered list
+description: Use the unordered list component to present a collection of items without specific ordering.
+keywords: ['bullet list']
+ready: true
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/branch/NzBMPIfPrFU9I87d3k7KVq/Primer-Brand?node-id=4045%3A17093&t=XJ9W58VgtbVo74gb-0'
+source: https://github.com/primer/brand/blob/main/packages/react/src/list/UnorderedList/UnorderedList.tsx
+storybook: '/brand/storybook/?path=/story/components-unorderedlist--playground'
+---
+```js
+import {UnorderedList} from '@primer/react-brand'
+```
+## Examples
+### Default
+```jsx
+<UnorderedList>
+  <UnorderedList.Item>Automatic security and version updates</UnorderedList.Item>
+  <UnorderedList.Item>GitHub Security Advisories</UnorderedList.Item>
+  <UnorderedList.Item>Code and secret scanning</UnorderedList.Item>
+  <UnorderedList.Item>Dependency review</UnorderedList.Item>
+  <UnorderedList.Item>Automated authentication and identity management</UnorderedList.Item>
+</UnorderedList>
+```
+### Checked variant
+```jsx
+<UnorderedList variant="checked">
+  <UnorderedList.Item>Automatic security and version updates</UnorderedList.Item>
+  <UnorderedList.Item>GitHub Security Advisories</UnorderedList.Item>
+  <UnorderedList.Item>Code and secret scanning</UnorderedList.Item>
+  <UnorderedList.Item>Dependency review</UnorderedList.Item>
+  <UnorderedList.Item>Automated authentication and identity management</UnorderedList.Item>
+</UnorderedList>
+```
+### `x` variant
+```jsx
+<UnorderedList variant="x">
+  <UnorderedList.Item>Automatic security and version updates</UnorderedList.Item>
+  <UnorderedList.Item>GitHub Security Advisories</UnorderedList.Item>
+  <UnorderedList.Item>Code and secret scanning</UnorderedList.Item>
+  <UnorderedList.Item>Dependency review</UnorderedList.Item>
+  <UnorderedList.Item>Automated authentication and identity management</UnorderedList.Item>
+</UnorderedList>
+```
+### Custom colors
+```jsx
+<UnorderedList variant="checked">
+  <UnorderedList.Item leadingVisualFill="var(--brand-color-success-fg)">
+    Automatic security and version updates
+  </UnorderedList.Item>
+  <UnorderedList.Item leadingVisualFill="var(--brand-color-success-fg)">GitHub Security Advisories</UnorderedList.Item>
+  <UnorderedList.Item leadingVisualFill="var(--brand-color-success-fg)">Code and secret scanning</UnorderedList.Item>
+  <UnorderedList.Item leadingVisualFill="var(--brand-color-success-fg)">Dependency review</UnorderedList.Item>
+  <UnorderedList.Item leadingVisualFill="var(--brand-color-success-fg)">
+    Automated authentication and identity management
+  </UnorderedList.Item>
+</UnorderedList>
+```
+## Component props
+### UnorderedList
+| Name        | Type                                   |  Default  | Description                                                |
+| :---------- | :------------------------------------- | :-------: | :--------------------------------------------------------- |
+| `className` | `string`                               |           | Sets a custom class on the root element                    |
+| `variant`   | `default`, `checked` , `x`             | `default` | Specify alternative leading visual for list items          |
+| `children`  | `React.ReactNode`, `React.ReactNode[]` |           | Content to be displayed within the UnorderedList component |
+### UnorderedList.Item
+| Name                     | Type                                   |   Default   | Description                                                                                         |
+| :----------------------- | :------------------------------------- | :---------: | :-------------------------------------------------------------------------------------------------- |
+| `className`              | `string`                               |             | Sets a custom class on the root element                                                             |
+| `children`               | `React.ReactNode`, `React.ReactNode[]` |  `default`  | Content to be displayed within the OrderedList component                                            |
+| `leadingVisual`          | `Icon`                                 | `undefined` | Sets a custom leading visual ([Octicon](https://primer.style/foundations/icons/)) for the list item |
+| `leadingVisualFill`      | `string`                               | `undefined` | Sets a custom color value for the leading visual                                                    |
+| `leadingVisualAriaLabel` | `string`                               | `undefined` | Sets `aria-label` on the leading visual icon                                                        |
+Also forwards the `variant` prop from the [Text component](../../typography/Text/index.md).

package/docs/components/VideoPlayer/index.md ADDED Viewed

@@ -0,0 +1,234 @@
+---
+title: Video player
+description: Use the video player component to enable playback of self-hosted videos
+keywords: ['playback', 'media']
+ready: true
+source: https://github.com/primer/brand/blob/main/packages/react/src/VideoPlayer/VideoPlayer.tsx
+storybook: '/brand/storybook/?path=/story/components-videoplayer--playground'
+---
+```js
+import {VideoPlayer} from '@primer/react-brand'
+```
+## Examples
+### Default
+```jsx
+<VideoPlayer title="GitHub media player">
+  <VideoPlayer.Source src="/example.mp4" />
+  <VideoPlayer.Track src="/example.vtt" default />
+</VideoPlayer>
+```
+## With Audio Description
+Videos with important visual information must include an audio description to ensure that the content is accessible to all users.
+The audio description can be provided as part of the existing soundtrack, or via a link to an alternate audio-described version.
+```jsx
+<Stack gap="normal" alignItems="center">
+  <VideoPlayer title="GitHub media player">
+    <VideoPlayer.Source src="/example.mp4" />
+    <VideoPlayer.Track src="/example.vtt" default />
+  </VideoPlayer>
+  <Stack direction="horizontal" gap={12} padding="none" alignItems="center">
+    <Link href="#" arrowDirection="none">
+      Watch with audio description
+    </Link>
+    <LinkExternalIcon size={16} />
+  </Stack>
+</Stack>
+```
+## With poster
+```jsx
+<VideoPlayer poster="/images/example-poster.png" title="GitHub media player">
+  <VideoPlayer.Source src="/example.mp4" />
+  <VideoPlayer.Track src="/example.vtt" default />
+</VideoPlayer>
+```
+## Without branding
+```jsx
+<VideoPlayer showBranding={false} title="GitHub media player">
+  <VideoPlayer.Source src="/example.mp4" />
+  <VideoPlayer.Track src="/example.vtt" default />
+</VideoPlayer>
+```
+## With visually hidden title
+```jsx
+<VideoPlayer visuallyHiddenTitle title="GitHub media player">
+  <VideoPlayer.Source src="/example.mp4" />
+  <VideoPlayer.Track src="/example.vtt" default />
+</VideoPlayer>
+```
+## With some hidden controls
+```jsx
+<VideoPlayer
+  title="GitHub media player"
+  showPlayPauseButton={false}
+  showSeekControl={true}
+  showCCButton={false}
+  showMuteButton={false}
+  showVolumeControl={false}
+  showFullScreenButton={false}
+>
+  <VideoPlayer.Source src="/example.mp4" type="video/mp4" />
+  <VideoPlayer.Track src="/example.vtt" default />
+</VideoPlayer>
+```
+## Hide controls when paused
+```jsx
+<VideoPlayer title="GitHub media player" showControlsWhenPaused={false}>
+  <VideoPlayer.Source src="/example.mp4" type="video/mp4" />
+  <VideoPlayer.Track src="/example.vtt" default />
+</VideoPlayer>
+```
+## Minimal
+```jsx
+<VideoPlayer title="GitHub media player" visuallyHiddenTitle showBranding={false} showControlsWhenPaused={false}>
+  <VideoPlayer.Source src="/example.mp4" type="video/mp4" />
+  <VideoPlayer.Track src="/example.vtt" default />
+</VideoPlayer>
+```
+## Custom play icon
+```jsx
+<VideoPlayer title="GitHub media player" playIcon={() => <PlayIcon fill="white" size={96} />}>
+  <VideoPlayer.Source src="/example.mp4" type="video/mp4" />
+  <VideoPlayer.Track src="/example.vtt" default />
+</VideoPlayer>
+```
+## Controlling programmatically
+The `VideoPlayer` component exposes a `useVideo` hook that can be used to control the video programmatically. To use the hook, the `VideoPlayer` component must be wrapped in a `VideoPlayer.Provider` component.
+Full documentation for the `useVideo` hook can be found [below](#usevideo-context).
+```jsx filename="noinline"
+const CustomVideoPlayer = () => {
+  const {isPlaying, togglePlaying, seek} = useVideo()
+  return (
+    <Stack direction="vertical">
+      <VideoPlayer
+        title="GitHub media player"
+        showPlayPauseButton={false}
+        showSeekControl={false}
+        showCCButton={false}
+        showMuteButton={false}
+        showVolumeControl={false}
+        showFullScreenButton={false}
+      >
+        <VideoPlayer.Source src="/example.mp4" type="video/mp4" />
+        <VideoPlayer.Track src="/example.vtt" default />
+      </VideoPlayer>
+      <Stack direction="horizontal">
+        <Button onClick={() => togglePlaying()}>{isPlaying ? 'Pause' : 'Play'}</Button>
+        <Button onClick={() => seek(0)}>Go to start</Button>
+        <Button onClick={() => seek(t => t + 5)}>Skip 5 seconds</Button>
+      </Stack>
+    </Stack>
+  )
+}
+const App = () => (
+  <VideoPlayer.Provider>
+    <CustomVideoPlayer />
+  </VideoPlayer.Provider>
+)
+render(<App />)
+```
+## useVideo Context
+The `useVideo` context provides a comprehensive API for managing video playback, volume, closed captioning, and fullscreen mode.
+The context can be accessed by using the `useVideo` hook in any component that is a child of `VideoPlayer.Provider`.
+Below is a detailed description of each property and method available in the `useVideo` context.
+| Name               | Type                                               | Description                                                                                    |
+| :----------------- | :------------------------------------------------- | :--------------------------------------------------------------------------------------------- |
+| `ref`              | `RefObject<HTMLVideoElement>`                      | A reference to the video element.                                                              |
+| `isPlaying`        | `boolean`                                          | Indicates if the video is currently playing.                                                   |
+| `volume`           | `number`                                           | The current volume of the video, ranging from 0 to 1.                                          |
+| `isMuted`          | `boolean`                                          | Indicates if the video is currently muted.                                                     |
+| `volumeBeforeMute` | `number`                                           | The volume of the video before it was muted, allowing for easy unmuting to the previous level. |
+| `duration`         | `number`                                           | The total duration of the video in seconds.                                                    |
+| `ccEnabled`        | `boolean`                                          | Indicates if closed captions are enabled.                                                      |
+| `isFullScreen`     | `boolean`                                          | Indicates if the video is currently in fullscreen mode.                                        |
+| `play`             | `() => void`                                       | Plays the video.                                                                               |
+| `pause`            | `() => void`                                       | Pauses the video.                                                                              |
+| `togglePlaying`    | `() => void`                                       | Toggles between playing and pausing the video.                                                 |
+| `setVolume`        | `(volumeValOrFn: SetStateAction<number>) => void`  | Sets the volume of the video.                                                                  |
+| `mute`             | `() => void`                                       | Mutes the video.                                                                               |
+| `unmute`           | `() => void`                                       | Unmutes the video.                                                                             |
+| `toggleMute`       | `() => void`                                       | Toggles between muting and unmuting the video.                                                 |
+| `setDuration`      | `(duration: number) => void`                       | Sets the duration of the video.                                                                |
+| `seekToPercent`    | `(percent: number) => void`                        | Seeks the video to a specific percentage of its duration.                                      |
+| `seek`             | `(secondsValOrFn: SetStateAction<number>) => void` | Seeks the video to an absolute time, or to a relative time if passed a function.               |
+| `enableCC`         | `() => void`                                       | Enables closed captions.                                                                       |
+| `disableCC`        | `() => void`                                       | Disables closed captions.                                                                      |
+| `toggleCC`         | `() => void`                                       | Toggles closed captions on and off.                                                            |
+| `enterFullScreen`  | `() => void`                                       | Enters fullscreen mode.                                                                        |
+| `exitFullScreen`   | `() => void`                                       | Exits fullscreen mode.                                                                         |
+| `toggleFullScreen` | `() => void`                                       | Toggles between entering and exiting fullscreen mode.                                          |
+## Component props
+### VideoPlayer `Required`
+`VideoPlayer` provides a React alternative to the native HTML `<video />`.
+| Name                     | Type                                   | Default | Required | Description                                                     |
+| :----------------------- | :------------------------------------- | :-----: | :------: | :-------------------------------------------------------------- |
+| `children`               | `React.ReactNode`, `React.ReactNode[]` |         |  `true`  | Takes `<VideoPlayer.Source>` and `<VideoPlayer.Track>` elements |
+| `title`                  | `string`                               |         |  `true`  | Sets the title of the video                                     |
+| `visuallyHiddenTitle`    | `boolean`                              |         |  `false` | Visually hides the title of the video in the upper-left corner  |
+| `showBranding`           | `boolean`                              |  `true` |  `false` | Displays GitHub branding next to video title                    |
+| `poster`                 | `string`                               |         |  `false` | Sets an image as the starting frame for the video element       |
+| `className`              | `string`                               |         |  `false` | Sets a custom class on the `<video>` element                    |
+| `showControlsWhenPaused` | `boolean`                              |  `true` |  `false` | Show the video controls when paused                             |
+| `showPlayPauseButton`    | `boolean`                              |  `true` |  `false` | Show the play button control                                    |
+| `showSeekControl`        | `boolean`                              |  `true` |  `false` | Show the seek control                                           |
+| `showCCButton`           | `boolean`                              |  `true` |  `false` | Show the closed caption toggle control                          |
+| `showMuteButton`         | `boolean`                              |  `true` |  `false` | Show the mute button control                                    |
+| `showVolumeControl`      | `boolean`                              |  `true` |  `false` | Show the volume control                                         |
+| `showFullScreenButton`   | `boolean`                              |  `true` |  `false` | Show the full screen button control                             |
+The component API supports all standard HTML attribute props, while providing some additional behavior as described above.
+### VideoPlayer.Source `Required`
+`VideoPlayer.Source` provides a React alternative to the native HTML `<source />`. The component API supports all standard HTML attribute props.
+### VideoPlayer.Track `Required`
+`VideoPlayer.Track` provides a React alternative to the native HTML `<track />`.
+| Name   | Type                                                                      |    Default   | Required | Description                                 |
+| :----- | :------------------------------------------------------------------------ | :----------: | :------: | :------------------------------------------ |
+| `kind` | `'subtitles'`, `'captions'`, `'descriptions'`, `'chapters'`, `'metadata'` | `'captions'` |  `false` | Sets how the text track is meant to be used |
+The component API supports all standard HTML attribute props, while providing some additional behavior as described above.
+### VideoPlayer.Provider
+`VideoPlayer.Provider` can be used in conjunction with the `useVideo` hook to enable programmatic access to features such as video playback, volume, closed captioning, and fullscreen mode.