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

package/docs/components/index.md

@@ -0,0 +1,53 @@
+---
+title: Components
+description: Primer Brand UI components
+---
+
+## In this section
+
+- [Action menu](ActionMenu/index.md): Use the action menu component to display a list of actions or selections that expand through a trigger button.
+- [Anchor nav](AnchorNav/index.md): Use the anchor nav component for prompt navigation to different sections of a page.
+- [Avatar](Avatar/react.md): Use the avatar component to display a thumbnail representation of a person.
+- [Bento](Bento/index.md): Use the bento to present content in a responsive grid layout.
+- [Breadcrumbs](Breadcrumbs/react.md): Breadcrumbs display the current page within the site's hierarchy, allowing users to easily navigate to a different level.
+- [Breakout banner](BreakoutBanner/react.md): Use a breakout banner to break up content on longer pages and highlight important information.
+- [Button](Button/react.md): Use the button component for the main actions on a page or form.
+- [Button group](ButtonGroup/react.md): Use the button group component to group related buttons together.
+- [Card](Card/react.md): Use the card component to display information in a compact way and link to other internal pages.
+- [Comparison table](ComparisonTable/index.md): Use the comparison table component to compare two products or features in a table format.
+- [CTA banner](CTABanner/react.md): Use the CTA banner component to highlight and create urgency around user actions.
+- [CTA form](CTAForm/react.md): Use the CTA form component to create a form that is used to collect minimal information from users.
+- [Eyebrow banner](EyebrowBanner/index.md): Use the eyebrow banner to highlight important information at the top of a page.
+- [FAQ](FAQ/react.md): Use the FAQ component to display content in a Q&A format.
+- [Footnotes](Footnotes/react.md): Use footnotes to display contextual information and cite sources in the page content.
+- [Hero](Hero/react.md): Use the hero component to render a full-width banner at the top of a page.
+- [Icon](Icon/index.md): Use the icon component to display Octicons with an optional background
+- [IDE](IDE/index.md): Use the IDE to showcase a simulated integrated developer environment, complete with a code editor and AI chat that's intended to enhance code representation in marketing contexts.
+- [Image](Image/react.md): Use the image component to display a graphical representation.
+- [Label](Label/react.md): Use the label component to add metadata or indicate the status of items.
+- [Logo suite](LogoSuite/react.md): Use a logo suite to present a list logos, such as sponsors or vendors.
+- [Media playlist](MediaPlaylist/index.md): Use MediaPlaylist to pair thumbnail-backed media items with a shared playback or media area.
+- [Minimal footer](MinimalFooter/index.md): Use the minimal footer component to provide a global footer featuring legal links, GitHub logomarks and footnotes.
+- [NavList](NavList/index.md): Use NavList to render vertical navigation with optional expandable groups.
+- [Ordered list](OrderedList/react.md): Use the ordered list component to display a list of numbered items.
+- [Pagination](Pagination/index.md): Use Pagination to display a sequence of links that allow navigation to discrete, related pages.
+- [Pillar](Pillar/react.md): Use the pillar component to group related content together.
+- [Pricing options](PricingOptions/index.md): Use the pricing options to display pricing plan information on a page.
+- [Prose](Prose/index.md): Use the prose component to apply Primer Brand styles to HTML markup.
+- [River](River/react.md): Use the river component to introduce a feature using a type and media pairing.
+- [River accordion](RiverAccordion/index.md): Use the river accordion to create expandable content panels with associated visuals.
+- [River breakout tabs](RiverBreakoutTabs/index.md): Use RiverBreakoutTabs to pair card-based tabs with a shared visual area on desktop and an accordion pattern on narrower viewports.
+- [Section](Section/react.md): Use the section component to group related content together.
+- [Section intro](SectionIntro/react.md): Use the section intro component to provide a title, optional description and link to a new section in the page.
+- [Section intro stacked](SectionIntroStacked/index.md): Use this section intro component to provide a heading, link and itemized content in a stacked layout.
+- [Statistic](Statistic/index.md): Use the statistic component display concise numerical information
+- [Sub nav](SubNav/index.md): A sub nav is a secondary navigation element, typically positioned beneath a primary navigation.
+- [Subdomain nav bar](SubdomainNavBar/index.md): Use the subdomain nav bar component for top level navigation for subdomain sites.
+- [Tabs](Tabs/index.md): Use Tabs to display a list of tabs with associated content panels.
+- [Testimonial](Testimonial/react.md): Use testimonial to display a quote from a customer or user.
+- [Tiles](Tiles/index.md): Use tiles to display a grid of logos or icons with optional links.
+- [Timeline](Timeline/index.md): Use the timeline component to display a list of connected items as a vertical timeline.
+- [Token](Token/index.md): Token is a compact representation of an object, and is typically used to show a collection of related metadata.
+- [Tooltip](Tooltip/index.md): Use the tooltip component to display a short message when a user hovers or focuses an interactive element.
+- [Unordered list](UnorderedList/react.md): Use the unordered list component to present a collection of items without specific ordering.
+- [Video player](VideoPlayer/index.md): Use the video player component to enable playback of self-hosted videos

package/docs/forms/Checkbox/index.md

@@ -0,0 +1,86 @@
+---
+title: Checkbox
+description: Use the checkbox component to select one or more options of a limited number of choices.
+keywords: ['form', 'control', 'selection', 'choices']
+---
+
+## Anatomy
+
+![An image displaying a checkbox with a checkbox and label.](https://github.com/primer/brand/assets/912236/a3c10059-1c76-4d51-8e83-0be9a7b8588b)
+
+- Checkbox: A selection control.
+- Label: A description for the checkbox.
+
+## Usage
+
+Use checkboxes to allow users to select multiple items from a list of individual items, or to mark one individual item as selected. Unlike the [Radio](../Radio/index.md) component or [Select](../Select/index.md) component, Checkbox does not restrict users to choosing just a single option.
+
+Checkbox labels should be descriptive and concise. Write labels in sentence case.
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/59d4b8da-1b59-418f-ae59-d2c6347376db)
+
+_Checkbox labels should be descriptive and concise._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/15d2412e-0adf-4449-97c1-fa51f7d0c2a7)
+
+_Don't make checkbox labels confusing, indirect, and avoid negative statements._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/01763c28-bccf-4aad-8179-1669667b4be0)
+
+_Use consistent styling (starting with capitalization and not ending with punctuation)._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/da0effd9-8111-44e6-a633-85f4baf2cb7a)
+
+_Don't have inconsistent styling (not starting with capitalization or ending in punctuation)._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/20a8d220-0875-49e6-a522-96192f51cc3b)
+
+_Use first-person when asking users for acknowledgement or consent._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/8ee9b08c-0a3d-4ff4-a6fa-224632597461)
+
+_Don't use third-person when asking users for acknowledgement or consent._
+
+**✅ Do**
+
+![](https://github.com/primer/brand/assets/912236/845c98ad-3c22-4ba1-8c14-5d978e39d51c)
+
+_Create checkbox options that are non-exclusive and allow for multiple selections._
+
+**❌ Don't**
+
+![](https://github.com/primer/brand/assets/912236/9747bf90-8e45-45f0-9ff7-80e70effd1c8)
+
+_Don't use checkbox options exclusive to one another. They should not be automatically deselected._
+
+### States
+
+Checkboxes have static dimensions and four different states: rest (default), checked, indeterminate, and disabled.
+
+An indeterminate checkbox state should be used if the input value is neither true nor false. This can be useful in situations where you are required to display an incomplete state, or one that is dependent on other input selections to determine a value.
+
+![](https://github.com/primer/brand/assets/912236/172e18b6-449e-4d3b-b3d0-a750df56fb77)
+
+## Accessibility
+
+Please use [FormControl](../FormControl/index.md) to display accessible checkboxes in the UI. This Checkbox component is intended only as an ingredient for other custom components, or as a drop-in replacement for native HTML checkboxes outside of form use-cases.
+
+If you intend to use this component as part of another component, it should always be accompanied by a corresponding `<label>` to improve support for assistive technologies.
+
+## Related components
+
+- [Radio](../Radio/index.md): Use the radio component when a user needs to select one option from a list.
+- [Select](../Select/index.md): Use the select component to enable selection of one option from a list.
+- [FormControl](../FormControl/index.md): Use the form control component to display form inputs alongside labels, validation and more.

package/docs/forms/Checkbox/react.md

@@ -0,0 +1,111 @@
+---
+title: Checkbox
+source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Checkbox/Checkbox.tsx
+keywords: ['form', 'control', 'selection', 'choices']
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1377%3A30754'
+storybook: '/brand/storybook/?path=/story/components-forms-checkbox--playground'
+description: Use the checkbox component to select one or more options of a limited number of choices.
+---
+
+## Examples
+
+> **Please use [FormControl](../FormControl/index.md) to display accessible checkboxes in the UI**. This `Checkbox` component is intended only as an ingredient for other custom components, or as a drop-in replacement for native HTML checkboxes outside of form use-cases.
+>
+> If you intend to use this component as part of another component, it should always be accompanied by a corresponding `<label>` to improve support for assistive technologies.
+
+The `Checkbox` component can be used in controlled and uncontrolled modes.
+
+```jsx
+<form>
+  <FormControl>
+    <Checkbox />
+    <FormControl.Label>Default checkbox</FormControl.Label>
+  </FormControl>
+  <FormControl>
+    <Checkbox checked />
+    <FormControl.Label>Always checked</FormControl.Label>
+  </FormControl>
+  <FormControl>
+    <Checkbox checked={false} />
+    <FormControl.Label>Always unchecked</FormControl.Label>
+  </FormControl>
+  <FormControl>
+    <Checkbox checked disabled />
+    <FormControl.Label>Inactive</FormControl.Label>
+  </FormControl>
+</form>
+```
+
+## Indeterminate
+
+An `indeterminate` checkbox state should be used if the input value is neither `true` nor `false`. This can be useful in situations where you are required to display an incomplete state, or one that is dependent on other input selections to determine a value.
+
+```jsx
+<form>
+  <FormControl>
+    <Checkbox onChange={() => {}} indeterminate={true} />
+    <FormControl.Label>Indeterminate checkbox</FormControl.Label>
+  </FormControl>
+</form>
+```
+
+## Optional border
+
+Apply an optional border using `FormControl` and `hasBorder`.
+
+```jsx
+<FormControl hasBorder required>
+  <Checkbox />
+  <FormControl.Label>Contact me about GitHub Enterprise Server</FormControl.Label>
+</FormControl>
+```
+
+## Custom label usage
+
+When using a custom label alongside a checkbox, the `Checkbox` component should always appear after the `FormControl.Label` component in the DOM. This ensures that the checkbox is correctly associated with the label for assistive technologies.
+
+```jsx
+<FormControl required>
+  <Checkbox />
+  <FormControl.Label>
+    <Text size="200" variant="muted">
+      I hereby accept the{' '}
+      <InlineLink size="200" href="https://github.com/customer-terms" target="_blank">
+        GitHub Customer Agreement
+      </InlineLink>{' '}
+      on behalf of my organization and confirm that I have the authority to do so. For more information about
+      GitHub&apos;s privacy practices, see the{' '}
+      <InlineLink
+        size="200"
+        href="https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement"
+        target="_blank"
+      >
+        GitHub Privacy Statement.
+      </InlineLink>
+    </Text>
+  </FormControl.Label>
+</FormControl>
+```
+
+## Component props
+
+`Checkbox` provides a React alternative to the native HTML `<input type="checkbox">`.
+
+The component API supports all standard HTML attribute props, while providing some additional behavior as described below.
+
+| Name               | Type              | Default | Description                                                                                                                                   |
+| :----------------- | :---------------- | :-----: | :-------------------------------------------------------------------------------------------------------------------------------------------- |
+| `checked`          | `boolean`         |         | Modifies true/false value of the native checkbox                                                                                              |
+| `className`        | `string`          |         | Sets a custom class                                                                                                                           |
+| `defaultChecked`   | `boolean`         |         | Checks the input by default in uncontrolled mode                                                                                              |
+| `disabled`         | `boolean`         |         | Modifies the native disabled state of the native checkbox                                                                                     |
+| `id`               | `string`          |         | Sets a custom id                                                                                                                              |
+| `indeterminate`    | `boolean`         |         | Applies an [indeterminate state](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#attr-indeterminate) to the checkbox |
+| `ref`              | `React.RefObject` |         | Forward a Ref to the underlying DOM node                                                                                                      |
+| `validationStatus` |                   |         | Ussed to inform ARIA attributes. Individual checkboxes do not have validation styles.                                                         |
+
+Additional props can be passed to the `<input>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) accepted by the `<input>` element.
+
+## Related components
+
+- FormControl

package/docs/forms/CheckboxGroup/index.md

@@ -0,0 +1,37 @@
+---
+title: Checkbox group
+description: Checkbox group renders a set of checkboxes.
+keywords: ['form', 'control', 'selection', 'choices']
+---
+
+## Usage
+
+Use checkbox group to allow users to select multiple items from a list of individual items, or to mark one individual item as selected.
+
+### Best practices
+
+- Put checkboxes in a logical order
+- If users are only allowed to select a single option, consider using a [radio group](../RadioGroup/index.md) instead
+- Each checkbox's state should be independent from other checkboxes in the group. For example: checking one checkbox should not check or disable any other checkboxes
+
+## Anatomy
+
+**Label:** A title that labels the group of options and helps users understand the relationship between the options in the group.
+
+**Required indicator:** Indicates that a selection is required.
+
+**Caption:** May be used to provide additional context about the checkbox group when the label alone is not sufficient
+
+**Options:** A list of options represented using [checkboxes](../Checkbox/index.md).
+
+**Validation message:** A message explaining why the selection failed validation. See the [form pattern documentation](https://primer.style/ui-patterns/forms/overview#validation-message) for more information on form validation patterns.
+
+## Accessibility
+
+Once a user checks an option from a checkbox group, the result should not be saved or applied until the user has explicitly submitted their input using a "save" or "submit" button. See the [saving pattern guidelines](https://primer.style/ui-patterns/saving) for more information.
+
+## Related components
+
+- [Checkbox](../Checkbox/index.md): Used to render an individual checkbox control.
+- [FormControl](../FormControl/index.md): Used to group individual controls with an associated label.
+- [RadioGroup](../RadioGroup/index.md): Similar to `CheckboxGroup`, but used for organizing radio controls.

package/docs/forms/CheckboxGroup/react.md

@@ -0,0 +1,175 @@
+---
+title: Checkbox group
+description: Checkbox group renders a set of checkboxes.
+keywords: ['form', 'control', 'selection', 'choices']
+source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Checkbox/Checkbox.tsx
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1377%3A30754'
+storybook: '/brand/storybook/?path=/story/components-forms-checkbox--playground'
+---
+
+```js
+import {CheckboxGroup} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+`CheckboxGroup` creates a semantic container for multiple related checkboxes.
+
+```jsx
+<CheckboxGroup>
+  <CheckboxGroup.Label>Choose your favorite features</CheckboxGroup.Label>
+  <FormControl>
+    <FormControl.Label>Actions notifications</FormControl.Label>
+    <Checkbox value="actions" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Packages</FormControl.Label>
+    <Checkbox value="packages" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Codespaces</FormControl.Label>
+    <Checkbox value="codespaces" />
+  </FormControl>
+</CheckboxGroup>
+```
+
+### With caption
+
+Use `CheckboxGroup.Caption` to provide additional context for the group.
+
+```jsx
+<CheckboxGroup>
+  <CheckboxGroup.Label>Notification preferences</CheckboxGroup.Label>
+  <CheckboxGroup.Caption>Select how you'd like to be notified</CheckboxGroup.Caption>
+  <FormControl>
+    <FormControl.Label>Email notifications</FormControl.Label>
+    <Checkbox value="email" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Browser notifications</FormControl.Label>
+    <Checkbox value="browser" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Mobile notifications</FormControl.Label>
+    <Checkbox value="mobile" />
+  </FormControl>
+</CheckboxGroup>
+```
+
+### With validation
+
+`CheckboxGroup.Validation` can display success or error states with appropriate icons.
+
+```jsx
+<Stack direction="vertical" gap="spacious">
+  <CheckboxGroup>
+    <CheckboxGroup.Label>Valid selection</CheckboxGroup.Label>
+    <FormControl>
+      <FormControl.Label>Option one</FormControl.Label>
+      <Checkbox value="one" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Option two</FormControl.Label>
+      <Checkbox value="two" />
+    </FormControl>
+    <CheckboxGroup.Validation variant="success">Great choice!</CheckboxGroup.Validation>
+  </CheckboxGroup>
+
+  <CheckboxGroup>
+    <CheckboxGroup.Label>Invalid selection</CheckboxGroup.Label>
+    <FormControl>
+      <FormControl.Label>Option one</FormControl.Label>
+      <Checkbox value="one" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Option two</FormControl.Label>
+      <Checkbox value="two" />
+    </FormControl>
+    <CheckboxGroup.Validation variant="error">Please select at least one option</CheckboxGroup.Validation>
+  </CheckboxGroup>
+</Stack>
+```
+
+### Visually hidden label
+
+When context is clear, labels can be visually hidden while remaining accessible to screen readers.
+
+```jsx
+<CheckboxGroup>
+  <CheckboxGroup.Label visuallyHidden>Filter options</CheckboxGroup.Label>
+  <Stack direction="vertical" gap="regular">
+    <FormControl>
+      <FormControl.Label>Show all</FormControl.Label>
+      <Checkbox value="all" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Show active only</FormControl.Label>
+      <Checkbox value="active" />
+    </FormControl>
+  </Stack>
+</CheckboxGroup>
+```
+
+### Inline
+
+When space is limited, checkboxes can be arranged horizontally using the [Stack](../../layout/Stack/index.md) component.
+
+```jsx
+<CheckboxGroup>
+  <CheckboxGroup.Label visuallyHidden>Filter options</CheckboxGroup.Label>
+  <CheckboxGroup.Caption>Some inline checkboxes with a visually hidden label</CheckboxGroup.Caption>
+  <Stack direction="horizontal" gap="normal" padding="none" flexWrap="wrap">
+    <FormControl>
+      <FormControl.Label>Choice one</FormControl.Label>
+      <Checkbox value="one" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Choice two</FormControl.Label>
+      <Checkbox value="two" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Choice three</FormControl.Label>
+      <Checkbox value="three" />
+    </FormControl>
+  </Stack>
+</CheckboxGroup>
+```
+
+## Component props
+
+### CheckboxGroup `Required`
+
+| Name       | Type                   | Default | Description                                                      |
+| :--------- | :--------------------- | :-----: | :--------------------------------------------------------------- |
+| `children` | `React.ReactElement[]` |         | CheckboxGroup components and FormControl components              |
+| `id`       | `string`               |         | Sets a custom id. If not provided, a unique id will be generated |
+
+`CheckboxGroup` extends the HTML `fieldset` element and supports all `fieldset` props.
+
+### CheckboxGroup.Label `Required`
+
+| Name             | Type      | Default | Description                             |
+| :--------------- | :-------- | :-----: | :-------------------------------------- |
+| `children`       | `string`  |         | Label text                              |
+| `visuallyHidden` | `boolean` | `false` | Hide label visually but keep accessible |
+
+`CheckboxGroup.Label` extends the HTML `legend` element and supports all `legend` props.
+
+### CheckboxGroup.Caption
+
+| Name       | Type     | Default | Description  |
+| :--------- | :------- | :-----: | :----------- |
+| `children` | `string` |         | Caption text |
+
+`CheckboxGroup.Caption` extends the `span` element and supports all `span` props.
+
+### CheckboxGroup.Validation
+
+| Name       | Type                   | Default | Description                        |
+| :--------- | :--------------------- | :-----: | :--------------------------------- |
+| `children` | `string`               |         | Validation message                 |
+| `variant`  | `'error' \| 'success'` |         | Sets the validation state and icon |
+
+`CheckboxGroup.Validation` extends the `span` element and supports all `span` props.