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

package/docs/forms/RadioGroup/react.md

@@ -0,0 +1,151 @@
+---
+title: Radio group
+description: Radio group is used to render a short list of mutually exclusive options.
+keywords: ['radio button', 'selection', 'input', 'form', 'option', 'single choice']
+source: https://github.com/primer/brand/blob/main/packages/react/src/forms/RadioGroup/RadioGroup.tsx
+figma: 'https://www.figma.com/design/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=10467-3461&t=GA5GtEqPtQ9yeRaN-4'
+storybook: '/brand/storybook/?path=/story/components-forms-radiogroup--playground'
+---
+
+```js
+import {RadioGroup} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+`RadioGroup` creates a semantic container for multiple related radio inputs. Note that all radio inputs must share the same `name` prop to function as a group.
+
+```jsx
+<RadioGroup>
+  <RadioGroup.Label>Choose your primary workspace</RadioGroup.Label>
+  <FormControl>
+    <FormControl.Label>Codespaces</FormControl.Label>
+    <Radio name="workspace" value="codespaces" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Local environment</FormControl.Label>
+    <Radio name="workspace" value="local" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Pen and paper</FormControl.Label>
+    <Radio name="workspace" value="remote" />
+  </FormControl>
+</RadioGroup>
+```
+
+### With caption
+
+Use `RadioGroup.Caption` to provide additional context for the group.
+
+```jsx
+<RadioGroup>
+  <RadioGroup.Label>Repository visibility</RadioGroup.Label>
+  <RadioGroup.Caption>Choose who can see and access your repository</RadioGroup.Caption>
+  <FormControl>
+    <FormControl.Label>Public</FormControl.Label>
+    <Radio name="visibility" value="public" />
+  </FormControl>
+  <FormControl>
+    <FormControl.Label>Private</FormControl.Label>
+    <Radio name="visibility" value="private" />
+  </FormControl>
+</RadioGroup>
+```
+
+### With validation
+
+`RadioGroup.Validation` can display success or error states with appropriate icons.
+
+```jsx
+<Stack direction="vertical" gap="spacious">
+  <RadioGroup>
+    <RadioGroup.Label>Valid selection</RadioGroup.Label>
+    <FormControl>
+      <FormControl.Label>Basic plan</FormControl.Label>
+      <Radio name="plan-valid" value="basic" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Pro plan</FormControl.Label>
+      <Radio name="plan-valid" value="pro" defaultChecked />
+    </FormControl>
+    <RadioGroup.Validation variant="success">Great choice!</RadioGroup.Validation>
+  </RadioGroup>
+
+  <RadioGroup>
+    <RadioGroup.Label>Invalid selection</RadioGroup.Label>
+    <FormControl>
+      <FormControl.Label>Basic plan</FormControl.Label>
+      <Radio name="plan-invalid" value="basic" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Pro plan</FormControl.Label>
+      <Radio name="plan-invalid" value="pro" />
+    </FormControl>
+    <RadioGroup.Validation variant="error">Please select a plan to continue</RadioGroup.Validation>
+  </RadioGroup>
+</Stack>
+```
+
+### Inline
+
+When space is limited, radio inputs can be arranged horizontally using the [Stack](../../layout/Stack/index.md) component.
+
+```jsx
+<RadioGroup>
+  <RadioGroup.Label visuallyHidden>Time period</RadioGroup.Label>
+  <RadioGroup.Caption>Some inline radio inputs with a visually hidden label</RadioGroup.Caption>
+  <Stack direction="horizontal" gap="normal" padding="none" flexWrap="wrap">
+    <FormControl>
+      <FormControl.Label>Last 7 days</FormControl.Label>
+      <Radio name="period" value="week" />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Last 30 days</FormControl.Label>
+      <Radio name="period" value="month" defaultChecked />
+    </FormControl>
+    <FormControl>
+      <FormControl.Label>Last year</FormControl.Label>
+      <Radio name="period" value="year" />
+    </FormControl>
+  </Stack>
+</RadioGroup>
+```
+
+## Component props
+
+### RadioGroup `Required`
+
+| Name       | Type                   | Default | Description                                                      |
+| :--------- | :--------------------- | :-----: | :--------------------------------------------------------------- |
+| `children` | `React.ReactElement[]` |         | RadioGroup components and FormControl components                 |
+| `id`       | `string`               |         | Sets a custom id. If not provided, a unique id will be generated |
+
+`RadioGroup` extends the HTML `fieldset` element and supports all `fieldset` props.
+
+### RadioGroup.Label `Required`
+
+| Name             | Type      | Default | Description                             |
+| :--------------- | :-------- | :-----: | :-------------------------------------- |
+| `children`       | `string`  |         | Label text                              |
+| `visuallyHidden` | `boolean` | `false` | Hide label visually but keep accessible |
+
+`RadioGroup.Label` extends the HTML `legend` element and supports all `legend` props.
+
+### RadioGroup.Caption
+
+| Name       | Type     | Default | Description  |
+| :--------- | :------- | :-----: | :----------- |
+| `children` | `string` |         | Caption text |
+
+`RadioGroup.Caption` extends the `span` element and supports all `span` props.
+
+### RadioGroup.Validation
+
+| Name       | Type                   | Default | Description                        |
+| :--------- | :--------------------- | :-----: | :--------------------------------- |
+| `children` | `string`               |         | Validation message                 |
+| `variant`  | `'error' \| 'success'` |         | Sets the validation state and icon |
+
+`RadioGroup.Validation` extends the `span` element and supports all `span` props.

package/docs/forms/Select/index.md

@@ -0,0 +1,244 @@
+---
+title: Select
+description: Use the select component to enable selection of one option from a list.
+keywords: ['dropdown', 'list', 'menu', 'input', 'form']
+figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1793%3A28117'
+source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Select/Select.tsx
+storybook: '/brand/storybook/?path=/story/components-forms-select--playground'
+---
+
+```js
+import {Select} from '@primer/react-brand'
+```
+
+## Examples
+
+### Default
+
+```jsx
+<Select aria-label="Select a handle">
+  <Select.Option value="mona">Monalisa</Select.Option>
+  <Select.Option value="hubot">Hubot</Select.Option>
+</Select>
+```
+
+### Placeholder
+
+```jsx
+<Select defaultValue="" aria-label="Select a handle">
+  <Select.Option value="" disabled>
+    Select a handle
+  </Select.Option>
+  <Select.Option value="mona">Monalisa</Select.Option>
+  <Select.Option value="hubot">Hubot</Select.Option>
+</Select>
+```
+
+### Option groups
+
+```jsx
+<Select defaultValue="" aria-label="Select a country">
+  <Select.Option value="" disabled>
+    Select a country
+  </Select.Option>
+
+  <Select.OptGroup label="Asia">
+    <Select.Option value="cn">China</Select.Option>
+  </Select.OptGroup>
+  <Select.OptGroup label="Europe">
+    <Select.Option value="fr">France</Select.Option>
+    <Select.Option value="it">Italy</Select.Option>
+    <Select.Option value="es">Spain</Select.Option>
+    <Select.Option value="uk">United Kingdom</Select.Option>
+  </Select.OptGroup>
+  <Select.OptGroup label="Americas">
+    <Select.Option value="mx">Mexico</Select.Option>
+    <Select.Option value="us">United States</Select.Option>
+  </Select.OptGroup>
+</Select>
+```
+
+### Use with `FormControl`
+
+Use `Select` alongside `FormControl` to ensure the control has a corresponding form label.
+
+[See FormControl for additional usage examples.](../FormControl/index.md)
+
+```jsx
+<FormControl>
+  <FormControl.Label>Country</FormControl.Label>
+  <Select defaultValue="">
+    <Select.Option value="" disabled>
+      Select a country
+    </Select.Option>
+    <Select.Option value="cn">China</Select.Option>
+    <Select.Option value="fr">France</Select.Option>
+    <Select.Option value="it">Italy</Select.Option>
+    <Select.Option value="mx">Mexico</Select.Option>
+    <Select.Option value="es">Spain</Select.Option>
+    <Select.Option value="uk">United Kingdom</Select.Option>
+    <Select.Option value="us">United States</Select.Option>
+  </Select>
+</FormControl>
+```
+
+### Validation
+
+```jsx
+<div style={{display: 'inline-grid', gap: 3}}>
+  <FormControl validationStatus="error">
+    <FormControl.Label>Error</FormControl.Label>
+    <Select>
+      <Select.Option value="mona">Monalisa</Select.Option>
+      <Select.Option value="hubot">Hubot</Select.Option>
+    </Select>
+    <FormControl.Validation>This is an error message</FormControl.Validation>
+  </FormControl>
+  <FormControl validationStatus="success">
+    <FormControl.Label>Success</FormControl.Label>
+    <Select>
+      <Select.Option value="mona">Monalisa</Select.Option>
+      <Select.Option value="hubot">Hubot</Select.Option>
+    </Select>
+    <FormControl.Validation>This is a success message</FormControl.Validation>
+  </FormControl>
+</div>
+```
+
+### Full width
+
+```jsx
+<Select fullWidth aria-label="Select a handle">
+  <Select.Option value="mona">Monalisa</Select.Option>
+  <Select.Option value="hubot">Hubot</Select.Option>
+</Select>
+```
+
+### Sizes
+
+`FormControl` can appear in `medium` and `large` dimensions using the `size` prop.
+
+```jsx
+<div style={{display: 'inline-grid', gap: 3}}>
+  <FormControl size="medium">
+    <FormControl.Label>Medium</FormControl.Label>
+    <Select>
+      <Select.Option value="mona">Monalisa</Select.Option>
+      <Select.Option value="hubot">Hubot</Select.Option>
+    </Select>
+  </FormControl>
+
+  <FormControl size="large">
+    <FormControl.Label>Large</FormControl.Label>
+    <Select>
+      <Select.Option value="mona">Monalisa</Select.Option>
+      <Select.Option value="hubot">Hubot</Select.Option>
+    </Select>
+  </FormControl>
+</div>
+```
+
+### Required
+
+Pass the `required` prop to ensure that the input field must be filled out before submitting the form.
+
+```jsx
+<Select required defaultValue="" aria-label="Select a handle">
+  <Select.Option value="" disabled>
+    Select a handle
+  </Select.Option>
+  <Select.Option value="mona">Monalisa</Select.Option>
+  <Select.Option value="hubot">Hubot</Select.Option>
+</Select>
+```
+
+### Using `refs`
+
+`Select` inputs can be used in [uncontrolled mode](https://reactjs.org/docs/uncontrolled-components.html) by forwarding a `ref` to the underlying element.
+
+```jsx filename="noinline"
+const App = () => {
+  const selectRef = React.useRef(null)
+
+  const handleSubmit = e => {
+    e.preventDefault()
+    if (!selectRef.current.value) {
+      alert(`Select a handle to continue`)
+      return
+    }
+
+    alert(`Name: ${selectRef.current.value}`)
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <div
+        style={{
+          display: 'grid',
+          gap: 'var(--base-size-16)',
+          maxWidth: 400,
+          marginX: 'auto',
+        }}
+      >
+        <FormControl fullWidth>
+          <FormControl.Label>Name</FormControl.Label>
+          <Select ref={selectRef} defaultValue="">
+            <Select.Option value="" disabled>
+              Select a handle
+            </Select.Option>
+            <Select.Option value="mona">Monalisa</Select.Option>
+            <Select.Option value="hubot">Hubot</Select.Option>
+          </Select>
+        </FormControl>
+        <Button type="submit" variant="primary">
+          Submit
+        </Button>
+      </div>
+    </form>
+  )
+}
+
+render(App)
+```
+
+## Component props
+
+`Select` provides a React-based alternative to the native HTML `<select>`, `<option>` and `<optgroup>` elements.
+
+The component API supports all standard HTML attribute props, while providing some additional behaviour as described below.
+
+### Select `Required`
+
+| Name               | Type                                   | Default | Description                                                       |
+| :----------------- | :------------------------------------- | :-----: | :---------------------------------------------------------------- |
+| `children`         | `'Select.Option' \| 'Select.OptGroup'` |         | Valid child nodes                                                 |
+| `className`        | `string`                               |         | Sets a custom class                                               |
+| `id`               | `string`                               |         | Sets a custom id                                                  |
+| `fullWidth`        | `boolean`                              |         | Stretches elements visually to the edges of its parent container. |
+| `ref`              | `React.RefObject`                      |         | Forward a Ref to the underlying DOM node                          |
+| `size`             | `'medium' \| 'large'`                  |         | Visual dimensions for the input                                   |
+| `validationStatus` | `'error' \| 'success'`                 |         | Applies visual and semantic state to the underlying elements      |
+
+Additional props can be passed to the `<select>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) accepted by the `<select>` element.
+
+### Select.Option `Required`
+
+| Name    | Type     | Default | Description                                       |
+| :------ | :------- | :-----: | :------------------------------------------------ |
+| `value` | `string` |         | The value to be supplied during form subsmission. |
+
+Additional props can be passed to the `<option>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/option) accepted by the `<option>` element.
+
+### Select.OptGroup
+
+| Name    | Type     | Default | Description                       |
+| :------ | :------- | :-----: | :-------------------------------- |
+| `label` | `string` |         | The name of the group of options. |
+
+Additional props can be passed to the `<optgroup>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/optgroup) accepted by the `<optgroup>` element.
+
+## Related components
+
+- [Checkbox](../Checkbox/index.md)
+- [FormControl](../FormControl/index.md)
+- [TextInput](../TextInput/index.md)

package/docs/forms/TextArea/index.md

@@ -0,0 +1,126 @@
+---
+title: Textarea
+description: Use the textarea component for multi-line text input form fields.
+keywords: ['input', 'form']
+source: https://github.com/primer/brand/blob/main/packages/react/src/forms/Textarea/Textarea.tsx
+storybook: '/brand/storybook/?path=/story/components-forms-textarea--default'
+---
+
+```js
+import {Textarea} from '@primer/react-brand'
+```
+
+## Examples
+
+> Textarea components **must always** be accompanied by a corresponding label to improve support for assistive
+> technologies. Examples below are provided for conciseness and may not reflect accessibility best practices.
+>
+> Use the [FormControl](../FormControl/index.md) component to render a Textarea with a corresponding label.
+
+### Controlled mode
+
+```jsx filename="noinline"
+const TextareaExample = () => {
+  // Running in controlled mode (recommended)
+  const [value, setValue] = React.useState('This value was initially set through state.')
+
+  const handleChange = event => {
+    setValue(event.target.value)
+  }
+
+  return <Textarea aria-label="Description" placeholder="Enter a description" onChange={handleChange} value={value} />
+}
+
+render(<TextareaExample />)
+```
+
+### Uncontrolled mode
+
+```jsx filename="noinline"
+const TextareaExample = () => {
+  const ref = React.useRef()
+
+  const handleSubmit = event => {
+    event.preventDefault()
+    if (!ref.current.value) {
+      alert(`Enter a value into the Textarea and press submit`)
+      return
+    }
+
+    alert(`Current Textarea value: ${ref.current.value}`)
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <Textarea
+        cols={40}
+        rows={8}
+        ref={ref}
+        defaultValue="Set the initial state in uncontrolled mode using the defaultValue prop"
+        aria-label="Demo Textarea"
+      />
+      <br /> <br />
+      <Button variant="primary" type="submit">
+        Submit
+      </Button>
+    </form>
+  )
+}
+
+render(<TextareaExample />)
+```
+
+### Displaying form validation state
+
+```jsx
+<Stack direction={{narrow: 'vertical', wide: 'horizontal'}}>
+  <Stack direction="vertical">
+    <FormControl validationStatus="success">
+      <FormControl.Label>Success state</FormControl.Label>
+      <Textarea />
+      <FormControl.Validation>This is a success message</FormControl.Validation>
+    </FormControl>
+  </Stack>
+  <Stack direction="vertical">
+    <FormControl validationStatus="error">
+      <FormControl.Label>Error state</FormControl.Label>
+      <Textarea />
+      <FormControl.Validation>This is an error message</FormControl.Validation>
+    </FormControl>
+  </Stack>
+</Stack>
+```
+
+### Inactive
+
+```jsx
+<Textarea disabled aria-label="Demo Textarea">
+  This text is inactive
+</Textarea>
+```
+
+### Resize
+
+By default, `Textarea` can be resized by the user vertically and horizontally. Resizing can be prevented by setting `resize` to `none`
+
+```jsx
+<Textarea resize="none" aria-label="Resizable Textarea" />
+```
+
+## Props
+
+### Textarea
+
+| Name               | Type                                             |  Default | Description                                                                        |
+| :----------------- | :----------------------------------------------- | :------: | :--------------------------------------------------------------------------------- |
+| `className`        | `string`                                         |          | Sets a custom class                                                                |
+| `cols`             | `number`                                         |   `30`   | Specifies the visible width of a textarea.                                         |
+| `id`               | `string`                                         |          | Sets a custom id                                                                   |
+| `ref`              | `React.RefObject`                                |          | Forward a Ref to the underlying DOM node                                           |
+| `required`         | `boolean`                                        |          | Indicates to the user and assistive technologies that the field value is required. |
+| `resize`           | `'both' \| 'horizontal' \| 'vertical' \| 'none'` | `'both'` | Sets whether an element is resizable, and if so, in which directions.              |
+| `rows`             | `number`                                         |    `7`   | Specifies the visible height of a text area.                                       |
+| `size`             | `'medium' \| 'large'`                            |          | Provides alternate visual presentation.                                            |
+| `validationStatus` | `'error' \| 'success'`                           |          | Applies visual and semantic state to the underlying elements                       |
+
+Additional props can be passed to the `<textarea>` element. [See MDN for a list of props](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea) accepted by the `<textarea>` element.